From 45237f66db033da4edf2af8075ec5c02e3fbe282 Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@gmail.com> Date: Sat, 5 Apr 2014 17:38:44 -0500 Subject: [PATCH] Many more nodes. Nodes for just about every section, and many subsections, as I felt appropriate. --- doc/asdf.texinfo | 89 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 82 insertions(+), 7 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index bd1a56b2..788d229f 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -413,6 +413,7 @@ you only need to @code{(require "asdf")}: ASDF will automatically look whether an updated version of itself is available amongst the regularly configured systems, before it compiles anything else. +@node Notes about ASDF 1 and ASDF 2, Issues with upgrading ASDF, Upgrading ASDF, Upgrading ASDF @subsection Notes about ASDF 1 and ASDF 2 Most implementations provide ASDF 3 in their latest release, @@ -449,6 +450,7 @@ after requiring the builtin ASDF 2: (asdf:load-system :asdf) @end lisp +@node Issues with upgrading ASDF, , Notes about ASDF 1 and ASDF 2, Upgrading ASDF @subsection Issues with upgrading ASDF Note that there are some limitations to upgrading ASDF: @@ -829,6 +831,13 @@ on CMUCL and SCL, etc. @node Using ASDF, Defining systems with defsystem, Configuring ASDF, Top @chapter Using ASDF +@menu +* Loading a system:: +* Other Operations:: +* Moving on:: +@end menu + +@node Loading a system, Other Operations, Using ASDF, Using ASDF @section Loading a system The system @var{foo} is loaded (and compiled, if necessary) @@ -868,7 +877,7 @@ or silently convert lowercase to uppercase (lpns). @c so this makes more sense than attempting to use @code{:case :common}, @c which is reported not to work on some implementations - +@node Other Operations, Moving on, Loading a system, Using ASDF @section Other Operations ASDF provides three commands for the most common system operations: @@ -905,6 +914,7 @@ with keyword arguments @code{:force-not (already-loaded-systems)}. the system, and any provided keyword arguments. +@node Moving on, , Other Operations, Using ASDF @section Moving on That's all you need to know to use ASDF to load systems written by others. @@ -2585,6 +2595,27 @@ as well as an inclusive lower bound. @comment node-name, next, previous, up @chapter Controlling where ASDF searches for systems + + +@menu +* Configurations:: +* Truenames and other dangers:: +* XDG base directory:: +* Backward Compatibility:: +* Configuration DSL:: +* Configuration Directories:: +* Shell-friendly syntax for configuration:: +* Search Algorithm:: +* Caching Results:: +* Configuration API:: +* Introspection:: +* Status:: +* Rejected ideas:: +* TODO:: +* Credits for the source-registry:: +@end menu + +@node Configurations, Truenames and other dangers, Controlling where ASDF searches for systems, Controlling where ASDF searches for systems @section Configurations Configurations specify paths where to find system files. @@ -2663,7 +2694,7 @@ Additionally, some implementation-specific directories may be automatically prepended to whatever directories are specified in configuration files, no matter if the last one inherits or not. - +@node Truenames and other dangers, XDG base directory, Configurations, Controlling where ASDF searches for systems @section Truenames and other dangers One great innovation of the original ASDF was its ability to leverage @@ -2686,7 +2717,7 @@ by setting the variable @var{asdf:*resolve-symlinks*} to @code{nil}. PS: Yes, if you haven't read Vernor Vinge's short but great classic ``True Names... and Other Dangers'' then you're in for a treat. - +@node XDG base directory, Backward Compatibility, Truenames and other dangers, Controlling where ASDF searches for systems @section XDG base directory Note that we purport to respect the XDG base directory specification @@ -2708,6 +2739,7 @@ Since support for querying the Windows registry is not possible to do in reasonable amounts of portable Common Lisp code, ASDF 3 relies on the environment variables that Windows usually exports. +@node Backward Compatibility, Configuration DSL, XDG base directory, Controlling where ASDF searches for systems @section Backward Compatibility For backward compatibility as well as to provide a practical backdoor for hackers, @@ -2722,6 +2754,7 @@ By default, @code{asdf:*central-registry*} will be empty. This old mechanism will therefore not affect you if you don't use it, but will take precedence over the new mechanism if you do use it. +@node Configuration DSL, Configuration Directories, Backward Compatibility, Controlling where ASDF searches for systems @section Configuration DSL @cindex :inherit-configuration source config directive @cindex inherit-configuration source config directive @@ -2842,6 +2875,7 @@ which is the default place ASDF looks for this configuration, once contained: :inherit-configuration) @end example +@node Configuration Directories, Shell-friendly syntax for configuration, Configuration DSL, Controlling where ASDF searches for systems @section Configuration Directories Configuration directories consist in files each containing @@ -2878,6 +2912,7 @@ alone in its directory with the following contents: (:tree "/home/fare/cl/") @end example +@node The :here directive, , Configuration Directories, Configuration Directories @subsection The :here directive The @code{:here} directive is an absolute pathname designator that @@ -2923,6 +2958,7 @@ form containing that s-expression. ASDF will find the .conf file that X has provided, and then set up source locations within the working directory according to X's (relative) instructions. +@node Shell-friendly syntax for configuration, Search Algorithm, Configuration Directories, Controlling where ASDF searches for systems @section Shell-friendly syntax for configuration When considering environment variable @code{CL_SOURCE_REGISTRY} @@ -2946,7 +2982,7 @@ list of paths, where then it indicates that the inherited configuration should be spliced there. - +@node Search Algorithm, Caching Results, Shell-friendly syntax for configuration, Controlling where ASDF searches for systems @section Search Algorithm @vindex *default-source-registry-exclusions* @@ -2982,6 +3018,7 @@ specifications from the next configuration (@pxref{Controlling where ASDF searches for systems,,Configurations} above). +@node Caching Results, Configuration API, Search Algorithm, Controlling where ASDF searches for systems @section Caching Results The implementation is allowed to either eagerly compute the information @@ -2989,7 +3026,7 @@ from the configurations and file system, or to lazily re-compute it every time, or to cache any part of it as it goes. To explicitly flush any information cached by the system, use the API below. - +@node Configuration API, Introspection, Caching Results, Controlling where ASDF searches for systems @section Configuration API The specified functions are exported from your build system's package. @@ -3035,8 +3072,15 @@ you need to explicitly @code{initialize-source-registry} again, or maybe simply to @code{clear-source-registry} (or @code{clear-configuration}) which will cause the initialization to happen next time around. +@node Introspection, Status, Configuration API, Controlling where ASDF searches for systems @section Introspection +@menu +* *source-registry-parameter* variable:: +* Information about system dependencies:: +@end menu + +@node *source-registry-parameter* variable, Information about system dependencies, Introspection, Introspection @subsection *source-registry-parameter* variable @vindex *source-registry-parameter* @@ -3047,6 +3091,7 @@ never be set!} It will be set as a side-effect of calling @code{initialize-source-registry}; user code should treat it as read-only. +@node Information about system dependencies, , *source-registry-parameter* variable, Introspection @subsection Information about system dependencies ASDF makes available three functions to read system interdependencies. @@ -3070,6 +3115,7 @@ than the return values of the other two system dependency introspection functions. @end defun +@node Status, Rejected ideas, Introspection, Controlling where ASDF searches for systems @section Status This mechanism is vastly successful, and we have declared @@ -3079,7 +3125,7 @@ All hooks into implementation-specific search mechanisms have been integrated in the @code{wrapping-source-registry} that everyone uses implicitly. - +@node Rejected ideas, TODO, Status, Controlling where ASDF searches for systems @section Rejected ideas Alternatives I considered and rejected included: @@ -3133,13 +3179,14 @@ for the sake of keeping ASDF no more complex than strictly necessary. It isn't that Lisp friendly either. @end itemize +@node TODO, Credits for the source-registry, Rejected ideas, Controlling where ASDF searches for systems @section TODO @itemize @item Add examples @end itemize - +@node Credits for the source-registry, , TODO, Controlling where ASDF searches for systems @section Credits for the source-registry Thanks a lot to Stelian Ionescu for the initial idea. @@ -3173,6 +3220,19 @@ as you switch from one implementation to the next. Since ASDF 2, ASDF includes the @code{asdf-output-translations} facility to mitigate the problem. +@menu +* Configurations:: +* Backward Compatibility:: +* Configuration DSL:: +* Configuration Directories:: +* Shell-friendly syntax for configuration:: +* Semantics of Output Translations:: +* Caching Results:: +* Output location API:: +* Credits for output translations:: +@end menu + +@node Configurations, Backward Compatibility, Controlling where ASDF saves compiled files, Controlling where ASDF saves compiled files @section Configurations Configurations specify mappings from input locations to output locations. @@ -3245,6 +3305,7 @@ at the expense of taking a small toll when developers have to clean up output files and find they need to get familiar with output-translations first. +@node Backward Compatibility, Configuration DSL, Configurations, Controlling where ASDF saves compiled files @section Backward Compatibility @cindex ASDF-BINARY-LOCATIONS compatibility @@ -3300,6 +3361,7 @@ Also, note that output translation is enabled by default. To disable it, use @code{(asdf:disable-output-translations)}. +@node Configuration DSL, Configuration Directories, Backward Compatibility, Controlling where ASDF saves compiled files @section Configuration DSL Here is the grammar of the SEXP DSL @@ -3426,6 +3488,7 @@ which by default is the same as using @end itemize +@node Configuration Directories, Shell-friendly syntax for configuration, Configuration DSL, Controlling where ASDF saves compiled files @section Configuration Directories Configuration directories consist in files each contains @@ -3452,6 +3515,7 @@ or namestring in an @code{:include} directive, e.g.: (:include "/foo/bar/") @end verbatim +@node Shell-friendly syntax for configuration, Semantics of Output Translations, Configuration Directories, Controlling where ASDF saves compiled files @section Shell-friendly syntax for configuration When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS} @@ -3472,6 +3536,7 @@ it indicates that the directory specified first is to be left untranslated (which has the same effect as if the directory had been repeated). +@node Semantics of Output Translations, Caching Results, Shell-friendly syntax for configuration, Controlling where ASDF saves compiled files @section Semantics of Output Translations From the specified configuration, @@ -3501,6 +3566,7 @@ If no match is found, return the source pathname. may ensure that there will always be a match, with same fall-through semantics). +@node Caching Results, Output location API, Semantics of Output Translations, Controlling where ASDF saves compiled files @section Caching Results The implementation is allowed to either eagerly compute the information @@ -3509,6 +3575,7 @@ every time, or to cache any part of it as it goes. To explicitly flush any information cached by the system, use the API below. +@node Output location API, Credits for output translations, Caching Results, Controlling where ASDF saves compiled files @section Output location API The specified functions are exported from package ASDF. @@ -3565,6 +3632,7 @@ or maybe @code{clear-output-translations} (or @code{clear-configuration}), which will cause the initialization to happen next time around. +@node Credits for output translations, , Output location API, Controlling where ASDF saves compiled files @section Credits for output translations Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations}, @@ -3635,6 +3703,12 @@ The valid values for these variables are ASDF includes several additional features that are generally useful for system definition and development. +@menu +* Controlling file compilation:: +* Some Utility Functions:: +@end menu + +@node Controlling file compilation, , Miscellaneous additional functionality, Miscellaneous additional functionality @section Controlling file compilation @cindex :around-compile @cindex around-compile keyword @@ -3947,6 +4021,7 @@ while others (like SBCL) will make an attempt at invoking a POSIX shell (and fail if it is not present). @end defun +@node Some Utility Functions, , Controlling file compilation, Miscellaneous additional functionality @section Some Utility Functions The below functions are not exported by ASDF itself, but by UIOP, available since ASDF 3. -- GitLab