Many Lisp implementations include a copy of ASDF. You can
usually load this copy using Common-Lisp's require
function:
(require 'asdf)
Consult your Lisp implementation's documentation for details. If ASDF doesn't come bundled with your Lisp or if you want to make sure that you have the most recent version, then you'll want to download it from the asdf-home website.
Note to SBCL users: you are cautioned that installing ASDF yourself may break some SBCL contribs. We are working to provide instructions for doing this safely.
If you want to get the latest and greatest version of ASDF from its VCS repository, See Getting the latest version.
If your CL implementation does not provide ASDF through the
require
feature, then you need to download ASDF and load it
yourself.
The single file asdf.lisp is all you need to use asdf normally. Once you load it in a running Lisp, you're ready to use asdf. For maximum convenience you might want to have asdf loaded whenever you start your Lisp implementation, for example by loading it from the startup script or dumping a custom core – check your Lisp implementation's manual for details.
To compile and load a system, you need to ensure that its
system definition can be found in one of the directories in
*central-registry*
1.
There are two ways that you can make a system definition findable
through *central-registry*
. One is to simply insert into
*central-registry*
an entry that specifies the pathname of for
the directory containing the system definition file (a file whose name
is of the form *.asd
).
For example, if we had a
system foo that is stored in a directory
/home/me/src/foo/, containing /home/me/src/foo/, we could
make the foo system asdf-operable by doing (push
"/home/me/src/foo/" asdf:*central-registry*).
ASDF will also properly handle the case where the
*central-registry*
points to a directory containing a
symbolic link to the system definition file.
For example, if #p"/home/me/cl/systems/"
(note the trailing
slash) is a member of *central-registry*
, you could set up the
system foo for loading with asdf with the following
commands at the shell:
$ cd /home/me/cl/systems/ $ ln -s ~/src/foo/foo.asd .
Previous versions of the ASDF manual suggested that users create a
directory in their *central-registry*
that would act as a “link
farm.” However, this method may cause problems if you work on multiple
lisp projects that contain different mixes of ASDF libraries.
The variable asdf:*central-registry*
is a list of “system
directory designators”2. A system directory designator is a form which
will be evaluated whenever a system is to be found, and must evaluate
to a directory to look in. You might want to set or augment
*central-registry*
in your Lisp init file, for example:
(setf asdf:*central-registry* (list* '*default-pathname-defaults* #p"/home/me/cl/systems/" #p"/usr/share/common-lisp/systems/" asdf:*central-registry*))
The system foo is loaded (and compiled, if necessary) by evaluating the following form in your Lisp implementation:
(asdf:load-system 'foo)
(In older versions of ASDF, you may need to use (asdf:oos
'asdf:load-op 'foo)
, instead.)
Output from asdf and asdf extensions are supposed to be sent to the CL
stream *standard-output*
, and so rebinding that stream around
calls to asdf:operate
should redirect all output from asdf
operations.
ASDF provides three commands for the most common system
operations: load-system
, compile-system
or test-system
.
Because ASDF is an extensible system for defining
operations on components also provides a generic
function: operate
(which is usually abbreviated by
oos
). You'll use oos
whenever you want to do something
beyond compiling, loading and testing.
Reminder: before ASDF can operate on a system, however, it must be able to find and load that system's definition.
By default, ASDF will place the compiled files it creates in the same directory as the source files. This works for most simple use cases. However, if you use multiple Common Lisp implementations, or for some other reason need to place your compiled files elsewhere, you will want to enable ASDF-BINARY-LOCATIONS. See Controlling where ASDF saves compiled files.
To use ASDF:
require
or load
.
*central-registry*
.
operate
(or shorthand oos
)
to tell ASDF what you'd like to do to what systems.
For simple operations, you can use load-system
, compile-system
or test-system
instead.
That's all you need to know to use asdf to load systems written by others. The rest of this manual deals with writing system definitions for Lisp software you write yourself, including how to extend ASDF to define new operation and component types.
[1] It is possible to customize the
system definition file search. That's considered advanced use, and
covered later: search forward for
*system-definition-search-functions*
. See Defining systems with defsystem.
[2] When we say “directory” here, we mean “designator for a pathname with a supplied DIRECTORY component”.