X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=contrib%2Fasdf%2Fasdf.texinfo;h=f506edb5ab8e36e8df2a7e9e0f59b86ff34d89f5;hb=1483e561a090d9f07687da27f8dd10fcd4152be1;hp=ff7636d6e0d7bbee0d1ce3e430407a154594712a;hpb=82f9c527cb607ccd19e5b24261dfe9af7b1ba72e;p=sbcl.git diff --git a/contrib/asdf/asdf.texinfo b/contrib/asdf/asdf.texinfo index ff7636d..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 @@ -172,14 +172,23 @@ the ASDF internals and how to extend ASDF. @emph{Nota Bene}: We have released ASDF 2.000 on May 31st 2010. Subsequent releases of ASDF 2 have since then been included -in all actively maintained CL implementations that bundle ASDF, -and made to work with all actively used CL implementations and a few more. +in all actively maintained CL implementations that used to bundle ASDF 1, +plus some implementations that didn't use to, +and has been made to work with all actively used CL implementations and a few more. @xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}. Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 on the fly. For this reason, we have stopped supporting ASDF 1; if you are using ASDF 1 and are experiencing any kind of issues or limitations, we recommend you upgrade to ASDF 2 ---- and we explain how to do it. @xref{Loading ASDF}. +--- and we explain how to do that. @xref{Loading ASDF}. + +Also note that ASDF is not to be confused with ASDF-Install. +ASDF-Install is not part of ASDF, but a separate piece of software. +ASDF-Install is also unmaintained and obsolete. +We recommend you use Quicklisp instead, +which works great and is being actively maintained. +If you want to download software from version control instead of tarballs, +so you may more easily modify it, we recommend clbuild. @node Loading ASDF, Configuring ASDF, Introduction, Top @@ -188,6 +197,7 @@ we recommend you upgrade to ASDF 2 @vindex *central-registry* @cindex link farm @findex load-system +@findex require-system @findex compile-system @findex test-system @cindex system directory designator @@ -205,15 +215,16 @@ Many Lisp implementations include a copy of ASDF. You can usually load this copy using Common Lisp's @code{require} function: @lisp -(require :asdf) +(require "asdf") @end lisp 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 might 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, @@ -222,6 +233,10 @@ If that implementation is still actively maintained, you may also send a bug report to your Lisp vendor and complain about their failing to provide ASDF. +NB: all implementations except clisp also accept +@code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}. +For portability's sake, you probably want to use @code{(require "asdf")}. + @section Checking whether ASDF is loaded @@ -270,7 +285,7 @@ configure ASDF as usual (see @pxref{Configuring ASDF} below), and upgrade with: @lisp -(require :asdf) +(require "asdf") (asdf:load-system :asdf) @end lisp @@ -278,7 +293,7 @@ If on the other hand, your implementation only provides an old ASDF, you will require a special configuration step and an old-style loading: @lisp -(require :asdf) +(require "asdf") (push #p"@var{/path/to/new/asdf/}" asdf:*central-registry*) (asdf:oos 'asdf:load-op :asdf) @end lisp @@ -375,14 +390,15 @@ The default location for a user to install Common Lisp software is under If you install software there, you don't need further configuration. If you're installing software yourself at a location that isn't standard, you have to tell ASDF where you installed it. See below. -If you're using some tool to install software, +If you're using some tool to install software (e.g. Quicklisp), the authors of that tool should already have configured ASDF. The simplest way to add a path to your search path, say @file{/home/luser/.asd-link-farm/} is to create the directory @file{~/.config/common-lisp/source-registry.conf.d/} -and there create a file with any name of your choice but the type @file{conf}, +and there create a file with any name of your choice, +and with the type @file{conf}, for instance @file{42-asd-link-farm.conf} containing the line: @@ -417,7 +433,7 @@ between the machine where you save it at the time you save it and the machine you resume it at the time you resume it. -@section Configuring ASDF to find your systems -- old style +@section Configuring ASDF to find your systems --- old style The old way to configure ASDF to find your systems is by @code{push}ing directory pathnames onto the variable @@ -442,7 +458,7 @@ search forward for For instance, if you wanted ASDF to find the @file{.asd} file @file{/home/me/src/foo/foo.asd} your initialization script -could after it loads ASDF with @code{(require :asdf)} +could after it loads ASDF with @code{(require "asdf")} configure it with: @lisp @@ -484,7 +500,8 @@ instead of pushing each of the many involved directories to the @code{asdf:*central-registry*}. ASDF knows how to follow such @emph{symlinks} to the actual file location when resolving the paths of system components -(on Windows, you can use Windows shortcuts instead of POSIX symlinks). +(on Windows, you can use Windows shortcuts instead of POSIX symlinks; +if you try aliases under MacOS, we are curious to hear about your experience). For example, if @code{#p"/home/me/cl/systems/"} (note the trailing slash) is a member of @code{*central-registry*}, you could set up the @@ -502,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 @@ -581,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 @@ -625,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}, @@ -650,7 +696,7 @@ To use ASDF: @itemize @item Load ASDF itself into your Lisp image, either through -@code{(require :asdf)} or else through +@code{(require "asdf")} or else through @code{(load "/path/to/asdf.lisp")}. @item @@ -854,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 @@ -917,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 @@ -925,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 @@ -984,7 +1068,7 @@ or @code{#.(make-pathname ...)}. Note however, that @code{#p...} is a shorthand for @code{#.(parse-namestring ...)} and that the behavior of @code{parse-namestring} is completely non-portable, unless you are using Common Lisp @code{logical-pathname}s -(@pxref{The defsystem grammar,,Warning about logical pathnames}, below). +(@pxref{The defsystem grammar,,Using logical pathnames}, below). Pathnames made with @code{#.(make-pathname ...)} can usually be done more easily with the string syntax above. The only case that you really need a pathname object is to override @@ -1021,32 +1105,35 @@ API) and patch level. @xref{Common attributes of components}. -@subsection Warning about logical pathnames +@subsection Using logical pathnames @cindex logical pathnames -We recommend that you not use logical pathnames -in your asdf system definitions at this point, -but logical pathnames @emph{are} supported. +We do not generally recommend the use of logical pathnames, +especially not so to newcomers to Common Lisp. +However, we do support the use of logical pathnames by old timers, +when such is their preference. To use logical pathnames, you will have to provide a pathname object as a @code{:pathname} specifier to components that use it, using such syntax as @code{#p"LOGICAL-HOST:absolute;path;to;component.lisp"}. -You only have to specify such logical pathname for your system or -some top-level component. Sub-components' relative pathnames, specified -using the string syntax -for names, will be properly merged with the pathnames of their parents. +You only have to specify such logical pathname +for your system or some top-level component. +Sub-components' relative pathnames, +specified using the string syntax for names, +will be properly merged with the pathnames of their parents. The specification of a logical pathname host however is @emph{not} otherwise directly supported in the ASDF syntax for pathname specifiers as strings. The @code{asdf-output-translation} layer will -avoid trying to resolve and translate logical-pathnames. -The advantage of this is that you can define yourself what translations you want to use +avoid trying to resolve and translate logical pathnames. +The advantage of this is that +you can define yourself what translations you want to use with the logical pathname facility. -The disadvantage is that if you do not define such translations, any -system that uses logical pathnames will behave differently under +The disadvantage is that if you do not define such translations, +any system that uses logical pathnames will behave differently under asdf-output-translations than other systems you use. If you wish to use logical pathnames you will have to configure the @@ -1054,6 +1141,24 @@ translations yourself before they may be used. ASDF currently provides no specific support for defining logical pathname translations. +Note that the reasons we do not recommend logical pathnames are that +(1) there is no portable way to set up logical pathnames before they are used, +(2) logical pathnames are limited to only portably use +a single character case, digits and hyphens. +While you can solve the first issue on your own, +describing how to do it on each of fifteen implementations supported by ASDF +is more than we can document. +As for the second issue, mind that the limitation is notably enforced on SBCL, +and that you therefore can't portably violate the limitations +but must instead define some encoding of your own and add individual mappings +to name physical pathnames that do not fit the restrictions. +This can notably be a problem when your Lisp files are part of a larger project +in which it is common to name files or directories in a way that +includes the version numbers of supported protocols, +or in which files are shared with software written +in different programming languages where conventions include the use of +underscores, dots or CamelCase in pathnames. + @subsection Serial dependencies @cindex serial dependencies @@ -1174,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 @@ -1374,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 @@ -1537,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: @@ -1752,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 @@ -1863,7 +1991,7 @@ ASDF will first search for @code{.asd} files in the directories specified in @code{asdf:*central-registry*} before it searches in the source registry above. -@xref{Configuring ASDF,,Configuring ASDF to find your systems -- old style}. +@xref{Configuring ASDF,,Configuring ASDF to find your systems --- old style}. By default, @code{asdf:*central-registry*} will be empty. @@ -1902,9 +2030,9 @@ DIRECTIVE := (:tree DIRECTORY-PATHNAME-DESIGNATOR) | ;; override the defaults for exclusion patterns - (:exclude PATTERN ...) | + (:exclude EXCLUSION-PATTERN ...) | ;; augment the defaults for exclusion patterns - (:also-exclude PATTERN ...) | + (:also-exclude EXCLUSION-PATTERN ...) | ;; Note that the scope of a an exclude pattern specification is ;; the rest of the current configuration expression or file. @@ -1918,35 +2046,56 @@ REGULAR-FILE-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a file DIRECTORY-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a directory name PATHNAME-DESIGNATOR := - NULL | ;; Special: skip this entry. - ABSOLUTE-COMPONENT-DESIGNATOR | - (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) + NIL | ;; Special: skip this entry. + ABSOLUTE-COMPONENT-DESIGNATOR ;; see pathname DSL + +EXCLUSION-PATTERN := a string without wildcards, that will be matched exactly + against the name of a any subdirectory in the directory component + of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"} +@end example +Pathnames are designated using another DSL, +shared with the output-translations configuration DSL below. +The DSL is resolved by the function @code{asdf::resolve-location}, +to be documented and exported at some point in the future. + +@example ABSOLUTE-COMPONENT-DESIGNATOR := - STRING | ;; namestring (better be absolute or bust, directory assumed where applicable) + (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) | + STRING | ;; namestring (better be absolute or bust, directory assumed where applicable). + ;; In output-translations, directory is assumed and **/*.*.* added if it's last. + ;; On MCL, a MacOSX-style POSIX namestring (for MacOS9 style, use #p"..."); + ;; Note that none of the above applies to strings used in *central-registry*, + ;; which doesn't use this DSL: they are processed as normal namestrings. + ;; however, you can compute what you put in the *central-registry* + ;; based on the results of say (asdf::resolve-location "/Users/fare/cl/cl-foo/") PATHNAME | ;; pathname (better be an absolute path, or bust) + ;; In output-translations, unless followed by relative components, + ;; it better have appropriate wildcards, as in **/*.*.* :HOME | ;; designates the user-homedir-pathname ~/ :USER-CACHE | ;; designates the default location for the user cache - :SYSTEM-CACHE | ;; designates the default location for the system cache - :HERE ;; designates the location of the configuration file - ;; (or *default-pathname-defaults*, if invoked interactively) + :HERE | ;; designates the location of the configuration file + ;; (or *default-pathname-defaults*, if invoked interactively) + :ROOT ;; magic, for output-translations source only: paths that are relative + ;; to the root of the source host and device + ;; Not valid anymore: :SYSTEM-CACHE (was a security hazard) RELATIVE-COMPONENT-DESIGNATOR := - STRING | ;; namestring (directory assumed where applicable) - PATHNAME | ;; pathname - :IMPLEMENTATION | ;; a directory based on implementation, e.g. sbcl-1.0.45-linux-amd64 + (RELATIVE-COMPONENT-DESIGNATOR 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.45-linux-x64 :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl - :UID | ;; current UID -- not available on Windows - :USER ;; current USER name -- NOT IMPLEMENTED(!) - -PATTERN := a string without wildcards, that will be matched exactly - against the name of a any subdirectory in the directory component - of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"} + :DEFAULT-DIRECTORY | ;; a relativized version of the default directory + :*/ | ;; any direct subdirectory (since ASDF 2.011.4) + :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4) + :*.*.* | ;; any file (since ASDF 2.011.4) + ;; Not supported (anymore): :UID and :USERNAME @end example For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf}, -which is the default place ASDF looks for this configuration, -once contained: +which is the default place ASDF looks for this configuration, once contained: @example (:source-registry (:tree (:home "cl")) ;; will expand to e.g. "/home/joeluser/cl/" @@ -2418,29 +2567,9 @@ DIRECTIVE := (DIRECTORY-DESIGNATOR (:function TRANSLATION-FUNCTION)) DIRECTORY-DESIGNATOR := + NIL | ;; As source: skip this entry. As destination: same as source T | ;; as source matches anything, as destination leaves pathname unmapped. - ABSOLUTE-COMPONENT-DESIGNATOR | - (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) - -ABSOLUTE-COMPONENT-DESIGNATOR := - NULL | ;; As source: skip this entry. As destination: same as source - :ROOT | ;; magic: paths that are relative to the root of the source host and device - STRING | ;; namestring (directory is assumed, better be absolute or bust, ``/**/*.*'' added) - PATHNAME | ;; pathname (better be an absolute directory or bust) - :HOME | ;; designates the user-homedir-pathname ~/ - :USER-CACHE | ;; designates the default location for the user cache - :SYSTEM-CACHE ;; designates the default location for the system cache - -RELATIVE-COMPONENT-DESIGNATOR := - STRING | ;; namestring, directory is assumed. If the last component, /**/*.* is added - PATHNAME | ;; pathname; unless last component, directory is assumed. - :IMPLEMENTATION | ;; a directory based on implementation, e.g. sbcl-1.0.45-linux-amd64 - :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl - :*/ | ;; any direct subdirectory (since ASDF 2.011.4) - :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4) - :*.*.* | ;; any file (since ASDF 2.011.4) - :UID | ;; current UID -- not available on Windows - :USER ;; current USER name -- NOT IMPLEMENTED(!) + ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language TRANSLATION-FUNCTION := SYMBOL | ;; symbol of a function that takes two arguments, @@ -2737,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 @@ -2835,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 @@ -3045,7 +3382,7 @@ or take great pains to have the correct version of ASDF installed. With ASDF 2, we provide a new stable set of working features that everyone can rely on from now on. Use @code{#+asdf2} to detect presence of ASDF 2, -@code{(asdf:version-satisfies (asdf:asdf-version) "2.000")} +@code{(asdf:version-satisfies (asdf:asdf-version) "2.345.67")} to check the availability of a version no earlier than required. @@ -3054,7 +3391,7 @@ to check the availability of a version no earlier than required. When an old version of ASDF was loaded, it was very hard to upgrade ASDF in your current image without breaking everything. -Instead you have to exit the Lisp process and +Instead you had to exit the Lisp process and somehow arrange to start a new one from a simpler image. Something that can't be done from within Lisp, making automation of it difficult, @@ -3148,11 +3485,13 @@ and not use any deep @code{:tree} entry but only @code{:directory} entries or shallow @code{:tree} entries. Or you can fix your implementation to not be quite that slow when recursing through directories. +@emph{Update}: performance bug fixed the hard way in 2.010. @item On Windows, only LispWorks supports proper default configuration pathnames based on the Windows registry. -Other implementations make do with environment variables. +Other implementations make do with environment variables, +that you may have to define yourself if you're using an older version of Windows. Windows support is somewhat less tested than Unix support. Please help report and fix bugs. @@ -3162,7 +3501,7 @@ may use a different extension from the default @file{.lisp} has changed. Previously, the pathname for a component was lazily computed when operating on a system, and you would @code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo)))) - (declare (ignorable component system)) "cl")}. + (declare (ignorable component system)) "lis")}. Now, the pathname for a component is eagerly computed when defining the system, and instead you will @code{(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))} and use @code{:default-component-class cl-source-file.lis} as argument to @code{defsystem}, @@ -3201,7 +3540,7 @@ As to how to include ASDF, we recommend the following: @itemize @item -If ASDF isn't loaded yet, then @code{(require :asdf)} +If ASDF isn't loaded yet, then @code{(require "asdf")} should load the version of ASDF that is bundled with your system. You may have it load some other version configured by the user, if you allow such configuration. @@ -3506,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