Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

Diff of /contrib/asdf/asdf.texinfo [997412] .. [d9e3be] Maximize Restore

  Switch to side-by-side view

--- a/contrib/asdf/asdf.texinfo
+++ b/contrib/asdf/asdf.texinfo
@@ -1,23 +1,45 @@
 \input texinfo          @c -*- texinfo -*-
 @c %**start of header
 @setfilename asdf.info
-@settitle asdf Manual
+@settitle ASDF Manual
 @c %**end of header
+
+@c We use @&key, etc to escape & from TeX in lambda lists --
+@c so we need to define them for info as well.
+@macro AallowOtherKeys
+&allow-other-keys
+@end macro
+@macro Aoptional
+&optional
+@end macro
+@macro Arest
+&rest
+@end macro
+@macro Akey
+&key
+@end macro
+@macro Abody
+&body
+@end macro
 
 @c for install-info
 @dircategory Software development
 @direntry
-* asdf: (asdf).           another system definition facility
+* asdf: (asdf).           Another System Definition Facility (for Common Lisp)
 @end direntry
 
 @copying
-This manual describes asdf, a system definition facility for Common
-Lisp programs and libraries.
-     
-asdf Copyright @copyright{} 2001-2004 Daniel Barlow and contributors
-
-This manual Copyright @copyright{} 2001-2004 Daniel Barlow and
-contributors
+This manual describes ASDF, a system definition facility
+for Common Lisp programs and libraries.
+
+You can find the latest version of this manual at
+@url{http://common-lisp.net/project/asdf/asdf.html}.
+
+ASDF Copyright @copyright{} 2001-2014 Daniel Barlow and contributors.
+
+This manual Copyright @copyright{} 2001-2014 Daniel Barlow and contributors.
+
+This manual revised @copyright{} 2009-2014 Robert P. Goldman and Francois-Rene Rideau.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -43,14 +65,14 @@
 
 
 @titlepage
-@title asdf: another system definition facility
-     
+@title ASDF: Another System Definition Facility
+
 @c The following two commands start the copyright page.
 @page
 @vskip 0pt plus 1filll
 @insertcopying
 @end titlepage
-     
+
 @c Output the table of contents at the beginning.
 @contents
 
@@ -58,54 +80,182 @@
 
 @ifnottex
 
-@node Top, Using asdf to load systems, (dir), (dir)
-@top asdf: another system definition facility
-     
+@node Top, Introduction, (dir), (dir)
+@top ASDF: Another System Definition Facility
+
 @insertcopying
 
 @menu
-* Using asdf to load systems::  
-* Defining systems with defsystem::  
-* The object model of asdf::    
-* Error handling::              
-* Compilation error and warning handling::  
-* Getting the latest version::  
-* TODO list::                   
-* missing bits in implementation::  
-* Inspiration::                 
-* Concept Index::               
-* Function and Class Index::    
-* Variable Index::              
+* Introduction::
+* Quick start summary::
+* Loading ASDF::
+* Configuring ASDF::
+* Using ASDF::
+* Defining systems with defsystem::
+* The object model of ASDF::
+* Controlling where ASDF searches for systems::
+* Controlling where ASDF saves compiled files::
+* Error handling::
+* Miscellaneous additional functionality::
+* Getting the latest version::
+* FAQ::
+* Ongoing Work::
+* Bibliography::
+* Concept Index::
+* Function and Class Index::
+* Variable Index::              @c @detailmenu
+@c
 
 @detailmenu
  --- The Detailed Node Listing ---
 
+Loading ASDF
+
+* Loading a pre-installed ASDF::
+* Checking whether ASDF is loaded::
+* Upgrading 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
 
-* The defsystem form::          
-* A more involved example::     
-* The defsystem grammar::       
-
-The object model of asdf
-
-* Operations::                  
-* Components::                  
+* The defsystem form::
+* A more involved example::
+* The defsystem grammar::
+* Other code in .asd files::
+* The package-inferred-system extension::
+
+The Object model of ASDF
+
+* Operations::
+* Components::
+* Dependencies::
+* Functions::
 
 Operations
 
-* Predefined operations of asdf::  
-* Creating new operations::     
+* Predefined operations of ASDF::
+* Creating new operations::
 
 Components
 
-* Common attributes of components::  
-* Pre-defined subclasses of component::  
-* Creating new component types::  
+* Common attributes of components::
+* Pre-defined subclasses of component::
+* Creating new component types::
 
 properties
 
-* Pre-defined subclasses of component::  
-* Creating new component types::  
+* 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
+
+* Where do I report a bug?::
+* What has changed between ASDF 1 and ASDF 2?::
+* Issues with installing the proper version of ASDF::
+* Issues with configuring ASDF::
+* Issues with using and extending ASDF to define systems::
+* ASDF development FAQs::
+
+``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::
+* Source Registry Configuration::
+* Usual operations are made easier to the user::
+* Many bugs have been fixed::
+* ASDF itself is versioned::
+* ASDF can be upgraded::
+* Decoupled release cycle::
+* Pitfalls of the transition to ASDF 2::
+
+Issues with installing the proper version of ASDF
+
+* My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
+* I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::
+
+Issues with configuring ASDF
+
+* How can I customize where fasl files are stored?::
+* How can I wholly disable the compiler output cache?::
+
+Issues with using and extending ASDF to define systems
+
+* How can I cater for unit-testing in my system?::
+* How can I cater for documentation generation in my system?::
+* How can I maintain non-Lisp (e.g. C) source files?::
+* 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
+
+* How do run the tests interactively in a REPL?::
 
 @end detailmenu
 @end menu
@@ -114,125 +264,814 @@
 
 @c -------------------
 
-
-@node  Using asdf to load systems, Defining systems with defsystem, Top, Top
+@node Introduction, Quick start summary, Top, Top
 @comment  node-name,  next,  previous,  up
-@chapter Using asdf to load systems
-@cindex system directory designator
-@vindex *central-registry*
-
-This chapter describes how to use asdf to compile and load ready-made
-Lisp programs and libraries.
-
-@section Downloading asdf
-
-Some Lisp implementations (such as SBCL and OpenMCL) come with asdf
-included already, so you don't need to download it separately.
-Consult your Lisp system's documentation.  If you need to download
-asdf and install it by hand, the canonical source is the cCLan CVS
-repository at
-@url{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/}.
-
-@section Setting up asdf
-
-The single file @file{asdf.lisp} is all you need to use asdf normally.
-Once you load it in a running Lisp, you're ready to use asdf.  For
-maximum convenience you might want to have asdf loaded whenever you
-start your Lisp implementation, for example by loading it from the
-startup script or dumping a custom core -- check your Lisp
-implementation's manual for details.
-
-The variable @code{asdf:*central-registry*} is a list of ``system
-directory designators''@footnote{When we say ``directory'' here, we
-mean ``designator for a pathname with a supplied DIRECTORY
-component''.}.  A @dfn{system directory designator} is a form which
-will be evaluated whenever a system is to be found, and must evaluate
-to a directory to look in.  You might want to set or augment
-@code{*central-registry*} in your Lisp init file, for example:
+@chapter Introduction
+@cindex ASDF-related features
+@vindex *features*
+@cindex Testing for ASDF
+@cindex ASDF versions
+@cindex :asdf
+@cindex :asdf2
+@cindex :asdf3
+
+ASDF is Another System Definition Facility:
+a tool for specifying how systems of Common Lisp software
+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,
+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},
+to learn how to define a system of your own.
+@xref{The object model of ASDF}, for a description of
+the ASDF internals and how to extend ASDF.
+
+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
+(@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 (@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.
+
+@node  Quick start summary, Loading ASDF, Introduction, Top
+@chapter Quick start summary
+
+@itemize
+
+@item To load an ASDF system:
+
+@itemize
+@item
+Load ASDF itself into your Lisp image, either through
+@code{(require "asdf")} (if it's supplied by your lisp implementation)
+or else through
+@code{(load "/path/to/asdf.lisp")}.  For more details, @ref{Loading ASDF}.
+
+@item
+Make sure ASDF can find system definitions
+through proper source-registry configuration.
+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),
+or @file{~/.local/share/common-lisp/source/}
+(for ASDF 2 and later, or if you want to keep source in a hidden directory).
+Such code will automatically be found.
+
+@item
+Load a system with @code{(asdf:load-system :system)}. @xref{Using ASDF}.
+
+@end itemize
+
+@item To make your own ASDF system:
+
+@itemize
+@item
+As above, load and configure ASDF.
+
+@item
+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
+Create an ASDF system definition listing the dependencies of
+your system, its components, and their interdependencies,
+and put it in @file{my-system.asd}.
+This file must have the same name as your system.
+@xref{Defining systems with defsystem}.
+
+@item
+Use @code{(asdf:load-system :my-system)}
+to make sure it's all working properly. @xref{Using ASDF}.
+
+@end itemize
+@end itemize
+
+@c FIXME: (1) add a sample project that the user can cut and paste to
+@c get started.  (2) discuss the option of starting with Quicklisp.
+
+
+
+
+
+@node Loading ASDF, Configuring ASDF, Quick start summary, Top
+@comment  node-name,  next,  previous,  up
+@chapter Loading ASDF
+
+@menu
+* Loading a pre-installed ASDF::
+* Checking whether ASDF is loaded::
+* Upgrading ASDF::
+* Loading ASDF from source::
+@end menu
+
+@node  Loading a pre-installed ASDF, Checking whether ASDF is loaded, Loading ASDF, Loading ASDF
+@section Loading a pre-installed ASDF
+
+Most recent Lisp implementations include a copy of ASDF 3,
+or at least ASDF 2.
+You can usually load this copy using Common Lisp's @code{require} function.@footnote{
+NB: all implementations except GNU CLISP also accept
+@code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}.
+For portability's sake, you should use @code{(require "asdf")}.
+}
 
 @lisp
-(setf asdf:*central-registry*
-  (list* '*default-pathname-defaults*
-         #p"/home/me/cl/systems/"
-         #p"/usr/share/common-lisp/systems/"
-         asdf:*central-registry*))
+(require "asdf")
 @end lisp
 
-@section Setting up a system to be loaded
-
-To compile and load a system, you need to ensure that a symbolic link to its
-system definition is in one of the directories in
-@code{*central-registry*}@footnote{It is possible to customize the
-system definition file search.  That's considered advanced use, and
-covered later: search forward for
-@code{*system-definition-search-functions*}.  @xref{Defining systems
-with defsystem}.}.
-
-For example, if @code{#p"/home/me/cl/systems/"} (note the trailing
-slash) is a member of @code{*central-registry*}, you would set up a
-system @var{foo} that is stored in a directory
-@file{/home/me/src/foo/} for loading with asdf with the following
-commands at the shell (this has to be done only once):
+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.
+The following implementations only provide ASDF 2:
+LispWorks, mocl, XCL.
+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 ASDF from source} below.
+If that implementation is still actively maintained,
+you may also send a bug report to your Lisp vendor and complain
+about their failing to provide ASDF.
+
+@node Checking whether ASDF is loaded, Upgrading ASDF, Loading a pre-installed ASDF, Loading ASDF
+@section Checking whether ASDF is loaded
+
+To check whether ASDF is properly loaded in your current Lisp image,
+you can run this form:
+
+@lisp
+(asdf:asdf-version)
+@end lisp
+
+If it returns a string,
+that is the version of ASDF that is currently installed.
+
+If it raises an error,
+then either ASDF is not loaded, or
+you are using a very old version of ASDF,
+and need to install ASDF 3.
+
+You can check whether an old version is loaded
+by checking if the ASDF package is present.
+The form below will allow you to programmatically determine
+whether a recent version is loaded, an old version is loaded,
+or none at all:
+
+@lisp
+(when (find-package :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)))))
+      (null "1.0"))))
+@end lisp
+
+If it returns @code{nil} then ASDF is not installed.
+Otherwise it should return a string.
+If it returns @code{"1.0"}, then it can actually be
+any version before 1.77 or so, or some buggy variant of 1.x.
+
+If you are experiencing problems with ASDF,
+please try upgrading to the latest released version,
+using the method below,
+before you contact us and raise an issue.
+
+@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
+@c doesn't matter to almost anyone.  Move discussion of updating antique
+@c versions of ASDF down, or encapsulate it.
+
+If you want to upgrade to a more recent ASDF version,
+you need to install and configure your ASDF just like any other system
+(@pxref{Configuring ASDF to find your systems}).
+
+If your implementation provides ASDF 3 or later,
+you only need to @code{(require "asdf")}:
+ASDF will automatically look whether an updated version of itself is available
+amongst the regularly configured systems, before it compiles anything else.
+
+@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 after loading ASDF from source.
+
+Finally, if your implementation only provides ASDF 2,
+and you can't or won't upgrade it or override its ASDF module,
+you may simply configure ASDF to find a proper upgrade;
+however, to avoid issues with a self-upgrade in mid-build,
+you @emph{must} make sure to upgrade ASDF immediately
+after requiring the builtin ASDF 2:
+
+@lisp
+(require "asdf")
+;; <--- insert programmatic configuration here if needed
+(asdf:load-system :asdf)
+@end lisp
+
+@node Issues with upgrading ASDF,  , Upgrading your implementation's ASDF, Upgrading ASDF
+@subsection Issues with upgrading ASDF
+
+Note that there are some limitations to upgrading ASDF:
+@itemize
+@item
+Previously loaded ASDF extensions become invalid, and will need to be reloaded.
+Examples include CFFI-Grovel, hacks used by ironclad, etc.
+Since it isn't possible to automatically detect what extensions
+need to be invalidated,
+ASDF will invalidate @emph{all} previously loaded systems
+when it is loaded on top of a forward-incompatible ASDF version.
+@footnote{
+@vindex *oldest-forward-compatible-asdf-version*
+Forward incompatibility can be determined using the variable
+@code{asdf/upgrade::*oldest-forward-compatible-asdf-version*},
+which is 2.33 at the time of this writing.}
+
+Starting with ASDF 3 (2.27 or later),
+this self-upgrade will be automatically attempted as the first step
+to any system operation, to avoid any possibility of
+a catastrophic attempt to self-upgrade in mid-build.
+
+@c FIXME: Fix grammar below.
+@item
+For this and many other reasons,
+you should load, configure and upgrade ASDF
+as one of the very first things done by your build and startup scripts.
+It is safer if you upgrade ASDF and its extensions as a special step
+at the very beginning of whatever script you are running,
+before you start using ASDF to load anything else.
+
+@item
+Until all implementations provide ASDF 3 or later,
+it is unsafe to upgrade ASDF as part of loading a system
+that depends on a more recent version of ASDF,
+since the new one might shadow the old one while the old one is running,
+and the running old one will be confused
+when extensions are loaded into the new one.
+In the meantime, we recommend that your systems should @emph{not} specify
+@code{:depends-on (:asdf)}, or @code{:depends-on ((:version :asdf "3.0.1"))},
+but instead that they check that a recent enough ASDF is installed,
+with such code as:
+@example
+(unless (or #+asdf2 (asdf:version-satisfies
+                     (asdf:asdf-version) *required-asdf-version*))
+  (error "FOO requires ASDF ~A or later." *required-asdf-version*))
+@end example
+@item
+Until all implementations provide ASDF 3 or later,
+it is unsafe for a system to transitively depend on ASDF
+and not directly depend on ASDF;
+if any of the system you use either depends-on asdf,
+system-depends-on asdf, or transitively does,
+you should also do as well.
+@end itemize
+
+@node Loading ASDF from source,  , Upgrading ASDF, Loading ASDF
+@section Loading ASDF from source
+
+If your implementation doesn't include ASDF,
+if for some reason the upgrade somehow fails,
+does not or cannot apply to your case,
+you will have to install the file @file{asdf.lisp}
+somewhere and load it with:
+
+@lisp
+(load "/path/to/your/installed/asdf.lisp")
+@end lisp
+
+The single file @file{asdf.lisp} is all you normally need to use ASDF.
+
+You can extract this file from latest release tarball on the
+@url{http://common-lisp.net/project/asdf/,ASDF website}.
+If you are daring and willing to report bugs, you can get
+the latest and greatest version of ASDF from its git repository.
+@xref{Getting the latest version}.
+
+For maximum convenience you might want to have ASDF loaded
+whenever you start your Lisp implementation,
+for example by loading it from the startup script or dumping a custom core
+--- check your Lisp implementation's manual for details.
+
+
+@node Configuring ASDF, Using ASDF, Loading ASDF, Top
+@comment  node-name,  next,  previous,  up
+@chapter Configuring ASDF
+
+For standard use cases, ASDF should work pretty much out of the box.
+We recommend you skim the sections on configuring ASDF to find your systems
+and choose the method of installing Lisp software that works best for you.
+Then skip directly to @xref{Using ASDF}. That will probably be enough.
+You are unlikely to have to worry about the way ASDF stores object files,
+and resetting the ASDF configuration is usually only needed in corner cases.
+
+
+@menu
+* Configuring ASDF to find your systems::
+* Configuring ASDF to find your systems --- old style::
+* Configuring where ASDF stores object files::
+* Resetting the ASDF configuration::
+@end menu
+
+@node Configuring ASDF to find your systems, Configuring ASDF to find your systems --- old style, Configuring ASDF, Configuring ASDF
+@section Configuring ASDF to find your systems
+
+In order to compile and load your systems, ASDF must be configured to find
+the @file{.asd} files that contain system definitions.
+
+There are a number of different techniques for setting yourself up with
+ASDF, starting from easiest to the most complex:
+
+@itemize @bullet
+
+@item
+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/}.
+@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.1 or later.}
+
+@item
+If you're using some tool to install software (e.g. Quicklisp),
+the authors of that tool should already have configured ASDF.
+
+@item
+If you have more specific desires about how to lay out your software on
+disk, the preferred way to configure where ASDF finds your systems is
+the @code{source-registry} facility,
+fully described in its own chapter of this manual.
+@xref{Controlling where ASDF searches for systems}.  Here is a quick
+recipe for getting started:
+
+The simplest way to add a path to your search path,
+say @file{/home/luser/.asd-link-farm/}
+is to create the directory
+@file{~/.config/common-lisp/source-registry.conf.d/}
+and there create a file with any name of your choice,
+and with the type @file{conf}@footnote{By requiring the @file{.conf}
+extension, and ignoring other files, ASDF allows you to have disabled files,
+editor backups, etc. in the same directory with your active
+configuration files.
+
+ASDF will also ignore files whose names start with a @file{.} character.
+
+It is customary to start the filename with two digits, to control the
+sorting of the @code{conf} files in the source registry directory, and
+thus the order in which the directories will be scanned.},
+for instance @file{42-asd-link-farm.conf},
+containing the line:
+
+@kbd{(:directory "/home/luser/.asd-link-farm/")}
+
+If you want all the subdirectories under @file{/home/luser/lisp/}
+to be recursively scanned for @file{.asd} files, instead use:
+
+@kbd{(:tree "/home/luser/lisp/")}
+
+ASDF will automatically read your configuration
+the first time you try to find a system.
+If necessary, you can reset the source-registry configuration with:
+
+@lisp
+(asdf:clear-source-registry)
+@end lisp
+
+@item
+In earlier versions of ASDF, the system source registry was configured
+using a global variable, @code{asdf:*central-registry*}.
+For more details about this, see the following section,
+@ref{Configuring ASDF to find your systems --- old style}.
+Unless you need to understand this,
+skip directly to @ref{Configuring where ASDF stores object files}.
+
+@end itemize
+
+Note that your Operating System distribution or your system administrator
+may already have configured system-managed libraries for you.
+
+
+
+@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]
+
+
+The old way to configure ASDF to find your systems is by
+@code{push}ing directory pathnames onto the variable
+@code{asdf:*central-registry*}.
+
+You must configure this variable between the time you load ASDF
+and the time you first try to use it.
+Loading and configuring ASDF presumably happen
+as part of some initialization script that builds or starts
+your Common Lisp software system.
+(For instance, some SBCL users used to put it in their @file{~/.sbclrc}.)
+
+The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
+but is still supported for compatibility with ASDF 1.
+When used, it takes precedence over the above source-registry.@footnote{
+It is possible to further customize
+the system definition file search.
+That's considered advanced use, and covered later:
+search forward for
+@code{*system-definition-search-functions*}.
+@xref{Defining systems with defsystem}.}
+
+For example, let's say you want ASDF to find the @file{.asd} file
+@file{/home/me/src/foo/foo.asd}.
+In your lisp initialization file, you could have the following:
+
+@lisp
+(require "asdf")
+(push "/home/me/src/foo/" asdf:*central-registry*)
+@end lisp
+
+Note the trailing slash: when searching for a system,
+ASDF will evaluate each entry of the central registry
+and coerce the result to a pathname.@footnote{
+ASDF will indeed call @code{eval} on each entry.
+It will skip entries that evaluate to @code{nil}.
+
+Strings and pathname objects are self-evaluating,
+in which case the @code{eval} step does nothing;
+but you may push arbitrary s-expressions onto the central registry.
+These s-expressions may be evaluated to compute context-dependent
+entries, e.g. things that depend
+on the value of shell variables or the identity of the user.
+
+The variable @code{asdf:*central-registry*} is thus a list of
+``system directory designators''.
+A @dfn{system directory designator} is a form
+which will be evaluated whenever a system is to be found,
+and must evaluate to a directory to look in (or @code{NIL}).
+By ``directory'', we mean
+``designator for a pathname with a non-empty DIRECTORY component''.
+}
+The trailing directory name separator
+is necessary to tell Lisp that you're discussing a directory
+rather than a file.  If you leave it out, ASDF is likely to look in
+@code{/home/me/src/} instead of @code{/home/me/src/foo/} as you
+intended, and fail to find your system definition.
+
+Typically there are a lot of @file{.asd} files, and
+a common idiom was to put
+@emph{symbolic links} to all of one's @file{.asd} files
+in a common directory
+and push @emph{that} directory (the ``link farm'')
+onto
+@code{asdf:*central-registry*},
+instead of pushing each individual system directory.
+
+ASDF knows to follow @emph{symlinks}
+to the actual location of the systems.@footnote{
+On Windows, you can use Windows shortcuts instead of POSIX symlinks.
+if you try aliases under MacOS, we are curious to hear about your experience.}
+
+For example, if @code{#p"/home/me/cl/systems/"}
+is an element of @code{*central-registry*}, you could set up the
+system @var{foo} as follows:
 
 @example
 $ cd /home/me/cl/systems/
 $ ln -s ~/src/foo/foo.asd .
 @end example
 
+This old style for configuring ASDF is not recommended for new users,
+but it is supported for old users, and for users who want to programmatically
+control what directories are added to the ASDF search path.
+
+
+@node Configuring where ASDF stores object files, Resetting the ASDF configuration, Configuring ASDF to find your systems --- old style, Configuring ASDF
+@section Configuring where ASDF stores object files
+@findex clear-output-translations
+
+ASDF lets you configure where object files will be stored.
+Sensible defaults are provided and
+you shouldn't normally have to worry about it.
+
+This allows the same source code repository to be shared
+between several versions of several Common Lisp implementations,
+between several users using different compilation options,
+with users who lack write privileges on shared source directories, etc.
+This also keeps source directories from being cluttered
+with object/fasl files.
+
+Starting with ASDF 2, the @code{asdf-output-translations} facility
+was added to ASDF itself.  This facility controls where object files will be stored.
+This facility is fully described in a chapter of this manual,
+@ref{Controlling where ASDF saves compiled files}.
+
+@c FIXME: possibly this should be moved elsewhere.  It's redundant here,
+@c and makes this section of the manual too long and daunting for the
+@c new user. [2014/02/27:rpg]
+@c The simplest way to add a translation to your search path,
+@c say from @file{/foo/bar/baz/quux/}
+@c to @file{/where/i/want/my/fasls/}
+@c is to create the directory
+@c @file{~/.config/common-lisp/asdf-output-translations.conf.d/}
+@c and there create a file with any name of your choice and the type @file{conf},
+@c for instance @file{42-bazquux.conf}
+@c containing the line:
+
+@c @kbd{("/foo/bar/baz/quux/" "/where/i/want/my/fasls/")}
+
+@c To disable output translations for source under a given directory,
+@c say @file{/toto/tata/}
+@c you can create a file @file{40-disable-toto.conf}
+@c with the line:
+
+@c @kbd{("/toto/tata/")}
+
+@c To wholly disable output translations for all directories,
+@c you can create a file @file{00-disable.conf}
+@c with the line:
+
+@c @kbd{(t t)}
+
+@c Note that your Operating System distribution or your system administrator
+@c may already have configured translations for you.
+@c In absence of any configuration, the default is to redirect everything
+@c under an implementation-dependent subdirectory of @file{~/.cache/common-lisp/}.
+@c @xref{Controlling where ASDF searches for systems}, for full details.
+
+@c The required @file{.conf} extension allows you to have disabled files
+@c or editor backups (ending in @file{~}), and works portably
+@c (for instance, it is a pain to allow both empty and non-empty extension on CLISP).
+@c Excluded are files the name of which start with a @file{.} character.
+@c It is customary to start the filename with two digits
+@c that specify the order in which the directories will be scanned.
+
+@c ASDF will automatically read your configuration
+@c the first time you try to find a system.
+@c You can reset the source-registry configuration with:
+
+@c @lisp
+@c (asdf:clear-output-translations)
+@c @end lisp
+
+@c And you probably should do so before you dump your Lisp image,
+@c if the configuration may change
+@c between the machine where you save it at the time you save it
+@c and the machine you resume it at the time you resume it.
+@c (Once again, you should use @code{(asdf:clear-configuration)}
+@c before you dump your Lisp image, which includes the above.)
+
+Note that before ASDF 2,
+other ASDF add-ons offered the same functionality,
+each in subtly different and incompatible ways:
+ASDF-Binary-Locations, cl-launch, common-lisp-controller.
+ASDF-Binary-Locations is now not needed anymore and should not be used.
+cl-launch 3.000 and common-lisp-controller 7.2 have been updated
+to delegate object file placement to ASDF.
+
+@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]
+
+
+When you dump and restore an image, or when you tweak your configuration,
+you may want to reset the ASDF configuration.
+For that you may use the following function:
+
+@defun clear-configuration
+   Undoes any ASDF configuration
+   regarding source-registry or output-translations.
+@end defun
+
+This function is pushed onto the @code{uiop:*image-dump-hook*} by default,
+which means that if you save an image using @code{uiop:dump-image},
+or via @code{asdf:image-op} and @code{asdf:program-op},
+it will be automatically called to clear your configuration.
+If for some reason you prefer to call your implementation's underlying functionality,
+be sure to call @code{clear-configuration} manually,
+or push it into your implementation's equivalent of @code{uiop:*image-dump-hook*},
+e.g. @code{sb-ext:*save-hooks*} on SBCL, or @code{ext:*before-save-initializations*}
+on CMUCL and SCL, etc.
+
+@node  Using ASDF, Defining systems with defsystem, Configuring ASDF, Top
+@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
 
-The system @var{foo} is loaded (and compiled, if necessary) by
-evaluating the following form in your Lisp implementation:
+The system @var{foo} is loaded (and compiled, if necessary)
+by evaluating the following Lisp form:
 
 @example
-(asdf:operate 'asdf:load-op '@var{foo})
+(asdf:load-system :@var{foo})
 @end example
 
-That's all you need to know to use asdf to load systems written by
-others.  The rest of this manual deals with writing system
-definitions for Lisp software you write yourself.
-
-@node   Defining systems with defsystem, The object model of asdf, Using asdf to load systems, Top
+On some implementations (namely recent versions of
+ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL),
+ASDF hooks into the @code{CL:REQUIRE} facility
+and you can just use:
+
+@example
+(require :@var{foo})
+@end example
+
+In older versions of ASDF, you needed to use
+@code{(asdf:oos 'asdf:load-op :@var{foo})}.
+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 ASDF from source}.
+
+Note the name of a system is specified as a string or a symbol.
+If a symbol (including a keyword), its name is taken and lowercased.
+The name must be a suitable value for the @code{:name} initarg
+to @code{make-pathname} in whatever filesystem the system is to be
+found.
+
+The lower-casing-symbols behaviour is unconventional,
+but was selected after some consideration.
+The type of systems we want to support
+either have lowercase as customary case (Unix, Mac, Windows)
+or silently convert lowercase to uppercase (lpns).
+@c so this makes more sense than attempting to use @code{:case :common},
+@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}, 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 stands for operate-on-system).
+You'll use @code{oos} whenever you want to do something beyond
+compiling, loading and testing.
+
+Output from ASDF and ASDF extensions are sent
+to the CL stream @code{*standard-output*},
+so rebinding that stream around calls to @code{asdf:operate}
+should redirect all output from ASDF operations.
+
+@c Reminder: before ASDF can operate on a system, however,
+@c it must be able to find and load that system's definition.
+@c @xref{Configuring ASDF,,Configuring ASDF to find your systems}.
+
+@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}
+with keyword arguments @code{:force-not (already-loaded-systems)}.
+@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}),
+the system, and any provided keyword arguments.
+
+
+@node Moving on,  , Other Operations, Using ASDF
+@section Moving on
+
+That's all you need to know to use ASDF to load systems written by others.
+The rest of this manual deals with writing system definitions
+for Common Lisp software you write yourself,
+including how to extend ASDF to define new operation and component types.
+
+
+@node Defining systems with defsystem, The object model of ASDF, Using ASDF, Top
 @comment  node-name,  next,  previous,  up
 @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.
 
 
 @menu
-* The defsystem form::          
-* A more involved example::     
-* The defsystem grammar::       
+* The defsystem form::
+* A more involved example::
+* The defsystem grammar::
+* Other code in .asd files::
+* The package-inferred-system extension::
 @end menu
 
 @node  The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
 @comment  node-name,  next,  previous,  up
 @section The defsystem form
-
-Systems can be constructed programmatically by instantiating
-components using make-instance.  Most of the time, however, it is much
-more practical to use a static @code{defsystem} form.  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}:
+@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 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
-(defpackage hello-lisp-system
-  (:use :common-lisp :asdf))
-
-(in-package :hello-lisp-system)
+(in-package :asdf-user)
 
 (defsystem "hello-lisp"
-    :description "hello-lisp: a sample Lisp system."
-    :version "0.2"
-    :author "Joe User <joe@@example.com>"
-    :licence "Public Domain"
-    :components ((:file "packages")
-                 (:file "macros" :depends-on ("packages"))
-                 (:file "hello" :depends-on ("macros"))))
+  :description "hello-lisp: a sample Lisp system."
+  :version "0.0.1"
+  :author "Joe User <joe@@example.com>"
+  :licence "Public Domain"
+  :components ((:file "packages")
+               (:file "macros" :depends-on ("packages"))
+               (:file "hello" :depends-on ("macros"))))
 @end lisp
 
 Some notes about this example:
@@ -240,201 +1079,823 @@
 @itemize
 
 @item
-The file starts with @code{defpackage} and @code{in-package} forms to
-make and use a package expressly for defining this system in.  This
-package is named by taking the system name and suffixing
-@code{-system} - note that it is @emph{not} the same package as you
-will use for the application code.
-
-This is not absolutely required by asdf, but helps avoid namespace
-pollution and so is considered good form. 
-
-@item
-The defsystem form defines a system named "hello-lisp" that contains
-three source files: @file{packages}, @file{macros} and @file{hello}.
-
-@item
-The file @file{macros} depends on @file{packages} (presumably because
-the package it's in is defined in @file{packages}), and the file
-@file{hello} depends on @file{macros} (and hence, transitively on
-@file{packages}).  This means that asdf will compile and load
-@file{packages} and @file{macros} before starting the compilation of
-file @file{hello}.
-
-
-@item
-The files are located in the same directory as the file with the
-system definition.  asdf resolves symbolic links 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.
+The file starts with an @code{in-package} form
+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
+The @code{defsystem} form defines a system named @code{hello-lisp}
+that contains three source files:
+@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}
+(presumably because the package it's in is defined in @file{packages}),
+and the file @file{hello} depends on @file{macros}
+(and hence, transitively on @file{packages}).
+This means that ASDF will compile and load @file{packages} and @file{macros}
+before starting the compilation of file @file{hello}.
+
+@item
+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!
+Only period-separated non-negative integers are accepted.
+See below Version specifiers in @ref{The defsystem grammar}.
+@cindex :version
 
 @end itemize
 
 @node  A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
 @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
 slightly convoluted example:
 
 @lisp
+(in-package :asdf-user)
+
 (defsystem "foo"
-  :version "1.0"
-  :components ((:module "foo" :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)))
+  :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")))
 @end lisp
 
-The method-form tokens need explaining: essentially, this part:
+The @code{:module} component named @code{"mod"} is a collection of three files,
+which will be located in a subdirectory of the main code directory named
+@file{mod} (this location can be overridden; see the discussion of the
+@code{:pathname} option in @ref{The defsystem grammar}).
+
+The method-form tokens provide a shorthand for defining methods on
+particular components.  This part
 
 @lisp
-	        :perform (compile-op :after (op c)
-			  (do-something c))
-		:explain (compile-op :after (op c)
-			  (explain-something c))
+                :perform (compile-op :after (op c)
+                          (do-something c))
+                :explain (compile-op :after (op c)
+                          (explain-something c))
 @end lisp
 
 has the effect of
 
 @lisp
 (defmethod perform :after ((op compile-op) (c (eql ...)))
-	   (do-something c))
+           (do-something c))
 (defmethod explain :after ((op compile-op) (c (eql ...)))
-	   (explain-something c))
+           (explain-something c))
 @end lisp
 
-where @code{...} is the component in question; note that although this
-also supports @code{:before} methods, they may not do what you want
-them to -- a @code{:before} method on perform @code{((op compile-op) (c
-(eql ...)))}  will run after all the dependencies and sub-components
-have been processed, but before the component in question has been
-compiled.
-
-@node  The defsystem grammar,  , A more involved example, Defining systems with defsystem
+where @code{...} is the component in question.
+In this case @code{...} would expand to something like
+
+@lisp
+(find-component "foo" "mod")
+@end lisp
+
+For more details on the syntax of such forms, see @ref{The defsystem
+grammar}.
+For more details on what these methods do, @pxref{Operations} in
+@ref{The object model of ASDF}.
+
+@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,
+@c they may not do what you want them to ---
+@c a @code{:before} method on perform @code{((op compile-op) (c (eql ...)))}
+@c will run after all the dependencies and sub-components have been processed,
+@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
-
-@verbatim
-system-definition := ( defsystem system-designator {option}* )
-
-option := :components component-list
-        | :pathname pathname
-        | :default-component-class
-        | :perform method-form 
+@findex defsystem
+@cindex DEFSYSTEM grammar
+
+@c FIXME: @var typesetting not consistently used here.  We should either expand
+@c its use to everywhere, or we should kill it everywhere.
+
+
+@example
+system-definition := ( defsystem system-designator @var{system-option}* )
+
+system-option := :defsystem-depends-on system-list
+                 | :weakly-depends-on @var{system-list}
+                 | :class class-name (see discussion below)
+                 | module-option
+                 | option
+
+module-option := :components component-list
+                 | :serial [ t | nil ]
+
+option :=
+        | :pathname pathname-specifier
+        | :default-component-class class-name
+        | :perform method-form
         | :explain method-form
-	| :output-files  method-form
+        | :output-files method-form
         | :operation-done-p method-form
-        | :depends-on ( {simple-component-name}* ) 
-	| :serial [ t | nil ]
-        | :in-order-to ( {dependency}+ )
-
-component-list := ( {component-def}* )
-                
-component-def  := simple-component-name
-                | ( component-type name {option}* )
-
-component-type := :module | :file | :system | other-component-type
-
-dependency := (dependent-op {requirement}+)
-requirement := (required-op {required-component}+)
-             | (feature feature-name)
+        | :if-feature feature-expression
+        | :depends-on ( @var{dependency-def}* )
+        | :in-order-to ( @var{dependency}+ )
+
+
+system-list := ( @var{simple-component-name}* )
+
+component-list := ( @var{component-def}* )
+
+component-def  := ( component-type simple-component-name @var{option}* )
+
+component-type := :module | :file | :static-file | other-component-type
+
+other-component-type := symbol-by-name
+                        (@pxref{The defsystem grammar,,Component types})
+
+# This is used in :depends-on, as opposed to ``dependency,''
+# which is used in :in-order-to
+dependency-def := simple-component-name
+               | ( :feature @var{feature-expression} dependency-def )
+               | ( :version simple-component-name version-specifier )
+               | ( :require module-name )
+
+# ``dependency'' is used in :in-order-to, as opposed to
+# ``dependency-def''
+dependency := (dependent-op @var{requirement}+)
+requirement := (required-op @var{required-component}+)
 dependent-op := operation-name
-required-op := operation-name | feature
-@end verbatim
+required-op := operation-name
+
+simple-component-name := string
+                      |  symbol
+
+pathname-specifier := pathname | string | symbol
+
+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})
+@end example
+
+
+@subsection Component names
+
+Component names (@code{simple-component-name})
+may be either strings or symbols.
+
+@subsection Component types
+
+Component type names, even if expressed as keywords, will be looked up
+by name in the current package and in the asdf package, if not found in
+the current package.  So a component type @code{my-component-type}, in
+the current package @code{my-system-asd} can be specified as
+@code{:my-component-type}, or @code{my-component-type}.
+
+@code{system} and its subclasses are @emph{not}
+allowed as component types for such children components.
+
+@subsection System class names
+
+A system class name will be looked up
+in the same way as a Component type (see above),
+except that only @code{system} and its subclasses are allowed.
+Typically, one will not need to specify a system
+class name, unless using a non-standard system class defined in some
+ASDF extension, typically loaded through @code{DEFSYSTEM-DEPENDS-ON},
+see below.  For such class names in the ASDF package, we recommend that
+the @code{:class} option be specified using a keyword symbol, such as
+
+@example
+:class :MY-NEW-SYSTEM-SUBCLASS
+@end example
+
+This practice will ensure that package name conflicts are avoided.
+Otherwise, the symbol @code{MY-NEW-SYSTEM-SUBCLASS} will be read into
+the current package @emph{before} it has been exported from the ASDF
+extension loaded by @code{:defsystem-depends-on}, causing a name
+conflict in the current package.
+
+@subsection Defsystem depends on
+@cindex :defsystem-depends-on
+
+The @code{:defsystem-depends-on} option to @code{defsystem} allows the
+programmer to specify another ASDF-defined system or set of systems that
+must be loaded @emph{before} the system definition is processed.
+Typically this is used to load an ASDF extension that is used in the
+system definition.
+
+@subsection Weakly depends on
+@cindex :weakly-depends-on
+
+We do @emph{NOT} recommend you use this feature.
+If you are tempted to write a system @var{foo}
+that weakly-depends-on a system @var{bar},
+we recommend that you should instead
+write system @var{foo} in a parametric way,
+and offer some special variable and/or some hook to specialize its behavior;
+then you should write a system @var{foo+bar}
+that does the hooking of things together.
+
+The (deprecated) @code{:weakly-depends-on} option to @code{defsystem}
+allows the programmer to specify another ASDF-defined system or set of systems
+that ASDF should @emph{try} to load,
+but need not load in order to be successful.
+Typically this is used if there are a number of systems
+that, if present, could provide additional functionality,
+but which are not necessary for basic function.
+
+Currently, although it is specified to be an option only to @code{defsystem},
+this option is accepted at any component, but it probably
+only makes sense at the @code{defsystem} level.
+Programmers are cautioned not
+to use this component option except at the @code{defsystem} level, as
+this anomalous behavior may be removed without warning.
+
+@c Finally, you might look into the @code{asdf-system-connections} extension,
+@c that will let you define additional code to be loaded
+@c when two systems are simultaneously loaded.
+@c It may or may not be considered good style, but at least it can be used
+@c in a way that has deterministic behavior independent of load order,
+@c unlike @code{weakly-depends-on}.
+
+
+@subsection Pathname specifiers
+@cindex pathname specifiers
+
+A pathname specifier (@code{pathname-specifier})
+may be a pathname, a string or a symbol.
+When no pathname specifier is given for a component,
+which is the usual case, the component name itself is used.
+
+If a string is given, which is the usual case,
+the string will be interpreted as a Unix-style pathname
+where @code{/} characters will be interpreted as directory separators.
+Usually, Unix-style relative pathnames are used
+(i.e. not starting with @code{/}, as opposed to absolute pathnames);
+they are relative to the path of the parent component.
+Finally, depending on the @code{component-type},
+the pathname may be interpreted as either a file or a directory,
+and if it's a file,
+a file type may be added corresponding to the @code{component-type},
+or else it will be extracted from the string itself (if applicable).
+
+For instance, the @code{component-type} @code{:module}
+wants a directory pathname, and so a string @code{"foo/bar"}
+will be interpreted as the pathname @file{#p"foo/bar/"}.
+On the other hand, the @code{component-type} @code{:file}
+wants a file of type @code{lisp}, and so a string @code{"foo/bar"}
+will be interpreted as the pathname @file{#p"foo/bar.lisp"},
+and a string @code{"foo/bar.quux"}
+will be interpreted as the pathname @file{#p"foo/bar.quux.lisp"}.
+Finally, the @code{component-type} @code{:static-file}
+wants a file without specifying a type, and so a string @code{"foo/bar"}
+will be interpreted as the pathname @file{#p"foo/bar"},
+and a string @code{"foo/bar.quux"}
+will be interpreted as the pathname @file{#p"foo/bar.quux"}.
+
+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,
+and downcased in the process.
+The downcasing of symbols is unconventional,
+but was selected after some consideration.
+Observations suggest that the type of systems we want to support
+either have lowercase as customary case (Unix, Mac, windows)
+or silently convert lowercase to uppercase (lpns),
+so this makes more sense than attempting to use @code{:case :common}
+as argument to @code{make-pathname},
+which is reported not to work on some implementations.
+
+Pathname objects may be given to override the path for a component.
+Such objects are typically specified using reader macros such as @code{#p}
+or @code{#.(make-pathname ...)}.
+Note however, that @code{#p...} is
+a shorthand for @code{#.(parse-namestring ...)}
+and that the behavior of @code{parse-namestring} is completely non-portable,
+unless you are using Common Lisp @code{logical-pathname}s,
+which themselves involve other non-portable behavior
+(@pxref{The defsystem grammar,,Using logical pathnames}, below).
+Pathnames made with @code{#.(make-pathname ...)}
+can usually be done more easily with the string syntax above.
+The only case that you really need a pathname object is to override
+the component-type default file type for a given component.
+Therefore, pathname objects should only rarely be used.
+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.
+An alternative to @code{#.} read-time evaluation is to use
+@code{(eval `(defsystem ... ,pathname ...))}.
+
+Note that when specifying pathname objects,
+ASDF does not do any special interpretation of the pathname
+influenced by the component type, unlike the procedure for
+pathname-specifying strings.
+On the one hand, you have to be careful to provide a pathname that correctly
+fulfills whatever constraints are required from that component type
+(e.g. naming a directory or a file with appropriate type);
+on the other hand, you can circumvent the file type that would otherwise
+be forced upon you if you were specifying a string.
+
+@subsection Version specifiers
+@cindex version specifiers
+@cindex :version
+
+Version specifiers are strings to be 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"},
+though the latter is not canonical and may lead to a warning being issued.
+Also, @code{"1.3"} and @code{"1.4"} are both strictly @code{uiop:version<} to @code{"1.30"},
+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
+@var{x}.@var{y}.@var{z} for
+major version, minor version and patch level,
+where significant API incompatibilities are signaled by an increased major number.
+
+@xref{Common attributes of components}.
+
+@subsection Require
+@cindex :require dependencies
+
+Use the implementation's own @code{require} to load the @var{module-name}.
+
+
+@subsection Using logical pathnames
+@cindex logical pathnames
+
+We do not generally recommend the use of logical pathnames,
+especially not so to newcomers to Common Lisp.
+However, we do support the use of logical pathnames by old timers,
+when such is their preference.
+
+To use logical pathnames,
+you will have to provide a pathname object as a @code{:pathname} specifier
+to components that use it, using such syntax as
+@code{#p"LOGICAL-HOST:absolute;path;to;component.lisp"}.
+
+You only have to specify such logical pathname
+for your system or some top-level component.
+Sub-components' relative pathnames,
+specified using the string syntax for names,
+will be properly merged with the pathnames of their parents.
+The specification of a logical pathname host however is @emph{not}
+otherwise directly supported in the ASDF syntax
+for pathname specifiers as strings.
+
+The @code{asdf-output-translation} layer will
+avoid trying to resolve and translate logical pathnames.
+The advantage of this is that
+you can define yourself what translations you want to use
+with the logical pathname facility.
+The disadvantage is that if you do not define such translations,
+any system that uses logical pathnames will behave differently under
+asdf-output-translations than other systems you use.
+
+If you wish to use logical pathnames you will have to configure the
+translations yourself before they may be used.
+ASDF currently provides no specific support
+for defining logical pathname translations.
+
+Note that the reasons we do not recommend logical pathnames are that
+(1) there is no portable way to set up logical pathnames before they are used,
+(2) logical pathnames are limited to only portably use
+a single character case, digits and hyphens.
+While you can solve the first issue on your own,
+describing how to do it on each of fifteen implementations supported by ASDF
+is more than we can document.
+As for the second issue, mind that the limitation is notably enforced on SBCL,
+and that you therefore can't portably violate the limitations
+but must instead define some encoding of your own and add individual mappings
+to name physical pathnames that do not fit the restrictions.
+This can notably be a problem when your Lisp files are part of a larger project
+in which it is common to name files or directories in a way that
+includes the version numbers of supported protocols,
+or in which files are shared with software written
+in different programming languages where conventions include the use of
+underscores, dots or CamelCase in pathnames.
+
 
 @subsection Serial dependencies
-
-If the @code{:serial t} option is specified for a module, asdf will add
-dependencies for each each child component, on all the children
-textually preceding it.  This is done as if by @code{:depends-on}.
+@cindex serial dependencies
+
+If the @code{:serial t} option is specified for a module,
+ASDF will add dependencies for each child component,
+on all the children textually preceding it.
+This is done as if by @code{:depends-on}.
 
 @lisp
+:serial t
 :components ((:file "a") (:file "b") (:file "c"))
-:serial t
 @end lisp
 
 is equivalent to
 
 @lisp
-:components ((:file "a") 
-	     (:file "b" :depends-on ("a"))
-	     (:file "c" :depends-on ("a" "b")))
+:components ((:file "a")
+             (:file "b" :depends-on ("a"))
+             (:file "c" :depends-on ("a" "b")))
 @end lisp
 
 
-@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 @code{find-system} will load a system from disk and have its pathname
-default to the right place
-@item this pathname information will not be
-overwritten with @code{*default-pathname-defaults*} (which could be
-somewhere else altogether) if the user loads up the @file{.asd} file
-into his editor and interactively re-evaluates that form.
+@item
+@code{find-system}
+will load a system from disk
+and have its pathname default to the right place.
+
+@item
+This pathname information will not be overwritten with
+@code{*default-pathname-defaults*}
+(which could be somewhere else altogether)
+if the user loads up the @file{.asd} file into his editor
+and interactively re-evaluates that form.
 @end enumerate
 
-If a system is being loaded for the first time, its top-level pathname
-will be set to:
+If a system is being loaded for the first time,
+its top-level pathname will be set to:
 
 @itemize
-@item The host/device/directory parts of @code{*load-truename*}, if it is bound
-@item @code{*default-pathname-defaults*}, otherwise
+@item
+The host/device/directory parts of @code{*load-truename*},
+if it is bound.
+@item
+@code{*default-pathname-defaults*}, otherwise.
 @end itemize
 
 If a system is being redefined, the top-level pathname will be
 
 @itemize
 @item
-changed, if explicitly supplied or obtained from
-@code{*load-truename*} (so that an updated source location is
-reflected in the system definition)
-@item
-changed if it had previously been set from
-@code{*default-pathname-defaults*}
-@item
-left as before, if it had previously been set from
-@code{*load-truename*} and @code{*load-truename*} is currently
-unbound (so that a developer can evaluate a @code{defsystem} form from
-within an editor without clobbering its source location)
+changed, if explicitly supplied or obtained from @code{*load-truename*}
+(so that an updated source location is reflected in the system definition)
+
+@item
+changed if it had previously been set from @code{*default-pathname-defaults*}
+
+@item
+left as before, if it had previously been set from @code{*load-truename*}
+and @code{*load-truename*} is currently unbound
+(so that a developer can evaluate a @code{defsystem} form
+from within an editor without clobbering its source location)
 @end itemize
 
-
-
-@node The object model of asdf, Error handling, Defining systems with defsystem, Top
+@subsection if-feature option
+@cindex :if-feature component option
+@anchor{if-feature-option}      @c redo if this ever becomes a node in
+@c its own right...
+
+This option allows you to specify a feature expression to be evaluated
+as if by @code{#+} to conditionally include a component in your build.
+If the expression is false, the component is dropped
+as well as any dependency pointing to it.
+As compared to using @code{#+} which is expanded at read-time,
+this allows you to have an object in your component hierarchy
+that can be used for manipulations beside building your project, and
+that is accessible to outside code that wishes to reason about system
+structure.
+
+Programmers should be careful to consider @strong{when} the
+@code{:if-feature} is evaluated.  Recall that ASDF first computes a
+build plan, and then executes that plan.  ASDF will check to see whether
+or not a feature is present @strong{at planning time}, not during the
+build.  It follows that one cannot use @code{:if-feature} to check
+features that are set during the course of the build.  It can only be
+used to check the state of features before any build operations have
+been performed.
+
+This option was added in ASDF 3.  For more information,
+@xref{required-features, Required features}.
+
+@subsection if-component-dep-fails option
+@cindex :if-component-dep-fails component option
+This option was removed in ASDF 3.
+Its semantics was limited in purpose and dubious to explain,
+and its implementation was breaking a hole into the ASDF object model.
+Please use the @code{if-feature} option instead.
+
+@subsection feature requirement
+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-inferred-system extension, The defsystem grammar, Defining systems with defsystem
+@section Other code in .asd files
+
+Files containing @code{defsystem} forms
+are regular Lisp files that are executed by @code{load}.
+Consequently, you can put whatever Lisp code you like into these files.
+However, it is recommended to keep such forms to a minimal,
+and to instead define @code{defsystem} extensions
+that you use with @code{:defsystem-depends-on}.
+
+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*}.
+If so, here are some conventions we recommend you follow,
+so that users can control certain details of execution
+of the Lisp in @file{.asd} files:
+
+@itemize
+@item
+Any informative output
+(other than warnings and errors,
+which are the condition system's to dispose of)
+should be sent to the standard CL stream @code{*standard-output*},
+so that users can easily control the disposition
+of output from ASDF operations.
+@end itemize
+
+
+@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.1,
+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
+(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)
+refer to files under the filesystem hierarchy where the system is defined.
+For instance, if system @code{my-lib} is defined in
+@file{/foo/bar/my-lib/my-lib.asd}, then system @code{my-lib/src/utility}
+will be found in file @file{/foo/bar/my-lib/src/utility.lisp}.
+
+This style was made popular by @code{faslpath} and @code{quick-build} before,
+and at the cost of a stricter package discipline,
+seems to make for more maintainable code.
+It is used by ASDF itself (starting with ASDF 3) and by @code{lisp-interface-library}.
+
+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-inferred-system} option in its @code{defsystem}.
+For instance:
+@example
+#-asdf (error "my-lib requires ASDF 3")
+(defsystem my-lib
+  :class :package-inferred-system
+  :defsystem-depends-on (:asdf-package-system)
+  :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
+
+In the code above, the
+@code{:defsystem-depends-on (:asdf-package-system)} is
+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 release 3.1.1,
+which can be detected with the feature @code{:asdf3.1}).
+
+The function @code{register-system-packages} has to be called to register
+packages used or provided by your system and its components
+where the name of the system that provides the package
+is not the downcase of the package name.
+
+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
+(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
+
+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},
+and has many options that prove useful in this context,
+such as @code{:use-reexport} and @code{:mix-reexport}
+that allow for ``inheritance'' of symbols being exported.
+
+@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
-
-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 protocol.  asdf is extensible to new operations and to new
-component types.  This allows the addition of behaviours: for example,
-a new component could be added for Java JAR archives, and methods
-specialised on @code{compile-op} added for it that would accomplish the
-relevant actions.
-
-This chapter deals with @emph{components}, the building blocks of a
-system, and @emph{operations}, the actions that can be performed on a
-system.
-
-
-
+@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, 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::                  
+* Operations::
+* Components::
+* Dependencies::
+* Functions::
 @end menu
 
-@node  Operations, Components, The object model of asdf, The object model of asdf
+@node  Operations, Components, The object model of ASDF, The object model of ASDF
 @comment  node-name,  next,  previous,  up
 @section Operations
 @cindex operation
@@ -448,208 +1909,542 @@
 @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.  @emph{FIXME: document how!}  There
-are a bunch of methods specialised on operation and component type
+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.
-
-The operation object contains whatever state is relevant for this
-purpose (perhaps a list of visited nodes, for example) but primarily
-is a nice thing to specialise operation methods on and easier than
-having them all be EQL methods.
+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}.
-
-@deffn {Generic function} operate operation system &rest initargs
-@deffnx {Generic function} oos operation system &rest initargs
-@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 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 initargs as the original one.
+@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.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
 
-@menu
-* Predefined operations of asdf::  
-* Creating new operations::     
-@end menu
-
-@node Predefined operations of asdf, Creating new operations, Operations, Operations
+
+
+@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.
+@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 ...}@})
+(asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
 @end lisp
 
-@deffn Operation compile-op &key proclamations
-
-This operation compiles the specified component.  If proclamations are
-supplied, they will be proclaimed.  This is a good place to specify
-optimization settings.
-
-When creating a new component type, you should provide methods for
-@code{compile-op}.
-
-When @code{compile-op} is invoked, component dependencies often cause
-some parts of the system to be loaded as well as compiled.  Invoking
-@code{compile-op} does not necessarily load all the parts of the
-system, though; use @code{load-op} to load a system.
+@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 load-op &key proclamations
-
-This operation loads a system.
-
-The default methods for @code{load-op} compile files before loading them.
-For parity, your own methods on new component types should probably do
-so too.
+@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 load-source-op
-
-This operation will load the source for the files in a module even if
-the source files have been compiled. Systems sometimes have knotty
-dependencies which require that sources are loaded before they can be
-compiled.  This is how you do that.
-
-If you are creating a component type, you need to implement this
-operation - at least, where meaningful.
+@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 test-system-version &key minimum
-
-Asks the system whether it satisfies a version requirement.
-
-The default method accepts a string, which is expected to contain of a
-number of integers separated by #\. characters.  The method is not
-recursive.  The component satisfies the version dependency if it has
-the same major number as required and each of its sub-versions is
-greater than or equal to the sub-version number required.
-
+@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
-(defun version-satisfies (x y)
-  (labels ((bigger (x y)
-	     (cond ((not y) t)
-		   ((not x) nil)
-		   ((> (car x) (car y)) t)
-		   ((= (car x) (car y))
-		    (bigger (cdr x) (cdr y))))))
-    (and (= (car x) (car y))
-	 (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
+(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
 
-If that doesn't work for your system, you can override it.  I hope
-you have as much fun writing the new method as @verb{|#lisp|} did
-reimplementing this one.
+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 feature-dependent-op
-
-An instance of @code{feature-dependent-op} will ignore any components
-which have a @code{features} attribute, unless the feature combination
-it designates is satisfied by @code{*features*}.  This operation is
-not intended to be instantiated directly, but other operations may
-inherit from it.
-
+
+
+@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
 
-@node  Creating new operations,  , Predefined operations of asdf, Operations
+@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.
-
-An operation must provide methods for the following generic functions
-when invoked with an object of type @code{source-file}:  @emph{FIXME describe
-this better}
+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}
-@item @code{perform}
-The @code{perform} method must call @code{output-files} to find out
-where to put its files, because the user is allowed to override
-@item @code{output-files} for local policy @code{explain}
-@item @code{operation-done-p}, if you don't like the default one
+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
 
-@node Components,  , Operations, The object model of asdf
+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 @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 string or symbol and behaves just like
-any other component name (including with regard to the case conversion
-rules for component names).
-
-
-@defun find-system system-designator &optional (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.
+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,
+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.
+A @code{module} is an intermediate component itself grouping several other components,
+themselves source-files or further modules.
+
+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.  The resulting pathname is loaded if either
-of the following conditions is true:
+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 file's last-modified time exceeds the last-modified time of the
-  system in memory
+@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
-function that 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.  Hence, it is strongly advised to define a system
+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::  
+* 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
@@ -660,56 +2455,85 @@
 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.  The name must be a suitable value for the
-@code{:name} initarg to @code{make-pathname} in whatever filesystem
-the system is to be found.
-
-The lower-casing-symbols behaviour is unconventional, but was selected
-after some consideration.  Observations suggest that the type of
-systems we want to support either have lowercase as customary case
-(Unix, Mac, windows) or silently convert lowercase to uppercase
-(lpns), so this makes more sense than attempting to use @code{:case
-:common} as argument to @code{make-pathname}, which is reported not to
-work on some implementations
+@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
-
-This optional attribute is used by the test-system-version
-operation. @xref{Predefined operations of asdf}.  For the default method of
-test-system-version, the version should be a string of intergers
-separated by dots, for example @samp{1.0.11}.
+@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
-
-Traditionally defsystem users have used reader conditionals to include
-or exclude specific per-implementation files.  This means that any
-single implementation cannot read the entire system, which becomes a
-problem if it doesn't wish to compile it, but instead for example to
-create an archive file containing all the sources, as it will omit to
-process the system-dependent sources for other systems.
-
-Each component in an asdf system may therefore specify features using
-the same syntax as #+ does, and it will (somehow) be ignored for
-certain operations unless the feature conditional is a member of
-@code{*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.
+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
+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")))
+              (load-op (load-op "foo")))
 @end lisp
 
 This means the following things:
@@ -724,29 +2548,32 @@
 The syntax is approximately
 
 @verbatim
-(this-op {(other-op required-components)}+)
-
-required-components := component-name
+(this-op @{(other-op required-components)@}+)
+
+simple-component-name := string
+                      |  symbol
+
+required-components := simple-component-name
                      | (required-components required-components)
 
-component-name := string
-                | (:version string minimum-version-object)
+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
+This is on a par with what ACL defsystem does.
+mk-defsystem is less general: it has an implied dependency
 
 @verbatim
-  for all x, (load x) depends on (compile x)
+  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) 
+  (compile b) depends on (load a)
 @end verbatim
 
 This is insufficient for e.g. the McCLIM system, which requires that
@@ -754,81 +2581,71 @@
 
 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
+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 a @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)
+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 will be inferred from the
-component's name, type (the subclass of source-file), and the location
-of its parent.
-
-The rules for this inference are:
-
-(for source-files)
-@itemize
-@item the host is taken from the parent
-@item pathname type is @code{(source-file-type component system)}
-@item the pathname case option is @code{:local}
-@item the pathname is merged against the parent
-@end itemize
-
-(for modules)
-@itemize
-@item the host is taken from the parent
-@item the name and type are @code{NIL}
-@item the directory is @code{(:relative component-name)}
-@item the pathname case option is @code{:local}
-@item the pathname is merged against the parent
-@end itemize
-
-Note that the DEFSYSTEM operator (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}.
-
-The answer to the frequently asked question "how do I create a system 
-definition where all the source files have a .cl extension" is thus
-
-@lisp
-(defmethod source-file-type ((c cl-source-file) (s (eql (find-system 'my-sys))))
-   "cl")
-@end lisp
+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
+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
+Sometimes the creator of an ASDF system may know the additional
 information and wish to provide it directly.
 
-(component-property component property-name) and associated 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.
+@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::  
+* 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
@@ -838,18 +2655,20 @@
 @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.}
+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
@@ -863,27 +2682,25 @@
 @code{:components} the components contained in this module
 
 @item
-@code{:default-component-class} All child components which don't
-specify their class explicitly are inferred to be of this type.
-
-@item
-@code{:if-component-dep-fails} This attribute takes one of the values
-@code{:fail}, @code{:try-next}, @code{:ignore}, its default value is
-@code{:fail}.  The other values can be used for implementing
-conditional compilation based on implementation @code{*features*}, for
-the case where it is not necessary for all files in a module to be
-compiled.
-
-@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.
+@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.
+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.
@@ -894,11 +2711,11 @@
 @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{:classs} keyword
-argument.
+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
@@ -908,30 +2725,30 @@
 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 ...}
+@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
+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
 
-A hypothetical function @code{system-dependent-dirname} 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}.
+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))
-  (let ((pathname (call-next-method))
-        (name (string-downcase (system-dependent-dirname))))
-    (merge-pathnames
-     (make-pathname :directory (list :relative name))
-     pathname)))
+  (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:
@@ -947,281 +2764,2852 @@
     )
 @end lisp
 
-@node  Error handling, Compilation error and warning handling, The object model of asdf, Top
+@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
+to keep the dependency graph without cycles,
+ASDF will fail loudly as it eventually finds one.
+To clearly distinguish the direction of dependencies,
+ASDF 3 uses the words @emph{requiring} and @emph{required}
+as applied to an action depending on the other:
+the requiring action @code{depends-on} the completion of all required actions
+before it may itself be @code{perform}ed.
+
+Using the @code{defsystem} syntax, users may easily express
+direct dependencies along the graph of the object hierarchy:
+between a component and its parent, its children, and its siblings.
+By defining custom CLOS methods, you can express more elaborate dependencies as you wish.
+Most common operations, such as @code{load-op}, @code{compile-op} or @code{load-source-op}
+are automatically propagate ``downward'' the component hierarchy and are ``covariant'' with it:
+to act the operation on the parent module, you must first act it on all the children components,
+with the action on the parent being parent of the action on each child.
+Other operations, such as @code{prepare-op} and @code{prepare-source-op}
+(introduced in ASDF 3) are automatically propagated ``upward'' the component hierarchy
+and are ``contravariant'' with it:
+to perform the operation of preparing for compilation of a child component,
+you must perform the operation of preparing for compilation of its parent component, and so on,
+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-bundle-op}
+remain at the system level, and are not propagated along the hierarchy,
+but instead do something global on the system.
+
+
+@node Functions,  , Dependencies, The object model of ASDF
+@comment  node-name,  next,  previous,  up
+@section Functions
+
+@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}.
+@var{version-spec} should be a string.
+If it's a component, its version is extracted as a string before further processing.
+
+A version string satisfies the version-spec if after parsing,
+the former is no older than the latter.
+Therefore @code{"1.9.1"}, @code{"1.9.2"} and @code{"1.10"} all satisfy @code{"1.9.1"},
+but @code{"1.8.4"} or @code{"1.9"} do not.
+For more information about how @code{version-satisfies} parses and interprets
+version strings and specifications,
+@pxref{The defsystem grammar} (version specifiers) and
+@ref{Common attributes of components}.
+
+Note that in versions of ASDF prior to 3.0.1,
+including the entire ASDF 1 and ASDF 2 series,
+@code{version-satisfies} would also require that the version and the version-spec
+have the same major version number (the first integer in the list);
+if the major version differed, the version would be considered as not matching the spec.
+But that feature was not documented, therefore presumably not relied upon,
+whereas it was a nuisance to several users.
+Starting with ASDF 3.0.1,
+@code{version-satisfies} does not treat the major version number specially,
+and returns T simply if the first argument designates a version that isn't older
+than the one specified as a second argument.
+If needs be, the @code{(:version ...)} syntax for specifying dependencies
+could be in the future extended to specify an exclusive upper bound for compatible versions
+as well as an inclusive lower bound.
+@end defun
+
+@node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
+@comment  node-name,  next,  previous,  up
+@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
+
+Configurations specify paths where to find system files.
+
+@enumerate
+
+@item
+The search registry may use some hardcoded wrapping registry specification.
+This allows some implementations (notably SBCL) to specify where to find
+some special implementation-provided systems that
+need to precisely match the version of the implementation itself.
+
+@item
+An application may explicitly initialize the source-registry configuration
+using the configuration API
+(@pxref{Controlling where ASDF searches for systems,Configuration API,Configuration API}, below)
+in which case this takes precedence.
+It may itself compute this configuration from the command-line,
+from a script, from its own configuration file, etc.
+
+@item
+The source registry will be configured from
+the environment variable @code{CL_SOURCE_REGISTRY} if it exists.
+
+@item
+The source registry will be configured from
+user configuration file
+@file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf}
+(which defaults to
+@file{~/.config/common-lisp/source-registry.conf})
+if it exists.
+
+@item
+The source registry will be configured from
+user configuration directory
+@file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf.d/}
+(which defaults to
+@file{~/.config/common-lisp/source-registry.conf.d/})
+if it exists.
+
+@item
+The source registry will be configured from
+default user configuration trees
+@file{~/common-lisp/} (since ASDF 3.1.1 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.
+
+@item
+The source registry will be configured from
+system configuration directory
+@file{/etc/common-lisp/source-registry.conf.d/}
+if it exists.
+
+@item
+The source registry will be configured from a default configuration.
+This configuration may allow for implementation-specific systems
+to be found, for systems to be found the current directory
+(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/},
+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
+
+Each of these configurations is specified as an s-expression
+in a trivial domain-specific language (defined below).
+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
+includes its inherited configuration.
+
+Additionally, some implementation-specific directories
+may be automatically prepended to whatever directories are specified
+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
+
+One great innovation of the original ASDF was its ability to leverage
+@code{CL:TRUENAME} to locate where your source code was and where to build it,
+allowing for symlink farms as a simple but effective configuration mechanism
+that is easy to control programmatically.
+ASDF 3 still supports this configuration style, and it is enabled by default;
+however we recommend you instead use
+our source-registry configuration mechanism described below,
+because it is easier to setup in a portable way across users and implementations.
+
+Addtionally, some people dislike truename,
+either because it is very slow on their system, or
+because they are using content-addressed storage where the truename of a file
+is related to a digest of its individual contents,
+and not to other files in the same intended project.
+For these people, ASDF 3 allows to eschew the @code{TRUENAME} mechanism,
+by setting the variable @var{asdf:*resolve-symlinks*} to @code{nil}.
+
+PS: Yes, if you haven't read Vernor Vinge's short but great classic
+``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
+
+Note that we purport to respect the XDG base directory specification
+as to where configuration files are located,
+where data files are located,
+where output file caches are located.
+Mentions of XDG variables refer to that document.
+
+@url{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}
+
+This specification allows the user to specify some environment variables
+to customize how applications behave to his preferences.
+
+On Windows platforms, when not using Cygwin,
+instead of the XDG base directory specification,
+we try to use folder configuration from the registry regarding
+@code{Common AppData} and similar directories.
+Since support for querying the Windows registry
+is not possible to do in reasonable amounts of portable Common Lisp code,
+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 @file{.asd} files in the directories specified in
+@code{asdf:*central-registry*}
+before it searches in the source registry above.
+
+@xref{Configuring ASDF,,Configuring ASDF to find your systems --- old style}.
+
+By default, @code{asdf:*central-registry*} will be empty.
+
+This old mechanism will therefore not affect you if you don't use it,
+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
+@cindex inherit-configuration source config directive
+@cindex :ignore-invalid-entries source config directive
+@cindex ignore-invalid-entries source config directive
+@cindex :directory source config directive
+@cindex directory source config directive
+@cindex :tree source config directive
+@cindex tree source config directive
+@cindex :exclude source config directive
+@cindex exclude source config directive
+@cindex :also-exclude source config directive
+@cindex also-exclude source config directive
+@cindex :include source config directive
+@cindex include source config directive
+@cindex :default-registry source config directive
+@cindex default-registry source config directive
+
+Here is the grammar of the s-expression (SEXP) DSL for source-registry
+configuration:
+
+@c FIXME: This is too wide for happy compilation into pdf.
+
+@example
+;; A configuration is a single SEXP starting with the keyword
+;; :source-registry followed by a list of directives.
+CONFIGURATION := (:source-registry DIRECTIVE ...)
+
+;; A directive is one of the following:
+DIRECTIVE :=
+    ;; INHERITANCE DIRECTIVE:
+    ;; Your configuration expression MUST contain
+    ;; 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
+    ;; 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
+    (:tree DIRECTORY-PATHNAME-DESIGNATOR) |
+
+    ;; override the defaults for exclusion patterns
+    (:exclude EXCLUSION-PATTERN ...) |
+    ;; augment the defaults for exclusion patterns
+    (:also-exclude EXCLUSION-PATTERN ...) |
+    ;; Note that the scope of a an exclude pattern specification is
+    ;; the rest of the current configuration expression or file.
+
+    ;; splice the parsed contents of another config file
+    (:include REGULAR-FILE-PATHNAME-DESIGNATOR) |
+
+    ;; This directive specifies that some default must be spliced.
+    :default-registry
+
+REGULAR-FILE-PATHNAME-DESIGNATOR
+    := PATHNAME-DESIGNATOR ; interpreted as a file
+DIRECTORY-PATHNAME-DESIGNATOR
+    := PATHNAME-DESIGNATOR ; interpreted as a directory
+
+PATHNAME-DESIGNATOR :=
+    NIL | ;; Special: skip this entry.
+    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"}
+@end example
+
+Pathnames are designated using another DSL,
+shared with the output-translations configuration DSL below.
+The DSL is resolved by the function @code{asdf::resolve-location},
+to be documented and exported at some point in the future.
+
+@example
+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
+
+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
+    :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
+    :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
+    :*.*.* | ;; any file (since ASDF 2.011.4)
+
+The keywords :UID and :USERNAME are no longer supported.
+@end example
+
+For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf},
+which is the default place ASDF looks for this configuration, once contained:
+@example
+(:source-registry
+  (:tree (:home "cl")) ;; will expand to e.g. "/home/joeluser/cl/"
+  :inherit-configuration)
+@end example
+
+@node Configuration Directories, Shell-friendly syntax for configuration, Configuration DSL, Controlling where ASDF searches for systems
+@section Configuration Directories
+
+Configuration directories consist in files each containing
+a list of directives without any enclosing @code{(:source-registry ...)} form.
+The files will be sorted by namestring as if by @code{string<} and
+the lists of directives of these files with be concatenated in order.
+An implicit @code{:inherit-configuration} will be included
+at the @emph{end} of the list.
+
+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 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.:
+
+@example
+	(:include "/foo/bar/")
+@end example
+
+Hence, to achieve the same effect as
+my example @file{~/.config/common-lisp/source-registry.conf} above,
+I could simply create a file
+@file{~/.config/common-lisp/source-registry.conf.d/33-home-fare-cl.conf}
+alone in its directory with the following contents:
+@example
+(:tree "/home/fare/cl/")
+@end example
+
+@menu
+* The here directive::
+@end menu
+
+@node The here directive,  , Configuration Directories, Configuration Directories
+@subsection The :here directive
+
+The @code{:here} directive is an absolute pathname designator that
+refers to the directory containing the configuration file currently
+being processed.
+
+The @code{:here} directive is intended to simplify the delivery of
+complex CL systems, and for easy configuration of projects shared through
+revision control systems, in accordance with our design principle that
+each participant should be able to provide all and only the information
+available to him or her.
+
+Consider a person X who has set up the source code repository for a
+complex project with a master directory @file{dir/}.  Ordinarily, one
+might simply have the user add a directive that would look something
+like this:
+@example
+   (:tree "path/to/dir")
+@end example
+But what if X knows that there are very large subtrees
+under dir that are filled with, e.g., Java source code, image files for
+icons, etc.?  All of the asdf system definitions are contained in the
+subdirectories @file{dir/src/lisp/} and @file{dir/extlib/lisp/}, and
+these are the only directories that should be searched.
+
+In this case, X can put into @file{dir/} a file @file{asdf.conf} that
+contains the following:
+@example
+(:source-registry
+   (:tree (:here "src/lisp/"))
+   (:tree (:here "extlib/lisp"))
+   (:directory (:here "outlier/")))
+@end example
+
+Then when someone else (call her Y) checks out a copy of this
+repository, she need only add
+@example
+(:include "/path/to/my/checkout/directory/asdf.conf")
+@end example
+to one of her previously-existing asdf source location configuration
+files, or invoke @code{initialize-source-registry} with a configuration
+form containing that s-expression.  ASDF will find the .conf file that X
+has provided, and then set up source locations within the working
+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
+
+When considering environment variable @code{CL_SOURCE_REGISTRY}
+ASDF will skip to next configuration if it's an empty string.
+It will @code{READ} the string as a SEXP in the DSL
+if it begins with a paren @code{(}
+and it will be interpreted much like @code{TEXINPUTS}
+list of paths, where
+
+  * paths are separated
+   by a @code{:} (colon) on Unix platforms (including cygwin),
+   by a @code{;} (semicolon) on other platforms (mainly, Windows).
+
+  * each entry is a directory to add to the search path.
+
+  * if the entry ends with a double slash @code{//}
+    then it instead indicates a tree in the subdirectories
+    of which to recurse.
+
+  * if the entry is the empty string (which may only appear once),
+    then it indicates that the inherited configuration should be
+    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*
+
+In case that isn't clear, the semantics of the configuration is that
+when searching for a system of a given name,
+directives are processed in order.
+
+When looking in a directory, if the system is found, the search succeeds,
+otherwise it continues.
+
+When looking in a tree, if one system is found, the search succeeds.
+If multiple systems are found, the consequences are unspecified:
+the search may succeed with any of the found systems,
+or an error may be raised.
+ASDF currently returns the first system found,
+XCVB currently raised an error.
+If none is found, the search continues.
+
+Exclude statements specify patterns of subdirectories
+the systems from which to ignore.
+Typically you don't want to use copies of files kept by such
+version control systems as Darcs.
+Exclude statements are not propagated to further included or inherited
+configuration files or expressions;
+instead the defaults are reset around every configuration statement
+to the default defaults from @code{asdf::*default-source-registry-exclusions*}.
+
+Include statements cause the search to recurse with the path specifications
+from the file specified.
+
+An inherit-configuration statement cause the search to recurse with the path
+specifications from the next configuration
+(@pxref{Controlling where ASDF searches for systems,,Configurations} above).
+
+
+@node Caching Results, Configuration API, Search Algorithm, Controlling where ASDF searches for systems
+@section Caching Results
+
+The implementation is allowed to either eagerly compute the information
+from the configurations and file system, or to lazily re-compute it
+every time, or to cache any part of it as it goes.
+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
+
+The specified functions are exported from your build system's package.
+Thus for ASDF the corresponding functions are in package ASDF,
+and for XCVB the corresponding functions are in package XCVB.
+
+@defun initialize-source-registry @Aoptional{} PARAMETER
+   will read the configuration and initialize all internal variables.
+   You may extend or override configuration
+   from the environment and configuration files
+   with the given @var{PARAMETER}, which can be
+   @code{nil} (no configuration override),
+   or a SEXP (in the SEXP DSL),
+   a string (as in the string DSL),
+   a pathname (of a file or directory with configuration),
+   or a symbol (fbound to function that when called returns one of the above).
+@end defun
+
+@defun clear-source-registry
+   undoes any source registry configuration
+   and clears any cache for the search algorithm.
+   You might want to call this function
+   (or better, @code{clear-configuration})
+   before you dump an image that would be resumed
+   with a different configuration,
+   and return an empty configuration.
+   Note that this does not include clearing information about
+   systems defined in the current image, only about
+   where to look for systems not yet defined.
+@end defun
+
+@defun ensure-source-registry @Aoptional{} PARAMETER
+   checks whether a source registry has been initialized.
+   If not, initialize it with the given @var{PARAMETER}.
+@end defun
+
+Every time you use ASDF's @code{find-system}, or
+anything that uses it (such as @code{operate}, @code{load-system}, etc.),
+@code{ensure-source-registry} is called with parameter @code{nil},
+which the first time around causes your configuration to be read.
+If you change a configuration file,
+you need to explicitly @code{initialize-source-registry} again,
+or maybe simply to @code{clear-source-registry} (or @code{clear-configuration})
+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*
+
+We have made available the variable @code{*source-registry-parameter*}
+that can be used by code that wishes to introspect about the (past)
+configuration of ASDF's source registry.  @strong{This variable should
+never be set!}  It will be set as a side-effect of calling
+@code{initialize-source-registry}; user code should treat it as
+read-only.
+
+@node Information about system dependencies,  , *source-registry-parameter* variable, Introspection
+@subsection Information about system dependencies
+
+ASDF makes available three functions to read system interdependencies.
+These are intended to aid programmers who wish to perform dependency
+analyses.
+
+@defun system-defsystem-depends-on system
+@end defun
+
+@defun system-depends-on system
+@end defun
+
+@defun system-weakly-depends-on system
+Returns a list of names of systems that are weakly depended on by
+@var{system}.  Weakly depended on systems are optionally loaded only if
+ASDF can find them; failure to find such systems does @emph{not} cause an
+error in loading.
+
+Note that the return value for @code{system-weakly-depends-on} is simpler
+than the return values of the other two system dependency introspection
+functions.
+@end defun
+
+@node Status, Rejected ideas, Introspection, Controlling where ASDF searches for systems
+@section Status
+
+This mechanism is vastly successful, and we have declared
+that @code{asdf:*central-registry*} is not recommended anymore,
+though we will continue to support it.
+All hooks into implementation-specific search mechanisms
+have been integrated in the @code{wrapping-source-registry}
+that everyone uses implicitly.
+
+@node Rejected ideas, TODO, Status, Controlling where ASDF searches for systems
+@section Rejected ideas
+
+Alternatives I (FRR) considered and rejected while developing ASDF 2 included:
+
+@enumerate
+@item Keep @code{asdf:*central-registry*} as the master with its current semantics,
+   and somehow the configuration parser expands the new configuration
+   language into a expanded series of directories of subdirectories to
+   lookup, pre-recursing through specified hierarchies. This is kludgy,
+   and leaves little space of future cleanups and extensions.
+
+@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.
+
+@item Completely remove @code{asdf:*central-registry*}
+   and break backwards compatibility.
+   Hopefully this will happen in a few years after everyone migrate to
+   a better ASDF and/or to XCVB, but it would be very bad to do it now.
+
+@item Replace @code{asdf:*central-registry*} by a symbol-macro with appropriate magic
+   when you dereference it or setf it. Only the new variable with new
+   semantics is handled by the new search procedure.
+   Complex and still introduces subtle semantic issues.
+@end enumerate
+
+
+I've been suggested the below features, but have rejected them,
+for the sake of keeping ASDF no more complex than strictly necessary.
+
+@itemize
+@item
+  More syntactic sugar: synonyms for the configuration directives, such as
+  @code{(:add-directory X)} for @code{(:directory X)}, or @code{(:add-directory-hierarchy X)}
+  or @code{(:add-directory X :recurse t)} for @code{(:tree X)}.
+
+@item
+   The possibility to register individual files instead of directories.
+
+@item
+  Integrate Xach Beane's tilde expander into the parser,
+  or something similar that is shell-friendly or shell-compatible.
+  I'd rather keep ASDF minimal. But maybe this precisely keeps it
+  minimal by removing the need for evaluated entries that ASDF has?
+  i.e. uses of @code{USER-HOMEDIR-PATHNAME} and @code{$SBCL_HOME}
+  Hopefully, these are already superseded by the @code{:default-registry}
+
+@item
+  Using the shell-unfriendly syntax @code{/**} instead of @code{//} to specify recursion
+  down a filesystem tree in the environment variable.
+  It isn't that Lisp friendly either.
+@end itemize
+
+@node TODO, Credits for the source-registry, Rejected ideas, Controlling where ASDF searches for systems
+@section TODO
+
+@itemize
+@item Add examples
+@end itemize
+
+@node Credits for the source-registry,  , TODO, Controlling where ASDF searches for systems
+@section Credits for the source-registry
+
+Thanks a lot to Stelian Ionescu for the initial idea.
+
+Thanks to Rommel Martinez for the initial implementation attempt.
+
+All bad design ideas and implementation bugs are mine, not theirs.
+But so are good design ideas and elegant implementation tricks.
+
+ --- Francois-Rene Rideau @email{fare@@tunes.org}, Mon, 22 Feb 2010 00:07:33 -0500
+
+
+
+@node Controlling where ASDF saves compiled files, Error handling, Controlling where ASDF searches for systems, Top
+@comment  node-name,  next,  previous,  up
+@chapter Controlling where ASDF saves compiled files
+@cindex asdf-output-translations
+@vindex ASDF_OUTPUT_TRANSLATIONS
+
+Each Common Lisp implementation has its own format
+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, 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.
+
+Since ASDF 2, ASDF includes the @code{asdf-output-translations} facility
+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.
+Once again we rely on the XDG base directory specification for configuration.
+@xref{Controlling where ASDF searches for systems,,XDG base directory}.
+
+@enumerate
+
+@item
+Some hardcoded wrapping output translations configuration may be used.
+This allows special output translations (or usually, invariant directories)
+to be specified corresponding to the similar special entries in the source registry.
+
+@item
+An application may explicitly initialize the output-translations
+configuration using the Configuration API
+in which case this takes precedence.
+(@pxref{Controlling where ASDF saves compiled files,,Configuration API}.)
+It may itself compute this configuration from the command-line,
+from a script, from its own configuration file, etc.
+
+@item
+The source registry will be configured from
+the environment variable @code{ASDF_OUTPUT_TRANSLATIONS} if it exists.
+
+@item
+The source registry will be configured from
+user configuration file
+@file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf}
+(which defaults to
+@file{~/.config/common-lisp/asdf-output-translations.conf})
+if it exists.
+
+@item
+The source registry will be configured from
+user configuration directory
+@file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf.d/}
+(which defaults to
+@file{~/.config/common-lisp/asdf-output-translations.conf.d/})
+if it exists.
+
+@item
+The source registry will be configured from
+system configuration file
+@file{/etc/common-lisp/asdf-output-translations.conf}
+if it exists.
+
+@item
+The source registry will be configured from
+system configuration directory
+@file{/etc/common-lisp/asdf-output-translations.conf.d/}
+if it exists.
+
+@end enumerate
+
+Each of these configurations is specified as a SEXP
+in a trivial domain-specific language (@pxref{Configuration DSL}).
+Additionally, a more shell-friendly syntax is available
+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.
+
+Note that by default, a per-user cache is used for output files.
+This allows the seamless use of shared installations of software
+between several users, and takes files out of the way of the developers
+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.@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
+@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 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.
+
+This incompatibility shouldn't inconvenience many people.
+Indeed, few people use and customize these packages;
+these few people are experts who can trivially adapt to the new configuration.
+Most people are not experts, could not properly configure these features
+(except inasmuch as the default configuration of
+@code{common-lisp-controller} and/or @code{cl-launch}
+might have been doing the right thing for some users),
+and yet will experience software that ``just works'',
+as configured by the system distributor, or by default.
+
+Nevertheless, if you are a fan of @code{ASDF-Binary-Locations},
+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
+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.
+Where you would previously set global variables
+@var{*centralize-lisp-binaries*},
+@var{*default-toplevel-directory*},
+@var{*include-per-user-information*},
+@var{*map-all-source-files*} or @var{*source-to-target-mappings*}
+you will now have to pass the same values as keyword arguments to this function.
+Note however that as an extension the @code{:source-to-target-mappings} keyword argument
+will accept any valid pathname designator for @code{asdf-output-translations}
+instead of just strings and pathnames.
+@end defun
+
+If you insist, you can also keep using the old @code{ASDF-Binary-Locations}
+(the one available as an extension to load of top of ASDF,
+not the one built into a few old versions of ASDF),
+but first you must disable @code{asdf-output-translations}
+with @code{(asdf:disable-output-translations)},
+or you might experience ``interesting'' issues.
+
+Also, note that output translation is enabled by default.
+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
+
+Here is the grammar of the SEXP DSL
+for @code{asdf-output-translations} configuration:
+
+@verbatim
+;; A configuration is single SEXP starting with keyword :source-registry
+;; followed by a list of directives.
+CONFIGURATION := (:output-translations DIRECTIVE ...)
+
+;; A directive is one of the following:
+DIRECTIVE :=
+    ;; 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)
+
+    ;; 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 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-user-cache |
+    ;; Disable global cache. Map / to /
+    :disable-cache |
+
+    ;; add a single directory to be scanned (no recursion)
+    (DIRECTORY-DESIGNATOR DIRECTORY-DESIGNATOR)
+
+    ;; use a function to return the translation of a directory designator
+    (DIRECTORY-DESIGNATOR (:function TRANSLATION-FUNCTION))
+
+DIRECTORY-DESIGNATOR :=
+    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 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
+
+Relative components better be either relative
+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
+by using a pathname object as the last component
+e.g. @file{#p"some/path/**/foo*/bar-*.fasl"}
+
+You may use @code{#+features} to customize the configuration file.
+
+The second designator of a mapping may be @code{nil}, indicating that files are not mapped
+to anything but themselves (same as if the second designator was the same as the first).
+
+When the first designator is @code{t},
+the mapping always matches.
+When the first designator starts with @code{:root},
+the mapping matches any host and device.
+In either of these cases, if the second designator
+isn't @code{t} and doesn't start with @code{:root},
+then strings indicating the host and pathname are somehow copied
+in the beginning of the directory component of the source pathname
+before it is translated.
+
+When the second designator is @code{t}, the mapping is the identity.
+When the second designator starts with @code{:root},
+the mapping preserves the host and device of the original pathname.
+Notably, this allows you to map files
+to a subdirectory of the whichever directory the file is in.
+Though the syntax is not quite as easy to use as we'd like,
+you can have an (source destination) mapping entry such as follows
+in your configuration file,
+or you may use @code{enable-asdf-binary-locations-compatibility}
+with @code{:centralize-lisp-binaries nil}
+which will do the same thing internally for you:
+@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 :*.*.*))}
+
+
+
+@code{:include} statements cause the search to recurse with the path specifications
+from the file specified.
+
+If the @code{translate-pathname} mechanism cannot achieve a desired
+translation, the user may provide a function which provides the
+required algorithim.  Such a translation function is specified by
+supplying a list as the second @code{directory-designator}
+the first element of which is the keyword @code{:function},
+and the second element of which is
+either a symbol which designates a function or a lambda expression.
+The function designated by the second argument must take two arguments,
+the first being the pathname of the source file,
+the second being the wildcard that was matched.
+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
+@code{:enable-user-cache} is the same as @code{(t :user-cache)}.
+@item
+@code{:disable-cache} is the same as @code{(t t)}.
+@item
+@code{:user-cache} uses the contents of variable @code{asdf::*user-cache*}
+which by default is the same as using
+@code{(:home ".cache" "common-lisp" :implementation)}.
+@end itemize
+
+
+@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 of files, each of which contains
+a list of directives without any enclosing
+@code{(:output-translations ...)} form.
+The files will be sorted by namestring as if by @code{string<} and
+the lists of directives of these files with be concatenated in order.
+An implicit @code{:inherit-configuration} will be included
+at the @emph{end} of the list.
+
+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 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 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{(}
+and it will be interpreted as a list of directories.
+Directories should come by pairs, indicating a mapping directive.
+Entries are separated
+by a @code{:} (colon) on Unix platforms (including cygwin),
+by a @code{;} (semicolon) on other platforms (mainly, Windows).
+
+The magic empty entry,
+if it comes in what would otherwise be the first entry in a pair,
+indicates the splicing of inherited configuration.
+If it comes as the second entry in a pair,
+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
+
+From the specified configuration,
+a list of mappings is extracted in a straightforward way:
+mappings are collected in order, recursing through
+included or inherited configuration as specified.
+To this list is prepended some implementation-specific mappings,
+and is appended a global default.
+
+The list is then compiled to a mapping table as follows:
+for each entry, in order, resolve the first designated directory
+into an actual directory pathname for source locations.
+If no mapping was specified yet for that location,
+resolve the second designated directory to an output location directory
+add a mapping to the table mapping the source location to the output location,
+and add another mapping from the output location to itself
+(unless a mapping already exists for the output location).
+
+Based on the table, a mapping function is defined,
+mapping source pathnames to output pathnames:
+given a source pathname, locate the longest matching prefix
+in the source column of the mapping table.
+Replace that prefix by the corresponding output column
+in the same row of the table, and return the result.
+If no match is found, return the source pathname.
+(A global default mapping the filesystem root to itself
+may ensure that there will always be a match,
+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
+
+The implementation is allowed to either eagerly compute the information
+from the configurations and file system, or to lazily re-compute it
+every time, or to cache any part of it as it goes.
+To explicitly flush any information cached by the system, use the API below.
+
+
+@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
+   will read the configuration and initialize all internal variables.
+   You may extend or override configuration
+   from the environment and configuration files
+   with the given @var{PARAMETER}, which can be
+   @code{nil} (no configuration override),
+   or a SEXP (in the SEXP DSL),
+   a string (as in the string DSL),
+   a pathname (of a file or directory with configuration),
+   or a symbol (fbound to function that when called returns one of the above).
+@end defun
+
+@defun disable-output-translations
+   will initialize output translations in a way
+   that maps every pathname to itself,
+   effectively disabling the output translation facility.
+@end defun
+
+@defun clear-output-translations
+   undoes any output translation configuration
+   and clears any cache for the mapping algorithm.
+   You might want to call this function
+   (or better, @code{clear-configuration})
+   before you dump an image that would be resumed
+   with a different configuration,
+   and return an empty configuration.
+   Note that this does not include clearing information about
+   systems defined in the current image, only about
+   where to look for systems not yet defined.
+@end defun
+
+@defun ensure-output-translations @Aoptional{} PARAMETER
+   checks whether output translations have been initialized.
+   If not, initialize them with the given @var{PARAMETER}.
+   This function will be called before any attempt to operate on a system.
+@end defun
+
+@defun apply-output-translations PATHNAME
+   Applies the configured output location translations to @var{PATHNAME}
+   (calls @code{ensure-output-translations} for the translations).
+@end defun
+
+Every time you use ASDF's @code{output-files}, or
+anything that uses it (that may compile, such as @code{operate}, @code{perform}, etc.),
+@code{ensure-output-translations} is called with parameter @code{nil},
+which the first time around causes your configuration to be read.
+If you change a configuration file,
+you need to explicitly @code{initialize-output-translations} again,
+or maybe @code{clear-output-translations} (or @code{clear-configuration}),
+which will cause the initialization to happen next time around.
+
+
+@node Credits for output translations,  , Output location API, Controlling where ASDF saves compiled files
+@section Credits for output translations
+
+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.
+But so are good design ideas and elegant implementation tricks.
+
+ --- Francois-Rene Rideau @email{fare@@tunes.org}
+
+@c @section Default locations
+@c @findex output-files-for-system-and-operation
+
+@c The default binary location for each Lisp implementation
+@c is a subdirectory of each source directory.
+@c To account for different Lisps, Operating Systems, Implementation versions,
+@c and so on, ASDF borrows code from SLIME
+@c to create reasonable custom directory names.
+@c Here are some examples:
+
+@c @itemize
+@c @item
+@c SBCL, version 1.0.45 on Mac OS X for Intel: @code{sbcl-1.0.45-darwin-x86}
+
+@c @item
+@c Franz Allegro, version 8.0, ANSI Common Lisp: @code{allegro-8.0a-macosx-x86}
+
+@c @item
+@c Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: @code{allegro-8.1m-macosx-x86}
+@c @end itemize
+
+@c By default, all output file pathnames will be relocated
+@c to some thus-named subdirectory of @file{~/.cache/common-lisp/}.
+
+@c See the document @file{README.asdf-output-translations}
+@c for a full specification on how to configure @code{asdf-output-translations}.
+
+@node  Error handling, Miscellaneous additional functionality, Controlling where ASDF saves compiled files, Top
 @comment  node-name,  next,  previous,  up
 @chapter Error handling
 @findex SYSTEM-DEFINITION-ERROR
 @findex OPERATION-ERROR
 
-It is an error to define a system incorrectly: an implementation may
-detect this and signal a generalised instance of
+@section ASDF errors
+
+If ASDF detects an incorrect system definition, it will signal a generalised instance of
 @code{SYSTEM-DEFINITION-ERROR}.
 
-Operations may go wrong (for example when source files contain
-errors).  These are signalled using generalised instances of
+Operations may go wrong (for example when source files contain errors).
+These are signalled using generalised instances of
 @code{OPERATION-ERROR}.
 
-@node  Compilation error and warning handling, Getting the latest version, Error handling, Top
-@comment  node-name,  next,  previous,  up
-@chapter Compilation error and warning handling
+@section Compilation error and warning handling
 @vindex *compile-file-warnings-behaviour*
 @vindex *compile-file-errors-behavior*
 
-ASDF checks for warnings and errors when a file is compiled. The
-variables @code{*compile-file-warnings-behaviour*} and
-@code{*compile-file-errors-behavior*} controls the handling of any
-such events. The valid values for these variables are @code{:error},
-@code{:warn}, and @code{:ignore}.
-
-@node Getting the latest version, TODO list, Compilation error and warning handling, Top
+ASDF checks for warnings and errors when a file is compiled.
+The variables @var{*compile-file-warnings-behaviour*} and
+@var{*compile-file-errors-behavior*}
+control the handling of any such events.
+The valid values for these variables are
+@code{:error}, @code{:warn}, and @code{:ignore}.
+
+@node  Miscellaneous additional functionality, Getting the latest version, Error handling, Top
+@comment  node-name,  next,  previous,  up
+@chapter Miscellaneous additional functionality
+
+ASDF includes several additional features that are generally
+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
+@cindex around-compile keyword
+@cindex compile-check keyword
+@cindex :compile-check
+@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}.
+If left unspecified (and therefore unbound),
+the value will be inherited from the parent component if any,
+or with a default of @code{nil}
+if no value is specified in any transitive parent.
+
+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
+because it prevents the introspection done by e.g. asdf-dependency-grovel),
+or a string that when @code{read} yields a symbol or a lambda-expression.
+@code{nil} means the normal compile-file function will be called.
+A non-nil value designates a function of one argument
+that will be called with a function that will
+invoke @code{compile-file*} with various arguments;
+the around-compile hook may supply additional keyword arguments
+to pass to that call to @code{compile-file*}.
+
+One notable argument that is heeded by @code{compile-file*} is
+@code{:compile-check},
+a function called when the compilation was otherwise a success,
+with the same arguments as @code{compile-file};
+the function shall return true if the compilation
+and its resulting compiled file respected all system-specific invariants,
+and false (@code{nil}) if it broke any of those invariants;
+it may issue warnings or errors before it returns @code{nil}.
+(NB: The ability to pass such extra flags
+is only available starting with ASDF 2.22.3.)
+This feature is notably exercised by asdf-finalizers.
+
+By using a string, you may reference
+a function, symbol and/or package
+that will only be created later during the build, but
+isn't yet present at the time the defsystem form is evaluated.
+However, if your entire system is using such a hook, you may have to
+explicitly override the hook with @code{nil} for all the modules and files
+that are compiled before the hook is defined.
+
+Using this hook, you may achieve such effects as:
+locally renaming packages,
+binding @var{*readtables*} and other syntax-controlling variables,
+handling warnings and other conditions,
+proclaiming consistent optimization settings,
+saving code coverage information,
+maintaining meta-data about compilation timings,
+setting gensym counters and PRNG seeds and other sources of non-determinism,
+overriding the source-location and/or timestamping systems,
+checking that some compile-time side-effects were properly balanced,
+etc.
+
+Note that there is no around-load hook. This is on purpose.
+Some implementations such as ECL, GCL or MKCL link object files,
+which allows for no such hook.
+Other implementations allow for concatenating FASL files,
+which doesn't allow for such a hook either.
+We aim to discourage something that's not portable,
+and has some dubious impact on performance and semantics
+even when it is possible.
+Things you might want to do with an around-load hook
+are better done around-compile,
+though it may at times require some creativity
+(see e.g. the @code{package-renaming} system).
+
+
+@node Controlling source file character encoding, Some Utility Functions, Controlling file compilation, Miscellaneous additional functionality
+@section Controlling source file character encoding
+
+Starting with ASDF 2.21, components accept a @code{:encoding} option
+so authors may specify which character encoding should be used
+to read and evaluate their source code.
+When left unspecified, the encoding is inherited
+from the parent module or system;
+if no encoding is specified at any point,
+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 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
+(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 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,
+already used by the vast majority of libraries that use more than ASCII.
+On implementations that do not support unicode,
+the feature @code{:asdf-unicode} is absent, and
+the @code{:default} external-format is used
+to read even source files declared as @code{:utf-8}.
+On these implementations, non-ASCII characters
+intended to be read as one CL character
+may thus end up being read as multiple CL characters.
+In most cases, this shouldn't affect the software's semantics:
+comments will be skipped just the same, strings with be read and printed
+with slightly different lengths, symbol names will be accordingly longer,
+but none of it should matter.
+But a few systems that actually depend on unicode characters
+may fail to work properly, or may work in a subtly different way.
+See for instance @code{lambda-reader}.
+
+We invite you to embrace UTF-8
+as the encoding for non-ASCII characters starting today,
+even without any explicit specification in your @file{.asd} files.
+Indeed, on some implementations and configurations,
+UTF-8 is already the @code{:default},
+and loading your code may cause errors if it is encoded in anything but UTF-8.
+Therefore, even with the legacy behavior,
+non-UTF-8 is guaranteed to break for some users,
+whereas UTF-8 is pretty much guaranteed not to break anywhere
+(provided you do @emph{not} use a BOM),
+although it might be read incorrectly on some implementations.
+@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,
+use the extension system @code{asdf-encodings}, by specifying
+@code{:defsystem-depends-on (:asdf-encodings)} in your @code{defsystem}.
+This extension system will register support for more encodings using the
+@code{*encoding-external-format-hook*} facility,
+so you can explicitly specify @code{:encoding :latin1}
+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, @code{asdf-encoding} only supports the encodings
+that are supported as part of your implementation.
+Since the list varies depending on implementations,
+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
+@kbd{git clone ssh://common-lisp.net/project/asdf/git/asdf-encodings.git}.
+You can also browse the repository on
+@url{http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git}.
+
+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 @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
+
+These functions are exported by ASDF for your convenience.
+
+@anchor{system-relative-pathname}
+@defun system-relative-pathname system name @Akey{} type
+
+It's often handy to locate a file relative to some system.
+The @code{system-relative-pathname} function meets this need.
+
+It takes two mandatory arguments @var{system} and @var{name}
+and a keyword argument @var{type}:
+@var{system} is name of a system, whereas @var{name} and optionally @var{type}
+specify a relative pathname, interpreted like a component pathname specifier
+by @code{coerce-pathname}. @xref{The defsystem grammar,,Pathname specifiers}.
+
+It returns a pathname built from the location of the system's
+source directory and the relative pathname. For example:
+
+@lisp
+> (asdf:system-relative-pathname 'cl-ppcre "regex.data")
+#P"/repository/other/cl-ppcre/regex.data"
+@end lisp
+
+@end defun
+
+@defun system-source-directory system-designator
+
+ASDF does not provide a turnkey solution for locating
+data (or other miscellaneous) files
+that are distributed together with the source code of a system.
+Programmers can use @code{system-source-directory} to find such files.
+Returns a pathname object.
+The @var{system-designator} may be a string, symbol, or ASDF system object.
+@end defun
+
+@defun clear-system system-designator
+
+It is sometimes useful to force recompilation of a previously loaded system.
+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 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,
+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.
+It is up to the user to make sure that reloading is possible and has the desired effect.
+In some cases, extreme measures such as recursively deleting packages,
+unregistering symbols, defining methods on @code{update-instance-for-redefined-class}
+and much more are necessary for reloading to happen smoothly.
+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
+A system with name @var{name},
+created by @code{make-instance} with extra keys @var{keys}
+(e.g. @code{:version}),
+is registered as @emph{preloaded}.
+That is, its code has already been loaded into the current image,
+and if at some point some other system @code{:depends-on} it yet no source code is found,
+it is considered as already provided,
+and ASDF will not raise a @code{missing-component} error.
+
+This function is particularly useful if you distribute your code
+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
+
+This function is obsolete and present only for the sake of backwards-compatibility:
+``If it's not backwards, it's not compatible''. We @emph{strongly} discourage its use.
+Its current behavior is only well-defined on Unix platforms
+(which include MacOS X and cygwin). On Windows, anything goes.
+The following documentation is only for the purpose of your migrating away from it
+in a way that preserves semantics.
+
+Instead we recommend the use @code{run-program}, described in the next section, and
+available as part of ASDF since ASDF 3.
+
+@code{run-shell-command} takes as arguments a format @code{control-string}
+and arguments to be passed to @code{format} after this control-string
+to produce a string.
+This string is a command that will be evaluated with a POSIX shell if possible;
+yet, on Windows, some implementations will use CMD.EXE,
+while others (like SBCL) will make an attempt at invoking a POSIX shell
+(and fail if it is not present).
+@end defun
+
+@node Some Utility Functions,  , Controlling source file character encoding, Miscellaneous additional functionality
+@section Some Utility Functions
+
+The below functions are not exported by ASDF itself, but by UIOP, available since ASDF 3.
+Some of them have precursors in ASDF 2, but we recommend
+you rely on ASDF 3 for active developments.
+UIOP provides many, many more utility functions, and we recommend
+you read its README and sources for more information.
+
+
+@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 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.
+
+When given a @code{pathname} object, just return it untouched.
+When given @code{nil}, just return @code{nil}.
+When given a non-null @code{symbol}, first downcase its name and treat it as a string.
+When given a @code{string}, portably decompose it into a pathname as below.
+
+@code{#\/} separates directory components.
+
+The last @code{#\/}-separated substring is interpreted as follows:
+1- If @var{type} is @code{:directory} or @var{ensure-directory} is true,
+ the string is made the last directory component, and its @code{name} and @code{type} are @code{nil}.
+ if the string is empty, it's the empty pathname with all slots @code{nil}.
+2- If @var{type} is @code{nil}, the substring is a file-namestring,
+ and its @code{name} and @code{type} are separated by @code{split-name-type}.
+3- If @var{type} is a string, it is the given @code{type}, and the whole string is the @code{name}.
+
+Directory components with an empty name the name @code{.} are removed.
+Any directory named @code{..} is read as @var{dot-dot},
+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*}.
+@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.
+
+For relative pathnames, these components (and hence the defaults) won't matter
+if you use @code{merge-pathnames*} but will matter if you use @code{merge-pathnames},
+which is an important reason to always use @code{merge-pathnames*}.
+
+Arbitrary keys are accepted, and the parse result is passed to @code{ensure-pathname}
+with those keys, removing @var{type}, @var{defaults} and @var{dot-dot}.
+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}
+so that @code{parse-unix-namestring} will throw an error if the pathname is absolute.
+@end defun
+
+@defun merge-pathnames* specified @Aoptional{} defaults
+
+This function is a replacement for @code{merge-pathnames} that uses the host and device
+from the @var{defaults} rather than the @var{specified} pathname when the latter
+is a relative pathname. This allows ASDF and its users to create and use relative pathnames
+without having to know beforehand what are the host and device
+of the absolute pathnames they are relative to.
+
+@end defun
+
+@defun subpathname pathname subpath @Akey{} type
+
+This function takes a @var{pathname} and a @var{subpath} and a @var{type}.
+If @var{subpath} is already a @code{pathname} object (not namestring),
+and is an absolute pathname at that, it is returned unchanged;
+otherwise, @var{subpath} is turned into a relative pathname with given @var{type}
+as per @code{parse-unix-namestring} with @code{:want-relative t :type }@var{type},
+then it is merged with the @code{pathname-directory-pathname} of @var{pathname},
+as per @code{merge-pathnames*}.
+
+We strongly encourage the use of this function
+for portably resolving relative pathnames in your code base.
+@end defun
+
+@defun subpathname* pathname subpath @Akey{} type
+
+This function returns @code{nil} if the base @var{pathname} is @code{nil},
+otherwise acts like @code{subpathname}.
+@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
+
+@code{run-program} takes a @var{command} argument that is either
+a list of a program name or path and its arguments,
+or a string to be executed by a shell.
+It spawns the command, waits for it to return,
+verifies that it exited cleanly (unless told not too below),
+and optionally captures and processes its output.
+It accepts many keyword arguments to configure its behavior.
+
+@code{run-program} returns three values: the first for the output,
+the second for the error-output, and the third for the return value.
+(Beware that before ASDF 3.0.2.11, it didn't handle input or error-output,
+and returned only one value,
+the one for the output if any handler was specified, or else the exit code;
+please upgrade ASDF, or at least UIOP, to rely on the new enhanced behavior.)
+
+@var{output} is its most important argument;
+it specifies how the output is captured and processed.
+If it is @code{nil}, then the output is redirected to the null device,
+that will discard it.
+If it is @code{:interactive}, then it is inherited from the current process
+(beware: this may be different from your @var{*standard-output*},
+and under SLIME will be on your @code{*inferior-lisp*} buffer).
+If it is @code{t}, output goes to your current @var{*standard-output*} stream.
+Otherwise, @var{output} should be a value that is a suitable first argument to
+@code{slurp-input-stream} (see below), or
+a list of such a value and keyword arguments.
+In this case, @code{run-program} will
+create a temporary stream for the program output;
+the program output, in that stream,
+will be processed by a call to @code{slurp-input-stream},
+using @var{output} as the first argument
+(or if it's a list the first element of @var{output} and the rest as keywords).
+The primary value resulting from that call
+(or @code{nil} if no call was needed)
+will be the first value returned by @code{run-program}.
+E.g., using @code{:output :string}
+will have it return the entire output stream as a string.
+And using @code{:output '(:string :stripped t)}
+will have it return the same string stripped of any ending newline.
+
+@var{error-output} is similar to @var{output}, except that
+the resulting value is returned as the second value of @code{run-program}.
+@code{t} designates the @var{*error-output*}.
+Also @code{:output} means redirecting the error output to the output stream,
+in which case @code{nil} is returned.
+
+@var{input} is similar to @var{output}, except that
+@code{vomit-output-stream} is used, no value is returned,
+and @code{t} designates the @var{*standard-input*}.
+
+@code{element-type} and @code{external-format} are passed on
+to your Lisp implementation, when applicable, for creation of the output stream.
+
+One and only one of the stream slurping or vomiting may or may not happen
+in parallel in parallel with the subprocess,
+depending on options and implementation,
+and with priority being given to output processing.
+Other streams are completely produced or consumed
+before or after the subprocess is spawned, using temporary files.
+
+@code{force-shell} forces evaluation of the command through a shell,
+even if it was passed as a list rather than a string.
+If a shell is used, it is @file{/bin/sh} on Unix or @file{CMD.EXE} on Windows,
+except on implementations that (erroneously, IMNSHO)
+insist on consulting @code{$SHELL} like clisp.
+
+@code{ignore-error-status} causes @code{run-program}
+to not raise an error if the spawned program exits in error.
+Following POSIX convention, an error is anything but
+a normal exit with status code zero.
+By default, an error of type @code{subprocess-error} is raised in this case.
+
+@code{run-program} works on all platforms supported by ASDF, except Genera.
+See the source code for more documentation.
+
+@end defun
+
+@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 follows:
+
+@itemize
+@item
+If the object is a function, the function is called with the stream as argument.
+
+@item If the object is a cons, its first element is applied to its rest appended by
+a list of the input stream.
+
+@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.
+Otherwise, copying happen based on a buffer of size @var{buffer-size},
+using the specified @var{element-type}.
+
+@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}.
+
+@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.
+
+@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.
+A number will extract the corresponding line.
+See the documentation for @code{uiop:access-at}.
+
+@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,
+it is a maximum count of lines to be read.
+We recommend you control the syntax with such macro as
+@code{uiop:with-safe-io-syntax}.
+
+@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.
+A number will extract the corresponding form.
+See the documentation for @code{uiop:access-at}.
+We recommend you control the syntax with such macro as
+@code{uiop:with-safe-io-syntax}.
+@end itemize
+@end defun
+
+
+@node Getting the latest version, FAQ, Miscellaneous additional functionality, Top
 @comment  node-name,  next,  previous,  up
 @chapter Getting the latest version
 
-@enumerate
-@item
-Decide which version you want.  HEAD is the newest version and
-usually OK, whereas RELEASE is for cautious people (e.g. who already
-have systems using asdf that they don't want broken), a slightly older
-version about which none of the HEAD users have complained.
-
-@item
-Check it out from sourceforge cCLan CVS:
-
-@kbd{cvs -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan login}
-
-(no password: just press @key{Enter})
- 
-@kbd{cvs -z3 -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan co -r RELEASE asdf}
-
-or for the bleeding edge, instead
-
-@kbd{cvs -z3 -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan co -A asdf}
-
-@end enumerate
-
-If you are tracking the bleeding edge, you may want to subscribe to
-the cclan-commits mailing list (see
-@url{http://sourceforge.net/mail/?group_id=28536}) to receive commit
-messages and diffs whenever changes are made.
-
-For more CVS information, look at
-@url{http://sourceforge.net/cvs/?group_id=28536}.
-
-
-
-
-@node  TODO list, missing bits in implementation, Getting the latest version, Top
+Decide which version you want.
+The @code{master} branch is where development happens;
+its @code{HEAD} is usually OK, including the latest fixes and portability tweaks,
+but an occasional regression may happen despite our (limited) test suite.
+
+The @code{release} branch is what cautious people should be using;
+it has usually been tested more, and releases are cut at a point
+where there isn't any known unresolved issue.
+
+You may get the ASDF source repository using git:
+@kbd{git clone git://common-lisp.net/projects/asdf/asdf.git}
+
+You will find the above referenced tags in this repository.
+You can also browse the repository on
+@url{http://common-lisp.net/gitweb?p=projects/asdf/asdf.git}.
+
+Discussion of ASDF development is conducted on the
+mailing list
+@kbd{asdf-devel@@common-lisp.net}.
+@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel}
+
+
+@node FAQ, Ongoing Work, Getting the latest version, Top
 @comment  node-name,  next,  previous,  up
-@chapter TODO list
-
-* Outstanding spec questions, things to add
-
-** packaging systems
-
-*** manual page component?
-
-** style guide for .asd files
-
-You should either use keywords or be careful with the package that you
-evaluate defsystem forms in.  Otherwise (defsystem partition ...)
-being read in the cl-user package will intern a cl-user:partition
-symbol, which will then collide with the partition:partition symbol.
-
-Actually there's a hairier packages problem to think about too.
-in-order-to is not a keyword: if you read defsystem forms in a package
-that doesn't use ASDF, odd things might happen
-
-** extending defsystem with new options
-
-You might not want to write a whole parser, but just to add options to
-the existing syntax.  Reinstate parse-option or something akin
-
-** document all the error classes
-
-** what to do with compile-file failure
-
-Should check the primary return value from compile-file and see if
-that gets us any closer to a sensible error handling strategy
-
-** foreign files
-
-lift unix-dso stuff from db-sockets
-
-** Diagnostics
-
-A ``dry run'' of an operation can be made with the following form:
+@chapter FAQ
+
+@menu
+* Where do I report a bug?::
+* What has changed between ASDF 1 and ASDF 2?::
+* Issues with installing the proper version of ASDF::
+* Issues with configuring ASDF::
+* Issues with using and extending ASDF to define systems::
+* ASDF development FAQs::
+@end menu
+
+@node Where do I report a bug?, What has changed between ASDF 1 and ASDF 2?, FAQ, FAQ
+@section  ``Where do I report a bug?''
+
+ASDF bugs are tracked on launchpad: @url{https://launchpad.net/asdf}.
+
+If you're unsure about whether something is a bug, or for general discussion,
+use the @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
+
+
+@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, 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.1 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::
+* Source Registry Configuration::
+* Usual operations are made easier to the user::
+* Many bugs have been fixed::
+* ASDF itself is versioned::
+* ASDF can be upgraded::
+* Decoupled release cycle::
+* Pitfalls of the transition to ASDF 2::
+@end menu
+
+@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),
+and to any development revision earlier than 2.000 (May 2010).
+If your copy of ASDF doesn't even contain version information, it's an old ASDF 1.
+Revisions between 1.656 and 1.728 may count as development releases for ASDF 2.
+
+ASDF 2 refers to releases from 2.000 (May 31st 2010) to 2.26 (Oct 30 2012),
+and any development revision newer than ASDF 1 and older than 2.27 (Feb 1 2013).
+
+ASDF 3 refers to releases from 2.27 (Feb 1 2013) to 2.33 and 3.0.0 onward (May 15 2013).
+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*}.
+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.1 (April 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
+to write code that takes advantage of recent ASDF functionality
+but still works on older versions, or at least detects the old version and signals an error.
+
+Additionally, all releases starting with ASDF 2
+define a function @code{(asdf:asdf-version)} you may use to query the version.
+All releases starting with 2.013 display the version number prominently
+on the second line of the @file{asdf.lisp} source file.
+
+If you are experiencing problems or limitations of any sort with ASDF 1 or ASDF 2,
+we recommend that you should upgrade to the latest release, be it ASDF 3 or other.
+
+
+@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 pathname namestrings,
+that themselves have various limitations and require a lot of setup
+that is itself ultimately non-portable.
+
+In ASDF 1, the only portable ways to refer to pathnames inside systems and components
+were very awkward, using @code{#.(make-pathname ...)} and
+@code{#.(merge-pathnames ...)}.
+Even the above were themselves were inadequate in the general case
+due to host and device issues, unless horribly complex patterns were used.
+Plenty of simple cases that looked portable actually weren't,
+leading to much confusion and greavance.
+
+ASDF 2 implements its own portable syntax for strings as pathname specifiers.
+Naming files within a system definition becomes easy and portable again.
+@xref{Miscellaneous additional functionality,system-relative-pathname},
+@code{merge-pathnames*},
+@code{coerce-pathname}.
+
+On the other hand, there are places where systems used to accept namestrings
+where you must now use an explicit pathname object:
+@code{(defsystem ... :pathname "LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
+must now be written with the @code{#p} syntax:
+@code{(defsystem ... :pathname #p"LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
+
+@xref{The defsystem grammar,,Pathname specifiers}.
+
+
+@node Output translations, Source Registry Configuration, ASDF can portably name files in subdirectories, What has changed between ASDF 1 and ASDF 2?
+@subsection Output translations
+
+A popular feature added to ASDF was output pathname translation:
+@code{asdf-binary-locations}, @code{common-lisp-controller},
+@code{cl-launch} and other hacks were all implementing it in ways
+both mutually incompatible and difficult to configure.
+
+Output pathname translation is essential to share
+source directories of portable systems across multiple implementations
+or variants thereof,
+or source directories of shared installations of systems across multiple users,
+or combinations of the above.
+
+In ASDF 2, a standard mechanism is provided for that,
+@code{asdf-output-translations},
+with sensible defaults, adequate configuration languages,
+a coherent set of configuration files and hooks,
+and support for non-Unix platforms.
+
+@xref{Controlling where ASDF saves compiled files}.
+
+@node Source Registry Configuration, Usual operations are made easier to the user, Output translations, What has changed between ASDF 1 and ASDF 2?
+@subsection Source Registry Configuration
+
+Configuring ASDF used to require special magic
+to be applied just at the right moment,
+between the moment ASDF is loaded and the moment it is used,
+in a way that is specific to the user,
+the implementation he is using and the application he is building.
+
+This made for awkward configuration files and startup scripts
+that could not be shared between users, managed by administrators
+or packaged by distributions.
+
+ASDF 2 provides a well-documented way to configure ASDF,
+with sensible defaults, adequate configuration languages,
+and a coherent set of configuration files and hooks.
+
+We believe it's a vast improvement because it decouples
+application distribution from library distribution.
+The application writer can avoid thinking where the libraries are,
+and the library distributor (dpkg, clbuild, advanced user, etc.)
+can configure them once and for every application.
+Yet settings can be easily overridden where needed,
+so whoever needs control has exactly as much as required.
+
+At the same time, ASDF 2 remains compatible
+with the old magic you may have in your build scripts
+(using @code{*central-registry*} and
+@code{*system-definition-search-functions*})
+to tailor the ASDF configuration to your build automation needs,
+and also allows for new magic, simpler and more powerful magic.
+
+@xref{Controlling where ASDF searches for systems}.
+
+
+@node Usual operations are made easier to the user, Many bugs have been fixed, Source Registry Configuration, What has changed between ASDF 1 and ASDF 2?
+@subsection Usual operations are made easier to the user
+
+In ASDF 1, you had to use the awkward syntax
+@code{(asdf:oos 'asdf:load-op :foo)}
+to load a system,
+and similarly for @code{compile-op}, @code{test-op}.
+
+In ASDF 2, you can use shortcuts for the usual operations:
+@code{(asdf:load-system :foo)}, and
+similarly for @code{compile-system}, @code{test-system}.
+
+
+@node Many bugs have been fixed, ASDF itself is versioned, Usual operations are made easier to the user, What has changed between ASDF 1 and ASDF 2?
+@subsection Many bugs have been fixed
+
+The following issues and many others have been fixed:
+
+@itemize
+@item
+The infamous TRAVERSE function has been revamped completely
+between ASDF 1 and ASDF 2, with many bugs squashed.
+In particular, dependencies were not correctly propagated
+across modules but now are.
+It has been completely rewritten many times over
+between ASDF 2.000 and ASDF 3,
+with fundamental issues in the original model being fixed.
+Timestamps were not propagated at all, and now are.
+The internal model of how actions depend on each other
+is now both consistent and complete.
+The @code{:version} and
+the @code{:force (system1 .. systemN)} feature have been fixed.
+
+@item
+Performance has been notably improved for large systems
+(say with thousands of components) by using
+hash-tables instead of linear search,
+and linear-time list accumulation instead of cubic time recursive append,
+for an overall @emph{O(n)} complexity vs @emph{O(n^4)}.
+
+@item
+Many features used to not be portable,
+especially where pathnames were involved.
+Windows support was notably quirky because of such non-portability.
+
+@item
+The internal test suite used to massively fail on many implementations.
+While still incomplete, it now fully passes
+on all implementations supported by the test suite,
+though some tests are commented out on a few implementations.
+
+@item
+Support was lacking for some implementations.
+ABCL and GCL were notably wholly broken.
+ECL extensions were not integrated with ASDF release.
+
+@item
+The documentation was grossly out of date.
+
+@end itemize
+
+
+@node ASDF itself is versioned, ASDF can be upgraded, Many bugs have been fixed, What has changed between ASDF 1 and ASDF 2?
+@subsection ASDF itself is versioned
+
+Between new features, old bugs fixed, and new bugs introduced,
+there were various releases of ASDF in the wild,
+and no simple way to check which release had which feature set.
+People using or writing systems had to either make worst-case assumptions
+as to what features were available and worked,
+or take great pains to have the correct version of ASDF installed.
+
+With ASDF 2, we provide a new stable set of working features
+that everyone can rely on from now on.
+Use @code{#+asdf2} to detect presence of ASDF 2,
+@code{(asdf:version-satisfies (asdf:asdf-version) "2.345.67")}
+to check the availability of a version no earlier than required.
+
+
+@node ASDF can be upgraded, Decoupled release cycle, ASDF itself is versioned, What has changed between ASDF 1 and ASDF 2?
+@subsection ASDF can be upgraded
+
+When an old version of ASDF was loaded,
+it was very hard to upgrade ASDF in your current image
+without breaking everything.
+Instead you had to exit the Lisp process and
+somehow arrange to start a new one from a simpler image.
+Something that can't be done from within Lisp,
+making automation of it difficult,
+which compounded with difficulty in configuration,
+made the task quite hard.
+Yet as we saw before, the task would have been required
+to not have to live with the worst case or non-portable
+subset of ASDF features.
+
+With ASDF 2, it is easy to upgrade
+from ASDF 2 to later versions from within Lisp,
+and not too hard to upgrade from ASDF 1 to ASDF 2 from within Lisp.
+We support hot upgrade of ASDF and any breakage is a bug
+that we will do our best to fix.
+There are still limitations on upgrade, though,
+most notably the fact that after you upgrade ASDF,
+you must also reload or upgrade all ASDF extensions.
+
+@node Decoupled release cycle, Pitfalls of the transition to ASDF 2, ASDF can be upgraded, What has changed between ASDF 1 and ASDF 2?
+@subsection Decoupled release cycle
+
+When vendors were releasing their Lisp implementations with ASDF,
+they had to basically never change version
+because neither upgrade nor downgrade was possible
+without breaking something for someone,
+and no obvious upgrade path was visible and recommendable.
+
+With ASDF 2, upgrade is possible, easy and can be recommended.
+This means that vendors can safely ship a recent version of ASDF,
+confident that if a user isn't fully satisfied,
+he can easily upgrade ASDF and deal
+with a supported recent version of it.
+This means that release cycles will be causally decoupled,
+the practical consequence of which will mean faster convergence
+towards the latest version for everyone.
+
+
+@node Pitfalls of the transition to ASDF 2,  , Decoupled release cycle, What has changed between ASDF 1 and ASDF 2?
+@subsection Pitfalls of the transition to ASDF 2
+
+The main pitfalls in upgrading to ASDF 2 seem to be related
+to the output translation mechanism.
+
+@itemize
+
+@item
+Output translations is enabled by default. This may surprise some users,
+most of them in pleasant way (we hope), a few of them in an unpleasant way.
+It is trivial to disable output translations.
+@xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
+
+@item
+Some systems in the large have been known
+not to play well with output translations.
+They were relatively easy to fix.
+Once again, it is also easy to disable output translations,
+or to override its configuration.
+
+@item
+The new ASDF output translations are incompatible with ASDF-Binary-Locations.
+They replace A-B-L, and there is compatibility mode to emulate
+your previous A-B-L configuration.
+See @code{enable-asdf-binary-locations-compatibility} in
+@pxref{Controlling where ASDF saves compiled files,,Backward Compatibility}.
+But thou shalt not load ABL on top of ASDF 2.
+
+@end itemize
+
+Other issues include the following:
+
+@itemize
+
+@item
+ASDF pathname designators are now specified
+in places where they were unspecified,
+and a few small adjustments have to be made to some non-portable defsystems.
+Notably, in the @code{:pathname} argument
+to a @code{defsystem} and its components,
+a logical pathname (or implementation-dependent hierarchical pathname)
+must now be specified with @code{#p} syntax
+where the namestring might have previously sufficed;
+moreover when evaluation is desired @code{#.} must be used,
+where it wasn't necessary in the toplevel @code{:pathname} argument
+(but necessary in other @code{:pathname} arguments).
+
+@item
+There is a slight performance bug, notably on SBCL,
+when initially searching for @file{asd} files,
+the implicit @code{(directory "/configured/path/**/*.asd")}
+for every configured path @code{(:tree "/configured/path/")}
+in your @code{source-registry} configuration can cause a slight pause.
+Try to @code{(time (asdf:initialize-source-registry))}
+to see how bad it is or isn't on your system.
+If you insist on not having this pause,
+you can avoid the pause by overriding the default source-registry configuration
+and not use any deep @code{:tree} entry but only @code{:directory} entries
+or shallow @code{:tree} entries.
+Or you can fix your implementation to not be quite that slow
+when recursing through directories.
+@emph{Update}: This performance bug fixed the hard way in 2.010.
+
+@item
+On Windows, only LispWorks supports proper default configuration pathnames
+based on the Windows registry.
+Other implementations make do with environment variables,
+that you may have to define yourself
+if you're using an older version of Windows.
+Windows support is somewhat less tested than Unix support.
+Please help report and fix bugs.
+@emph{Update}: As of ASDF 2.21, all implementations
+should now use the same proper default configuration pathnames
+and they should actually work, though they haven't all been tested.
+
+@item
+The mechanism by which one customizes a system so that Lisp files
+may use a different extension from the default @file{.lisp} has changed.
+Previously, the pathname for a component
+was lazily computed when operating on a system,
+and you would
+@code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
+  (declare (ignorable component system)) "lis")}.
+Now, the pathname for a component is eagerly computed when defining the system,
+and instead you will @code{(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))}
+and use @code{:default-component-class cl-source-file.lis}
+as argument to @code{defsystem},
+as detailed in a @pxref{FAQ,How do I create a system definition where all the source files have a .cl extension?} below.
+
+@findex source-file-type
+
+
+@end itemize
+
+
+@node Issues with installing the proper version of ASDF, Issues with configuring ASDF, What has changed between ASDF 1 and ASDF 2?, FAQ
+@section Issues with installing the proper version of ASDF
+
+@menu
+* My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
+* I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::
+@end menu
+
+@node My Common Lisp implementation comes with an outdated version of ASDF. What to do?, I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?, Issues with installing the proper version of ASDF, Issues with installing the proper version of ASDF
+@subsection ``My Common Lisp implementation comes with an outdated version of ASDF. What to do?''
+
+We recommend you upgrade ASDF.
+@xref{Loading ASDF,,Upgrading ASDF}.
+
+If this does not work, it is a bug, and you should report it.
+@xref{FAQ, report-bugs, Where do I report a bug}.
+In the meantime, you can load @file{asdf.lisp} directly.
+@xref{Loading ASDF,Loading an otherwise installed ASDF}.
+
+
+@node I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?,  , My Common Lisp implementation comes with an outdated version of ASDF. What to do?, Issues with installing the proper version of ASDF
+@subsection ``I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?''
+
+Since ASDF 2,
+it should always be a good time to upgrade to a recent version of ASDF.
+You may consult with the maintainer for which specific version they recommend,
+but the latest @code{release} should be correct.
+Though we do try to test ASDF releases against all implementations that we can,
+we may not be testing against all variants of your implementation,
+and we may not be running enough tests;
+we trust you to thoroughly test it with your own implementation
+before you release it.
+If there are any issues with the current release,
+it's a bug that you should report upstream and that we will fix ASAP.
+
+As to how to include ASDF, we recommend the following:
+
+@itemize
+@item
+If ASDF isn't loaded yet, then @code{(require "asdf")}
+should load the version of ASDF that is bundled with your system.
+If possible so should @code{(require "ASDF")}.
+You may have it load some other version configured by the user,
+if you allow such configuration.
+
+@item
+If your system provides a mechanism to hook into @code{CL:REQUIRE},
+then it would be nice to add ASDF to this hook the same way that
+ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it.
+Please send us appropriate code to this end.
+
+@item
+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.
+You should still include the file @file{asdf.lisp} in your source distribution
+and precompile it in your binary distribution,
+but @file{asdf.asd} if included at all,
+should be secluded from the magic systems,
+in a separate file hierarchy.
+Alternatively, you may provide the system
+after renaming it and its @file{.asd} file to e.g.
+@code{asdf-ecl} and @file{asdf-ecl.asd}, or
+@code{sb-asdf} and @file{sb-asdf.asd}.
+Indeed, if you made @file{asdf.asd} a magic system,
+then users would no longer be able to upgrade ASDF using ASDF itself
+to some version of their preference that
+they maintain independently from your Lisp distribution.
+
+@item
+If you do not have any such magic systems, or have other non-magic systems
+that you want to bundle with your implementation,
+then you may add them to the @code{wrapping-source-registry},
+and you are welcome to include @file{asdf.asd} amongst them.
+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
+Since ASDF 3, the library UIOP comes transcluded in ASDF.
+But if you want to be nice to users who care for UIOP but not for ASDF,
+you may package UIOP separately,
+so that one may @code{(require "uiop")} and not load ASDF,
+or one may @code{(require "asdf")}
+which would implicitly require and load the former.
+
+@item
+Please send us upstream any patches you make to ASDF itself,
+so we can merge them back in for the benefit of your users
+when they upgrade to the upstream version.
+
+@end itemize
+
+
+
+@node Issues with configuring ASDF, Issues with using and extending ASDF to define systems, Issues with installing the proper version of ASDF, FAQ
+@section Issues with configuring ASDF
+
+@menu
+* How can I customize where fasl files are stored?::
+* How can I wholly disable the compiler output cache?::
+@end menu
+
+@node How can I customize where fasl files are stored?, How can I wholly disable the compiler output cache?, Issues with configuring ASDF, Issues with configuring ASDF
+@subsection ``How can I customize where fasl files are stored?''
+
+@xref{Controlling where ASDF saves compiled files}.
+
+Note that in the past there was an add-on to ASDF called
+@code{ASDF-binary-locations}, developed by Gary King.
+That add-on has been merged into ASDF proper,
+then superseded by the @code{asdf-output-translations} facility.
+
+Note that use of @code{asdf-output-translations}
+can interfere with one aspect of your systems
+--- if your system uses @code{*load-truename*} to find files
+(e.g., if you have some data files stored with your program),
+then the relocation that this ASDF customization performs
+is likely to interfere.
+Use @code{asdf:system-relative-pathname} to locate a file
+in the source directory of some system, and
+use @code{asdf:apply-output-translations} to locate a file
+whose pathname has been translated by the facility.
+
+@node How can I wholly disable the compiler output cache?,  , How can I customize where fasl files are stored?, Issues with configuring ASDF
+@subsection ``How can I wholly disable the compiler output cache?''
+
+To permanently disable the compiler output cache
+for all future runs of ASDF, you can:
+
+@example
+mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/
+echo ':disable-cache' > ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
+@end example
+
+This assumes that you didn't otherwise configure the ASDF files
+(if you did, edit them again),
+and don't somehow override the configuration at runtime
+with a shell variable (see below) or some other runtime command
+(e.g. some call to @code{asdf:initialize-output-translations}).
+
+To disable the compiler output cache in Lisp processes
+run by your current shell, try (assuming @code{bash} or @code{zsh})
+(on Unix and cygwin only):
+
+@example
+export ASDF_OUTPUT_TRANSLATIONS=/:
+@end example
+
+To disable the compiler output cache just in the current Lisp process,
+use (after loading ASDF but before using it):
+
+@example
+(asdf:disable-output-translations)
+@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
+
+@menu
+* How can I cater for unit-testing in my system?::
+* How can I cater for documentation generation in my system?::
+* How can I maintain non-Lisp (e.g. C) source files?::
+* 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
+
+@node How can I cater for unit-testing in my system?, How can I cater for documentation generation in my system?, Issues with using and extending ASDF to define systems, Issues with using and extending ASDF to define systems
+@subsection ``How can I cater for unit-testing in my system?''
+
+ASDF provides a predefined test operation, @code{test-op}.
+@xref{Predefined operations of ASDF, test-op}.
+The test operation, however, is largely left to the system definer to specify.
+@code{test-op} has been
+a topic of considerable discussion on the
+@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list},
+and on the
+@url{https://launchpad.net/asdf,launchpad bug-tracker}.
+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
+@subsection ``How can I cater for documentation generation in my system?''
+
+Various ASDF extensions provide some kind of @code{doc-op} operation.
+See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
+
+
+@node How can I maintain non-Lisp (e.g. C) source files?, I want to put my module's files at the top level.  How do I do this?, How can I cater for documentation generation in my system?, Issues with using and extending ASDF to define systems
+@subsection ``How can I maintain non-Lisp (e.g. C) source files?''
+
+See @code{cffi}'s @code{cffi-grovel}.
+
+@anchor{report-bugs}
+
+
+@node 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 can I maintain non-Lisp (e.g. C) source files?, Issues with using and extending ASDF to define systems
+@subsection ``I want to put my module's files at the top level.  How do I do this?''
+
+By default, the files contained in an asdf module go
+in a subdirectory with the same name as the module.
+However, this can be overridden by adding a @code{:pathname ""} argument
+to the module description.
+For example, here is how it could be done
+in the spatial-trees ASDF system definition for ASDF 2:
+
+@example
+(asdf:defsystem :spatial-trees
+  :components
+  ((:module base
+            :pathname ""
+            :components
+            ((:file "package")
+             (:file "basedefs" :depends-on ("package"))
+             (:file "rectangles" :depends-on ("package"))))
+   (:module tree-impls
+            :depends-on (base)
+            :pathname ""
+            :components
+            ((:file "r-trees")
+             (:file "greene-trees" :depends-on ("r-trees"))
+             (:file "rstar-trees" :depends-on ("r-trees"))
+             (:file "rplus-trees" :depends-on ("r-trees"))
+             (:file "x-trees" :depends-on ("r-trees" "rstar-trees"))))
+   (:module viz
+            :depends-on (base)
+            :pathname ""
+            :components
+            ((:static-file "spatial-tree-viz.lisp")))
+   (:module tests
+            :depends-on (base)
+            :pathname ""
+            :components
+            ((:static-file "spatial-tree-test.lisp")))
+   (:static-file "LICENCE")
+   (:static-file "TODO")))
+@end example
+
+All of the files in the @code{tree-impls} module are at the top level,
+instead of in a @file{tree-impls/} subdirectory.
+
+Note that the argument to @code{:pathname} can be either a pathname object or a string.
+A pathname object can be constructed with the @file{#p"foo/bar/"} syntax,
+but this is discouraged because the results of parsing a namestring are not portable.
+A pathname can only be portably constructed with such syntax as
+@code{#.(make-pathname :directory '(:relative "foo" "bar"))},
+and similarly the current directory can only be portably specified as
+@code{#.(make-pathname :directory '(:relative))}.
+However, as of ASDF 2, you can portably use a string to denote a pathname.
+The string will be parsed as a @code{/}-separated path from the current directory,
+such that the empty string @code{""} denotes the current directory, and
+@code{"foo/bar"} (no trailing @code{/} required in the case of modules)
+portably denotes the same subdirectory as above.
+When files are specified, the last @code{/}-separated component is interpreted
+either as the name component of a pathname
+(if the component class specifies a pathname type),
+or as a name component plus optional dot-separated type component
+(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?, 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?
+
+Starting with ASDF 2.014.14, you may just pass
+the builtin class @code{cl-source-file.cl} as
+the @code{:default-component-class} argument to @code{defsystem}:
 
 @lisp
-(traverse (make-instance '<operation-name>)
-          (find-system <system-name>)
-          'explain)
+(defsystem my-cl-system
+  :default-component-class cl-source-file.cl
+  ...)
 @end lisp
 
-This uses unexported symbols.  What would be a nice interface for this
-functionality?
-
-@node  missing bits in implementation, Inspiration, TODO list, Top
+Another builtin class @code{cl-source-file.lsp} is offered
+for files ending in @file{.lsp}.
+
+If you want to use a different extension
+for which ASDF doesn't provide builtin support,
+or want to support versions of ASDF
+earlier than 2.014.14 (but later than 2.000),
+you can define a class as follows:
+
+@lisp
+;; Prologue: make sure we're using a sane package.
+(defpackage :my-asdf-extension
+   (:use :asdf :common-lisp)
+   (:export #:cl-source-file.lis))
+(in-package :my-asdf-extension)
+
+(defclass cl-source-file.lis (cl-source-file)
+  ((type :initform "lis")))
+@end lisp
+
+Then you can use it as follows:
+@lisp
+(defsystem my-cl-system
+  :default-component-class my-asdf-extension:cl-source-file.lis
+  ...)
+@end lisp
+
+Of course, if you're in the same package, e.g. in the same file,
+you won't need to use the package qualifier before @code{cl-source-file.lis}.
+Actually, if all you're doing is defining this class
+and using it in the same file without other fancy definitions,
+you might skip package complications:
+
+@lisp
+(in-package :asdf)
+(defclass cl-source-file.lis (cl-source-file)
+   ((type :initform "lis")))
+(defsystem my-cl-system
+  :default-component-class cl-source-file.lis
+  ...)
+@end lisp
+
+It is possible to achieve the same effect
+in a way that supports both ASDF 1 and ASDF 2,
+but really, friends don't let friends use ASDF 1.
+Please upgrade to ASDF 3.
+In short, though: do same as above, but
+@emph{before} you use the class in a @code{defsystem},
+you also define the following method:
+
+@lisp
+(defmethod source-file-type ((f cl-source-file.lis) (s system))
+  (declare (ignorable f s))
+  "lis")
+@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
+
+@menu
+* How do run the tests interactively in a REPL?::
+@end menu
+
+@node How do run the tests interactively in a REPL?,  , ASDF development FAQs, ASDF development FAQs
+@subsection How do run the tests interactively in a REPL?
+
+This not-so-frequently asked question is primarily for ASDF developers,
+but those who encounter an unexpected error in some test may be
+interested, too.
+
+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")
+
+;; 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
+
+
+@comment FIXME: Add a FAQ about how to use a new system class...
+
 @comment  node-name,  next,  previous,  up
-@chapter missing bits in implementation
-
-** all of the above
-
-** reuse the same scratch package whenever a system is reloaded from disk
-
-** rules for system pathname defaulting are not yet implemented properly
-
-** proclamations probably aren't
-
-** when a system is reloaded with fewer components than it previously
-   had, odd things happen
-
-we should do something inventive when processing a defsystem form,
-like take the list of kids and setf the slot to nil, then transfer
-children from old to new list as they're found
-
-**  traverse may become a normal function
-
-If you're defining methods on traverse,  speak up.
-
-
-** a lot of load-op methods can be rewritten to use input-files
-
-so should be.
-
-
-** (stuff that might happen later)
-
-*** david lichteblau's patch for symlink resolution?
-
-*** Propagation of the :force option.  ``I notice that
-
-	(oos 'compile-op :araneida :force t)
-
-also forces compilation of every other system the :araneida system
-depends on.  This is rarely useful to me; usually, when I want to force
-recompilation of something more than a single source file, I want to
-recompile only one system.  So it would be more useful to have
-make-sub-operation refuse to propagate @code{:force t} to other systems, and
-propagate only something like @code{:force :recursively}.
-
-Ideally what we actually want is some kind of criterion that says to
-which systems (and which operations) a @code{:force} switch will
-propagate.
-
-The problem is perhaps that `force' is a pretty meaningless concept.
-How obvious is it that @code{load :force t} should force
-@emph{compilation}?  But we don't really have the right dependency
-setup for the user to compile @code{:force t} and expect it to work
-(files will not be loaded after compilation, so the compile
-environment for subsequent files will be emptier than it needs to be)
-
-What does the user actually want to do when he forces?  Usually, for
-me, update for use with a new version of the lisp compiler.  Perhaps
-for recovery when he suspects that something has gone wrong.  Or else
-when he's changed compilation options or configuration in some way
-that's not reflected in the dependency graph.
-
-Other possible interface: have a 'revert' function akin to 'make clean'
-
-@lisp
-(asdf:revert 'asdf:compile-op 'araneida) 
-@end lisp
-
-would delete any files produced by 'compile-op 'araneida.  Of course, it
-wouldn't be able to do much about stuff in the image itself.
-
-How would this work?
-
-traverse
-
-There's a difference between a module's dependencies (peers) and its
-components (children).  Perhaps there's a similar difference in
-operations?  For example, @code{(load "use") depends-on (load "macros")} is a
-peer, whereas @code{(load "use") depends-on (compile "use")} is more of a
-`subservient' relationship.
-
-@node  Inspiration, Concept Index, missing bits in implementation, Top
-@comment  node-name,  next,  previous,  up
-@chapter Inspiration
-
-@section mk-defsystem (defsystem-3.x)
-
-We aim to solve basically the same problems as mk-defsystem does.
-However, our architecture for extensibility better exploits CL
-language features (and is documented), and we intend to be portable
-rather than just widely-ported.  No slight on the mk-defsystem authors
-and maintainers is intended here; that implementation has the
-unenviable task of supporting pre-ANSI implementations, which is 
-no longer necessary.
-
-The surface defsystem syntax of asdf is more-or-less compatible with
-mk-defsystem, except that we do not support the @code{source-foo} and
-@code{binary-foo} prefixes for separating source and binary files, and 
-we advise the removal of all options to specify pathnames.
-
-The mk-defsystem code for topologically sorting a module's dependency
-list was very useful.
-
-@section defsystem-4 proposal
-
-Marco and Peter's proposal for defsystem 4 served as the driver for
-many of the features in here.  Notable differences are:
+@node  Ongoing Work, Bibliography, FAQ, Top
+@unnumbered Ongoing Work
+For an active list of things to be done,
+see the @file{TODO} file in the source repository.
+
+Also, bugs are now tracked on launchpad:
+@url{https://launchpad.net/asdf}.
+
+@node Bibliography, Concept Index, Ongoing Work, Top
+@unnumbered Bibliography
 
 @itemize
-@item
-We don't specify output files or output file extensions as part of the
-system.  
-
-If you want to find out what files an operation would create, ask the
-operation.
-
-@item
-We don't deal with CL packages
-
-If you want to compile in a particular package, use an in-package form
-in that file (ilisp / SLIME will like you more if you do this anyway)
-
-@item
-There is no proposal here that defsystem does version control.  
-
-A system has a given version which can be used to check dependencies,
-but that's all.
+@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.
+  The Quicklisp blog and Xach's livejournal contain information on Quicklisp.
+  @url{http://blog.quicklisp.org/}
+  @url{http://xach.livejournal.com/}
+@item Francois-Rene Rideau and Robert Goldman:
+  ``Evolving ASDF: More Cooperation, Less Coordination'', 2010.
+  This article describes the main issues solved by ASDF 2.
+  @url{http://common-lisp.net/project/asdf/doc/ilc2010draft.pdf}
+  @url{http://www.common-lisp.org/gitweb?p=projects/asdf/ilc2010.git}
+@item Francois-Rene Rideau and Spencer Brody:
+  ``XCVB: an eXtensible Component Verifier and Builder for Common Lisp'', 2009.
+  This article describes XCVB, a proposed competitor for ASDF,
+  many ideas of which have been incorporated into ASDF 2 and 3,
+  though many other of which still haven't.
+  @url{http://common-lisp.net/projects/xcvb/}
+@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,
+  and comparisons with older defsystems (@code{mk-defsystem})
+  and defsystem (@code{defsystem-4}, kmp's Memo 801).
+@item Marco Antoniotti and Peter Van Eynde:
+ ``@code{DEFSYSTEM}: A @code{make} for Common Lisp, A Thoughtful Re-Implementation of an Old Idea'', 2002.
+  The @file{defsystem-4} proposal available in the CLOCC repository.
+@item Mark Kantrovitz: ``Defsystem: A Portable Make Facility for Common Lisp'', 1990.
+  The classic @file{mk-defsystem}, later variants of which
+  are available in the CLOCC repository as @code{defsystem-3.x}.
+@item Richard Elliot Robbins:
+  ``BUILD: A Tool for Maintaining Consistency in Modular Systems'', MIT AI TR 874, 1985.
+  @url{ftp://publications.ai.mit.edu/ai-publications/pdf/AITR-874.pdf}
+@item Kent M. Pitman (kmp): ``The Description of Large Systems'', MIT AI Memo 801, 1984.
+  Available in updated-for-CL form on the web at
+  @url{http://nhplace.com/kent/Papers/Large-Systems.html}
+@item Dan Weinreb and David Moon:
+  ``Lisp Machine Manual'', MIT, 1981.
+  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}
 @end itemize
 
-The defsystem 4 proposal tends to look more at the external features,
-whereas this one centres on a protocol for system introspection.
-
-@section kmp's ``The Description of Large Systems'', MIT AI Memu 801
-
-Available in updated-for-CL form on the web at 
-@url{http://world.std.com/~pitman/Papers/Large-Systems.html}
-
-In our implementation we borrow kmp's overall PROCESS-OPTIONS and
-concept to deal with creating component trees from defsystem surface
-syntax.  [ this is not true right now, though it used to be and
-probably will be again soon ]
-
-
-@c -------------------
-
-
-@node Concept Index, Function and Class Index, Inspiration, Top
+
+@node Concept Index, Function and Class Index, Bibliography, Top
 @unnumbered Concept Index
-     
+
 @printindex cp
 
 @node Function and Class Index, Variable Index, Concept Index, Top
 @unnumbered Function and Class Index
-     
+
 @printindex fn
 
 @node Variable Index,  , Function and Class Index, Top
 @unnumbered Variable Index
-     
+
 @printindex vr
 
-
-
-
 @bye
-