Configuring ASDF to find your systems (ASDF Manual)

4.1 Configuring ASDF to find your systems

In order to compile and load your systems, ASDF must be configured to find the .asd files that contain system definitions.

There are a number of different techniques for setting yourself up with ASDF, starting from easiest to the most complex:

Put all of your systems in one of the standard locations, subdirectories of
- ~/common-lisp/ or
- ~/.local/share/common-lisp/source/.
If you install software there, you don’t need further configuration.² You can then skip to the next section. See Loading a system.
If you’re using some tool to install software (e.g. Quicklisp), the authors of that tool should already have configured ASDF.
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 source-registry facility, fully described in its own chapter of this manual. See Controlling where ASDF searches for systems. Here is a quick recipe for getting started.
First create the directory ~/.config/common-lisp/source-registry.conf.d/³; there create a file with any name of your choice but with the type conf⁴, for instance 50-luser-lisp.conf; in this file, add the following line to tell ASDF to recursively scan all the subdirectories under /home/luser/lisp/ for .asd files: (:tree "/home/luser/lisp/")

That’s enough. You may replace /home/luser/lisp/ by wherever you want to install your source code. You don’t actually need to specify anything if you use the default ~/common-lisp/ as above and your implementation provides ASDF 3.1.2 or later. If your implementation provides an earlier variant of ASDF 3, you might want to specify (:tree (:home "common-lisp/")) for bootstrap purposes, then install a recent source tree of ASDF under ~/common-lisp/asdf/.

If you prefer to use a “link farm”, which is faster to use but costlier to manage than a recursive traversal, say at /home/luser/.asd-link-farm/, then you may instead (or additionally) create a file 42-asd-link-farm.conf, containing the line: (:directory "/home/luser/.asd-link-farm/")

ASDF will automatically read your configuration the first time you try to find a system. If necessary, you can reset the source-registry configuration with:
```
(asdf:clear-source-registry)
```
In earlier versions of ASDF, the system source registry was configured using a global variable, asdf:*central-registry*. For more details about this, see the following section, Configuring ASDF to find your systems — old style. Unless you need to understand this, skip directly to Configuring where ASDF stores object files.

Note that your Operating System distribution or your system administrator may already have configured system-managed libraries for you.

Footnotes

(2)

~/common-lisp/ is only included in the default configuration starting with ASDF 3.1.2 or later. If your implementation provides an earlier variant of ASDF, you may need to explicitly configure it to use this path, as further explained.

(3)

For Windows users, and starting with ASDF 3.1.5, start from your %LOCALAPPDATA%, which is usually ~/AppData/Local/ (but you can ask in a CMD.EXE terminal echo %LOCALAPPDATA% to make sure) and underneath create a subpath config/common-lisp/source-registry.conf.d/.

(4)

By requiring the .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 . character.

It is customary to start the filename with two digits, to control the sorting of the conf files in the source registry directory, and thus the order in which the directories will be scanned.