Changeset 14713

Timestamp:

05/17/14 10:51:33 (9 years ago)

Author:

Mark Evenson

Message:

Update to ASDF 3.1.2.2 version.

Location:

trunk/abcl

Files:

• doc/asdf/asdf.texinfo (modified) (144 diffs)
• src/org/armedbear/lisp/asdf.lisp (modified) (36 diffs)

trunk/abcl/doc/asdf/asdf.texinfo

@@ -105 +105 @@
 * Function and Class Index::
 * Variable Index::              @c @detailmenu
-@c 
+@c
 
 @detailmenu
@@ -115 +115 @@
 * Checking whether ASDF is loaded::
 * Upgrading ASDF::
-* Loading an otherwise installed ASDF::
+* Loading ASDF from source::
+
+Upgrading ASDF
+
+* Upgrading your implementation's ASDF::
+* Issues with upgrading ASDF::
 
 Configuring ASDF
 
 * Configuring ASDF to find your systems::
+* Configuring ASDF to find your systems --- old style::
 * Configuring where ASDF stores object files::
+* Resetting the ASDF configuration::
+
+Using ASDF
+
+* Loading a system::
+* Other Operations::
+* Moving on::
 
 Defining systems with defsystem
@@ -128 +141 @@
 * The defsystem grammar::
 * Other code in .asd files::
-* The package-system extension::
-
-The object model of ASDF
+* The package-inferred-system extension::
+
+The Object model of ASDF
 
 * Operations::
 * Components::
+* Dependencies::
 * Functions::
 
@@ -151 +165 @@
 * Pre-defined subclasses of component::
 * Creating new component types::
+
+Controlling where ASDF searches for systems
+
+* Configurations::
+* Truenames and other dangers::
+* XDG base directory::
+* Backward Compatibility::
+* Configuration DSL::
+* Configuration Directories::
+* Shell-friendly syntax for configuration::
+* Search Algorithm::
+* Caching Results::
+* Configuration API::
+* Introspection::
+* Status::
+* Rejected ideas::
+* TODO::
+* Credits for the source-registry::
+
+Configuration Directories
+
+* The here directive::
+
+Introspection
+
+* *source-registry-parameter* variable::
+* Information about system dependencies::
+
+Controlling where ASDF saves compiled files
+
+* Output Configurations::
+* Output Backward Compatibility::
+* Output Configuration DSL::
+* Output Configuration Directories::
+* Output Shell-friendly syntax for configuration::
+* Semantics of Output Translations::
+* Output Caching Results::
+* Output location API::
+* Credits for output translations::
+
+Miscellaneous additional functionality
+
+* Controlling file compilation::
+* Controlling source file character encoding::
+* Some Utility Functions::
 
 FAQ
@@ -161 +220 @@
 * ASDF development FAQs::
 
-``What has changed between ASDF 1 and ASDF 2?''
+``What has changed between ASDF 1, ASDF 2 and ASDF 3?''
 
 * What are ASDF 1 2 3?::
+* How do I detect the ASDF version?::
 * ASDF can portably name files in subdirectories::
 * Output translations::
@@ -191 +251 @@
 * I want to put my module's files at the top level.  How do I do this?::
 * How do I create a system definition where all the source files have a .cl extension?::
+* How do I mark a source file to be loaded only and not compiled?::
+* How do I work with readtables?::
 
 ASDF development FAQs
@@ -216 +278 @@
 ASDF is Another System Definition Facility:
 a tool for specifying how systems of Common Lisp software
-are comprised of components (sub-systems and files),
+are made up of components (sub-systems and files),
 and how to operate on these components in the right order
 so that they can be compiled, loaded, tested, etc.
+If you are new to ASDF, @pxref{Quick start summary,,the quick start
+guide}.
 
 ASDF presents three faces:
 one for users of Common Lisp software who want to reuse other people's code,
 one for writers of Common Lisp software who want to specify how to build their systems,
-one for implementers of Common Lisp extensions who want to extend the build system.
-@xref{Using ASDF,,Loading a system},
+and one for implementers of Common Lisp extensions who want to extend
+the build system.
+For more specifics,
+@pxref{Using ASDF,,Loading a system},
 to learn how to use ASDF to load a system.
 @xref{Defining systems with defsystem},
@@ -231 +297 @@
 the ASDF internals and how to extend ASDF.
 
-@emph{Nota Bene}:
-We have released ASDF 2.000 on May 31st 2010,
-and ASDF 3.0.0 on May 15th 2013.
-Releases of ASDF 2 and later have since then been included
-in all actively maintained CL implementations that used to bundle ASDF 1,
-plus some implementations that didn't use to,
-and has been made to work with all actively used CL implementations and a few more.
-@xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
-Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly
-(though we recommend instead upgrading your implementation or its ASDF module).
-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 @code{:asdf3} feature;
-still, please use the latest release).
-Release ASDF 3.1.1 and later also define the @code{:asdf3.1} feature.
-
-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.
+Note that
+ASDF is @emph{not} a tool for library and system @emph{installation}; it
+plays a role like @t{make} or @t{ant}, not like a package manager.
+In particular, ASDF should not to be confused with ASDF-Install, which attempts to find and
+download ASDF systems for you.
+Despite the name, ASDF-Install is not part of ASDF, but a separate piece of software.
 ASDF-Install is also unmaintained and obsolete.
-We recommend you use Quicklisp instead,
-which works great and is being actively maintained.
+We recommend you use Quicklisp
+(@uref{http://www.quicklisp.org}) instead,
+a Common Lisp package manager which works well and is being actively maintained.
 If you want to download software from version control instead of tarballs,
-so you may more easily modify it, we recommend clbuild.
+so you may more easily modify it, we recommend clbuild (@uref{http://common-lisp.net/project/clbuild/}).
 We recommend @file{~/common-lisp/}
 as a place into which to install Common Lisp software;
-starting with ASDF 3.1.1, it is included in the default source-registry configuration.
+starting with ASDF 3.1.2, it is included in the default source-registry configuration.
 
 @node  Quick start summary, Loading ASDF, Introduction, Top
@@ -281 +332 @@
 For more details, @xref{Configuring ASDF to find your systems}.
 The simplest way is simply to put all your lisp code in subdirectories of
-@file{~/common-lisp/} (starting with ASDF 3.1.1),
+@file{~/common-lisp/} (starting with ASDF 3.1.2),
 or @file{~/.local/share/common-lisp/source/}
 (for ASDF 2 and later, or if you want to keep source in a hidden directory).
@@ -300 +351 @@
 Make a new directory for your system, @code{my-system/} in a location
 where ASDF can find it (@pxref{Configuring ASDF to find your systems}).
+All else being equal, the easiest location is probably
+@file{~/common-lisp/my-system/}.
+
 
 @item
@@ -330 +384 @@
 * Checking whether ASDF is loaded::
 * Upgrading ASDF::
-* Loading an otherwise installed ASDF::
+* Loading ASDF from source::
 @end menu
 
@@ -350 +404 @@
 As of the writing of this manual,
 the following implementations provide ASDF 3 this way:
-ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, mkcl, SBCL.
+ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL, SBCL.
 The following implementations only provide ASDF 2:
 LispWorks, mocl, XCL.
-The following implementation doesn't provide ASDF yet but will in an upcoming release:
-SCL.
-The following implementations are obsolete, not actively maintained,
-and most probably will never bundle ASDF:
-Corman CL, GCL, Genera, MCL.
+The following implementations don't provide ASDF:
+Corman CL, GCL, Genera, MCL, SCL.
+The latter implementations are not actively maintained;
+if some of them are ever released again, they probably will include ASDF 3.
 
 If the implementation you are using doesn't provide ASDF 2 or ASDF 3,
-see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
+see @pxref{Loading ASDF,,Loading ASDF from source} below.
 If that implementation is still actively maintained,
 you may also send a bug report to your Lisp vendor and complain
@@ -380 +433 @@
 If it raises an error,
 then either ASDF is not loaded, or
-you are using an old version of ASDF.
+you are using a very old version of ASDF,
+and need to install ASDF 3.
 
 You can check whether an old version is loaded
@@ -390 +444 @@
 @lisp
 (when (find-package :asdf)
-  (let ((ver (symbol-value (or (find-symbol (string :*asdf-version*) :asdf)
-                               (find-symbol (string :*asdf-revision*) :asdf)))))
+  (let ((ver (symbol-value
+                   (or (find-symbol (string :*asdf-version*) :asdf)
+                       (find-symbol (string :*asdf-revision*) :asdf)))))
     (etypecase ver
       (string ver)
       (cons (with-output-to-string (s)
-              (loop for (n . m) on ver do (princ n s) (when m (princ "." s)))))
+              (loop for (n . m) on ver
+                    do (princ n s)
+                       (when m (princ "." s)))))
       (null "1.0"))))
 @end lisp
@@ -409 +466 @@
 before you contact us and raise an issue.
 
-@node  Upgrading ASDF, Loading an otherwise installed ASDF, Checking whether ASDF is loaded, Loading ASDF
+@node  Upgrading ASDF, Loading ASDF from source, Checking whether ASDF is loaded, Loading ASDF
 @section Upgrading ASDF
 @c FIXME: tighten this up a bit -- there's a lot of stuff here that
@@ -424 +481 @@
 amongst the regularly configured systems, before it compiles anything else.
 
-@subsection Notes about ASDF 1 and ASDF 2
-
-Most implementations provide ASDF 3 in their latest release,
-and we recommend upgrading your implementation rather than using ASDF 1 or 2.
-A few implementations only provide ASDF 2,
-that can be overridden by installing a fasl (see below).
-A few implementations don't provide ASDF,
-but a fasl can be installed to provide it.
-GCL so far is still lacking a usable @code{require} interface.
-
-If your implementation has no suitable upgrade available (yet),
-or somehow upgrading is not an option,
-we assume you're an expert deliberately using a legacy implementation,
-and are proficient enough to install this fasl.
-Still, the ASDF source repository contains a script
-@file{bin/install-asdf-as-module} that can help you do that.
-It relies on @file{cl-launch} 4 for command-line invocation,
-which may depend on ASDF being checked out in @file{~/cl/asdf/}
-if your implementation doesn't even have an ASDF 2;
-but if you don't have @file{cl-launch},
+@menu
+* Upgrading your implementation's ASDF::
+* Issues with upgrading ASDF::
+@end menu
+
+@node Upgrading your implementation's ASDF, Issues with upgrading ASDF, Upgrading ASDF, Upgrading ASDF
+@subsection Upgrading your implementation's ASDF
+
+Most implementations provide a recent ASDF 3 in their latest release.
+If yours doesn't, we recommend upgrading your implementation.
+If the latest version of your implementation still doesn't provide ASDF,
+or provides an old version, we recommend installing a recent ASDF so your implementation provides it,
+as explained below.
+If all fails, we recommend you load ASDF from source
+@pxref{Loading ASDF,,Loading ASDF from source}.
+
+The ASDF source repository contains a script
+@file{bin/install-asdf-as-module} that can help you upgrade your implementation's ASDF.
+It works on
+Allegro CL, Clozure CL, CMU CL, ECL, GNU CLISP, LispWorks, MKCL, SBCL, SCL, XCL.
+That's all known implementations except ABCL, Corman CL, GCL, Genera, MCL, MOCL.
+Happily, ABCL is usually pretty up to date and shouldn't need that script.
+GCL would be supported, except that so far is still lacking usable support for @code{require}.
+Corman CL, Genera, MCL are obsolete anyway.
+MOCL is under development.
+On an old version of an implementation that does not provide ASDF,
+you may have to load ASDF 3 from source before you load that script.
+
+The script relies on @code{cl-launch} 4 for command-line invocation,
+which may depend on ASDF being checked out in @file{~/common-lisp/asdf/}
+(which we recommend anyway)
+if your implementation doesn't even have an ASDF 2.
+If you don't have @code{cl-launch},
 you can instead @code{(load "bin/install-asdf-as-module")}
-from your implementation's REPL.
+from your implementation's REPL after loading ASDF from source.
 
 Finally, if your implementation only provides ASDF 2,
@@ -460 +530 @@
 @end lisp
 
+@node Issues with upgrading ASDF,  , Upgrading your implementation's ASDF, Upgrading ASDF
 @subsection Issues with upgrading ASDF
 
@@ -516 +587 @@
 @end itemize
 
-@node Loading an otherwise installed ASDF,  , Upgrading ASDF, Loading ASDF
-@section Loading an otherwise installed ASDF
+@node Loading ASDF from source,  , Upgrading ASDF, Loading ASDF
+@section Loading ASDF from source
 
 If your implementation doesn't include ASDF,
@@ -574 +645 @@
 
 @item
-Put all of your systems in subdirectories of
+Put all of your systems in one of the standard locations, subdirectories
+of
+@itemize
+@item
 @file{~/common-lisp/} or
+@item
 @file{~/.local/share/common-lisp/source/}.
-If you install software there, you don't need further configuration.
-(NB: @file{~/common-lisp/} is only included in the default configuration
-starting with ASDF 3.1.1 or later)
+@end itemize
+If you install software there, you don't need further
+configuration.@footnote{@file{~/common-lisp/} is only included in
+the default configuration
+starting with ASDF 3.1.2 or later.}
 
 @item
@@ -642 +719 @@
 
 @node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Configuring ASDF
+@section Configuring ASDF to find your systems --- old style
+
 
 @c FIXME: this section should be moved elsewhere.  The novice user
 @c should not be burdened with it. [2014/02/27:rpg]
-@section Configuring ASDF to find your systems --- old style
+
 
 The old way to configure ASDF to find your systems is by
@@ -816 +895 @@
 
 @node Resetting the ASDF configuration,  , Configuring where ASDF stores object files, Configuring ASDF
+@section Resetting the ASDF configuration
+
 @c FIXME: this should probably be moved out of the "quickstart" part of
 @c the manual. [2014/02/27:rpg]
-@section Resetting the ASDF configuration
+
 
 When you dump and restore an image, or when you tweak your configuration,
@@ -825 +906 @@
 
 @defun clear-configuration
-   undoes any ASDF configuration,
+   Undoes any ASDF configuration
    regarding source-registry or output-translations.
 @end defun
@@ -842 +923 @@
 @chapter Using ASDF
 
+@menu
+* Loading a system::
+* Other Operations::
+* Moving on::
+@end menu
+
+@node Loading a system, Other Operations, Using ASDF, Using ASDF
 @section Loading a system
 
@@ -852 +940 @@
 
 On some implementations (namely recent versions of
-ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP,
-LispWorks, MKCL, SBCL and XCL),
+ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL),
 ASDF hooks into the @code{CL:REQUIRE} facility
 and you can just use:
@@ -865 +952 @@
 If your ASDF is too old to provide @code{asdf:load-system} though
 we recommend that you upgrade to ASDF 3.
-@xref{Loading ASDF,,Loading an otherwise installed ASDF}.
+@xref{Loading ASDF,,Loading ASDF from source}.
 
 Note the name of a system is specified as a string or a symbol.
@@ -881 +968 @@
 @c which is reported not to work on some implementations
 
-
+@node Other Operations, Moving on, Loading a system, Using ASDF
 @section Other Operations
 
+@findex load-system
+@findex compile-system
+@findex test-system
+@findex requrie-system
+
 ASDF provides three commands for the most common system operations:
-@code{load-system}, @code{compile-system} or @code{test-system}.
+@code{load-system}, @code{compile-system}, and @code{test-system}.
 It also provides @code{require-system}, a version of @code{load-system}
 that skips trying to update systems that are already loaded.
+
+@c FIXME: We seem to export @findex bundle-system also.
+
+@findex operate
+@findex oos
 
 Because ASDF is an extensible system
 for defining @emph{operations} on @emph{components},
 it also provides a generic function @code{operate}
-(which is usually abbreviated by @code{oos}).
+(which is usually abbreviated by @code{oos},
+which stands for operate-on-system).
 You'll use @code{oos} whenever you want to do something beyond
 compiling, loading and testing.
@@ -907 +1005 @@
 @c FIXME: the following is too complicated for here, especially since
 @c :force hasn't been defined yet.  Move it. [2014/02/27:rpg]
+
 @findex already-loaded-systems
-
+@findex require-system
+@findex load-system
+@vindex *load-system-operation*
 For advanced users, note that
 @code{require-system} calls @code{load-system}
@@ -914 +1015 @@
 @code{already-loaded-systems} returns a list of the names of loaded systems.
 @code{load-system} applies @code{operate} with the operation from
-@code{*load-system-operation*}, which by default is @code{load-op},
+@code{*load-system-operation*} (which by default is @code{load-op}),
 the system, and any provided keyword arguments.
 
 
+@node Moving on,  , Other Operations, Using ASDF
 @section Moving on
 
@@ -930 +1032 @@
 @chapter Defining systems with defsystem
 
-This chapter describes how to use asdf to define systems and develop
+This chapter describes how to use ASDF to define systems and develop
 software.
 
@@ -939 +1041 @@
 * The defsystem grammar::
 * Other code in .asd files::
-* The package-system extension::
+* The package-inferred-system extension::
 @end menu
 
@@ -945 +1047 @@
 @comment  node-name,  next,  previous,  up
 @section The defsystem form
-
-Systems can be constructed programmatically
-by instantiating components using @code{make-instance}.
-Most of the time, however, it is much more practical to use
-a static @code{defsystem} form.
+@findex defsystem
+@cindex asdf-user
+@findex load-asd
+
 This section begins with an example of a system definition,
 then gives the full grammar of @code{defsystem}.
 
 Let's look at a simple system.
-This is a complete file that would
-usually be saved as @file{hello-lisp.asd}:
+This is a complete file that should be saved as @file{hello-lisp.asd}
+(in order that ASDF can find it
+when ordered to operate on the system named @code{"hello-lisp"}).
+
+@c FIXME: the first example should have an outside dependency, e.g.,
+@c CL-PPCRE.
 
 @lisp
-(in-package :asdf)
+(in-package :asdf-user)
 
 (defsystem "hello-lisp"
   :description "hello-lisp: a sample Lisp system."
-  :version "0.2.1"
+  :version "0.0.1"
   :author "Joe User <joe@@example.com>"
   :licence "Public Domain"
@@ -976 +1081 @@
 @item
 The file starts with an @code{in-package} form
-to use package @code{asdf}.
-You could instead start your definition by using
-a qualified name @code{asdf:defsystem}.
-
-@item
-If in addition to simply using @code{defsystem},
-you are going to define functions,
-create ASDF extension, globally bind symbols, etc.,
-it is recommended that to avoid namespace pollution between systems,
-you should create your own package for that purpose,
-for instance replacing the above @code{(in-package :asdf)} with:
-
-@lisp
-(defpackage :foo-system
-  (:use :cl :asdf))
-
-(in-package :foo-system)
-@end lisp
+for package @code{asdf-user}.  Quick summary: just do this, because it
+helps make interactive development of @code{defsystem} forms behave in
+the same was as when these forms are loaded by ASDF.  If that's enough
+for you, skip the rest of this item.  Otherwise read on for the gory details.
+
+If your file is loaded by ASDF 3, it will be loaded into the
+@code{asdf-user} package.  The @code{in-package} form
+will ensure that the system definition is read the
+same as within ASDF when you load it interactively with @code{cl:load}.
+However, we recommend that you load @file{.asd} files
+through function @code{asdf::load-asd} rather than through @code{cl:load},
+in which case this form is unnecessary.
+Recent versions of SLIME (2013-02 and later) know to do that.
+
+@item
+You can always rely on symbols
+from both package @code{asdf} and @code{common-lisp} being available in
+@code{.asd} files --
+most importantly including @code{defsystem}.
+
+@c FIXME: the following should be inserted in a more advanced
+@c bit of the manual.  For now, it is simply elided.
+@c Starting with ASDF 3.1,
+@c @file{.asd} files are read in the package @code{asdf-user}
+@c that uses @code{asdf}, @code{uiop} and @code{uiop/common-lisp}
+@c (a variant of @code{common-lisp}
+@c that has some portability fixes on old implementations).
+@c ASDF 3 releases before 3.1 also read in package @code{asdf-user}
+@c but that package don't use the full @code{uiop}, only @code{uiop/package}.
+@c ASDF 1 and ASDF 2 releases (up until 2.26) instead read @file{.asd} files
+@c in a temporary package @code{asdf@emph{N}}
+@c that uses @code{asdf} and @code{common-lisp}.
+@c You may thus have to package-qualify some symbols with @code{uiop:}
+@c to support older variants of ASDF 3,
+@c and/or package-qualify them with @code{asdf::}
+@c to be compatible with even older variants of ASDF 2
+@c (and then only use the few already available in ASDF 2).
+
 
 @item
@@ -1000 +1125 @@
 @file{packages}, @file{macros} and @file{hello}.
 
+@c FIXME: The first example system should probably use just :serial T.
 @item
 The file @file{macros} depends on @file{packages}
@@ -1009 +1135 @@
 
 @item
-The files are located in the same directory
-as the file with the system definition.
-ASDF resolves symbolic links (or Windows shortcuts)
-before loading the system definition file and
-stores its location in the resulting system@footnote{
-It is possible, though almost never necessary, to override this behaviour.}.
-This is a good thing because the user can move the system sources
-without having to edit the system definition.
+System source files should be located in the same directory
+as the @code{.asd} file with the system definition.
+@c FIXME: the following should live somewhere, but not in the quickstart
+@c page. [2014/05/03:rpg]
+@c ASDF resolves symbolic links (or Windows shortcuts)
+@c before loading the system definition file and
+@c stores its location in the resulting system@footnote{
+@c It is possible, though almost never necessary, to override this behaviour.}.
+@c This is a good thing because the user can move the system sources
+@c without having to edit the system definition.
 
 @c FIXME: Should have cross-reference to "Version specifiers" in the
 @c defsystem grammar, but the cross-referencing is so broken by
 @c insufficient node breakdown that I have not put one in.
+@c FIXME: this is way too detailed for the first example!
+@c move it!
 @item
 Make sure you know how the @code{:version} numbers will be parsed!
-They are parsed as period-separated lists of integers.
-I.e., in the example, @code{0.2.1} is to be interpreted,
-roughly speaking, as @code{(0 2 1)}.
-In particular, version @code{0.2.1}
-is interpreted the same as @code{0.0002.1} and
-is strictly version-less-than version @code{0.20.1},
-even though the two are the same when interpreted as decimal fractions.
-Instead of a string representing the version,
-the @code{:version} argument can be an expression that is resolved to
-such a string using the following trivial domain-specific language:
-in addition to being a literal string, it can be an expression of the form
-@code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)},
-which will be resolved by reading a form in the specified pathname
-(read as a subpathname of the current system if relative or a unix-namestring).
-You may use a @code{uiop:access-at} specifier
-with the (optional) @code{:at} keyword,
-by default the specifier is @code{0}, meaning the first form is returned.
-
+Only period-separated non-negative integers are accepted.
+See below Version specifiers in @ref{The defsystem grammar}.
 @cindex :version
 
@@ -1048 +1162 @@
 @comment  node-name,  next,  previous,  up
 @section A more involved example
+@findex defsystem
 
 Let's illustrate some more involved uses of @code{defsystem} via a
@@ -1053 +1168 @@
 
 @lisp
+(in-package :asdf-user)
+
 (defsystem "foo"
   :version "1.0.0"
   :components ((:module "mod"
-                            :components ((:file "bar")
-                                                  (:file"baz")
-                                                  (:file "quux"))
-                            :perform (compile-op :after (op c)
-                                                  (do-something c))
-                            :explain (compile-op :after (op c)
-                                            (explain-something c)))
-                         (:file "blah")))
+                :components ((:file "bar")
+                             (:file"baz")
+                             (:file "quux"))
+                :perform (compile-op :after (op c)
+                           (do-something c))
+                :explain (compile-op :after (op c)
+                           (explain-something c)))
+               (:file "blah")))
 @end lisp
 
@@ -1102 +1219 @@
 @ref{The object model of ASDF}.
 
-@c The following plunge into the weeds is not appropriate in this
+@c FIXME: The following plunge into detail weeds is not appropriate in this
 @c location. [2010/10/03:rpg]
 @c note that although this also supports @code{:before} methods,
@@ -1110 +1227 @@
 @c but before the component in question has been compiled.
 
+
+@c FIXME: There should be YA example that shows definitions of functions
+@c and classes.  The following material should go there.
+@c @item
+@c If in addition to simply using @code{defsystem},
+@c you are going to define functions,
+@c create ASDF extension, globally bind symbols, etc.,
+@c it is recommended that to avoid namespace pollution between systems,
+@c you should create your own package for that purpose, with:
+
+@c @lisp
+@c (defpackage :hello-lisp-system
+@c   (:use :cl :asdf))
+
+@c (in-package :hello-lisp-system)
+@c @end lisp
+
+
 @node  The defsystem grammar, Other code in .asd files, A more involved example, Defining systems with defsystem
 @comment  node-name,  next,  previous,  up
 @section The defsystem grammar
+@findex defsystem
+@cindex DEFSYSTEM grammar
 
 @c FIXME: @var typesetting not consistently used here.  We should either expand
@@ -1150 +1287 @@
 component-type := :module | :file | :static-file | other-component-type
 
-other-component-type := symbol-by-name (@pxref{The defsystem grammar,,Component types})
+other-component-type := symbol-by-name
+                        (@pxref{The defsystem grammar,,Component types})
 
 # This is used in :depends-on, as opposed to ``dependency,''
@@ -1171 +1309 @@
 pathname-specifier := pathname | string | symbol
 
-method-form := (operation-name qual lambda-list @Arest body)
+method-form := (operation-name qual lambda-list @Arest{} body)
 qual := method qualifier
 
 component-dep-fail-option := :fail | :try-next | :ignore
 
-feature-expression := keyword | (:and @var{feature-expression}*)
-                      | (:or @var{feature-expression}*) | (:not @var{feature-expression})
+feature-expression := keyword
+                      | (:and @var{feature-expression}*)
+                      | (:or @var{feature-expression}*)
+                      | (:not @var{feature-expression})
 @end example
 
@@ -1296 +1436 @@
 will be interpreted as the pathname @file{#p"foo/bar.quux"}.
 
-ASDF does not interpret the string @code{".."} to designate the parent
-directory.  This string will be passed through to the underlying
-operating system for interpretation.  We @emph{believe} that this will
-work on all platforms where ASDF is deployed, but do not guarantee this
-behavior.  A pathname object with a relative directory component of
-@code{:up} or @code{:back} is the only guaranteed way to specify a
-parent directory.
+ASDF interprets the string @code{".."}
+as the pathname directory component word @code{:back},
+which when merged, goes back one level in the directory hierarchy.
 
 If a symbol is given, it will be translated into a string,
@@ -1329 +1465 @@
 the component-type default file type for a given component.
 Therefore, pathname objects should only rarely be used.
-Unhappily, ASDF 1 didn't properly support
+Unhappily, ASDF 1 used not to properly support
 parsing component names as strings specifying paths with directories,
 and the cumbersome @code{#.(make-pathname ...)} syntax had to be used.
@@ -1357 +1493 @@
 quite unlike what would have happened
 had the version strings been interpreted as decimal fractions.
+
+Instead of a string representing the version,
+the @code{:version} argument can be an expression that is resolved to
+such a string using the following trivial domain-specific language:
+in addition to being a literal string, it can be an expression of the form
+@code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)},
+which will be resolved by reading a form in the specified pathname
+(read as a subpathname of the current system if relative or a unix-namestring).
+You may use a @code{uiop:access-at} specifier
+with the (optional) @code{:at} keyword,
+by default the specifier is @code{0}, meaning the first form is returned;
+subforms can also be specified, with e.g. @code{(1 2 2)} specifying
+``the third subform (index 2) of the third subform (index 2) of the second form (index 1)''
+in the file (mind the off-by-one error in the English language).
 
 System definers are encouraged to use version identifiers of the form
@@ -1448 +1598 @@
 
 
-@subsection Source location
+@subsection Source location (@code{:pathname})
 
 The @code{:pathname} option is optional in all cases for systems
-defined via @code{defsystem},
-and in the usual case the user is recommended not to supply it.
-
-Instead, ASDF follows a hairy set of rules that are designed so that
+defined via @code{defsystem}, and generally is unnecessary.  In the
+simple case, source files will be found in the same directory as the
+system or, in the case of modules, in a subdirectory with the same name
+as the module.
+
+@c FIXME: This should be moved elsewhere -- it's too much detail for the
+@c grammar section.
+
+More specifically, ASDF follows a hairy set of rules that are designed so that
 @enumerate
 @item
@@ -1532 +1687 @@
 
 @subsection feature requirement
-This requirement was removed in ASDF 3.1.
-It used to ensure that a chain of component dependencies will raise an error,
-which in conjunction with if-component-dep-fails would offer
+This requirement was removed in ASDF 3.1.  Please do not use it.  In
+most cases, @code{:if-feature} (@pxref{if-feature-option}) will provide
+an adequate substitute.
+
+The @code{feature} requirement used to ensure that a chain of component
+dependencies would fail when a key feature was absent.
+Used in conjunction with @code{:if-component-dep-fails}
+this provided
 a roundabout way to express conditional compilation.
 
 
-@node Other code in .asd files, The package-system extension, The defsystem grammar, Defining systems with defsystem
+@node Other code in .asd files, The package-inferred-system extension, The defsystem grammar, Defining systems with defsystem
 @section Other code in .asd files
 
@@ -1548 +1708 @@
 that you use with @code{:defsystem-depends-on}.
 
-If however, you might insist on including code in the @code{.asd} file itself,
+If however, you might insist on including code in the @file{.asd} file itself,
 e.g., to examine and adjust the compile-time environment,
 possibly adding appropriate features to @code{*features*}.
@@ -1566 +1726 @@
 
 
-@node The package-system extension,  , Other code in .asd files, Defining systems with defsystem
-@section The package-system extension
-
-Starting with ASDF 3.0.3,
+@node The package-inferred-system extension,  , Other code in .asd files, Defining systems with defsystem
+@section The package-inferred-system extension
+
+Starting with release 3.1.2,
 ASDF supports a one-package-per-file style of programming,
 whereby each file is its own system,
-and dependencies are deduced from the @code{defpackage} form.
-
-In this style, packages referring to a same-named system (downcased);
-and if a system is defined with @code{:class package-system},
+and dependencies are deduced from the @code{defpackage} form
+(or its variant @code{uiop:define-package}).
+
+
+In this style, packages refer to a system with the same name (downcased);
+and if a system is defined with @code{:class package-inferred-system},
 then system names that start with that name
 (using the slash @code{/} separator)
@@ -1590 +1752 @@
 To use this style, choose a toplevel system name, e.g. @code{my-lib},
 and create a file @file{my-lib.asd}
-with the @code{:class :package-system} option in its @code{defsystem}.
+with the @code{:class :package-inferred-system} option in its @code{defsystem}.
 For instance:
 @example
 #-asdf (error "my-lib requires ASDF 3")
 (defsystem my-lib
-  :class :package-system
+  :class :package-inferred-system
   :defsystem-depends-on (:asdf-package-system)
-  :depends-on (:my-lib/src/all)
-  :in-order-to ((test-op (load-op :my-lib/test/all)))
-  :perform (test-op (o c) (symbol-call :my-lib/test/all :test-suite)))
-(register-system-packages :closer-mop
+  :depends-on (:lil/interface/all
+               :lil/pure/all
+               :lil/stateful/all
+               :lil/transform/all)
+  :in-order-to ((test-op (load-op :lil/test/all)))
+  :perform (test-op (o c) (symbol-call :lil/test/all :test-suite)))
+
+(defsystem :lil/test :depends-on (:lil/test/all))
+
+(register-system-packages :lil/interface/all '(:interface))
+(register-system-packages :lil/pure/all '(:pure))
+(register-system-packages :lil/stateful/all '(:stateful))
+(register-system-packages :lil/transform/classy '(:classy))
+(register-system-packages :lil/transform/posh '(:posh))
+(register-system-packages :lil/test/all '(:lil/test))
+
+(register-system-packages
+ :closer-mop
  '(:c2mop :closer-common-lisp :c2cl :closer-common-lisp-user :c2cl-user))
 @end example
@@ -1606 +1782 @@
 In the code above, the
 @code{:defsystem-depends-on (:asdf-package-system)} is
-for compatibility with older versions of ASDF 3 (ASDF 2 not supported),
+for compatibility with older versions of ASDF 3 (ASDF 2 is not supported),
 and requires the @code{asdf-package-system} library to be present
-(it is implicitly provided by ASDF starting with ASDF 3.0.3).
+(it is implicitly provided by ASDF starting with release 3.1.2,
+which can be detected with the feature @code{:asdf3.1}).
 
 The function @code{register-system-packages} has to be called to register
@@ -1615 +1792 @@
 is not the downcase of the package name.
 
-File @file{my-lib/src/utility.lisp} might start with:
+Then, file @file{interface/order.lisp} under the @code{lil} hierarchy,
+that defines abstract interfaces for order comparisons,
+starts with the following form,
+dependencies being trivially computed from the @code{:use} and @code{:mix} clauses:
 
 @example
-(defpackage :my-lib/src/utility
-  (:use :closer-common-lisp :my-lib/src/macros :my-lib/src/variables)
-  (:import-from :cl-ppcre #:register-groups-bind)
-  (:export #:foo #:bar))
+(uiop:define-package :lil/interface/order
+  (:use :closer-common-lisp
+   :lil/interface/definition
+   :lil/interface/base
+   :lil/interface/eq :lil/interface/group)
+  (:mix :fare-utils :uiop :alexandria)
+  (:export ...))
 @end example
 
-And from the @code{:use} and @code{:import-from} clauses,
-ASDF could tell that you depend on systems @code{closer-mop} (registered above),
-@code{cl-ppcre} (package and system names match), and
-@code{my-lib/src/macros} and @code{my-lib/src/variables}
+ASDF can tell that this file depends on system @code{closer-mop} (registered above),
+@code{lil/interface/definition}, @code{lil/interface/base},
+@code{lil/interface/eq}, and @code{lil/interface/group}
 (package and system names match, and they will be looked up hierarchically).
+
+ASDF also detects dependencies from @code{:import-from} clauses.
+To depend on a system without using a package or importing any symbol from it
+(because you'll fully qualify them when used),
+you may thus use an @code{:import-from} clause with an empty list of symbols, as in:
+
+@example
+(defpackage :foo/bar
+  (:use :cl)
+  (:import-from :foo/baz #:sym1 #:sym2)
+  (:import-from :foo/quux)
+  (:export ...))
+@end example
 
 The form @code{uiop:define-package} is supported as well as @code{defpackage},
@@ -1637 +1832 @@
 @node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top
 @comment  node-name,  next,  previous,  up
-@chapter The object model of ASDF
+@chapter The Object model of ASDF
+@tindex component
+@tindex operation
 
 ASDF is designed in an object-oriented way from the ground up.
 Both a system's structure and the operations that can be performed on systems
-follow a extensible protocol.
-
-This allows the addition of behaviours:
-for example, @code{cffi} adds support of special FFI description files
-to interface with C libraries and of wrapper files to embed C code in Lisp;
-@code{abcl-jar} supports creating Java JAR archives in ABCL;
-and @code{poiu} supports for compiling code in parallel using background processes.
-
-This chapter deals with @code{component}s and @code{operation}s.
+follow a extensible protocol, allowing programmers to add new behaviors to ASDF.
+For example, @code{cffi} adds support for special FFI description files
+that interface with C libraries and for wrapper files that embed C code in Lisp.
+@code{abcl-jar} supports creating Java JAR archives in ABCL.
+@code{poiu} supports compiling code in parallel using background processes.
+
+The key classes in ASDF are @code{component} and @code{operation}.
+A @code{component} represents an individual source file or a group of source files,
+and the products (e.g., fasl files) produced from it.
+An @code{operation} represents a transformation that can be performed on a component,
+turning them from source files to intermediate results to final outputs.
+Components are related by @emph{dependencies}, specified in system
+definitions.
+
+When ordered to @code{operate} with some operation on a component (usually a system),
+ASDF will first compute a @emph{plan}
+by traversing the dependency graph using function @code{make-plan}.@footnote{
+  Historically, the function that built a plan was
+  called @code{traverse}, and returned a list of actions;
+  it was deprecated in favor of @code{make-plan} (that returns a plan object)
+  when the @code{plan} objects were introduced;
+  the old function is kept for backward compatibility and debugging purposes only.
+}
+The resulting plan object contains an ordered list of @emph{actions}.
+An action is a pair of an @code{operation} and a @code{component},
+representing  a particular build step to be @code{perform}ed.
+The ordering of the plan ensures that no action is performed before
+all its dependencies have been fulfilled.@footnote{
+  The term @emph{action}
+  was used by Kent Pitman in his article, ``The Description of Large Systems,''
+  (@pxref{Bibliography}).
+  Although the term was only used by ASDF hackers starting with ASDF 2,
+  the concept was there since the very beginning of ASDF 1,
+  just not clearly articulated.
+}
+
+In this chapter, we describe ASDF's object-oriented protocol,
+the classes that make it up, and the generic functions on those classes.
+These generic functions often take
+both an operation and a component as arguments:
+much of the power and configurability of ASDF is provided by
+this use of CLOS's multiple dispatch.
+We will describe the built-in component and operation classes, and
+explain how to extend the ASDF protocol by defining new classes and
+methods for ASDF's generic functions.
+We will also describe the many @emph{hooks} that can be configured to
+customize the behavior of existing @emph{functions}.
+
+@c FIXME: Swap operations and components.
+@c FIXME: Possibly add a description of the PLAN object.
+@c Not critical, since the user isn't expected to interact with it.
+@menu
+* Operations::
+* Components::
+* Dependencies::
+* Functions::
+@end menu
+
+@node  Operations, Components, The object model of ASDF, The object model of ASDF
+@comment  node-name,  next,  previous,  up
+@section Operations
+@cindex operation
+
+An @dfn{operation} object of the appropriate type is instantiated
+whenever the user wants to do something with a system like
+
+@itemize
+@item compile all its files
+@item load the files into a running lisp environment
+@item copy its source files somewhere else
+@end itemize
+
+Operations can be invoked directly, or examined
+to see what their effects would be without performing them.
+There are a bunch of methods specialised on operation and component type
+that actually do the grunt work.
+Operations are invoked on systems via @code{operate} (@pxref{operate}).
+
+ASDF contains a number of pre-defined @t{operation} classes for common,
+and even fairly uncommon tasks that you might want to do with it.
+In addition, ASDF contains ``abstract'' @t{operation} classes that
+programmers can use as building blocks to define ASDF extensions.  We
+discuss these in turn below.
+
+@c The operation object contains whatever state is relevant for this purpose
+@c (perhaps a list of visited nodes, for example)
+@c but primarily is a nice thing to specialise operation methods on
+@c and easier than having them all be @code{EQL} methods.
+
+@menu
+* Predefined operations of ASDF::
+* Creating new operations::
+@end menu
+
+Operations are invoked on systems via @code{operate}.
+@anchor{operate}
+@deffn {Generic function} @code{operate} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @code{force} @code{force-not} @code{verbose} @AallowOtherKeys
+@deffnx {Generic function} @code{oos} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @AallowOtherKeys{}
+@code{operate} invokes @var{operation} on @var{system}.
+@code{oos} is a synonym for @code{operate} (it stands for operate-on-system).
+
+@var{operation} is a symbol that is passed,
+along with the supplied @var{initargs},
+to @code{make-operation} (which will call @code{make-instance})
+to create the operation object.
+@var{component} is a component designator,
+usually a string or symbol that designates a system,
+sometimes a list of strings or symbols that designate a subcomponent of a system.
+
+The @var{initargs} are passed to the @code{make-instance} call
+when creating the operation object.
+@c We probably want to deprecate that, because
+@c (1) there is a mix of flags for operate, for the operation-class, for the plan-class, etc.
+@c (2) flags to operations have never been well-supported, anyway.
+@c The future solution probably involves having an explicit :operation-options keyword or some such
+@c (if operation options are not wholly eliminated), a separate :plan-options, etc.
+Note that dependencies may cause the operation
+to invoke other operations on the system or its components:
+the new operations will be created
+with the same @var{initargs} as the original one.
+
+If @var{force} is @code{:all}, then all systems
+are forced to be recompiled even if not modified since last compilation.
+If @var{force} is @code{t}, then only the system being loaded
+is forced to be recompiled even if not modified since last compilation,
+but other systems are not affected.
+If @var{force} is a list, then it specifies a list of systems that
+are forced to be recompiled even if not modified since last compilation.
+If @var{force-not} is @code{:all}, then all systems
+are forced not to be recompiled even if modified since last compilation.
+If @var{force-not} is @code{t}, then all systems but the system being loaded
+are forced not to be recompiled even if modified since last compilation
+(note: this was changed in ASDF 3.1.2).
+If @var{force-not} is a list, then it specifies a list of systems that
+are forced not to be recompiled even if modified since last compilation.
+
+Both @var{force} and @var{force-not} apply to systems that are dependencies and were already compiled.
+@var{force-not} takes precedences over @var{force},
+as it should, really, but unhappily only since ASDF 3.1.2.
+Moreover, systems the name of which is member of the set @var{*immutable-systems*}
+(represented as an equal hash-table) are always considered @var{forced-not}, and
+even their @file{.asd} is not refreshed from the filesystem.
+
+To see what @code{operate} would do, you can use:
+@example
+(asdf:traverse operation-class system-name)
+@end example
+
+@end deffn
+
+
+
+@node Predefined operations of ASDF, Creating new operations, Operations, Operations
+@comment  node-name,  next,  previous,  up
+@subsection Predefined operations of ASDF
+@c FIXME: All these deffn's should be replaced with deftyp.  Also, we
+@c should set up an appropriate index.
+
+All the operations described in this section are in the @code{asdf} package.
+They are invoked via the @code{operate} generic function.
+
+@lisp
+(asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
+@end lisp
+
+@deffn Operation @code{compile-op}
+
+This operation compiles the specified component.
+A @code{cl-source-file} will be @code{compile-file}'d.
+All the children and dependencies of a system or module
+will be recursively compiled by @code{compile-op}.
+
+@code{compile-op} depends on @code{prepare-op} which
+itself depends on a @code{load-op} of all of a component's dependencies,
+as well as of its parent's dependencies.
+When @code{operate} is called on @code{compile-op},
+all these dependencies will be loaded as well as compiled;
+yet, some parts of the system main remain unloaded,
+because nothing depends on them.
+Use @code{load-op} to load a system.
+@end deffn
+
+@deffn Operation @code{load-op}
+
+This operation loads the compiled code for a specified component.
+A @code{cl-source-file} will have its compiled fasl @code{load}ed,
+which fasl is the output of @code{compile-op} that @code{load-op} depends on.
+
+@code{load-op} will recursively load all the children of a system or module.
+
+@code{load-op} also depends on @code{prepare-op} which
+itself depends on a @code{load-op} of all of a component's dependencies,
+as well as of its parent's dependencies.
+@end deffn
+
+@deffn Operation @code{prepare-op}
+
+This operation ensures that the dependencies of a component
+and its recursive parents are loaded (as per @code{load-op}),
+as a prerequisite before @code{compile-op} and @code{load-op} operations
+may be performed on a given component.
+@end deffn
+
+@deffn Operation @code{load-source-op}, @code{prepare-source-op}
+
+@code{load-source-op} will load the source for the files in a module
+rather than the compiled fasl output.
+It has a @code{prepare-source-op} analog to @code{prepare-op},
+that ensures the dependencies are themselves loaded via @code{load-source-op}.
+
+@end deffn
+
+@anchor{test-op}
+@deffn Operation @code{test-op}
+
+This operation will perform some tests on the module.
+The default method will do nothing.
+The default dependency is to require
+@code{load-op} to be performed on the module first.
+Its @code{operation-done-p} method returns @code{nil},
+which means that the operation is @emph{never} done
+--
+we assume that if you invoke the @code{test-op},
+you want to test the system, even if you have already done so.
+
+The results of this operation are not defined by ASDF.
+It has proven difficult to define how the test operation
+should signal its results to the user
+in a way that is compatible with all of the various test libraries
+and test techniques in use in the community, and
+given the fact that ASDF operations do not return a value indicating
+success or failure.
+For those willing to go to the effort, we suggest defining conditions to
+signal when a @code{test-op} fails, and storing in those conditions
+information that describes which tests fail.
+
+People typically define a separate test @emph{system} to hold the tests.
+Doing this avoids unnecessarily adding a test framework as a dependency
+on a library.  For example, one might have
+@lisp
+(defsystem foo
+  :in-order-to ((test-op (test-op "foo/test")))
+ ...)
+
+(defsystem foo/test
+  :depends-on (foo fiveam) ; fiveam is a test framework library
+  ...)
+@end lisp
+
+Then one defines @code{perform} methods on
+@code{test-op} such as the following:
+@lisp
+(defsystem foo/test
+  :depends-on (foo fiveam) ; fiveam is a test framework library
+  :perform (test-op (o s)
+                    (uiop:symbol-call :fiveam  '#:run!
+                       (uiop:find-symbol* '#:foo-test-suite
+                                            :foo-tests)))
+  ...)
+@end lisp
+
+@end deffn
+
+
+
+@deffn Operation @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op}, @code{lib-op}, @code{monolithic-lib-op}, @code{dll-op}, @code{monolithic-dll-op}, @code{image-op}, @code{program-op}
+
+These are ``bundle'' operations, that can create a single-file ``bundle''
+for all the contents of each system in an application,
+or for the entire application.
+
+@code{compile-bundle-op} will create a single fasl file for each of the systems needed,
+grouping all its many fasls in one,
+so you can deliver each system as a single fasl
+@code{monolithic-compile-bundle-op} will create a single fasl file for the target system
+and all its dependencies,
+so you can deliver your entire application as a single fasl.
+@code{load-bundle-op} will load the output of @code{compile-bundle-op}.
+Note that if it the output is not up-to-date,
+@code{compile-bundle-op} may load the intermediate fasls as a side-effect.
+Bundling fasls together matters a lot on ECL,
+where the dynamic linking involved in loading tens of individual fasls
+can be noticeably more expensive than loading a single one.
+
+NB: @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op} were respectively called
+@code{fasl-op}, @code{monolithic-fasl-op}, @code{load-fasl-op}, @code{monolithic-load-fasl-op}, @code{binary-op}, @code{monolithic-binary-op} before ASDF 3.1.
+The old names still exist for backward compatibility,
+though they poorly label what is going on.
+
+Once you have created a fasl with @code{compile-bundle-op},
+you can use @code{precompiled-system} to deliver it in a way
+that is compatible with clients having dependencies on your system,
+whether it is distributed as source or as a single binary;
+the @file{.asd} file to be delivered with the fasl will look like this:
+@example
+(defsystem :mysystem :class :precompiled-system
+  :fasl (some expression that will evaluate to a pathname))
+@end example
+Or you can use @code{deliver-asd-op} to let ASDF create such a system for you
+as well as the @code{compile-bundle-op} output,
+or @code{monolithic-deliver-asd-op}.
+This allows you to deliver code for your systems or applications
+as a single file.
+Of course, if you want to test the result in the current image,
+@emph{before} you try to use any newly created @file{.asd} files,
+you should not forget to @code{(asdf:clear-configuration)}
+or at least @code{(asdf:clear-source-registry)},
+so it re-populates the source-registry from the filesystem.
+
+The @code{program-op} operation will create an executable program
+from the specified system and its dependencies.
+You can use UIOP for its pre-image-dump hooks, its post-image-restore hooks,
+and its access to command-line arguments.
+And you can specify an entry point @code{my-app:main}
+by specifying in your @code{defsystem}
+the option @code{:entry-point "my-app:main"}.
+Depending on your implementation,
+running @code{(asdf:operate 'asdf:program-op :my-app)}
+may quit the current Lisp image upon completion.
+See the example in
+@file{test/hello-world-example.asd} and @file{test/hello.lisp},
+as built and tested by
+@file{test/test-program.script} and @file{test/make-hello-world.lisp}.
+@code{image-op} will dump an image that may not be standalone
+and does not start its own function,
+but follows the usual execution convention of the underlying Lisp,
+just with more code pre-loaded,
+for use as an intermediate build result or with a wrapper invocation script.
+
+There is also @code{lib-op}
+for building a linkable @file{.a} file (Windows: @file{.lib})
+from all linkable object dependencies (FFI files, and on ECL, Lisp files too),
+and its monolithic equivalent @code{monolithic-lib-op}.
+And there is also @code{dll-op}
+(respectively its monolithic equivalent @code{monolithic-lib-op})
+for building a linkable @file{.so} file
+(Windows: @file{.dll}, MacOS X: @file{.dynlib})
+to create a single dynamic library
+for all the extra FFI code to be linked into each of your systems
+(respectively your entire application).
+
+All these ``bundle'' operations are available since ASDF 3
+on all actively supported Lisp implementations,
+but may be unavailable on unmaintained legacy implementations.
+This functionality was previously available for select implementations,
+as part of a separate system @code{asdf-bundle},
+itself descended from the ECL-only @code{asdf-ecl}.
+
+The pathname of the output of bundle operations
+is subject to output-translation as usual,
+unless the operation is equal to
+the @code{:build-operation} argument to @code{defsystem}.
+This behavior is not very satisfactory and may change in the future.
+Maybe you have suggestions on how to better configure it?
+@end deffn
+
+@deffn Operation @code{concatenate-source-op}, @code{monolithic-concatenate-source-op}, @code{load-concatenated-source-op}, @code{compile-concatenated-source-op}, @code{load-compiled-concatenated-source-op}, @code{monolithic-load-concatenated-source-op}, @code{monolithic-compile-concatenated-source-op}, @code{monolithic-load-compiled-concatenated-source-op}
+
+These operations, as their respective names indicate,
+will concatenate all the @code{cl-source-file} source files in a system
+(or in a system and all its dependencies, if monolithic),
+in the order defined by dependencies,
+then load the result, or compile and then load the result.
+
+These operations are useful to deliver a system or application
+as a single source file,
+and for testing that said file loads properly, or compiles and then loads properly.
+
+ASDF itself is delivered as a single source file this way,
+using @code{monolithic-concatenate-source-op},
+prepending a prelude and the @code{uiop} library
+before the @code{asdf/defsystem} system itself.
+@end deffn
+
+
+@node  Creating new operations,  , Predefined operations of ASDF, Operations
+@comment  node-name,  next,  previous,  up
+@subsection Creating new operations
+
+ASDF was designed to be extensible in an object-oriented fashion.
+To teach ASDF new tricks, a programmer can implement the behaviour he wants
+by creating a subclass of @code{operation}.
+
+ASDF's pre-defined operations are in no way ``privileged'',
+but it is requested that developers never use the @code{asdf} package
+for operations they develop themselves.
+The rationale for this rule is that we don't want to establish a
+``global asdf operation name registry'',
+but also want to avoid name clashes.
+
+Your operation @emph{must} usually provide methods
+for one or more of the following generic functions:
+
+@itemize
+
+@findex perform
+@item @code{perform}
+Unless your operation, like @code{prepare-op},
+is for dependency propagation only,
+the most important function for which to define a method
+is usually @code{perform},
+which will be called to perform the operation on a specified component,
+after all dependencies have been performed.
+
+The @code{perform} method must call @code{input-files} and @code{output-files} (see below)
+to locate its inputs and outputs,
+because the user is allowed to override the method
+or tweak the output-translation mechanism.
+Perform should only use the primary value returned by @code{output-files}.
+If one and only one output file is expected,
+it can call @code{output-file} that checks that this is the case
+and returns the first and only list element.
+
+@findex output-files
+@item @code{output-files}
+If your perform method has any output,
+you must define a method for this function.
+for ASDF to determine where the outputs of performing operation lie.
+
+Your method may return two values, a list of pathnames, and a boolean.
+If the boolean is @code{nil} (or you fail to return multiple values),
+then enclosing @code{:around} methods may translate these pathnames,
+e.g. to ensure object files are somehow stored
+in some implementation-dependent cache.
+If the boolean is @code{t} then the pathnames are marked
+not be translated by the enclosing @code{:around} method.
+
+@findex component-depends-on
+@item @code{component-depends-on}
+If the action of performing the operation on a component has dependencies,
+you must define a method on @code{component-depends-on}.
+
+Your method will take as specialized arguments
+an operation and a component which together identify an action,
+and return a list of entries describing actions that this action depends on.
+The format of entries is described below.
+
+It is @emph{strongly} advised that
+you should always append the results of @code{(call-next-method)}
+to the results of your method,
+or ``interesting'' failures will likely occur,
+unless you're a true specialist of ASDF internals.
+It is unhappily too late to compatibly use the @code{append} method combination,
+but conceptually that's the protocol that is being manually implemented.
+
+Each entry returned by @code{component-depends-on} is itself a list.
+
+The first element of an entry is an operation designator:
+either an operation object designating itself, or
+a symbol that names an operation class
+(that ASDF will instantiate using @code{make-operation}).
+For instance, @code{load-op}, @code{compile-op} and @code{prepare-op}
+are common such names, denoting the respective operations.
+
+@c FIXME COERCE-NAME is referenced, but not defined.
+@findex coerce-name
+@findex find-component
+The rest of each entry is a list of component designators:
+either a component object designating itself,
+or an identifier to be used with @code{find-component}.
+@code{find-component} will be called with the current component's parent as parent,
+and the identifier as second argument.
+The identifier is typically a string,
+a symbol (to be downcased as per @code{coerce-name}),
+or a list of strings or symbols.
+In particular, the empty list @code{nil} denotes the parent itself.
+
+@end itemize
+
+An operation @emph{may} provide methods for the following generic functions:
+
+@itemize
+
+@item @code{input-files}
+@findex input-files
+A method for this function is often not needed,
+since ASDF has a pretty clever default @code{input-files} mechanism.
+You only need create a method if there are multiple ultimate input files,
+and/or the bottom one doesn't depend
+on the @code{component-pathname} of the component.
+
+@item @code{operation-done-p}
+@findex operation-done-p
+You only need to define a method on that function
+if you can detect conditions that invalidate previous runs of the operation,
+even though no filesystem timestamp has changed,
+in which case you return @code{nil} (the default is @code{t}).
+
+For instance, the method for @code{test-op} always returns @code{nil},
+so that tests are always run afresh.
+Of course, the @code{test-op} for your system could depend
+on a deterministically repeatable @code{test-report-op},
+and just read the results from the report files,
+in which case you could have this method return @code{t}.
+
+@end itemize
+
+Operations that print output should send that output to the standard
+CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
+
+@node Components, Dependencies, Operations, The object model of ASDF
+@comment  node-name,  next,  previous,  up
+@section Components
+@cindex component
+@cindex system
+@cindex system designator
+@cindex component designator
+@vindex *system-definition-search-functions*
 
 A @code{component} represents an individual source file or a group of source files,
 and the things that get transformed into.
-A @code{system} is a component at the top level of the component hierarchy.
+A @code{system} is a component at the top level of the component hierarchy,
+that can be found via @code{find-system}.
 A @code{source-file} is a component representing a single source-file
 and the successive output files into which it is transformed.
@@ -1659 +2356 @@
 themselves source-files or further modules.
 
-An @code{Operation} represents a transformation that can be performed on a component,
-turning them from source files to intermediate results to final outputs.
-
-A pair of an @code{operation} and a @code{component} is called an @code{action}.
-An @code{action} represents a particular build step to be @code{perform}ed,
-after all its dependencies have been fulfilled.
-In the ASDF model, actions depend on other actions.
-The term @emph{action} itself was used by Kent Pitman in his old article,
-but was only used by ASDF hackers starting with the ASDF 2;
-but the concept is ubiquitous since the very beginning of ASDF 1,
-though previously implicit.
-
-Then, there are many @emph{functions} available
-to users, extenders and implementers of ASDF
-to use, define or implement the activities
-that are part of building your software.
-Though they manipulate @code{action}s,
-most of these functions do not take as an argument
-a reified pair (a @code{cons} cell) of an operation and a component;
-instead, they usually take two separate arguments,
-which allows to take advantage of the power CLOS-style multiple dispatch
-for fun and profit.
-
-There are many @emph{hooks} in which to add functionality,
-by customizing the behavior of existing @emph{functions}.
-
-Last but not least is the notion of @emph{dependency} between two actions.
-The structure of dependencies between actions is
-a directed @emph{dependency graph}.
-ASDF is invoked by being told to @emph{operate}
-with some @emph{operation} on some toplevel @emph{system};
-it will then @emph{traverse} the graph and build a @emph{plan}
-that follows its structure.
+A @dfn{system designator} is a system itself,
+or a string or symbol that behaves just like any other component name
+(including with regard to the case conversion rules for component names).
+
+A @dfn{component designator}, relative to a base component,
+is either a component itself,
+or a string or symbol,
+or a list of designators.
+
+@defun find-system system-designator @Aoptional{} (error-p t)
+
+Given a system designator, @code{find-system} finds and returns a system.
+If no system is found, an error of type
+@code{missing-component} is thrown,
+or @code{nil} is returned if @code{error-p} is false.
+
+To find and update systems, @code{find-system} funcalls each element
+in the @code{*system-definition-search-functions*} list,
+expecting a pathname to be returned, or a system object,
+from which a pathname may be extracted, and that will be registered.
+The resulting pathname (if any) is loaded
+if one of the following conditions is true:
+
+@itemize
+@item
+there is no system of that name in memory
+@item
+the pathname is different from that which was previously loaded
+@item
+the file's @code{last-modified} time exceeds the @code{last-modified} time
+of the system in memory
+@end itemize
+
+When system definitions are loaded from @file{.asd} files,
+a new scratch package is created for them to load into,
+so that different systems do not overwrite each others operations.
+The user may also wish to (and is recommended to)
+include @code{defpackage} and @code{in-package} forms
+in his system definition files, however,
+so that they can be loaded manually if need be.
+
+The default value of @code{*system-definition-search-functions*}
+is a list of two functions.
+The first function looks in each of the directories given
+by evaluating members of @code{*central-registry*}
+for a file whose name is the name of the system and whose type is @file{asd}.
+The first such file is returned,
+whether or not it turns out to actually define the appropriate system.
+The second function does something similar,
+for the directories specified in the @code{source-registry}.
+Hence, it is strongly advised to define a system
+@var{foo} in the corresponding file @var{foo.asd}.
+@end defun
+
+@defun find-component base path
+
+Given a @var{base} component (or designator for such),
+and a @var{path}, find the component designated by the @var{path}
+starting from the @var{base}.
+
+If @var{path} is a component object, it designates itself,
+independently from the base.
+
+@findex coerce-name
+If @var{path} is a string, or symbol denoting a string via @code{coerce-name},
+then @var{base} is resolved to a component object,
+which must be a system or module,
+and the designated component is the child named by the @var{path}.
+
+If @var{path} is a @code{cons} cell,
+@code{find-component} with the base and the @code{car} of the @var{path},
+and the resulting object is used as the base for a tail call
+to @code{find-component} with the @code{car} of the @var{path}.
+
+If @var{base} is a component object, it designates itself.
+
+If @var{base} is null, then @var{path} is used as the base, with @code{nil} as the path.
+
+If @var{base} is a string, or symbol denoting a string via @code{coerce-name},
+it designates a system as per @code{find-system}.
+
+If @var{base} is a @code{cons} cell, it designates the component found by
+@code{find-component} with its @code{car} as base and @code{cdr} as path.
+@end defun
+
+
+@menu
+* Common attributes of components::
+* Pre-defined subclasses of component::
+* Creating new component types::
+@end menu
+
+@node  Common attributes of components, Pre-defined subclasses of component, Components, Components
+@comment  node-name,  next,  previous,  up
+@subsection Common attributes of components
+
+All components, regardless of type, have the following attributes.
+All attributes except @code{name} are optional.
+
+@subsubsection Name
+@findex coerce-name
+A component name is a string or a symbol.
+If a symbol, its name is taken and lowercased.  This translation is
+performed by the exported function @code{coerce-name}.
+
+Unless overridden by a @code{:pathname} attribute,
+the name will be interpreted as a pathname specifier according
+to a Unix-style syntax.
+@xref{The defsystem grammar,,Pathname specifiers}.
+
+@subsubsection Version identifier
+@findex version-satisfies
+@cindex :version
+
+This optional attribute specifies a version for the current component.
+The version should typically be a string of integers separated by dots,
+for example @samp{1.0.11}.
+For more information on version specifiers, see @ref{The defsystem grammar}.
+
+A version may then be queried by the generic function @code{version-satisfies},
+to see if @code{:version} dependencies are satisfied,
+and when specifying dependencies, a constraint of minimal version to satisfy
+can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
+
+Note that in the wild, we typically see version numbering
+only on components of type @code{system}.
+Presumably it is much less useful within a given system,
+wherein the library author is responsible to keep the various files in synch.
+
+@subsubsection Required features
+@anchor{required-features}
+
+Traditionally defsystem users have used @code{#+} reader conditionals
+to include or exclude specific per-implementation files.
+For example, CFFI, the portable C foreign function interface contained
+lines like:
+@lisp
+     #+sbcl       (:file "cffi-sbcl")
+@end lisp
+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
+for example the file @code{cffi-sbcl.lisp} above would be invisible when
+running the @code{archive-op} on any implementation other than SBCL.
+
+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
+during compilation, loading and/or linking.
+Since the expression is read by the normal reader,
+you must explicitly prefix your symbols with @code{:} so they be read as keywords;
+this is as contrasted with the @code{#+} syntax
+that implicitly reads symbols in the keyword package by default.
+
+For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
+the given component is only to be compiled and loaded
+when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
+You cannot write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
+since the symbols would not be read as keywords.
+
+@xref{if-feature-option}.
+
+@subsubsection Dependencies
+
+This attribute specifies dependencies of the component on its siblings.
+It is optional but often necessary.
+
+There is an excitingly complicated relationship between the initarg
+and the method that you use to ask about dependencies
+
+Dependencies are between (operation component) pairs.
+In your initargs for the component, you can say
+
+@lisp
+:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
+              (load-op (load-op "foo")))
+@end lisp
+
+This means the following things:
+@itemize
+@item
+before performing compile-op on this component, we must perform
+load-op on @var{a} and @var{b}, and compile-op on @var{c},
+@item
+before performing @code{load-op}, we have to load @var{foo}
+@end itemize
+
+The syntax is approximately
+
+@verbatim
+(this-op @{(other-op required-components)@}+)
+
+simple-component-name := string
+                      |  symbol
+
+required-components := simple-component-name
+                     | (required-components required-components)
+
+component-name := simple-component-name
+                | (:version simple-component-name minimum-version-object)
+@end verbatim
+
+Side note:
+
+This is on a par with what ACL defsystem does.
+mk-defsystem is less general: it has an implied dependency
+
+@verbatim
+  for all source file x, (load x) depends on (compile x)
+@end verbatim
+
+and using a @code{:depends-on} argument to say that @var{b} depends on
+@var{a} @emph{actually} means that
+
+@verbatim
+  (compile b) depends on (load a)
+@end verbatim
+
+This is insufficient for e.g. the McCLIM system, which requires that
+all the files are loaded before any of them can be compiled ]
+
+End side note
+
+In ASDF, the dependency information for a given component and operation
+can be queried using @code{(component-depends-on operation component)},
+which returns a list
+
+@lisp
+((load-op "a") (load-op "b") (compile-op "c") ...)
+@end lisp
+
+@code{component-depends-on} can be subclassed for more specific
+component/operation types: these need to @code{(call-next-method)}
+and append the answer to their dependency, unless
+they have a good reason for completely overriding the default dependencies.
+
+If it weren't for CLISP, we'd be using @code{LIST} method
+combination to do this transparently.
+But, we need to support CLISP.
+If you have the time for some CLISP hacking,
+I'm sure they'd welcome your fixes.
+@c Doesn't CLISP now support LIST method combination?
+
+A minimal version can be specified for a component you depend on
+(typically another system), by specifying @code{(:version "other-system" "1.2.3")}
+instead of simply @code{"other-system"} as the dependency.
+See the discussion of the semantics of @code{:version}
+in the defsystem grammar.
+
+@c FIXME: Should have cross-reference to "Version specifiers" in the
+@c defsystem grammar, but the cross-referencing is so broken by
+@c insufficient node breakdown that I have not put one in.
+
+
+@subsubsection pathname
+
+This attribute is optional and if absent (which is the usual case),
+the component name will be used.
+
+@xref{The defsystem grammar,,Pathname specifiers},
+for an explanation of how this attribute is interpreted.
+
+Note that the @code{defsystem} macro (used to create a ``top-level'' system)
+does additional processing to set the filesystem location of
+the top component in that system.
+This is detailed elsewhere. @xref{Defining systems with defsystem}.
+
+
+@subsubsection properties
+
+This attribute is optional.
+
+Packaging systems often require information about files or systems
+in addition to that specified by ASDF's pre-defined component attributes.
+Programs that create vendor packages out of ASDF systems therefore
+have to create ``placeholder'' information to satisfy these systems.
+Sometimes the creator of an ASDF system may know the additional
+information and wish to provide it directly.
+
+@code{(component-property component property-name)} and
+associated @code{setf} method will allow
+the programmatic update of this information.
+Property names are compared as if by @code{EQL},
+so use symbols or keywords or something.
+
+@menu
+* Pre-defined subclasses of component::
+* Creating new component types::
+@end menu
+
+@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
+@comment  node-name,  next,  previous,  up
+@subsection Pre-defined subclasses of component
+
+@deffn Component source-file
+
+A source file is any file that the system does not know how to
+generate from other components of the system.
+
+Note that this is not necessarily the same thing as
+``a file containing data that is typically fed to a compiler''.
+If a file is generated by some pre-processor stage
+(e.g. a @file{.h} file from @file{.h.in} by autoconf)
+then it is not, by this definition, a source file.
+Conversely, we might have a graphic file
+that cannot be automatically regenerated,
+or a proprietary shared library that we received as a binary:
+these do count as source files for our purposes.
+
+Subclasses of source-file exist for various languages.
+@emph{FIXME: describe these.}
+@end deffn
+
+@deffn Component module
+
+A module is a collection of sub-components.
+
+A module component has the following extra initargs:
+
+@itemize
+@item
+@code{:components} the components contained in this module
+
+@item
+@code{:default-component-class}
+All children components which don't specify their class explicitly
+are inferred to be of this type.
+
+@item
+@code{:if-component-dep-fails}
+This attribute was removed in ASDF 3. Do not use it.
+Use @code{:if-feature} instead (@pxref{required-features}, and @pxref{if-feature-option}).
+
+@item
+@code{:serial} When this attribute is set,
+each subcomponent of this component is assumed to depend on all subcomponents
+before it in the list given to @code{:components}, i.e.
+all of them are loaded before a compile or load operation is performed on it.
+
+@end itemize
+
+The default operation knows how to traverse a module, so
+most operations will not need to provide methods specialised on modules.
+
+@code{module} may be subclassed to represent components such as
+foreign-language linked libraries or archive files.
+@end deffn
+
+@deffn Component system
+
+@code{system} is a subclass of @code{module}.
+
+A system is a module with a few extra attributes for documentation
+purposes; these are given elsewhere.
+@xref{The defsystem grammar}.
+
+Users can create new classes for their systems:
+the default @code{defsystem} macro takes a @code{:class} keyword argument.
+@end deffn
+
+@node  Creating new component types,  , Pre-defined subclasses of component, Components
+@comment  node-name,  next,  previous,  up
+@subsection Creating new component types
+
+New component types are defined by subclassing one of the existing
+component classes and specializing methods on the new component class.
+
+@emph{FIXME: this should perhaps be explained more throughly,
+not only by example ...}
+
+As an example, suppose we have some implementation-dependent
+functionality that we want to isolate
+in one subdirectory per Lisp implementation our system supports.
+We create a subclass of
+@code{cl-source-file}:
+
+@lisp
+(defclass unportable-cl-source-file (cl-source-file)
+  ())
+@end lisp
+
+Function @code{asdf:implementation-type} (exported since 2.014.14)
+gives us the name of the subdirectory.
+All that's left is to define how to calculate the pathname
+of an @code{unportable-cl-source-file}.
+
+@lisp
+(defmethod component-pathname ((component unportable-cl-source-file))
+  (merge-pathnames*
+   (parse-unix-namestring (format nil "~(~A~)/" (asdf:implementation-type)))
+   (call-next-method)))
+@end lisp
+
+The new component type is used in a @code{defsystem} form in this way:
+
+@lisp
+(defsystem :foo
+    :components
+    ((:file "packages")
+     ...
+     (:unportable-cl-source-file "threads"
+      :depends-on ("packages" ...))
+     ...
+    )
+@end lisp
+
+@node Dependencies, Functions, Components, The object model of ASDF
+@section Dependencies
+@c FIXME: Moved this material here, but it isn't very comfortable
+@c here....  Also needs to be revised to be coherent.
+
 To be successfully buildable, this graph of actions but be acyclic.
 If, as a user, extender or implementer of ASDF, you fail
@@ -1717 +2795 @@
 ensuring that all the parent's dependencies are (compiled and) loaded
 before the child component may be compiled and loaded.
-Yet other operations, such as @code{test-op} or @code{load-fasl-op}
+Yet other operations, such as @code{test-op} or @code{load-bundle-op}
 remain at the system level, and are not propagated along the hierarchy,
 but instead do something global on the system.
 
-@menu
-* Operations::
-* Components::
-* Functions::
-@end menu
-
-@node  Operations, Components, The object model of ASDF, The object model of ASDF
-@comment  node-name,  next,  previous,  up
-@section Operations
-@cindex operation
-
-An @dfn{operation} object of the appropriate type is instantiated
-whenever the user wants to do something with a system like
-
-@itemize
-@item compile all its files
-@item load the files into a running lisp environment
-@item copy its source files somewhere else
-@end itemize
-
-Operations can be invoked directly, or examined
-to see what their effects would be without performing them.
-There are a bunch of methods specialised on operation and component type
-that actually do the grunt work.
-Operations are invoked on systems via @code{operate} (@pxref{operate}).
-
-ASDF contains a number of pre-defined @t{operation} classes for common,
-and even fairly uncommon tasks that you might want to do with it.
-In addition, ASDF contains ``abstract'' @t{operation} classes that
-programmers can use as building blocks to define ASDF extensions.  We
-discuss these in turn below.
-
-@c The operation object contains whatever state is relevant for this purpose
-@c (perhaps a list of visited nodes, for example)
-@c but primarily is a nice thing to specialise operation methods on
-@c and easier than having them all be @code{EQL} methods.
-
-@menu
-* Predefined operations of ASDF::
-* Creating new operations::
-@end menu
-
-Operations are invoked on systems via @code{operate}.
-@anchor{operate}
-@deffn {Generic function} @code{operate} @var{operation} @var{system} @Arest @var{initargs} @Akey @code{force} @code{force-not} @code{verbose} @AallowOtherKeys
-@deffnx {Generic function} @code{oos} @var{operation} @var{system} @Arest @var{initargs} @Akey @AallowOtherKeys
-@code{operate} invokes @var{operation} on @var{system}.
-@code{oos} is a synonym for @code{operate}.
-
-@var{operation} is a symbol that is passed, along with the supplied
-@var{initargs}, to @code{make-instance} to create the operation object.
-@var{system} is a system designator.
-
-The @var{initargs} are passed to the @code{make-instance} call
-when creating the operation object.
-Note that dependencies may cause the operation
-to invoke other operations on the system or its components:
-the new operations will be created
-with the same @var{initargs} as the original one.
-
-If @var{force} is @code{:all}, then all systems
-are forced to be recompiled even if not modified since last compilation.
-If @var{force} is @code{t}, then only the system being loaded
-is forced to be recompiled even if not modified since last compilation,
-but other systems are not affected.
-If @var{force} is a list, then it specifies a list of systems that
-are forced to be recompiled even if not modified since last compilation.
-If @var{force-not} is @code{:all}, then all systems
-are forced not to be recompiled even if modified since last compilation.
-If @var{force-not} is @code{t}, then all systems but the system being loaded
-are forced not to be recompiled even if modified since last compilation
-(note: this was changed in ASDF 3.1.1).
-If @var{force-not} is a list, then it specifies a list of systems that
-are forced not to be recompiled even if modified since last compilation.
-
-Both @var{force} and @var{force-not} apply to systems that are dependencies and were already compiled.
-@var{force-not} takes precedences over @var{force},
-as it should, really, but unhappily only since ASDF 3.1.1.
-Moreover, systems the name of which is member of the set @var{*immutable-systems*}
-(represented as an equal hash-table) are always considered @var{forced-not}, and
-even their @file{.asd} is not refreshed from the filesystem.
-
-To see what @code{operate} would do, you can use:
-@example
-(asdf:traverse operation-class system-name)
-@end example
-
-@end deffn
-
-
-
-@node Predefined operations of ASDF, Creating new operations, Operations, Operations
-@comment  node-name,  next,  previous,  up
-@subsection Predefined operations of ASDF
-
-All the operations described in this section are in the @code{asdf} package.
-They are invoked via the @code{operate} generic function.
-
-@lisp
-(asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
-@end lisp
-
-@deffn Operation @code{compile-op}
-
-This operation compiles the specified component.
-A @code{cl-source-file} will be @code{compile-file}'d.
-All the children and dependencies of a system or module
-will be recursively compiled by @code{compile-op}.
-
-@code{compile-op} depends on @code{prepare-op} which
-itself depends on a @code{load-op} of all of a component's dependencies,
-as well as of its parent's dependencies.
-When @code{operate} is called on @code{compile-op},
-all these dependencies will be loaded as well as compiled;
-yet, some parts of the system main remain unloaded,
-because nothing depends on them.
-Use @code{load-op} to load a system.
-@end deffn
-
-@deffn Operation @code{load-op}
-
-This operation loads the compiled code for a specified component.
-A @code{cl-source-file} will have its compiled fasl @code{load}ed,
-which fasl is the output of @code{compile-op} that @code{load-op} depends on.
-All the children and dependencies of a system or module
-will be recursively loaded by @code{load-op}.
-
-@code{load-op} depends on @code{prepare-op} which
-itself depends on a @code{load-op} of all of a component's dependencies,
-as well as of its parent's dependencies.
-@end deffn
-
-@deffn Operation @code{prepare-op}
-
-This operation ensures that the dependencies of a component
-and its recursive parents are loaded (as per @code{load-op}),
-as a prerequisite before @code{compile-op} and @code{load-op} operations
-may be performed on a given component.
-@end deffn
-
-@deffn Operation @code{load-source-op}, @code{prepare-source-op}
-
-@code{load-source-op} will load the source for the files in a module
-rather than they compiled fasl output.
-It has a @code{prepare-source-op} analog to @code{prepare-op},
-that ensures the dependencies are themselves loaded via @code{load-source-op}.
-
-There is no provision in ASDF for ensuring that
-some components are always loaded as source, while others are always compiled.
-While this idea often comes up in discussions,
-it actually doesn't play well with either the linking model of ECL
-or with various bundle operations (see below), and is eventually not workable;
-also the dependency model of ASDF would have to be modified incompatibly
-to allow for such trick.
-If your code doesn't compile cleanly, fix it.
-If compilation makes it slow, use @code{declaim} or @code{eval-when}
-to adjust your compiler settings,
-or eschew compilation by @code{eval}uating a quoted source form at load-time.
-@end deffn
-
-@anchor{test-op}
-@deffn Operation @code{test-op}
-
-This operation will perform some tests on the module.
-The default method will do nothing.
-The default dependency is to require
-@code{load-op} to be performed on the module first.
-The default @code{operation-done-p} is that the operation is @emph{never} done
----
-we assume that if you invoke the @code{test-op},
-you want to test the system, even if you have already done so.
-
-The results of this operation are not defined by ASDF.
-It has proven difficult to define how the test operation
-should signal its results to the user
-in a way that is compatible with all of the various test libraries
-and test techniques in use in the community.
-
-People typically define @code{test-op} methods like thus:
-@example
-(defmethod perform ((o asdf:test-op)
-                    (s (eql (asdf:find-system @var{:my-system}))))
-  (asdf:load-system @var{:my-system-test})
-  (funcall (read-from-string "my-system-test:test-suite")))
-@end example
-
-Using @code{load-system} in the perform method
-rather than an @code{:in-order-to} dependency,
-is sometimes necessary for backward compatibility with ASDF 2 and older,
-to avoid circular dependencies that could arise
-because of the way these old versions propagate dependencies.
-
-If you don't care for compatibility with ASDF 2,
-you could use the following options in your @code{defsystem} form:
-@example
-  :in-order-to ((test-op (load-op :my-system-test)))
-  :perform (test-op (o c) (symbol-call :my-system-test :test-suite))
-@end example
-@end deffn
-
-@deffn Operation @code{fasl-op}, @code{monolithic-fasl-op}, @code{load-fasl-op}, @code{binary-op}, @code{monolithic-binary-op}, @code{lib-op}, @code{monolithic-lib-op}, @code{dll-op}, @code{monolithic-dll-op}, @code{program-op}
-
-These are ``bundle'' operations, that can create a single-file ``bundle''
-for all the contents of each system in an application,
-or for the entire application.
-
-@code{fasl-op} will create a single fasl file for each of the systems needed,
-grouping all its many fasls in one,
-so you can deliver each system as a single fasl.
-@code{monolithic-fasl-op} will create a single fasl file for target system
-and all its dependencies,
-so you can deliver your entire application as a single fasl.
-@code{load-fasl-op} will load the output of @code{fasl-op}
-(though if it the output is not up-to-date,
-it will load the intermediate fasls indeed as part of building it);
-this matters a lot on ECL, where the dynamic linking involved in loading
-tens of individual fasls can be noticeably more expensive
-than loading a single one.
-
-Once you have created a fasl with @code{fasl-op},
-you can use @code{precompiled-system} to deliver it in a way
-that is compatible with clients having dependencies on your system,
-whether it is distributed as source or as a single binary;
-the @file{.asd} file to be delivered with the fasl will look like this:
-@example
-(defsystem :mysystem :class :precompiled-system
-    :fasl (some expression that will evaluate to a pathname))
-@end example
-Or you can use @code{binary-op} to let ASDF create such a system for you
-as well as the @code{fasl-op} output, or @code{monolithic-binary-op}.
-This allows you to deliver code for your systems or applications
-as a single file.
-Of course, if you want to test the result in the current image,
-@emph{before} you try to use any newly created @file{.asd} files,
-you should not forget to @code{(asdf:clear-configuration)}
-or at least @code{(asdf:clear-source-registry)},
-so it re-populates the source-registry from the filesystem.
-
-The @code{program-op} operation will create an executable program
-from the specified system and its dependencies.
-You can use UIOP for its pre-image-dump hooks, its post-image-restore hooks,
-and its access to command-line arguments.
-And you can specify an entry point @code{my-app:main}
-by specifying in your @code{defsystem}
-the option @code{:entry-point "my-app:main"}.
-Depending on your implementation,
-running @code{(asdf:operate 'asdf:program-op :my-app)}
-may quit the current Lisp image upon completion.
-See the example in
-@file{test/hello-world-example.asd} and @file{test/hello.lisp},
-as built and tested by
-@file{test/test-program.script} and @file{test/make-hello-world.lisp}.
-
-There is also @code{lib-op}
-for building a linkable @file{.a} file (Windows: @file{.lib})
-from all linkable object dependencies (FFI files, and on ECL, Lisp files too),
-and its monolithic equivalent @code{monolithic-lib-op}.
-And there is also @code{dll-op}
-(respectively its monolithic equivalent @code{monolithic-lib-op})
-for building a linkable @file{.so} file
-(Windows: @file{.dll}, MacOS X: @file{.dynlib})
-to create a single dynamic library
-for all the extra FFI code to be linked into each of your systems
-(respectively your entire application).
-
-All these ``bundle'' operations are available since ASDF 3
-on all actively supported Lisp implementations,
-but may be unavailable on unmaintained legacy implementations.
-This functionality was previously available for select implementations,
-as part of a separate system @code{asdf-bundle},
-itself descended from the ECL-only @code{asdf-ecl}.
-
-The pathname of the output of bundle operations
-is subject to output-translation as usual,
-unless the operation is equal to
-the @code{:build-operation} argument to @code{defsystem}.
-This behavior is not very satisfactory and may change in the future.
-Maybe you have suggestions on how to better configure it?
-@end deffn
-
-@deffn Operation @code{concatenate-source-op}, @code{monolithic-concatenate-source-op}, @code{load-concatenated-source-op}, @code{compile-concatenated-source-op}, @code{load-compiled-concatenated-source-op}, @code{monolithic-load-concatenated-source-op}, @code{monolithic-compile-concatenated-source-op}, @code{monolithic-load-compiled-concatenated-source-op}
-
-These operation, as their respective names indicate,
-consist in concatenating all @code{cl-source-file} source files in a system
-(or in a system and all its dependencies, if monolithic),
-in the order defined by dependencies,
-then loading the result, or compiling then loading the result.
-
-These operations are useful to deliver a system or application
-as a single source file,
-and for testing that said file loads properly, or compiles then loads properly.
-
-ASDF itself is notably delivered as a single source file this way
-using @code{monolithic-concatenate-source-op},
-transcluding a prelude and the @code{uiop} library
-before the @code{asdf/defsystem} system itself.
-@end deffn
-
-
-@node  Creating new operations,  , Predefined operations of ASDF, Operations
-@comment  node-name,  next,  previous,  up
-@subsection Creating new operations
-
-ASDF was designed to be extensible in an object-oriented fashion.
-To teach ASDF new tricks, a programmer can implement the behaviour he wants
-by creating a subclass of @code{operation}.
-
-ASDF's pre-defined operations are in no way ``privileged'',
-but it is requested that developers never use the @code{asdf} package
-for operations they develop themselves.
-The rationale for this rule is that we don't want to establish a
-``global asdf operation name registry'',
-but also want to avoid name clashes.
-
-Your operation @emph{must} usually provide methods
-for one or more of the following generic functions:
-
-@itemize
-
-@item @code{perform}
-Unless your operation, like @code{prepare-op},
-is for dependency propagation only,
-the most important function for which to define a method
-is usually @code{perform},
-which will be called to perform the operation on a specified component,
-after all dependencies have been performed.
-
-The @code{perform} method must call @code{output-files} (see below)
-to find out where to put its files,
-because the user is allowed to override the method
-or tweak the output-translation mechanism.
-Perform should only use the primary value returned by @code{output-files}.
-If one and only one output file is expected,
-it can call @code{output-file} that checks that this is the case
-and returns the first and only list element.
-
-@item @code{output-files}
-If your perform method has any output,
-you must define a method for this function.
-for ASDF to determine where the outputs of performing operation lie.
-
-Your method may return two values, a list of pathnames, and a boolean.
-If the boolean is @code{nil} (or you fail to return multiple values),
-then enclosing @code{:around} methods may translate these pathnames,
-e.g. to ensure object files are somehow stored
-in some implementation-dependent cache.
-If the boolean is @code{t} then the pathnames are marked
-not be translated by the enclosing @code{:around} method.
-
-@item @code{component-depends-on}
-If the action of performing the operation on a component has dependencies,
-you must define a method on @code{component-depends-on}.
-
-Your method will take as specialized arguments
-an operation and a component which together identify an action,
-and return a list of entries describing actions that this action depends on.
-The format of entries is described below.
-
-It is @emph{strongly} advised that
-you should always append the results of @code{(call-next-method)}
-to the results of your method,
-or ``interesting'' failures will likely occur,
-unless you're a true specialist of ASDF internals.
-It is unhappily too late to compatibly use the @code{append} method combination,
-but conceptually that's the protocol that is being manually implemented.
-
-Each entry returned by @code{component-depends-on} is itself a list.
-
-The first element of an entry is an operation designator:
-either an operation object designating itself, or
-a symbol that names an operation class
-(that ASDF will instantiate using @code{make-operation}).
-For instance, @code{load-op}, @code{compile-op} and @code{prepare-op}
-are common such names, denoting the respective operations.
-
-The rest of each entry is a list of component designators:
-either a component object designating itself,
-or an identifier to be used with @code{find-component}.
-@code{find-component} will be called with the current component's parent as parent,
-and the identifier as second argument.
-The identifier is typically a string,
-a symbol (to be downcased as per @code{coerce-name}),
-or a list of strings or symbols.
-In particular, the empty list @code{nil} denotes the parent itself.
-
-@end itemize
-
-An operation @emph{may} provide methods for the following generic functions:
-
-@itemize
-
-@item @code{input-files}
-A method for this function is often not needed,
-since ASDF has a pretty clever default @code{input-files} mechanism.
-You only need create a method if there are multiple ultimate input files,
-and/or the bottom one doesn't depend
-on the @code{component-pathname} of the component.
-
-@item @code{operation-done-p}
-You only need to define a method on that function
-if you can detect conditions that invalidate previous runs of the operation,
-even though no filesystem timestamp has changed,
-in which case you return @code{nil} (the default is @code{t}).
-
-For instance, the method for @code{test-op} always returns @code{nil},
-so that tests are always run afresh.
-Of course, the @code{test-op} for your system could depend
-on a deterministically repeatable @code{test-report-op},
-and just read the results from the report files,
-in which case you could have this method return @code{t}.
-
-@end itemize
-
-Operations that print output should send that output to the standard
-CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
-
-@node Components, Functions, Operations, The object model of ASDF
-@comment  node-name,  next,  previous,  up
-@section Components
-@cindex component
-@cindex system
-@cindex system designator
-@cindex component designator
-@vindex *system-definition-search-functions*
-
-A @dfn{component} represents a source file or
-(recursively) a collection of components.
-A @dfn{system} is (roughly speaking) a top-level component
-that can be found via @code{find-system}.
-
-A @dfn{system designator} is a system itself,
-or a string or symbol that behaves just like any other component name
-(including with regard to the case conversion rules for component names).
-
-A @dfn{component designator}, relative to a base component,
-is either a component itself,
-or a string or symbol,
-or a list of designators.
-
-@defun find-system system-designator @Aoptional (error-p t)
-
-Given a system designator, @code{find-system} finds and returns a system.
-If no system is found, an error of type
-@code{missing-component} is thrown,
-or @code{nil} is returned if @code{error-p} is false.
-
-To find and update systems, @code{find-system} funcalls each element
-in the @code{*system-definition-search-functions*} list,
-expecting a pathname to be returned, or a system object,
-from which a pathname may be extracted, and that will be registered.
-The resulting pathname (if any) is loaded
-if one of the following conditions is true:
-
-@itemize
-@item
-there is no system of that name in memory
-@item
-the pathname is different from that which was previously loaded
-@item
-the file's @code{last-modified} time exceeds the @code{last-modified} time
-of the system in memory
-@end itemize
-
-When system definitions are loaded from @file{.asd} files,
-a new scratch package is created for them to load into,
-so that different systems do not overwrite each others operations.
-The user may also wish to (and is recommended to)
-include @code{defpackage} and @code{in-package} forms
-in his system definition files, however,
-so that they can be loaded manually if need be.
-
-The default value of @code{*system-definition-search-functions*}
-is a list of two functions.
-The first function looks in each of the directories given
-by evaluating members of @code{*central-registry*}
-for a file whose name is the name of the system and whose type is @file{asd}.
-The first such file is returned,
-whether or not it turns out to actually define the appropriate system.
-The second function does something similar,
-for the directories specified in the @code{source-registry}.
-Hence, it is strongly advised to define a system
-@var{foo} in the corresponding file @var{foo.asd}.
-@end defun
-
-@defun find-component base path
-
-Given a @var{base} component (or designator for such),
-and a @var{path}, find the component designated by the @var{path}
-starting from the @var{base}.
-
-If @var{path} is a component object, it designates itself,
-independently from the base.
-
-If @var{path} is a string, or symbol denoting a string via @code{coerce-name},
-then @var{base} is resolved to a component object,
-which must be a system or module,
-and the designated component is the child named by the @var{path}.
-
-If @var{path} is a @code{cons} cell,
-@code{find-component} with the base and the @code{car} of the @var{path},
-and the resulting object is used as the base for a tail call
-to @code{find-component} with the @code{car} of the @var{path}.
-
-If @var{base} is a component object, it designates itself.
-
-If @var{base} is null, then @var{path} is used as the base, with @code{nil} as the path.
-
-If @var{base} is a string, or symbol denoting a string via @code{coerce-name},
-it designates a system as per @code{find-system}.
-
-If @var{base} is a @code{cons} cell, it designates the component found by
-@code{find-component} with its @code{car} as base and @code{cdr} as path.
-@end defun
-
-
-@menu
-* Common attributes of components::
-* Pre-defined subclasses of component::
-* Creating new component types::
-@end menu
-
-@node  Common attributes of components, Pre-defined subclasses of component, Components, Components
-@comment  node-name,  next,  previous,  up
-@subsection Common attributes of components
-
-All components, regardless of type, have the following attributes.
-All attributes except @code{name} are optional.
-
-@subsubsection Name
-
-A component name is a string or a symbol.
-If a symbol, its name is taken and lowercased.
-
-Unless overridden by a @code{:pathname} attribute,
-the name will be interpreted as a pathname specifier according
-to a Unix-style syntax.
-@xref{The defsystem grammar,,Pathname specifiers}.
-
-@subsubsection Version identifier
-@findex version-satisfies
-@cindex :version
-
-This optional attribute specifies a version for the current component.
-The version should typically be a string of integers separated by dots,
-for example @samp{1.0.11}.
-For more information on version specifiers, see @ref{The defsystem grammar}.
-
-A version may then be queried by the generic function @code{version-satisfies},
-to see if @code{:version} dependencies are satisfied,
-and when specifying dependencies, a constraint of minimal version to satisfy
-can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
-
-Note that in the wild, we typically see version numbering
-only on components of type @code{system}.
-Presumably it is much less useful within a given system,
-wherein the library author is responsible to keep the various files in synch.
-
-@subsubsection Required features
-@anchor{required-features}
-
-Traditionally defsystem users have used @code{#+} reader conditionals
-to include or exclude specific per-implementation files.
-For example, CFFI, the portable C foreign function interface contained
-lines like:
-@lisp
-     #+sbcl       (:file "cffi-sbcl")
-@end lisp
-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
-for example the file @code{cffi-sbcl.lisp} above would be invisible when
-running the @code{archive-op} on any implementation other than SBCL.
-
-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
-during compilation, loading and/or linking.
-Since the expression is read by the normal reader,
-you must explicitly prefix your symbols with @code{:} so they be read as keywords;
-this is as contrasted with the @code{#+} syntax
-that implicitly reads symbols in the keyword package by default.
-
-For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
-the given component is only to be compiled and loaded
-when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
-You cannot write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
-since the symbols would not be read as keywords.
-
-@xref{if-feature-option}.
-
-@subsubsection Dependencies
-
-This attribute specifies dependencies of the component on its siblings.
-It is optional but often necessary.
-
-There is an excitingly complicated relationship between the initarg
-and the method that you use to ask about dependencies
-
-Dependencies are between (operation component) pairs.
-In your initargs for the component, you can say
-
-@lisp
-:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
-              (load-op (load-op "foo")))
-@end lisp
-
-This means the following things:
-@itemize
-@item
-before performing compile-op on this component, we must perform
-load-op on @var{a} and @var{b}, and compile-op on @var{c},
-@item
-before performing @code{load-op}, we have to load @var{foo}
-@end itemize
-
-The syntax is approximately
-
-@verbatim
-(this-op @{(other-op required-components)@}+)
-
-simple-component-name := string
-                      |  symbol
-
-required-components := simple-component-name
-                     | (required-components required-components)
-
-component-name := simple-component-name
-                | (:version simple-component-name minimum-version-object)
-@end verbatim
-
-Side note:
-
-This is on a par with what ACL defsystem does.
-mk-defsystem is less general: it has an implied dependency
-
-@verbatim
-  for all source file x, (load x) depends on (compile x)
-@end verbatim
-
-and using a @code{:depends-on} argument to say that @var{b} depends on
-@var{a} @emph{actually} means that
-
-@verbatim
-  (compile b) depends on (load a)
-@end verbatim
-
-This is insufficient for e.g. the McCLIM system, which requires that
-all the files are loaded before any of them can be compiled ]
-
-End side note
-
-In ASDF, the dependency information for a given component and operation
-can be queried using @code{(component-depends-on operation component)},
-which returns a list
-
-@lisp
-((load-op "a") (load-op "b") (compile-op "c") ...)
-@end lisp
-
-@code{component-depends-on} can be subclassed for more specific
-component/operation types: these need to @code{(call-next-method)}
-and append the answer to their dependency, unless
-they have a good reason for completely overriding the default dependencies.
-
-If it weren't for CLISP, we'd be using @code{LIST} method
-combination to do this transparently.
-But, we need to support CLISP.
-If you have the time for some CLISP hacking,
-I'm sure they'd welcome your fixes.
-@c Doesn't CLISP now support LIST method combination?
-
-A minimal version can be specified for a component you depend on
-(typically another system), by specifying @code{(:version "other-system" "1.2.3")}
-instead of simply @code{"other-system"} as the dependency.
-See the discussion of the semantics of @code{:version}
-in the defsystem grammar.
-
-@c FIXME: Should have cross-reference to "Version specifiers" in the
-@c defsystem grammar, but the cross-referencing is so broken by
-@c insufficient node breakdown that I have not put one in.
-
-
-@subsubsection pathname
-
-This attribute is optional and if absent (which is the usual case),
-the component name will be used.
-
-@xref{The defsystem grammar,,Pathname specifiers},
-for an explanation of how this attribute is interpreted.
-
-Note that the @code{defsystem} macro (used to create a ``top-level'' system)
-does additional processing to set the filesystem location of
-the top component in that system.
-This is detailed elsewhere. @xref{Defining systems with defsystem}.
-
-
-@subsubsection properties
-
-This attribute is optional.
-
-Packaging systems often require information about files or systems
-in addition to that specified by ASDF's pre-defined component attributes.
-Programs that create vendor packages out of ASDF systems therefore
-have to create ``placeholder'' information to satisfy these systems.
-Sometimes the creator of an ASDF system may know the additional
-information and wish to provide it directly.
-
-@code{(component-property component property-name)} and
-associated @code{setf} method will allow
-the programmatic update of this information.
-Property names are compared as if by @code{EQL},
-so use symbols or keywords or something.
-
-@menu
-* Pre-defined subclasses of component::
-* Creating new component types::
-@end menu
-
-@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
-@comment  node-name,  next,  previous,  up
-@subsection Pre-defined subclasses of component
-
-@deffn Component source-file
-
-A source file is any file that the system does not know how to
-generate from other components of the system.
-
-Note that this is not necessarily the same thing as
-``a file containing data that is typically fed to a compiler''.
-If a file is generated by some pre-processor stage
-(e.g. a @file{.h} file from @file{.h.in} by autoconf)
-then it is not, by this definition, a source file.
-Conversely, we might have a graphic file
-that cannot be automatically regenerated,
-or a proprietary shared library that we received as a binary:
-these do count as source files for our purposes.
-
-Subclasses of source-file exist for various languages.
-@emph{FIXME: describe these.}
-@end deffn
-
-@deffn Component module
-
-A module is a collection of sub-components.
-
-A module component has the following extra initargs:
-
-@itemize
-@item
-@code{:components} the components contained in this module
-
-@item
-@code{:default-component-class}
-All children components which don't specify their class explicitly
-are inferred to be of this type.
-
-@item
-@code{:if-component-dep-fails}
-This attribute was removed in ASDF 3. Do not use it.
-Use @code{:if-feature} instead (@pxref{required-features}, and @pxref{if-feature-option}).
-
-@item
-@code{:serial} When this attribute is set,
-each subcomponent of this component is assumed to depend on all subcomponents
-before it in the list given to @code{:components}, i.e.
-all of them are loaded before a compile or load operation is performed on it.
-
-@end itemize
-
-The default operation knows how to traverse a module, so
-most operations will not need to provide methods specialised on modules.
-
-@code{module} may be subclassed to represent components such as
-foreign-language linked libraries or archive files.
-@end deffn
-
-@deffn Component system
-
-@code{system} is a subclass of @code{module}.
-
-A system is a module with a few extra attributes for documentation
-purposes; these are given elsewhere.
-@xref{The defsystem grammar}.
-
-Users can create new classes for their systems:
-the default @code{defsystem} macro takes a @code{:class} keyword argument.
-@end deffn
-
-@node  Creating new component types,  , Pre-defined subclasses of component, Components
-@comment  node-name,  next,  previous,  up
-@subsection Creating new component types
-
-New component types are defined by subclassing one of the existing
-component classes and specializing methods on the new component class.
-
-@emph{FIXME: this should perhaps be explained more throughly,
-not only by example ...}
-
-As an example, suppose we have some implementation-dependent
-functionality that we want to isolate
-in one subdirectory per Lisp implementation our system supports.
-We create a subclass of
-@code{cl-source-file}:
-
-@lisp
-(defclass unportable-cl-source-file (cl-source-file)
-  ())
-@end lisp
-
-Function @code{asdf:implementation-type} (exported since 2.014.14)
-gives us the name of the subdirectory.
-All that's left is to define how to calculate the pathname
-of an @code{unportable-cl-source-file}.
-
-@lisp
-(defmethod component-pathname ((component unportable-cl-source-file))
-  (merge-pathnames*
-   (parse-unix-namestring (format nil "~(~A~)/" (asdf:implementation-type)))
-   (call-next-method)))
-@end lisp
-
-The new component type is used in a @code{defsystem} form in this way:
-
-@lisp
-(defsystem :foo
-    :components
-    ((:file "packages")
-     ...
-     (:unportable-cl-source-file "threads"
-      :depends-on ("packages" ...))
-     ...
-    )
-@end lisp
-
-@node Functions,  , Components, The object model of ASDF
+
+@node Functions,  , Dependencies, The object model of ASDF
 @comment  node-name,  next,  previous,  up
 @section Functions
-@findex version-satisfies
-
-@deffn version-satisfies @var{version} @var{version-spec}
+
+@c FIXME: this does not belong here....
+@defun version-satisfies @var{version} @var{version-spec}
 Does @var{version} satisfy the @var{version-spec}.  A generic function.
 ASDF provides built-in methods for @var{version} being a @code{component} or @code{string}.
@@ -2592 +2834 @@
 could be in the future extended to specify an exclusive upper bound for compatible versions
 as well as an inclusive lower bound.
-@end deffn
+@end defun
 
 @node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
@@ -2598 +2840 @@
 @chapter Controlling where ASDF searches for systems
 
+
+
+@menu
+* Configurations::
+* Truenames and other dangers::
+* XDG base directory::
+* Backward Compatibility::
+* Configuration DSL::
+* Configuration Directories::
+* Shell-friendly syntax for configuration::
+* Search Algorithm::
+* Caching Results::
+* Configuration API::
+* Introspection::
+* Status::
+* Rejected ideas::
+* TODO::
+* Credits for the source-registry::
+@end menu
+
+@node  Configurations, Truenames and other dangers, Controlling where ASDF searches for systems, Controlling where ASDF searches for systems
 @section Configurations
 
@@ -2640 +2903 @@
 @item
 The source registry will be configured from
+default user configuration trees
+@file{~/common-lisp/} (since ASDF 3.1.2 only),
+@file{~/.sbcl/systems/} (on SBCL only),
+@file{$XDG_DATA_HOME/common-lisp/systems/} (no recursion, link farm)
+@file{$XDG_DATA_HOME/common-lisp/source/}.
+The @code{XDG_DATA_HOME} directory defaults to @file{~/.local/share/}.
+On Windows, the @code{local-appdata} and @code{appdata} directories are used instead.
+
+@item
+The source registry will be configured from
 system configuration file
 @file{/etc/common-lisp/source-registry.conf}
-if it exists/
+if it exists.
 
 @item
@@ -2656 +2929 @@
 (at the time that the configuration is initialized) as well as
 @code{:directory} entries for @file{$XDG_DATA_DIRS/common-lisp/systems/} and
-@code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/}.
-For instance, SBCL will include directories for its contribs
-when it can find them; it will look for them where SBCL was installed,
-or at the location specified by the @code{SBCL_HOME} environment variable.
+@code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/},
+where @code{XDG_DATA_DIRS} defaults to @file{/usr/local/share} and @file{/usr/share} on Unix,
+and the @code{common-appdata} directory on Windows.
+
+@item
+The source registry may include implementation-dependent directories
+that correspond to implementation-provided extensions.
 
 @end enumerate
@@ -2676 +2952 @@
 in configuration files, no matter if the last one inherits or not.
 
-
+@node Truenames and other dangers, XDG base directory, Configurations, Controlling where ASDF searches for systems
 @section Truenames and other dangers
 
@@ -2699 +2975 @@
 ``True Names... and Other Dangers'' then you're in for a treat.
 
-
+@node XDG base directory, Backward Compatibility, Truenames and other dangers, Controlling where ASDF searches for systems
 @section XDG base directory
 
@@ -2721 +2997 @@
 ASDF 3 relies on the environment variables that Windows usually exports.
 
+@node Backward Compatibility, Configuration DSL, XDG base directory, Controlling where ASDF searches for systems
 @section Backward Compatibility
 
 For backward compatibility as well as to provide a practical backdoor for hackers,
-ASDF will first search for @code{.asd} files in the directories specified in
+ASDF will first search for @file{.asd} files in the directories specified in
 @code{asdf:*central-registry*}
 before it searches in the source registry above.
@@ -2735 +3012 @@
 but will take precedence over the new mechanism if you do use it.
 
+@node Configuration DSL, Configuration Directories, Backward Compatibility, Controlling where ASDF searches for systems
 @section Configuration DSL
 @cindex :inherit-configuration source config directive
@@ -2759 +3037 @@
 
 @example
-;; A configuration is a single SEXP starting with keyword :source-registry
-;; followed by a list of directives.
+;; A configuration is a single SEXP starting with the keyword
+;; :source-registry followed by a list of directives.
 CONFIGURATION := (:source-registry DIRECTIVE ...)
 
@@ -2767 +3045 @@
     ;; INHERITANCE DIRECTIVE:
     ;; Your configuration expression MUST contain
-    ;; exactly one of either of these:
-    :inherit-configuration | ; splices inherited configuration (often specified last)
-    :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
+    ;; exactly one of the following:
+    :inherit-configuration |
+    ;; splices inherited configuration (often specified last) or
+    :ignore-inherited-configuration |
+    ;; drop inherited configuration (specified anywhere)
 
     ;; forward compatibility directive (since ASDF 2.011.4), useful when
-    ;; you want to use new configuration features but have to bootstrap a
-    ;; the newer required ASDF from an older release that doesn't sport said features:
-    :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
+    ;; you want to use new configuration features but have to bootstrap
+    ;; the newer required ASDF from an older release that doesn't
+    ;; support said features:
+    :ignore-invalid-entries |
 
     ;; add a single directory to be scanned (no recursion)
     (:directory DIRECTORY-PATHNAME-DESIGNATOR) |
 
-    ;; add a directory hierarchy, recursing but excluding specified patterns
+    ;; add a directory hierarchy, recursing but
+    ;; excluding specified patterns
     (:tree DIRECTORY-PATHNAME-DESIGNATOR) |
 
@@ -2795 +3077 @@
     :default-registry
 
-REGULAR-FILE-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a file
-DIRECTORY-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a directory name
+REGULAR-FILE-PATHNAME-DESIGNATOR
+    := PATHNAME-DESIGNATOR ; interpreted as a file
+DIRECTORY-PATHNAME-DESIGNATOR
+    := PATHNAME-DESIGNATOR ; interpreted as a directory
 
 PATHNAME-DESIGNATOR :=
@@ -2802 +3086 @@
     ABSOLUTE-COMPONENT-DESIGNATOR ;; see pathname DSL
 
-EXCLUSION-PATTERN := a string without wildcards, that will be matched exactly
-  against the name of a any subdirectory in the directory component
-        of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"}
+EXCLUSION-PATTERN := a string without wildcards, that will be matched
+    exactly against the name of a any subdirectory in the directory
+    component of a path. e.g. @code{"_darcs"} will match
+    @file{#p"/foo/bar/_darcs/src/bar.asd"}
 @end example
 
@@ -2815 +3100 @@
 ABSOLUTE-COMPONENT-DESIGNATOR :=
     (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
-    STRING | ;; namestring (better be absolute or bust, directory assumed where applicable).
-             ;; In output-translations, directory is assumed and **/*.*.* added if it's last.
-             ;; On MCL, a MacOSX-style POSIX namestring (for MacOS9 style, use #p"...");
-             ;; Note that none of the above applies to strings used in *central-registry*,
-             ;; which doesn't use this DSL: they are processed as normal namestrings.
-             ;; however, you can compute what you put in the *central-registry*
-             ;; based on the results of say (asdf::resolve-location "/Users/fare/cl/cl-foo/")
-    PATHNAME | ;; pathname (better be an absolute path, or bust)
-               ;; In output-translations, unless followed by relative components,
-               ;; it better have appropriate wildcards, as in **/*.*.*
-    :HOME | ;; designates the user-homedir-pathname ~/
-    :USER-CACHE | ;; designates the default location for the user cache
-    :HERE | ;; designates the location of the configuration file
-            ;; (or *default-pathname-defaults*, if invoked interactively)
-    :ROOT ;; magic, for output-translations source only: paths that are relative
-          ;; to the root of the source host and device
-    ;; Not valid anymore: :SYSTEM-CACHE (was a security hazard)
+    STRING |
+    ;; namestring (better be absolute or bust, directory assumed where
+    ;; applicable).  In output-translations, directory is assumed and
+    ;; **/*.*.* added if it's last.  On MCL, a MacOSX-style POSIX
+    ;; namestring (for MacOS9 style, use #p"..."); Note that none of the
+    ;; above applies to strings used in *central-registry*, which
+    ;; doesn't use this DSL: they are processed as normal namestrings.
+    ;; however, you can compute what you put in the *central-registry*
+    ;; based on the results of say
+    ;; (asdf::resolve-location "/Users/fare/cl/cl-foo/")
+    PATHNAME |
+    ;; pathname (better be an absolute path, or bust)
+    ;; In output-translations, unless followed by relative components,
+    ;; it better have appropriate wildcards, as in **/*.*.*
+    :HOME | ; designates the user-homedir-pathname ~/
+    :USER-CACHE | ; designates the default location for the user cache
+    :HERE |
+    ;; designates the location of the configuration file
+    ;; (or *default-pathname-defaults*, if invoked interactively)
+    :ROOT
+    ;; magic, for output-translations source only: paths that are relative
+    ;; to the root of the source host and device
+
+They keyword :SYSTEM-CACHE is not accepted in ASDF 3.1 and beyond: it
+was a security hazard.
 
 RELATIVE-COMPONENT-DESIGNATOR :=
     (RELATIVE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
-    STRING | ;; relative directory pathname as interpreted by parse-unix-namestring.
-             ;; In output translations, if last component, **/*.*.* is added
-    PATHNAME | ;; pathname; unless last component, directory is assumed.
-    :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
-    :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
-    :DEFAULT-DIRECTORY | ;; a relativized version of the default directory
+    STRING |
+      ;; relative directory pathname as interpreted by
+      ;; parse-unix-namestring.
+      ;; In output translations, if last component, **/*.*.* is added
+    PATHNAME | ; pathname; unless last component, directory is assumed.
+    :IMPLEMENTATION |
+       ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
+    :IMPLEMENTATION-TYPE |
+       ;; a directory based on lisp-implementation-type only, e.g. sbcl
+    :DEFAULT-DIRECTORY |
+       ;; a relativized version of the default directory
     :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
     :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
     :*.*.* | ;; any file (since ASDF 2.011.4)
-    ;; Not supported (anymore): :UID and :USERNAME
+
+The keywords :UID and :USERNAME are no longer supported.
 @end example
 
@@ -2855 +3154 @@
 @end example
 
+@node Configuration Directories, Shell-friendly syntax for configuration, Configuration DSL, Controlling where ASDF searches for systems
 @section Configuration Directories
 
@@ -2864 +3164 @@
 at the @emph{end} of the list.
 
-This allows for packaging software that has file granularity
-(e.g. Debian's @code{dpkg} or some future version of @code{clbuild})
-to easily include configuration information about distributed software.
+System-wide or per-user Common Lisp software distributions
+such as Debian packages or some future version of @code{clbuild}
+may then include files such as
+@file{/etc/common-lisp/source-registry.conf.d/10-foo.conf} or
+@file{~/.config/common-lisp/source-registry.conf.d/10-foo.conf}
+to easily and modularly register configuration information
+about software being distributed.
 
 The convention is that, for sorting purposes,
 the names of files in such a directory begin with two digits
 that determine the order in which these entries will be read.
-Also, the type of these files is conventionally @code{"conf"}
-and as a limitation to some implementations (e.g. GNU clisp),
-the type cannot be @code{nil}.
+Also, the type of these files must be @file{.conf},
+which not only simplifies the implementation by allowing
+for more portable techniques in finding those files,
+but also makes it trivial to disable a file, by renaming it to a different file type.
 
 Directories may be included by specifying a directory pathname
@@ -2891 +3196 @@
 @end example
 
+@menu
+* The here directive::
+@end menu
+
+@node The here directive,  , Configuration Directories, Configuration Directories
 @subsection The :here directive
 
@@ -2908 +3218 @@
 like this:
 @example
-   (:tree  "path/to/dir")
+   (:tree "path/to/dir")
 @end example
 But what if X knows that there are very large subtrees
@@ -2936 +3246 @@
 directory according to X's (relative) instructions.
 
+@node Shell-friendly syntax for configuration, Search Algorithm, Configuration Directories, Controlling where ASDF searches for systems
 @section Shell-friendly syntax for configuration
 
@@ -2959 +3270 @@
     spliced there.
 
-
+@node Search Algorithm, Caching Results, Shell-friendly syntax for configuration, Controlling where ASDF searches for systems
 @section Search Algorithm
 @vindex *default-source-registry-exclusions*
@@ -2995 +3306 @@
 
 
+@node Caching Results, Configuration API, Search Algorithm, Controlling where ASDF searches for systems
 @section Caching Results
 
@@ -3002 +3314 @@
 To explicitly flush any information cached by the system, use the API below.
 
-
+@node Configuration API, Introspection, Caching Results, Controlling where ASDF searches for systems
 @section Configuration API
 
@@ -3009 +3321 @@
 and for XCVB the corresponding functions are in package XCVB.
 
-@defun initialize-source-registry @Aoptional PARAMETER
+@defun initialize-source-registry @Aoptional{} PARAMETER
    will read the configuration and initialize all internal variables.
    You may extend or override configuration
@@ -3034 +3346 @@
 @end defun
 
-@defun ensure-source-registry @Aoptional PARAMETER
+@defun ensure-source-registry @Aoptional{} PARAMETER
    checks whether a source registry has been initialized.
    If not, initialize it with the given @var{PARAMETER}.
@@ -3048 +3360 @@
 which will cause the initialization to happen next time around.
 
+@node Introspection, Status, Configuration API, Controlling where ASDF searches for systems
 @section Introspection
 
+@menu
+* *source-registry-parameter* variable::
+* Information about system dependencies::
+@end menu
+
+@node *source-registry-parameter* variable, Information about system dependencies, Introspection, Introspection
 @subsection *source-registry-parameter* variable
 @vindex *source-registry-parameter*
@@ -3060 +3379 @@
 read-only.
 
+@node Information about system dependencies,  , *source-registry-parameter* variable, Introspection
 @subsection Information about system dependencies
 
@@ -3083 +3403 @@
 @end defun
 
+@node Status, Rejected ideas, Introspection, Controlling where ASDF searches for systems
 @section Status
 
@@ -3092 +3413 @@
 that everyone uses implicitly.
 
-
+@node Rejected ideas, TODO, Status, Controlling where ASDF searches for systems
 @section Rejected ideas
 
-Alternatives I considered and rejected included:
+Alternatives I (FRR) considered and rejected while developing ASDF 2 included:
 
 @enumerate
@@ -3104 +3425 @@
    and leaves little space of future cleanups and extensions.
 
-@item Keep @code{asdf:*central-registry*} remains the master but extend its semantics
+@item Keep @code{asdf:*central-registry*} as the master but extend its semantics
    in completely new ways, so that new kinds of entries may be implemented
    as a recursive search, etc. This seems somewhat backwards.
@@ -3146 +3467 @@
 @end itemize
 
+@node TODO, Credits for the source-registry, Rejected ideas, Controlling where ASDF searches for systems
 @section TODO
 
@@ -3152 +3474 @@
 @end itemize
 
-
+@node Credits for the source-registry,  , TODO, Controlling where ASDF searches for systems
 @section Credits for the source-registry
 
@@ -3173 +3495 @@
 
 Each Common Lisp implementation has its own format
-for compiled files (fasls for short, short for ``fast loading'').
+for compiled files or fasls.@footnote{``FASL'' is short for ``FASt Loading.''}
 If you use multiple implementations
 (or multiple versions of the same implementation),
 you'll soon find your source directories
-littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so on.
-Worse yet, some implementations use the same file extension
-while changing formats from version to version (or platform to platform)
-which means that you'll have to recompile binaries
+littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so
+on.
+Worse yet, multiple implementations use the same file extension and
+some implementations maintain the same file extension
+while changing formats from version to version (or platform to
+platform).
+This can lead to many errors and much confusion
 as you switch from one implementation to the next.
 
@@ -3186 +3511 @@
 to mitigate the problem.
 
+@menu
+* Output Configurations::
+* Output Backward Compatibility::
+* Output Configuration DSL::
+* Output Configuration Directories::
+* Output Shell-friendly syntax for configuration::
+* Semantics of Output Translations::
+* Output Caching Results::
+* Output location API::
+* Credits for output translations::
+@end menu
+
+@node Output Configurations, Output Backward Compatibility, Controlling where ASDF saves compiled files, Controlling where ASDF saves compiled files
 @section Configurations
+
+@c FIXME: Explain how configurations work: can't expect reader will have
+@c looked at previous chapter. Probably cut and paste will do.
+
 
 Configurations specify mappings from input locations to output locations.
@@ -3242 +3584 @@
 
 Each of these configurations is specified as a SEXP
-in a trival domain-specific language (defined below).
+in a trivial domain-specific language (@pxref{Configuration DSL}).
 Additionally, a more shell-friendly syntax is available
-for the environment variable (defined yet below).
-
-Each of these configurations is only used if the previous
-configuration explicitly or implicitly specifies that it
+for the environment variable (@pxref{Shell-friendly syntax for configuration}).
+
+When processing an entry in the above list of configuration methods,
+ASDF will stop unless that entry
+explicitly or implicitly specifies that it
 includes its inherited configuration.
 
@@ -3255 +3598 @@
 when they browse source code,
 at the expense of taking a small toll when developers have to clean up
-output files and find they need to get familiar with output-translations first.
-
-
+output files and find they need to get familiar with output-translations
+first.@footnote{A @code{CLEAN-OP} would be a partial solution to this problem.}
+
+
+@node Output Backward Compatibility, Output Configuration DSL, Output Configurations, Controlling where ASDF saves compiled files
 @section Backward Compatibility
 @cindex ASDF-BINARY-LOCATIONS compatibility
-
-
-We purposefully do NOT provide backward compatibility with earlier versions of
+@c FIXME: Demote this section -- the typical reader doesn't care about
+@c backwards compatibility.
+
+
+We purposely do @emph{not} provide backward compatibility with earlier versions of
 @code{ASDF-Binary-Locations} (8 Sept 2009),
 @code{common-lisp-controller} (7.0) or
 @code{cl-launch} (2.35),
 each of which had similar general capabilities.
-The previous APIs of these programs were not designed
-for configuration by the end-user
-in an easy way with configuration files.
-Recent versions of same packages use
-the new @code{asdf-output-translations} API as defined below:
-@code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000).
+The APIs of these programs were not designed
+for easy user configuration
+through configuration files.
+Recent versions of @code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000)
+use the new @code{asdf-output-translations} API as defined below.
 @code{ASDF-Binary-Locations} is fully superseded and not to be used anymore.
 
@@ -3288 +3634 @@
 we provide a limited emulation mode:
 
-@defun enable-asdf-binary-locations-compatibility @Akey centralize-lisp-binaries default-toplevel-directory include-per-user-information map-all-source-files source-to-target-mappings
+@defun enable-asdf-binary-locations-compatibility @Akey{} centralize-lisp-binaries default-toplevel-directory include-per-user-information map-all-source-files source-to-target-mappings
 This function will initialize the new @code{asdf-output-translations} facility in a way
 that emulates the behavior of the old @code{ASDF-Binary-Locations} facility.
@@ -3312 +3658 @@
 To disable it, use @code{(asdf:disable-output-translations)}.
 
-
+@node Output Configuration DSL, Output Configuration Directories, Output Backward Compatibility, Controlling where ASDF saves compiled files
 @section Configuration DSL
 
@@ -3328 +3674 @@
     ;; Your configuration expression MUST contain
     ;; exactly one of either of these:
-    :inherit-configuration | ; splices inherited configuration (often specified last)
-    :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
+    :inherit-configuration |
+      ;; splices inherited configuration (often specified last)
+    :ignore-inherited-configuration |
+      ;; drop inherited configuration (specified anywhere)
 
     ;; forward compatibility directive (since ASDF 2.011.4), useful when
     ;; you want to use new configuration features but have to bootstrap a
-    ;; the newer required ASDF from an older release that doesn't sport said features:
-    :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
+    ;; the newer required ASDF from an older release that doesn't have
+    ;; said features:
+    :ignore-invalid-entries |
 
     ;; include a configuration file or directory
     (:include PATHNAME-DESIGNATOR) |
 
-    ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/ or something.
+    ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/
+    ;; or something.
     :enable-user-cache |
     ;; Disable global cache. Map / to /
@@ -3351 +3701 @@
 
 DIRECTORY-DESIGNATOR :=
-    NIL | ;; As source: skip this entry. As destination: same as source
-    T | ;; as source matches anything, as destination leaves pathname unmapped.
-    ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language
+    NIL | ; As source: skip this entry. As destination: same as source
+    T | ; as source matches anything, as destination
+        ; maps pathname to itself.
+    ABSOLUTE-COMPONENT-DESIGNATOR ; same as in the source-registry language
 
 TRANSLATION-FUNCTION :=
-    SYMBOL | ;; symbol of a function that takes two arguments,
-             ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
-    LAMBDA   ;; A form which evalutates to a function taking two arguments consisting of
-             ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
+    SYMBOL | ;; symbol naming a function that takes two arguments:
+             ;; the pathname to be translated and the matching
+             ;; DIRECTORY-DESIGNATOR
+    LAMBDA   ;; A form which evalutates to a function taking two arguments:
+             ;; the pathname to be translated and the matching
+             ;; DIRECTORY-DESIGNATOR
 
 @end verbatim
@@ -3366 +3719 @@
 or subdirectories of the path before them, or bust.
 
+@c FIXME: the following assumes that the reader is familiar with the use
+@c of this pattern in logical pathnames, which may not be a reasonable
+@c assumption.  Expand.
 The last component, if not a pathname, is notionally completed by @file{/**/*.*}.
 You can specify more fine-grained patterns
@@ -3397 +3753 @@
 with @code{:centralize-lisp-binaries nil}
 which will do the same thing internally for you:
-@verbatim
-  #.(let ((wild-subdir (make-pathname :directory '(:relative :wild-inferiors)))
-          (wild-file (make-pathname :name :wild :version :wild :type :wild)))
-     `((:root ,wild-subdir ,wild-file) ;; Or using the implicit wildcard, just :root
-       (:root ,wild-subdir :implementation ,wild-file)))
-@end verbatim
+@lisp
+#.(let ((wild-subdir
+          (make-pathname :directory '(:relative :wild-inferiors)))
+        (wild-file
+          (make-pathname :name :wild :version :wild :type :wild)))
+   `((:root ,wild-subdir ,wild-file)
+     (:root ,wild-subdir :implementation ,wild-file)))
+@end lisp
 Starting with ASDF 2.011.4, you can use the simpler:
   @code{`(:root (:root :**/ :implementation :*.*.*))}
@@ -3421 +3779 @@
 the first being the pathname of the source file,
 the second being the wildcard that was matched.
-The result of the function invocation should be the translated pathname.
-
-An @code{:inherit-configuration} statement cause the search to recurse with the path
-specifications from the next configuration.
+When invoked, the function should return the translated pathname.
+
+An @code{:inherit-configuration} statement causes the search to recurse with the path
+specifications from the next configuration in the bulleted list.
 @xref{Controlling where ASDF saves compiled files,,Configurations}, above.
 
+@vindex @code{asdf::*user-cache*}
 @itemize
 @item
@@ -3439 +3798 @@
 
 
+@node Output Configuration Directories, Output Shell-friendly syntax for configuration, Output Configuration DSL, Controlling where ASDF saves compiled files
 @section Configuration Directories
 
-Configuration directories consist in files each contains
+Configuration directories consist of files, each of which contains
 a list of directives without any enclosing
 @code{(:output-translations ...)} form.
@@ -3449 +3809 @@
 at the @emph{end} of the list.
 
-This allows for packaging software that has file granularity
-(e.g. Debian's @command{dpkg} or some future version of @command{clbuild})
-to easily include configuration information about software being distributed.
+System-wide or per-user Common Lisp software distributions
+such as Debian packages or some future version of @code{clbuild}
+may then include files such as
+@file{/etc/common-lisp/asdf-output-translations.conf.d/10-foo.conf} or
+@file{~/.config/common-lisp/asdf-output-translations.conf.d/10-foo.conf}
+to easily and modularly register configuration information
+about software being distributed.
 
 The convention is that, for sorting purposes,
 the names of files in such a directory begin with two digits
 that determine the order in which these entries will be read.
-Also, the type of these files is conventionally @code{"conf"}
-and as a limitation of some implementations, the type cannot be @code{nil}.
+Also, the type of these files must be @file{.conf},
+which not only simplifies the implementation by allowing
+for more portable techniques in finding those files,
+but also makes it trivial to disable a file, by renaming it to a different file type.
 
 Directories may be included by specifying a directory pathname
 or namestring in an @code{:include} directive, e.g.:
+
 @verbatim
   (:include "/foo/bar/")
 @end verbatim
 
+@node Output Shell-friendly syntax for configuration, Semantics of Output Translations, Output Configuration Directories, Controlling where ASDF saves compiled files
 @section Shell-friendly syntax for configuration
 
 When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS}
-ASDF will skip to next configuration if it's an empty string.
+ASDF will skip to the next configuration if it's an empty string.
 It will @code{READ} the string as an SEXP in the DSL
 if it begins with a paren @code{(}
@@ -3483 +3851 @@
 it indicates that the directory specified first is to be left untranslated
 (which has the same effect as if the directory had been repeated).
-
-
+Thus @code{"/foo:/bar::/baz:"} means that
+things under directory @file{/foo/}
+are translated to be under @file{/bar/},
+then include the inherited configuration,
+then specify that things under directory @file{/baz/} are not translated.
+
+@node Semantics of Output Translations, Output Caching Results, Output Shell-friendly syntax for configuration, Controlling where ASDF saves compiled files
 @section Semantics of Output Translations
 
@@ -3514 +3887 @@
 with same fall-through semantics).
 
+@node Output Caching Results, Output location API, Semantics of Output Translations, Controlling where ASDF saves compiled files
 @section Caching Results
 
@@ -3522 +3896 @@
 
 
+@node Output location API, Credits for output translations, Output Caching Results, Controlling where ASDF saves compiled files
 @section Output location API
 
 The specified functions are exported from package ASDF.
 
-@defun initialize-output-translations @Aoptional PARAMETER
+@defun initialize-output-translations @Aoptional{} PARAMETER
    will read the configuration and initialize all internal variables.
    You may extend or override configuration
@@ -3557 +3932 @@
 @end defun
 
-@defun ensure-output-translations @Aoptional PARAMETER
+@defun ensure-output-translations @Aoptional{} PARAMETER
    checks whether output translations have been initialized.
    If not, initialize them with the given @var{PARAMETER}.
@@ -3578 +3953 @@
 
 
+@node Credits for output translations,  , Output location API, Controlling where ASDF saves compiled files
 @section Credits for output translations
 
-Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations},
-and to Peter van Eynde for @code{Common Lisp Controller}.
+Thanks a lot to Peter van Eynde for @code{Common Lisp Controller}
+and to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations}.
 
 All bad design ideas and implementation bugs are to mine, not theirs.
@@ -3648 +4024 @@
 useful for system definition and development.
 
+@menu
+* Controlling file compilation::
+* Controlling source file character encoding::
+* Some Utility Functions::
+@end menu
+
+@node Controlling file compilation, Controlling source file character encoding, Miscellaneous additional functionality, Miscellaneous additional functionality
 @section Controlling file compilation
 @cindex :around-compile
@@ -3655 +4038 @@
 @findex compile-file*
 
+@c FIXME: Needs rewrite.  Start with motivation -- why are we doing
+@c this?  (there is some, but it's buried).  Also, all of a sudden in
+@c the middle of the discussion we start talking about a "hook," which
+@c is confusing.
+
 When declaring a component (system, module, file),
 you can specify a keyword argument @code{:around-compile function}.
@@ -3662 +4050 @@
 if no value is specified in any transitive parent.
 
-The argument must be a either @code{nil}, a fbound symbol,
+The argument must be either @code{nil}, an fbound symbol,
 a lambda-expression (e.g. @code{(lambda (thunk) ...(funcall thunk ...) ...)})
 a function object (e.g. using @code{#.#'} but that's discouraged
@@ -3720 +4108 @@
 
 
+@node Controlling source file character encoding, Some Utility Functions, Controlling file compilation, Miscellaneous additional functionality
 @section Controlling source file character encoding
 
@@ -3728 +4117 @@
 from the parent module or system;
 if no encoding is specified at any point,
-the default @code{:autodetect} is assumed.
-By default, only @code{:default}, @code{:utf-8}
-and @code{:autodetect} are accepted.
-@code{:autodetect}, the default, calls
-@code{*encoding-detection-hook*} which by default always returns
-@code{*default-encoding*} which itself defaults to @code{:default}.
+or if @code{nil} is explicitly specified,
+an extensible protocol described below is followed,
+that ultimately defaults to @code{:utf-8} since ASDF 3.
+
+The protocol to determine the encoding is
+to call the function @code{detect-encoding},
+which itself, if provided a valid file,
+calls the function specified by @var{*encoding-detection-hook*},
+or else defaults to the @var{*default-encoding*}.
+The @var{*encoding-detection-hook*} is by default bound
+to function @code{always-default-encoding},
+that always returns the contents of @var{*default-encoding*}.
+@var{*default-encoding*} is bound to @code{:utf-8} by default
+(before ASDF 3, the default was @code{:default}).
+
+Whichever encoding is returned must be a portable keyword,
+that will be translated to an implementation-specific external-format designator
+by function @code{encoding-external-format},
+which itself simply calls the function specified @var{*encoding-external-format-hook*};
+that function by default is @code{default-encoding-external-format},
+that only recognizes @code{:utf-8} and @code{:default},
+and translates the former to the implementation-dependent @var{*utf-8-external-format*},
+and the latter to itself (that itself is portable but has an implementation-dependent meaning).
 
 In other words, there now are plenty of extension hooks, but
-by default ASDF follows the backwards compatible behavior
-of using whichever @code{:default} encoding your implementation uses,
-which itself may or may not vary based on environment variables
-and other locale settings.
-In practice this means that only source code that only uses ASCII
-is guaranteed to be read the same on all implementations
-independently from any user setting.
-
-Additionally, for backward-compatibility with older versions of ASDF
-and/or with implementations that do not support unicode and its many encodings,
-you may want to use
-the reader conditionals @code{#+asdf-unicode #+asdf-unicode}
-to protect any @code{:encoding @emph{encoding}} statement
-as @code{:asdf-unicode} will be present in @code{*features*}
-only if you're using a recent ASDF
-on an implementation that supports unicode.
+by default ASDF enforces the previous @emph{de facto} standard behavior
+of using @code{:utf-8}, independently from
+whatever configuration the user may be using.
+Thus, system authors can now rely on @code{:utf-8}
+being used while compiling their files,
+even if the user is currently using @code{:koi8-r} or @code{:euc-jp}
+as their interactive encoding.
+(Before ASDF 3, there was no such guarantee, @code{:default} was used,
+and only plain ASCII was safe to include in source code.)
+
+Some legacy implementations only support 8-bit characters,
+and some implementations provide 8-bit only variants.
+On these implementations, the @var{*utf-8-external-format*}
+gracefully falls back to @code{:default},
+and Unicode characters will be read as multi-character mojibake.
+To detect such situations, UIOP will push the @code{:asdf-unicode} feature
+on implementations that support Unicode, and you can use reader-conditionalization
+to protect any @code{:encoding @emph{encoding}} statement, as in
+@code{#+asdf-unicode :encoding #+asdf-unicode :utf-8}.
 We recommend that you avoid using unprotected @code{:encoding} specifications
-until after ASDF 2.21 or later becomes widespread, hopefully by the end of 2012.
+until after ASDF 2.21 or later becomes widespread
+(in April 2014, only LispWorks lags with ASDF 2.019,
+and is scheduled to be updated later this year).
 
 While it offers plenty of hooks for extension,
-and one such extension is being developed (see below),
+and one such extension is available (see @code{asdf-encodings} below),
 ASDF itself only recognizes one encoding beside @code{:default},
 and that is @code{:utf-8}, which is the @emph{de facto} standard,
@@ -3777 +4188 @@
 We invite you to embrace UTF-8
 as the encoding for non-ASCII characters starting today,
-even without any explicit specification in your @code{.asd} files.
+even without any explicit specification in your @file{.asd} files.
 Indeed, on some implementations and configurations,
 UTF-8 is already the @code{:default},
@@ -3786 +4197 @@
 (provided you do @emph{not} use a BOM),
 although it might be read incorrectly on some implementations.
-In the future, we intend to make @code{:utf-8}
-the default value of @code{*default-encoding*},
-to be enforced everywhere, so at least the code is guaranteed
-to be read correctly everywhere it can be.
+@code{:utf-8} has been the default value of @code{*default-encoding*} since ASDF 3.
 
 If you need non-standard character encodings for your source code,
@@ -3797 +4205 @@
 @code{*encoding-external-format-hook*} facility,
 so you can explicitly specify @code{:encoding :latin1}
-in your @code{.asd} file.
+in your @file{.asd} file.
 Using the @code{*encoding-detection-hook*} it will also
 eventually implement some autodetection of a file's encoding
 from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration,
 or otherwise based on an analysis of octet patterns in the file.
-At this point, asdf-encoding only supports the encodings
+At this point, @code{asdf-encoding} only supports the encodings
 that are supported as part of your implementation.
 Since the list varies depending on implementations,
-we once again recommend you use @code{:utf-8} everywhere,
-which is the most portable (next is @code{:latin1}).
-
-If you're not using a version of Quicklisp that has it,
-you may get the source for @code{asdf-encodings} using git:
+we still recommend you use @code{:utf-8} everywhere,
+which is the most portable (next to it is @code{:latin1}).
+
+Recent versions of Quicklisp include @code{asdf-encodings};
+if you're not using it, you may get this extension using git:
 @kbd{git clone git://common-lisp.net/projects/asdf/asdf-encodings.git}
 or
@@ -3816 +4224 @@
 @url{http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git}.
 
-In the future, we intend to change the default @code{*default-encoding*}
-to @code{:utf-8}, which is already the de facto standard
-for most libraries that use non-ASCII characters:
-utf-8 works everywhere and was backhandedly enforced by
-a lot of people using SBCL and utf-8 and sending reports to authors
-so they make their packages compatible.
-A survey showed only about a handful few libraries
-are incompatible with non-UTF-8, and then, only in comments,
-and we believe that authors will adopt UTF-8 when prompted.
-See the April 2012 discussion on the asdf-devel mailing-list.
-For backwards compatibility with users who insist on a non-UTF-8 encoding,
-but cannot immediately transition to using @code{asdf-encodings}
-(maybe because it isn't ready), it will still be possible to use
-the @code{:encoding :default} option in your @code{defsystem} form
-to restore the behavior of ASDF 2.20 and earlier.
-This shouldn't be required in libraries,
-because user pressure as mentioned above will already have pushed
-library authors towards using UTF-8;
-but authors of end-user programs might care.
-
-When you use @code{asdf-encodings}, any further loaded @code{.asd} file
-will use the autodetection algorithm to determine its encoding;
-yet if you depend on this detection happening,
-you may want to explicitly load @code{asdf-encodings} early in your build,
-for by the time you can use @code{:defsystem-depends-on},
-it is already too late to load it.
+When you use @code{asdf-encodings},
+any @file{.asd} file loaded
+will use the autodetection algorithm to determine its encoding.
+If you depend on this detection happening,
+you should explicitly load @code{asdf-encodings} early in your build.
+Note that @code{:defsystem-depends-on} cannot be used here: by the time
+the @code{:defsystem-depends-on} is loaded, the enclosing
+@code{defsystem} form has already been read.
+
 In practice, this means that the @code{*default-encoding*}
-is usually used for @code{.asd} files.
-Currently, this defaults to @code{:default} for backwards compatibility,
-and that means that you shouldn't rely on non-ASCII characters in a .asd file.
-Since component (path)names are the only real data in these files,
-and non-ASCII characters are not very portable for file names,
-this isn't too much of an issue.
-We still encourage you to use either plain ASCII or UTF-8
-in @code{.asd} files,
-as we intend to make @code{:utf-8} the default encoding in the future.
+is usually used for @file{.asd} files.
+Currently, this defaults to @code{:utf-8}, and
+you should be safe using Unicode characters in those files.
 This might matter, for instance, in meta-data about author's names.
-
+Otherwise, the main data in these files is component (path)names,
+and we don't recommend using non-ASCII characters for these,
+for the result probably isn't very portable.
 
 @section Miscellaneous Functions
@@ -3860 +4247 @@
 
 @anchor{system-relative-pathname}
-@defun system-relative-pathname system name @Akey type
+@defun system-relative-pathname system name @Akey{} type
 
 It's often handy to locate a file relative to some system.
@@ -3894 +4281 @@
 
 It is sometimes useful to force recompilation of a previously loaded system.
-In these cases, it may be useful to @code{(asdf:clear-system :foo)}
-to remove the system from the table of currently loaded systems;
+For these cases, @code{(asdf:clear-system :foo)}
+will remove the system from the table of currently loaded systems:
 the next time the system @code{foo} or one that depends on it is re-loaded,
-@code{foo} will then be loaded again.
-Alternatively, you could touch @code{foo.asd} or
-remove the corresponding fasls from the output file cache.
-(It was once conceived that one should provide
-a list of systems the recompilation of which to force
-as the @code{:force} keyword argument to @code{load-system};
-but this has never worked, and though the feature was fixed in ASDF 2.000,
-it remains @code{cerror}'ed out as nobody ever used it.)
-
-Note that this does not and cannot by itself undo the previous loading
-of the system. Common Lisp has no provision for such an operation,
-and its reliance on irreversible side-effects to global datastructures
+@code{foo} will be loaded again.@footnote{Alternatively, you could touch @code{foo.asd} or
+remove the corresponding fasls from the output file cache.}
+
+Note that this does not and cannot undo
+the previous loading of the system.
+Common Lisp has no provision for such an operation,
+and its reliance on irreversible side-effects to global data structures
 makes such a thing impossible in the general case.
 If the software being re-loaded is not conceived with hot upgrade in mind,
-this re-loading may cause many errors, warnings or subtle silent problems,
+re-loading may cause many errors, warnings or subtle silent problems,
 as packages, generic function signatures, structures, types, macros, constants, etc.
 are being redefined incompatibly.
@@ -3918 +4300 @@
 unregistering symbols, defining methods on @code{update-instance-for-redefined-class}
 and much more are necessary for reloading to happen smoothly.
-ASDF itself goes through notable pains to make such a hot upgrade possible
-with respect to its own code, and what it does is ridiculously complex;
-look at the beginning of @file{asdf.lisp} to see what it does.
+ASDF itself goes to extensive effort to make a hot upgrade possible
+with respect to its own code.
+If you want, you can reuse some of its utilities such as
+@code{uiop:define-package} and @code{uiop:with-upgradability},
+and get inspiration (or disinspiration)
+from what it does in @file{header.lisp} and @file{upgrade.lisp}.
 @end defun
 
-@defun register-preloaded-system name @Arest keys
+@defun register-preloaded-system name @Arest{} keys
 A system with name @var{name},
 created by @code{make-instance} with extra keys @var{keys}
@@ -3934 +4319 @@
 
 This function is particularly useful if you distribute your code
-as fasls with either @code{fasl-op} or @code{monolithic-fasl-op},
+as fasls with either @code{compile-bundle-op} or @code{monolithic-compile-bundle-op},
 and want to register systems so that dependencies will work uniformly
 whether you're using your software from source or from fasl.
 @end defun
 
-@defun run-shell-command control-string @Arest args
+@defun run-shell-command control-string @Arest{} args
 
 This function is obsolete and present only for the sake of backwards-compatibility:
@@ -3960 +4345 @@
 @end defun
 
+@node Some Utility Functions,  , Controlling source file character encoding, Miscellaneous additional functionality
 @section Some Utility Functions
 
@@ -3969 +4355 @@
 
 
-@defun parse-unix-namestring name @Akey type defaults dot-dot ensure-directory @AallowOtherKeys
+@defun parse-unix-namestring name @Akey{} type defaults dot-dot ensure-directory @AallowOtherKeys
 Coerce NAME into a PATHNAME using standard Unix syntax.
 
 Unix syntax is used whether or not the underlying system is Unix;
-on such non-Unix systems it is only usable but for relative pathnames;
-but especially to manipulate relative pathnames portably, it is of crucial
+on non-Unix systems it is only usable for relative pathnames.
+In order to manipulate relative pathnames portably, it is crucial
 to possess a portable pathname syntax independent of the underlying OS.
 This is what @code{parse-unix-namestring} provides, and why we use it in ASDF.
@@ -3997 +4383 @@
 which must be one of @code{:back} or @code{:up} and defaults to @code{:back}.
 
+@vindex *nil-pathname*
 @code{host}, @code{device} and @code{version} components are taken from @var{defaults},
-which itself defaults to @code{*nil-pathname*}, also used if @var{defaults} is @code{nil}.
+which itself defaults to @code{*nil-pathname*}.
+@code{*nil-pathname*} is also used if @var{defaults} is @code{nil}.
 No host or device can be specified in the string itself,
 which makes it unsuitable for absolute pathnames outside Unix.
@@ -4010 +4398 @@
 When you're manipulating pathnames that are supposed to make sense portably
 even though the OS may not be Unixish, we recommend you use @code{:want-relative t}
-to throw an error if the pathname is absolute
+so that @code{parse-unix-namestring} will throw an error if the pathname is absolute.
 @end defun
 
-@defun merge-pathnames* specified @Aoptional defaults
+@defun merge-pathnames* specified @Aoptional{} defaults
 
 This function is a replacement for @code{merge-pathnames} that uses the host and device
@@ -4023 +4411 @@
 @end defun
 
-@defun subpathname pathname subpath @Akey type
+@defun subpathname pathname subpath @Akey{} type
 
 This function takes a @var{pathname} and a @var{subpath} and a @var{type}.
@@ -4037 +4425 @@
 @end defun
 
-@defun subpathname* pathname subpath @Akey type
+@defun subpathname* pathname subpath @Akey{} type
 
 This function returns @code{nil} if the base @var{pathname} is @code{nil},
@@ -4043 +4431 @@
 @end defun
 
-@defun run-program command @Akey ignore-error-status force-shell input output error-output
-  if-input-does-not-exist if-output-exists if-error-output-exists
-  element-type external-format @AallowOtherKeys
+@defun run-program command @Akey{} ignore-error-status force-shell input output @
+error-output if-input-does-not-exist if-output-exists if-error-output-exists @
+element-type external-format @AallowOtherKeys
 
 @code{run-program} takes a @var{command} argument that is either
@@ -4124 +4512 @@
 @end defun
 
-@defun slurp-input-stream processor input-stream @Akey
-
-It's a generic function of two arguments, a target object and an input stream,
+@defun slurp-input-stream processor input-stream @Akey{}
+
+@code{slurp-input-stream} is a generic function of two arguments, a target object and an input stream,
 and accepting keyword arguments.
-Predefined methods based on the target object are as follow:
-
+Predefined methods based on the target object are as follows:
+
+@itemize
+@item
 If the object is a function, the function is called with the stream as argument.
 
-If the object is a cons, its first element is applied to its rest appended by
+@item If the object is a cons, its first element is applied to its rest appended by
 a list of the input stream.
 
-If the object is an output stream, the contents of the input stream are copied to it.
+@item If the object is an output stream, the contents of the input stream are copied to it.
 If the @var{linewise} keyword argument is provided, copying happens line by line,
 and an optional @var{prefix} is printed before each line.
@@ -4141 +4531 @@
 using the specified @var{element-type}.
 
-If the object is @code{'string} or @code{:string}, the content is captured into a string.
+@item If the object is @code{'string} or @code{:string}, the content is captured into a string.
 Accepted keywords include the @var{element-type} and a flag @var{stripped},
 which when true causes any single line ending to be removed as per @code{uiop:stripln}.
 
-If the object is @code{:lines}, the content is captured as a list of strings,
+@item If the object is @code{:lines}, the content is captured as a list of strings,
 one per line, without line ending. If the @var{count} keyword argument is provided,
 it is a maximum count of lines to be read.
 
-If the object is @code{:line}, the content is capture as with @code{:lines} above,
+@item If the object is @code{:line}, the content is captured as with @code{:lines} above,
 and then its sub-object is extracted with the @var{at} argument,
 which defaults to @code{0}, extracting the first line.
@@ -4155 +4545 @@
 See the documentation for @code{uiop:access-at}.
 
-If the object is @code{:forms}, the content is captured as a list of S-expressions,
+@item If the object is @code{:forms}, the content is captured as a list of S-expressions,
 as read by the Lisp reader.
 If the @var{count} argument is provided,
@@ -4162 +4552 @@
 @code{uiop:with-safe-io-syntax}.
 
-If the object is @code{:form}, the content is capture as with @code{:forms} above,
+@item If the object is @code{:form}, the content is captured as with @code{:forms} above,
 and then its sub-object is extracted with the @var{at} argument,
 which defaults to @code{0}, extracting the first form.
@@ -4169 +4559 @@
 We recommend you control the syntax with such macro as
 @code{uiop:with-safe-io-syntax}.
-
+@end itemize
 @end defun
 
@@ -4222 +4612 @@
 
 @node What has changed between ASDF 1 and ASDF 2?, Issues with installing the proper version of ASDF, Where do I report a bug?, FAQ
-@section ``What has changed between ASDF 1 and ASDF 2?''
+@section ``What has changed between ASDF 1, ASDF 2 and ASDF 3?''
+
+We released ASDF 2.000 on May 31st 2010,
+and ASDF 3.0.0 on May 15th 2013.
+Releases of ASDF 2 and later have since then been included
+in all actively maintained CL implementations that used to bundle ASDF 1,
+plus some implementations that previously did not.
+ASDF has been made to work with all actively maintained CL
+implementations and even a few implementations that are @emph{not}
+actively maintained.
+@xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
+Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly
+(though we recommend instead upgrading your implementation or its ASDF module).
+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 @code{:asdf3} feature;
+still, please use the latest release).
+Release ASDF 3.1.2 and later also define the @code{:asdf3.1} feature.
+
 
 @menu
 * What are ASDF 1 2 3?::
+* How do I detect the ASDF version?::
 * ASDF can portably name files in subdirectories::
 * Output translations::
@@ -4237 +4650 @@
 @end menu
 
-@node What are ASDF 1 2 3?, ASDF can portably name files in subdirectories, What has changed between ASDF 1 and ASDF 2?, What has changed between ASDF 1 and ASDF 2?
-@subsection What are ASDF 1, ASDF 2 and ASDF 3?
+@node What are ASDF 1 2 3?, How do I detect the ASDF version?, What has changed between ASDF 1 and ASDF 2?, What has changed between ASDF 1 and ASDF 2?
+@subsection What are ASDF 1, ASDF 2, and ASDF 3?
 
 ASDF 1 refers to any release earlier than 1.369 or so (from August 2001 to October 2009),
@@ -4251 +4664 @@
 2.27 to 2.33 count as pre-releases to ASDF 3.
 
+@node How do I detect the ASDF version?, ASDF can portably name files in subdirectories, What are ASDF 1 2 3?, What has changed between ASDF 1 and ASDF 2?
+@subsection How do I detect the ASDF version?
+@findex asdf-version
+@cindex *features*
+
 All releases of ASDF
 push @code{:asdf} onto @code{*features*}.
 Releases starting with ASDF 2
- push @code{:asdf2} onto @code{*features*}.
+push @code{:asdf2} onto @code{*features*}.
 Releases starting with ASDF 3 (including 2.27 and later pre-releases)
 push @code{:asdf3} onto @code{*features*}.
-Furthermore, releases starting with ASDF 3.1 (March 2014),
-though they count as ASDF 3, includes enough progress that they
+Furthermore, releases starting with ASDF 3.1.2 (May 2014),
+though they count as ASDF 3, include enough progress that they
 push @code{:asdf3.1} onto @code{*features*}.
 You may depend on the presence or absence of these features
@@ -4273 +4691 @@
 
 
-@node ASDF can portably name files in subdirectories, Output translations, What are ASDF 1 2 3?, What has changed between ASDF 1 and ASDF 2?
+@node ASDF can portably name files in subdirectories, Output translations, How do I detect the ASDF version?, What has changed between ASDF 1 and ASDF 2?
 @subsection ASDF can portably name files in subdirectories
 
 Common Lisp namestrings are not portable,
-except maybe for logical pathnamestrings,
+except maybe for logical pathname namestrings,
 that themselves have various limitations and require a lot of setup
 that is itself ultimately non-portable.
@@ -4398 +4816 @@
 (say with thousands of components) by using
 hash-tables instead of linear search,
-and linear-time list accumulation
-instead of quadratic-time recursive appends.
+and linear-time list accumulation instead of cubic time recursive append,
+for an overall @emph{O(n)} complexity vs @emph{O(n^4)}.
 
 @item
@@ -4410 +4828 @@
 While still incomplete, it now fully passes
 on all implementations supported by the test suite,
-except for GCL (due to GCL bugs).
+though some tests are commented out on a few implementations.
 
 @item
@@ -4632 +5050 @@
 
 @item
-You may, like SBCL, have ASDF be implicitly used to require systems
-that are bundled with your Lisp distribution.
-If you do have a few magic systems that come with your implementation
-in a precompiled way such that one should only use the binary version
-that goes with your distribution, like SBCL does,
-then you should add them in the beginning of @code{wrapping-source-registry}.
-
-@item
-If you have magic systems as above, like SBCL does,
+You may, like SBCL since 1.1.13 or MKCL since 1.1.9,
+have ASDF create bundle FASLs
+that are provided as modules by your Lisp distribution.
+You may also, but we don't recommend that anymore,
+have ASDF like SBCL up until 1.1.12 be implicitly used
+when requiring modules that are provided by your Lisp distribution;
+if you do, you should add them in the beginning of both
+@code{wrapping-source-registry} and @code{wrapping-output-translations}.
+
+@item
+If you have magic systems as above, like SBCL used to do,
 then we explicitly ask you to @emph{NOT} distribute
 @file{asdf.asd} as part of those magic systems.
@@ -4664 +5084 @@
 Non-magic systems should be at the back of the @code{wrapping-source-registry}
 while magic systems are at the front.
+If they are precompiled,
+they should also be in the @code{wrapping-output-translations}.
 
 @item
@@ -4743 +5165 @@
 @end example
 
+Note that this does @emph{NOT} belong in a @file{.asd} file.
+Please do not tamper with ASDF configuration from a @file{.asd} file,
+and only do this from your personal configuration or build scripts.
+
 @node Issues with using and extending ASDF to define systems, ASDF development FAQs, Issues with configuring ASDF, FAQ
 @section Issues with using and extending ASDF to define systems
@@ -4752 +5178 @@
 * I want to put my module's files at the top level.  How do I do this?::
 * How do I create a system definition where all the source files have a .cl extension?::
+* How do I mark a source file to be loaded only and not compiled?::
+* How do I work with readtables?::
 @end menu
 
@@ -4765 +5193 @@
 and on the
 @url{https://launchpad.net/asdf,launchpad bug-tracker}.
-
-Here are some guidelines:
-
-@itemize
-@item
-For a given system, @var{foo}, you will want to define a corresponding
-test system, such as @var{foo-test}.  The reason that you will want this
-separate system is that ASDF does not out of the box supply components
-that are conditionally loaded.  So if you want to have source files
-(with the test definitions) that will not be loaded except when testing,
-they should be put elsewhere.
-
-@item
-The @var{foo-test} system can be defined in an asd file of its own or
-together with @var{foo}.  An aesthetic preference against cluttering up
-the filesystem with extra asd files should be balanced against the
-question of whether one might want to directly load @var{foo-test}.
-Typically one would not want to do this except in early stages of
-debugging.
-
-@item
-Record that testing is implemented by @var{foo-test}.  For example:
-@example
-(defsystem @var{foo}
-   :in-order-to ((test-op (test-op @var{foo-test})))
-   ....)
-
-(defsystem @var{foo-test}
-   :depends-on (@var{foo} @var{my-test-library} ...)
-   ....)
-@end example
-@end itemize
-
-This procedure will allow you to support users who do not wish to
-install your test framework.
-
-One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
-does not return a value.  So in current versions of ASDF there is no
-reliable programmatic means of determining whether or not a set of tests
-has passed, or which tests have failed.  The user must simply read the
-console output.  This limitation has been the subject of much
-discussion.
+We provide some guidelines in the discussion of @code{test-op}.
+
+@c cut the following because it's discussed in the discussion of test-op.
+@c Here are some guidelines:
+
+@c @itemize
+@c @item
+@c For a given system, @var{foo}, you will want to define a corresponding
+@c test system, such as @var{foo-test}.  The reason that you will want this
+@c separate system is that ASDF does not out of the box supply components
+@c that are conditionally loaded.  So if you want to have source files
+@c (with the test definitions) that will not be loaded except when testing,
+@c they should be put elsewhere.
+
+@c @item
+@c The @var{foo-test} system can be defined in an asd file of its own or
+@c together with @var{foo}.  An aesthetic preference against cluttering up
+@c the filesystem with extra asd files should be balanced against the
+@c question of whether one might want to directly load @var{foo-test}.
+@c Typically one would not want to do this except in early stages of
+@c debugging.
+
+@c @item
+@c Record that testing is implemented by @var{foo-test}.  For example:
+@c @example
+@c (defsystem @var{foo}
+@c    :in-order-to ((test-op (test-op @var{foo-test})))
+@c    ....)
+
+@c (defsystem @var{foo-test}
+@c    :depends-on (@var{foo} @var{my-test-library} ...)
+@c    ....)
+@c @end example
+@c @end itemize
+
+@c This procedure will allow you to support users who do not wish to
+@c install your test framework.
+
+@c One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
+@c does not return a value.  So in current versions of ASDF there is no
+@c reliable programmatic means of determining whether or not a set of tests
+@c has passed, or which tests have failed.  The user must simply read the
+@c console output.  This limitation has been the subject of much
+@c discussion.
 
 @node How can I cater for documentation generation in my system?, How can I maintain non-Lisp (e.g. C) source files?, How can I cater for unit-testing in my system?, Issues with using and extending ASDF to define systems
@@ -4886 +5316 @@
 (if the component class doesn't specifies a pathname type).
 
-@node How do I create a system definition where all the source files have a .cl extension?,  , I want to put my module's files at the top level.  How do I do this?, Issues with using and extending ASDF to define systems
+@node How do I create a system definition where all the source files have a .cl extension?, How do I mark a source file to be loaded only and not compiled?, I want to put my module's files at the top level.  How do I do this?, Issues with using and extending ASDF to define systems
 @subsection How do I create a system definition where all the source files have a .cl extension?
 
@@ -4955 +5385 @@
 @end lisp
 
+@node How do I mark a source file to be loaded only and not compiled?, How do I work with readtables?, How do I create a system definition where all the source files have a .cl extension?, Issues with using and extending ASDF to define systems
+@subsection How do I mark a source file to be loaded only and not compiled?
+
+There is no provision in ASDF for ensuring that
+some components are always loaded as source, while others are always
+compiled.
+There is @code{load-source-op} (@pxref{Predefined operations of
+ASDF,load-source-op}), but that is an operation to be applied to a
+system as a whole, not to one or another specific source files.
+While this idea often comes up in discussions,
+it doesn't play well with either the linking model of ECL
+or with various bundle operations.
+In addition, the dependency model of ASDF would have to be modified incompatibly
+to allow for such a trick.
+@c If your code doesn't compile cleanly, fix it.
+@c If compilation makes it slow, use @code{declaim} or @code{eval-when}
+@c to adjust your compiler settings,
+@c or eschew compilation by @code{eval}uating a quoted source form at load-time.
+
+@node How do I work with readtables?,  , How do I mark a source file to be loaded only and not compiled?, Issues with using and extending ASDF to define systems
+@subsection How do I work with readtables?
+
+@cindex readtables
+
+It is possible to configure the lisp syntax by modifying the currently-active readtable.
+However, this same readtable is shared globally by all software being compiled by ASDF,
+especially since @code{load} and @code{compile-file} both bind @var{*readtable*},
+so that its value is the same across the build at the start of every file
+(unless overridden by some @code{perform :around} method),
+even if a file locally binds it to a different readtable during the build.
+
+Therefore, the following hygiene restrictions apply. If you don't abide by these restrictions,
+there will be situations where your output files will be corrupted during an incremental build.
+We are not trying to prescribe new restrictions for the sake of good style:
+these restrictions have always applied implicitly, and
+we are simply describing what they have always been.
+
+@itemize
+@item It is forbidden to modifying any standard character or standard macro dispatch defined in the CLHS.
+@item No two dependencies may assign different meanings to the same non-standard character.
+@item Using any non-standard character while expecting the implementation to treat some way
+    counts as such an assignment of meaning.
+@item libraries need to document these assignments of meaning to non-standard characters.
+@item free software libraries will register these changes on:
+        @url{http://www.cliki.net/Macro%20Characters}
+@end itemize
+
+If you want to use readtable modifications that cannot abide by those restrictions,
+you @emph{must} create a different readtable object and set @var{*readtable*}
+to temporarily bind it to your new readtable (which will be undone after processing the file).
+
+For that, we recommend you use system @code{named-readtables}
+to define or combine such readtables using @code{named-readtables:defreadtable}
+and use them using @code{named-readtables:in-readtable}.
+Equivalently, you can use system @code{cl-syntax},
+that itself uses @code{named-readtables},
+but may someday do more with, e.g. @var{*print-pprint-dispatch*}.
+
+For even more advanced syntax modification beyond what a readtable can express,
+you may consider either:
+@itemize
+@item a @code{perform} method that compiles a constant file that contains a single form
+  @code{#.*code-read-with-alternate-reader*} in an environment where this special variable
+  was bound to the code read by your alternate reader, or
+@item using the system @code{reader-interception}.
+@end itemize
+
+Beware that @c unless and until the @code{syntax-control} branch is merged,
+it is unsafe to use ASDF from the REPL to compile or load systems
+while the readtable isn't the shared readtable previously used to build software.
+You @emph{must} manually undo any binding of @var{*readtable*} at the REPL
+and restore its initial value whenever you call @code{operate}
+(via e.g. @code{load-system}, @code{test-system} or @code{require})
+from a REPL that is using a different readtable.
+
+@subsubsection How should my system use a readtable exported by another system?
+
+Use from the @code{named-readtables} system the macro @code{named-readtables:in-readtable}.
+
+If the other system fails to use @code{named-readtables}, fix it and send a patch upstream.
+In the day and age of Quicklisp and clbuild, there is little reason
+to eschew using such an important library anymore.
+
+@subsubsection How should my library make a readtable available to other systems?
+
+Use from the @code{named-readtables} system the macro @code{named-readtables:defreadtable}.
+
 @node ASDF development FAQs,  , Issues with using and extending ASDF to define systems, FAQ
 @section ASDF development FAQs
@@ -4971 +5488 @@
 Here's the procedure for experimenting with tests in a REPL:
 @example
+;; BEWARE! Some tests expect you to be in the .../asdf/test directory
+;; If your REPL is not there yet, change your current directory:
+;; under SLIME, you may: ,change-directory ~/common-lisp/asdf/test/
+;; otherwise you may evaluate something like:
+(require "asdf") (asdf:upgrade-asdf) ;load UIOP & update asdf.lisp
+(uiop:chdir (asdf:system-relative-pathname :asdf "test/"))
+(setf *default-pathname-defaults* (uiop:getcwd))
+
+;; Load the test script support.
 (load "script-support.lisp")
-(in-package :asdf-test)
-(compile-load-asdf) ; there are a number of other functions to load ASDF
-;; experiment with test code from a .script file...
+
+;; Initialize the script support.
+;; This will also change your *package* to asdf-test.
+;; NB: this function is also available from package cl-user,
+;; and also available with the shorter name da in both packages.
+(asdf-test::debug-asdf)
+
+;; In case you modified ASDF since you last tested it,
+;; you need to update asdf.lisp itself by evaluating 'make' in a shell,
+;; or (require "asdf") (asdf:load-system :asdf) in another CL REPL,
+;; if not done in this REPL above.
+;; *Then*, in this REPL, you need to evaluate:
+;(asdf-test::compile-load-asdf)
+
+;; Now, you may experiment with test code from a .script file.
+;; See the instructions given at the end of your failing test
+;; to identify which form is needed, e.g.
+(frob-packages)
+(asdf::with-asdf-cache () (load "test-utilities.script"))
 @end example
 
@@ -4986 +5528 @@
 see the @file{TODO} file in the source repository.
 
-Also, bugs that are now tracked on launchpad:
+Also, bugs are now tracked on launchpad:
 @url{https://launchpad.net/asdf}.
 
@@ -4993 +5535 @@
 
 @itemize
+@item Francois-Rene Rideau:
+  ``ASDF 3, or Why Lisp is Now an Acceptable Scripting Language'', 2014.
+  This article describes the innovations in ASDF 3 and 3.1,
+  as well as historical information on previous versions.
+  @url{http://github.com/fare/asdf3-2013}
+@item Alastair Bridgewater:
+  ``Quick-build'' (private communication), 2012.
+  @code{quick-build} is a simple and robust one file, one package build system,
+  similar to @code{faslpath}, in 182 lines of code
+  (117 of which are not blank, not comments, not docstrings).
+  Unhappily, it remains unpublished and its IP status is unclear as of April 2014.
+  @code{asdf/package-system} is mostly compatible with it,
+  modulo a different setup for toplevel hierarchies.
 @item Zach Beane:
   ``Quicklisp'', 2011.
@@ -5009 +5564 @@
   though many other of which still haven't.
   @url{http://common-lisp.net/projects/xcvb/}
-@item Dan Barlow: ``ASDF Manual'', 2004
+@item Peter von Etter:
+  ``faslpath'', 2009.
+  @code{faslpath} is similar to the latter @code{quick-build}
+  and our letter @code{asdf/package-system} extension,
+  except that it uses the dot @code{.} rather than the slash @code{/} as a separator.
+  @url{https://code.google.com/p/faslpath/}
+@item Drew McDermott:
+  ``A Framework for Maintaining the Coherence of a Running Lisp,''
+  International Lisp Conference, 2005, available in pre-print form at
+  @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf}
+@item Dan Barlow: ``ASDF Manual'', 2004.
   Older versions of this document from the days of ASDF 1;
   they include ideas laid down by Dan Barlow,
@@ -5030 +5595 @@
   The famous CHINE NUAL describes one of the earliest variants of DEFSYSTEM.
   @url{https://bitsavers.trailing-edge.com/pdf/mit/cadr/chinual_4thEd_Jul81.pdf}
-@item Drew McDermott: ``A Framework for Maintaining the Coherence of a
-  Running Lisp,'' International Lisp Conference, 2005, available in
-  pre-print form at @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf}.
 @end itemize
 

trunk/abcl/src/org/armedbear/lisp/asdf.lisp

@@ -1 +1 @@
 ;;; -*- mode: Common-Lisp; Base: 10 ; Syntax: ANSI-Common-Lisp ; buffer-read-only: t; -*-
-;;; This is ASDF 3.1.0.103: Another System Definition Facility.
+;;; This is ASDF 3.1.2.2: Another System Definition Facility.
 ;;;
 ;;; Feedback, bug reports, and patches are all welcome:
@@ -820 +820 @@
           `(apply 'ensure-package ',(parse-define-package-form package clauses))))
     `(progn
-       #+(or ecl gcl) (defpackage ,package (:use))
+       #+(or ecl gcl mkcl) (defpackage ,package (:use))
        (eval-when (:compile-toplevel :load-toplevel :execute)
          ,ensure-form))))
@@ -1668 +1668 @@
 except on ABCL where it might change between FASL compilation and runtime."
     (loop* :with o
-           :for (feature . detect) :in '((:os-unix . os-unix-p) (:os-windows . os-windows-p)
-                                         (:os-macosx . os-macosx-p)
+           :for (feature . detect) :in '((:os-unix . os-unix-p) (:os-macosx . os-macosx-p)
+                                         (:os-windows . os-windows-p)
                                          (:genera . os-genera-p) (:os-oldmac . os-oldmac-p))
-           :when (and (not o) (funcall detect)) :do (setf o feature) (pushnew o *features*)
+           :when (and (or (not o) (eq feature :os-macosx)) (funcall detect))
+           :do (setf o feature) (pushnew feature *features*)
            :else :do (setf *features* (remove feature *features*))
            :finally
@@ -1851 +1852 @@
   (defun getcwd ()
     "Get the current working directory as per POSIX getcwd(3), as a pathname object"
-    (or #+abcl (symbol-call :asdf/filesystem :parse-native-namestring
-                            (java:jstatic "getProperty" "java.lang.System" "user.dir")
-                                                     :ensure-directory t)
+    (or #+abcl (truename (symbol-call :asdf/filesystem :parse-native-namestring
+                          (java:jstatic "getProperty" "java.lang.System" "user.dir")
+                          :ensure-directory t))
         #+allegro (excl::current-directory)
         #+clisp (ext:default-directory)
@@ -3990 +3991 @@
     (assert (or streamp pathnamep))
     (let* ((afterp (position :close-stream body))
-           (before (if afterp (subseq body 0 (1- afterp)) body))
+           (before (if afterp (subseq body 0 afterp) body))
            (after (when afterp (subseq body (1+ afterp))))
            (beforef (gensym "BEFORE"))
@@ -4010 +4011 @@
           ,@(when type `(:type ,type))
           ,@(when keep `(:keep ,keep))
-          ,@(when after `(:after `#',afterf))
+          ,@(when after `(:after #',afterf))
           ,@(when element-type `(:element-type ,element-type))
           ,@(when external-format `(:external-format ,external-format))))))
@@ -4468 +4469 @@
                        &key kind output-name prologue-code epilogue-code extra-object-files
                          (prelude () preludep) (postlude () postludep)
-                         (entry-point () entry-point-p) build-args)
+                         (entry-point () entry-point-p) build-args no-uiop)
     (declare (ignorable destination lisp-object-files extra-object-files kind output-name
                         prologue-code epilogue-code prelude preludep postlude postludep
-                        entry-point entry-point-p build-args))
+                        entry-point entry-point-p build-args no-uiop))
     "On ECL, create an executable at pathname DESTINATION from the specified OBJECT-FILES and options"
     ;; Is it meaningful to run these in the current environment?
@@ -4478 +4479 @@
     #-(or ecl mkcl) (error "~S not implemented for your implementation (yet)" 'create-image)
     #+(or ecl mkcl)
-    (let ((epilogue-forms
-            (append
-             (when epilogue-code `(,epilogue-code))
-             (when postludep `((setf *image-postlude* ',postlude)))
-             (when preludep `((setf *image-prelude* ',prelude)))
-             (when entry-point-p `((setf *image-entry-point* ',entry-point)))
-             (case kind
-               ((:image)
-                (setf kind :program) ;; to ECL, it's just another program.
-                `((setf *image-dumped-p* t)
-                  (si::top-level #+ecl t) (quit)))
-               ((:program)
-                `((setf *image-dumped-p* :executable)
-                  (shell-boolean-exit
-                   (restore-image))))))))
+    (let ((epilogue-code
+            (if no-uiop
+                epilogue-code
+                (let ((forms
+                        (append
+                         (when epilogue-code `(,epilogue-code))
+                         (when postludep `((setf *image-postlude* ',postlude)))
+                         (when preludep `((setf *image-prelude* ',prelude)))
+                         (when entry-point-p `((setf *image-entry-point* ',entry-point)))
+                         (case kind
+                           ((:image)
+                            (setf kind :program) ;; to ECL, it's just another program.
+                            `((setf *image-dumped-p* t)
+                              (si::top-level #+ecl t) (quit)))
+                           ((:program)
+                            `((setf *image-dumped-p* :executable)
+                              (shell-boolean-exit
+                               (restore-image))))))))
+                  (when forms `(progn ,@forms))))))
       #+ecl (check-type kind (member :dll :lib :static-library :program :object :fasl))
       (apply #+ecl 'c::builder #+ecl kind
@@ -4505 +4510 @@
              (append
               (when prologue-code `(:prologue-code ,prologue-code))
-              (when epilogue-forms `(:epilogue-code (progn ,@epilogue-forms)))
+              (when epilogue-code `(:epilogue-code ,epilogue-code))
               #+mkcl (when extra-object-files `(:object-files ,extra-object-files))
               build-args)))))
@@ -5428 +5433 @@
    #+sbcl #:sb-grovel-unknown-constant-condition
    ;; Functions & Macros
-   #:get-optimization-settings #:proclaim-optimization-settings
+   #:get-optimization-settings #:proclaim-optimization-settings #:with-optimization-settings
    #:call-with-muffled-compiler-conditions #:with-muffled-compiler-conditions
    #:call-with-muffled-loader-conditions #:with-muffled-loader-conditions
@@ -5468 +5473 @@
   (defvar *previous-optimization-settings* nil
     "Optimization settings saved by PROCLAIM-OPTIMIZATION-SETTINGS")
+  (defparameter +optimization-variables+
+    ;; TODO: allegro genera corman mcl
+    (or #+(or abcl xcl) '(system::*speed* system::*space* system::*safety* system::*debug*)
+        #+clisp '() ;; system::*optimize* is a constant hash-table! (with non-constant contents)
+        #+clozure '(ccl::*nx-speed* ccl::*nx-space* ccl::*nx-safety*
+                    ccl::*nx-debug* ccl::*nx-cspeed*)
+        #+(or cmu scl) '(c::*default-cookie*)
+        #+ecl (unless (use-ecl-byte-compiler-p) '(c::*speed* c::*space* c::*safety* c::*debug*))
+        #+gcl '(compiler::*speed* compiler::*space* compiler::*compiler-new-safety* compiler::*debug*)
+        #+lispworks '(compiler::*optimization-level*)
+        #+mkcl '(si::*speed* si::*space* si::*safety* si::*debug*)
+        #+sbcl '(sb-c::*policy*)))
   (defun get-optimization-settings ()
     "Get current compiler optimization settings, ready to PROCLAIM again"
-    #-(or clisp clozure cmu ecl mkcl sbcl scl)
-    (warn "~S does not support ~S. Please help me fix that." 'get-optimization-settings (implementation-type))
-    #+clozure (ccl:declaration-information 'optimize nil)
-    #+(or clisp cmu ecl mkcl sbcl scl)
+    #-(or abcl allegro clisp clozure cmu ecl lispworks mkcl sbcl scl xcl)
+    (warn "~S does not support ~S. Please help me fix that."
+          'get-optimization-settings (implementation-type))
+    #+(or abcl allegro clisp clozure cmu ecl lispworks mkcl sbcl scl xcl)
     (let ((settings '(speed space safety debug compilation-speed #+(or cmu scl) c::brevity)))
-      #.`(loop :for x :in settings
-               ,@(or #+ecl '(:for v :in '(c::*speed* c::*space* c::*safety* c::*debug*))
-                     #+mkcl '(:for v :in '(si::*speed* si::*space* si::*safety* si::*debug*))
-                     #+(or cmu scl) '(:for f :in '(c::cookie-speed c::cookie-space c::cookie-safety c::cookie-debug c::cookie-cspeed c::cookie-brevity)))
-               :for y = (or #+clisp (gethash x system::*optimize*)
-                            #+(or ecl mkcl) (symbol-value v)
-                            #+(or cmu scl) (funcall f c::*default-cookie*)
+      #.`(loop #+(or allegro clozure)
+               ,@'(:with info = #+allegro (sys:declaration-information 'optimize)
+                   #+clozure (ccl:declaration-information 'optimize nil))
+               :for x :in settings
+               ,@(or #+(or abcl ecl gcl mkcl xcl) '(:for v :in +optimization-variables+))
+               :for y = (or #+(or allegro clozure) (second (assoc x info)) ; normalize order
+                            #+clisp (gethash x system::*optimize* 1)
+                            #+(or abcl ecl mkcl xcl) (symbol-value v)
+                            #+(or cmu scl) (slot-value c::*default-cookie*
+                                                       (case x (compilation-speed 'c::cspeed)
+                                                             (otherwise x)))
+                            #+lispworks (slot-value compiler::*optimization-level* x)
                             #+sbcl (cdr (assoc x sb-c::*policy*)))
                :when y :collect (list x y))))
@@ -5489 +5511 @@
     (let ((settings (get-optimization-settings)))
       (unless (equal *previous-optimization-settings* settings)
-        (setf *previous-optimization-settings* settings)))))
+        (setf *previous-optimization-settings* settings))))
+  (defmacro with-optimization-settings ((&optional (settings *optimization-settings*)) &body body)
+    #+(or allegro clisp)
+    (let ((previous-settings (gensym "PREVIOUS-SETTINGS")))
+      `(let ((,previous-settings (get-optimization-settings)))
+         ,@(when settings `((proclaim `(optimize ,@,settings))))
+         (unwind-protect (progn ,@body)
+           (proclaim `(optimize ,@,previous-settings)))))
+    #-(or allegro clisp)
+    `(let ,(loop :for v :in +optimization-variables+ :collect `(,v ,v))
+       ,@(when settings `((proclaim `(optimize ,@,settings))))
+       ,@body)))
 
 
@@ -6536 +6569 @@
    :uiop/configuration :uiop/backward-driver))
 
-#+mkcl (provide :uiop)
+;; Provide both lowercase and uppercase, to satisfy more people.
+(provide "uiop") (provide "UIOP")
 ;;;; -------------------------------------------------------------------------
 ;;;; Handle upgrade as forward- and backward-compatibly as possible
@@ -6606 +6640 @@
          ;; "3.4.5.0.8" would be your eighth local modification of official release 3.4.5
          ;; "3.4.5.67.8" would be your eighth local modification of development version 3.4.5.67
-         (asdf-version "3.1.0.103")
+         (asdf-version "3.1.2.2")
          (existing-version (asdf-version)))
     (setf *asdf-version* asdf-version)
@@ -6964 +6998 @@
 ;;;; version-satisfies
 (with-upgradability ()
+  ;; short-circuit testing of null version specifications.
+  ;; this is an all-pass, without warning
+  (defmethod version-satisfies :around ((c t) (version null))
+    t)
   (defmethod version-satisfies ((c component) version)
     (unless (and version (slot-boundp c 'version) (component-version c))
       (when version
         (warn "Requested version ~S but ~S has no version" version c))
-      (return-from version-satisfies t))
+      (return-from version-satisfies nil))
     (version-satisfies (component-version c) version))
 
@@ -9127 +9165 @@
     ;; If we're in the middle of something, restart it.
     (when *asdf-cache*
-      (let ((l (loop* :for (x y) :being :the hash-keys :of *asdf-cache*
-                      :when (eq x 'find-system) :collect y)))
+      (let ((l (loop :for k :being :the hash-keys :of *asdf-cache*
+                     :when (eq (first k) 'find-system) :collect (second k))))
         (clrhash *asdf-cache*)
         (dolist (s l) (find-system s nil)))))
@@ -10163 +10201 @@
     ((prologue-code :initform nil :initarg :prologue-code :reader prologue-code)
      (epilogue-code :initform nil :initarg :epilogue-code :reader epilogue-code)
+     (no-uiop :initform nil :initarg :no-uiop :reader no-uiop)
      (prefix-lisp-object-files :initarg :prefix-lisp-object-files
                                :initform nil :accessor prefix-lisp-object-files)
@@ -10174 +10213 @@
   (defmethod prologue-code ((x t)) nil)
   (defmethod epilogue-code ((x t)) nil)
+  (defmethod no-uiop ((x t)) nil)
   (defmethod prefix-lisp-object-files ((x t)) nil)
   (defmethod postfix-lisp-object-files ((x t)) nil)
@@ -10273 +10313 @@
       ((member :dll :lib :shared-library :static-library :program :object :program)
        (compile-file-type :type bundle-type))
-      ((member :image) "image")
+      ((member :image) #-allegro "image" #+allegro "dxl")
       ((member :dll :shared-library) (cond ((os-macosx-p) "dylib") ((os-unix-p) "so") ((os-windows-p) "dll")))
       ((member :lib :static-library) (cond ((os-unix-p) "a")
-             ((os-windows-p) (if (featurep '(:or :mingw32 :mingw64)) "a" "lib"))))
+                                           ((os-windows-p) (if (featurep '(:or :mingw32 :mingw64)) "a" "lib"))))
       ((eql :program) (cond ((os-unix-p) nil) ((os-windows-p) "exe")))))
 
@@ -10337 +10377 @@
     (setf (extra-build-args instance)
           (remove-plist-keys
-           '(:type :monolithic :name-suffix :epilogue-code :prologue-code :lisp-files)
+           '(:type :monolithic :name-suffix :epilogue-code :prologue-code :lisp-files
+             :force :force-not :plan-class) ;; TODO: refactor so we don't mix plan and operation arguments
            (operation-original-initargs instance))))
 
@@ -10587 +10628 @@
 
   (defun asdf-library-pathname ()
-    #+ecl (compile-file-pathname "sys:asdf" :type :lib)
+    #+ecl (or (probe-file* (compile-file-pathname "sys:asdf" :type :lib)) ;; new style
+              (probe-file* (compile-file-pathname "sys:asdf" :type :object))) ;; old style
     #+mkcl (make-pathname :type (bundle-pathname-type :lib) :defaults #p"sys:contrib;asdf"))
 
+  (defun compiler-library-pathname ()
+    #+ecl (compile-file-pathname "sys:cmp" :type :lib)
+    #+mkcl (make-pathname :type (bundle-pathname-type :lib) :defaults #p"sys:cmp"))
+
   (defun make-library-system (name pathname)
-    (make-instance 'prebuilt-system :name name :static-library (resolve-symlinks* pathname)))
+    (make-instance 'prebuilt-system
+                   :name (coerce-name name) :static-library (resolve-symlinks* pathname)))
 
   (defmethod component-depends-on :around ((o image-op) (c system))
@@ -10597 +10644 @@
       (flet ((has-it-p (x) (find x deps :test 'equal :key 'coerce-name)))
         `((,lib-op
-           #+mkcl ,@(unless (has-it-p "cmp")
-                      `(,(make-library-system
-                          "cmp" (make-pathname :type (bundle-pathname-type :lib)
-                                               :defaults #p"sys:cmp"))))
-           ,@(unless (or (has-it-p "asdf") (has-it-p "uiop"))
+           ,@(unless (or (no-uiop c) (has-it-p "cmp"))
+               `(,(make-library-system
+                   "cmp" (compiler-library-pathname))))
+           ,@(unless (or (no-uiop c) (has-it-p "uiop") (has-it-p "asdf"))
                `(,(cond
                     ((system-source-directory :uiop) (find-system :uiop))
                     ((system-source-directory :asdf) (find-system :asdf))
-                    (t (make-fake-asdf-system "asdf" (asdf-library-pathname))))))
+                    (t (make-library-system "asdf" (asdf-library-pathname))))))
            ,@deps)))))
 
@@ -10625 +10671 @@
                :build-args (or (extra-build-args o) (when programp (extra-build-args c)))
                :extra-object-files (or (extra-object-files o) (when programp (extra-object-files c)))
+               :no-uiop (no-uiop c)
                (when programp `(:entry-point ,(component-entry-point c))))))))
 
@@ -10638 +10685 @@
 
 
-;;; Backward compatibility with pre-3.1.1 names
+;;; Backward compatibility with pre-3.1.2 names
 (defclass fasl-op (selfward-operation)
   ((selfward-operation :initform 'compile-bundle-op :allocation :class)))
@@ -10918 +10965 @@
 ;;;; Package systems in the style of quick-build or faslpath
 
-(uiop:define-package :asdf/package-system
-  (:recycle :asdf/package-system :asdf)
+(uiop:define-package :asdf/package-inferred-system
+  (:recycle :asdf/package-inferred-system :asdf/package-system :asdf)
   (:use :uiop/common-lisp :uiop
         :asdf/defsystem ;; Using the old name of :asdf/parse-defsystem for compatibility
         :asdf/upgrade :asdf/component :asdf/system :asdf/find-system :asdf/lisp-action)
   (:export
-   #:package-system #:register-system-packages #:sysdef-package-system-search
-   #:*defpackage-forms* #:*package-systems* #:package-system-missing-package-error))
-(in-package :asdf/package-system)
-
-(with-upgradability ()
-  (defparameter *defpackage-forms* '(cl:defpackage uiop:define-package))
-
-  (defun initial-package-systems-table ()
+   #:package-inferred-system #:sysdef-package-inferred-system-search
+   #:package-system ;; backward compatibility only. To be removed.
+   #:register-system-packages
+   #:*defpackage-forms* #:*package-inferred-systems* #:package-inferred-system-missing-package-error))
+(in-package :asdf/package-inferred-system)
+
+(with-upgradability ()
+  (defparameter *defpackage-forms* '(defpackage define-package))
+
+  (defun initial-package-inferred-systems-table ()
     (let ((h (make-hash-table :test 'equal)))
       (dolist (p (list-all-packages))
@@ -10938 +10987 @@
       h))
 
-  (defvar *package-systems* (initial-package-systems-table))
-
-  (defclass package-system (system)
+  (defvar *package-inferred-systems* (initial-package-inferred-systems-table))
+
+  (defclass package-inferred-system (system)
     ())
+
+  ;; For backward compatibility only. To be removed in an upcoming release:
+  (defclass package-system (package-inferred-system) ())
 
   (defun defpackage-form-p (form)
@@ -10956 +11008 @@
       (stream-defpackage-form f)))
 
-  (define-condition package-system-missing-package-error (system-definition-error)
+  (define-condition package-inferred-system-missing-package-error (system-definition-error)
     ((system :initarg :system :reader error-system)
      (pathname :initarg :pathname :reader error-pathname))
     (:report (lambda (c s)
                (format s (compatfmt "~@<No package form found while ~
-                                     trying to define package-system ~A from file ~A~>")
+                                     trying to define package-inferred-system ~A from file ~A~>")
                        (error-system c) (error-pathname c)))))
 
@@ -10990 +11042 @@
     (let ((name (or (eq system t) (coerce-name system))))
       (dolist (p (ensure-list packages))
-        (setf (gethash (package-designator-name p) *package-systems*) name))))
+        (setf (gethash (package-designator-name p) *package-inferred-systems*) name))))
 
   (defun package-name-system (package-name)
@@ -10996 +11048 @@
 otherwise return a default system name computed from PACKAGE-NAME."
     (check-type package-name string)
-    (if-let ((system-name (gethash package-name *package-systems*)))
+    (if-let ((system-name (gethash package-name *package-inferred-systems*)))
       system-name
       (string-downcase package-name)))
 
-  (defun package-system-file-dependencies (file &optional system)
+  (defun package-inferred-system-file-dependencies (file &optional system)
     (if-let (defpackage-form (file-defpackage-form file))
       (remove t (mapcar 'package-name-system (package-dependencies defpackage-form)))
-      (error 'package-system-missing-package-error :system system :pathname file)))
-
-  (defun same-package-system-p (system name directory subpath dependencies)
-    (and (eq (type-of system) 'package-system)
+      (error 'package-inferred-system-missing-package-error :system system :pathname file)))
+
+  (defun same-package-inferred-system-p (system name directory subpath dependencies)
+    (and (eq (type-of system) 'package-inferred-system)
          (equal (component-name system) name)
          (pathname-equal directory (component-pathname system))
@@ -11018 +11070 @@
                             (equal (slot-value child 'relative-pathname) subpath))))))))
 
-  (defun sysdef-package-system-search (system)
+  (defun sysdef-package-inferred-system-search (system)
     (let ((primary (primary-system-name system)))
       (unless (equal primary system)
         (let ((top (find-system primary nil)))
-          (when (typep top 'package-system)
+          (when (typep top 'package-inferred-system)
             (if-let (dir (system-source-directory top))
               (let* ((sub (subseq system (1+ (length primary))))
@@ -11028 +11080 @@
                                      :truename *resolve-symlinks*)))
                 (when (file-pathname-p f)
-                  (let ((dependencies (package-system-file-dependencies f system))
+                  (let ((dependencies (package-inferred-system-file-dependencies f system))
                         (previous (cdr (system-registered-p system))))
-                    (if (same-package-system-p previous system dir sub dependencies)
+                    (if (same-package-inferred-system-p previous system dir sub dependencies)
                         previous
                         (eval `(defsystem ,system
-                                 :class package-system
+                                 :class package-inferred-system
                                  :source-file nil
                                  :pathname ,dir
@@ -11040 +11092 @@
 
 (with-upgradability ()
-  (pushnew 'sysdef-package-system-search *system-definition-search-functions*))
+  (pushnew 'sysdef-package-inferred-system-search *system-definition-search-functions*)
+  (setf *system-definition-search-functions*
+        (remove (find-symbol* :sysdef-package-system-search :asdf/package-system nil)
+                *system-definition-search-functions*)))
 ;;;; ---------------------------------------------------------------------------
 ;;;; Handle ASDF package upgrade, including implementation-dependent magic.
@@ -11055 +11110 @@
    :asdf/output-translations :asdf/source-registry
    :asdf/plan :asdf/operate :asdf/parse-defsystem :asdf/bundle :asdf/concatenate-source
-   :asdf/backward-internals :asdf/backward-interface :asdf/package-system)
+   :asdf/backward-internals :asdf/backward-interface :asdf/package-inferred-system)
   ;; Note: (1) we are NOT automatically reexporting everything from previous packages.
   ;; (2) we only reexport UIOP functionality when backward-compatibility requires it.
@@ -11102 +11157 @@
    #:file-type #:source-file-type
 
-   #:package-system #:register-system-packages
+   #:package-inferred-system #:register-system-packages
+   #:package-system ;; backward-compatibility during migration, to be removed in a further release.
 
    #:component-children          ; component accessors
@@ -11165 +11221 @@
    #:circular-dependency        ; errors
    #:duplicate-names #:non-toplevel-system #:non-system-system
-   #:package-system-missing-package-error
+   #:package-inferred-system-missing-package-error
    #:operation-definition-warning #:operation-definition-error
 
@@ -11215 +11271 @@
 (uiop/package:define-package :asdf/user
   (:nicknames :asdf-user)
-  ;; NB: releases before 3.1.1 this :use'd only uiop/package instead of uiop below.
+  ;; NB: releases before 3.1.2 this :use'd only uiop/package instead of uiop below.
   ;; They also :use'd uiop/common-lisp, that reexports common-lisp and is not included in uiop.
   ;; ASDF3 releases from 2.27 to 2.31 called uiop asdf-driver and asdf/foo uiop/foo.