Commit f2ac7b07 authored by Robert P. Goldman's avatar Robert P. Goldman
Browse files

Revise the system search functions docs.

Add a FIXME.
Pull out documentation of PRIMARY-SYSTEM-NAME.
Clarify that LOCATE-SYSTEM will actually load the system.
Minor copy-edits.
parent 79a01889
......@@ -2419,27 +2419,40 @@ but searches the filesystem only once and caches its results.
The third function makes the @code{package-inferred-system} extension work,
@pxref{The package-inferred-system extension}.
Hence, it is strongly advised to define a system
@var{foo} in a corresponding file @file{foo.asd}
that will be in a directory included
in the central registry or source registry configuration.
Because 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,
ASDF 3 also supports the convention whereby a file @file{foo.asd} can contain
Because of the way these search functions are defined,
you should put the definition for a system
@var{foo} in a file named @file{foo.asd},
in a directory that is
in the central registry or
which can be found using the
source registry configuration.
@c FIXME: Move this discussion to the system definition grammar, or somewhere else.
@anchor{System names}
@cindex System names
@cindex Primary system name
@findex primary-system-name
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 @file{foo.asd} to contain
secondary systems named @var{foo/bar}, @var{foo/baz}, @var{foo/quux}, etc.,
in addition to the primary system named @var{foo}.
The first component of a system name
when separated by slash characters @code{/}
is called the primary name of a system,
as extracted by function @code{asdf::primary-system-name};
The first component of a system name,
separated by the slash character, @code{/},
is called the primary name of a system.
The primary name may be
extracted by function @code{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 @code{package-inferred-system}.@footnote{
ASDF 2.26 and earlier versions however
do not actively support this primary system name convention,
and you will have to explicitly load @file{foo.asd}
ASDF 2.26 and earlier versions
do not support this primary system name convention.
With these versions of ASDF
you must explicitly load @file{foo.asd}
before you can use system @var{foo/bar} defined therein,
e.g. using @code{(asdf:find-system "foo")}.
We do not support ASDF 2, and recommend that you should upgrade to ASDF 3.
......@@ -2455,6 +2468,14 @@ though it is currently supported for backward compatibility.
@end defun
@defun primary-system-name name
Internal (not exported) function, @code{asdf::primary-system-name}.
Returns the primary system name (the portion before
the slash, @code{/}, in a secondary system name) from @var{name}.
@end defun
@defun locate-system name
This function should typically @emph{not} be invoked directly. It is
......@@ -2462,7 +2483,7 @@ exported as part of the API only for programmers who wish to provide
their own @code{*system-definition-search-functions*}.
Given a system @var{name} designator,
try to locate where to load the system from.
try to locate and load the system definition (but not the system itself).
Returns five values: @var{foundp}, @var{found-system}, @var{pathname},
@var{previous}, and @var{previous-time}.
@var{foundp} is true when a system was found,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment