asdf
ASDF (Another System Definition Facility) is an extensible build facility for Common Lisp software. ASDF comes bundled with all recent releases of active Common Lisp implementations as well as with quicklisp, and it is the most widely used system definition facility for Free Software Lisp libraries.

Documentation on how to use ASDF can be found on its home page on common-lisp.net. For more details, see the online ASDF Manual.

The current version of ASDF is ASDF 3. ASDF 3 actually contains two systems: the runtime support layer UIOP (formerly known as ASDF/DRIVER or ASDF-UTILS), and the defsystem itself ASDF/DEFSYSTEM.

On all actively developed implementations, you can (require "asdf") and the implementation will provide ASDF 2 or ASDF 3. ASDF is thus provided by ABCL, Allegro, CCL, CLISP, CMUCL, ECL, LispWorks, MOCL, SBCL; it is also provided by the in-progress MKCL and the now inactive XCL. The only actively maintained implementation that does not yet provide ASDF is SCL. ASDF also works on the dead or mostly dead implementations CormanLisp, GCL, Genera and RMCL, that may never see another release on which to provide ASDF.

ASDF will not automatically download software. For that, use Quicklisp. Do NOT use asdf-install anymore, for it is both obsolete and unmaintained.

To download the latest ASDF release:

  • Get just the source to asdf.lisp
  • The full release tarball
  • Or use git clone http://common-lisp.net/project/asdf/asdf.git to check out the repository.
  • There is also a Debian package.

ASDF is extensible, and various useful extensions are listed on the ASDF webpage, including asdf-encodings, poiu, asdf-package-system, asdf-system-connections, asdf-flv.

History

ASDF 1 was created by Dan Barlow in 2002. It can be considered a notional successor to mk-defsystem, of which it retains the concept of a declarative hierarchy of components that you operate upon. Dan Barlow introduced such great innovations as generic functions that specialize on both operation and component, and automatic pathname configuration via a registry of .asd files and locating source files based on its *LOAD-TRUENAME*. ASDF 1 was later maintained by Christophe Rhodes, then by Gary King.

ASDF 2 was a rewrite by Francois-Rene Rideau with the help of Robert Goldman, from November 2009 to November 2012. It can be seen as a portable productization of the previous ASDF 1. ASDF 1 was mainly developed on SBCL, and its behavior varied widely across Lisp implementations, notably with regards to how pathname were resolved; it otherwise had many bugs, and was lacking in extensibility; but more importantly, it had a tight coupling between what each implementation was providing and what library implementers and users could rely on, making progress almost impossible. See Faré's 2009 post about this phenomenon. ASDF 2 made pathname specification portable across all Lisp implementations, featured countless bug fixes, added extension points where users previously overrode ASDF, offered configuration languages suitable for implementation-independent deployment, an output-translation facility allowing multi-implementation development, and most importantly the hot-upgradability that decoupled what versions implementations provide from what users can use. See Faré and Robert Goldman's ILC 2010 article Evolving ASDF: More Cooperation, Less Coordination. ASDF 2 later introduced defsystem-depends-on and weakly-depends-on dependencies, per-system force and force-not, file encoding support, around-compile and compile-check hooks, bundle output support (initially from ECL), and support for all of 15 different implementations and 4 different operating system families.

ASDF 3 includes a complete rewrite of ASDF 2's defsystem, now its own system ASDF/DEFSYSTEM, that actually takes into account timestamp propagation and cross-system dependencies. To that effect, it fixes some deep conceptual bugs in the ASDF dependency model, so it now faithfully and consistently represents the dependencies between components. As a result, ASDF's defsystem is both simpler and more powerful, its TRAVERSE algorithm is more robust and more versatile. New features include better checking of deferred warnings on SBCL and CCL, bundle support on all active implementations, creating standalone executables with program-op on supported implementations, better support for logical pathnames or for physical pathnames without symlink resolution. ASDF 3 also formalizes and expands the runtime portability layer of ASDF 2 into its own system UIOP, also including image dumping support initially from cl-launch and a portable run-program implementation initially from xcvb-driver, as well as a DEFINE-PACKAGE that supports hot upgrade, and many utilities. See ASDF 3 tutorial at ELS 2013

Frequently Asked Question

Where to find a Short introduction?

Slightly outdated but still working, see this old howto.

Is there a per-System compilation unit?

Back in 2004, someone voiced the desire for a WITH-COMPILATION-UNIT around a system's compilation. ASDF 3 grants that wish in 2013 for SBCL and CCL and many other implementations, with its deferred-warnings support. But it's disabled by default for backward compatibility.

Enable it with:

(asdf:enable-deferred-warnings-check)

For all other systems, there is a WITH-COMPILATION-UNIT around the entire build.

How do I customize where ASDF outputs its files?

Starting with ASDF 2 (2010), use ASDF's output-translations. See the manual.

How do I query what files need to be recompiled?

With ASDF 3, you can

(asdf:required-components system :force nil :force-not nil :keep-component 'asdf:cl-source-file :keep-operation 'asdf:compile-op)

Is there IDE integration?

Slime adds Emacs-based support for ASDF system compilation and loading, with slime-load-system

With a recent SLIME, you may add this in your ~/.swank.lisp:

(in-package :swank) (pushnew 'try-compile-file-with-asdf *compile-file-for-emacs-hook*)

Is there a shortcut for (asdf:operate 'asdf:load-op :foo) ?

Since 2009, there is (asdf:load-system :foo).

See also (asdf:require-system :foo) which won't re-load already loaded systems, and is hooked into your implementation's CL:REQUIRE on ABCL, CCL, CLISP, CMUCL, ECL, MKCL, SBCL.

Where can I find a list of software that is packaged for use with ASDF?

See quicklisp.

In what package are .asd files loaded?

They are loaded in package ASDF-USER, which starting with ASDF 3.1, uses UIOP/COMMON-LISP, all of UIOP, and ASDF.

In previous variants of ASDF 3, ASDF-USER was only using UIOP/COMMON-LISP, UIOP/PACKAGE, and ASDF.

In ASDF 1 and after it ASDF 2, .asd files were instead loaded in temporary package ASDF~D created anew for each file, then deleted afterwards, that was using just COMMON-LISP and ASDF.

Some people like to define special-purpose ASDF extensions in their .asd files, in which case it is good practice to define your own package first. These days, it is considered better style to instead only use nicely done general-purpose ASDF extensions, and to have your system :defsystem-depends-on it.