Commit e3da9d70 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

Doc update about ASDF 2 vs ASDF 1.

parent 89b15db3
......@@ -170,12 +170,12 @@ to learn how to define a system of your own.
the ASDF internals and how to extend ASDF.
@emph{Nota Bene}:
We are preparing for a release of ASDF 2,
We are preparing for a release of ASDF 2, hopefully for May 2010,
which will have version 2.000 and later.
Current releases, in the 1.700 series and beyond,
should be considered as release candidates.
We're still working on polishing the code and documentation.
@ref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
@xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
@node Loading ASDF, Configuring ASDF, Introduction, Top
......@@ -241,7 +241,7 @@ If it returns the keyword @code{:OLD},
then you're using an old version of ASDF (from before 1.635).
If it returns @code{NIL} then ASDF is not installed.
If you are running a version older than 1.703,
If you are running a version older than 1.711,
we recommend that you load a newer ASDF using the method below.
......@@ -1319,11 +1319,11 @@ Don't hold your breath.
@code{defsystem} grammar subsection,
which doesn't provide any obvious way to specify required features.
Furthermore, in 2009, discussions on the
@uref{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
suggested that the specification of required features may be broken,
and that no one may have been using them for a while.
Please contact the
@uref{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
if you are interested in getting this features feature fixed.}
Traditionally defsystem users have used reader conditionals
......@@ -1674,7 +1674,7 @@ where data files are located,
where output file caches are located.
Mentions of XDG variables refer to that document.
@uref{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}
@url{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}
This specification allows the user to specify some environment variables
to customize how applications behave to his preferences.
......@@ -2475,7 +2475,7 @@ You can also browse the repository on
Discussion of ASDF development is conducted on the
mailing list
@kbd{asdf-devel@@common-lisp.net}.
@uref{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel}
@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel}
@node FAQ, TODO list, Getting the latest version, Top
......@@ -2487,7 +2487,7 @@ mailing list
ASDF bugs are tracked on launchpad: @url{https://launchpad.net/asdf}.
If you're unsure about whether something is a bug, of for general discussion,
use the @uref{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
use the @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
@section ``What has changed between ASDF 1 and ASDF 2?''
......@@ -2520,8 +2520,10 @@ we recommend that you should upgrade to ASDF 2 or its latest release candidate.
Common Lisp namestrings are not portable,
except maybe for logical pathnamestrings,
that themselves require a lot of setup that is itself ultimately non-portable.
The only portable ways to refer to pathnames inside systems and components
that themselves have various limitations and require a lot of setup
that is itself ultimately non-portable.
In ASDF 1, the only portable ways to refer to pathnames inside systems and components
were very awkward, using @code{#.(make-pathname ...)} and
@code{#.(merge-pathnames ...)}.
Even the above were themselves were inadequate in the general case
......@@ -2537,6 +2539,7 @@ Naming files within a system definition becomes easy and portable again.
@xref{The defsystem grammar,,Pathname specifiers}.
@subsection Output translations
A popular feature added to ASDF was output pathname translation:
......@@ -2581,6 +2584,7 @@ and also allows for new magic, simpler and more powerful magic.
@xref{Controlling where ASDF searches for systems}.
@subsection Usual operations are made easier to the user
In ASDF 1, you had to use the awkward syntax
......@@ -2595,9 +2599,10 @@ similarly for @code{compile-system}, @code{test-system}.
@subsection Many bugs have been fixed
These issues and many others have been fixed,
including the following:
The following issues and many others have been fixed:
@itemize
@item
The infamous TRAVERSE function has been revamped significantly,
with many bugs squashed.
In particular, dependencies were not correctly propagated
......@@ -2605,17 +2610,32 @@ across submodules within a system but now are.
The :version and :feature features and
the :force (system1 .. systemN) feature have been fixed.
@item
Performance has been notably improved for very large systems
(say with thousands of components) by using
hash-tables instead of linear search,
and linear-time list accumulation
instead of quadratic-time recursive appends.
@item
Many features used to not be portable,
especially where pathnames were involved.
Windows support was notably quirky because of such non-portability.
The internal test suite used to massively fail
on many implementations.
@item
The internal test suite used to massively fail on many implementations.
While still incomplete, it now fully passes
on all implementations supported by the test suite.
Support was broken for some implementations (notably ABCL).
@item
Support was lacking for some implementations.
ABCL was notably wholly broken.
ECL extensions were not integrated in the ASDF release.
@item
The documentation was grossly out of date.
ECL extensions were not integrated in the ASDF release.
@end itemize
@subsection ASDF itself is versioned
......@@ -2630,9 +2650,10 @@ or take great pains to have the correct version of ASDF installed.
With ASDF 2, we provide a new stable set of working features
that everyone can rely on from now on.
Use @code{#+asdf2} to detect presence of ASDF 2,
@code{(asdf:version-satisfies (asdf:asdf-version) "1.703")}
@code{(asdf:version-satisfies (asdf:asdf-version) "1.711")}
to check the availability of a version no earlier than required.
@subsection ASDF can be upgraded
When an old version of ASDF was loaded,
......@@ -2674,6 +2695,57 @@ This means that release cycles will be causally decoupled,
the practical consequence of which will mean faster convergence
towards the latest version for everyone.
@subsection Pitfalls of ASDF 2
The main pitfalls in upgrading to ASDF 2 seem to be related
to the output translation mechanism.
@itemize
@item
Output translations is enabled by default. This may surprise some users,
most of them in pleasant way (we hope), a few of them in an unpleasant way.
It is trivial to disable output translations.
@xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
@item
Some systems in the large have been known not to play well with output translations.
They were relatively easy to fix.
Once again, it is also easy to disable output translations,
or to override its configuration.
@item
The new ASDF output translations are incompatible with ASDF-Binary-Locations.
They replace A-B-L, and there is compatibility mode to emulate
your previous A-B-L configuration.
See @code{asdf:enable-asdf-binary-locations-compatibility} in
@pxref{Controlling where ASDF saves compiled files,,Backward Compatibility}.
But thou shall not load ABL on top of ASDF 2.
@end itemize
Other issues include the following:
@itemize
@item
There is a slight performance bug, notably on SBCL,
when initially searching for @file{asd} files
(depending on your configuration).
The @code{(directory "**/*.asd")} can make things slower than desired.
Try to @code{(time (asdf:initialize-source-registry))}
to see how bad it is or isn't on your system.
@item
On Windows, only LispWorks supports proper default configuration pathnames
based on the Windows registry.
Other implementations make do.
Windows support is largely untested, so please help report and fix bugs.
@end itemize
@section Issues with installing the proper version of ASDF
@subsection ``My Common Lisp implementation comes with an outdated version of ASDF. What to do?''
......@@ -2779,9 +2851,9 @@ ASDF provides a predefined test operation, @code{test-op}.
The test operation, however, is largely left to the system definer to specify.
@code{test-op} has been
a topic of considerable discussion on the
@uref{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list},
@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list},
and on the
@uref{https://launchpad.net/asdf,launchpad bug-tracker}.
@url{https://launchpad.net/asdf,launchpad bug-tracker}.
Here are some guidelines:
......
......@@ -31,7 +31,7 @@
<p>ASDF is a tool for describing how source files are organized:
what depends on which and when.
</p>
<p>It is roughly what Common-Lisp hackers use to build software
<p>It is roughly what Common Lisp hackers use to build software
where C hackers would use say GNU Make.
</p>
<p>ASDF stands for <em>A</em>nother <em>S</em>ystem <em>D</em>efinition <em>F</em>acility,
......@@ -90,7 +90,7 @@
<a id="news"></a>
<h3>What is happening</h3>
<dl>
<dt>December 2009 to April 2010</dt>
<dt>December 2009 to May 2010</dt>
<dd>Fran&ccedil;ois-Ren&eacute; Rideau is de facto maintainer,
with notable contributions from Robert P. Goldman,
Juanjo Garcia-Ripoll and James Anderson.
......@@ -101,9 +101,9 @@
<dt>May 2006 to November 2009</dt>
<dd>Gary King is de facto maintainer,
with notable contributions from
Robert P. Goldman, Nikodemus Siivola, Christophe Rhodes, D Herring.
Robert P. Goldman, Nikodemus Siivola, Christophe Rhodes, Daniel Herring.
Many small features and bug fixes,
trying to make the project more usable,
making the project more maintanable,
moving to using git and common-lisp.net.
</dd>
<dt>May 2004 to April 2006</dt>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment