From d19a46a924b4b151d085085af834d9c9750937ff Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@gmail.com> Date: Sun, 6 Apr 2014 10:21:52 -0500 Subject: [PATCH] Revised the introduction to the object model chapter. Also, in passing, fixed the spacing after the macros for lambda list keywords. --- doc/asdf.texinfo | 303 +++++++++++++++++++++++++++++------------------ 1 file changed, 191 insertions(+), 112 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 2151db39..8e02c5b0 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -21,9 +21,6 @@ @macro Abody &body @end macro -@macro defcond -@deftyp CONDITION -@end macro @c for install-info @dircategory Software development @@ -119,11 +116,22 @@ Loading ASDF * Upgrading ASDF:: * Loading ASDF from source:: +Upgrading ASDF + +* Notes about ASDF 1 and ASDF 2:: +* Issues with upgrading ASDF:: + Configuring ASDF * Configuring ASDF to find your systems:: * Configuring where ASDF stores object files:: +Using ASDF + +* Loading a system:: +* Other Operations:: +* Moving on:: + Defining systems with defsystem * The defsystem form:: @@ -132,10 +140,11 @@ Defining systems with defsystem * Other code in .asd files:: * The package-system extension:: -The object model of ASDF +The Object model of ASDF * Operations:: * Components:: +* Dependencies:: * Functions:: Operations @@ -154,6 +163,50 @@ properties * Pre-defined subclasses of component:: * Creating new component types:: +Controlling where ASDF searches for systems + +* 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:: + +Configuration Directories + +* The :here directive:: + +Introspection + +* *source-registry-parameter* variable:: +* Information about system dependencies:: + +Controlling where ASDF saves compiled files + +* 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:: + +Miscellaneous additional functionality + +* Controlling file compilation:: +* Some Utility Functions:: + FAQ * Where do I report a bug?:: @@ -416,6 +469,11 @@ 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. +@menu +* Notes about ASDF 1 and ASDF 2:: +* Issues with upgrading ASDF:: +@end menu + @node Notes about ASDF 1 and ASDF 2, Issues with upgrading ASDF, Upgrading ASDF, Upgrading ASDF @subsection Notes about ASDF 1 and ASDF 2 @@ -1188,7 +1246,7 @@ simple-component-name := string pathname-specifier := pathname | string | symbol -method-form := (operation-name qual lambda-list @Arest body) +method-form := (operation-name qual lambda-list @Arest@ body) qual := method qualifier component-dep-fail-option := :fail | :try-next | :ignore @@ -1465,13 +1523,18 @@ is equivalent to @end lisp -@subsection Source location +@subsection Source location (@code{:pathname}) The @code{:pathname} option is optional in all cases for systems -defined via @code{defsystem}, -and in the usual case the user is recommended not to supply it. +defined via @code{defsystem}, and generally is unnecessary. In the +simple case, source files will be found in the same directory as the +system or, in the case of modules, in a subdirectory with the same name +as the module. + +@c FIXME: This should be moved elsewhere -- it's too much detail for the +@c grammar section. -Instead, ASDF follows a hairy set of rules that are designed so that +More specifically, ASDF follows a hairy set of rules that are designed so that @enumerate @item @code{find-system} @@ -1549,9 +1612,14 @@ and its implementation was breaking a hole into the ASDF object model. Please use the @code{if-feature} option instead. @subsection feature requirement -This requirement was removed in ASDF 3.1. -It used to ensure that a chain of component dependencies will raise an error, -which in conjunction with if-component-dep-fails would offer +This requirement was removed in ASDF 3.1. Please do not use it. In +most cases, @code{:if-feature} (@pxref{if-feature-option}) will provide +an adequate substitute. + +The @code{feature} requirement used to ensure that a chain of component +dependencies would fail when a key feature was absent. +Used in conjunction with @code{:if-component-dep-fails} +this provided a roundabout way to express conditional compilation. @@ -1654,93 +1722,56 @@ that allow for ``inheritance'' of symbols being exported. @node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top @comment node-name, next, previous, up -@chapter The object model of ASDF +@chapter The Object model of ASDF +@tindex component +@tindex operation ASDF is designed in an object-oriented way from the ground up. Both a system's structure and the operations that can be performed on systems -follow a extensible protocol. - -This allows the addition of behaviours: -for example, @code{cffi} adds support of special FFI description files -to interface with C libraries and of wrapper files to embed C code in Lisp; -@code{abcl-jar} supports creating Java JAR archives in ABCL; -and @code{poiu} supports for compiling code in parallel using background processes. - -This chapter deals with @code{component}s and @code{operation}s. +follow a extensible protocol, allowing programmers to add new behaviors to ASDF. +For example, @code{cffi} adds support for special FFI description files +that interface with C libraries and for wrapper files that embed C code in Lisp. +@code{abcl-jar} supports creating Java JAR archives in ABCL. +@code{poiu} supports compiling code in parallel using background processes. +The key classes in ASDF are @code{component}s and @code{operation}s. A @code{component} represents an individual source file or a group of source files, -and the things that get transformed into. -A @code{system} is a component at the top level of the component hierarchy. -A @code{source-file} is a component representing a single source-file -and the successive output files into which it is transformed. -A @code{module} is an intermediate component itself grouping several other components, -themselves source-files or further modules. - -An @code{Operation} represents a transformation that can be performed on a component, +and the products (e.g., fasl files) produced from it. +An @code{operation} represents a transformation that can be performed on a component, turning them from source files to intermediate results to final outputs. - -A pair of an @code{operation} and a @code{component} is called an @code{action}. -An @code{action} represents a particular build step to be @code{perform}ed, -after all its dependencies have been fulfilled. -In the ASDF model, actions depend on other actions. -The term @emph{action} itself was used by Kent Pitman in his old article, -but was only used by ASDF hackers starting with the ASDF 2; -but the concept is ubiquitous since the very beginning of ASDF 1, -though previously implicit. - -Then, there are many @emph{functions} available -to users, extenders and implementers of ASDF -to use, define or implement the activities -that are part of building your software. -Though they manipulate @code{action}s, -most of these functions do not take as an argument -a reified pair (a @code{cons} cell) of an operation and a component; -instead, they usually take two separate arguments, -which allows to take advantage of the power CLOS-style multiple dispatch -for fun and profit. - -There are many @emph{hooks} in which to add functionality, -by customizing the behavior of existing @emph{functions}. - -Last but not least is the notion of @emph{dependency} between two actions. -The structure of dependencies between actions is -a directed @emph{dependency graph}. -ASDF is invoked by being told to @emph{operate} -with some @emph{operation} on some toplevel @emph{system}; -it will then @emph{traverse} the graph and build a @emph{plan} -that follows its structure. -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 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: -the requiring action @code{depends-on} the completion of all required actions -before it may itself be @code{perform}ed. - -Using the @code{defsystem} syntax, users may easily express -direct dependencies along the graph of the object hierarchy: -between a component and its parent, its children, and its siblings. -By defining custom CLOS methods, you can express more elaborate dependencies as you wish. -Most common operations, such as @code{load-op}, @code{compile-op} or @code{load-source-op} -are automatically propagate ``downward'' the component hierarchy and are ``covariant'' with it: -to act the operation on the parent module, you must first act it on all the children components, -with the action on the parent being parent of the action on each child. -Other operations, such as @code{prepare-op} and @code{prepare-source-op} -(introduced in ASDF 3) are automatically propagated ``upward'' the component hierarchy -and are ``contravariant'' with it: -to perform the operation of preparing for compilation of a child component, -you must perform the operation of preparing for compilation of its parent component, and so on, -ensuring that all the parent's dependencies are (compiled and) loaded -before the child component may be compiled and loaded. -Yet other operations, such as @code{test-op} or @code{load-fasl-op} -remain at the system level, and are not propagated along the hierarchy, -but instead do something global on the system. - +Components are related by @emph{dependencies}, specified in system +definitions. + +When ordered to perform some operation on a system, ASDF will first compute a dependency +graph. +ASDF will then @emph{traverse} the dependency graph to derive a @emph{plan} for the +operation. +This plan is an ordered list of @emph{actions}. +An action is a pair of an @code{operation} and a @code{component}, +representing a particular build step to be @code{perform}ed. +The ordering of the plan ensures that no action is performed before +all its dependencies have been fulfilled.@footnote{The term @emph{action} +was used by Kent Pitman in his old article, @c FIXME: what article? cite. +Although the term was only used by ASDF hackers starting with ASDF 2, +the concept was there since the very beginning of ASDF 1, +but not clearly articulated.} + +In this chapter, we describe ASDF's object-oriented protocol, the +classes that make it up, and the generic functions on those classes. +These generic functions often take both an operation and a component as +arguments: much of the power and configurability of ASDF is provided by +this use of CLOS's multiple dispatch. +We will describe the built-in component and operation classes, and +explain how to extend the ASDF protocol by defining new classes and +methods for ASDF's generic functions. +We will also describe the many @emph{hooks} that can be configured to +customize the behavior of existing @emph{functions}. + +@c FIXME: Swap operations and components. @menu * Operations:: * Components:: +* Dependencies:: * Functions:: @end menu @@ -1782,8 +1813,8 @@ discuss these in turn below. Operations are invoked on systems via @code{operate}. @anchor{operate} -@deffn {Generic function} @code{operate} @var{operation} @var{system} @Arest @var{initargs} @Akey @code{force} @code{force-not} @code{verbose} @AallowOtherKeys -@deffnx {Generic function} @code{oos} @var{operation} @var{system} @Arest @var{initargs} @Akey @AallowOtherKeys +@deffn {Generic function} @code{operate} @var{operation} @var{system} @Arest@ @var{initargs} @Akey@ @code{force} @code{force-not} @code{verbose} @AallowOtherKeys +@deffnx {Generic function} @code{oos} @var{operation} @var{system} @Arest@ @var{initargs} @Akey@ @AallowOtherKeys @code{operate} invokes @var{operation} on @var{system}. @code{oos} is a synonym for @code{operate}. @@ -2162,7 +2193,7 @@ in which case you could have this method return @code{t}. Operations that print output should send that output to the standard CL stream @code{*standard-output*}, as the Lisp compiler and loader do. -@node Components, Functions, Operations, The object model of ASDF +@node Components, Dependencies, Operations, The object model of ASDF @comment node-name, next, previous, up @section Components @cindex component @@ -2171,6 +2202,15 @@ CL stream @code{*standard-output*}, as the Lisp compiler and loader do. @cindex component designator @vindex *system-definition-search-functions* +@c FIXME: merge the following two redundant paragraphs. +A @code{component} represents an individual source file or a group of source files, +and the things that get transformed into. +A @code{system} is a component at the top level of the component hierarchy. +A @code{source-file} is a component representing a single source-file +and the successive output files into which it is transformed. +A @code{module} is an intermediate component itself grouping several other components, +themselves source-files or further modules. + A @dfn{component} represents a source file or (recursively) a collection of components. A @dfn{system} is (roughly speaking) a top-level component @@ -2185,7 +2225,7 @@ is either a component itself, or a string or symbol, or a list of designators. -@defun find-system system-designator @Aoptional (error-p t) +@defun find-system system-designator @Aoptional@ (error-p t) Given a system designator, @code{find-system} finds and returns a system. If no system is found, an error of type @@ -2584,12 +2624,47 @@ The new component type is used in a @code{defsystem} form in this way: ) @end lisp -@node Functions, , Components, The object model of ASDF +@node Dependencies, Functions, Components, The object model of ASDF +@section Dependencies +@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 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: +the requiring action @code{depends-on} the completion of all required actions +before it may itself be @code{perform}ed. + +Using the @code{defsystem} syntax, users may easily express +direct dependencies along the graph of the object hierarchy: +between a component and its parent, its children, and its siblings. +By defining custom CLOS methods, you can express more elaborate dependencies as you wish. +Most common operations, such as @code{load-op}, @code{compile-op} or @code{load-source-op} +are automatically propagate ``downward'' the component hierarchy and are ``covariant'' with it: +to act the operation on the parent module, you must first act it on all the children components, +with the action on the parent being parent of the action on each child. +Other operations, such as @code{prepare-op} and @code{prepare-source-op} +(introduced in ASDF 3) are automatically propagated ``upward'' the component hierarchy +and are ``contravariant'' with it: +to perform the operation of preparing for compilation of a child component, +you must perform the operation of preparing for compilation of its parent component, and so on, +ensuring that all the parent's dependencies are (compiled and) loaded +before the child component may be compiled and loaded. +Yet other operations, such as @code{test-op} or @code{load-fasl-op} +remain at the system level, and are not propagated along the hierarchy, +but instead do something global on the system. + + +@node Functions, , Dependencies, The object model of ASDF @comment node-name, next, previous, up @section Functions -@findex version-satisfies -@deffn version-satisfies @var{version} @var{version-spec} +@c FIXME: this does not belong here.... +@defun version-satisfies @var{version} @var{version-spec} Does @var{version} satisfy the @var{version-spec}. A generic function. ASDF provides built-in methods for @var{version} being a @code{component} or @code{string}. @var{version-spec} should be a string. @@ -2941,6 +3016,10 @@ alone in its directory with the following contents: (:tree "/home/fare/cl/") @end example +@menu +* The :here directive:: +@end menu + @node The :here directive, , Configuration Directories, Configuration Directories @subsection The :here directive @@ -3062,7 +3141,7 @@ The specified functions are exported from your build system's package. Thus for ASDF the corresponding functions are in package ASDF, and for XCVB the corresponding functions are in package XCVB. -@defun initialize-source-registry @Aoptional PARAMETER +@defun initialize-source-registry @Aoptional@ PARAMETER will read the configuration and initialize all internal variables. You may extend or override configuration from the environment and configuration files @@ -3087,7 +3166,7 @@ and for XCVB the corresponding functions are in package XCVB. where to look for systems not yet defined. @end defun -@defun ensure-source-registry @Aoptional PARAMETER +@defun ensure-source-registry @Aoptional@ PARAMETER checks whether a source registry has been initialized. If not, initialize it with the given @var{PARAMETER}. @end defun @@ -3365,7 +3444,7 @@ as configured by the system distributor, or by default. Nevertheless, if you are a fan of @code{ASDF-Binary-Locations}, we provide a limited emulation mode: -@defun enable-asdf-binary-locations-compatibility @Akey centralize-lisp-binaries default-toplevel-directory include-per-user-information map-all-source-files source-to-target-mappings +@defun enable-asdf-binary-locations-compatibility @Akey@ centralize-lisp-binaries default-toplevel-directory include-per-user-information map-all-source-files source-to-target-mappings This function will initialize the new @code{asdf-output-translations} facility in a way that emulates the behavior of the old @code{ASDF-Binary-Locations} facility. Where you would previously set global variables @@ -3609,7 +3688,7 @@ To explicitly flush any information cached by the system, use the API below. The specified functions are exported from package ASDF. -@defun initialize-output-translations @Aoptional PARAMETER +@defun initialize-output-translations @Aoptional@ PARAMETER will read the configuration and initialize all internal variables. You may extend or override configuration from the environment and configuration files @@ -3640,7 +3719,7 @@ The specified functions are exported from package ASDF. where to look for systems not yet defined. @end defun -@defun ensure-output-translations @Aoptional PARAMETER +@defun ensure-output-translations @Aoptional@ PARAMETER checks whether output translations have been initialized. If not, initialize them with the given @var{PARAMETER}. This function will be called before any attempt to operate on a system. @@ -3737,7 +3816,7 @@ useful for system definition and development. * Some Utility Functions:: @end menu -@node Controlling file compilation, , Miscellaneous additional functionality, Miscellaneous additional functionality +@node Controlling file compilation, Some Utility Functions, Miscellaneous additional functionality, Miscellaneous additional functionality @section Controlling file compilation @cindex :around-compile @cindex around-compile keyword @@ -3950,7 +4029,7 @@ This might matter, for instance, in meta-data about author's names. These functions are exported by ASDF for your convenience. @anchor{system-relative-pathname} -@defun system-relative-pathname system name @Akey type +@defun system-relative-pathname system name @Akey@ type It's often handy to locate a file relative to some system. The @code{system-relative-pathname} function meets this need. @@ -4013,7 +4092,7 @@ with respect to its own code, and what it does is ridiculously complex; look at the beginning of @file{asdf.lisp} to see what it does. @end defun -@defun register-preloaded-system name @Arest keys +@defun register-preloaded-system name @Arest@ keys A system with name @var{name}, created by @code{make-instance} with extra keys @var{keys} (e.g. @code{:version}), @@ -4029,7 +4108,7 @@ and want to register systems so that dependencies will work uniformly whether you're using your software from source or from fasl. @end defun -@defun run-shell-command control-string @Arest args +@defun run-shell-command control-string @Arest@ args This function is obsolete and present only for the sake of backwards-compatibility: ``If it's not backwards, it's not compatible''. We @emph{strongly} discourage its use. @@ -4060,7 +4139,7 @@ UIOP provides many, many more utility functions, and we recommend you read its README and sources for more information. -@defun parse-unix-namestring name @Akey type defaults dot-dot ensure-directory @AallowOtherKeys +@defun parse-unix-namestring name @Akey@ type defaults dot-dot ensure-directory @AallowOtherKeys Coerce NAME into a PATHNAME using standard Unix syntax. Unix syntax is used whether or not the underlying system is Unix; @@ -4104,7 +4183,7 @@ even though the OS may not be Unixish, we recommend you use @code{:want-relative to throw an error if the pathname is absolute @end defun -@defun merge-pathnames* specified @Aoptional defaults +@defun merge-pathnames* specified @Aoptional@ defaults This function is a replacement for @code{merge-pathnames} that uses the host and device from the @var{defaults} rather than the @var{specified} pathname when the latter @@ -4114,7 +4193,7 @@ of the absolute pathnames they are relative to. @end defun -@defun subpathname pathname subpath @Akey type +@defun subpathname pathname subpath @Akey@ type This function takes a @var{pathname} and a @var{subpath} and a @var{type}. If @var{subpath} is already a @code{pathname} object (not namestring), @@ -4128,13 +4207,13 @@ We strongly encourage the use of this function for portably resolving relative pathnames in your code base. @end defun -@defun subpathname* pathname subpath @Akey type +@defun subpathname* pathname subpath @Akey@ type This function returns @code{nil} if the base @var{pathname} is @code{nil}, otherwise acts like @code{subpathname}. @end defun -@defun run-program command @Akey ignore-error-status force-shell input output error-output +@defun run-program command @Akey@ ignore-error-status force-shell input output error-output if-input-does-not-exist if-output-exists if-error-output-exists element-type external-format @AallowOtherKeys @@ -4215,7 +4294,7 @@ See the source code for more documentation. @end defun -@defun slurp-input-stream processor input-stream @Akey +@defun slurp-input-stream processor input-stream @Akey@ It's a generic function of two arguments, a target object and an input stream, and accepting keyword arguments. -- GitLab