diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index e9e335af6f55ccd6917bc17241a42a218826a5b4..5f09a9f5a73d17de815334433cd9108ea3450d69 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -36,11 +36,11 @@ for Common Lisp programs and libraries. You can find the latest version of this manual at @url{https://common-lisp.net/project/asdf/asdf.html}. -ASDF Copyright @copyright{} 2001-2015 Daniel Barlow and contributors. +ASDF Copyright @copyright{} 2001-2016 Daniel Barlow and contributors. -This manual Copyright @copyright{} 2001-2015 Daniel Barlow and contributors. +This manual Copyright @copyright{} 2001-2016 Daniel Barlow and contributors. -This manual revised @copyright{} 2009-2015 Robert P. Goldman and Francois-Rene Rideau. +This manual revised @copyright{} 2009-2016 Robert P. Goldman and Francois-Rene Rideau. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -678,6 +678,11 @@ may already have configured system-managed libraries for you. @c FIXME: this section should be moved elsewhere. The novice user @c should not be burdened with it. [2014/02/27:rpg] +Novices may skip this section. +@c ``Experts may read it then proceed to ...'' +@c some better section explaining +@c *central-registry* vs source-registry vs *system-definition-search-functions*, +@c and .../asdf/tools/cl-source-registry-cache.lisp The old way to configure ASDF to find your systems is by @code{push}ing directory pathnames onto the variable @@ -702,7 +707,7 @@ search forward for For example, let's say you want ASDF to find the @file{.asd} file @file{/home/me/src/foo/foo.asd}. -In your lisp initialization file, you could have the following: +In your Lisp initialization file, you could have the following: @lisp (require "asdf") @@ -726,7 +731,7 @@ The variable @code{asdf:*central-registry*} is thus a list of ``system directory designators''. A @dfn{system directory designator} is a form which will be evaluated whenever a system is to be found, -and must evaluate to a directory to look in (or @code{NIL}). +and must evaluate to a directory to look in (or @code{nil}). By ``directory'', we mean ``designator for a pathname with a non-empty DIRECTORY component''. } @@ -1441,6 +1446,7 @@ other-component-type := symbol-by-name # which is used in :in-order-to dependency-def := simple-component-name | ( :feature @var{feature-expression} dependency-def ) + # (@pxref{The defsystem grammar,,Feature dependencies}) | ( :version simple-component-name version-specifier ) | ( :require module-name ) @@ -1459,8 +1465,6 @@ pathname-specifier := pathname | string | symbol method-form := (operation-name qual lambda-list @Arest{} body) qual := method qualifier? -component-dep-fail-option := :fail | :try-next | :ignore - feature-expression := keyword | (:and @var{feature-expression}*) | (:or @var{feature-expression}*) @@ -1684,6 +1688,25 @@ rather than @code{#+@emph{implementation-name}} to only depend on the specified module on the specific implementation that provides it. @xref{if-feature-option}. +@subsection Feature dependencies +@cindex :feature dependencies + +A feature dependency is of the form +@code{(:feature @var{feature-expression} @var{dependency})} +If the @var{feature-expression} is satisfied by the running lisp at the +time the system definition is parsed, then the @var{dependency} will be +added to the system's dependencies. If the @var{feature-expression} is +@emph{not} satisfied, then the feature dependency form is ignored. + +Note that this means that @code{:feature} @strong{cannot} be used to +enforce a feature dependency for the system in question. I.e., it +cannot be used to require that a feature hold in order for the system +definition to be loaded. E.g., one cannot use @code{(:feature :sbcl)} +to require that a system only be used on SBCL. + +Feature dependencies are not to be confused with the obsolete +feature requirement (@pxref{The defsystem grammar,,feature requirement}), or +with @code{if-feature}. @subsection Using logical pathnames @cindex logical pathnames @@ -1843,13 +1866,6 @@ been performed. This option was added in ASDF 3. For more information, @xref{required-features, Required features}. -@subsection if-component-dep-fails option -@cindex :if-component-dep-fails component option -This option was removed in ASDF 3. -Its semantics was limited in purpose and dubious to explain, -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. Please do not use it. In most cases, @code{:if-feature} (@pxref{if-feature-option}) will provide @@ -2004,7 +2020,7 @@ where the @file{.asd} file resides. 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, allowing programmers to add new behaviours to ASDF. +follow an extensible protocol, allowing programmers to add new behaviours 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{asdf-jar} supports creating Java JAR archives in ABCL. @@ -2699,9 +2715,9 @@ 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}, +@var{foundp} will be @code{t}, @item -@var{found-system} will be @code{NIL}, +@var{found-system} will be @code{nil}, @item @var{pathname} will be @code{#p"/current/path/to/foo.asd"}, @item @@ -4753,14 +4769,14 @@ while others (like SBCL) will make an attempt at invoking a POSIX shell @section Some Utility Functions The below functions are not exported by ASDF itself, but by UIOP, available since ASDF 3. -Some of them have precursors in ASDF 2, but we recommend -you rely on ASDF 3 for active developments. +Some of them have precursors in ASDF 2, but we recommend that for active developments, +you should rely on the package UIOP as included in ASDF 3. UIOP provides many, many more utility functions, and we recommend -you read its README and sources for more information. +you read its @file{README.md} and sources for more information. @defun parse-unix-namestring name @Akey{} type defaults dot-dot ensure-directory @AallowOtherKeys -Coerce NAME into a PATHNAME using standard Unix syntax. +Coerce @var{name} into a @var{pathname} using standard Unix syntax. Unix syntax is used whether or not the underlying system is Unix; on non-Unix systems it is only usable for relative pathnames. @@ -4949,7 +4965,7 @@ which defaults to @code{0}, extracting the first line. A number will extract the corresponding line. See the documentation for @code{uiop:access-at}. -@item If the object is @code{:forms}, the content is captured as a list of S-expressions, +@item If the object is @code{:forms}, the content is captured as a list of s-expressions, as read by the Lisp reader. If the @var{count} argument is provided, it is a maximum count of lines to be read.