Next: Using ASDF, Previous: Loading ASDF, Up: Top [Contents][Index]
So it may compile and load your systems, ASDF must be configured to find the .asd files that contain system definitions.
Since ASDF 2, 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.
The default location for a user to install Common Lisp software is under ~/.local/share/common-lisp/source/. If you install software there, you don’t need further configuration. If you’re installing software yourself at a location that isn’t standard, you have to tell ASDF where you installed it. See below. If you’re using some tool to install software, the authors of that tool should already have configured ASDF.
The simplest way to add a path to your search path, say /home/luser/.asd-link-farm/ is to create the directory ~/.config/common-lisp/source-registry.conf.d/ and there create a file with any name of your choice but the type conf, for instance 42-asd-link-farm.conf containing the line:
(:directory "/home/luser/.asd-link-farm/")
If you want all the subdirectories under /home/luser/lisp/ to be recursively scanned for .asd files, instead use:
(:tree "/home/luser/lisp/")
Note that your Operating System distribution or your system administrator may already have configured system-managed libraries for you.
The required .conf extension allows you to have disabled files or editor backups (ending in ~), and works portably (for instance, it is a pain to allow both empty and non-empty extension on CLISP). Excluded are files the name of which start with a . character. It is customary to start the filename with two digits that specify the order in which the directories will be scanned.
ASDF will automatically read your configuration the first time you try to find a system. You can reset the source-registry configuration with:
(asdf:clear-source-registry)
And you probably should do so before you dump your Lisp image, if the configuration may change between the machine where you save it at the time you save it and the machine you resume it at the time you resume it.
The old way to configure ASDF to find your systems is by
push
ing directory pathnames onto the variable
asdf:*central-registry*
.
You must configure this variable between the time you load ASDF and the time you first try to use it. Loading and configuring ASDF presumably happen as part of some initialization script that builds or starts your Common Lisp software system. (For instance, some SBCL users used to put it in their ~/.sbclrc.)
The asdf:*central-registry*
is empty by default in ASDF 2,
but is still supported for compatibility with ASDF 1.
When used, it takes precedence over the above source-registry1.
For instance, if you wanted ASDF to find the .asd file
/home/me/src/foo/foo.asd your initialization script
could after it loads ASDF with (require :asdf)
configure it with:
(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 pathname2 at which point the presence of the trailing directory name separator is necessary to tell Lisp that you’re discussing a directory rather than a file.
Typically, however, there are a lot of .asd files, and
a common idiom was to have to put
a bunch of symbolic links to .asd files
in a common directory
and push that directory (the “link farm”)
to the
asdf:*central-registry*
instead of pushing each of the many involved directories
to the asdf:*central-registry*
.
ASDF knows how to follow such symlinks
to the actual file location when resolving the paths of system components
(on Windows, you can use Windows shortcuts instead of POSIX symlinks).
For example, if #p"/home/me/cl/systems/"
(note the trailing slash)
is a member of *central-registry*
, you could set up the
system foo for loading with asdf with the following
commands at the shell:
$ 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 to programmatically control what directories are added to the ASDF search path.
ASDF lets you configure where object files will be stored. Sensible defaults are provided and you shouldn’t normally have to worry about it.
This allows the same source code repository may be shared between several versions of several Common Lisp implementations, between several users using different compilation options and without write privileges on shared source directories, etc. This also allows to keep source directories uncluttered by plenty of object files.
Starting with ASDF 2, the asdf-output-translations
facility
was added to ASDF itself, that controls where object files will be stored.
This facility is fully described in a chapter of this manual,
Controlling where ASDF saves compiled files.
The simplest way to add a translation to your search path, say from /foo/bar/baz/quux/ to /where/i/want/my/fasls/ is to create the directory ~/.config/common-lisp/asdf-output-translations.conf.d/ and there create a file with any name of your choice and the type conf, for instance 42-bazquux.conf containing the line:
("/foo/bar/baz/quux/" "/where/i/want/my/fasls/")
To disable output translations for source under a given directory, say /toto/tata/ you can create a file 40-disable-toto.conf with the line:
("/toto/tata/")
To wholly disable output translations for all directories, you can create a file 00-disable.conf with the line:
(t t)
Note that your Operating System distribution or your system administrator may already have configured translations for you. In absence of any configuration, the default is to redirect everything under an implementation-dependent subdirectory of ~/.cache/common-lisp/. See Controlling where ASDF searches for systems, for full details.
The required .conf extension allows you to have disabled files or editor backups (ending in ~), and works portably (for instance, it is a pain to allow both empty and non-empty extension on CLISP). Excluded are files the name of which start with a . character. It is customary to start the filename with two digits that specify the order in which the directories will be scanned.
ASDF will automatically read your configuration the first time you try to find a system. You can reset the source-registry configuration with:
(asdf:clear-output-translations)
And you probably should do so before you dump your Lisp image, if the configuration may change between the machine where you save it at the time you save it and the machine you resume it at the time you resume it.
Finally note that before ASDF 2, other ASDF add-ons offered the same functionality, each in subtly different and incompatible ways: ASDF-Binary-Locations, cl-launch, common-lisp-controller. ASDF-Binary-Locations is now not needed anymore and should not be used. cl-launch 3.000 and common-lisp-controller 7.2 have been updated to just delegate this functionality to ASDF.
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 also 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 SEXP onto the central registry,
that will be evaluated to compute 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.
By “directory” here, we mean
“designator for a pathname with a supplied DIRECTORY component”.
Next: Using ASDF, Previous: Loading ASDF, Up: Top [Contents][Index]