Next: Dependencies, Previous: Operations, Up: The Object model of ASDF [Contents][Index]
A component represents an individual source file or a group of source files,
and the things that get transformed into.
A system is a component at the top level of the component hierarchy,
that can be found via find-system.
A source-file is a component representing a single source-file
and the successive output files into which it is transformed.
A module is an intermediate component itself grouping several other components,
themselves source-files or further modules.
A system designator is a system itself, or a string or symbol that behaves just like any other component name (including with regard to the case conversion rules for component names).
A component designator, relative to a base component, is either a component itself, or a string or symbol, or a list of designators.
Given a system designator, find-system finds and returns a system.
If no system is found, an error of type
missing-component is thrown,
or nil is returned if error-p is false.
To find and update systems, find-system funcalls each element
in the *system-definition-search-functions* list,
expecting a pathname to be returned, or a system object,
from which a pathname may be extracted, and that will be registered.
The resulting pathname (if any) is loaded
if one of the following conditions is true:
last-modified time exceeds the last-modified time
of the system in memory
When system definitions are loaded from .asd files,
they are implicitly loaded into the ASDF-USER package,
which uses ASDF, UIOP and UIOP/COMMON-LISP12
Programmers who do anything non-trivial in a .asd file,
such as defining new variables, functions or classes,
should include defpackage and in-package forms in this file,
so they will not overwrite each others’ extensions.
Such forms might also help the files behave identically
if loaded manually with cl:load for development or debugging,
though we recommend you use the function asdf::load-asd instead,
which the slime-asdf contrib knows about.
The default value of *system-definition-search-functions*
is a list of three functions.
The first function looks in each of the directories given
by evaluating members of *central-registry*
for a file whose name is the name of the system and whose type is asd;
the first such file is returned,
whether or not it turns out to actually define the appropriate system.
The second function does something similar,
for the directories specified in the source-registry,
but searches the filesystem only once and caches its results.
The third function makes the package-inferred-system extension work,
see The package-inferred-system extension.
Because of the way these search functions are defined, you should put the definition for a system foo in a file named foo.asd, in a directory that is in the central registry or which can be found using the source registry configuration.
It is often useful to define multiple systems in a same file,
but ASDF can only locate a system’s definition file based on the system
name.
For this reason,
ASDF 3’s system search algorithm has been extended to
allow a file foo.asd to contain
secondary systems named foo/bar, foo/baz, foo/quux, etc.,
in addition to the primary system named foo.
The first component of a system name,
separated by the slash character, /,
is called the primary name of a system.
The primary name may be
extracted by function asdf::primary-system-name;
when ASDF 3 is told to find a system whose name has a slash,
it will first attempt to load the corresponding primary system,
and will thus see any such definitions, and/or any
definition of a package-inferred-system.13
If your file foo.asd also defines systems
that do not follow this convention, e.g., a system named foo-test,
ASDF will not be able to automatically locate a definition for these systems,
and will only see their definition
if you explicitly find or load the primary system
using e.g. (asdf:find-system "foo") before you try to use them.
We strongly recommend against this practice,
though it is currently supported for backward compatibility.
Internal (not exported) function, asdf::primary-system-name.
Returns the primary system name (the portion before
the slash, /, in a secondary system name) from name.
This function should typically not be invoked directly. It is
exported as part of the API only for programmers who wish to provide
their own *system-definition-search-functions*.
Given a system name designator,
try to locate where to load the system definition from.
Returns five values: foundp, found-system, pathname,
previous, and previous-time.
foundp is true when a system was found,
either a new as yet unregistered one, or a previously registered one.
The found-system return value
will be a system object, if a system definition is found in your
source registry.
The system definition will not be
loaded if it hasn’t been loaded already.
pathname when not null is a path from which to load the system,
either associated with found-system, or with the previous system.
If previous is not null, it will be a previously loaded
system object of the same name (note that the system
definition is previously-loaded: the system itself may or may not be).
previous-time when not null is
the timestamp of the previous system definition file, at the
time when the previous system definition was loaded.
For example, if your current registry has foo.asd in
/current/path/to/foo.asd,
but system foo was previously loaded from /previous/path/to/foo.asd
then locate-system will return the following values:
t,
nil,
#p"/current/path/to/foo.asd",
SYSTEM with
system-source-file slot value of
#p"/previous/path/to/foo.asd"
#p"/previous/path/to/foo.asd" at the time it was loaded.
Given a base component (or designator for such), and a path, find the component designated by the path starting from the base.
If path is a component object, it designates itself, independently from the base.
If path is a string, or symbol denoting a string via coerce-name,
then base is resolved to a component object,
which must be a system or module,
and the designated component is the child named by the path.
If path is a cons cell,
find-component with the base and the car of the path,
and the resulting object is used as the base for a tail call
to find-component with the car of the path.
If base is a component object, it designates itself.
If base is null, then path is used as the base, with nil as the path.
If base is a string, or symbol denoting a string via coerce-name,
it designates a system as per find-system.
If base is a cons cell, it designates the component found by
find-component with its car as base and cdr as path.
Note that between releases 2.27 and 3.0.3, only UIOP/PACKAGE,
not all of UIOP, was used; if you want your code to work
with releases earlier than 3.1.2, you may have to explicitly define a package
that uses UIOP, or use proper package prefix to your symbols, as in
uiop:version<.
ASDF 2.26 and earlier versions
do not support this primary system name convention.
With these versions of ASDF
you must explicitly load foo.asd
before you can use system foo/bar defined therein,
e.g. using (asdf:find-system "foo").
We do not support ASDF 2, and recommend that you should upgrade to ASDF 3.
Next: Dependencies, Previous: Operations, Up: The Object model of ASDF [Contents][Index]