Next: , Previous: Introduction, Up: Top


2 Using ASDF

2.1 Installing ASDF

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.

2.2 Loading ASDF

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.

2.3 Setting up a system to be loaded

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*))

2.4 Loading a system

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.

2.5 Placement of compiled files

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.

2.6 Summary

To use ASDF:

2.7 Moving on

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.


Footnotes

[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”.