X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=contrib%2Fasdf%2Fasdf.texinfo;h=f506edb5ab8e36e8df2a7e9e0f59b86ff34d89f5;hb=6d9e2243954872457115bbb9ac1ecb1d161acced;hp=e5c3edccc3682000f68a347b9ce702a4356f62fc;hpb=09bce61cb338ab75fec8008c9727e90cb6e4fc98;p=sbcl.git diff --git a/contrib/asdf/asdf.texinfo b/contrib/asdf/asdf.texinfo index e5c3edc..f506edb 100644 --- a/contrib/asdf/asdf.texinfo +++ b/contrib/asdf/asdf.texinfo @@ -35,11 +35,11 @@ for Common Lisp programs and libraries. You can find the latest version of this manual at @url{http://common-lisp.net/project/asdf/asdf.html}. -ASDF Copyright @copyright{} 2001-2011 Daniel Barlow and contributors. +ASDF Copyright @copyright{} 2001-2012 Daniel Barlow and contributors. -This manual Copyright @copyright{} 2001-2011 Daniel Barlow and contributors. +This manual Copyright @copyright{} 2001-2012 Daniel Barlow and contributors. -This manual revised @copyright{} 2009-2011 Robert P. Goldman and Francois-Rene Rideau. +This manual revised @copyright{} 2009-2012 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 @@ -197,6 +197,7 @@ so you may more easily modify it, we recommend clbuild. @vindex *central-registry* @cindex link farm @findex load-system +@findex require-system @findex compile-system @findex test-system @cindex system directory designator @@ -219,10 +220,11 @@ You can usually load this copy using Common Lisp's @code{require} function: As of the writing of this manual, the following implementations provide ASDF 2 this way: -abcl allegro ccl clisp cmucl ecl sbcl xcl. -The following implementations don't provide it yet but will in a future release: -lispworks scl. -The following implementations are obsolete and most probably will never bundle it: +abcl allegro ccl clisp cmucl ecl lispworks sbcl xcl. +The following implementation doesn't provide it yet but will in a future release: +scl. +The following implementations are obsolete, not actively maintained, +and most probably will never bundle it: cormancl gcl genera mcl. If the implementation you are using doesn't provide ASDF 2, @@ -517,7 +519,7 @@ control what directories are added to the ASDF search path. @section Configuring where ASDF stores object files -@findex clear-output-locations +@findex clear-output-translations ASDF lets you configure where object files will be stored. Sensible defaults are provided and @@ -596,6 +598,33 @@ to just delegate this functionality to ASDF. @node Using ASDF, Defining systems with defsystem, Configuring ASDF, Top @comment node-name, next, previous, up + +@section Resetting Configuration + +When you dump and restore an image, or when you tweak your configuration, +you may want to reset the ASDF configuration. +For that you may use the following function: + +@defun clear-configuration + undoes any ASDF configuration, + regarding source-registry or output-translations. +@end defun + +If you use SBCL, CMUCL or SCL, you may use this snippet +so that the ASDF configuration be cleared automatically as you dump an image: + +@example +#+(or cmu sbcl scl) +(pushnew 'clear-configuration + #+(or cmu scl) ext:*before-save-initializations* + #+sbcl sb-ext:*save-hooks*) +@end example + +For compatibility with all Lisp implementations, however, +you might want instead your build script to explicitly call +@code{(asdf:clear-configuration)} at an appropriate moment before dumping. + + @chapter Using ASDF @section Loading a system @@ -640,6 +669,8 @@ which is reported not to work on some implementations ASDF provides three commands for the most common system operations: @code{load-system}, @code{compile-system} or @code{test-system}. +It also provides @code{require-system}, a version of @code{load-system} +that skips trying to update systems that are already loaded. Because ASDF is an extensible system for defining @emph{operations} on @emph{components}, @@ -869,6 +900,8 @@ For more details on what these methods do, @pxref{Operations} in system-definition := ( defsystem system-designator @var{system-option}* ) system-option := :defsystem-depends-on system-list + | :weakly-depends-on @var{system-list} + | :class class-name (see discussion below) | module-option | option @@ -932,7 +965,27 @@ the current package. So a component type @code{my-component-type}, in the current package @code{my-system-asd} can be specified as @code{:my-component-type}, or @code{my-component-type}. +@subsection System class names + +A system class name will be looked up in the same way as a Component +type (see above). Typically, one will not need to specify a system +class name, unless using a non-standard system class defined in some +ASDF extension, typically loaded through @code{DEFSYSTEM-DEPENDS-ON}, +see below. For such class names in the ASDF package, we recommend that +the @code{:class} option be specified using a keyword symbol, such as + +@example +:class :MY-NEW-SYSTEM-SUBCLASS +@end example + +This practice will ensure that package name conflicts are avoided. +Otherwise, the symbol @code{MY-NEW-SYSTEM-SUBCLASS} will be read into +the current package @emph{before} it has been exported from the ASDF +extension loaded by @code{:defsystem-depends-on}, causing a name +conflict in the current package. + @subsection Defsystem depends on +@cindex :defsystem-depends-on The @code{:defsystem-depends-on} option to @code{defsystem} allows the programmer to specify another ASDF-defined system or set of systems that @@ -940,6 +993,22 @@ must be loaded @emph{before} the system definition is processed. Typically this is used to load an ASDF extension that is used in the system definition. +@subsection Weakly depends on +@cindex :weakly-depends-on + +The @code{:weakly-depends-on} option to @code{defsystem} allows the +programmer to specify another ASDF-defined system or set of systems that +ASDF should @emph{try} to load, but need not load in order to be +successful. Typically this is used if there are a number of systems +that, if present, could provide additional functionality, but which are +not necessary for basic function. + +Currently, although it is specified to be an option only to +@code{defsystem}, this option is accepted at any component, but it probably +only makes sense at the @code{defsystem} level. Programmers are cautioned not +to use this component option except at the @code{defsystem} level, as +this anomalous behavior may be removed without warning. + @subsection Pathname specifiers @cindex pathname specifiers @@ -1210,6 +1279,7 @@ and @emph{operations}, the actions that can be performed on a system. @menu * Operations:: * Components:: +* Functions:: @end menu @node Operations, Components, The object model of ASDF, The object model of ASDF @@ -1410,7 +1480,7 @@ if you don't like the default one 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, , Operations, The object model of ASDF +@node Components, Functions, Operations, The object model of ASDF @comment node-name, next, previous, up @section Components @cindex component @@ -1573,11 +1643,14 @@ The syntax is approximately @verbatim (this-op {(other-op required-components)}+) -required-components := component-name +simple-component-name := string + | symbol + +required-components := simple-component-name | (required-components required-components) -component-name := string - | (:version string minimum-version-object) +component-name := simple-component-name + | (:version simple-component-name minimum-version-object) @end verbatim Side note: @@ -1788,6 +1861,25 @@ The new component type is used in a @code{defsystem} form in this way: ) @end lisp +@node Functions, , Components, The object model of ASDF +@comment node-name, next, previous, up +@section Functions +@findex version-satisfies + +@deffn 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. + +In the wild, we typically see version numbering only on components of +type @code{system}. + +For more information about how @code{version-satisfies} interprets +version strings and specifications, @pxref{The defsystem grammar} and +@ref{Common attributes of components}. +@end deffn + @node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top @comment node-name, next, previous, up @chapter Controlling where ASDF searches for systems @@ -1993,7 +2085,7 @@ RELATIVE-COMPONENT-DESIGNATOR := STRING | ;; relative directory pathname as interpreted by coerce-pathname. ;; In output translations, if last component, **/*.*.* is added PATHNAME | ;; pathname; unless last component, directory is assumed. - :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.49-linux-x64 + :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64 :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl :DEFAULT-DIRECTORY | ;; a relativized version of the default directory :*/ | ;; any direct subdirectory (since ASDF 2.011.4) @@ -2774,10 +2866,191 @@ The valid values for these variables are @comment node-name, next, previous, up @chapter Miscellaneous additional functionality -@emph{FIXME: Add discussion of @code{run-shell-command}? Others?} - ASDF includes several additional features that are generally -useful for system definition and development. These include: +useful for system definition and development. + +@section Controlling file compilation + +When declaring a component (system, module, file), +you can specify a keyword argument @code{:around-compile function}. +If left unspecified, +the value will be inherited from the parent component if any, +or with a default of @code{nil} +if no value is specified in any transitive parent. + +The argument must be a either @code{nil}, a fbound symbol, +a lambda-expression (e.g. @code{(lambda (thunk) ...(funcall thunk) ...)}) +a function object (e.g. using @code{#.#'} but that's discouraged +because it prevents the introspection done by e.g. asdf-dependency-grovel), +or a string that when read yields a symbol or a lambda-expression. +@code{nil} means the normal compile-file function will be called. +A non-nil value designates a function of one argument +that will be called with a thunk for calling +the compile-file function with proper arguments. + +Note that by using a string, you may reference +a function, symbol and/or package +that will only be created later during the build, but +isn't yet present at the time the defsystem form is evaluated. +However, if your entire system is using such a hook, you may have to +explicitly override the hook with @code{nil} for all the modules and files +that are compiled before the hook is defined. + +Using this hook, you may achieve such effects as: +locally renaming packages, +binding @var{*readtables*} and other syntax-controlling variables, +handling warnings and other conditions, +proclaiming consistent optimization settings, +saving code coverage information, +maintaining meta-data about compilation timings, +setting gensym counters and PRNG seeds and other sources of non-determinism, +overriding the source-location and/or timestamping systems, +checking that some compile-time side-effects were properly balanced, +etc. + +Note that there is no around-load hook. This is on purpose. +Some implementations such as ECL or GCL link object files, +which allows for no such hook. +Other implementations allow for concatenating FASL files, +which doesn't allow for such a hook either. +We aim to discourage something that's not portable, +and has some dubious impact on performance and semantics +even when it is possible. +Things you might want to do with an around-load hook +are better done around-compile, +though it may at times require some creativity +(see e.g. the @code{package-renaming} system). + + +@section Controlling source file character encoding + +Starting with ASDF 2.21, components accept a @code{:encoding} option. +By default, only @code{:default}, @code{:utf-8} +and @code{:autodetect} are accepted. +@code{:autodetect} is the default, and calls +@code{*encoding-detection-hook*} which by default always returns +@code{*default-encoding*} which itself defaults to @code{:default}. +In other words, there now are plenty of extension hooks, but +by default ASDF follows the backwards compatible behavior +of using whichever @code{:default} encoding your implementation uses, +which itself may or may not vary based on environment variables +and other locale settings. +In practice this means that only source code that only uses ASCII +is guaranteed to be read the same on all implementations +independently from any user setting. + +Additionally, for backward-compatibility with older versions of ASDF +and/or with implementations that do not support unicode and its many encodings, +you may want to use +the reader conditionals @code{#+asdf-unicode #+asdf-unicode} +to protect any @code{:encoding @emph{encoding}} statement +as @code{:asdf-unicode} will be present in @code{*features*} +only if you're using a recent ASDF +on an implementation that supports unicode. +We recommend that you avoid using unprotected @code{:encoding} specifications +until after ASDF 2.21 becomes widespread, hopefully by the end of 2012. + +While it offers plenty of hooks for extension, +and one such extension is being developed (see below), +ASDF itself only recognizes one encoding beside @code{:default}, +and that is @code{:utf-8}, which is the @emph{de facto} standard, +already used by the vast majority of libraries that use more than ASCII. +On implementations that do not support unicode, +the feature @code{:asdf-unicode} is absent, and +the @code{:default} external-format is used +to read even source files declared as @code{:utf-8}. +On these implementations, non-ASCII characters +intended to be read as one CL character +may thus end up being read as multiple CL characters. +In most cases, this shouldn't affect the software's semantics: +comments will be skipped just the same, strings with be read and printed +with slightly different lengths, symbol names will be accordingly longer, +but none of it should matter. +But a few systems that actually depend on unicode characters +may fail to work properly, or may work in a subtly different way. +See for instance @code{lambda-reader}. + +We invite you to embrace UTF-8 +as the encoding for non-ASCII characters starting today, +even without any explicit specification in your @code{.asd} files. +Indeed, on some implementations and configurations, +UTF-8 is already the @code{:default}, +and loading your code may cause errors if it is encoded in anything but UTF-8. +Therefore, even with the legacy behavior, +non-UTF-8 is guaranteed to break for some users, +whereas UTF-8 is pretty much guaranteed not to break anywhere +(provided you do @emph{not} use a BOM), +although it might be read incorrectly on some implementations. +In the future, we intend to make @code{:utf-8} +the default value of @code{*default-encoding*}, +to be enforced everywhere, so at least the code is guaranteed +to be read correctly everywhere it can be. + +If you need non-standard character encodings for your source code, +use the extension system @code{asdf-encodings}, by specifying +@code{:defsystem-depends-on (:asdf-encodings)} in your @code{defsystem}. +This extension system will register support for more encodings using the +@code{*encoding-external-format-hook*} facility, +so you can explicitly specify @code{:encoding :latin1} +in your @code{.asd} file. +Using the @code{*encoding-detection-hook*} it will also +eventually implement some autodetection of a file's encoding +from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration, +or otherwise based on an analysis of octet patterns in the file. +At this point, asdf-encoding only supports the encodings +that are supported as part of your implementation. +Since the list varies depending on implementations, +we once again recommend you use @code{:utf-8} everywhere, +which is the most portable (next is @code{:latin1}). + +If you're not using a version of Quicklisp that has it, +you may get the source for @code{asdf-encodings} using git: +@kbd{git clone git://common-lisp.net/projects/asdf/asdf-encodings.git} +or +@kbd{git clone ssh://common-lisp.net/project/asdf/git/asdf-encodings.git}. +You can also browse the repository on +@url{http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git}. + +In the future, we intend to change the default @code{*default-encoding*} +to @code{:utf-8}, which is already the de facto standard +for most libraries that use non-ASCII characters: +utf-8 works everywhere and was backhandedly enforced by +a lot of people using SBCL and utf-8 and sending reports to authors +so they make their packages compatible. +A survey showed only about a handful few libraries +are incompatible with non-UTF-8, and then, only in comments, +and we believe that authors will adopt UTF-8 when prompted. +See the April 2012 discussion on the asdf-devel mailing-list. +For backwards compatibility with users who insist on a non-UTF-8 encoding, +but cannot immediately transition to using @code{asdf-encodings} +(maybe because it isn't ready), it will still be possible to use +the @code{:encoding :default} option in your @code{defsystem} form +to restore the behavior of ASDF 2.20 and earlier. +This shouldn't be required in libraries, +because user pressure as mentioned above will already have pushed +library authors towards using UTF-8; +but authors of end-user programs might care. + +When you use @code{asdf-encodings}, any further loaded @code{.asd} file +will use the autodetection algorithm to determine its encoding; +yet if you depend on this detection happening, +you may want to explicitly load @code{asdf-encodings} early in your build, +for by the time you can use @code{:defsystem-depends-on}, +it is already too late to load it. +In practice, this means that the @code{*default-encoding*} +is usually used for @code{.asd} files. +Currently, this defaults to @code{:default} for backwards compatibility, +and that means that you shouldn't rely on non-ASCII characters in a .asd file. +Since component (path)names are the only real data in these files, +and non-ASCII characters are not very portable for file names, +this isn't too much of an issue. +We still encourage you to use either plain ASCII or UTF-8 +in @code{.asd} files, +as we intend to make @code{:utf-8} the default encoding in the future. +This might matter, for instance, in meta-data about author's names. + + +@section Miscellaneous Exported Functions @defun coerce-pathname name @&key type defaults @@ -2872,6 +3145,33 @@ 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 run-shell-command + +This function is obsolete and present only for the sake of backwards-compatibility: +``If it's not backwards, it's not compatible''. We strongly discourage its use. +Its current behavior is only well-defined on Unix platforms +(which include MacOS X and cygwin). On Windows, anything goes. + +Instead we recommend the use of such a function as +@code{xcvb-driver:run-program/} +from the @code{xcvb-driver} system that is distributed with XCVB: +@url{http://common-lisp.net/project/xcvb}. +It's only alternative that supports +as many implementations and operating systems as ASDF does, +and provides well-defined behavior outside Unix (i.e. on Windows). +(The only unsupported exception is Genera, since on it +@code{run-shell-command} doesn't make sense anyway on that platform). + +@code{run-shell-command} takes as arguments a @code{format} control-string +and arguments to be passed to @code{format} after this control-string +to produce a string. +This string is a command that will be evaluated with a POSIX shell if possible; +yet, on Windows, some implementations will use CMD.EXE, +while others (like SBCL) will make an attempt at invoking a POSIX shell +(and fail if it is not present). +@end defun + + @node Getting the latest version, FAQ, Miscellaneous additional functionality, Top @comment node-name, next, previous, up @chapter Getting the latest version @@ -3545,6 +3845,8 @@ you also define the following method: "lis") @end lisp +@comment FIXME: Add a FAQ about how to use a new system class... + @node TODO list, Inspiration, FAQ, Top @comment node-name, next, previous, up