Newer
Older
@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.
Robert P. Goldman
committed
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:
Francois-Rene Rideau
committed
@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)
Francois-Rene Rideau
committed
;; 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) |
Francois-Rene Rideau
committed
;; 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)
Francois-Rene Rideau
committed
;; 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
Francois-Rene Rideau
committed
T | ;; as source matches anything, as destination leaves pathname unmapped.
ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
When the second designator starts with @code{:root},
the mapping preserves the host and device of the original pathname.
Francois-Rene Rideau
committed
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
Francois-Rene Rideau
committed
Starting with ASDF 2.011.4, you can use the simpler:
@code{`(:root (:root :**/ :implementation :*.*.*))}
Francois-Rene Rideau
committed
@code{:include} statements cause the search to recurse with the path specifications
from the file specified.
Francois-Rene Rideau
committed
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
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
@code{:enable-user-cache} is the same as @code{(t :user-cache)}.
Francois-Rene Rideau
committed
@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
Francois-Rene Rideau
committed
@code{("/var/cache/common-lisp" :uid :implementation-type)}
(on Unix and cygwin), or something semi-sensible on Windows.
Robert P. Goldman
committed
@end itemize
Robert P. Goldman
committed
@section Configuration Directories
Configuration directories consist in files each contains
a list of directives without any enclosing
Francois-Rene Rideau
committed
@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{(}
Francois-Rene Rideau
committed
and it will be interpreted as a list of directories.
Directories should come by pairs, indicating a mapping directive.
Francois-Rene Rideau
committed
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:
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
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).
@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.
Francois-Rene Rideau
committed
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).
Francois-Rene Rideau
committed
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},
Francois-Rene Rideau
committed
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.
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
Francois-Rene Rideau
committed
@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}.
Robert P. Goldman
committed
@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
Robert P. Goldman
committed
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
@cindex :around-compile
@cindex around-compile keyword
@cindex compile-check keyword
@cindex :compile-check
@findex compile-file*
When declaring a component (system, module, file),
Francois-Rene Rideau
committed
you can specify a keyword argument @code{:around-compile function}.
If left unspecified (and therefore unbound),
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
The argument must be a either @code{nil}, a fbound symbol,
Francois-Rene Rideau
committed
a lambda-expression (e.g. @code{(lambda (thunk) ...(funcall thunk ...) ...)})
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
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*}.
Francois-Rene Rideau
committed
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
Francois-Rene Rideau
committed
a function, symbol and/or package
Francois-Rene Rideau
committed
that will only be created later during the build, but
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
Note that there is no around-load hook. This is on purpose.
Some implementations such as ECL, GCL or MKCL link object files,
Francois-Rene Rideau
committed
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
Francois-Rene Rideau
committed
is guaranteed to be read the same on all implementations
independently from any user setting.
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
On implementations that do not support unicode,
the feature @code{:asdf-unicode} is absent, and
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
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.
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.
Francois-Rene Rideau
committed
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}.
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
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
Francois-Rene Rideau
committed
the @code{:encoding :default} option in your @code{defsystem} form
to restore the behavior of ASDF 2.20 and earlier.
Francois-Rene Rideau
committed
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.
Francois-Rene Rideau
committed
These functions are exported by ASDF for your convenience.
@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.
Francois-Rene Rideau
committed
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}.
Francois-Rene Rideau
committed
It returns a pathname built from the location of the system's
source directory and the relative pathname. For example:
@lisp
Francois-Rene Rideau
committed
> (asdf:system-relative-pathname 'cl-ppcre "regex.data")
#P"/repository/other/cl-ppcre/regex.data"
@end lisp
Robert P. Goldman
committed
@end defun
Robert P. Goldman
committed
@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.
Robert P. Goldman
committed
@end defun
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
@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 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{fasl-op} or @code{monolithic-fasl-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
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
@defun run-shell-command control-string @Arest args
This function is obsolete and present only for the sake of backwards-compatibility:
``If it's not backwards, it's not compatible''. We @emph{strongly} discourage its use.
Its current behavior is only well-defined on Unix platforms
(which include MacOS X and cygwin). On Windows, anything goes.
The following documentation is only for the purpose of your migrating away from it
in a way that preserves semantics.
Instead we recommend the use @code{run-program}, described in the next section, and
available as part of ASDF since ASDF 3.
@code{run-shell-command} takes as arguments a format @code{control-string}
and arguments to be passed to @code{format} after this control-string
to produce a string.
This string is a command that will be evaluated with a POSIX shell if possible;
yet, on Windows, some implementations will use CMD.EXE,
while others (like SBCL) will make an attempt at invoking a POSIX shell
(and fail if it is not present).
@end defun
@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 such non-Unix systems it is only usable but for relative pathnames;
but especially to manipulate relative pathnames portably, it is of 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}.
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
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}.
@code{host}, @code{device} and @code{version} components are taken from @var{defaults},
which itself defaults to @code{*nil-pathname*}, also used if @var{defaults} is @code{nil}.
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}
to throw an error if the pathname is absolute
@end defun
@defun merge-pathnames* specified @Aoptional defaults
This function is a replacement for @code{merge-pathnames} that uses the host and device
from the @var{defaults} rather than the @var{specified} pathname when the latter
is a relative pathname. This allows ASDF and its users to create and use relative pathnames
without having to know beforehand what are the host and device
of the absolute pathnames they are relative to.
@end defun
@defun subpathname pathname subpath @Akey type
This function takes a @var{pathname} and a @var{subpath} and a @var{type}.
If @var{subpath} is already a @code{pathname} object (not namestring),
and is an absolute pathname at that, it is returned unchanged;
otherwise, @var{subpath} is turned into a relative pathname with given @var{type}
as per @code{parse-unix-namestring} with @code{:want-relative t :type }@var{type},
then it is merged with the @code{pathname-directory-pathname} of @var{pathname},
as per @code{merge-pathnames*}.
We strongly encourage the use of this function
for portably resolving relative pathnames in your code base.
@end defun
@defun subpathname* pathname subpath @Akey type
This function returns @code{nil} if the base @var{pathname} is @code{nil},
otherwise acts like @code{subpathname}.
@end defun
@defun run-program command @Akey ignore-error-status force-shell input output error-output
if-input-does-not-exist if-output-exists if-error-output-exists
element-type external-format @AallowOtherKeys
@code{run-program} takes a @var{command} argument that is either
a list of a program name or path and its arguments,
or a string to be executed by a shell.
It spawns the command, waits for it to return,
verifies that it exited cleanly (unless told not too below),
and optionally captures and processes its output.
It accepts many keyword arguments to configure its behavior.
@code{run-program} returns three values: the first for the output,
the second for the error-output, and the third for the return value.
(Beware that before ASDF 3.0.2.11, it didn't handle input or error-output,
and returned only one value,
the one for the output if any handler was specified, or else the exit code;
please upgrade ASDF, or at least UIOP, to rely on the new enhanced behavior.)
@var{output} is its most important argument;
it specifies how the output is captured and processed.
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
If it is @code{nil}, then the output is redirected to the null device,
that will discard it.
If it is @code{:interactive}, then it is inherited from the current process
(beware: this may be different from your @var{*standard-output*},
and under SLIME will be on your @code{*inferior-lisp*} buffer).
If it is @code{t}, output goes to your current @var{*standard-output*} stream.
Otherwise, @var{output} should be a value that is a suitable first argument to
@code{slurp-input-stream} (see below), or
a list of such a value and keyword arguments.
In this case, @code{run-program} will
create a temporary stream for the program output;
the program output, in that stream,
will be processed by a call to @code{slurp-input-stream},
using @var{output} as the first argument
(or if it's a list the first element of @var{output} and the rest as keywords).
The primary value resulting from that call
(or @code{nil} if no call was needed)
will be the first value returned by @code{run-program}.
E.g., using @code{:output :string}
will have it return the entire output stream as a string.
And using @code{:output '(:string :stripped t)}
will have it return the same string stripped of any ending newline.
@var{error-output} is similar to @var{output}, except that
the resulting value is returned as the second value of @code{run-program}.
@code{t} designates the @var{*error-output*}.
Also @code{:output} means redirecting the error output to the output stream,
in which case @code{nil} is returned.
@var{input} is similar to @var{output}, except that
@code{vomit-output-stream} is used, no value is returned,
and @code{t} designates the @var{*standard-input*}.
@code{element-type} and @code{external-format} are passed on
to your Lisp implementation, when applicable, for creation of the output stream.
One and only one of the stream slurping or vomiting may or may not happen
in parallel in parallel with the subprocess,
depending on options and implementation,
and with priority being given to output processing.
Other streams are completely produced or consumed
before or after the subprocess is spawned, using temporary files.
@code{force-shell} forces evaluation of the command through a shell,
even if it was passed as a list rather than a string.
If a shell is used, it is @file{/bin/sh} on Unix or @file{CMD.EXE} on Windows,
except on implementations that (erroneously, IMNSHO)
insist on consulting @code{$SHELL} like clisp.
@code{ignore-error-status} causes @code{run-program}
to not raise an error if the spawned program exits in error.
Following POSIX convention, an error is anything but
a normal exit with status code zero.
By default, an error of type @code{subprocess-error} is raised in this case.
@code{run-program} works on all platforms supported by ASDF, except Genera.
See the source code for more documentation.
@end defun
@defun slurp-input-stream processor input-stream @Akey
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 @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}.
If the object is @code{'string} or @code{:string}, the content is captured into a string.
Accepted keywords include the @var{element-type} and a flag @var{stripped},
which when true causes any single line ending to be removed as per @code{uiop:stripln}.
If the object is @code{:lines}, the content is captured as a list of strings,
one per line, without line ending. If the @var{count} keyword argument is provided,
it is a maximum count of lines to be read.
If the object is @code{:line}, the content is capture as with @code{:lines} above,
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}.
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}.
If the object is @code{:form}, the content is capture as with @code{:forms} above,
and then its sub-object is extracted with the @var{at} argument,
which defaults to @code{0}, extracting the first form.
A number will extract the corresponding form.
See the documentation for @code{uiop:access-at}.
We recommend you control the syntax with such macro as
@code{uiop:with-safe-io-syntax}.
@end 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
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.