+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 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 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 sport said features:
+ :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
+
+ ;; 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 name
+
+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
+ ;; Not valid anymore: :SYSTEM-CACHE (was a security hazard)
+
+RELATIVE-COMPONENT-DESIGNATOR :=
+ (RELATIVE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
+ STRING | ;; relative directory pathname as interpreted by coerce-pathname.
+ ;; In output translations, if last component, **/*.*.* is added
+ PATHNAME | ;; pathname; unless last component, directory is assumed.
+ :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
+ :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
+ :DEFAULT-DIRECTORY | ;; a relativized version of the default directory
+ :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
+ :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
+ :*.*.* | ;; any file (since ASDF 2.011.4)
+ ;; Not supported (anymore): :UID and :USERNAME
+@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
+
+@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.
+
+This allows for packaging software that has file granularity
+(e.g. Debian's @code{dpkg} or some future version of @code{clbuild})
+to easily include configuration information about distributed software.
+
+The convention is that, for sorting purposes,
+the names of files in such a directory begin with two digits
+that determine the order in which these entries will be read.
+Also, the type of these files is conventionally @code{"conf"}
+and as a limitation to some implementations (e.g. GNU clisp),
+the type cannot be @code{NIL}.
+
+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
+
+@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.
+
+@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.
+
+
+@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).
+
+
+@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.
+
+
+@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 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.
+
+
+@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.
+
+
+@section Rejected ideas
+
+Alternatives I considered and rejected 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*} remains 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
+
+@section TODO
+
+@itemize
+@item Add examples
+@end itemize
+
+
+@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 to 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 (fasls for short, short for ``fast loading'').
+If you use multiple implementations
+(or multiple versions of the same implementation),
+you'll soon find your source directories
+littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so on.
+Worse yet, some implementations use the same file extension
+while changing formats from version to version (or platform to platform)
+which means that you'll have to recompile binaries
+as you switch from one implementation to the next.
+
+Since ASDF 2, ASDF includes the @code{asdf-output-translations} facility
+to mitigate the problem.
+
+@section Configurations
+
+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 trival 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.
+
+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.
+
+
+@section Backward Compatibility
+@cindex ASDF-BINARY-LOCATIONS compatibility
+
+
+We purposefully do NOT provide backward compatibility with earlier versions of
+@code{ASDF-Binary-Locations} (8 Sept 2009),
+@code{common-lisp-controller} (7.0) or
+@code{cl-launch} (2.35),
+each of which had similar general capabilities.
+The previous APIs of these programs were not designed
+for configuration by the end-user
+in an easy way with configuration files.
+Recent versions of same packages use
+the new @code{asdf-output-translations} API as defined below:
+@code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000).
+@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)}.
+
+
+@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 sport said features:
+ :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
+
+ ;; 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 leaves pathname unmapped.
+ ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language
+
+TRANSLATION-FUNCTION :=
+ SYMBOL | ;; symbol of a function that takes two arguments,
+ ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
+ LAMBDA ;; A form which evalutates to a function taking two arguments consisting of
+ ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
+
+@end verbatim
+
+Relative components better be either relative
+or subdirectories of the path before them, or bust.
+
+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:
+@verbatim
+ #.(let ((wild-subdir (make-pathname :directory '(:relative :wild-inferiors)))
+ (wild-file (make-pathname :name :wild :version :wild :type :wild)))
+ `((:root ,wild-subdir ,wild-file) ;; Or using the implicit wildcard, just :root
+ (:root ,wild-subdir :implementation ,wild-file)))
+@end verbatim
+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.
+The result of the function invocation should be the translated pathname.
+
+An @code{:inherit-configuration} statement cause the search to recurse with the path
+specifications from the next configuration.
+@xref{Controlling where ASDF saves compiled files,,Configurations}, above.
+
+@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)}.
+@item
+@code{:system-cache} uses the contents of variable @code{asdf::*system-cache*}
+which by default is the same as using
+@code{("/var/cache/common-lisp" :uid :implementation-type)}
+(on Unix and cygwin), or something semi-sensible on Windows.
+@end itemize
+
+
+@section Configuration Directories
+
+Configuration directories consist in files each 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.
+
+This allows for packaging software that has file granularity
+(e.g. Debian's @command{dpkg} or some future version of @command{clbuild})
+to easily include configuration information about software being distributed.
+
+The convention is that, for sorting purposes,
+the names of files in such a directory begin with two digits
+that determine the order in which these entries will be read.
+Also, the type of these files is conventionally @code{"conf"}
+and as a limitation of some implementations, the type cannot be @code{NIL}.
+
+Directories may be included by specifying a directory pathname
+or namestring in an @code{:include} directive, e.g.:
+@verbatim
+ (:include "/foo/bar/")
+@end verbatim
+
+@section Shell-friendly syntax for configuration
+
+When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS}
+ASDF will skip to next configuration if it's an empty string.
+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).
+
+
+@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).
+
+@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.
+
+
+@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 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.
+
+
+@section Credits for output translations
+
+Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations},
+and to Peter van Eynde for @code{Common Lisp Controller}.
+
+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
+
+@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
+@code{OPERATION-ERROR}.
+
+@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 @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.
+
+@section Controlling file compilation
+
+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 a either @code{nil}, a 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).
+
+
+@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,
+the default @code{:autodetect} is assumed.
+By default, only @code{:default}, @code{:utf-8}
+and @code{:autodetect} are accepted.
+@code{:autodetect}, the default, calls
+@code{*encoding-detection-hook*} which by default always returns
+@code{*default-encoding*} which itself defaults to @code{:default}.
+
+In other words, there now are plenty of extension hooks, but
+by default ASDF follows the backwards compatible behavior
+of using whichever @code{:default} encoding your implementation uses,
+which itself may or may not vary based on environment variables
+and other locale settings.
+In practice this means that only source code that only uses ASCII
+is guaranteed to be read the same on all implementations
+independently from any user setting.
+
+Additionally, for backward-compatibility with older versions of ASDF
+and/or with implementations that do not support unicode and its many encodings,
+you may want to use
+the reader conditionals @code{#+asdf-unicode #+asdf-unicode}
+to protect any @code{:encoding @emph{encoding}} statement
+as @code{:asdf-unicode} will be present in @code{*features*}
+only if you're using a recent ASDF
+on an implementation that supports unicode.
+We recommend that you avoid using unprotected @code{:encoding} specifications
+until after ASDF 2.21 or later becomes widespread, hopefully by the end of 2012.
+
+While it offers plenty of hooks for extension,
+and one such extension is being developed (see 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 @code{.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.
+In the future, we intend to make @code{:utf-8}
+the default value of @code{*default-encoding*},
+to be enforced everywhere, so at least the code is guaranteed
+to be read correctly everywhere it can be.
+
+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 @code{.asd} file.
+Using the @code{*encoding-detection-hook*} it will also
+eventually implement some autodetection of a file's encoding
+from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration,
+or otherwise based on an analysis of octet patterns in the file.
+At this point, asdf-encoding only supports the encodings
+that are supported as part of your implementation.
+Since the list varies depending on implementations,
+we once again recommend you use @code{:utf-8} everywhere,
+which is the most portable (next is @code{:latin1}).
+
+If you're not using a version of Quicklisp that has it,
+you may get the source for @code{asdf-encodings} using git:
+@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}.
+
+In the future, we intend to change the default @code{*default-encoding*}
+to @code{:utf-8}, which is already the de facto standard
+for most libraries that use non-ASCII characters:
+utf-8 works everywhere and was backhandedly enforced by
+a lot of people using SBCL and utf-8 and sending reports to authors
+so they make their packages compatible.
+A survey showed only about a handful few libraries
+are incompatible with non-UTF-8, and then, only in comments,
+and we believe that authors will adopt UTF-8 when prompted.
+See the April 2012 discussion on the asdf-devel mailing-list.
+For backwards compatibility with users who insist on a non-UTF-8 encoding,
+but cannot immediately transition to using @code{asdf-encodings}
+(maybe because it isn't ready), it will still be possible to use
+the @code{:encoding :default} option in your @code{defsystem} form
+to restore the behavior of ASDF 2.20 and earlier.
+This shouldn't be required in libraries,
+because user pressure as mentioned above will already have pushed
+library authors towards using UTF-8;
+but authors of end-user programs might care.
+
+When you use @code{asdf-encodings}, any further loaded @code{.asd} file
+will use the autodetection algorithm to determine its encoding;
+yet if you depend on this detection happening,
+you may want to explicitly load @code{asdf-encodings} early in your build,
+for by the time you can use @code{:defsystem-depends-on},
+it is already too late to load it.
+In practice, this means that the @code{*default-encoding*}
+is usually used for @code{.asd} files.
+Currently, this defaults to @code{:default} for backwards compatibility,
+and that means that you shouldn't rely on non-ASCII characters in a .asd file.
+Since component (path)names are the only real data in these files,
+and non-ASCII characters are not very portable for file names,
+this isn't too much of an issue.
+We still encourage you to use either plain ASCII or UTF-8
+in @code{.asd} files,
+as we intend to make @code{:utf-8} the default encoding in the future.
+This might matter, for instance, in meta-data about author's names.
+
+
+@section Miscellaneous Functions
+
+Most of these functions are not exported by ASDF anymore,
+but only used for private purposes of ASDF.
+Please use ASDF-UTILS for the same functions exported from a stable library.
+
+@defun coerce-pathname name @Akey type defaults
+
+This function (available starting with ASDF 2.012.11)
+takes an argument, and portably interprets it as a pathname.
+If the argument @var{name} is a pathname or @code{nil}, it is passed through;
+if it's a symbol, it's interpreted as a string by downcasing it;
+if it's a string, it is first separated using @code{/} into substrings;
+the leading substrings denote subdirectories of a relative pathname.
+If @var{type} is @code{:directory} or the string ends with @code{/},
+the last substring is also a subdirectory;
+if @var{type} is a string, it is used as the type of the pathname, and
+the last substring is the name component of the pathname;
+if @var{type} is @code{nil}, the last substring specifies both name and type components
+of the pathname, with the last @code{.} separating them, or only the name component
+if there's no last @code{.} or if there is only one dot and it's the first character.
+The host, device and version components come from @var{defaults}, which defaults to
+@var{*default-pathname-defaults*}; but that shouldn't matter if you use @code{merge-pathnames*}.
+
+@end defun
+
+@defun merge-pathnames* @Akey specified 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 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.
+In these cases, it may be useful to @code{(asdf:clear-system :foo)}
+to remove the system from the table of currently loaded systems;
+the next time the system @code{foo} or one that depends on it is re-loaded,
+@code{foo} will then be loaded again.
+Alternatively, you could touch @code{foo.asd} or
+remove the corresponding fasls from the output file cache.
+(It was once conceived that one should provide
+a list of systems the recompilation of which to force
+as the @code{:force} keyword argument to @code{load-system};
+but this has never worked, and though the feature was fixed in ASDF 2.000,
+it remains @code{cerror}'ed out as nobody ever used it.)
+
+Note that this does not and cannot by itself undo the previous loading
+of the system. Common Lisp has no provision for such an operation,
+and its reliance on irreversible side-effects to global datastructures
+makes such a thing impossible in the general case.
+If the software being re-loaded is not conceived with hot upgrade in mind,
+this re-loading may cause many errors, warnings or subtle silent problems,
+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 through notable pains to make such a hot upgrade possible
+with respect to its own code, and what it does is ridiculously complex;
+look at the beginning of @file{asdf.lisp} to see what it does.
+@end defun
+
+@defun run-program
+
+run-program takes a @var{COMMAND} argument that is either
+a list of a program 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{output} is its most important argument;
+it specifies how the output is captured and processed.
+If it is @code{nil}, then the output is not captured.
+If it is @code{:interactive}, then
+input and output are inherited from the current process,
+which the subprocess can control until it exits.
+Otherwise, the output is captured and redirected to a stream,
+and processed by @code{slurp-input-stream} with the object as first argument.
+See below.
+
+@code{element-type} and @code{external-format} are passed on
+to your Lisp implementation, when available, for creation of the output stream.
+
+@code{force-shell} forces evaluation of the command through a shell,
+even if it was passed as a list rather than a string.
+
+@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.
+
+run-program works on all platforms supported by ASDF, except Genera.
+
+@end defun
+
+@defun slurp-input-stream
+
+It's a generic function of two arguments, a target object and an input stream,
+and accepting keyword arguments.
+Predefined methods based on the target object are as follow:
+
+If the object is a function, the function is called with the stream as argument.
+
+If the object is a cons, its first element is applied to its rest appended by
+a list of the input stream.
+
+If the object is an output stream, the contents of the input stream are copied to it.
+If the linewise argument is provided, copying happens line by line,
+and an optional prefix is printed before each line.
+Otherwise, copying happen based on a buffer of size buffer-size,
+using the element-type.
+
+If the object is 'string or :string, the content is captured into a string
+of the given element-type.
+
+If the object is :lines, the content is captured as a list of strings,
+one per line, without line ending. If the count argument is provided,
+it is a maximum count of lines to be read.
+
+If the object is :line, the content is capture as with :lines above,
+and then its sub-object is extracted with the path argument,
+which defaults to 0, extracting the first line.
+A number will extract the corresponding line.
+See the documentation for asdf-driver:sub-object.
+
+If the object is :forms, the content is captured as a list of S-expressions,
+as read by the Lisp reader.
+If the count argument is provided,
+it is a maximum count of lines to be read.
+We recommend you control the syntax with such macro as
+asdf-driver:with-safe-io-syntax.
+
+If the object is :form, the content is capture as with :forms above,
+and then its sub-object is extracted with the path argument,
+which defaults to 0, extracting the first form.
+A number will extract the corresponding form.
+See the documentation for asdf-driver:sub-object.
+We recommend you control the syntax with such macro as
+asdf-driver:with-safe-io-syntax.
+
+@end defun
+
+@defun run-shell-command
+
+This function is obsolete and present only for the sake of backwards-compatibility:
+``If it's not backwards, it's not compatible''. We 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} above
+available as part of ASDF since ASDF 3.
+
+@code{run-shell-command} takes as arguments a @code{format} 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 Getting the latest version, FAQ, Miscellaneous additional functionality, Top
+@comment node-name, next, previous, up
+@chapter Getting the latest version
+
+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, TODO list, Getting the latest version, Top
+@comment node-name, next, previous, up
+@chapter 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}
+
+
+@section ``What has changed between ASDF 1 and ASDF 2?''
+
+@subsection What are ASDF 1 and ASDF 2?
+
+On May 31st 2010, we have released ASDF 2.
+ASDF 2 refers to release 2.000 and later.
+(Releases between 1.656 and 1.728 were development releases for ASDF 2.)
+ASDF 1 to any release earlier than 1.369 or so.
+If your ASDF doesn't sport a version, it's an old ASDF 1.
+
+ASDF 2 and its release candidates push
+@code{:asdf2} onto @code{*features*} so that if you are writing
+ASDF-dependent code you may check for this feature
+to see if the new API is present.
+@emph{All} versions of ASDF should have the @code{:asdf} feature.
+
+Additionally, all versions of ASDF 2
+define a function @code{(asdf:asdf-version)} you may use to query the version;
+and the source code of recent versions of ASDF 2 features the version number
+prominently on the second line of its source code.
+
+If you are experiencing problems or limitations of any sort with ASDF 1,
+we recommend that you should upgrade to ASDF 2,
+or whatever is the latest release.
+
+
+@subsection ASDF can portably name files in subdirectories
+
+Common Lisp namestrings are not portable,
+except maybe for logical pathnamestrings,
+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,asdf: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}.
+
+
+@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}.
+
+@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}.
+
+
+@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}.
+
+
+@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 :version and
+the :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 quadratic-time recursive appends.
+
+@item
+Many features used to not be portable,
+especially where pathnames were involved.
+Windows support was notably quirky because of such non-portability.
+
+@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,
+except for GCL (due to GCL bugs).
+
+@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
+
+
+@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.
+
+
+@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.
+
+@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.
+
+
+@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
+
+
+@section 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}.
+
+
+@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.
+We trust you to thoroughly test it with your 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, have ASDF be implicitly used to require systems
+that are bundled with your Lisp distribution.
+If you do have a few magic systems that come with your implementation
+in a precompiled way such that one should only use the binary version
+that goes with your distribution, like SBCL does,
+then you should add them in the beginning of @code{wrapping-source-registry}.
+
+@item
+If you have magic systems as above, like SBCL does,
+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.
+
+@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
+
+
+
+@section 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.
+
+@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
+
+@section 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}.
+
+Here are some guidelines:
+
+@itemize
+@item
+For a given system, @var{foo}, you will want to define a corresponding
+test system, such as @var{foo-test}. The reason that you will want this
+separate system is that ASDF does not out of the box supply components
+that are conditionally loaded. So if you want to have source files
+(with the test definitions) that will not be loaded except when testing,
+they should be put elsewhere.
+
+@item
+The @var{foo-test} system can be defined in an asd file of its own or
+together with @var{foo}. An aesthetic preference against cluttering up
+the filesystem with extra asd files should be balanced against the
+question of whether one might want to directly load @var{foo-test}.
+Typically one would not want to do this except in early stages of
+debugging.
+
+@item
+Record that testing is implemented by @var{foo-test}. For example:
+@example
+(defsystem @var{foo}
+ :in-order-to ((test-op (test-op @var{foo-test})))
+ ....)
+
+(defsystem @var{foo-test}
+ :depends-on (@var{foo} @var{my-test-library} ...)
+ ....)
+@end example
+@end itemize
+
+This procedure will allow you to support users who do not wish to
+install your test framework.
+
+One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
+does not return a value. So in current versions of ASDF there is no
+reliable programmatic means of determining whether or not a set of tests
+has passed, or which tests have failed. The user must simply read the
+console output. This limitation has been the subject of much
+discussion.
+
+@subsection ``How can I cater for documentation generation in my system?''
+
+The ASDF developers are currently working to add a @code{doc-op}
+to the set of predefined ASDF operations.
+@xref{Predefined operations of ASDF}.
+See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
+
+
+
+@subsection ``How can I maintain non-Lisp (e.g. C) source files?''
+
+See @code{cffi}'s @code{cffi-grovel}.
+
+@anchor{report-bugs}
+
+
+@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).
+
+@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}: