Next: Configuring where ASDF stores object files, Previous: Configuring ASDF to find your systems, Up: Configuring ASDF [Contents][Index]
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: Configuring where ASDF stores object files, Previous: Configuring ASDF to find your systems, Up: Configuring ASDF [Contents][Index]