From 6768551dc1ddff770b89ed18bd89d81989f92e59 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau <tunes@google.com> Date: Sun, 23 Feb 2014 23:34:01 -0500 Subject: [PATCH] Some tweaks to the documentation. --- doc/asdf.texinfo | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 96789b00..59c89053 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -184,6 +184,10 @@ For this reason, we have stopped supporting ASDF 1 and ASDF 2. If you are using ASDF 1 or ASDF 2 and are experiencing any kind of issues or limitations, we recommend you upgrade to ASDF 3 --- and we explain how to do that. @xref{Loading ASDF}. +(In the context of compatibility requirements, +ASDF 2.27, released on Feb 1st 2013, and further 2.x releases up to 2.33, +count as pre-releases of ASDF 3, and define the :asdf3 feature; +still, please use the latest release). Also note that ASDF is not to be confused with ASDF-Install. ASDF-Install is not part of ASDF, but a separate piece of software. @@ -214,7 +218,8 @@ so you may more easily modify it, we recommend clbuild. @section Loading a pre-installed ASDF -Most recent Lisp implementations include a copy of ASDF 2, and soon ASDF 3. +Most recent Lisp implementations include a copy of ASDF 3, +or at least ASDF 2. You can usually load this copy using Common Lisp's @code{require} function: @lisp @@ -222,8 +227,10 @@ You can usually load this copy using Common Lisp's @code{require} function: @end lisp As of the writing of this manual, -the following implementations provide ASDF 2 this way: -abcl allegro ccl clisp cmucl ecl lispworks mkcl sbcl xcl. +the following implementations provide ASDF 3 this way: +abcl allegro ccl clisp cmucl ecl mkcl sbcl. +The following implementation only provide ASDF 2: +lispworks mkcl mocl xcl. The following implementation doesn't provide it yet but will in an upcoming release: scl. The following implementations are obsolete, not actively maintained, @@ -335,15 +342,18 @@ see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below. Note that there are some limitations to upgrading ASDF: @itemize @item -Previously loaded ASDF extension becomes invalid, and will need to be reloaded. +Previously loaded ASDF extensions become invalid, and will need to be reloaded. This applies to e.g. CFFI-Grovel, or to hacks used by ironclad, etc. Since it isn't possible to automatically detect what extensions are present that need to be invalidated, ASDF will actually invalidate all previously loaded systems -when it is loaded on top of a different ASDF version, -starting with ASDF 2.014.8 (as far as releases go, 2.015); -and it will automatically attempt this self-upgrade as its very first step -starting with ASDF 3. +when it is loaded on top of a forward-incompatible ASDF version +(as per @code{asdf/upgrade::*oldest-forward-compatible-asdf-version*} +which is 2.33 at the time of this writing). +Furthermore, starting with ASDF 3 (2.27 or later), +this self-upgrade will be automatically attempted as the first step +to any system operation, to avoid any possibility of +a catastrophic attempt to self-upgrade in midflight. @item For this an many other reasons, @@ -1361,7 +1371,7 @@ Please use the @code{if-feature} option instead. @subsection feature requirement This requirement was removed in ASDF 3.1. -It used to ensure a chain of component dependencies will raise an error, +It used to ensure that a chain of component dependencies will raise an error, which in conjunction with if-component-dep-fails would offer a roundabout way to express conditional compilation. @@ -2102,14 +2112,15 @@ lines like: @lisp #+sbcl (:file "cffi-sbcl") @end lisp -An unfortunate side effect of this approach is tnoat no single +An unfortunate side effect of this approach is that no single implementation can read the entire system. This causes problems if, for example, one wished to design an @code{archive-op} -that would create an archive file containing all the sources, since +that would create an archive file containing all the sources, since for example the file @code{cffi-sbcl.lisp} above would be invisible when running the @code{archive-op} on any implementation other than SBCL. -ASDF components may therefore have an @code{:if-feature} option. +Starting with ASDF 3, +components may therefore have an @code{:if-feature} option. The value of this option should be a feature expression using the same syntax as @code{#+} does. If that feature expression evaluates to false, any reference to the component will be ignored @@ -2932,7 +2943,7 @@ But so are good design ideas and elegant implementation tricks. @node Controlling where ASDF saves compiled files, Error handling, Controlling where ASDF searches for systems, Top @comment node-name, next, previous, up @chapter Controlling where ASDF saves compiled files -@cindex asdf-output-translations +@cindex asdf-output-translations @vindex ASDF_OUTPUT_TRANSLATIONS Each Common Lisp implementation has its own format -- GitLab