Commit 53589ba1 authored by Robert P. Goldman's avatar Robert P. Goldman

Clarified documentation of locate-system per Fare.

Also, in passing, did some copy-editing, notably fixing spelling errors.
parent 8175027f
......@@ -909,6 +909,7 @@ For that you may use the following function:
regarding source-registry or output-translations.
@end defun
@vindex *image-dump-hook*
This function is pushed onto the @code{uiop:*image-dump-hook*} by default,
which means that if you save an image using @code{uiop:dump-image},
or via @code{asdf:image-op} and @code{asdf:program-op},
......@@ -2484,23 +2485,54 @@ their own @code{*system-definition-search-functions*}.
Given a system @var{name} designator,
try to locate where to load the system definition from.
(This does not include the loading of the system definition,
which is done by @code{find-system},
or the loading of the system itself, which is done by @code{load-system};
however, for systems the definition of which has already been loaded,
@code{locate-system} may return an object of class @code{system}.)
@c (This does not include the loading of the system definition,
@c which is done by @code{find-system},
@c or the loading of the system itself, which is done by @code{load-system};
@c however, for systems the definition of which has already been loaded,
@c @code{locate-system} may return an object of class @code{system}.)
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,
either a new as yet unregistered one, or a previously registered one.
@var{found-system} when not null is
a @code{system} object that may be @code{register-system}'ed.
The @var{found-system} return value
will be a @code{system} object, if a system definition is found in your
source registry.
@c This system may be registered (by @code{register-system}) or may not, if
@c it's preloaded code. Fare writes:
@c In the case of preloaded code, as for "asdf", "uiop", etc.,
@c themselves, the system objects are not registered until after they are
@c initially located by sysdef-preloaded-system-search as a fallback when
@c no source code was found.
The system definition will @emph{not} be
loaded if it hasn't been loaded already.
@var{pathname} when not null is a path from which to load the system,
either associated with @var{found-system}, or with the @var{previous} system.
@var{previous} when not null is a previously loaded @code{system} object
of the same name.
If @var{previous} is not null, it will be a @emph{previously loaded}
@code{system} object of the same name (note that the system
@emph{definition} is previously-loaded: the system itself may or may not be).
@var{previous-time} when not null is
the time at which the @var{previous} system was loaded.
the timestamp of the previous system definition file, at the
time when the @var{previous} system definition was loaded.
For example, if your current registry has @file{foo.asd} in
@file{/current/path/to/foo.asd},
but system @code{foo} was previously loaded from @file{/previous/path/to/foo.asd}
then @var{locate-system} will return the following values:
@enumerate
@item
@var{foundp} will be @code{T},
@item
@var{found-system} will be @code{NIL},
@item
@var{pathname} will be @code{#p"/current/path/to/foo.asd"},
@item
@var{previous} will be an object of type @code{SYSTEM} with
@code{system-source-file} slot value of
@code{#p"/previous/path/to/foo.asd"}
@item
@var{previous-time} will be the timestamp of
@code{#p"/previous/path/to/foo.asd"} at the time it was loaded.
@end enumerate
@end defun
@defun find-component base path
......@@ -2819,8 +2851,8 @@ the default @code{defsystem} macro takes a @code{:class} keyword argument.
New component types are defined by subclassing one of the existing
component classes and specializing methods on the new component class.
@emph{FIXME: this should perhaps be explained more throughly,
not only by example ...}
@c FIXME: this should perhaps be explained more throughly,
@c not only by example ...
As an example, suppose we have some implementation-dependent
functionality that we want to isolate
......@@ -2863,10 +2895,10 @@ The new component type is used in a @code{defsystem} form in this way:
@c FIXME: Moved this material here, but it isn't very comfortable
@c here.... Also needs to be revised to be coherent.
To be successfully buildable, this graph of actions but be acyclic.
If, as a user, extender or implementer of ASDF, you fail
to keep the dependency graph without cycles,
ASDF will fail loudly as it eventually finds one.
To be successfully build-able, this graph of actions must be acyclic.
If, as a user, extender or implementer of ASDF, you introduce
a cycle into the dependency graph,
ASDF will fail loudly.
To clearly distinguish the direction of dependencies,
ASDF 3 uses the words @emph{requiring} and @emph{required}
as applied to an action depending on the other:
......@@ -3057,7 +3089,7 @@ however we recommend you instead use
our source-registry configuration mechanism described below,
because it is easier to setup in a portable way across users and implementations.
Addtionally, some people dislike truename,
Additionally, some people dislike truename,
either because it is very slow on their system, or
because they are using content-addressed storage where the truename of a file
is related to a digest of its individual contents,
......@@ -3345,9 +3377,9 @@ directory according to X's (relative) instructions.
When considering environment variable @code{CL_SOURCE_REGISTRY}
ASDF will skip to next configuration if it's an empty string.
It will @code{READ} the string as a SEXP in the DSL
if it begins with a paren @code{(}
and it will be interpreted much like @code{TEXINPUTS}
list of paths, where
if it begins with a paren @code{(},
otherwise it will be interpreted much like @code{TEXINPUTS},
as a list of paths, where
* paths are separated
by a @code{:} (colon) on Unix platforms (including cygwin),
......@@ -3803,7 +3835,7 @@ TRANSLATION-FUNCTION :=
SYMBOL | ;; symbol naming a function that takes two arguments:
;; the pathname to be translated and the matching
;; DIRECTORY-DESIGNATOR
LAMBDA ;; A form which evalutates to a function taking two arguments:
LAMBDA ;; A form which evaluates to a function taking two arguments:
;; the pathname to be translated and the matching
;; DIRECTORY-DESIGNATOR
......@@ -3864,7 +3896,7 @@ from the file specified.
If the @code{translate-pathname} mechanism cannot achieve a desired
translation, the user may provide a function which provides the
required algorithim. Such a translation function is specified by
required algorithm. Such a translation function is specified by
supplying a list as the second @code{directory-designator}
the first element of which is the keyword @code{:function},
and the second element of which is
......@@ -5707,3 +5739,6 @@ Also, bugs are now tracked on launchpad:
@printindex vr
@bye
@c LocalWords: clbuild tarballs defsystem Quicklisp initarg uiop fasl
@c LocalWords: namestring initargs fasls
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