Next: , Previous: , Up: Configuring ASDF   [Contents][Index]

4.2 Configuring ASDF to find your systems — old style

Novices may skip this section. Please do not use the central-registry if you are a novice, and do not instruct novices to use the central-registry.

The old way to configure ASDF to find your systems is by pushing directory pathnames onto the variable asdf:*central-registry*.

You must configure this variable after you load ASDF 3 or later, yet before the first time you try to use it. This loading and configuring of ASDF must happen as part of some initialization script: typically, either a script you maintain that builds your project, or your implementation’s initialization script (e.g. ~/.sbclrc for SBCL).

Also, if you are using an ancient ASDF 2 or earlier to load ASDF 3 or later, then after it loads the ancient ASDF, your script must configure the central-registry a first time to tell ASDF 1 or 2 where to find ASDF 3, then load ASDF 3 with e.g. (asdf:operate 'asdf:load-op "asdf"), then configure the central-registry again, because ASDF 3 will not preserve the central-registry from ASDF 2 when upgrading. You should probably be using the source-registry instead, which will be preserved (unless you manually called asdf:initialize-source-registry with an argument, in which case you will have to do it again indeed). However, if you are using an ancient ASDF 2 or earlier, we strongly recommend that you should instead upgrade your implementation, or overwrite the ancient ASDF installation with a more recent one: See Replacing your implementation's ASDF.

The asdf:*central-registry* is empty by default in ASDF 2 or ASDF 3, but is still supported for compatibility with ASDF 1. When used, it takes precedence over the above source-registry.5

For example, let’s say you want ASDF to find the .asd file /home/me/src/foo/foo.asd. In your Lisp initialization file, you could have the following:

(require "asdf")
(push "/home/me/src/foo/" asdf:*central-registry*)

Note the trailing slash: when searching for a system, ASDF will evaluate each entry of the central registry and coerce the result to a pathname.6 The trailing directory name separator is necessary to tell Lisp that you’re discussing a directory rather than a file. If you leave it out, ASDF is likely to look in /home/me/src/ instead of /home/me/src/foo/ as you intended, and fail to find your system definition. Modern versions of ASDF will issue an error and offer you to remove such entries from the central-registry.

Typically there are a lot of .asd files, and a common idiom was to put symbolic links to all of one’s .asd files in a common directory and push that directory (the “link farm”) onto asdf:*central-registry*, instead of pushing each individual system directory.

ASDF knows to follow symlinks to the actual location of the systems.7

For example, if #p"/home/me/cl/systems/" is an element of *central-registry*, you could set up the system foo as follows:

$ cd /home/me/cl/systems/
$ ln -s ~/src/foo/foo.asd .

This old style for configuring ASDF is not recommended for new users, but it is supported for old users, and for users who want a simple way to programmatically control what directories are added to the ASDF search path.



It is possible to further 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.


ASDF will indeed call eval on each entry. It will skip entries that evaluate to nil.

Strings and pathname objects are self-evaluating, in which case the eval step does nothing; but you may push arbitrary s-expressions onto the central registry. These s-expressions may be evaluated to compute context-dependent entries, e.g. things that depend on the value of shell variables or the identity of the user.

The variable asdf:*central-registry* is thus a list of “system directory designators”. 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 (or nil). By “directory”, we mean “designator for a pathname with a non-empty DIRECTORY component”.


On Windows, you can use Windows shortcuts instead of POSIX symlinks. if you try aliases under MacOS, we are curious to hear about your experience.

Next: , Previous: , Up: Configuring ASDF   [Contents][Index]