Commit 0a7919e2 authored by mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f's avatar mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f
Browse files

asdf 3.1.0.94

parent c497a2f6
......@@ -81,12 +81,13 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@ifnottex
@node Top, Introduction, (dir), (dir)
@top asdf: another system definition facility
@top ASDF: Another System Definition Facility
@insertcopying
@menu
* Introduction::
* Quick start summary::
* Loading ASDF::
* Configuring ASDF::
* Using ASDF::
......@@ -98,52 +99,110 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
* Miscellaneous additional functionality::
* Getting the latest version::
* FAQ::
* TODO list::
* Inspiration::
* Ongoing Work::
* Bibliography::
* Concept Index::
* Function and Class Index::
* Variable Index::
* Variable Index:: @c @detailmenu
@c
@c @detailmenu
@c --- The Detailed Node Listing ---
@detailmenu
--- The Detailed Node Listing ---
@c Defining systems with defsystem
Loading ASDF
@c * The defsystem form::
@c * A more involved example::
@c * The defsystem grammar::
@c * Other code in .asd files::
* Loading a pre-installed ASDF::
* Checking whether ASDF is loaded::
* Upgrading ASDF::
* Loading an otherwise installed ASDF::
@c The object model of ASDF
Configuring ASDF
@c * Operations::
@c * Components::
@c * Functions::
* Configuring ASDF to find your systems::
* Configuring where ASDF stores object files::
@c Operations
Defining systems with defsystem
@c * Predefined operations of ASDF::
@c * Creating new operations::
* The defsystem form::
* A more involved example::
* The defsystem grammar::
* Other code in .asd files::
* The package-system extension::
@c Components
The object model of ASDF
@c * Common attributes of components::
@c * Pre-defined subclasses of component::
@c * Creating new component types::
* Operations::
* Components::
* Functions::
@c properties
Operations
@c * Pre-defined subclasses of component::
@c * Creating new component types::
* Predefined operations of ASDF::
* Creating new operations::
Components
* Common attributes of components::
* Pre-defined subclasses of component::
* Creating new component types::
@c @end detailmenu
properties
* Pre-defined subclasses of component::
* Creating new component types::
FAQ
* Where do I report a bug?::
* What has changed between ASDF 1 and ASDF 2?::
* Issues with installing the proper version of ASDF::
* Issues with configuring ASDF::
* Issues with using and extending ASDF to define systems::
* ASDF development FAQs::
``What has changed between ASDF 1 and ASDF 2?''
* What are ASDF 1 2 3?::
* ASDF can portably name files in subdirectories::
* Output translations::
* Source Registry Configuration::
* Usual operations are made easier to the user::
* Many bugs have been fixed::
* ASDF itself is versioned::
* ASDF can be upgraded::
* Decoupled release cycle::
* Pitfalls of the transition to ASDF 2::
Issues with installing the proper version of ASDF
* My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
* I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::
Issues with configuring ASDF
* How can I customize where fasl files are stored?::
* How can I wholly disable the compiler output cache?::
Issues with using and extending ASDF to define systems
* How can I cater for unit-testing in my system?::
* How can I cater for documentation generation in my system?::
* How can I maintain non-Lisp (e.g. C) source files?::
* I want to put my module's files at the top level. How do I do this?::
* How do I create a system definition where all the source files have a .cl extension?::
ASDF development FAQs
* How do run the tests interactively in a REPL?::
@end detailmenu
@end menu
@end ifnottex
@c -------------------
@node Introduction, Loading ASDF, Top, Top
@node Introduction, Quick start summary, Top, Top
@comment node-name, next, previous, up
@chapter Introduction
@cindex ASDF-related features
......@@ -179,11 +238,16 @@ in all actively maintained CL implementations that used to bundle ASDF 1,
plus some implementations that didn't use to,
and has been made to work with all actively used CL implementations and a few more.
@xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly.
Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly
(though we recommend instead upgrading your implementation or its ASDF module).
For this reason, we have stopped supporting ASDF 1 and ASDF 2.
If you are using ASDF 1 or ASDF 2 and are experiencing any kind of issues or limitations,
we recommend you upgrade to ASDF 3
--- and we explain how to do that. @xref{Loading ASDF}.
(In the context of compatibility requirements,
ASDF 2.27, released on Feb 1st 2013, and further 2.x releases up to 2.33,
count as pre-releases of ASDF 3, and define the :asdf3 feature;
still, please use the latest release).
Also note that ASDF is not to be confused with ASDF-Install.
ASDF-Install is not part of ASDF, but a separate piece of software.
......@@ -193,42 +257,100 @@ which works great and is being actively maintained.
If you want to download software from version control instead of tarballs,
so you may more easily modify it, we recommend clbuild.
@node Quick start summary, Loading ASDF, Introduction, Top
@chapter Quick start summary
@itemize
@item To load an ASDF system:
@itemize
@item
Load ASDF itself into your Lisp image, either through
@code{(require "asdf")} (if it's supplied by your lisp implementation)
or else through
@code{(load "/path/to/asdf.lisp")}. For more details, @ref{Loading ASDF}.
@item
Make sure ASDF can find system definitions
through proper source-registry configuration.
For more details, @xref{Configuring ASDF to find your systems}.
The simplest way is simply to put all your lisp code in subdirectories of
@file{~/.local/share/common-lisp/source/}.
Such code will automatically be found.
@item
Load a system with @code{(asdf:load-system :system)}. @xref{Using ASDF}.
@end itemize
@item To make your own ASDF system:
@itemize
@item
As above, load and configure ASDF.
@node Loading ASDF, Configuring ASDF, Introduction, Top
@item
Make a new directory for your system, @code{my-system/} in a location
where ASDF can find it (@pxref{Configuring ASDF to find your systems}).
@item
Create an ASDF system definition listing the dependencies of
your system, its components, and their interdependencies,
and put it in @file{my-system.asd}.
This file must have the same name as your system.
@xref{Defining systems with defsystem}.
@item
Use @code{(asdf:load-system :my-system)}
to make sure it's all working properly. @xref{Using ASDF}.
@end itemize
@end itemize
@c FIXME: (1) add a sample project that the user can cut and paste to
@c get started. (2) discuss the option of starting with Quicklisp.
@node Loading ASDF, Configuring ASDF, Quick start summary, Top
@comment node-name, next, previous, up
@chapter Loading ASDF
@vindex *central-registry*
@cindex link farm
@findex load-system
@findex require-system
@findex compile-system
@findex test-system
@cindex system directory designator
@findex operate
@findex oos
@c @menu
@c * Installing ASDF::
@c @end menu
@menu
* Loading a pre-installed ASDF::
* Checking whether ASDF is loaded::
* Upgrading ASDF::
* Loading an otherwise installed ASDF::
@end menu
@node Loading a pre-installed ASDF, Checking whether ASDF is loaded, Loading ASDF, Loading ASDF
@section Loading a pre-installed ASDF
Most recent Lisp implementations include a copy of ASDF 2, and soon ASDF 3.
You can usually load this copy using Common Lisp's @code{require} function:
Most recent Lisp implementations include a copy of ASDF 3,
or at least ASDF 2.
You can usually load this copy using Common Lisp's @code{require} function.@footnote{
NB: all implementations except GNU CLISP also accept
@code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}.
For portability's sake, you should use @code{(require "asdf")}.
}
@lisp
(require "asdf")
@end lisp
As of the writing of this manual,
the following implementations provide ASDF 2 this way:
abcl allegro ccl clisp cmucl ecl lispworks mkcl sbcl xcl.
The following implementation doesn't provide it yet but will in an upcoming release:
scl.
the following implementations provide ASDF 3 this way:
ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, mkcl, SBCL.
The following implementations only provide ASDF 2:
LispWorks, mocl, XCL.
The following implementation doesn't provide ASDF yet but will in an upcoming release:
SCL.
The following implementations are obsolete, not actively maintained,
and most probably will never bundle it:
cormanlisp gcl genera mcl.
and most probably will never bundle ASDF:
Corman CL, GCL, Genera, MCL.
If the implementation you are using doesn't provide ASDF 2 or ASDF 3,
see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
......@@ -236,11 +358,7 @@ If that implementation is still actively maintained,
you may also send a bug report to your Lisp vendor and complain
about their failing to provide ASDF.
NB: all implementations except clisp also accept
@code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}.
For portability's sake, you probably want to use @code{(require "asdf")}.
@node Checking whether ASDF is loaded, Upgrading ASDF, Loading a pre-installed ASDF, Loading ASDF
@section Checking whether ASDF is loaded
To check whether ASDF is properly loaded in your current Lisp image,
......@@ -284,77 +402,85 @@ please try upgrading to the latest released version,
using the method below,
before you contact us and raise an issue.
@node Upgrading ASDF, Loading an otherwise installed ASDF, Checking whether ASDF is loaded, Loading ASDF
@section Upgrading ASDF
@c FIXME: tighten this up a bit -- there's a lot of stuff here that
@c doesn't matter to almost anyone. Move discussion of updating antique
@c versions of ASDF down, or encapsulate it.
If you want to upgrade to a more recent ASDF version,
you need to install and configure your ASDF just like any other system
(@pxref{Configuring ASDF to find your systems}).
If your implementation provides ASDF 3 or later,
you only need to @code{(require "asdf")}:
ASDF will automatically look whether an updated version of itself is available
amongst the regularly configured systems, before it compiles anything else.
See @pxref{Configuring ASDF} below.
If your implementation does provide ASDF 2 or later,
but not ASDF 3 or later,
and you want to upgrade to a more recent version,
you need to install and configure your ASDF as above,
and additionally, you need to explicitly tell ASDF to load itself,
right after you require your implementation's old ASDF 2:
@subsection Notes about ASDF 1 and ASDF 2
Most implementations provide ASDF 3 in their latest release,
and we recommend upgrading your implementation rather than using ASDF 1 or 2.
A few implementations only provide ASDF 2,
that can be overridden by installing a fasl (see below).
A few implementations don't provide ASDF,
but a fasl can be installed to provide it.
GCL so far is still lacking a usable @code{require} interface.
If your implementation has no suitable upgrade available (yet),
or somehow upgrading is not an option,
we assume you're an expert deliberately using a legacy implementation,
and are proficient enough to install this fasl.
Still, the ASDF source repository contains a script
@file{bin/install-asdf-as-module} that can help you do that.
It relies on cl-launch 4 for command-line invocation,
which may depend on ASDF being checked out in @file{~/cl/asdf/}
if your implementation doesn't even have an ASDF 2;
but you can run the code it manually if needs be.
Finally, if your implementation only provides ASDF 2,
and you can't or won't upgrade it or override its ASDF module,
you may simply configure ASDF to find a proper upgrade;
however, to avoid issues with a self-upgrade in mid-build,
you @emph{must} make sure to upgrade ASDF immediately
after requiring the builtin ASDF 2:
@lisp
(require "asdf")
;; <--- insert programmatic configuration here if needed
(asdf:load-system :asdf)
@end lisp
If on the other hand, your implementation only provides an old ASDF,
you will require a special configuration step and an old-style loading.
Take special attention to not omit the trailing directory separator
@code{/} at the end of your pathname:
@lisp
(require "asdf")
(push #p"@var{/path/to/new/asdf/}" asdf:*central-registry*)
(asdf:oos 'asdf:load-op :asdf)
@end lisp
Note that ASDF 1 won't redirect its output files,
or at least won't do it according to your usual ASDF 2 configuration.
You therefore need write access on the directory
where you install the new ASDF,
and make sure you're not using it
for multiple mutually incompatible implementations.
At worst, you may have to have multiple copies of the new ASDF,
e.g. one per implementation installation, to avoid clashes.
Note that to our knowledge all implementations that provide ASDF
provide ASDF 2 in their latest release, so
you may want to upgrade your implementation rather than go through that hoop.
Finally, if you are using an unmaintained implementation
that does not provide ASDF at all,
see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
@subsection Issues with upgrading ASDF
Note that there are some limitations to upgrading ASDF:
@itemize
@item
Previously loaded ASDF extension becomes invalid, and will need to be reloaded.
This applies to e.g. CFFI-Grovel, or to hacks used by ironclad, etc.
Since it isn't possible to automatically detect what extensions are present
that need to be invalidated,
ASDF will actually invalidate all previously loaded systems
when it is loaded on top of a different ASDF version,
starting with ASDF 2.014.8 (as far as releases go, 2.015);
and it will automatically attempt this self-upgrade as its very first step
starting with ASDF 3.
Previously loaded ASDF extensions become invalid, and will need to be reloaded.
Examples include CFFI-Grovel, hacks used by ironclad, etc.
Since it isn't possible to automatically detect what extensions
need to be invalidated,
ASDF will invalidate @emph{all} previously loaded systems
when it is loaded on top of a forward-incompatible ASDF version.
@footnote{
@vindex *oldest-forward-compatible-asdf-version*
Forward incompatibility can be determined using the variable
@code{asdf/upgrade::*oldest-forward-compatible-asdf-version*},
which is 2.33 at the time of this writing.}
Starting with ASDF 3 (2.27 or later),
this self-upgrade will be automatically attempted as the first step
to any system operation, to avoid any possibility of
a catastrophic attempt to self-upgrade in mid-build.
@c FIXME: Fix grammar below.
@item
For this an many other reasons,
it important reason to load, configure and upgrade ASDF (if needed)
For this and many other reasons,
you should load, configure and upgrade ASDF
as one of the very first things done by your build and startup scripts.
Until all implementations provide ASDF 3 or later,
it is safer if you upgrade ASDF and its extensions as a special step
It is safer if you upgrade ASDF and its extensions as a special step
at the very beginning of whatever script you are running,
before you start using ASDF to load anything else;
even afterwards, it is still a good idea, to avoid having to
load and reload code twice as it gets invalidated.
before you start using ASDF to load anything else.
@item
Until all implementations provide ASDF 3 or later,
......@@ -364,7 +490,7 @@ since the new one might shadow the old one while the old one is running,
and the running old one will be confused
when extensions are loaded into the new one.
In the meantime, we recommend that your systems should @emph{not} specify
@code{:depends-on (:asdf)}, or @code{:depends-on ((:version :asdf "2.010"))},
@code{:depends-on (:asdf)}, or @code{:depends-on ((:version :asdf "3.0.1"))},
but instead that they check that a recent enough ASDF is installed,
with such code as:
@example
......@@ -381,7 +507,7 @@ system-depends-on asdf, or transitively does,
you should also do as well.
@end itemize
@node Loading an otherwise installed ASDF, , Upgrading ASDF, Loading ASDF
@section Loading an otherwise installed ASDF
If your implementation doesn't include ASDF,
......@@ -410,35 +536,68 @@ for example by loading it from the startup script or dumping a custom core
@node Configuring ASDF, Using ASDF, Loading ASDF, Top
@comment node-name, next, previous, up
@chapter Configuring ASDF
For standard use cases, ASDF should work pretty much out of the box.
We recommend you skim the sections on configuring ASDF to find your systems
and choose the method of installing Lisp software that works best for you.
Then skip directly to @xref{Using ASDF}. That will probably be enough.
You are unlikely to have to worry about the way ASDF stores object files,
and resetting the ASDF configuration is usually only needed in corner cases.
@menu
* Configuring ASDF to find your systems::
* Configuring ASDF to find your systems --- old style::
* Configuring where ASDF stores object files::
* Resetting the ASDF configuration::
@end menu
@node Configuring ASDF to find your systems, Configuring where ASDF stores object files, Configuring ASDF, Configuring ASDF
@section Configuring ASDF to find your systems
So it may compile and load your systems, ASDF must be configured to find
In order to compile and load your systems, ASDF must be configured to find
the @file{.asd} files that contain system definitions.
Since ASDF 2, the preferred way to configure where ASDF finds your systems is
the @code{source-registry} facility,
fully described in its own chapter of this manual.
@xref{Controlling where ASDF searches for systems}.
There are a number of different techniques for setting yourself up with
ASDF, starting from easiest to the most complex:
@itemize @bullet
The default location for a user to install Common Lisp software is under
@item
Put all of your systems in subdirectories of
@file{~/.local/share/common-lisp/source/}.
If you install software there (it can be a symlink),
you don't need further configuration.
If you're installing software yourself at a location that isn't standard,
you have to tell ASDF where you installed it. See below.
@item
If you're using some tool to install software (e.g. Quicklisp),
the authors of that tool should already have configured ASDF.
@item
If you have more specific desires about how to lay out your software on
disk, the preferred way to configure where ASDF finds your systems is
the @code{source-registry} facility,
fully described in its own chapter of this manual.
@xref{Controlling where ASDF searches for systems}. Here is a quick
recipe for getting started:
The simplest way to add a path to your search path,
say @file{/home/luser/.asd-link-farm/}
is to create the directory
@file{~/.config/common-lisp/source-registry.conf.d/}
and there create a file with any name of your choice,
and with the type @file{conf},
for instance @file{42-asd-link-farm.conf}
and with the type @file{conf}@footnote{By requiring the @file{.conf}
extension, and ignoring other files, ASDF allows you to have disabled files,
editor backups, etc. in the same directory with your active
configuration files.
ASDF will also ignore files whose names start with a @file{.} character.
It is customary to start the filename with two digits, to control the
sorting of the @code{conf} files in the source registry directory, and
thus the order in which the directories will be scanned.},
for instance @file{42-asd-link-farm.conf},
containing the line:
@kbd{(:directory "/home/luser/.asd-link-farm/")}
......@@ -448,32 +607,43 @@ to be recursively scanned for @file{.asd} files, instead use:
@kbd{(:tree "/home/luser/lisp/")}
Note that your Operating System distribution or your system administrator
may already have configured system-managed libraries for you.
The required @file{.conf} extension allows you to have disabled files
or editor backups (ending in @file{~}), and works portably
(for instance, it is a pain to allow both empty and non-empty extension on CLISP).
Excluded are files the name of which start with a @file{.} character.
It is customary to start the filename with two digits
that specify the order in which the directories will be scanned.
ASDF will automatically read your configuration
the first time you try to find a system.
You can reset the source-registry configuration with:
If necessary, you can reset the source-registry configuration with:
@lisp
(asdf:clear-source-registry)
@end lisp
And you probably should do so before you dump your Lisp image,
if the configuration may change
between the machine where you save it at the time you save it
and the machine you resume it at the time you resume it.
Actually, you should use @code{(asdf:clear-configuration)}
before you dump your Lisp image, which includes the above.
@c FIXME: too specific. Push this down to discussion of dumping an
@c image?
@c And you probably should do so before you dump your Lisp image,
@c if the configuration may change
@c between the machine where you save it at the time you save it
@c and the machine you resume it at the time you resume it.
@c Actually, you should use @code{(asdf:clear-configuration)}
@c before you dump your Lisp image, which includes the above.
@item
In earlier versions of ASDF, the system source registry was configured
using a global variable, @code{asdf:*central-registry*}.
For more details about this, see the following section,
@ref{Configuring ASDF to find your systems --- old style}.
Unless you need to understand this,
skip directly to @ref{Configuring where ASDF stores object files}.
@end itemize
Note that your Operating System distribution or your system administrator
may already have configured system-managed libraries for you.
@node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Configuring ASDF
@c FIXME: this section should be moved elsewhere. The novice user
@c should not be burdened with it. [2014/02/27:rpg]
@section Configuring ASDF to find your systems --- old style
The old way to configure ASDF to find your systems is by
......@@ -489,65 +659,67 @@ your Common Lisp software system.
The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
but is still supported for compatibility with ASDF 1.
When used, it takes precedence over the above source-registry@footnote{
When used, it takes precedence over the above source-registry.@footnote{
It is possible to further customize
the system definition file search.
That's considered advanced use, and covered later:
search forward for
@code{*system-definition-search-functions*}.
@xref{Defining systems with defsystem}.}.
@xref{Defining systems with defsystem}.}
For instance, if you wanted ASDF to find the @file{.asd} file
@file{/home/me/src/foo/foo.asd} your initialization script
could after it loads ASDF with @code{(require "asdf")}
configure it with:
For example, let's say you want ASDF to find the @file{.asd} file
@file{/home/me/src/foo/foo.asd}.
In your lisp initialization file, you could have the following:
@lisp
(require "asdf")
(push "/home/me/src/foo/" asdf:*central-registry*)
@end lisp
Note the trailing slash: when searching for a system,
ASDF will evaluate each entry of the central registry
and coerce the result to a pathname@footnote{
and coerce the result to a pathname.@footnote{
ASDF will indeed call @code{eval} on each entry.
It will also skip entries that evaluate to @code{nil}.
It will skip entries that evaluate to @code{nil}.
Strings and pathname objects are self-evaluating,
in which case the @code{eval} step does nothing;
but you may push arbitrary SEXP onto the central registry,
that will be evaluated to compute e.g. things that depend
but you may push arbitrary s-expressions onto the central registry.
These s-expressions may be evaluated to compute context-dependent
entries, e.g. things that depend
on the value of shell variables or the identity of the user.
The variable @code{asdf:*central-registry*} is thus a list of
``system directory designators''.
A @dfn{system directory designator} is a form
which will be evaluated whenever a system is to be found,
and must evaluate to a directory to look in.
By ``directory'' here, we mean
``designator for a pathname with a supplied DIRECTORY component''.
and must evaluate to a directory to look in (or @code{NIL}).
By ``directory'', we mean
``designator for a pathname with a non-empty DIRECTORY component''.
}
at which point the presence of the trailing directory name separator
The trailing directory name separator
is necessary to tell Lisp that you're discussing a directory
rather than a file.
rather than a file. If you leave it out, ASDF is likely to look in
@code{/home/me/src/} instead of @code{/home/me/src/foo/} as you