ASDF bugs are tracked on launchpad: https://launchpad.net/asdf.
If you're unsure about whether something is a bug, or for general discussion, use the asdf-devel mailing list
ASDF 1 refers to any release earlier than 1.369 or so (from August 2001 to October 2009), and to any development revision earlier than 2.000 (May 2010). If your copy of ASDF doesn't even contain version information, it's an old ASDF 1. Revisions between 1.656 and 1.728 may count as development releases for ASDF 2.
ASDF 2 refers to releases from 2.000 (May 31st 2010) to 2.26 (Oct 30 2012), and any development revision newer than ASDF 1 and older than 2.27 (Feb 1 2013).
ASDF 3 refers to releases from 2.27 (Feb 1 2013) to 2.33 and 3.0.0 onward (May 15 2013). 2.27 to 2.33 count as pre-releases to ASDF 3.
All releases of ASDF
Releases starting with ASDF 2
Releases starting with ASDF 3 (including 2.27 and later pre-releases)
Furthermore, releases starting with ASDF 3.1 (March 2014),
though they count as ASDF 3, includes enough progress that they
You may depend on the presence or absence of these features
to write code that takes advantage of recent ASDF functionality
but still works on older versions, or at least detects the old version and signals an error.
Additionally, all releases starting with ASDF 2
define a function
(asdf:asdf-version) you may use to query the version.
All releases starting with 2.013 display the version number prominently
on the second line of the asdf.lisp source file.
If you are experiencing problems or limitations of any sort with ASDF 1 or ASDF 2, we recommend that you should upgrade to the latest release, be it ASDF 3 or other.
Common Lisp namestrings are not portable, except maybe for logical pathnamestrings, that themselves have various limitations and require a lot of setup that is itself ultimately non-portable.
In ASDF 1, the only portable ways to refer to pathnames inside systems and components
were very awkward, using
#.(make-pathname ...) and
Even the above were themselves were inadequate in the general case
due to host and device issues, unless horribly complex patterns were used.
Plenty of simple cases that looked portable actually weren't,
leading to much confusion and greavance.
ASDF 2 implements its own portable syntax for strings as pathname specifiers.
Naming files within a system definition becomes easy and portable again.
On the other hand, there are places where systems used to accept namestrings
where you must now use an explicit pathname object:
(defsystem ... :pathname "LOGICAL-HOST:PATH;TO;SYSTEM;" ...)
must now be written with the
(defsystem ... :pathname #p"LOGICAL-HOST:PATH;TO;SYSTEM;" ...)
See Pathname specifiers.
A popular feature added to ASDF was output pathname translation:
cl-launch and other hacks were all implementing it in ways
both mutually incompatible and difficult to configure.
Output pathname translation is essential to share source directories of portable systems across multiple implementations or variants thereof, or source directories of shared installations of systems across multiple users, or combinations of the above.
In ASDF 2, a standard mechanism is provided for that,
with sensible defaults, adequate configuration languages,
a coherent set of configuration files and hooks,
and support for non-Unix platforms.
See Controlling where ASDF saves compiled files.
Configuring ASDF used to require special magic to be applied just at the right moment, between the moment ASDF is loaded and the moment it is used, in a way that is specific to the user, the implementation he is using and the application he is building.
This made for awkward configuration files and startup scripts that could not be shared between users, managed by administrators or packaged by distributions.
ASDF 2 provides a well-documented way to configure ASDF, with sensible defaults, adequate configuration languages, and a coherent set of configuration files and hooks.
We believe it's a vast improvement because it decouples application distribution from library distribution. The application writer can avoid thinking where the libraries are, and the library distributor (dpkg, clbuild, advanced user, etc.) can configure them once and for every application. Yet settings can be easily overridden where needed, so whoever needs control has exactly as much as required.
At the same time, ASDF 2 remains compatible
with the old magic you may have in your build scripts
to tailor the ASDF configuration to your build automation needs,
and also allows for new magic, simpler and more powerful magic.
See Controlling where ASDF searches for systems.
In ASDF 1, you had to use the awkward syntax
(asdf:oos 'asdf:load-op :foo)
to load a system,
and similarly for
In ASDF 2, you can use shortcuts for the usual operations:
(asdf:load-system :foo), and
The following issues and many others have been fixed:
Between new features, old bugs fixed, and new bugs introduced, there were various releases of ASDF in the wild, and no simple way to check which release had which feature set. People using or writing systems had to either make worst-case assumptions as to what features were available and worked, or take great pains to have the correct version of ASDF installed.
With ASDF 2, we provide a new stable set of working features
that everyone can rely on from now on.
#+asdf2 to detect presence of ASDF 2,
(asdf:version-satisfies (asdf:asdf-version) "2.345.67")
to check the availability of a version no earlier than required.
When an old version of ASDF was loaded, it was very hard to upgrade ASDF in your current image without breaking everything. Instead you had to exit the Lisp process and somehow arrange to start a new one from a simpler image. Something that can't be done from within Lisp, making automation of it difficult, which compounded with difficulty in configuration, made the task quite hard. Yet as we saw before, the task would have been required to not have to live with the worst case or non-portable subset of ASDF features.
With ASDF 2, it is easy to upgrade from ASDF 2 to later versions from within Lisp, and not too hard to upgrade from ASDF 1 to ASDF 2 from within Lisp. We support hot upgrade of ASDF and any breakage is a bug that we will do our best to fix. There are still limitations on upgrade, though, most notably the fact that after you upgrade ASDF, you must also reload or upgrade all ASDF extensions.
When vendors were releasing their Lisp implementations with ASDF, they had to basically never change version because neither upgrade nor downgrade was possible without breaking something for someone, and no obvious upgrade path was visible and recommendable.
With ASDF 2, upgrade is possible, easy and can be recommended. This means that vendors can safely ship a recent version of ASDF, confident that if a user isn't fully satisfied, he can easily upgrade ASDF and deal with a supported recent version of it. This means that release cycles will be causally decoupled, the practical consequence of which will mean faster convergence towards the latest version for everyone.
The main pitfalls in upgrading to ASDF 2 seem to be related to the output translation mechanism.
enable-asdf-binary-locations-compatibilityin see Backward Compatibility. But thou shalt not load ABL on top of ASDF 2.
Other issues include the following:
:pathnameargument to a
defsystemand its components, a logical pathname (or implementation-dependent hierarchical pathname) must now be specified with
#psyntax where the namestring might have previously sufficed; moreover when evaluation is desired
#.must be used, where it wasn't necessary in the toplevel
:pathnameargument (but necessary in other
(directory "/configured/path/**/*.asd")for every configured path
(:tree "/configured/path/")in your
source-registryconfiguration can cause a slight pause. Try to
(time (asdf:initialize-source-registry))to see how bad it is or isn't on your system. If you insist on not having this pause, you can avoid the pause by overriding the default source-registry configuration and not use any deep
:treeentry but only
:directoryentries or shallow
:treeentries. Or you can fix your implementation to not be quite that slow when recursing through directories. Update: This performance bug fixed the hard way in 2.010.
(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo)))) (declare (ignorable component system)) "lis"). Now, the pathname for a component is eagerly computed when defining the system, and instead you will
(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))and use
:default-component-class cl-source-file.lisas argument to
defsystem, as detailed in a see How do I create a system definition where all the source files have a .cl extension? below.
We recommend you upgrade ASDF. See Upgrading ASDF.
If this does not work, it is a bug, and you should report it. See report-bugs. In the meantime, you can load asdf.lisp directly. See Loading an otherwise installed ASDF.
Since ASDF 2,
it should always be a good time to upgrade to a recent version of ASDF.
You may consult with the maintainer for which specific version they recommend,
but the latest
release should be correct.
Though we do try to test ASDF releases against all implementations that we can,
we may not be testing against all variants of your implementation,
and we may not be running enough tests;
we trust you to thoroughly test it with your own implementation
before you release it.
If there are any issues with the current release,
it's a bug that you should report upstream and that we will fix ASAP.
As to how to include ASDF, we recommend the following:
(require "asdf")should load the version of ASDF that is bundled with your system. If possible so should
(require "ASDF"). You may have it load some other version configured by the user, if you allow such configuration.
CL:REQUIRE, then it would be nice to add ASDF to this hook the same way that ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it. Please send us appropriate code to this end.
asdf-ecland asdf-ecl.asd, or
sb-asdfand sb-asdf.asd. Indeed, if you made asdf.asd a magic system, then users would no longer be able to upgrade ASDF using ASDF itself to some version of their preference that they maintain independently from your Lisp distribution.
wrapping-source-registry, and you are welcome to include asdf.asd amongst them. Non-magic systems should be at the back of the
wrapping-source-registrywhile magic systems are at the front.
(require "uiop")and not load ASDF, or one may
(require "asdf")which would implicitly require and load the former.
See Controlling where ASDF saves compiled files.
Note that in the past there was an add-on to ASDF called
ASDF-binary-locations, developed by Gary King.
That add-on has been merged into ASDF proper,
then superseded by the
Note that use of
can interfere with one aspect of your systems
— if your system uses
*load-truename* to find files
(e.g., if you have some data files stored with your program),
then the relocation that this ASDF customization performs
is likely to interfere.
asdf:system-relative-pathname to locate a file
in the source directory of some system, and
asdf:apply-output-translations to locate a file
whose pathname has been translated by the facility.
To permanently disable the compiler output cache for all future runs of ASDF, you can:
mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/ echo ':disable-cache' > ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
This assumes that you didn't otherwise configure the ASDF files
(if you did, edit them again),
and don't somehow override the configuration at runtime
with a shell variable (see below) or some other runtime command
(e.g. some call to
To disable the compiler output cache in Lisp processes
run by your current shell, try (assuming
(on Unix and cygwin only):
To disable the compiler output cache just in the current Lisp process, use (after loading ASDF but before using it):
ASDF provides a predefined test operation,
The test operation, however, is largely left to the system definer to specify.
test-op has been
a topic of considerable discussion on the
asdf-devel mailing list,
and on the
Here are some guidelines:
(defsystem foo :in-order-to ((test-op (test-op foo-test))) ....) (defsystem foo-test :depends-on (foo my-test-library ...) ....)
This procedure will allow you to support users who do not wish to install your test framework.
One oddity of ASDF is that
operate (see operate)
does not return a value. So in current versions of ASDF there is no
reliable programmatic means of determining whether or not a set of tests
has passed, or which tests have failed. The user must simply read the
console output. This limitation has been the subject of much
Various ASDF extensions provide some kind of
See also https://bugs.launchpad.net/asdf/+bug/479470.
By default, the files contained in an asdf module go
in a subdirectory with the same name as the module.
However, this can be overridden by adding a
:pathname "" argument
to the module description.
For example, here is how it could be done
in the spatial-trees ASDF system definition for ASDF 2:
(asdf:defsystem :spatial-trees :components ((:module base :pathname "" :components ((:file "package") (:file "basedefs" :depends-on ("package")) (:file "rectangles" :depends-on ("package")))) (:module tree-impls :depends-on (base) :pathname "" :components ((:file "r-trees") (:file "greene-trees" :depends-on ("r-trees")) (:file "rstar-trees" :depends-on ("r-trees")) (:file "rplus-trees" :depends-on ("r-trees")) (:file "x-trees" :depends-on ("r-trees" "rstar-trees")))) (:module viz :depends-on (base) :pathname "" :components ((:static-file "spatial-tree-viz.lisp"))) (:module tests :depends-on (base) :pathname "" :components ((:static-file "spatial-tree-test.lisp"))) (:static-file "LICENCE") (:static-file "TODO")))
All of the files in the
tree-impls module are at the top level,
instead of in a tree-impls/ subdirectory.
Note that the argument to
:pathname can be either a pathname object or a string.
A pathname object can be constructed with the #p"foo/bar/" syntax,
but this is discouraged because the results of parsing a namestring are not portable.
A pathname can only be portably constructed with such syntax as
#.(make-pathname :directory '(:relative "foo" "bar")),
and similarly the current directory can only be portably specified as
#.(make-pathname :directory '(:relative)).
However, as of ASDF 2, you can portably use a string to denote a pathname.
The string will be parsed as a
/-separated path from the current directory,
such that the empty string
"" denotes the current directory, and
"foo/bar" (no trailing
/ required in the case of modules)
portably denotes the same subdirectory as above.
When files are specified, the last
/-separated component is interpreted
either as the name component of a pathname
(if the component class specifies a pathname type),
or as a name component plus optional dot-separated type component
(if the component class doesn't specifies a pathname type).
Starting with ASDF 2.014.14, you may just pass
the builtin class
:default-component-class argument to
(defsystem my-cl-system :default-component-class cl-source-file.cl ...)
Another builtin class
cl-source-file.lsp is offered
for files ending in .lsp.
If you want to use a different extension for which ASDF doesn't provide builtin support, or want to support versions of ASDF earlier than 2.014.14 (but later than 2.000), you can define a class as follows:
;; Prologue: make sure we're using a sane package. (defpackage :my-asdf-extension (:use :asdf :common-lisp) (:export #:cl-source-file.lis)) (in-package :my-asdf-extension) (defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))
Then you can use it as follows:
(defsystem my-cl-system :default-component-class my-asdf-extension:cl-source-file.lis ...)
Of course, if you're in the same package, e.g. in the same file,
you won't need to use the package qualifier before
Actually, if all you're doing is defining this class
and using it in the same file without other fancy definitions,
you might skip package complications:
(in-package :asdf) (defclass cl-source-file.lis (cl-source-file) ((type :initform "lis"))) (defsystem my-cl-system :default-component-class cl-source-file.lis ...)
It is possible to achieve the same effect
in a way that supports both ASDF 1 and ASDF 2,
but really, friends don't let friends use ASDF 1.
Please upgrade to ASDF 3.
In short, though: do same as above, but
before you use the class in a
you also define the following method:
(defmethod source-file-type ((f cl-source-file.lis) (s system)) (declare (ignorable f s)) "lis")
This not-so-frequently asked question is primarily for ASDF developers, but those who encounter an unexpected error in some test may be interested, too.
Here's the procedure for experimenting with tests in a REPL:
(load "script-support.lisp") (in-package :asdf-test) (compile-load-asdf) ; there are a number of other functions to load ASDF ;; experiment with test code from a .script file...