Skip to content
Snippets Groups Projects
asdf.texinfo 242 KiB
Newer Older
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 algorithm.  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*}
@code{:enable-user-cache} is the same as @code{(t :user-cache)}.
@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)}.
@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
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
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
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
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
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).
@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.
@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.
@defun apply-output-translations PATHNAME
   Applies the configured output location translations to @var{PATHNAME}
   (calls @code{ensure-output-translations} for the translations).
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.

Robert P. Goldman's avatar
Robert P. Goldman committed
@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

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-failure-behaviour*
ASDF checks for warnings and errors when a file is compiled.
The variables @var{*compile-file-warnings-behaviour*} and
@var{*compile-file-failure-behaviour*}
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.

Robert P. Goldman's avatar
Robert P. Goldman committed
@menu
* Controlling file compilation::
* Controlling source file character encoding::
* Miscellaneous Functions::
Robert P. Goldman's avatar
Robert P. Goldman committed
* 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
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, Miscellaneous 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 behaviour
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.
As of May 2015, all maintained implementations provide ASDF 3,
so you may prudently start using this and other features without such protection.

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.
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 https://gitlab.common-lisp.net/asdf/asdf-encodings.git}
@kbd{git clone git@@gitlab.common-lisp.net:asdf/asdf-encodings.git}.
You can also browse the repository on
@url{https://gitlab.common-lisp.net/asdf/asdf-encodings}.
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.
@node Miscellaneous Functions, Some Utility Functions, Controlling source file character encoding, Miscellaneous additional functionality
@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:
> (asdf:system-relative-pathname 'cl-ppcre "regex.data")
#P"/repository/other/cl-ppcre/regex.data"
@end lisp

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.
@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}.
@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 register-immutable-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{immutable}.
That is, its code has already been loaded into the current image,
and if at some point some other system @code{:depends-on} it,
it is considered as already provided, and
no attempt will be made to search for an updated version from the source-registry
or any other method.
There will be no search for an @file{.asd} file, and no @code{missing-component} error.

This function (available since ASDF 3.1.5) is particularly useful if
you distribute a large body of code as a precompiled image,
and want to allow users to extend the image with further extension systems,
but without making thousands of filesystem requests looking for inexistent (or worse, out of date) source code
for all the systems that came bundled with the image but aren't
distributed as source code to regular users.
@cindex immutable systems
@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 behaviour 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.
@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 behaviour.
@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 behaviour.)

@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.
@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:
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
@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}.
@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 https://gitlab.common-lisp.net/asdf/asdf.git}
You will find the above referenced tags in this repository.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
You can also browse the repository on
@url{https://gitlab.common-lisp.net/asdf/asdf}.
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
@menu
* Where do I report a bug?::
* What has changed between ASDF 1 ASDF 2 and ASDF 3?::
* 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 ASDF 2 and ASDF 3?, 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 ASDF 2 and ASDF 3?, 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?''
ASDF 3.0.0 on May 15th 2013,
ASDF 3.1.2 on May 6th 2014.
Releases of ASDF 2 and now ASDF 3 have since then been included
in all actively maintained CL implementations that used to bundle ASDF 1,
plus many 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 ASDF 2 and ASDF 3?''}.

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 replacing 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}.

Note that in the context of compatibility requirements,
ASDF 2.27, released on Feb 1st 2013, and further releases up to 2.33,
count as pre-releases of ASDF 3, and define the @code{:asdf3} feature,
though the first stable release of ASDF 3 was release 3.0.1.
Significant new or improved functionality were added in ASDF 3.1;
the @code{:asdf3.1} feature is present in recent enough versions to detect this functionality;
the first stable release since then was ASDF 3.1.2.
New @code{*features*} are only added at major milestones,
and the next one will probably be @code{:asdf3.2}.
@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::
* What happened to the bundle operations::
@node What are ASDF 1 2 3?, How do I detect the ASDF version?, What has changed between ASDF 1 ASDF 2 and ASDF 3?, What has changed between ASDF 1 ASDF 2 and ASDF 3?
@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 30th 2012),
and any development revision newer than ASDF 1 and older than 2.27 (Feb 1st 2013).
ASDF 3 refers to releases from 2.27 (Feb 1st 2013) to 2.33 and 3.0.0 onward (May 15th 2013).
2.27 to 2.33 count as pre-releases to ASDF 3.
ASDF 3.1 refers to releases from 3.1.2 (May 6th 2014) onward.
These releases are also considered part of 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 ASDF 2 and ASDF 3?
@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.2 (May 2014),
though they count as ASDF 3, include enough progress that they
also 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.
Finally, for a code snippet that works on all versions including very old ones, @pxref{Checking whether ASDF is loaded}.

@node ASDF can portably name files in subdirectories, Output translations, How do I detect the ASDF version?, What has changed between ASDF 1 ASDF 2 and ASDF 3?
@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: