From e3da9d70ad7b1e7e42d3e87608ab1ed086619754 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau <fare@tunes.org> Date: Sat, 1 May 2010 14:14:24 -0400 Subject: [PATCH] Doc update about ASDF 2 vs ASDF 1. --- doc/asdf.texinfo | 110 +++++++++++++++++++++++++++++++++++++++-------- doc/index.html | 8 ++-- 2 files changed, 95 insertions(+), 23 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 390384a0..1f3433a5 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -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: diff --git a/doc/index.html b/doc/index.html index d8d14a96..7dcf172b 100644 --- a/doc/index.html +++ b/doc/index.html @@ -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çois-René 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> -- GitLab