From f2ac7b0722cd662093374b4a22cedaa0515851ca Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@gmail.com> Date: Thu, 3 Jul 2014 11:58:17 -0500 Subject: [PATCH] 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. --- doc/asdf.texinfo | 53 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 6f7fb747..ba4210f9 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -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, -- GitLab