diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 316d8f79b2b2eed81667aee0850ade28f7e375da..e4d8f7268596286a6912c306aa6f80b933a88c20 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -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