Changeset 14713


Ignore:
Timestamp:
05/17/14 10:51:33 (8 years ago)
Author:
Mark Evenson
Message:

Update to ASDF 3.1.2.2 version.

Location:
trunk/abcl
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/abcl/doc/asdf/asdf.texinfo

    r14661 r14713  
    105105* Function and Class Index::
    106106* Variable Index::              @c @detailmenu
    107 @c 
     107@c
    108108
    109109@detailmenu
     
    115115* Checking whether ASDF is loaded::
    116116* Upgrading ASDF::
    117 * Loading an otherwise installed ASDF::
     117* Loading ASDF from source::
     118
     119Upgrading ASDF
     120
     121* Upgrading your implementation's ASDF::
     122* Issues with upgrading ASDF::
    118123
    119124Configuring ASDF
    120125
    121126* Configuring ASDF to find your systems::
     127* Configuring ASDF to find your systems --- old style::
    122128* Configuring where ASDF stores object files::
     129* Resetting the ASDF configuration::
     130
     131Using ASDF
     132
     133* Loading a system::
     134* Other Operations::
     135* Moving on::
    123136
    124137Defining systems with defsystem
     
    128141* The defsystem grammar::
    129142* Other code in .asd files::
    130 * The package-system extension::
    131 
    132 The object model of ASDF
     143* The package-inferred-system extension::
     144
     145The Object model of ASDF
    133146
    134147* Operations::
    135148* Components::
     149* Dependencies::
    136150* Functions::
    137151
     
    151165* Pre-defined subclasses of component::
    152166* Creating new component types::
     167
     168Controlling where ASDF searches for systems
     169
     170* Configurations::
     171* Truenames and other dangers::
     172* XDG base directory::
     173* Backward Compatibility::
     174* Configuration DSL::
     175* Configuration Directories::
     176* Shell-friendly syntax for configuration::
     177* Search Algorithm::
     178* Caching Results::
     179* Configuration API::
     180* Introspection::
     181* Status::
     182* Rejected ideas::
     183* TODO::
     184* Credits for the source-registry::
     185
     186Configuration Directories
     187
     188* The here directive::
     189
     190Introspection
     191
     192* *source-registry-parameter* variable::
     193* Information about system dependencies::
     194
     195Controlling where ASDF saves compiled files
     196
     197* Output Configurations::
     198* Output Backward Compatibility::
     199* Output Configuration DSL::
     200* Output Configuration Directories::
     201* Output Shell-friendly syntax for configuration::
     202* Semantics of Output Translations::
     203* Output Caching Results::
     204* Output location API::
     205* Credits for output translations::
     206
     207Miscellaneous additional functionality
     208
     209* Controlling file compilation::
     210* Controlling source file character encoding::
     211* Some Utility Functions::
    153212
    154213FAQ
     
    161220* ASDF development FAQs::
    162221
    163 ``What has changed between ASDF 1 and ASDF 2?''
     222``What has changed between ASDF 1, ASDF 2 and ASDF 3?''
    164223
    165224* What are ASDF 1 2 3?::
     225* How do I detect the ASDF version?::
    166226* ASDF can portably name files in subdirectories::
    167227* Output translations::
     
    191251* I want to put my module's files at the top level.  How do I do this?::
    192252* How do I create a system definition where all the source files have a .cl extension?::
     253* How do I mark a source file to be loaded only and not compiled?::
     254* How do I work with readtables?::
    193255
    194256ASDF development FAQs
     
    216278ASDF is Another System Definition Facility:
    217279a tool for specifying how systems of Common Lisp software
    218 are comprised of components (sub-systems and files),
     280are made up of components (sub-systems and files),
    219281and how to operate on these components in the right order
    220282so that they can be compiled, loaded, tested, etc.
     283If you are new to ASDF, @pxref{Quick start summary,,the quick start
     284guide}.
    221285
    222286ASDF presents three faces:
    223287one for users of Common Lisp software who want to reuse other people's code,
    224288one for writers of Common Lisp software who want to specify how to build their systems,
    225 one for implementers of Common Lisp extensions who want to extend the build system.
    226 @xref{Using ASDF,,Loading a system},
     289and one for implementers of Common Lisp extensions who want to extend
     290the build system.
     291For more specifics,
     292@pxref{Using ASDF,,Loading a system},
    227293to learn how to use ASDF to load a system.
    228294@xref{Defining systems with defsystem},
     
    231297the ASDF internals and how to extend ASDF.
    232298
    233 @emph{Nota Bene}:
    234 We have released ASDF 2.000 on May 31st 2010,
    235 and ASDF 3.0.0 on May 15th 2013.
    236 Releases of ASDF 2 and later have since then been included
    237 in all actively maintained CL implementations that used to bundle ASDF 1,
    238 plus some implementations that didn't use to,
    239 and has been made to work with all actively used CL implementations and a few more.
    240 @xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
    241 Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly
    242 (though we recommend instead upgrading your implementation or its ASDF module).
    243 For this reason, we have stopped supporting ASDF 1 and ASDF 2.
    244 If you are using ASDF 1 or ASDF 2 and are experiencing any kind of issues or limitations,
    245 we recommend you upgrade to ASDF 3
    246 --- and we explain how to do that. @xref{Loading ASDF}.
    247 (In the context of compatibility requirements,
    248 ASDF 2.27, released on Feb 1st 2013, and further 2.x releases up to 2.33,
    249 count as pre-releases of ASDF 3, and define the @code{:asdf3} feature;
    250 still, please use the latest release).
    251 Release ASDF 3.1.1 and later also define the @code{:asdf3.1} feature.
    252 
    253 Also note that ASDF is not to be confused with ASDF-Install.
    254 ASDF-Install is not part of ASDF, but a separate piece of software.
     299Note that
     300ASDF is @emph{not} a tool for library and system @emph{installation}; it
     301plays a role like @t{make} or @t{ant}, not like a package manager.
     302In particular, ASDF should not to be confused with ASDF-Install, which attempts to find and
     303download ASDF systems for you.
     304Despite the name, ASDF-Install is not part of ASDF, but a separate piece of software.
    255305ASDF-Install is also unmaintained and obsolete.
    256 We recommend you use Quicklisp instead,
    257 which works great and is being actively maintained.
     306We recommend you use Quicklisp
     307(@uref{http://www.quicklisp.org}) instead,
     308a Common Lisp package manager which works well and is being actively maintained.
    258309If you want to download software from version control instead of tarballs,
    259 so you may more easily modify it, we recommend clbuild.
     310so you may more easily modify it, we recommend clbuild (@uref{http://common-lisp.net/project/clbuild/}).
    260311We recommend @file{~/common-lisp/}
    261312as a place into which to install Common Lisp software;
    262 starting with ASDF 3.1.1, it is included in the default source-registry configuration.
     313starting with ASDF 3.1.2, it is included in the default source-registry configuration.
    263314
    264315@node  Quick start summary, Loading ASDF, Introduction, Top
     
    281332For more details, @xref{Configuring ASDF to find your systems}.
    282333The simplest way is simply to put all your lisp code in subdirectories of
    283 @file{~/common-lisp/} (starting with ASDF 3.1.1),
     334@file{~/common-lisp/} (starting with ASDF 3.1.2),
    284335or @file{~/.local/share/common-lisp/source/}
    285336(for ASDF 2 and later, or if you want to keep source in a hidden directory).
     
    300351Make a new directory for your system, @code{my-system/} in a location
    301352where ASDF can find it (@pxref{Configuring ASDF to find your systems}).
     353All else being equal, the easiest location is probably
     354@file{~/common-lisp/my-system/}.
     355
    302356
    303357@item
     
    330384* Checking whether ASDF is loaded::
    331385* Upgrading ASDF::
    332 * Loading an otherwise installed ASDF::
     386* Loading ASDF from source::
    333387@end menu
    334388
     
    350404As of the writing of this manual,
    351405the following implementations provide ASDF 3 this way:
    352 ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, mkcl, SBCL.
     406ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL, SBCL.
    353407The following implementations only provide ASDF 2:
    354408LispWorks, mocl, XCL.
    355 The following implementation doesn't provide ASDF yet but will in an upcoming release:
    356 SCL.
    357 The following implementations are obsolete, not actively maintained,
    358 and most probably will never bundle ASDF:
    359 Corman CL, GCL, Genera, MCL.
     409The following implementations don't provide ASDF:
     410Corman CL, GCL, Genera, MCL, SCL.
     411The latter implementations are not actively maintained;
     412if some of them are ever released again, they probably will include ASDF 3.
    360413
    361414If the implementation you are using doesn't provide ASDF 2 or ASDF 3,
    362 see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
     415see @pxref{Loading ASDF,,Loading ASDF from source} below.
    363416If that implementation is still actively maintained,
    364417you may also send a bug report to your Lisp vendor and complain
     
    380433If it raises an error,
    381434then either ASDF is not loaded, or
    382 you are using an old version of ASDF.
     435you are using a very old version of ASDF,
     436and need to install ASDF 3.
    383437
    384438You can check whether an old version is loaded
     
    390444@lisp
    391445(when (find-package :asdf)
    392   (let ((ver (symbol-value (or (find-symbol (string :*asdf-version*) :asdf)
    393                                (find-symbol (string :*asdf-revision*) :asdf)))))
     446  (let ((ver (symbol-value
     447                   (or (find-symbol (string :*asdf-version*) :asdf)
     448                       (find-symbol (string :*asdf-revision*) :asdf)))))
    394449    (etypecase ver
    395450      (string ver)
    396451      (cons (with-output-to-string (s)
    397               (loop for (n . m) on ver do (princ n s) (when m (princ "." s)))))
     452              (loop for (n . m) on ver
     453                    do (princ n s)
     454                       (when m (princ "." s)))))
    398455      (null "1.0"))))
    399456@end lisp
     
    409466before you contact us and raise an issue.
    410467
    411 @node  Upgrading ASDF, Loading an otherwise installed ASDF, Checking whether ASDF is loaded, Loading ASDF
     468@node  Upgrading ASDF, Loading ASDF from source, Checking whether ASDF is loaded, Loading ASDF
    412469@section Upgrading ASDF
    413470@c FIXME: tighten this up a bit -- there's a lot of stuff here that
     
    424481amongst the regularly configured systems, before it compiles anything else.
    425482
    426 @subsection Notes about ASDF 1 and ASDF 2
    427 
    428 Most implementations provide ASDF 3 in their latest release,
    429 and we recommend upgrading your implementation rather than using ASDF 1 or 2.
    430 A few implementations only provide ASDF 2,
    431 that can be overridden by installing a fasl (see below).
    432 A few implementations don't provide ASDF,
    433 but a fasl can be installed to provide it.
    434 GCL so far is still lacking a usable @code{require} interface.
    435 
    436 If your implementation has no suitable upgrade available (yet),
    437 or somehow upgrading is not an option,
    438 we assume you're an expert deliberately using a legacy implementation,
    439 and are proficient enough to install this fasl.
    440 Still, the ASDF source repository contains a script
    441 @file{bin/install-asdf-as-module} that can help you do that.
    442 It relies on @file{cl-launch} 4 for command-line invocation,
    443 which may depend on ASDF being checked out in @file{~/cl/asdf/}
    444 if your implementation doesn't even have an ASDF 2;
    445 but if you don't have @file{cl-launch},
     483@menu
     484* Upgrading your implementation's ASDF::
     485* Issues with upgrading ASDF::
     486@end menu
     487
     488@node Upgrading your implementation's ASDF, Issues with upgrading ASDF, Upgrading ASDF, Upgrading ASDF
     489@subsection Upgrading your implementation's ASDF
     490
     491Most implementations provide a recent ASDF 3 in their latest release.
     492If yours doesn't, we recommend upgrading your implementation.
     493If the latest version of your implementation still doesn't provide ASDF,
     494or provides an old version, we recommend installing a recent ASDF so your implementation provides it,
     495as explained below.
     496If all fails, we recommend you load ASDF from source
     497@pxref{Loading ASDF,,Loading ASDF from source}.
     498
     499The ASDF source repository contains a script
     500@file{bin/install-asdf-as-module} that can help you upgrade your implementation's ASDF.
     501It works on
     502Allegro CL, Clozure CL, CMU CL, ECL, GNU CLISP, LispWorks, MKCL, SBCL, SCL, XCL.
     503That's all known implementations except ABCL, Corman CL, GCL, Genera, MCL, MOCL.
     504Happily, ABCL is usually pretty up to date and shouldn't need that script.
     505GCL would be supported, except that so far is still lacking usable support for @code{require}.
     506Corman CL, Genera, MCL are obsolete anyway.
     507MOCL is under development.
     508On an old version of an implementation that does not provide ASDF,
     509you may have to load ASDF 3 from source before you load that script.
     510
     511The script relies on @code{cl-launch} 4 for command-line invocation,
     512which may depend on ASDF being checked out in @file{~/common-lisp/asdf/}
     513(which we recommend anyway)
     514if your implementation doesn't even have an ASDF 2.
     515If you don't have @code{cl-launch},
    446516you can instead @code{(load "bin/install-asdf-as-module")}
    447 from your implementation's REPL.
     517from your implementation's REPL after loading ASDF from source.
    448518
    449519Finally, if your implementation only provides ASDF 2,
     
    460530@end lisp
    461531
     532@node Issues with upgrading ASDF,  , Upgrading your implementation's ASDF, Upgrading ASDF
    462533@subsection Issues with upgrading ASDF
    463534
     
    516587@end itemize
    517588
    518 @node Loading an otherwise installed ASDF,  , Upgrading ASDF, Loading ASDF
    519 @section Loading an otherwise installed ASDF
     589@node Loading ASDF from source,  , Upgrading ASDF, Loading ASDF
     590@section Loading ASDF from source
    520591
    521592If your implementation doesn't include ASDF,
     
    574645
    575646@item
    576 Put all of your systems in subdirectories of
     647Put all of your systems in one of the standard locations, subdirectories
     648of
     649@itemize
     650@item
    577651@file{~/common-lisp/} or
     652@item
    578653@file{~/.local/share/common-lisp/source/}.
    579 If you install software there, you don't need further configuration.
    580 (NB: @file{~/common-lisp/} is only included in the default configuration
    581 starting with ASDF 3.1.1 or later)
     654@end itemize
     655If you install software there, you don't need further
     656configuration.@footnote{@file{~/common-lisp/} is only included in
     657the default configuration
     658starting with ASDF 3.1.2 or later.}
    582659
    583660@item
     
    642719
    643720@node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Configuring ASDF
     721@section Configuring ASDF to find your systems --- old style
     722
    644723
    645724@c FIXME: this section should be moved elsewhere.  The novice user
    646725@c should not be burdened with it. [2014/02/27:rpg]
    647 @section Configuring ASDF to find your systems --- old style
     726
    648727
    649728The old way to configure ASDF to find your systems is by
     
    816895
    817896@node Resetting the ASDF configuration,  , Configuring where ASDF stores object files, Configuring ASDF
     897@section Resetting the ASDF configuration
     898
    818899@c FIXME: this should probably be moved out of the "quickstart" part of
    819900@c the manual. [2014/02/27:rpg]
    820 @section Resetting the ASDF configuration
     901
    821902
    822903When you dump and restore an image, or when you tweak your configuration,
     
    825906
    826907@defun clear-configuration
    827    undoes any ASDF configuration,
     908   Undoes any ASDF configuration
    828909   regarding source-registry or output-translations.
    829910@end defun
     
    842923@chapter Using ASDF
    843924
     925@menu
     926* Loading a system::
     927* Other Operations::
     928* Moving on::
     929@end menu
     930
     931@node Loading a system, Other Operations, Using ASDF, Using ASDF
    844932@section Loading a system
    845933
     
    852940
    853941On some implementations (namely recent versions of
    854 ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP,
    855 LispWorks, MKCL, SBCL and XCL),
     942ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL),
    856943ASDF hooks into the @code{CL:REQUIRE} facility
    857944and you can just use:
     
    865952If your ASDF is too old to provide @code{asdf:load-system} though
    866953we recommend that you upgrade to ASDF 3.
    867 @xref{Loading ASDF,,Loading an otherwise installed ASDF}.
     954@xref{Loading ASDF,,Loading ASDF from source}.
    868955
    869956Note the name of a system is specified as a string or a symbol.
     
    881968@c which is reported not to work on some implementations
    882969
    883 
     970@node Other Operations, Moving on, Loading a system, Using ASDF
    884971@section Other Operations
    885972
     973@findex load-system
     974@findex compile-system
     975@findex test-system
     976@findex requrie-system
     977
    886978ASDF provides three commands for the most common system operations:
    887 @code{load-system}, @code{compile-system} or @code{test-system}.
     979@code{load-system}, @code{compile-system}, and @code{test-system}.
    888980It also provides @code{require-system}, a version of @code{load-system}
    889981that skips trying to update systems that are already loaded.
     982
     983@c FIXME: We seem to export @findex bundle-system also.
     984
     985@findex operate
     986@findex oos
    890987
    891988Because ASDF is an extensible system
    892989for defining @emph{operations} on @emph{components},
    893990it also provides a generic function @code{operate}
    894 (which is usually abbreviated by @code{oos}).
     991(which is usually abbreviated by @code{oos},
     992which stands for operate-on-system).
    895993You'll use @code{oos} whenever you want to do something beyond
    896994compiling, loading and testing.
     
    9071005@c FIXME: the following is too complicated for here, especially since
    9081006@c :force hasn't been defined yet.  Move it. [2014/02/27:rpg]
     1007
    9091008@findex already-loaded-systems
    910 
     1009@findex require-system
     1010@findex load-system
     1011@vindex *load-system-operation*
    9111012For advanced users, note that
    9121013@code{require-system} calls @code{load-system}
     
    9141015@code{already-loaded-systems} returns a list of the names of loaded systems.
    9151016@code{load-system} applies @code{operate} with the operation from
    916 @code{*load-system-operation*}, which by default is @code{load-op},
     1017@code{*load-system-operation*} (which by default is @code{load-op}),
    9171018the system, and any provided keyword arguments.
    9181019
    9191020
     1021@node Moving on,  , Other Operations, Using ASDF
    9201022@section Moving on
    9211023
     
    9301032@chapter Defining systems with defsystem
    9311033
    932 This chapter describes how to use asdf to define systems and develop
     1034This chapter describes how to use ASDF to define systems and develop
    9331035software.
    9341036
     
    9391041* The defsystem grammar::
    9401042* Other code in .asd files::
    941 * The package-system extension::
     1043* The package-inferred-system extension::
    9421044@end menu
    9431045
     
    9451047@comment  node-name,  next,  previous,  up
    9461048@section The defsystem form
    947 
    948 Systems can be constructed programmatically
    949 by instantiating components using @code{make-instance}.
    950 Most of the time, however, it is much more practical to use
    951 a static @code{defsystem} form.
     1049@findex defsystem
     1050@cindex asdf-user
     1051@findex load-asd
     1052
    9521053This section begins with an example of a system definition,
    9531054then gives the full grammar of @code{defsystem}.
    9541055
    9551056Let's look at a simple system.
    956 This is a complete file that would
    957 usually be saved as @file{hello-lisp.asd}:
     1057This is a complete file that should be saved as @file{hello-lisp.asd}
     1058(in order that ASDF can find it
     1059when ordered to operate on the system named @code{"hello-lisp"}).
     1060
     1061@c FIXME: the first example should have an outside dependency, e.g.,
     1062@c CL-PPCRE.
    9581063
    9591064@lisp
    960 (in-package :asdf)
     1065(in-package :asdf-user)
    9611066
    9621067(defsystem "hello-lisp"
    9631068  :description "hello-lisp: a sample Lisp system."
    964   :version "0.2.1"
     1069  :version "0.0.1"
    9651070  :author "Joe User <joe@@example.com>"
    9661071  :licence "Public Domain"
     
    9761081@item
    9771082The file starts with an @code{in-package} form
    978 to use package @code{asdf}.
    979 You could instead start your definition by using
    980 a qualified name @code{asdf:defsystem}.
    981 
    982 @item
    983 If in addition to simply using @code{defsystem},
    984 you are going to define functions,
    985 create ASDF extension, globally bind symbols, etc.,
    986 it is recommended that to avoid namespace pollution between systems,
    987 you should create your own package for that purpose,
    988 for instance replacing the above @code{(in-package :asdf)} with:
    989 
    990 @lisp
    991 (defpackage :foo-system
    992   (:use :cl :asdf))
    993 
    994 (in-package :foo-system)
    995 @end lisp
     1083for package @code{asdf-user}.  Quick summary: just do this, because it
     1084helps make interactive development of @code{defsystem} forms behave in
     1085the same was as when these forms are loaded by ASDF.  If that's enough
     1086for you, skip the rest of this item.  Otherwise read on for the gory details.
     1087
     1088If your file is loaded by ASDF 3, it will be loaded into the
     1089@code{asdf-user} package.  The @code{in-package} form
     1090will ensure that the system definition is read the
     1091same as within ASDF when you load it interactively with @code{cl:load}.
     1092However, we recommend that you load @file{.asd} files
     1093through function @code{asdf::load-asd} rather than through @code{cl:load},
     1094in which case this form is unnecessary.
     1095Recent versions of SLIME (2013-02 and later) know to do that.
     1096
     1097@item
     1098You can always rely on symbols
     1099from both package @code{asdf} and @code{common-lisp} being available in
     1100@code{.asd} files --
     1101most importantly including @code{defsystem}.
     1102
     1103@c FIXME: the following should be inserted in a more advanced
     1104@c bit of the manual.  For now, it is simply elided.
     1105@c Starting with ASDF 3.1,
     1106@c @file{.asd} files are read in the package @code{asdf-user}
     1107@c that uses @code{asdf}, @code{uiop} and @code{uiop/common-lisp}
     1108@c (a variant of @code{common-lisp}
     1109@c that has some portability fixes on old implementations).
     1110@c ASDF 3 releases before 3.1 also read in package @code{asdf-user}
     1111@c but that package don't use the full @code{uiop}, only @code{uiop/package}.
     1112@c ASDF 1 and ASDF 2 releases (up until 2.26) instead read @file{.asd} files
     1113@c in a temporary package @code{asdf@emph{N}}
     1114@c that uses @code{asdf} and @code{common-lisp}.
     1115@c You may thus have to package-qualify some symbols with @code{uiop:}
     1116@c to support older variants of ASDF 3,
     1117@c and/or package-qualify them with @code{asdf::}
     1118@c to be compatible with even older variants of ASDF 2
     1119@c (and then only use the few already available in ASDF 2).
     1120
    9961121
    9971122@item
     
    10001125@file{packages}, @file{macros} and @file{hello}.
    10011126
     1127@c FIXME: The first example system should probably use just :serial T.
    10021128@item
    10031129The file @file{macros} depends on @file{packages}
     
    10091135
    10101136@item
    1011 The files are located in the same directory
    1012 as the file with the system definition.
    1013 ASDF resolves symbolic links (or Windows shortcuts)
    1014 before loading the system definition file and
    1015 stores its location in the resulting system@footnote{
    1016 It is possible, though almost never necessary, to override this behaviour.}.
    1017 This is a good thing because the user can move the system sources
    1018 without having to edit the system definition.
     1137System source files should be located in the same directory
     1138as the @code{.asd} file with the system definition.
     1139@c FIXME: the following should live somewhere, but not in the quickstart
     1140@c page. [2014/05/03:rpg]
     1141@c ASDF resolves symbolic links (or Windows shortcuts)
     1142@c before loading the system definition file and
     1143@c stores its location in the resulting system@footnote{
     1144@c It is possible, though almost never necessary, to override this behaviour.}.
     1145@c This is a good thing because the user can move the system sources
     1146@c without having to edit the system definition.
    10191147
    10201148@c FIXME: Should have cross-reference to "Version specifiers" in the
    10211149@c defsystem grammar, but the cross-referencing is so broken by
    10221150@c insufficient node breakdown that I have not put one in.
     1151@c FIXME: this is way too detailed for the first example!
     1152@c move it!
    10231153@item
    10241154Make sure you know how the @code{:version} numbers will be parsed!
    1025 They are parsed as period-separated lists of integers.
    1026 I.e., in the example, @code{0.2.1} is to be interpreted,
    1027 roughly speaking, as @code{(0 2 1)}.
    1028 In particular, version @code{0.2.1}
    1029 is interpreted the same as @code{0.0002.1} and
    1030 is strictly version-less-than version @code{0.20.1},
    1031 even though the two are the same when interpreted as decimal fractions.
    1032 Instead of a string representing the version,
    1033 the @code{:version} argument can be an expression that is resolved to
    1034 such a string using the following trivial domain-specific language:
    1035 in addition to being a literal string, it can be an expression of the form
    1036 @code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)},
    1037 which will be resolved by reading a form in the specified pathname
    1038 (read as a subpathname of the current system if relative or a unix-namestring).
    1039 You may use a @code{uiop:access-at} specifier
    1040 with the (optional) @code{:at} keyword,
    1041 by default the specifier is @code{0}, meaning the first form is returned.
    1042 
     1155Only period-separated non-negative integers are accepted.
     1156See below Version specifiers in @ref{The defsystem grammar}.
    10431157@cindex :version
    10441158
     
    10481162@comment  node-name,  next,  previous,  up
    10491163@section A more involved example
     1164@findex defsystem
    10501165
    10511166Let's illustrate some more involved uses of @code{defsystem} via a
     
    10531168
    10541169@lisp
     1170(in-package :asdf-user)
     1171
    10551172(defsystem "foo"
    10561173  :version "1.0.0"
    10571174  :components ((:module "mod"
    1058                             :components ((:file "bar")
    1059                                                   (:file"baz")
    1060                                                   (:file "quux"))
    1061                             :perform (compile-op :after (op c)
    1062                                                   (do-something c))
    1063                             :explain (compile-op :after (op c)
    1064                                             (explain-something c)))
    1065                          (:file "blah")))
     1175                :components ((:file "bar")
     1176                             (:file"baz")
     1177                             (:file "quux"))
     1178                :perform (compile-op :after (op c)
     1179                           (do-something c))
     1180                :explain (compile-op :after (op c)
     1181                           (explain-something c)))
     1182               (:file "blah")))
    10661183@end lisp
    10671184
     
    11021219@ref{The object model of ASDF}.
    11031220
    1104 @c The following plunge into the weeds is not appropriate in this
     1221@c FIXME: The following plunge into detail weeds is not appropriate in this
    11051222@c location. [2010/10/03:rpg]
    11061223@c note that although this also supports @code{:before} methods,
     
    11101227@c but before the component in question has been compiled.
    11111228
     1229
     1230@c FIXME: There should be YA example that shows definitions of functions
     1231@c and classes.  The following material should go there.
     1232@c @item
     1233@c If in addition to simply using @code{defsystem},
     1234@c you are going to define functions,
     1235@c create ASDF extension, globally bind symbols, etc.,
     1236@c it is recommended that to avoid namespace pollution between systems,
     1237@c you should create your own package for that purpose, with:
     1238
     1239@c @lisp
     1240@c (defpackage :hello-lisp-system
     1241@c   (:use :cl :asdf))
     1242
     1243@c (in-package :hello-lisp-system)
     1244@c @end lisp
     1245
     1246
    11121247@node  The defsystem grammar, Other code in .asd files, A more involved example, Defining systems with defsystem
    11131248@comment  node-name,  next,  previous,  up
    11141249@section The defsystem grammar
     1250@findex defsystem
     1251@cindex DEFSYSTEM grammar
    11151252
    11161253@c FIXME: @var typesetting not consistently used here.  We should either expand
     
    11501287component-type := :module | :file | :static-file | other-component-type
    11511288
    1152 other-component-type := symbol-by-name (@pxref{The defsystem grammar,,Component types})
     1289other-component-type := symbol-by-name
     1290                        (@pxref{The defsystem grammar,,Component types})
    11531291
    11541292# This is used in :depends-on, as opposed to ``dependency,''
     
    11711309pathname-specifier := pathname | string | symbol
    11721310
    1173 method-form := (operation-name qual lambda-list @Arest body)
     1311method-form := (operation-name qual lambda-list @Arest{} body)
    11741312qual := method qualifier
    11751313
    11761314component-dep-fail-option := :fail | :try-next | :ignore
    11771315
    1178 feature-expression := keyword | (:and @var{feature-expression}*)
    1179                       | (:or @var{feature-expression}*) | (:not @var{feature-expression})
     1316feature-expression := keyword
     1317                      | (:and @var{feature-expression}*)
     1318                      | (:or @var{feature-expression}*)
     1319                      | (:not @var{feature-expression})
    11801320@end example
    11811321
     
    12961436will be interpreted as the pathname @file{#p"foo/bar.quux"}.
    12971437
    1298 ASDF does not interpret the string @code{".."} to designate the parent
    1299 directory.  This string will be passed through to the underlying
    1300 operating system for interpretation.  We @emph{believe} that this will
    1301 work on all platforms where ASDF is deployed, but do not guarantee this
    1302 behavior.  A pathname object with a relative directory component of
    1303 @code{:up} or @code{:back} is the only guaranteed way to specify a
    1304 parent directory.
     1438ASDF interprets the string @code{".."}
     1439as the pathname directory component word @code{:back},
     1440which when merged, goes back one level in the directory hierarchy.
    13051441
    13061442If a symbol is given, it will be translated into a string,
     
    13291465the component-type default file type for a given component.
    13301466Therefore, pathname objects should only rarely be used.
    1331 Unhappily, ASDF 1 didn't properly support
     1467Unhappily, ASDF 1 used not to properly support
    13321468parsing component names as strings specifying paths with directories,
    13331469and the cumbersome @code{#.(make-pathname ...)} syntax had to be used.
     
    13571493quite unlike what would have happened
    13581494had the version strings been interpreted as decimal fractions.
     1495
     1496Instead of a string representing the version,
     1497the @code{:version} argument can be an expression that is resolved to
     1498such a string using the following trivial domain-specific language:
     1499in addition to being a literal string, it can be an expression of the form
     1500@code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)},
     1501which will be resolved by reading a form in the specified pathname
     1502(read as a subpathname of the current system if relative or a unix-namestring).
     1503You may use a @code{uiop:access-at} specifier
     1504with the (optional) @code{:at} keyword,
     1505by default the specifier is @code{0}, meaning the first form is returned;
     1506subforms can also be specified, with e.g. @code{(1 2 2)} specifying
     1507``the third subform (index 2) of the third subform (index 2) of the second form (index 1)''
     1508in the file (mind the off-by-one error in the English language).
    13591509
    13601510System definers are encouraged to use version identifiers of the form
     
    14481598
    14491599
    1450 @subsection Source location
     1600@subsection Source location (@code{:pathname})
    14511601
    14521602The @code{:pathname} option is optional in all cases for systems
    1453 defined via @code{defsystem},
    1454 and in the usual case the user is recommended not to supply it.
    1455 
    1456 Instead, ASDF follows a hairy set of rules that are designed so that
     1603defined via @code{defsystem}, and generally is unnecessary.  In the
     1604simple case, source files will be found in the same directory as the
     1605system or, in the case of modules, in a subdirectory with the same name
     1606as the module.
     1607
     1608@c FIXME: This should be moved elsewhere -- it's too much detail for the
     1609@c grammar section.
     1610
     1611More specifically, ASDF follows a hairy set of rules that are designed so that
    14571612@enumerate
    14581613@item
     
    15321687
    15331688@subsection feature requirement
    1534 This requirement was removed in ASDF 3.1.
    1535 It used to ensure that a chain of component dependencies will raise an error,
    1536 which in conjunction with if-component-dep-fails would offer
     1689This requirement was removed in ASDF 3.1.  Please do not use it.  In
     1690most cases, @code{:if-feature} (@pxref{if-feature-option}) will provide
     1691an adequate substitute.
     1692
     1693The @code{feature} requirement used to ensure that a chain of component
     1694dependencies would fail when a key feature was absent.
     1695Used in conjunction with @code{:if-component-dep-fails}
     1696this provided
    15371697a roundabout way to express conditional compilation.
    15381698
    15391699
    1540 @node Other code in .asd files, The package-system extension, The defsystem grammar, Defining systems with defsystem
     1700@node Other code in .asd files, The package-inferred-system extension, The defsystem grammar, Defining systems with defsystem
    15411701@section Other code in .asd files
    15421702
     
    15481708that you use with @code{:defsystem-depends-on}.
    15491709
    1550 If however, you might insist on including code in the @code{.asd} file itself,
     1710If however, you might insist on including code in the @file{.asd} file itself,
    15511711e.g., to examine and adjust the compile-time environment,
    15521712possibly adding appropriate features to @code{*features*}.
     
    15661726
    15671727
    1568 @node The package-system extension,  , Other code in .asd files, Defining systems with defsystem
    1569 @section The package-system extension
    1570 
    1571 Starting with ASDF 3.0.3,
     1728@node The package-inferred-system extension,  , Other code in .asd files, Defining systems with defsystem
     1729@section The package-inferred-system extension
     1730
     1731Starting with release 3.1.2,
    15721732ASDF supports a one-package-per-file style of programming,
    15731733whereby each file is its own system,
    1574 and dependencies are deduced from the @code{defpackage} form.
    1575 
    1576 In this style, packages referring to a same-named system (downcased);
    1577 and if a system is defined with @code{:class package-system},
     1734and dependencies are deduced from the @code{defpackage} form
     1735(or its variant @code{uiop:define-package}).
     1736
     1737
     1738In this style, packages refer to a system with the same name (downcased);
     1739and if a system is defined with @code{:class package-inferred-system},
    15781740then system names that start with that name
    15791741(using the slash @code{/} separator)
     
    15901752To use this style, choose a toplevel system name, e.g. @code{my-lib},
    15911753and create a file @file{my-lib.asd}
    1592 with the @code{:class :package-system} option in its @code{defsystem}.
     1754with the @code{:class :package-inferred-system} option in its @code{defsystem}.
    15931755For instance:
    15941756@example
    15951757#-asdf (error "my-lib requires ASDF 3")
    15961758(defsystem my-lib
    1597   :class :package-system
     1759  :class :package-inferred-system
    15981760  :defsystem-depends-on (:asdf-package-system)
    1599   :depends-on (:my-lib/src/all)
    1600   :in-order-to ((test-op (load-op :my-lib/test/all)))
    1601   :perform (test-op (o c) (symbol-call :my-lib/test/all :test-suite)))
    1602 (register-system-packages :closer-mop
     1761  :depends-on (:lil/interface/all
     1762               :lil/pure/all
     1763               :lil/stateful/all
     1764               :lil/transform/all)
     1765  :in-order-to ((test-op (load-op :lil/test/all)))
     1766  :perform (test-op (o c) (symbol-call :lil/test/all :test-suite)))
     1767
     1768(defsystem :lil/test :depends-on (:lil/test/all))
     1769
     1770(register-system-packages :lil/interface/all '(:interface))
     1771(register-system-packages :lil/pure/all '(:pure))
     1772(register-system-packages :lil/stateful/all '(:stateful))
     1773(register-system-packages :lil/transform/classy '(:classy))
     1774(register-system-packages :lil/transform/posh '(:posh))
     1775(register-system-packages :lil/test/all '(:lil/test))
     1776
     1777(register-system-packages
     1778 :closer-mop
    16031779 '(:c2mop :closer-common-lisp :c2cl :closer-common-lisp-user :c2cl-user))
    16041780@end example
     
    16061782In the code above, the
    16071783@code{:defsystem-depends-on (:asdf-package-system)} is
    1608 for compatibility with older versions of ASDF 3 (ASDF 2 not supported),
     1784for compatibility with older versions of ASDF 3 (ASDF 2 is not supported),
    16091785and requires the @code{asdf-package-system} library to be present
    1610 (it is implicitly provided by ASDF starting with ASDF 3.0.3).
     1786(it is implicitly provided by ASDF starting with release 3.1.2,
     1787which can be detected with the feature @code{:asdf3.1}).
    16111788
    16121789The function @code{register-system-packages} has to be called to register
     
    16151792is not the downcase of the package name.
    16161793
    1617 File @file{my-lib/src/utility.lisp} might start with:
     1794Then, file @file{interface/order.lisp} under the @code{lil} hierarchy,
     1795that defines abstract interfaces for order comparisons,
     1796starts with the following form,
     1797dependencies being trivially computed from the @code{:use} and @code{:mix} clauses:
    16181798
    16191799@example
    1620 (defpackage :my-lib/src/utility
    1621   (:use :closer-common-lisp :my-lib/src/macros :my-lib/src/variables)
    1622   (:import-from :cl-ppcre #:register-groups-bind)
    1623   (:export #:foo #:bar))
     1800(uiop:define-package :lil/interface/order
     1801  (:use :closer-common-lisp
     1802   :lil/interface/definition
     1803   :lil/interface/base
     1804   :lil/interface/eq :lil/interface/group)
     1805  (:mix :fare-utils :uiop :alexandria)
     1806  (:export ...))
    16241807@end example
    16251808
    1626 And from the @code{:use} and @code{:import-from} clauses,
    1627 ASDF could tell that you depend on systems @code{closer-mop} (registered above),
    1628 @code{cl-ppcre} (package and system names match), and
    1629 @code{my-lib/src/macros} and @code{my-lib/src/variables}
     1809ASDF can tell that this file depends on system @code{closer-mop} (registered above),
     1810@code{lil/interface/definition}, @code{lil/interface/base},
     1811@code{lil/interface/eq}, and @code{lil/interface/group}
    16301812(package and system names match, and they will be looked up hierarchically).
     1813
     1814ASDF also detects dependencies from @code{:import-from} clauses.
     1815To depend on a system without using a package or importing any symbol from it
     1816(because you'll fully qualify them when used),
     1817you may thus use an @code{:import-from} clause with an empty list of symbols, as in:
     1818
     1819@example
     1820(defpackage :foo/bar
     1821  (:use :cl)
     1822  (:import-from :foo/baz #:sym1 #:sym2)
     1823  (:import-from :foo/quux)
     1824  (:export ...))
     1825@end example
    16311826
    16321827The form @code{uiop:define-package} is supported as well as @code{defpackage},
     
    16371832@node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top
    16381833@comment  node-name,  next,  previous,  up
    1639 @chapter The object model of ASDF
     1834@chapter The Object model of ASDF
     1835@tindex component
     1836@tindex operation
    16401837
    16411838ASDF is designed in an object-oriented way from the ground up.
    16421839Both a system's structure and the operations that can be performed on systems
    1643 follow a extensible protocol.
    1644 
    1645 This allows the addition of behaviours:
    1646 for example, @code{cffi} adds support of special FFI description files
    1647 to interface with C libraries and of wrapper files to embed C code in Lisp;
    1648 @code{abcl-jar} supports creating Java JAR archives in ABCL;
    1649 and @code{poiu} supports for compiling code in parallel using background processes.
    1650 
    1651 This chapter deals with @code{component}s and @code{operation}s.
     1840follow a extensible protocol, allowing programmers to add new behaviors to ASDF.
     1841For example, @code{cffi} adds support for special FFI description files
     1842that interface with C libraries and for wrapper files that embed C code in Lisp.
     1843@code{abcl-jar} supports creating Java JAR archives in ABCL.
     1844@code{poiu} supports compiling code in parallel using background processes.
     1845
     1846The key classes in ASDF are @code{component} and @code{operation}.
     1847A @code{component} represents an individual source file or a group of source files,
     1848and the products (e.g., fasl files) produced from it.
     1849An @code{operation} represents a transformation that can be performed on a component,
     1850turning them from source files to intermediate results to final outputs.
     1851Components are related by @emph{dependencies}, specified in system
     1852definitions.
     1853
     1854When ordered to @code{operate} with some operation on a component (usually a system),
     1855ASDF will first compute a @emph{plan}
     1856by traversing the dependency graph using function @code{make-plan}.@footnote{
     1857  Historically, the function that built a plan was
     1858  called @code{traverse}, and returned a list of actions;
     1859  it was deprecated in favor of @code{make-plan} (that returns a plan object)
     1860  when the @code{plan} objects were introduced;
     1861  the old function is kept for backward compatibility and debugging purposes only.
     1862}
     1863The resulting plan object contains an ordered list of @emph{actions}.
     1864An action is a pair of an @code{operation} and a @code{component},
     1865representing  a particular build step to be @code{perform}ed.
     1866The ordering of the plan ensures that no action is performed before
     1867all its dependencies have been fulfilled.@footnote{
     1868  The term @emph{action}
     1869  was used by Kent Pitman in his article, ``The Description of Large Systems,''
     1870  (@pxref{Bibliography}).
     1871  Although the term was only used by ASDF hackers starting with ASDF 2,
     1872  the concept was there since the very beginning of ASDF 1,
     1873  just not clearly articulated.
     1874}
     1875
     1876In this chapter, we describe ASDF's object-oriented protocol,
     1877the classes that make it up, and the generic functions on those classes.
     1878These generic functions often take
     1879both an operation and a component as arguments:
     1880much of the power and configurability of ASDF is provided by
     1881this use of CLOS's multiple dispatch.
     1882We will describe the built-in component and operation classes, and
     1883explain how to extend the ASDF protocol by defining new classes and
     1884methods for ASDF's generic functions.
     1885We will also describe the many @emph{hooks} that can be configured to
     1886customize the behavior of existing @emph{functions}.
     1887
     1888@c FIXME: Swap operations and components.
     1889@c FIXME: Possibly add a description of the PLAN object.
     1890@c Not critical, since the user isn't expected to interact with it.
     1891@menu
     1892* Operations::
     1893* Components::
     1894* Dependencies::
     1895* Functions::
     1896@end menu
     1897
     1898@node  Operations, Components, The object model of ASDF, The object model of ASDF
     1899@comment  node-name,  next,  previous,  up
     1900@section Operations
     1901@cindex operation
     1902
     1903An @dfn{operation} object of the appropriate type is instantiated
     1904whenever the user wants to do something with a system like
     1905
     1906@itemize
     1907@item compile all its files
     1908@item load the files into a running lisp environment
     1909@item copy its source files somewhere else
     1910@end itemize
     1911
     1912Operations can be invoked directly, or examined
     1913to see what their effects would be without performing them.
     1914There are a bunch of methods specialised on operation and component type
     1915that actually do the grunt work.
     1916Operations are invoked on systems via @code{operate} (@pxref{operate}).
     1917
     1918ASDF contains a number of pre-defined @t{operation} classes for common,
     1919and even fairly uncommon tasks that you might want to do with it.
     1920In addition, ASDF contains ``abstract'' @t{operation} classes that
     1921programmers can use as building blocks to define ASDF extensions.  We
     1922discuss these in turn below.
     1923
     1924@c The operation object contains whatever state is relevant for this purpose
     1925@c (perhaps a list of visited nodes, for example)
     1926@c but primarily is a nice thing to specialise operation methods on
     1927@c and easier than having them all be @code{EQL} methods.
     1928
     1929@menu
     1930* Predefined operations of ASDF::
     1931* Creating new operations::
     1932@end menu
     1933
     1934Operations are invoked on systems via @code{operate}.
     1935@anchor{operate}
     1936@deffn {Generic function} @code{operate} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @code{force} @code{force-not} @code{verbose} @AallowOtherKeys
     1937@deffnx {Generic function} @code{oos} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @AallowOtherKeys{}
     1938@code{operate} invokes @var{operation} on @var{system}.
     1939@code{oos} is a synonym for @code{operate} (it stands for operate-on-system).
     1940
     1941@var{operation} is a symbol that is passed,
     1942along with the supplied @var{initargs},
     1943to @code{make-operation} (which will call @code{make-instance})
     1944to create the operation object.
     1945@var{component} is a component designator,
     1946usually a string or symbol that designates a system,
     1947sometimes a list of strings or symbols that designate a subcomponent of a system.
     1948
     1949The @var{initargs} are passed to the @code{make-instance} call
     1950when creating the operation object.
     1951@c We probably want to deprecate that, because
     1952@c (1) there is a mix of flags for operate, for the operation-class, for the plan-class, etc.
     1953@c (2) flags to operations have never been well-supported, anyway.
     1954@c The future solution probably involves having an explicit :operation-options keyword or some such
     1955@c (if operation options are not wholly eliminated), a separate :plan-options, etc.
     1956Note that dependencies may cause the operation
     1957to invoke other operations on the system or its components:
     1958the new operations will be created
     1959with the same @var{initargs} as the original one.
     1960
     1961If @var{force} is @code{:all}, then all systems
     1962are forced to be recompiled even if not modified since last compilation.
     1963If @var{force} is @code{t}, then only the system being loaded
     1964is forced to be recompiled even if not modified since last compilation,
     1965but other systems are not affected.
     1966If @var{force} is a list, then it specifies a list of systems that
     1967are forced to be recompiled even if not modified since last compilation.
     1968If @var{force-not} is @code{:all}, then all systems
     1969are forced not to be recompiled even if modified since last compilation.
     1970If @var{force-not} is @code{t}, then all systems but the system being loaded
     1971are forced not to be recompiled even if modified since last compilation
     1972(note: this was changed in ASDF 3.1.2).
     1973If @var{force-not} is a list, then it specifies a list of systems that
     1974are forced not to be recompiled even if modified since last compilation.
     1975
     1976Both @var{force} and @var{force-not} apply to systems that are dependencies and were already compiled.
     1977@var{force-not} takes precedences over @var{force},
     1978as it should, really, but unhappily only since ASDF 3.1.2.
     1979Moreover, systems the name of which is member of the set @var{*immutable-systems*}
     1980(represented as an equal hash-table) are always considered @var{forced-not}, and
     1981even their @file{.asd} is not refreshed from the filesystem.
     1982
     1983To see what @code{operate} would do, you can use:
     1984@example
     1985(asdf:traverse operation-class system-name)
     1986@end example
     1987
     1988@end deffn
     1989
     1990
     1991
     1992@node Predefined operations of ASDF, Creating new operations, Operations, Operations
     1993@comment  node-name,  next,  previous,  up
     1994@subsection Predefined operations of ASDF
     1995@c FIXME: All these deffn's should be replaced with deftyp.  Also, we
     1996@c should set up an appropriate index.
     1997
     1998All the operations described in this section are in the @code{asdf} package.
     1999They are invoked via the @code{operate} generic function.
     2000
     2001@lisp
     2002(asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
     2003@end lisp
     2004
     2005@deffn Operation @code{compile-op}
     2006
     2007This operation compiles the specified component.
     2008A @code{cl-source-file} will be @code{compile-file}'d.
     2009All the children and dependencies of a system or module
     2010will be recursively compiled by @code{compile-op}.
     2011
     2012@code{compile-op} depends on @code{prepare-op} which
     2013itself depends on a @code{load-op} of all of a component's dependencies,
     2014as well as of its parent's dependencies.
     2015When @code{operate} is called on @code{compile-op},
     2016all these dependencies will be loaded as well as compiled;
     2017yet, some parts of the system main remain unloaded,
     2018because nothing depends on them.
     2019Use @code{load-op} to load a system.
     2020@end deffn
     2021
     2022@deffn Operation @code{load-op}
     2023
     2024This operation loads the compiled code for a specified component.
     2025A @code{cl-source-file} will have its compiled fasl @code{load}ed,
     2026which fasl is the output of @code{compile-op} that @code{load-op} depends on.
     2027
     2028@code{load-op} will recursively load all the children of a system or module.
     2029
     2030@code{load-op} also depends on @code{prepare-op} which
     2031itself depends on a @code{load-op} of all of a component's dependencies,
     2032as well as of its parent's dependencies.
     2033@end deffn
     2034
     2035@deffn Operation @code{prepare-op}
     2036
     2037This operation ensures that the dependencies of a component
     2038and its recursive parents are loaded (as per @code{load-op}),
     2039as a prerequisite before @code{compile-op} and @code{load-op} operations
     2040may be performed on a given component.
     2041@end deffn
     2042
     2043@deffn Operation @code{load-source-op}, @code{prepare-source-op}
     2044
     2045@code{load-source-op} will load the source for the files in a module
     2046rather than the compiled fasl output.
     2047It has a @code{prepare-source-op} analog to @code{prepare-op},
     2048that ensures the dependencies are themselves loaded via @code{load-source-op}.
     2049
     2050@end deffn
     2051
     2052@anchor{test-op}
     2053@deffn Operation @code{test-op}
     2054
     2055This operation will perform some tests on the module.
     2056The default method will do nothing.
     2057The default dependency is to require
     2058@code{load-op} to be performed on the module first.
     2059Its @code{operation-done-p} method returns @code{nil},
     2060which means that the operation is @emph{never} done
     2061--
     2062we assume that if you invoke the @code{test-op},
     2063you want to test the system, even if you have already done so.
     2064
     2065The results of this operation are not defined by ASDF.
     2066It has proven difficult to define how the test operation
     2067should signal its results to the user
     2068in a way that is compatible with all of the various test libraries
     2069and test techniques in use in the community, and
     2070given the fact that ASDF operations do not return a value indicating
     2071success or failure.
     2072For those willing to go to the effort, we suggest defining conditions to
     2073signal when a @code{test-op} fails, and storing in those conditions
     2074information that describes which tests fail.
     2075
     2076People typically define a separate test @emph{system} to hold the tests.
     2077Doing this avoids unnecessarily adding a test framework as a dependency
     2078on a library.  For example, one might have
     2079@lisp
     2080(defsystem foo
     2081  :in-order-to ((test-op (test-op "foo/test")))
     2082 ...)
     2083
     2084(defsystem foo/test
     2085  :depends-on (foo fiveam) ; fiveam is a test framework library
     2086  ...)
     2087@end lisp
     2088
     2089Then one defines @code{perform} methods on
     2090@code{test-op} such as the following:
     2091@lisp
     2092(defsystem foo/test
     2093  :depends-on (foo fiveam) ; fiveam is a test framework library
     2094  :perform (test-op (o s)
     2095                    (uiop:symbol-call :fiveam  '#:run!
     2096                       (uiop:find-symbol* '#:foo-test-suite
     2097                                            :foo-tests)))
     2098  ...)
     2099@end lisp
     2100
     2101@end deffn
     2102
     2103
     2104
     2105@deffn Operation @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op}, @code{lib-op}, @code{monolithic-lib-op}, @code{dll-op}, @code{monolithic-dll-op}, @code{image-op}, @code{program-op}
     2106
     2107These are ``bundle'' operations, that can create a single-file ``bundle''
     2108for all the contents of each system in an application,
     2109or for the entire application.
     2110
     2111@code{compile-bundle-op} will create a single fasl file for each of the systems needed,
     2112grouping all its many fasls in one,
     2113so you can deliver each system as a single fasl
     2114@code{monolithic-compile-bundle-op} will create a single fasl file for the target system
     2115and all its dependencies,
     2116so you can deliver your entire application as a single fasl.
     2117@code{load-bundle-op} will load the output of @code{compile-bundle-op}.
     2118Note that if it the output is not up-to-date,
     2119@code{compile-bundle-op} may load the intermediate fasls as a side-effect.
     2120Bundling fasls together matters a lot on ECL,
     2121where the dynamic linking involved in loading tens of individual fasls
     2122can be noticeably more expensive than loading a single one.
     2123
     2124NB: @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op} were respectively called
     2125@code{fasl-op}, @code{monolithic-fasl-op}, @code{load-fasl-op}, @code{monolithic-load-fasl-op}, @code{binary-op}, @code{monolithic-binary-op} before ASDF 3.1.
     2126The old names still exist for backward compatibility,
     2127though they poorly label what is going on.
     2128
     2129Once you have created a fasl with @code{compile-bundle-op},
     2130you can use @code{precompiled-system} to deliver it in a way
     2131that is compatible with clients having dependencies on your system,
     2132whether it is distributed as source or as a single binary;
     2133the @file{.asd} file to be delivered with the fasl will look like this:
     2134@example
     2135(defsystem :mysystem :class :precompiled-system
     2136  :fasl (some expression that will evaluate to a pathname))
     2137@end example
     2138Or you can use @code{deliver-asd-op} to let ASDF create such a system for you
     2139as well as the @code{compile-bundle-op} output,
     2140or @code{monolithic-deliver-asd-op}.
     2141This allows you to deliver code for your systems or applications
     2142as a single file.
     2143Of course, if you want to test the result in the current image,
     2144@emph{before} you try to use any newly created @file{.asd} files,
     2145you should not forget to @code{(asdf:clear-configuration)}
     2146or at least @code{(asdf:clear-source-registry)},
     2147so it re-populates the source-registry from the filesystem.
     2148
     2149The @code{program-op} operation will create an executable program
     2150from the specified system and its dependencies.
     2151You can use UIOP for its pre-image-dump hooks, its post-image-restore hooks,
     2152and its access to command-line arguments.
     2153And you can specify an entry point @code{my-app:main}
     2154by specifying in your @code{defsystem}
     2155the option @code{:entry-point "my-app:main"}.
     2156Depending on your implementation,
     2157running @code{(asdf:operate 'asdf:program-op :my-app)}
     2158may quit the current Lisp image upon completion.
     2159See the example in
     2160@file{test/hello-world-example.asd} and @file{test/hello.lisp},
     2161as built and tested by
     2162@file{test/test-program.script} and @file{test/make-hello-world.lisp}.
     2163@code{image-op} will dump an image that may not be standalone
     2164and does not start its own function,
     2165but follows the usual execution convention of the underlying Lisp,
     2166just with more code pre-loaded,
     2167for use as an intermediate build result or with a wrapper invocation script.
     2168
     2169There is also @code{lib-op}
     2170for building a linkable @file{.a} file (Windows: @file{.lib})
     2171from all linkable object dependencies (FFI files, and on ECL, Lisp files too),
     2172and its monolithic equivalent @code{monolithic-lib-op}.
     2173And there is also @code{dll-op}
     2174(respectively its monolithic equivalent @code{monolithic-lib-op})
     2175for building a linkable @file{.so} file
     2176(Windows: @file{.dll}, MacOS X: @file{.dynlib})
     2177to create a single dynamic library
     2178for all the extra FFI code to be linked into each of your systems
     2179(respectively your entire application).
     2180
     2181All these ``bundle'' operations are available since ASDF 3
     2182on all actively supported Lisp implementations,
     2183but may be unavailable on unmaintained legacy implementations.
     2184This functionality was previously available for select implementations,
     2185as part of a separate system @code{asdf-bundle},
     2186itself descended from the ECL-only @code{asdf-ecl}.
     2187
     2188The pathname of the output of bundle operations
     2189is subject to output-translation as usual,
     2190unless the operation is equal to
     2191the @code{:build-operation} argument to @code{defsystem}.
     2192This behavior is not very satisfactory and may change in the future.
     2193Maybe you have suggestions on how to better configure it?
     2194@end deffn
     2195
     2196@deffn Operation @code{concatenate-source-op}, @code{monolithic-concatenate-source-op}, @code{load-concatenated-source-op}, @code{compile-concatenated-source-op}, @code{load-compiled-concatenated-source-op}, @code{monolithic-load-concatenated-source-op}, @code{monolithic-compile-concatenated-source-op}, @code{monolithic-load-compiled-concatenated-source-op}
     2197
     2198These operations, as their respective names indicate,
     2199will concatenate all the @code{cl-source-file} source files in a system
     2200(or in a system and all its dependencies, if monolithic),
     2201in the order defined by dependencies,
     2202then load the result, or compile and then load the result.
     2203
     2204These operations are useful to deliver a system or application
     2205as a single source file,
     2206and for testing that said file loads properly, or compiles and then loads properly.
     2207
     2208ASDF itself is delivered as a single source file this way,
     2209using @code{monolithic-concatenate-source-op},
     2210prepending a prelude and the @code{uiop} library
     2211before the @code{asdf/defsystem} system itself.
     2212@end deffn
     2213
     2214
     2215@node  Creating new operations,  , Predefined operations of ASDF, Operations
     2216@comment  node-name,  next,  previous,  up
     2217@subsection Creating new operations
     2218
     2219ASDF was designed to be extensible in an object-oriented fashion.
     2220To teach ASDF new tricks, a programmer can implement the behaviour he wants
     2221by creating a subclass of @code{operation}.
     2222
     2223ASDF's pre-defined operations are in no way ``privileged'',
     2224but it is requested that developers never use the @code{asdf} package
     2225for operations they develop themselves.
     2226The rationale for this rule is that we don't want to establish a
     2227``global asdf operation name registry'',
     2228but also want to avoid name clashes.
     2229
     2230Your operation @emph{must} usually provide methods
     2231for one or more of the following generic functions:
     2232
     2233@itemize
     2234
     2235@findex perform
     2236@item @code{perform}
     2237Unless your operation, like @code{prepare-op},
     2238is for dependency propagation only,
     2239the most important function for which to define a method
     2240is usually @code{perform},
     2241which will be called to perform the operation on a specified component,
     2242after all dependencies have been performed.
     2243
     2244The @code{perform} method must call @code{input-files} and @code{output-files} (see below)
     2245to locate its inputs and outputs,
     2246because the user is allowed to override the method
     2247or tweak the output-translation mechanism.
     2248Perform should only use the primary value returned by @code{output-files}.
     2249If one and only one output file is expected,
     2250it can call @code{output-file} that checks that this is the case
     2251and returns the first and only list element.
     2252
     2253@findex output-files
     2254@item @code{output-files}
     2255If your perform method has any output,
     2256you must define a method for this function.
     2257for ASDF to determine where the outputs of performing operation lie.
     2258
     2259Your method may return two values, a list of pathnames, and a boolean.
     2260If the boolean is @code{nil} (or you fail to return multiple values),
     2261then enclosing @code{:around} methods may translate these pathnames,
     2262e.g. to ensure object files are somehow stored
     2263in some implementation-dependent cache.
     2264If the boolean is @code{t} then the pathnames are marked
     2265not be translated by the enclosing @code{:around} method.
     2266
     2267@findex component-depends-on
     2268@item @code{component-depends-on}
     2269If the action of performing the operation on a component has dependencies,
     2270you must define a method on @code{component-depends-on}.
     2271
     2272Your method will take as specialized arguments
     2273an operation and a component which together identify an action,
     2274and return a list of entries describing actions that this action depends on.
     2275The format of entries is described below.
     2276
     2277It is @emph{strongly} advised that
     2278you should always append the results of @code{(call-next-method)}
     2279to the results of your method,
     2280or ``interesting'' failures will likely occur,
     2281unless you're a true specialist of ASDF internals.
     2282It is unhappily too late to compatibly use the @code{append} method combination,
     2283but conceptually that's the protocol that is being manually implemented.
     2284
     2285Each entry returned by @code{component-depends-on} is itself a list.
     2286
     2287The first element of an entry is an operation designator:
     2288either an operation object designating itself, or
     2289a symbol that names an operation class
     2290(that ASDF will instantiate using @code{make-operation}).
     2291For instance, @code{load-op}, @code{compile-op} and @code{prepare-op}
     2292are common such names, denoting the respective operations.
     2293
     2294@c FIXME COERCE-NAME is referenced, but not defined.
     2295@findex coerce-name
     2296@findex find-component
     2297The rest of each entry is a list of component designators:
     2298either a component object designating itself,
     2299or an identifier to be used with @code{find-component}.
     2300@code{find-component} will be called with the current component's parent as parent,
     2301and the identifier as second argument.
     2302The identifier is typically a string,
     2303a symbol (to be downcased as per @code{coerce-name}),
     2304or a list of strings or symbols.
     2305In particular, the empty list @code{nil} denotes the parent itself.
     2306
     2307@end itemize
     2308
     2309An operation @emph{may} provide methods for the following generic functions:
     2310
     2311@itemize
     2312
     2313@item @code{input-files}
     2314@findex input-files
     2315A method for this function is often not needed,
     2316since ASDF has a pretty clever default @code{input-files} mechanism.
     2317You only need create a method if there are multiple ultimate input files,
     2318and/or the bottom one doesn't depend
     2319on the @code{component-pathname} of the component.
     2320
     2321@item @code{operation-done-p}
     2322@findex operation-done-p
     2323You only need to define a method on that function
     2324if you can detect conditions that invalidate previous runs of the operation,
     2325even though no filesystem timestamp has changed,
     2326in which case you return @code{nil} (the default is @code{t}).
     2327
     2328For instance, the method for @code{test-op} always returns @code{nil},
     2329so that tests are always run afresh.
     2330Of course, the @code{test-op} for your system could depend
     2331on a deterministically repeatable @code{test-report-op},
     2332and just read the results from the report files,
     2333in which case you could have this method return @code{t}.
     2334
     2335@end itemize
     2336
     2337Operations that print output should send that output to the standard
     2338CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
     2339
     2340@node Components, Dependencies, Operations, The object model of ASDF
     2341@comment  node-name,  next,  previous,  up
     2342@section Components
     2343@cindex component
     2344@cindex system
     2345@cindex system designator
     2346@cindex component designator
     2347@vindex *system-definition-search-functions*
    16522348
    16532349A @code{component} represents an individual source file or a group of source files,
    16542350and the things that get transformed into.
    1655 A @code{system} is a component at the top level of the component hierarchy.
     2351A @code{system} is a component at the top level of the component hierarchy,
     2352that can be found via @code{find-system}.
    16562353A @code{source-file} is a component representing a single source-file
    16572354and the successive output files into which it is transformed.
     
    16592356themselves source-files or further modules.
    16602357
    1661 An @code{Operation} represents a transformation that can be performed on a component,
    1662 turning them from source files to intermediate results to final outputs.
    1663 
    1664 A pair of an @code{operation} and a @code{component} is called an @code{action}.
    1665 An @code{action} represents a particular build step to be @code{perform}ed,
    1666 after all its dependencies have been fulfilled.
    1667 In the ASDF model, actions depend on other actions.
    1668 The term @emph{action} itself was used by Kent Pitman in his old article,
    1669 but was only used by ASDF hackers starting with the ASDF 2;
    1670 but the concept is ubiquitous since the very beginning of ASDF 1,
    1671 though previously implicit.
    1672 
    1673 Then, there are many @emph{functions} available
    1674 to users, extenders and implementers of ASDF
    1675 to use, define or implement the activities
    1676 that are part of building your software.
    1677 Though they manipulate @code{action}s,
    1678 most of these functions do not take as an argument
    1679 a reified pair (a @code{cons} cell) of an operation and a component;
    1680 instead, they usually take two separate arguments,
    1681 which allows to take advantage of the power CLOS-style multiple dispatch
    1682 for fun and profit.
    1683 
    1684 There are many @emph{hooks} in which to add functionality,
    1685 by customizing the behavior of existing @emph{functions}.
    1686 
    1687 Last but not least is the notion of @emph{dependency} between two actions.
    1688 The structure of dependencies between actions is
    1689 a directed @emph{dependency graph}.
    1690 ASDF is invoked by being told to @emph{operate}
    1691 with some @emph{operation} on some toplevel @emph{system};
    1692 it will then @emph{traverse} the graph and build a @emph{plan}
    1693 that follows its structure.
     2358A @dfn{system designator} is a system itself,
     2359or a string or symbol that behaves just like any other component name
     2360(including with regard to the case conversion rules for component names).
     2361
     2362A @dfn{component designator}, relative to a base component,
     2363is either a component itself,
     2364or a string or symbol,
     2365or a list of designators.
     2366
     2367@defun find-system system-designator @Aoptional{} (error-p t)
     2368
     2369Given a system designator, @code{find-system} finds and returns a system.
     2370If no system is found, an error of type
     2371@code{missing-component} is thrown,
     2372or @code{nil} is returned if @code{error-p} is false.
     2373
     2374To find and update systems, @code{find-system} funcalls each element
     2375in the @code{*system-definition-search-functions*} list,
     2376expecting a pathname to be returned, or a system object,
     2377from which a pathname may be extracted, and that will be registered.
     2378The resulting pathname (if any) is loaded
     2379if one of the following conditions is true:
     2380
     2381@itemize
     2382@item
     2383there is no system of that name in memory
     2384@item
     2385the pathname is different from that which was previously loaded
     2386@item
     2387the file's @code{last-modified} time exceeds the @code{last-modified} time
     2388of the system in memory
     2389@end itemize
     2390
     2391When system definitions are loaded from @file{.asd} files,
     2392a new scratch package is created for them to load into,
     2393so that different systems do not overwrite each others operations.
     2394The user may also wish to (and is recommended to)
     2395include @code{defpackage} and @code{in-package} forms
     2396in his system definition files, however,
     2397so that they can be loaded manually if need be.
     2398
     2399The default value of @code{*system-definition-search-functions*}
     2400is a list of two functions.
     2401The first function looks in each of the directories given
     2402by evaluating members of @code{*central-registry*}
     2403for a file whose name is the name of the system and whose type is @file{asd}.
     2404The first such file is returned,
     2405whether or not it turns out to actually define the appropriate system.
     2406The second function does something similar,
     2407for the directories specified in the @code{source-registry}.
     2408Hence, it is strongly advised to define a system
     2409@var{foo} in the corresponding file @var{foo.asd}.
     2410@end defun
     2411
     2412@defun find-component base path
     2413
     2414Given a @var{base} component (or designator for such),
     2415and a @var{path}, find the component designated by the @var{path}
     2416starting from the @var{base}.
     2417
     2418If @var{path} is a component object, it designates itself,
     2419independently from the base.
     2420
     2421@findex coerce-name
     2422If @var{path} is a string, or symbol denoting a string via @code{coerce-name},
     2423then @var{base} is resolved to a component object,
     2424which must be a system or module,
     2425and the designated component is the child named by the @var{path}.
     2426
     2427If @var{path} is a @code{cons} cell,
     2428@code{find-component} with the base and the @code{car} of the @var{path},
     2429and the resulting object is used as the base for a tail call
     2430to @code{find-component} with the @code{car} of the @var{path}.
     2431
     2432If @var{base} is a component object, it designates itself.
     2433
     2434If @var{base} is null, then @var{path} is used as the base, with @code{nil} as the path.
     2435
     2436If @var{base} is a string, or symbol denoting a string via @code{coerce-name},
     2437it designates a system as per @code{find-system}.
     2438
     2439If @var{base} is a @code{cons} cell, it designates the component found by
     2440@code{find-component} with its @code{car} as base and @code{cdr} as path.
     2441@end defun
     2442
     2443
     2444@menu
     2445* Common attributes of components::
     2446* Pre-defined subclasses of component::
     2447* Creating new component types::
     2448@end menu
     2449
     2450@node  Common attributes of components, Pre-defined subclasses of component, Components, Components
     2451@comment  node-name,  next,  previous,  up
     2452@subsection Common attributes of components
     2453
     2454All components, regardless of type, have the following attributes.
     2455All attributes except @code{name} are optional.
     2456
     2457@subsubsection Name
     2458@findex coerce-name
     2459A component name is a string or a symbol.
     2460If a symbol, its name is taken and lowercased.  This translation is
     2461performed by the exported function @code{coerce-name}.
     2462
     2463Unless overridden by a @code{:pathname} attribute,
     2464the name will be interpreted as a pathname specifier according
     2465to a Unix-style syntax.
     2466@xref{The defsystem grammar,,Pathname specifiers}.
     2467
     2468@subsubsection Version identifier
     2469@findex version-satisfies
     2470@cindex :version
     2471
     2472This optional attribute specifies a version for the current component.
     2473The version should typically be a string of integers separated by dots,
     2474for example @samp{1.0.11}.
     2475For more information on version specifiers, see @ref{The defsystem grammar}.
     2476
     2477A version may then be queried by the generic function @code{version-satisfies},
     2478to see if @code{:version} dependencies are satisfied,
     2479and when specifying dependencies, a constraint of minimal version to satisfy
     2480can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
     2481
     2482Note that in the wild, we typically see version numbering
     2483only on components of type @code{system}.
     2484Presumably it is much less useful within a given system,
     2485wherein the library author is responsible to keep the various files in synch.
     2486
     2487@subsubsection Required features
     2488@anchor{required-features}
     2489
     2490Traditionally defsystem users have used @code{#+} reader conditionals
     2491to include or exclude specific per-implementation files.
     2492For example, CFFI, the portable C foreign function interface contained
     2493lines like:
     2494@lisp
     2495     #+sbcl       (:file "cffi-sbcl")
     2496@end lisp
     2497An unfortunate side effect of this approach is that no single
     2498implementation can read the entire system.
     2499This causes problems if, for example, one wished to design an @code{archive-op}
     2500that would create an archive file containing all the sources, since
     2501for example the file @code{cffi-sbcl.lisp} above would be invisible when
     2502running the @code{archive-op} on any implementation other than SBCL.
     2503
     2504Starting with ASDF 3,
     2505components may therefore have an @code{:if-feature} option.
     2506The value of this option should be
     2507a feature expression using the same syntax as @code{#+} does.
     2508If that feature expression evaluates to false, any reference to the component will be ignored
     2509during compilation, loading and/or linking.
     2510Since the expression is read by the normal reader,
     2511you must explicitly prefix your symbols with @code{:} so they be read as keywords;
     2512this is as contrasted with the @code{#+} syntax
     2513that implicitly reads symbols in the keyword package by default.
     2514
     2515For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
     2516the given component is only to be compiled and loaded
     2517when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
     2518You cannot write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
     2519since the symbols would not be read as keywords.
     2520
     2521@xref{if-feature-option}.
     2522
     2523@subsubsection Dependencies
     2524
     2525This attribute specifies dependencies of the component on its siblings.
     2526It is optional but often necessary.
     2527
     2528There is an excitingly complicated relationship between the initarg
     2529and the method that you use to ask about dependencies
     2530
     2531Dependencies are between (operation component) pairs.
     2532In your initargs for the component, you can say
     2533
     2534@lisp
     2535:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
     2536              (load-op (load-op "foo")))
     2537@end lisp
     2538
     2539This means the following things:
     2540@itemize
     2541@item
     2542before performing compile-op on this component, we must perform
     2543load-op on @var{a} and @var{b}, and compile-op on @var{c},
     2544@item
     2545before performing @code{load-op}, we have to load @var{foo}
     2546@end itemize
     2547
     2548The syntax is approximately
     2549
     2550@verbatim
     2551(this-op @{(other-op required-components)@}+)
     2552
     2553simple-component-name := string
     2554                      |  symbol
     2555
     2556required-components := simple-component-name
     2557                     | (required-components required-components)
     2558
     2559component-name := simple-component-name
     2560                | (:version simple-component-name minimum-version-object)
     2561@end verbatim
     2562
     2563Side note:
     2564
     2565This is on a par with what ACL defsystem does.
     2566mk-defsystem is less general: it has an implied dependency
     2567
     2568@verbatim
     2569  for all source file x, (load x) depends on (compile x)
     2570@end verbatim
     2571
     2572and using a @code{:depends-on} argument to say that @var{b} depends on
     2573@var{a} @emph{actually} means that
     2574
     2575@verbatim
     2576  (compile b) depends on (load a)
     2577@end verbatim
     2578
     2579This is insufficient for e.g. the McCLIM system, which requires that
     2580all the files are loaded before any of them can be compiled ]
     2581
     2582End side note
     2583
     2584In ASDF, the dependency information for a given component and operation
     2585can be queried using @code{(component-depends-on operation component)},
     2586which returns a list
     2587
     2588@lisp
     2589((load-op "a") (load-op "b") (compile-op "c") ...)
     2590@end lisp
     2591
     2592@code{component-depends-on} can be subclassed for more specific
     2593component/operation types: these need to @code{(call-next-method)}
     2594and append the answer to their dependency, unless
     2595they have a good reason for completely overriding the default dependencies.
     2596
     2597If it weren't for CLISP, we'd be using @code{LIST} method
     2598combination to do this transparently.
     2599But, we need to support CLISP.
     2600If you have the time for some CLISP hacking,
     2601I'm sure they'd welcome your fixes.
     2602@c Doesn't CLISP now support LIST method combination?
     2603
     2604A minimal version can be specified for a component you depend on
     2605(typically another system), by specifying @code{(:version "other-system" "1.2.3")}
     2606instead of simply @code{"other-system"} as the dependency.
     2607See the discussion of the semantics of @code{:version}
     2608in the defsystem grammar.
     2609
     2610@c FIXME: Should have cross-reference to "Version specifiers" in the
     2611@c defsystem grammar, but the cross-referencing is so broken by
     2612@c insufficient node breakdown that I have not put one in.
     2613
     2614
     2615@subsubsection pathname
     2616
     2617This attribute is optional and if absent (which is the usual case),
     2618the component name will be used.
     2619
     2620@xref{The defsystem grammar,,Pathname specifiers},
     2621for an explanation of how this attribute is interpreted.
     2622
     2623Note that the @code{defsystem} macro (used to create a ``top-level'' system)
     2624does additional processing to set the filesystem location of
     2625the top component in that system.
     2626This is detailed elsewhere. @xref{Defining systems with defsystem}.
     2627
     2628
     2629@subsubsection properties
     2630
     2631This attribute is optional.
     2632
     2633Packaging systems often require information about files or systems
     2634in addition to that specified by ASDF's pre-defined component attributes.
     2635Programs that create vendor packages out of ASDF systems therefore
     2636have to create ``placeholder'' information to satisfy these systems.
     2637Sometimes the creator of an ASDF system may know the additional
     2638information and wish to provide it directly.
     2639
     2640@code{(component-property component property-name)} and
     2641associated @code{setf} method will allow
     2642the programmatic update of this information.
     2643Property names are compared as if by @code{EQL},
     2644so use symbols or keywords or something.
     2645
     2646@menu
     2647* Pre-defined subclasses of component::
     2648* Creating new component types::
     2649@end menu
     2650
     2651@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
     2652@comment  node-name,  next,  previous,  up
     2653@subsection Pre-defined subclasses of component
     2654
     2655@deffn Component source-file
     2656
     2657A source file is any file that the system does not know how to
     2658generate from other components of the system.
     2659
     2660Note that this is not necessarily the same thing as
     2661``a file containing data that is typically fed to a compiler''.
     2662If a file is generated by some pre-processor stage
     2663(e.g. a @file{.h} file from @file{.h.in} by autoconf)
     2664then it is not, by this definition, a source file.
     2665Conversely, we might have a graphic file
     2666that cannot be automatically regenerated,
     2667or a proprietary shared library that we received as a binary:
     2668these do count as source files for our purposes.
     2669
     2670Subclasses of source-file exist for various languages.
     2671@emph{FIXME: describe these.}
     2672@end deffn
     2673
     2674@deffn Component module
     2675
     2676A module is a collection of sub-components.
     2677
     2678A module component has the following extra initargs:
     2679
     2680@itemize
     2681@item
     2682@code{:components} the components contained in this module
     2683
     2684@item
     2685@code{:default-component-class}
     2686All children components which don't specify their class explicitly
     2687are inferred to be of this type.
     2688
     2689@item
     2690@code{:if-component-dep-fails}
     2691This attribute was removed in ASDF 3. Do not use it.
     2692Use @code{:if-feature} instead (@pxref{required-features}, and @pxref{if-feature-option}).
     2693
     2694@item
     2695@code{:serial} When this attribute is set,
     2696each subcomponent of this component is assumed to depend on all subcomponents
     2697before it in the list given to @code{:components}, i.e.
     2698all of them are loaded before a compile or load operation is performed on it.
     2699
     2700@end itemize
     2701
     2702The default operation knows how to traverse a module, so
     2703most operations will not need to provide methods specialised on modules.
     2704
     2705@code{module} may be subclassed to represent components such as
     2706foreign-language linked libraries or archive files.
     2707@end deffn
     2708
     2709@deffn Component system
     2710
     2711@code{system} is a subclass of @code{module}.
     2712
     2713A system is a module with a few extra attributes for documentation
     2714purposes; these are given elsewhere.
     2715@xref{The defsystem grammar}.
     2716
     2717Users can create new classes for their systems:
     2718the default @code{defsystem} macro takes a @code{:class} keyword argument.
     2719@end deffn
     2720
     2721@node  Creating new component types,  , Pre-defined subclasses of component, Components
     2722@comment  node-name,  next,  previous,  up
     2723@subsection Creating new component types
     2724
     2725New component types are defined by subclassing one of the existing
     2726component classes and specializing methods on the new component class.
     2727
     2728@emph{FIXME: this should perhaps be explained more throughly,
     2729not only by example ...}
     2730
     2731As an example, suppose we have some implementation-dependent
     2732functionality that we want to isolate
     2733in one subdirectory per Lisp implementation our system supports.
     2734We create a subclass of
     2735@code{cl-source-file}:
     2736
     2737@lisp
     2738(defclass unportable-cl-source-file (cl-source-file)
     2739  ())
     2740@end lisp
     2741
     2742Function @code{asdf:implementation-type} (exported since 2.014.14)
     2743gives us the name of the subdirectory.
     2744All that's left is to define how to calculate the pathname
     2745of an @code{unportable-cl-source-file}.
     2746
     2747@lisp
     2748(defmethod component-pathname ((component unportable-cl-source-file))
     2749  (merge-pathnames*
     2750   (parse-unix-namestring (format nil "~(~A~)/" (asdf:implementation-type)))
     2751   (call-next-method)))
     2752@end lisp
     2753
     2754The new component type is used in a @code{defsystem} form in this way:
     2755
     2756@lisp
     2757(defsystem :foo
     2758    :components
     2759    ((:file "packages")
     2760     ...
     2761     (:unportable-cl-source-file "threads"
     2762      :depends-on ("packages" ...))
     2763     ...
     2764    )
     2765@end lisp
     2766
     2767@node Dependencies, Functions, Components, The object model of ASDF
     2768@section Dependencies
     2769@c FIXME: Moved this material here, but it isn't very comfortable
     2770@c here....  Also needs to be revised to be coherent.
     2771
    16942772To be successfully buildable, this graph of actions but be acyclic.
    16952773If, as a user, extender or implementer of ASDF, you fail
     
    17172795ensuring that all the parent's dependencies are (compiled and) loaded
    17182796before the child component may be compiled and loaded.
    1719 Yet other operations, such as @code{test-op} or @code{load-fasl-op}
     2797Yet other operations, such as @code{test-op} or @code{load-bundle-op}
    17202798remain at the system level, and are not propagated along the hierarchy,
    17212799but instead do something global on the system.
    17222800
    1723 @menu
    1724 * Operations::
    1725 * Components::
    1726 * Functions::
    1727 @end menu
    1728 
    1729 @node  Operations, Components, The object model of ASDF, The object model of ASDF
    1730 @comment  node-name,  next,  previous,  up
    1731 @section Operations
    1732 @cindex operation
    1733 
    1734 An @dfn{operation} object of the appropriate type is instantiated
    1735 whenever the user wants to do something with a system like
    1736 
    1737 @itemize
    1738 @item compile all its files
    1739 @item load the files into a running lisp environment
    1740 @item copy its source files somewhere else
    1741 @end itemize
    1742 
    1743 Operations can be invoked directly, or examined
    1744 to see what their effects would be without performing them.
    1745 There are a bunch of methods specialised on operation and component type
    1746 that actually do the grunt work.
    1747 Operations are invoked on systems via @code{operate} (@pxref{operate}).
    1748 
    1749 ASDF contains a number of pre-defined @t{operation} classes for common,
    1750 and even fairly uncommon tasks that you might want to do with it.
    1751 In addition, ASDF contains ``abstract'' @t{operation} classes that
    1752 programmers can use as building blocks to define ASDF extensions.  We
    1753 discuss these in turn below.
    1754 
    1755 @c The operation object contains whatever state is relevant for this purpose
    1756 @c (perhaps a list of visited nodes, for example)
    1757 @c but primarily is a nice thing to specialise operation methods on
    1758 @c and easier than having them all be @code{EQL} methods.
    1759 
    1760 @menu
    1761 * Predefined operations of ASDF::
    1762 * Creating new operations::
    1763 @end menu
    1764 
    1765 Operations are invoked on systems via @code{operate}.
    1766 @anchor{operate}
    1767 @deffn {Generic function} @code{operate} @var{operation} @var{system} @Arest @var{initargs} @Akey @code{force} @code{force-not} @code{verbose} @AallowOtherKeys
    1768 @deffnx {Generic function} @code{oos} @var{operation} @var{system} @Arest @var{initargs} @Akey @AallowOtherKeys
    1769 @code{operate} invokes @var{operation} on @var{system}.
    1770 @code{oos} is a synonym for @code{operate}.
    1771 
    1772 @var{operation} is a symbol that is passed, along with the supplied
    1773 @var{initargs}, to @code{make-instance} to create the operation object.
    1774 @var{system} is a system designator.
    1775 
    1776 The @var{initargs} are passed to the @code{make-instance} call
    1777 when creating the operation object.
    1778 Note that dependencies may cause the operation
    1779 to invoke other operations on the system or its components:
    1780 the new operations will be created
    1781 with the same @var{initargs} as the original one.
    1782 
    1783 If @var{force} is @code{:all}, then all systems
    1784 are forced to be recompiled even if not modified since last compilation.
    1785 If @var{force} is @code{t}, then only the system being loaded
    1786 is forced to be recompiled even if not modified since last compilation,
    1787 but other systems are not affected.
    1788 If @var{force} is a list, then it specifies a list of systems that
    1789 are forced to be recompiled even if not modified since last compilation.
    1790 If @var{force-not} is @code{:all}, then all systems
    1791 are forced not to be recompiled even if modified since last compilation.
    1792 If @var{force-not} is @code{t}, then all systems but the system being loaded
    1793 are forced not to be recompiled even if modified since last compilation
    1794 (note: this was changed in ASDF 3.1.1).
    1795 If @var{force-not} is a list, then it specifies a list of systems that
    1796 are forced not to be recompiled even if modified since last compilation.
    1797 
    1798 Both @var{force} and @var{force-not} apply to systems that are dependencies and were already compiled.
    1799 @var{force-not} takes precedences over @var{force},
    1800 as it should, really, but unhappily only since ASDF 3.1.1.
    1801 Moreover, systems the name of which is member of the set @var{*immutable-systems*}
    1802 (represented as an equal hash-table) are always considered @var{forced-not}, and
    1803 even their @file{.asd} is not refreshed from the filesystem.
    1804 
    1805 To see what @code{operate} would do, you can use:
    1806 @example
    1807 (asdf:traverse operation-class system-name)
    1808 @end example
    1809 
    1810 @end deffn
    1811 
    1812 
    1813 
    1814 @node Predefined operations of ASDF, Creating new operations, Operations, Operations
    1815 @comment  node-name,  next,  previous,  up
    1816 @subsection Predefined operations of ASDF
    1817 
    1818 All the operations described in this section are in the @code{asdf} package.
    1819 They are invoked via the @code{operate} generic function.
    1820 
    1821 @lisp
    1822 (asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
    1823 @end lisp
    1824 
    1825 @deffn Operation @code{compile-op}
    1826 
    1827 This operation compiles the specified component.
    1828 A @code{cl-source-file} will be @code{compile-file}'d.
    1829 All the children and dependencies of a system or module
    1830 will be recursively compiled by @code{compile-op}.
    1831 
    1832 @code{compile-op} depends on @code{prepare-op} which
    1833 itself depends on a @code{load-op} of all of a component's dependencies,
    1834 as well as of its parent's dependencies.
    1835 When @code{operate} is called on @code{compile-op},
    1836 all these dependencies will be loaded as well as compiled;
    1837 yet, some parts of the system main remain unloaded,
    1838 because nothing depends on them.
    1839 Use @code{load-op} to load a system.
    1840 @end deffn
    1841 
    1842 @deffn Operation @code{load-op}
    1843 
    1844 This operation loads the compiled code for a specified component.
    1845 A @code{cl-source-file} will have its compiled fasl @code{load}ed,
    1846 which fasl is the output of @code{compile-op} that @code{load-op} depends on.
    1847 All the children and dependencies of a system or module
    1848 will be recursively loaded by @code{load-op}.
    1849 
    1850 @code{load-op} depends on @code{prepare-op} which
    1851 itself depends on a @code{load-op} of all of a component's dependencies,
    1852 as well as of its parent's dependencies.
    1853 @end deffn
    1854 
    1855 @deffn Operation @code{prepare-op}
    1856 
    1857 This operation ensures that the dependencies of a component
    1858 and its recursive parents are loaded (as per @code{load-op}),
    1859 as a prerequisite before @code{compile-op} and @code{load-op} operations
    1860 may be performed on a given component.
    1861 @end deffn
    1862 
    1863 @deffn Operation @code{load-source-op}, @code{prepare-source-op}
    1864 
    1865 @code{load-source-op} will load the source for the files in a module
    1866 rather than they compiled fasl output.
    1867 It has a @code{prepare-source-op} analog to @code{prepare-op},
    1868 that ensures the dependencies are themselves loaded via @code{load-source-op}.
    1869 
    1870 There is no provision in ASDF for ensuring that
    1871 some components are always loaded as source, while others are always compiled.
    1872 While this idea often comes up in discussions,
    1873 it actually doesn't play well with either the linking model of ECL
    1874 or with various bundle operations (see below), and is eventually not workable;
    1875 also the dependency model of ASDF would have to be modified incompatibly
    1876 to allow for such trick.
    1877 If your code doesn't compile cleanly, fix it.
    1878 If compilation makes it slow, use @code{declaim} or @code{eval-when}
    1879 to adjust your compiler settings,
    1880 or eschew compilation by @code{eval}uating a quoted source form at load-time.
    1881 @end deffn
    1882 
    1883 @anchor{test-op}
    1884 @deffn Operation @code{test-op}
    1885 
    1886 This operation will perform some tests on the module.
    1887 The default method will do nothing.
    1888 The default dependency is to require
    1889 @code{load-op} to be performed on the module first.
    1890 The default @code{operation-done-p} is that the operation is @emph{never} done
    1891 ---
    1892 we assume that if you invoke the @code{test-op},
    1893 you want to test the system, even if you have already done so.
    1894 
    1895 The results of this operation are not defined by ASDF.
    1896 It has proven difficult to define how the test operation
    1897 should signal its results to the user
    1898 in a way that is compatible with all of the various test libraries
    1899 and test techniques in use in the community.
    1900 
    1901 People typically define @code{test-op} methods like thus:
    1902 @example
    1903 (defmethod perform ((o asdf:test-op)
    1904                     (s (eql (asdf:find-system @var{:my-system}))))
    1905   (asdf:load-system @var{:my-system-test})
    1906   (funcall (read-from-string "my-system-test:test-suite")))
    1907 @end example
    1908 
    1909 Using @code{load-system} in the perform method
    1910 rather than an @code{:in-order-to} dependency,
    1911 is sometimes necessary for backward compatibility with ASDF 2 and older,
    1912 to avoid circular dependencies that could arise
    1913 because of the way these old versions propagate dependencies.
    1914 
    1915 If you don't care for compatibility with ASDF 2,
    1916 you could use the following options in your @code{defsystem} form:
    1917 @example
    1918   :in-order-to ((test-op (load-op :my-system-test)))
    1919   :perform (test-op (o c) (symbol-call :my-system-test :test-suite))
    1920 @end example
    1921 @end deffn
    1922 
    1923 @deffn Operation @code{fasl-op}, @code{monolithic-fasl-op}, @code{load-fasl-op}, @code{binary-op}, @code{monolithic-binary-op}, @code{lib-op}, @code{monolithic-lib-op}, @code{dll-op}, @code{monolithic-dll-op}, @code{program-op}
    1924 
    1925 These are ``bundle'' operations, that can create a single-file ``bundle''
    1926 for all the contents of each system in an application,
    1927 or for the entire application.
    1928 
    1929 @code{fasl-op} will create a single fasl file for each of the systems needed,
    1930 grouping all its many fasls in one,
    1931 so you can deliver each system as a single fasl.
    1932 @code{monolithic-fasl-op} will create a single fasl file for target system
    1933 and all its dependencies,
    1934 so you can deliver your entire application as a single fasl.
    1935 @code{load-fasl-op} will load the output of @code{fasl-op}
    1936 (though if it the output is not up-to-date,
    1937 it will load the intermediate fasls indeed as part of building it);
    1938 this matters a lot on ECL, where the dynamic linking involved in loading
    1939 tens of individual fasls can be noticeably more expensive
    1940 than loading a single one.
    1941 
    1942 Once you have created a fasl with @code{fasl-op},
    1943 you can use @code{precompiled-system} to deliver it in a way
    1944 that is compatible with clients having dependencies on your system,
    1945 whether it is distributed as source or as a single binary;
    1946 the @file{.asd} file to be delivered with the fasl will look like this:
    1947 @example
    1948 (defsystem :mysystem :class :precompiled-system
    1949     :fasl (some expression that will evaluate to a pathname))
    1950 @end example
    1951 Or you can use @code{binary-op} to let ASDF create such a system for you
    1952 as well as the @code{fasl-op} output, or @code{monolithic-binary-op}.
    1953 This allows you to deliver code for your systems or applications
    1954 as a single file.
    1955 Of course, if you want to test the result in the current image,
    1956 @emph{before} you try to use any newly created @file{.asd} files,
    1957 you should not forget to @code{(asdf:clear-configuration)}
    1958 or at least @code{(asdf:clear-source-registry)},
    1959 so it re-populates the source-registry from the filesystem.
    1960 
    1961 The @code{program-op} operation will create an executable program
    1962 from the specified system and its dependencies.
    1963 You can use UIOP for its pre-image-dump hooks, its post-image-restore hooks,
    1964 and its access to command-line arguments.
    1965 And you can specify an entry point @code{my-app:main}
    1966 by specifying in your @code{defsystem}
    1967 the option @code{:entry-point "my-app:main"}.
    1968 Depending on your implementation,
    1969 running @code{(asdf:operate 'asdf:program-op :my-app)}
    1970 may quit the current Lisp image upon completion.
    1971 See the example in
    1972 @file{test/hello-world-example.asd} and @file{test/hello.lisp},
    1973 as built and tested by
    1974 @file{test/test-program.script} and @file{test/make-hello-world.lisp}.
    1975 
    1976 There is also @code{lib-op}
    1977 for building a linkable @file{.a} file (Windows: @file{.lib})
    1978 from all linkable object dependencies (FFI files, and on ECL, Lisp files too),
    1979 and its monolithic equivalent @code{monolithic-lib-op}.
    1980 And there is also @code{dll-op}
    1981 (respectively its monolithic equivalent @code{monolithic-lib-op})
    1982 for building a linkable @file{.so} file
    1983 (Windows: @file{.dll}, MacOS X: @file{.dynlib})
    1984 to create a single dynamic library
    1985 for all the extra FFI code to be linked into each of your systems
    1986 (respectively your entire application).
    1987 
    1988 All these ``bundle'' operations are available since ASDF 3
    1989 on all actively supported Lisp implementations,
    1990 but may be unavailable on unmaintained legacy implementations.
    1991 This functionality was previously available for select implementations,
    1992 as part of a separate system @code{asdf-bundle},
    1993 itself descended from the ECL-only @code{asdf-ecl}.
    1994 
    1995 The pathname of the output of bundle operations
    1996 is subject to output-translation as usual,
    1997 unless the operation is equal to
    1998 the @code{:build-operation} argument to @code{defsystem}.
    1999 This behavior is not very satisfactory and may change in the future.
    2000 Maybe you have suggestions on how to better configure it?
    2001 @end deffn
    2002 
    2003 @deffn Operation @code{concatenate-source-op}, @code{monolithic-concatenate-source-op}, @code{load-concatenated-source-op}, @code{compile-concatenated-source-op}, @code{load-compiled-concatenated-source-op}, @code{monolithic-load-concatenated-source-op}, @code{monolithic-compile-concatenated-source-op}, @code{monolithic-load-compiled-concatenated-source-op}
    2004 
    2005 These operation, as their respective names indicate,
    2006 consist in concatenating all @code{cl-source-file} source files in a system
    2007 (or in a system and all its dependencies, if monolithic),
    2008 in the order defined by dependencies,
    2009 then loading the result, or compiling then loading the result.
    2010 
    2011 These operations are useful to deliver a system or application
    2012 as a single source file,
    2013 and for testing that said file loads properly, or compiles then loads properly.
    2014 
    2015 ASDF itself is notably delivered as a single source file this way
    2016 using @code{monolithic-concatenate-source-op},
    2017 transcluding a prelude and the @code{uiop} library
    2018 before the @code{asdf/defsystem} system itself.
    2019 @end deffn
    2020 
    2021 
    2022 @node  Creating new operations,  , Predefined operations of ASDF, Operations
    2023 @comment  node-name,  next,  previous,  up
    2024 @subsection Creating new operations
    2025 
    2026 ASDF was designed to be extensible in an object-oriented fashion.
    2027 To teach ASDF new tricks, a programmer can implement the behaviour he wants
    2028 by creating a subclass of @code{operation}.
    2029 
    2030 ASDF's pre-defined operations are in no way ``privileged'',
    2031 but it is requested that developers never use the @code{asdf} package
    2032 for operations they develop themselves.
    2033 The rationale for this rule is that we don't want to establish a
    2034 ``global asdf operation name registry'',
    2035 but also want to avoid name clashes.
    2036 
    2037 Your operation @emph{must} usually provide methods
    2038 for one or more of the following generic functions:
    2039 
    2040 @itemize
    2041 
    2042 @item @code{perform}
    2043 Unless your operation, like @code{prepare-op},
    2044 is for dependency propagation only,
    2045 the most important function for which to define a method
    2046 is usually @code{perform},
    2047 which will be called to perform the operation on a specified component,
    2048 after all dependencies have been performed.
    2049 
    2050 The @code{perform} method must call @code{output-files} (see below)
    2051 to find out where to put its files,
    2052 because the user is allowed to override the method
    2053 or tweak the output-translation mechanism.
    2054 Perform should only use the primary value returned by @code{output-files}.
    2055 If one and only one output file is expected,
    2056 it can call @code{output-file} that checks that this is the case
    2057 and returns the first and only list element.
    2058 
    2059 @item @code{output-files}
    2060 If your perform method has any output,
    2061 you must define a method for this function.
    2062 for ASDF to determine where the outputs of performing operation lie.
    2063 
    2064 Your method may return two values, a list of pathnames, and a boolean.
    2065 If the boolean is @code{nil} (or you fail to return multiple values),
    2066 then enclosing @code{:around} methods may translate these pathnames,
    2067 e.g. to ensure object files are somehow stored
    2068 in some implementation-dependent cache.
    2069 If the boolean is @code{t} then the pathnames are marked
    2070 not be translated by the enclosing @code{:around} method.
    2071 
    2072 @item @code{component-depends-on}
    2073 If the action of performing the operation on a component has dependencies,
    2074 you must define a method on @code{component-depends-on}.
    2075 
    2076 Your method will take as specialized arguments
    2077 an operation and a component which together identify an action,
    2078 and return a list of entries describing actions that this action depends on.
    2079 The format of entries is described below.
    2080 
    2081 It is @emph{strongly} advised that
    2082 you should always append the results of @code{(call-next-method)}
    2083 to the results of your method,
    2084 or ``interesting'' failures will likely occur,
    2085 unless you're a true specialist of ASDF internals.
    2086 It is unhappily too late to compatibly use the @code{append} method combination,
    2087 but conceptually that's the protocol that is being manually implemented.
    2088 
    2089 Each entry returned by @code{component-depends-on} is itself a list.
    2090 
    2091 The first element of an entry is an operation designator:
    2092 either an operation object designating itself, or
    2093 a symbol that names an operation class
    2094 (that ASDF will instantiate using @code{make-operation}).
    2095 For instance, @code{load-op}, @code{compile-op} and @code{prepare-op}
    2096 are common such names, denoting the respective operations.
    2097 
    2098 The rest of each entry is a list of component designators:
    2099 either a component object designating itself,
    2100 or an identifier to be used with @code{find-component}.
    2101 @code{find-component} will be called with the current component's parent as parent,
    2102 and the identifier as second argument.
    2103 The identifier is typically a string,
    2104 a symbol (to be downcased as per @code{coerce-name}),
    2105 or a list of strings or symbols.
    2106 In particular, the empty list @code{nil} denotes the parent itself.
    2107 
    2108 @end itemize
    2109 
    2110 An operation @emph{may} provide methods for the following generic functions:
    2111 
    2112 @itemize
    2113 
    2114 @item @code{input-files}
    2115 A method for this function is often not needed,
    2116 since ASDF has a pretty clever default @code{input-files} mechanism.
    2117 You only need create a method if there are multiple ultimate input files,
    2118 and/or the bottom one doesn't depend
    2119 on the @code{component-pathname} of the component.
    2120 
    2121 @item @code{operation-done-p}
    2122 You only need to define a method on that function
    2123 if you can detect conditions that invalidate previous runs of the operation,
    2124 even though no filesystem timestamp has changed,
    2125 in which case you return @code{nil} (the default is @code{t}).
    2126 
    2127 For instance, the method for @code{test-op} always returns @code{nil},
    2128 so that tests are always run afresh.
    2129 Of course, the @code{test-op} for your system could depend
    2130 on a deterministically repeatable @code{test-report-op},
    2131 and just read the results from the report files,
    2132 in which case you could have this method return @code{t}.
    2133 
    2134 @end itemize
    2135 
    2136 Operations that print output should send that output to the standard
    2137 CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
    2138 
    2139 @node Components, Functions, Operations, The object model of ASDF
    2140 @comment  node-name,  next,  previous,  up
    2141 @section Components
    2142 @cindex component
    2143 @cindex system
    2144 @cindex system designator
    2145 @cindex component designator
    2146 @vindex *system-definition-search-functions*
    2147 
    2148 A @dfn{component} represents a source file or
    2149 (recursively) a collection of components.
    2150 A @dfn{system} is (roughly speaking) a top-level component
    2151 that can be found via @code{find-system}.
    2152 
    2153 A @dfn{system designator} is a system itself,
    2154 or a string or symbol that behaves just like any other component name
    2155 (including with regard to the case conversion rules for component names).
    2156 
    2157 A @dfn{component designator}, relative to a base component,
    2158 is either a component itself,
    2159 or a string or symbol,
    2160 or a list of designators.
    2161 
    2162 @defun find-system system-designator @Aoptional (error-p t)
    2163 
    2164 Given a system designator, @code{find-system} finds and returns a system.
    2165 If no system is found, an error of type
    2166 @code{missing-component} is thrown,
    2167 or @code{nil} is returned if @code{error-p} is false.
    2168 
    2169 To find and update systems, @code{find-system} funcalls each element
    2170 in the @code{*system-definition-search-functions*} list,
    2171 expecting a pathname to be returned, or a system object,
    2172 from which a pathname may be extracted, and that will be registered.
    2173 The resulting pathname (if any) is loaded
    2174 if one of the following conditions is true:
    2175 
    2176 @itemize
    2177 @item
    2178 there is no system of that name in memory
    2179 @item
    2180 the pathname is different from that which was previously loaded
    2181 @item
    2182 the file's @code{last-modified} time exceeds the @code{last-modified} time
    2183 of the system in memory
    2184 @end itemize
    2185 
    2186 When system definitions are loaded from @file{.asd} files,
    2187 a new scratch package is created for them to load into,
    2188 so that different systems do not overwrite each others operations.
    2189 The user may also wish to (and is recommended to)
    2190 include @code{defpackage} and @code{in-package} forms
    2191 in his system definition files, however,
    2192 so that they can be loaded manually if need be.
    2193 
    2194 The default value of @code{*system-definition-search-functions*}
    2195 is a list of two functions.
    2196 The first function looks in each of the directories given
    2197 by evaluating members of @code{*central-registry*}
    2198 for a file whose name is the name of the system and whose type is @file{asd}.
    2199 The first such file is returned,
    2200 whether or not it turns out to actually define the appropriate system.
    2201 The second function does something similar,
    2202 for the directories specified in the @code{source-registry}.
    2203 Hence, it is strongly advised to define a system
    2204 @var{foo} in the corresponding file @var{foo.asd}.
    2205 @end defun
    2206 
    2207 @defun find-component base path
    2208 
    2209 Given a @var{base} component (or designator for such),
    2210 and a @var{path}, find the component designated by the @var{path}
    2211 starting from the @var{base}.
    2212 
    2213 If @var{path} is a component object, it designates itself,
    2214 independently from the base.
    2215 
    2216 If @var{path} is a string, or symbol denoting a string via @code{coerce-name},
    2217 then @var{base} is resolved to a component object,
    2218 which must be a system or module,
    2219 and the designated component is the child named by the @var{path}.
    2220 
    2221 If @var{path} is a @code{cons} cell,
    2222 @code{find-component} with the base and the @code{car} of the @var{path},
    2223 and the resulting object is used as the base for a tail call
    2224 to @code{find-component} with the @code{car} of the @var{path}.
    2225 
    2226 If @var{base} is a component object, it designates itself.
    2227 
    2228 If @var{base} is null, then @var{path} is used as the base, with @code{nil} as the path.
    2229 
    2230 If @var{base} is a string, or symbol denoting a string via @code{coerce-name},
    2231 it designates a system as per @code{find-system}.
    2232 
    2233 If @var{base} is a @code{cons} cell, it designates the component found by
    2234 @code{find-component} with its @code{car} as base and @code{cdr} as path.
    2235 @end defun
    2236 
    2237 
    2238 @menu
    2239 * Common attributes of components::
    2240 * Pre-defined subclasses of component::
    2241 * Creating new component types::
    2242 @end menu
    2243 
    2244 @node  Common attributes of components, Pre-defined subclasses of component, Components, Components
    2245 @comment  node-name,  next,  previous,  up
    2246 @subsection Common attributes of components
    2247 
    2248 All components, regardless of type, have the following attributes.
    2249 All attributes except @code{name} are optional.
    2250 
    2251 @subsubsection Name
    2252 
    2253 A component name is a string or a symbol.
    2254 If a symbol, its name is taken and lowercased.
    2255 
    2256 Unless overridden by a @code{:pathname} attribute,
    2257 the name will be interpreted as a pathname specifier according
    2258 to a Unix-style syntax.
    2259 @xref{The defsystem grammar,,Pathname specifiers}.
    2260 
    2261 @subsubsection Version identifier
    2262 @findex version-satisfies
    2263 @cindex :version
    2264 
    2265 This optional attribute specifies a version for the current component.
    2266 The version should typically be a string of integers separated by dots,
    2267 for example @samp{1.0.11}.
    2268 For more information on version specifiers, see @ref{The defsystem grammar}.
    2269 
    2270 A version may then be queried by the generic function @code{version-satisfies},
    2271 to see if @code{:version} dependencies are satisfied,
    2272 and when specifying dependencies, a constraint of minimal version to satisfy
    2273 can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
    2274 
    2275 Note that in the wild, we typically see version numbering
    2276 only on components of type @code{system}.
    2277 Presumably it is much less useful within a given system,
    2278 wherein the library author is responsible to keep the various files in synch.
    2279 
    2280 @subsubsection Required features
    2281 @anchor{required-features}
    2282 
    2283 Traditionally defsystem users have used @code{#+} reader conditionals
    2284 to include or exclude specific per-implementation files.
    2285 For example, CFFI, the portable C foreign function interface contained
    2286 lines like:
    2287 @lisp
    2288      #+sbcl       (:file "cffi-sbcl")
    2289 @end lisp
    2290 An unfortunate side effect of this approach is that no single
    2291 implementation can read the entire system.
    2292 This causes problems if, for example, one wished to design an @code{archive-op}
    2293 that would create an archive file containing all the sources, since
    2294 for example the file @code{cffi-sbcl.lisp} above would be invisible when
    2295 running the @code{archive-op} on any implementation other than SBCL.
    2296 
    2297 Starting with ASDF 3,
    2298 components may therefore have an @code{:if-feature} option.
    2299 The value of this option should be
    2300 a feature expression using the same syntax as @code{#+} does.
    2301 If that feature expression evaluates to false, any reference to the component will be ignored
    2302 during compilation, loading and/or linking.
    2303 Since the expression is read by the normal reader,
    2304 you must explicitly prefix your symbols with @code{:} so they be read as keywords;
    2305 this is as contrasted with the @code{#+} syntax
    2306 that implicitly reads symbols in the keyword package by default.
    2307 
    2308 For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
    2309 the given component is only to be compiled and loaded
    2310 when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
    2311 You cannot write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
    2312 since the symbols would not be read as keywords.
    2313 
    2314 @xref{if-feature-option}.
    2315 
    2316 @subsubsection Dependencies
    2317 
    2318 This attribute specifies dependencies of the component on its siblings.
    2319 It is optional but often necessary.
    2320 
    2321 There is an excitingly complicated relationship between the initarg
    2322 and the method that you use to ask about dependencies
    2323 
    2324 Dependencies are between (operation component) pairs.
    2325 In your initargs for the component, you can say
    2326 
    2327 @lisp
    2328 :in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
    2329               (load-op (load-op "foo")))
    2330 @end lisp
    2331 
    2332 This means the following things:
    2333 @itemize
    2334 @item
    2335 before performing compile-op on this component, we must perform
    2336 load-op on @var{a} and @var{b}, and compile-op on @var{c},
    2337 @item
    2338 before performing @code{load-op}, we have to load @var{foo}
    2339 @end itemize
    2340 
    2341 The syntax is approximately
    2342 
    2343 @verbatim
    2344 (this-op @{(other-op required-components)@}+)
    2345 
    2346 simple-component-name := string
    2347                       |  symbol
    2348 
    2349 required-components := simple-component-name
    2350                      | (required-components required-components)
    2351 
    2352 component-name := simple-component-name
    2353                 | (:version simple-component-name minimum-version-object)
    2354 @end verbatim
    2355 
    2356 Side note:
    2357 
    2358 This is on a par with what ACL defsystem does.
    2359 mk-defsystem is less general: it has an implied dependency
    2360 
    2361 @verbatim
    2362   for all source file x, (load x) depends on (compile x)
    2363 @end verbatim
    2364 
    2365 and using a @code{:depends-on} argument to say that @var{b} depends on
    2366 @var{a} @emph{actually} means that
    2367 
    2368 @verbatim
    2369   (compile b) depends on (load a)
    2370 @end verbatim
    2371 
    2372 This is insufficient for e.g. the McCLIM system, which requires that
    2373 all the files are loaded before any of them can be compiled ]
    2374 
    2375 End side note
    2376 
    2377 In ASDF, the dependency information for a given component and operation
    2378 can be queried using @code{(component-depends-on operation component)},
    2379 which returns a list
    2380 
    2381 @lisp
    2382 ((load-op "a") (load-op "b") (compile-op "c") ...)
    2383 @end lisp
    2384 
    2385 @code{component-depends-on} can be subclassed for more specific
    2386 component/operation types: these need to @code{(call-next-method)}
    2387 and append the answer to their dependency, unless
    2388 they have a good reason for completely overriding the default dependencies.
    2389 
    2390 If it weren't for CLISP, we'd be using @code{LIST} method
    2391 combination to do this transparently.
    2392 But, we need to support CLISP.
    2393 If you have the time for some CLISP hacking,
    2394 I'm sure they'd welcome your fixes.
    2395 @c Doesn't CLISP now support LIST method combination?
    2396 
    2397 A minimal version can be specified for a component you depend on
    2398 (typically another system), by specifying @code{(:version "other-system" "1.2.3")}
    2399 instead of simply @code{"other-system"} as the dependency.
    2400 See the discussion of the semantics of @code{:version}
    2401 in the defsystem grammar.
    2402 
    2403 @c FIXME: Should have cross-reference to "Version specifiers" in the
    2404 @c defsystem grammar, but the cross-referencing is so broken by
    2405 @c insufficient node breakdown that I have not put one in.
    2406 
    2407 
    2408 @subsubsection pathname
    2409 
    2410 This attribute is optional and if absent (which is the usual case),
    2411 the component name will be used.
    2412 
    2413 @xref{The defsystem grammar,,Pathname specifiers},
    2414 for an explanation of how this attribute is interpreted.
    2415 
    2416 Note that the @code{defsystem} macro (used to create a ``top-level'' system)
    2417 does additional processing to set the filesystem location of
    2418 the top component in that system.
    2419 This is detailed elsewhere. @xref{Defining systems with defsystem}.
    2420 
    2421 
    2422 @subsubsection properties
    2423 
    2424 This attribute is optional.
    2425 
    2426 Packaging systems often require information about files or systems
    2427 in addition to that specified by ASDF's pre-defined component attributes.
    2428 Programs that create vendor packages out of ASDF systems therefore
    2429 have to create ``placeholder'' information to satisfy these systems.
    2430 Sometimes the creator of an ASDF system may know the additional
    2431 information and wish to provide it directly.
    2432 
    2433 @code{(component-property component property-name)} and
    2434 associated @code{setf} method will allow
    2435 the programmatic update of this information.
    2436 Property names are compared as if by @code{EQL},
    2437 so use symbols or keywords or something.
    2438 
    2439 @menu
    2440 * Pre-defined subclasses of component::
    2441 * Creating new component types::
    2442 @end menu
    2443 
    2444 @node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
    2445 @comment  node-name,  next,  previous,  up
    2446 @subsection Pre-defined subclasses of component
    2447 
    2448 @deffn Component source-file
    2449 
    2450 A source file is any file that the system does not know how to
    2451 generate from other components of the system.
    2452 
    2453 Note that this is not necessarily the same thing as
    2454 ``a file containing data that is typically fed to a compiler''.
    2455 If a file is generated by some pre-processor stage
    2456 (e.g. a @file{.h} file from @file{.h.in} by autoconf)
    2457 then it is not, by this definition, a source file.
    2458 Conversely, we might have a graphic file
    2459 that cannot be automatically regenerated,
    2460 or a proprietary shared library that we received as a binary:
    2461 these do count as source files for our purposes.
    2462 
    2463 Subclasses of source-file exist for various languages.
    2464 @emph{FIXME: describe these.}
    2465 @end deffn
    2466 
    2467 @deffn Component module
    2468 
    2469 A module is a collection of sub-components.
    2470 
    2471 A module component has the following extra initargs:
    2472 
    2473 @itemize
    2474 @item
    2475 @code{:components} the components contained in this module
    2476 
    2477 @item
    2478 @code{:default-component-class}
    2479 All children components which don't specify their class explicitly
    2480 are inferred to be of this type.
    2481 
    2482 @item
    2483 @code{:if-component-dep-fails}
    2484 This attribute was removed in ASDF 3. Do not use it.
    2485 Use @code{:if-feature} instead (@pxref{required-features}, and @pxref{if-feature-option}).
    2486 
    2487 @item
    2488 @code{:serial} When this attribute is set,
    2489 each subcomponent of this component is assumed to depend on all subcomponents
    2490 before it in the list given to @code{:components}, i.e.
    2491 all of them are loaded before a compile or load operation is performed on it.
    2492 
    2493 @end itemize
    2494 
    2495 The default operation knows how to traverse a module, so
    2496 most operations will not need to provide methods specialised on modules.
    2497 
    2498 @code{module} may be subclassed to represent components such as
    2499 foreign-language linked libraries or archive files.
    2500 @end deffn
    2501 
    2502 @deffn Component system
    2503 
    2504 @code{system} is a subclass of @code{module}.
    2505 
    2506 A system is a module with a few extra attributes for documentation
    2507 purposes; these are given elsewhere.
    2508 @xref{The defsystem grammar}.
    2509 
    2510 Users can create new classes for their systems:
    2511 the default @code{defsystem} macro takes a @code{:class} keyword argument.
    2512 @end deffn
    2513 
    2514 @node  Creating new component types,  , Pre-defined subclasses of component, Components
    2515 @comment  node-name,  next,  previous,  up
    2516 @subsection Creating new component types
    2517 
    2518 New component types are defined by subclassing one of the existing
    2519 component classes and specializing methods on the new component class.
    2520 
    2521 @emph{FIXME: this should perhaps be explained more throughly,
    2522 not only by example ...}
    2523 
    2524 As an example, suppose we have some implementation-dependent
    2525 functionality that we want to isolate
    2526 in one subdirectory per Lisp implementation our system supports.
    2527 We create a subclass of
    2528 @code{cl-source-file}:
    2529 
    2530 @lisp
    2531 (defclass unportable-cl-source-file (cl-source-file)
    2532   ())
    2533 @end lisp
    2534 
    2535 Function @code{asdf:implementation-type} (exported since 2.014.14)
    2536 gives us the name of the subdirectory.
    2537 All that's left is to define how to calculate the pathname
    2538 of an @code{unportable-cl-source-file}.
    2539 
    2540 @lisp
    2541 (defmethod component-pathname ((component unportable-cl-source-file))
    2542   (merge-pathnames*
    2543    (parse-unix-namestring (format nil "~(~A~)/" (asdf:implementation-type)))
    2544    (call-next-method)))
    2545 @end lisp
    2546 
    2547 The new component type is used in a @code{defsystem} form in this way:
    2548 
    2549 @lisp
    2550 (defsystem :foo
    2551     :components
    2552     ((:file "packages")
    2553      ...
    2554      (:unportable-cl-source-file "threads"
    2555       :depends-on ("packages" ...))
    2556      ...
    2557     )
    2558 @end lisp
    2559 
    2560 @node Functions,  , Components, The object model of ASDF
     2801
     2802@node Functions,  , Dependencies, The object model of ASDF
    25612803@comment  node-name,  next,  previous,  up
    25622804@section Functions
    2563 @findex version-satisfies
    2564 
    2565 @deffn version-satisfies @var{version} @var{version-spec}
     2805
     2806@c FIXME: this does not belong here....
     2807@defun version-satisfies @var{version} @var{version-spec}
    25662808Does @var{version} satisfy the @var{version-spec}.  A generic function.
    25672809ASDF provides built-in methods for @var{version} being a @code{component} or @code{string}.
     
    25922834could be in the future extended to specify an exclusive upper bound for compatible versions
    25932835as well as an inclusive lower bound.
    2594 @end deffn
     2836@end defun
    25952837
    25962838@node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
     
    25982840@chapter Controlling where ASDF searches for systems
    25992841
     2842
     2843
     2844@menu
     2845* Configurations::
     2846* Truenames and other dangers::
     2847* XDG base directory::
     2848* Backward Compatibility::
     2849* Configuration DSL::
     2850* Configuration Directories::
     2851* Shell-friendly syntax for configuration::
     2852* Search Algorithm::
     2853* Caching Results::
     2854* Configuration API::
     2855* Introspection::
     2856* Status::
     2857* Rejected ideas::
     2858* TODO::
     2859* Credits for the source-registry::
     2860@end menu
     2861
     2862@node  Configurations, Truenames and other dangers, Controlling where ASDF searches for systems, Controlling where ASDF searches for systems
    26002863@section Configurations
    26012864
     
    26402903@item
    26412904The source registry will be configured from
     2905default user configuration trees
     2906@file{~/common-lisp/} (since ASDF 3.1.2 only),
     2907@file{~/.sbcl/systems/} (on SBCL only),
     2908@file{$XDG_DATA_HOME/common-lisp/systems/} (no recursion, link farm)
     2909@file{$XDG_DATA_HOME/common-lisp/source/}.
     2910The @code{XDG_DATA_HOME} directory defaults to @file{~/.local/share/}.
     2911On Windows, the @code{local-appdata} and @code{appdata} directories are used instead.
     2912
     2913@item
     2914The source registry will be configured from
    26422915system configuration file
    26432916@file{/etc/common-lisp/source-registry.conf}
    2644 if it exists/
     2917if it exists.
    26452918
    26462919@item
     
    26562929(at the time that the configuration is initialized) as well as
    26572930@code{:directory} entries for @file{$XDG_DATA_DIRS/common-lisp/systems/} and
    2658 @code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/}.
    2659 For instance, SBCL will include directories for its contribs
    2660 when it can find them; it will look for them where SBCL was installed,
    2661 or at the location specified by the @code{SBCL_HOME} environment variable.
     2931@code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/},
     2932where @code{XDG_DATA_DIRS} defaults to @file{/usr/local/share} and @file{/usr/share} on Unix,
     2933and the @code{common-appdata} directory on Windows.
     2934
     2935@item
     2936The source registry may include implementation-dependent directories
     2937that correspond to implementation-provided extensions.
    26622938
    26632939@end enumerate
     
    26762952in configuration files, no matter if the last one inherits or not.
    26772953
    2678 
     2954@node Truenames and other dangers, XDG base directory, Configurations, Controlling where ASDF searches for systems
    26792955@section Truenames and other dangers
    26802956
     
    26992975``True Names... and Other Dangers'' then you're in for a treat.
    27002976
    2701 
     2977@node XDG base directory, Backward Compatibility, Truenames and other dangers, Controlling where ASDF searches for systems
    27022978@section XDG base directory
    27032979
     
    27212997ASDF 3 relies on the environment variables that Windows usually exports.
    27222998
     2999@node Backward Compatibility, Configuration DSL, XDG base directory, Controlling where ASDF searches for systems
    27233000@section Backward Compatibility
    27243001
    27253002For backward compatibility as well as to provide a practical backdoor for hackers,
    2726 ASDF will first search for @code{.asd} files in the directories specified in
     3003ASDF will first search for @file{.asd} files in the directories specified in
    27273004@code{asdf:*central-registry*}
    27283005before it searches in the source registry above.
     
    27353012but will take precedence over the new mechanism if you do use it.
    27363013
     3014@node Configuration DSL, Configuration Directories, Backward Compatibility, Controlling where ASDF searches for systems
    27373015@section Configuration DSL
    27383016@cindex :inherit-configuration source config directive
     
    27593037
    27603038@example
    2761 ;; A configuration is a single SEXP starting with keyword :source-registry
    2762 ;; followed by a list of directives.
     3039;; A configuration is a single SEXP starting with the keyword
     3040;; :source-registry followed by a list of directives.
    27633041CONFIGURATION := (:source-registry DIRECTIVE ...)
    27643042
     
    27673045    ;; INHERITANCE DIRECTIVE:
    27683046    ;; Your configuration expression MUST contain
    2769     ;; exactly one of either of these:
    2770     :inherit-configuration | ; splices inherited configuration (often specified last)
    2771     :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
     3047    ;; exactly one of the following:
     3048    :inherit-configuration |
     3049    ;; splices inherited configuration (often specified last) or
     3050    :ignore-inherited-configuration |
     3051    ;; drop inherited configuration (specified anywhere)
    27723052
    27733053    ;; forward compatibility directive (since ASDF 2.011.4), useful when
    2774     ;; you want to use new configuration features but have to bootstrap a
    2775     ;; the newer required ASDF from an older release that doesn't sport said features:
    2776     :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
     3054    ;; you want to use new configuration features but have to bootstrap
     3055    ;; the newer required ASDF from an older release that doesn't
     3056    ;; support said features:
     3057    :ignore-invalid-entries |
    27773058
    27783059    ;; add a single directory to be scanned (no recursion)
    27793060    (:directory DIRECTORY-PATHNAME-DESIGNATOR) |
    27803061
    2781     ;; add a directory hierarchy, recursing but excluding specified patterns
     3062    ;; add a directory hierarchy, recursing but
     3063    ;; excluding specified patterns
    27823064    (:tree DIRECTORY-PATHNAME-DESIGNATOR) |
    27833065
     
    27953077    :default-registry
    27963078
    2797 REGULAR-FILE-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a file
    2798 DIRECTORY-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a directory name
     3079REGULAR-FILE-PATHNAME-DESIGNATOR
     3080    := PATHNAME-DESIGNATOR ; interpreted as a file
     3081DIRECTORY-PATHNAME-DESIGNATOR
     3082    := PATHNAME-DESIGNATOR ; interpreted as a directory
    27993083
    28003084PATHNAME-DESIGNATOR :=
     
    28023086    ABSOLUTE-COMPONENT-DESIGNATOR ;; see pathname DSL
    28033087
    2804 EXCLUSION-PATTERN := a string without wildcards, that will be matched exactly
    2805   against the name of a any subdirectory in the directory component
    2806         of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"}
     3088EXCLUSION-PATTERN := a string without wildcards, that will be matched
     3089    exactly against the name of a any subdirectory in the directory
     3090    component of a path. e.g. @code{"_darcs"} will match
     3091    @file{#p"/foo/bar/_darcs/src/bar.asd"}
    28073092@end example
    28083093
     
    28153100ABSOLUTE-COMPONENT-DESIGNATOR :=
    28163101    (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
    2817     STRING | ;; namestring (better be absolute or bust, directory assumed where applicable).
    2818              ;; In output-translations, directory is assumed and **/*.*.* added if it's last.
    2819              ;; On MCL, a MacOSX-style POSIX namestring (for MacOS9 style, use #p"...");
    2820              ;; Note that none of the above applies to strings used in *central-registry*,
    2821              ;; which doesn't use this DSL: they are processed as normal namestrings.
    2822              ;; however, you can compute what you put in the *central-registry*
    2823              ;; based on the results of say (asdf::resolve-location "/Users/fare/cl/cl-foo/")
    2824     PATHNAME | ;; pathname (better be an absolute path, or bust)
    2825                ;; In output-translations, unless followed by relative components,
    2826                ;; it better have appropriate wildcards, as in **/*.*.*
    2827     :HOME | ;; designates the user-homedir-pathname ~/
    2828     :USER-CACHE | ;; designates the default location for the user cache
    2829     :HERE | ;; designates the location of the configuration file
    2830             ;; (or *default-pathname-defaults*, if invoked interactively)
    2831     :ROOT ;; magic, for output-translations source only: paths that are relative
    2832           ;; to the root of the source host and device
    2833     ;; Not valid anymore: :SYSTEM-CACHE (was a security hazard)
     3102    STRING |
     3103    ;; namestring (better be absolute or bust, directory assumed where
     3104    ;; applicable).  In output-translations, directory is assumed and
     3105    ;; **/*.*.* added if it's last.  On MCL, a MacOSX-style POSIX
     3106    ;; namestring (for MacOS9 style, use #p"..."); Note that none of the
     3107    ;; above applies to strings used in *central-registry*, which
     3108    ;; doesn't use this DSL: they are processed as normal namestrings.
     3109    ;; however, you can compute what you put in the *central-registry*
     3110    ;; based on the results of say
     3111    ;; (asdf::resolve-location "/Users/fare/cl/cl-foo/")
     3112    PATHNAME |
     3113    ;; pathname (better be an absolute path, or bust)
     3114    ;; In output-translations, unless followed by relative components,
     3115    ;; it better have appropriate wildcards, as in **/*.*.*
     3116    :HOME | ; designates the user-homedir-pathname ~/
     3117    :USER-CACHE | ; designates the default location for the user cache
     3118    :HERE |
     3119    ;; designates the location of the configuration file
     3120    ;; (or *default-pathname-defaults*, if invoked interactively)
     3121    :ROOT
     3122    ;; magic, for output-translations source only: paths that are relative
     3123    ;; to the root of the source host and device
     3124
     3125They keyword :SYSTEM-CACHE is not accepted in ASDF 3.1 and beyond: it
     3126was a security hazard.
    28343127
    28353128RELATIVE-COMPONENT-DESIGNATOR :=
    28363129    (RELATIVE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
    2837     STRING | ;; relative directory pathname as interpreted by parse-unix-namestring.
    2838              ;; In output translations, if last component, **/*.*.* is added
    2839     PATHNAME | ;; pathname; unless last component, directory is assumed.
    2840     :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
    2841     :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
    2842     :DEFAULT-DIRECTORY | ;; a relativized version of the default directory
     3130    STRING |
     3131      ;; relative directory pathname as interpreted by
     3132      ;; parse-unix-namestring.
     3133      ;; In output translations, if last component, **/*.*.* is added
     3134    PATHNAME | ; pathname; unless last component, directory is assumed.
     3135    :IMPLEMENTATION |
     3136       ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
     3137    :IMPLEMENTATION-TYPE |
     3138       ;; a directory based on lisp-implementation-type only, e.g. sbcl
     3139    :DEFAULT-DIRECTORY |
     3140       ;; a relativized version of the default directory
    28433141    :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
    28443142    :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
    28453143    :*.*.* | ;; any file (since ASDF 2.011.4)
    2846     ;; Not supported (anymore): :UID and :USERNAME
     3144
     3145The keywords :UID and :USERNAME are no longer supported.
    28473146@end example
    28483147
     
    28553154@end example
    28563155
     3156@node Configuration Directories, Shell-friendly syntax for configuration, Configuration DSL, Controlling where ASDF searches for systems
    28573157@section Configuration Directories
    28583158
     
    28643164at the @emph{end} of the list.
    28653165
    2866 This allows for packaging software that has file granularity
    2867 (e.g. Debian's @code{dpkg} or some future version of @code{clbuild})
    2868 to easily include configuration information about distributed software.
     3166System-wide or per-user Common Lisp software distributions
     3167such as Debian packages or some future version of @code{clbuild}
     3168may then include files such as
     3169@file{/etc/common-lisp/source-registry.conf.d/10-foo.conf} or
     3170@file{~/.config/common-lisp/source-registry.conf.d/10-foo.conf}
     3171to easily and modularly register configuration information
     3172about software being distributed.
    28693173
    28703174The convention is that, for sorting purposes,
    28713175the names of files in such a directory begin with two digits
    28723176that determine the order in which these entries will be read.
    2873 Also, the type of these files is conventionally @code{"conf"}
    2874 and as a limitation to some implementations (e.g. GNU clisp),
    2875 the type cannot be @code{nil}.
     3177Also, the type of these files must be @file{.conf},
     3178which not only simplifies the implementation by allowing
     3179for more portable techniques in finding those files,
     3180but also makes it trivial to disable a file, by renaming it to a different file type.
    28763181
    28773182Directories may be included by specifying a directory pathname
     
    28913196@end example
    28923197
     3198@menu
     3199* The here directive::
     3200@end menu
     3201
     3202@node The here directive,  , Configuration Directories, Configuration Directories
    28933203@subsection The :here directive
    28943204
     
    29083218like this:
    29093219@example
    2910    (:tree  "path/to/dir")
     3220   (:tree "path/to/dir")
    29113221@end example
    29123222But what if X knows that there are very large subtrees
     
    29363246directory according to X's (relative) instructions.
    29373247
     3248@node Shell-friendly syntax for configuration, Search Algorithm, Configuration Directories, Controlling where ASDF searches for systems
    29383249@section Shell-friendly syntax for configuration
    29393250
     
    29593270    spliced there.
    29603271
    2961 
     3272@node Search Algorithm, Caching Results, Shell-friendly syntax for configuration, Controlling where ASDF searches for systems
    29623273@section Search Algorithm
    29633274@vindex *default-source-registry-exclusions*
     
    29953306
    29963307
     3308@node Caching Results, Configuration API, Search Algorithm, Controlling where ASDF searches for systems
    29973309@section Caching Results
    29983310
     
    30023314To explicitly flush any information cached by the system, use the API below.
    30033315
    3004 
     3316@node Configuration API, Introspection, Caching Results, Controlling where ASDF searches for systems
    30053317@section Configuration API
    30063318
     
    30093321and for XCVB the corresponding functions are in package XCVB.
    30103322
    3011 @defun initialize-source-registry @Aoptional PARAMETER
     3323@defun initialize-source-registry @Aoptional{} PARAMETER
    30123324   will read the configuration and initialize all internal variables.
    30133325   You may extend or override configuration
     
    30343346@end defun
    30353347
    3036 @defun ensure-source-registry @Aoptional PARAMETER
     3348@defun ensure-source-registry @Aoptional{} PARAMETER
    30373349   checks whether a source registry has been initialized.
    30383350   If not, initialize it with the given @var{PARAMETER}.
     
    30483360which will cause the initialization to happen next time around.
    30493361
     3362@node Introspection, Status, Configuration API, Controlling where ASDF searches for systems
    30503363@section Introspection
    30513364
     3365@menu
     3366* *source-registry-parameter* variable::
     3367* Information about system dependencies::
     3368@end menu
     3369
     3370@node *source-registry-parameter* variable, Information about system dependencies, Introspection, Introspection
    30523371@subsection *source-registry-parameter* variable
    30533372@vindex *source-registry-parameter*
     
    30603379read-only.
    30613380
     3381@node Information about system dependencies,  , *source-registry-parameter* variable, Introspection
    30623382@subsection Information about system dependencies
    30633383
     
    30833403@end defun
    30843404
     3405@node Status, Rejected ideas, Introspection, Controlling where ASDF searches for systems
    30853406@section Status
    30863407
     
    30923413that everyone uses implicitly.
    30933414
    3094 
     3415@node Rejected ideas, TODO, Status, Controlling where ASDF searches for systems
    30953416@section Rejected ideas
    30963417
    3097 Alternatives I considered and rejected included:
     3418Alternatives I (FRR) considered and rejected while developing ASDF 2 included:
    30983419
    30993420@enumerate
     
    31043425   and leaves little space of future cleanups and extensions.
    31053426
    3106 @item Keep @code{asdf:*central-registry*} remains the master but extend its semantics
     3427@item Keep @code{asdf:*central-registry*} as the master but extend its semantics
    31073428   in completely new ways, so that new kinds of entries may be implemented
    31083429   as a recursive search, etc. This seems somewhat backwards.
     
    31463467@end itemize
    31473468
     3469@node TODO, Credits for the source-registry, Rejected ideas, Controlling where ASDF searches for systems
    31483470@section TODO
    31493471
     
    31523474@end itemize
    31533475
    3154 
     3476@node Credits for the source-registry,  , TODO, Controlling where ASDF searches for systems
    31553477@section Credits for the source-registry
    31563478
     
    31733495
    31743496Each Common Lisp implementation has its own format
    3175 for compiled files (fasls for short, short for ``fast loading'').
     3497for compiled files or fasls.@footnote{``FASL'' is short for ``FASt Loading.''}
    31763498If you use multiple implementations
    31773499(or multiple versions of the same implementation),
    31783500you'll soon find your source directories
    3179 littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so on.
    3180 Worse yet, some implementations use the same file extension
    3181 while changing formats from version to version (or platform to platform)
    3182 which means that you'll have to recompile binaries
     3501littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so
     3502on.
     3503Worse yet, multiple implementations use the same file extension and
     3504some implementations maintain the same file extension
     3505while changing formats from version to version (or platform to
     3506platform).
     3507This can lead to many errors and much confusion
    31833508as you switch from one implementation to the next.
    31843509
     
    31863511to mitigate the problem.
    31873512
     3513@menu
     3514* Output Configurations::
     3515* Output Backward Compatibility::
     3516* Output Configuration DSL::
     3517* Output Configuration Directories::
     3518* Output Shell-friendly syntax for configuration::
     3519* Semantics of Output Translations::
     3520* Output Caching Results::
     3521* Output location API::
     3522* Credits for output translations::
     3523@end menu
     3524
     3525@node Output Configurations, Output Backward Compatibility, Controlling where ASDF saves compiled files, Controlling where ASDF saves compiled files
    31883526@section Configurations
     3527
     3528@c FIXME: Explain how configurations work: can't expect reader will have
     3529@c looked at previous chapter. Probably cut and paste will do.
     3530
    31893531
    31903532Configurations specify mappings from input locations to output locations.
     
    32423584
    32433585Each of these configurations is specified as a SEXP
    3244 in a trival domain-specific language (defined below).
     3586in a trivial domain-specific language (@pxref{Configuration DSL}).
    32453587Additionally, a more shell-friendly syntax is available
    3246 for the environment variable (defined yet below).
    3247 
    3248 Each of these configurations is only used if the previous
    3249 configuration explicitly or implicitly specifies that it
     3588for the environment variable (@pxref{Shell-friendly syntax for configuration}).
     3589
     3590When processing an entry in the above list of configuration methods,
     3591ASDF will stop unless that entry
     3592explicitly or implicitly specifies that it
    32503593includes its inherited configuration.
    32513594
     
    32553598when they browse source code,
    32563599at the expense of taking a small toll when developers have to clean up
    3257 output files and find they need to get familiar with output-translations first.
    3258 
    3259 
     3600output files and find they need to get familiar with output-translations
     3601first.@footnote{A @code{CLEAN-OP} would be a partial solution to this problem.}
     3602
     3603
     3604@node Output Backward Compatibility, Output Configuration DSL, Output Configurations, Controlling where ASDF saves compiled files
    32603605@section Backward Compatibility
    32613606@cindex ASDF-BINARY-LOCATIONS compatibility
    3262 
    3263 
    3264 We purposefully do NOT provide backward compatibility with earlier versions of
     3607@c FIXME: Demote this section -- the typical reader doesn't care about
     3608@c backwards compatibility.
     3609
     3610
     3611We purposely do @emph{not} provide backward compatibility with earlier versions of
    32653612@code{ASDF-Binary-Locations} (8 Sept 2009),
    32663613@code{common-lisp-controller} (7.0) or
    32673614@code{cl-launch} (2.35),
    32683615each of which had similar general capabilities.
    3269 The previous APIs of these programs were not designed
    3270 for configuration by the end-user
    3271 in an easy way with configuration files.
    3272 Recent versions of same packages use
    3273 the new @code{asdf-output-translations} API as defined below:
    3274 @code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000).
     3616The APIs of these programs were not designed
     3617for easy user configuration
     3618through configuration files.
     3619Recent versions of @code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000)
     3620use the new @code{asdf-output-translations} API as defined below.
    32753621@code{ASDF-Binary-Locations} is fully superseded and not to be used anymore.
    32763622
     
    32883634we provide a limited emulation mode:
    32893635
    3290 @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
     3636@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
    32913637This function will initialize the new @code{asdf-output-translations} facility in a way
    32923638that emulates the behavior of the old @code{ASDF-Binary-Locations} facility.
     
    33123658To disable it, use @code{(asdf:disable-output-translations)}.
    33133659
    3314 
     3660@node Output Configuration DSL, Output Configuration Directories, Output Backward Compatibility, Controlling where ASDF saves compiled files
    33153661@section Configuration DSL
    33163662
     
    33283674    ;; Your configuration expression MUST contain
    33293675    ;; exactly one of either of these:
    3330     :inherit-configuration | ; splices inherited configuration (often specified last)
    3331     :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
     3676    :inherit-configuration |
     3677      ;; splices inherited configuration (often specified last)
     3678    :ignore-inherited-configuration |
     3679      ;; drop inherited configuration (specified anywhere)
    33323680
    33333681    ;; forward compatibility directive (since ASDF 2.011.4), useful when
    33343682    ;; you want to use new configuration features but have to bootstrap a
    3335     ;; the newer required ASDF from an older release that doesn't sport said features:
    3336     :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
     3683    ;; the newer required ASDF from an older release that doesn't have
     3684    ;; said features:
     3685    :ignore-invalid-entries |
    33373686
    33383687    ;; include a configuration file or directory
    33393688    (:include PATHNAME-DESIGNATOR) |
    33403689
    3341     ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/ or something.
     3690    ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/
     3691    ;; or something.
    33423692    :enable-user-cache |
    33433693    ;; Disable global cache. Map / to /
     
    33513701
    33523702DIRECTORY-DESIGNATOR :=
    3353     NIL | ;; As source: skip this entry. As destination: same as source
    3354     T | ;; as source matches anything, as destination leaves pathname unmapped.
    3355     ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language
     3703    NIL | ; As source: skip this entry. As destination: same as source
     3704    T | ; as source matches anything, as destination
     3705        ; maps pathname to itself.
     3706    ABSOLUTE-COMPONENT-DESIGNATOR ; same as in the source-registry language
    33563707
    33573708TRANSLATION-FUNCTION :=
    3358     SYMBOL | ;; symbol of a function that takes two arguments,
    3359              ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
    3360     LAMBDA   ;; A form which evalutates to a function taking two arguments consisting of
    3361              ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
     3709    SYMBOL | ;; symbol naming a function that takes two arguments:
     3710             ;; the pathname to be translated and the matching
     3711             ;; DIRECTORY-DESIGNATOR
     3712    LAMBDA   ;; A form which evalutates to a function taking two arguments:
     3713             ;; the pathname to be translated and the matching
     3714             ;; DIRECTORY-DESIGNATOR
    33623715
    33633716@end verbatim
     
    33663719or subdirectories of the path before them, or bust.
    33673720
     3721@c FIXME: the following assumes that the reader is familiar with the use
     3722@c of this pattern in logical pathnames, which may not be a reasonable
     3723@c assumption.  Expand.
    33683724The last component, if not a pathname, is notionally completed by @file{/**/*.*}.
    33693725You can specify more fine-grained patterns
     
    33973753with @code{:centralize-lisp-binaries nil}
    33983754which will do the same thing internally for you:
    3399 @verbatim
    3400   #.(let ((wild-subdir (make-pathname :directory '(:relative :wild-inferiors)))
    3401           (wild-file (make-pathname :name :wild :version :wild :type :wild)))
    3402      `((:root ,wild-subdir ,wild-file) ;; Or using the implicit wildcard, just :root
    3403        (:root ,wild-subdir :implementation ,wild-file)))
    3404 @end verbatim
     3755@lisp
     3756#.(let ((wild-subdir
     3757          (make-pathname :directory '(:relative :wild-inferiors)))
     3758        (wild-file
     3759          (make-pathname :name :wild :version :wild :type :wild)))
     3760   `((:root ,wild-subdir ,wild-file)
     3761     (:root ,wild-subdir :implementation ,wild-file)))
     3762@end lisp
    34053763Starting with ASDF 2.011.4, you can use the simpler:
    34063764  @code{`(:root (:root :**/ :implementation :*.*.*))}
     
    34213779the first being the pathname of the source file,
    34223780the second being the wildcard that was matched.
    3423 The result of the function invocation should be the translated pathname.
    3424 
    3425 An @code{:inherit-configuration} statement cause the search to recurse with the path
    3426 specifications from the next configuration.
     3781When invoked, the function should return the translated pathname.
     3782
     3783An @code{:inherit-configuration} statement causes the search to recurse with the path
     3784specifications from the next configuration in the bulleted list.
    34273785@xref{Controlling where ASDF saves compiled files,,Configurations}, above.
    34283786
     3787@vindex @code{asdf::*user-cache*}
    34293788@itemize
    34303789@item
     
    34393798
    34403799
     3800@node Output Configuration Directories, Output Shell-friendly syntax for configuration, Output Configuration DSL, Controlling where ASDF saves compiled files
    34413801@section Configuration Directories
    34423802
    3443 Configuration directories consist in files each contains
     3803Configuration directories consist of files, each of which contains
    34443804a list of directives without any enclosing
    34453805@code{(:output-translations ...)} form.
     
    34493809at the @emph{end} of the list.
    34503810
    3451 This allows for packaging software that has file granularity
    3452 (e.g. Debian's @command{dpkg} or some future version of @command{clbuild})
    3453 to easily include configuration information about software being distributed.
     3811System-wide or per-user Common Lisp software distributions
     3812such as Debian packages or some future version of @code{clbuild}
     3813may then include files such as
     3814@file{/etc/common-lisp/asdf-output-translations.conf.d/10-foo.conf} or
     3815@file{~/.config/common-lisp/asdf-output-translations.conf.d/10-foo.conf}
     3816to easily and modularly register configuration information
     3817about software being distributed.
    34543818
    34553819The convention is that, for sorting purposes,
    34563820the names of files in such a directory begin with two digits
    34573821that determine the order in which these entries will be read.
    3458 Also, the type of these files is conventionally @code{"conf"}
    3459 and as a limitation of some implementations, the type cannot be @code{nil}.
     3822Also, the type of these files must be @file{.conf},
     3823which not only simplifies the implementation by allowing
     3824for more portable techniques in finding those files,
     3825but also makes it trivial to disable a file, by renaming it to a different file type.
    34603826
    34613827Directories may be included by specifying a directory pathname
    34623828or namestring in an @code{:include} directive, e.g.:
     3829
    34633830@verbatim
    34643831  (:include "/foo/bar/")
    34653832@end verbatim
    34663833
     3834@node Output Shell-friendly syntax for configuration, Semantics of Output Translations, Output Configuration Directories, Controlling where ASDF saves compiled files
    34673835@section Shell-friendly syntax for configuration
    34683836
    34693837When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS}
    3470 ASDF will skip to next configuration if it's an empty string.
     3838ASDF will skip to the next configuration if it's an empty string.
    34713839It will @code{READ} the string as an SEXP in the DSL
    34723840if it begins with a paren @code{(}
     
    34833851it indicates that the directory specified first is to be left untranslated
    34843852(which has the same effect as if the directory had been repeated).
    3485 
    3486 
     3853Thus @code{"/foo:/bar::/baz:"} means that
     3854things under directory @file{/foo/}
     3855are translated to be under @file{/bar/},
     3856then include the inherited configuration,
     3857then specify that things under directory @file{/baz/} are not translated.
     3858
     3859@node Semantics of Output Translations, Output Caching Results, Output Shell-friendly syntax for configuration, Controlling where ASDF saves compiled files
    34873860@section Semantics of Output Translations
    34883861
     
    35143887with same fall-through semantics).
    35153888
     3889@node Output Caching Results, Output location API, Semantics of Output Translations, Controlling where ASDF saves compiled files
    35163890@section Caching Results
    35173891
     
    35223896
    35233897
     3898@node Output location API, Credits for output translations, Output Caching Results, Controlling where ASDF saves compiled files
    35243899@section Output location API
    35253900
    35263901The specified functions are exported from package ASDF.
    35273902
    3528 @defun initialize-output-translations @Aoptional PARAMETER
     3903@defun initialize-output-translations @Aoptional{} PARAMETER
    35293904   will read the configuration and initialize all internal variables.
    35303905   You may extend or override configuration
     
    35573932@end defun
    35583933
    3559 @defun ensure-output-translations @Aoptional PARAMETER
     3934@defun ensure-output-translations @Aoptional{} PARAMETER
    35603935   checks whether output translations have been initialized.
    35613936   If not, initialize them with the given @var{PARAMETER}.
     
    35783953
    35793954
     3955@node Credits for output translations,  , Output location API, Controlling where ASDF saves compiled files
    35803956@section Credits for output translations
    35813957
    3582 Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations},
    3583 and to Peter van Eynde for @code{Common Lisp Controller}.
     3958Thanks a lot to Peter van Eynde for @code{Common Lisp Controller}
     3959and to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations}.
    35843960
    35853961All bad design ideas and implementation bugs are to mine, not theirs.
     
    36484024useful for system definition and development.
    36494025
     4026@menu
     4027* Controlling file compilation::
     4028* Controlling source file character encoding::
     4029* Some Utility Functions::
     4030@end menu
     4031
     4032@node Controlling file compilation, Controlling source file character encoding, Miscellaneous additional functionality, Miscellaneous additional functionality
    36504033@section Controlling file compilation
    36514034@cindex :around-compile
     
    36554038@findex compile-file*
    36564039
     4040@c FIXME: Needs rewrite.  Start with motivation -- why are we doing
     4041@c this?  (there is some, but it's buried).  Also, all of a sudden in
     4042@c the middle of the discussion we start talking about a "hook," which
     4043@c is confusing.
     4044
    36574045When declaring a component (system, module, file),
    36584046you can specify a keyword argument @code{:around-compile function}.
     
    36624050if no value is specified in any transitive parent.
    36634051
    3664 The argument must be a either @code{nil}, a fbound symbol,
     4052The argument must be either @code{nil}, an fbound symbol,
    36654053a lambda-expression (e.g. @code{(lambda (thunk) ...(funcall thunk ...) ...)})
    36664054a function object (e.g. using @code{#.#'} but that's discouraged
     
    37204108
    37214109
     4110@node Controlling source file character encoding, Some Utility Functions, Controlling file compilation, Miscellaneous additional functionality
    37224111@section Controlling source file character encoding
    37234112
     
    37284117from the parent module or system;
    37294118if no encoding is specified at any point,
    3730 the default @code{:autodetect} is assumed.
    3731 By default, only @code{:default}, @code{:utf-8}
    3732 and @code{:autodetect} are accepted.
    3733 @code{:autodetect}, the default, calls
    3734 @code{*encoding-detection-hook*} which by default always returns
    3735 @code{*default-encoding*} which itself defaults to @code{:default}.
     4119or if @code{nil} is explicitly specified,
     4120an extensible protocol described below is followed,
     4121that ultimately defaults to @code{:utf-8} since ASDF 3.
     4122
     4123The protocol to determine the encoding is
     4124to call the function @code{detect-encoding},
     4125which itself, if provided a valid file,
     4126calls the function specified by @var{*encoding-detection-hook*},
     4127or else defaults to the @var{*default-encoding*}.
     4128The @var{*encoding-detection-hook*} is by default bound
     4129to function @code{always-default-encoding},
     4130that always returns the contents of @var{*default-encoding*}.
     4131@var{*default-encoding*} is bound to @code{:utf-8} by default
     4132(before ASDF 3, the default was @code{:default}).
     4133
     4134Whichever encoding is returned must be a portable keyword,
     4135that will be translated to an implementation-specific external-format designator
     4136by function @code{encoding-external-format},
     4137which itself simply calls the function specified @var{*encoding-external-format-hook*};
     4138that function by default is @code{default-encoding-external-format},
     4139that only recognizes @code{:utf-8} and @code{:default},
     4140and translates the former to the implementation-dependent @var{*utf-8-external-format*},
     4141and the latter to itself (that itself is portable but has an implementation-dependent meaning).
    37364142
    37374143In other words, there now are plenty of extension hooks, but
    3738 by default ASDF follows the backwards compatible behavior
    3739 of using whichever @code{:default} encoding your implementation uses,
    3740 which itself may or may not vary based on environment variables
    3741 and other locale settings.
    3742 In practice this means that only source code that only uses ASCII
    3743 is guaranteed to be read the same on all implementations
    3744 independently from any user setting.
    3745 
    3746 Additionally, for backward-compatibility with older versions of ASDF
    3747 and/or with implementations that do not support unicode and its many encodings,
    3748 you may want to use
    3749 the reader conditionals @code{#+asdf-unicode #+asdf-unicode}
    3750 to protect any @code{:encoding @emph{encoding}} statement
    3751 as @code{:asdf-unicode} will be present in @code{*features*}
    3752 only if you're using a recent ASDF
    3753 on an implementation that supports unicode.
     4144by default ASDF enforces the previous @emph{de facto} standard behavior
     4145of using @code{:utf-8}, independently from
     4146whatever configuration the user may be using.
     4147Thus, system authors can now rely on @code{:utf-8}
     4148being used while compiling their files,
     4149even if the user is currently using @code{:koi8-r} or @code{:euc-jp}
     4150as their interactive encoding.
     4151(Before ASDF 3, there was no such guarantee, @code{:default} was used,
     4152and only plain ASCII was safe to include in source code.)
     4153
     4154Some legacy implementations only support 8-bit characters,
     4155and some implementations provide 8-bit only variants.
     4156On these implementations, the @var{*utf-8-external-format*}
     4157gracefully falls back to @code{:default},
     4158and Unicode characters will be read as multi-character mojibake.
     4159To detect such situations, UIOP will push the @code{:asdf-unicode} feature
     4160on implementations that support Unicode, and you can use reader-conditionalization
     4161to protect any @code{:encoding @emph{encoding}} statement, as in
     4162@code{#+asdf-unicode :encoding #+asdf-unicode :utf-8}.
    37544163We recommend that you avoid using unprotected @code{:encoding} specifications
    3755 until after ASDF 2.21 or later becomes widespread, hopefully by the end of 2012.
     4164until after ASDF 2.21 or later becomes widespread
     4165(in April 2014, only LispWorks lags with ASDF 2.019,
     4166and is scheduled to be updated later this year).
    37564167
    37574168While it offers plenty of hooks for extension,
    3758 and one such extension is being developed (see below),
     4169and one such extension is available (see @code{asdf-encodings} below),
    37594170ASDF itself only recognizes one encoding beside @code{:default},
    37604171and that is @code{:utf-8}, which is the @emph{de facto} standard,
     
    37774188We invite you to embrace UTF-8
    37784189as the encoding for non-ASCII characters starting today,
    3779 even without any explicit specification in your @code{.asd} files.
     4190even without any explicit specification in your @file{.asd} files.
    37804191Indeed, on some implementations and configurations,
    37814192UTF-8 is already the @code{:default},
     
    37864197(provided you do @emph{not} use a BOM),
    37874198although it might be read incorrectly on some implementations.
    3788 In the future, we intend to make @code{:utf-8}
    3789 the default value of @code{*default-encoding*},
    3790 to be enforced everywhere, so at least the code is guaranteed
    3791 to be read correctly everywhere it can be.
     4199@code{:utf-8} has been the default value of @code{*default-encoding*} since ASDF 3.
    37924200
    37934201If you need non-standard character encodings for your source code,
     
    37974205@code{*encoding-external-format-hook*} facility,
    37984206so you can explicitly specify @code{:encoding :latin1}
    3799 in your @code{.asd} file.
     4207in your @file{.asd} file.
    38004208Using the @code{*encoding-detection-hook*} it will also
    38014209eventually implement some autodetection of a file's encoding
    38024210from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration,
    38034211or otherwise based on an analysis of octet patterns in the file.
    3804 At this point, asdf-encoding only supports the encodings
     4212At this point, @code{asdf-encoding} only supports the encodings
    38054213that are supported as part of your implementation.
    38064214Since the list varies depending on implementations,
    3807 we once again recommend you use @code{:utf-8} everywhere,
    3808 which is the most portable (next is @code{:latin1}).
    3809 
    3810 If you're not using a version of Quicklisp that has it,
    3811 you may get the source for @code{asdf-encodings} using git:
     4215we still recommend you use @code{:utf-8} everywhere,
     4216which is the most portable (next to it is @code{:latin1}).
     4217
     4218Recent versions of Quicklisp include @code{asdf-encodings};
     4219if you're not using it, you may get this extension using git:
    38124220@kbd{git clone git://common-lisp.net/projects/asdf/asdf-encodings.git}
    38134221or
     
    38164224@url{http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git}.
    38174225
    3818 In the future, we intend to change the default @code{*default-encoding*}
    3819 to @code{:utf-8}, which is already the de facto standard
    3820 for most libraries that use non-ASCII characters:
    3821 utf-8 works everywhere and was backhandedly enforced by
    3822 a lot of people using SBCL and utf-8 and sending reports to authors
    3823 so they make their packages compatible.
    3824 A survey showed only about a handful few libraries
    3825 are incompatible with non-UTF-8, and then, only in comments,
    3826 and we believe that authors will adopt UTF-8 when prompted.
    3827 See the April 2012 discussion on the asdf-devel mailing-list.
    3828 For backwards compatibility with users who insist on a non-UTF-8 encoding,
    3829 but cannot immediately transition to using @code{asdf-encodings}
    3830 (maybe because it isn't ready), it will still be possible to use
    3831 the @code{:encoding :default} option in your @code{defsystem} form
    3832 to restore the behavior of ASDF 2.20 and earlier.
    3833 This shouldn't be required in libraries,
    3834 because user pressure as mentioned above will already have pushed
    3835 library authors towards using UTF-8;
    3836 but authors of end-user programs might care.
    3837 
    3838 When you use @code{asdf-encodings}, any further loaded @code{.asd} file
    3839 will use the autodetection algorithm to determine its encoding;
    3840 yet if you depend on this detection happening,
    3841 you may want to explicitly load @code{asdf-encodings} early in your build,
    3842 for by the time you can use @code{:defsystem-depends-on},
    3843 it is already too late to load it.
     4226When you use @code{asdf-encodings},
     4227any @file{.asd} file loaded
     4228will use the autodetection algorithm to determine its encoding.
     4229If you depend on this detection happening,
     4230you should explicitly load @code{asdf-encodings} early in your build.
     4231Note that @code{:defsystem-depends-on} cannot be used here: by the time
     4232the @code{:defsystem-depends-on} is loaded, the enclosing
     4233@code{defsystem} form has already been read.
     4234
    38444235In practice, this means that the @code{*default-encoding*}
    3845 is usually used for @code{.asd} files.
    3846 Currently, this defaults to @code{:default} for backwards compatibility,
    3847 and that means that you shouldn't rely on non-ASCII characters in a .asd file.
    3848 Since component (path)names are the only real data in these files,
    3849 and non-ASCII characters are not very portable for file names,
    3850 this isn't too much of an issue.
    3851 We still encourage you to use either plain ASCII or UTF-8
    3852 in @code{.asd} files,
    3853 as we intend to make @code{:utf-8} the default encoding in the future.
     4236is usually used for @file{.asd} files.
     4237Currently, this defaults to @code{:utf-8}, and
     4238you should be safe using Unicode characters in those files.
    38544239This might matter, for instance, in meta-data about author's names.
    3855 
     4240Otherwise, the main data in these files is component (path)names,
     4241and we don't recommend using non-ASCII characters for these,
     4242for the result probably isn't very portable.
    38564243
    38574244@section Miscellaneous Functions
     
    38604247
    38614248@anchor{system-relative-pathname}
    3862 @defun system-relative-pathname system name @Akey type
     4249@defun system-relative-pathname system name @Akey{} type
    38634250
    38644251It's often handy to locate a file relative to some system.
     
    38944281
    38954282It is sometimes useful to force recompilation of a previously loaded system.
    3896 In these cases, it may be useful to @code{(asdf:clear-system :foo)}
    3897 to remove the system from the table of currently loaded systems;
     4283For these cases, @code{(asdf:clear-system :foo)}
     4284will remove the system from the table of currently loaded systems:
    38984285the next time the system @code{foo} or one that depends on it is re-loaded,
    3899 @code{foo} will then be loaded again.
    3900 Alternatively, you could touch @code{foo.asd} or
    3901 remove the corresponding fasls from the output file cache.
    3902 (It was once conceived that one should provide
    3903 a list of systems the recompilation of which to force
    3904 as the @code{:force} keyword argument to @code{load-system};
    3905 but this has never worked, and though the feature was fixed in ASDF 2.000,
    3906 it remains @code{cerror}'ed out as nobody ever used it.)
    3907 
    3908 Note that this does not and cannot by itself undo the previous loading
    3909 of the system. Common Lisp has no provision for such an operation,
    3910 and its reliance on irreversible side-effects to global datastructures
     4286@code{foo} will be loaded again.@footnote{Alternatively, you could touch @code{foo.asd} or
     4287remove the corresponding fasls from the output file cache.}
     4288
     4289Note that this does not and cannot undo
     4290the previous loading of the system.
     4291Common Lisp has no provision for such an operation,
     4292and its reliance on irreversible side-effects to global data structures
    39114293makes such a thing impossible in the general case.
    39124294If the software being re-loaded is not conceived with hot upgrade in mind,
    3913 this re-loading may cause many errors, warnings or subtle silent problems,
     4295re-loading may cause many errors, warnings or subtle silent problems,
    39144296as packages, generic function signatures, structures, types, macros, constants, etc.
    39154297are being redefined incompatibly.
     
    39184300unregistering symbols, defining methods on @code{update-instance-for-redefined-class}
    39194301and much more are necessary for reloading to happen smoothly.
    3920 ASDF itself goes through notable pains to make such a hot upgrade possible
    3921 with respect to its own code, and what it does is ridiculously complex;
    3922 look at the beginning of @file{asdf.lisp} to see what it does.
     4302ASDF itself goes to extensive effort to make a hot upgrade possible
     4303with respect to its own code.
     4304If you want, you can reuse some of its utilities such as
     4305@code{uiop:define-package} and @code{uiop:with-upgradability},
     4306and get inspiration (or disinspiration)
     4307from what it does in @file{header.lisp} and @file{upgrade.lisp}.
    39234308@end defun
    39244309
    3925 @defun register-preloaded-system name @Arest keys
     4310@defun register-preloaded-system name @Arest{} keys
    39264311A system with name @var{name},
    39274312created by @code{make-instance} with extra keys @var{keys}
     
    39344319
    39354320This function is particularly useful if you distribute your code
    3936 as fasls with either @code{fasl-op} or @code{monolithic-fasl-op},
     4321as fasls with either @code{compile-bundle-op} or @code{monolithic-compile-bundle-op},
    39374322and want to register systems so that dependencies will work uniformly
    39384323whether you're using your software from source or from fasl.
    39394324@end defun
    39404325
    3941 @defun run-shell-command control-string @Arest args
     4326@defun run-shell-command control-string @Arest{} args
    39424327
    39434328This function is obsolete and present only for the sake of backwards-compatibility:
     
    39604345@end defun
    39614346
     4347@node Some Utility Functions,  , Controlling source file character encoding, Miscellaneous additional functionality
    39624348@section Some Utility Functions
    39634349
     
    39694355
    39704356
    3971 @defun parse-unix-namestring name @Akey type defaults dot-dot ensure-directory @AallowOtherKeys
     4357@defun parse-unix-namestring name @Akey{} type defaults dot-dot ensure-directory @AallowOtherKeys
    39724358Coerce NAME into a PATHNAME using standard Unix syntax.
    39734359
    39744360Unix syntax is used whether or not the underlying system is Unix;
    3975 on such non-Unix systems it is only usable but for relative pathnames;
    3976 but especially to manipulate relative pathnames portably, it is of crucial
     4361on non-Unix systems it is only usable for relative pathnames.
     4362In order to manipulate relative pathnames portably, it is crucial
    39774363to possess a portable pathname syntax independent of the underlying OS.
    39784364This is what @code{parse-unix-namestring} provides, and why we use it in ASDF.
     
    39974383which must be one of @code{:back} or @code{:up} and defaults to @code{:back}.
    39984384
     4385@vindex *nil-pathname*
    39994386@code{host}, @code{device} and @code{version} components are taken from @var{defaults},
    4000 which itself defaults to @code{*nil-pathname*}, also used if @var{defaults} is @code{nil}.
     4387which itself defaults to @code{*nil-pathname*}.
     4388@code{*nil-pathname*} is also used if @var{defaults} is @code{nil}.
    40014389No host or device can be specified in the string itself,
    40024390which makes it unsuitable for absolute pathnames outside Unix.
     
    40104398When you're manipulating pathnames that are supposed to make sense portably
    40114399even though the OS may not be Unixish, we recommend you use @code{:want-relative t}
    4012 to throw an error if the pathname is absolute
     4400so that @code{parse-unix-namestring} will throw an error if the pathname is absolute.
    40134401@end defun
    40144402
    4015 @defun merge-pathnames* specified @Aoptional defaults
     4403@defun merge-pathnames* specified @Aoptional{} defaults
    40164404
    40174405This function is a replacement for @code{merge-pathnames} that uses the host and device
     
    40234411@end defun
    40244412
    4025 @defun subpathname pathname subpath @Akey type
     4413@defun subpathname pathname subpath @Akey{} type
    40264414
    40274415This function takes a @var{pathname} and a @var{subpath} and a @var{type}.
     
    40374425@end defun
    40384426
    4039 @defun subpathname* pathname subpath @Akey type
     4427@defun subpathname* pathname subpath @Akey{} type
    40404428
    40414429This function returns @code{nil} if the base @var{pathname} is @code{nil},
     
    40434431@end defun
    40444432
    4045 @defun run-program command @Akey ignore-error-status force-shell input output error-output
    4046   if-input-does-not-exist if-output-exists if-error-output-exists
    4047   element-type external-format @AallowOtherKeys
     4433@defun run-program command @Akey{} ignore-error-status force-shell input output @
     4434error-output if-input-does-not-exist if-output-exists if-error-output-exists @
     4435element-type external-format @AallowOtherKeys
    40484436
    40494437@code{run-program} takes a @var{command} argument that is either
     
    41244512@end defun
    41254513
    4126 @defun slurp-input-stream processor input-stream @Akey
    4127 
    4128 It's a generic function of two arguments, a target object and an input stream,
     4514@defun slurp-input-stream processor input-stream @Akey{}
     4515
     4516@code{slurp-input-stream} is a generic function of two arguments, a target object and an input stream,
    41294517and accepting keyword arguments.
    4130 Predefined methods based on the target object are as follow:
    4131 
     4518Predefined methods based on the target object are as follows:
     4519
     4520@itemize
     4521@item
    41324522If the object is a function, the function is called with the stream as argument.
    41334523
    4134 If the object is a cons, its first element is applied to its rest appended by
     4524@item If the object is a cons, its first element is applied to its rest appended by
    41354525a list of the input stream.
    41364526
    4137 If the object is an output stream, the contents of the input stream are copied to it.
     4527@item If the object is an output stream, the contents of the input stream are copied to it.
    41384528If the @var{linewise} keyword argument is provided, copying happens line by line,
    41394529and an optional @var{prefix} is printed before each line.
     
    41414531using the specified @var{element-type}.
    41424532
    4143 If the object is @code{'string} or @code{:string}, the content is captured into a string.
     4533@item If the object is @code{'string} or @code{:string}, the content is captured into a string.
    41444534Accepted keywords include the @var{element-type} and a flag @var{stripped},
    41454535which when true causes any single line ending to be removed as per @code{uiop:stripln}.
    41464536
    4147 If the object is @code{:lines}, the content is captured as a list of strings,
     4537@item If the object is @code{:lines}, the content is captured as a list of strings,
    41484538one per line, without line ending. If the @var{count} keyword argument is provided,
    41494539it is a maximum count of lines to be read.
    41504540
    4151 If the object is @code{:line}, the content is capture as with @code{:lines} above,
     4541@item If the object is @code{:line}, the content is captured as with @code{:lines} above,
    41524542and then its sub-object is extracted with the @var{at} argument,
    41534543which defaults to @code{0}, extracting the first line.
     
    41554545See the documentation for @code{uiop:access-at}.
    41564546
    4157 If the object is @code{:forms}, the content is captured as a list of S-expressions,
     4547@item If the object is @code{:forms}, the content is captured as a list of S-expressions,
    41584548as read by the Lisp reader.
    41594549If the @var{count} argument is provided,
     
    41624552@code{uiop:with-safe-io-syntax}.
    41634553
    4164 If the object is @code{:form}, the content is capture as with @code{:forms} above,
     4554@item If the object is @code{:form}, the content is captured as with @code{:forms} above,
    41654555and then its sub-object is extracted with the @var{at} argument,
    41664556which defaults to @code{0}, extracting the first form.
     
    41694559We recommend you control the syntax with such macro as
    41704560@code{uiop:with-safe-io-syntax}.
    4171 
     4561@end itemize
    41724562@end defun
    41734563
     
    42224612
    42234613@node What has changed between ASDF 1 and ASDF 2?, Issues with installing the proper version of ASDF, Where do I report a bug?, FAQ
    4224 @section ``What has changed between ASDF 1 and ASDF 2?''
     4614@section ``What has changed between ASDF 1, ASDF 2 and ASDF 3?''
     4615
     4616We released ASDF 2.000 on May 31st 2010,
     4617and ASDF 3.0.0 on May 15th 2013.
     4618Releases of ASDF 2 and later have since then been included
     4619in all actively maintained CL implementations that used to bundle ASDF 1,
     4620plus some implementations that previously did not.
     4621ASDF has been made to work with all actively maintained CL
     4622implementations and even a few implementations that are @emph{not}
     4623actively maintained.
     4624@xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
     4625Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly
     4626(though we recommend instead upgrading your implementation or its ASDF module).
     4627For this reason, we have stopped supporting ASDF 1 and ASDF 2.
     4628If you are using ASDF 1 or ASDF 2 and are experiencing any kind of issues or limitations,
     4629we recommend you upgrade to ASDF 3
     4630--- and we explain how to do that. @xref{Loading ASDF}.
     4631(In the context of compatibility requirements,
     4632ASDF 2.27, released on Feb 1st 2013, and further 2.x releases up to 2.33,
     4633count as pre-releases of ASDF 3, and define the @code{:asdf3} feature;
     4634still, please use the latest release).
     4635Release ASDF 3.1.2 and later also define the @code{:asdf3.1} feature.
     4636
    42254637
    42264638@menu
    42274639* What are ASDF 1 2 3?::
     4640* How do I detect the ASDF version?::
    42284641* ASDF can portably name files in subdirectories::
    42294642* Output translations::
     
    42374650@end menu
    42384651
    4239 @node What are ASDF 1 2 3?, ASDF can portably name files in subdirectories, What has changed between ASDF 1 and ASDF 2?, What has changed between ASDF 1 and ASDF 2?
    4240 @subsection What are ASDF 1, ASDF 2 and ASDF 3?
     4652@node What are ASDF 1 2 3?, How do I detect the ASDF version?, What has changed between ASDF 1 and ASDF 2?, What has changed between ASDF 1 and ASDF 2?
     4653@subsection What are ASDF 1, ASDF 2, and ASDF 3?
    42414654
    42424655ASDF 1 refers to any release earlier than 1.369 or so (from August 2001 to October 2009),
     
    425146642.27 to 2.33 count as pre-releases to ASDF 3.
    42524665
     4666@node How do I detect the ASDF version?, ASDF can portably name files in subdirectories, What are ASDF 1 2 3?, What has changed between ASDF 1 and ASDF 2?
     4667@subsection How do I detect the ASDF version?
     4668@findex asdf-version
     4669@cindex *features*
     4670
    42534671All releases of ASDF
    42544672push @code{:asdf} onto @code{*features*}.
    42554673Releases starting with ASDF 2
    4256  push @code{:asdf2} onto @code{*features*}.
     4674push @code{:asdf2} onto @code{*features*}.
    42574675Releases starting with ASDF 3 (including 2.27 and later pre-releases)
    42584676push @code{:asdf3} onto @code{*features*}.
    4259 Furthermore, releases starting with ASDF 3.1 (March 2014),
    4260 though they count as ASDF 3, includes enough progress that they
     4677Furthermore, releases starting with ASDF 3.1.2 (May 2014),
     4678though they count as ASDF 3, include enough progress that they
    42614679push @code{:asdf3.1} onto @code{*features*}.
    42624680You may depend on the presence or absence of these features
     
    42734691
    42744692
    4275 @node ASDF can portably name files in subdirectories, Output translations, What are ASDF 1 2 3?, What has changed between ASDF 1 and ASDF 2?
     4693@node ASDF can portably name files in subdirectories, Output translations, How do I detect the ASDF version?, What has changed between ASDF 1 and ASDF 2?
    42764694@subsection ASDF can portably name files in subdirectories
    42774695
    42784696Common Lisp namestrings are not portable,
    4279 except maybe for logical pathnamestrings,
     4697except maybe for logical pathname namestrings,
    42804698that themselves have various limitations and require a lot of setup
    42814699that is itself ultimately non-portable.
     
    43984816(say with thousands of components) by using
    43994817hash-tables instead of linear search,
    4400 and linear-time list accumulation
    4401 instead of quadratic-time recursive appends.
     4818and linear-time list accumulation instead of cubic time recursive append,
     4819for an overall @emph{O(n)} complexity vs @emph{O(n^4)}.
    44024820
    44034821@item
     
    44104828While still incomplete, it now fully passes
    44114829on all implementations supported by the test suite,
    4412 except for GCL (due to GCL bugs).
     4830though some tests are commented out on a few implementations.
    44134831
    44144832@item
     
    46325050
    46335051@item
    4634 You may, like SBCL, have ASDF be implicitly used to require systems
    4635 that are bundled with your Lisp distribution.
    4636 If you do have a few magic systems that come with your implementation
    4637 in a precompiled way such that one should only use the binary version
    4638 that goes with your distribution, like SBCL does,
    4639 then you should add them in the beginning of @code{wrapping-source-registry}.
    4640 
    4641 @item
    4642 If you have magic systems as above, like SBCL does,
     5052You may, like SBCL since 1.1.13 or MKCL since 1.1.9,
     5053have ASDF create bundle FASLs
     5054that are provided as modules by your Lisp distribution.
     5055You may also, but we don't recommend that anymore,
     5056have ASDF like SBCL up until 1.1.12 be implicitly used
     5057when requiring modules that are provided by your Lisp distribution;
     5058if you do, you should add them in the beginning of both
     5059@code{wrapping-source-registry} and @code{wrapping-output-translations}.
     5060
     5061@item
     5062If you have magic systems as above, like SBCL used to do,
    46435063then we explicitly ask you to @emph{NOT} distribute
    46445064@file{asdf.asd} as part of those magic systems.
     
    46645084Non-magic systems should be at the back of the @code{wrapping-source-registry}
    46655085while magic systems are at the front.
     5086If they are precompiled,
     5087they should also be in the @code{wrapping-output-translations}.
    46665088
    46675089@item
     
    47435165@end example
    47445166
     5167Note that this does @emph{NOT} belong in a @file{.asd} file.
     5168Please do not tamper with ASDF configuration from a @file{.asd} file,
     5169and only do this from your personal configuration or build scripts.
     5170
    47455171@node Issues with using and extending ASDF to define systems, ASDF development FAQs, Issues with configuring ASDF, FAQ
    47465172@section Issues with using and extending ASDF to define systems
     
    47525178* I want to put my module's files at the top level.  How do I do this?::
    47535179* How do I create a system definition where all the source files have a .cl extension?::
     5180* How do I mark a source file to be loaded only and not compiled?::
     5181* How do I work with readtables?::
    47545182@end menu
    47555183
     
    47655193and on the
    47665194@url{https://launchpad.net/asdf,launchpad bug-tracker}.
    4767 
    4768 Here are some guidelines:
    4769 
    4770 @itemize
    4771 @item
    4772 For a given system, @var{foo}, you will want to define a corresponding
    4773 test system, such as @var{foo-test}.  The reason that you will want this
    4774 separate system is that ASDF does not out of the box supply components
    4775 that are conditionally loaded.  So if you want to have source files
    4776 (with the test definitions) that will not be loaded except when testing,
    4777 they should be put elsewhere.
    4778 
    4779 @item
    4780 The @var{foo-test} system can be defined in an asd file of its own or
    4781 together with @var{foo}.  An aesthetic preference against cluttering up
    4782 the filesystem with extra asd files should be balanced against the
    4783 question of whether one might want to directly load @var{foo-test}.
    4784 Typically one would not want to do this except in early stages of
    4785 debugging.
    4786 
    4787 @item
    4788 Record that testing is implemented by @var{foo-test}.  For example:
    4789 @example
    4790 (defsystem @var{foo}
    4791    :in-order-to ((test-op (test-op @var{foo-test})))
    4792    ....)
    4793 
    4794 (defsystem @var{foo-test}
    4795    :depends-on (@var{foo} @var{my-test-library} ...)
    4796    ....)
    4797 @end example
    4798 @end itemize
    4799 
    4800 This procedure will allow you to support users who do not wish to
    4801 install your test framework.
    4802 
    4803 One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
    4804 does not return a value.  So in current versions of ASDF there is no
    4805 reliable programmatic means of determining whether or not a set of tests
    4806 has passed, or which tests have failed.  The user must simply read the
    4807 console output.  This limitation has been the subject of much
    4808 discussion.
     5195We provide some guidelines in the discussion of @code{test-op}.
     5196
     5197@c cut the following because it's discussed in the discussion of test-op.
     5198@c Here are some guidelines:
     5199
     5200@c @itemize
     5201@c @item
     5202@c For a given system, @var{foo}, you will want to define a corresponding
     5203@c test system, such as @var{foo-test}.  The reason that you will want this
     5204@c separate system is that ASDF does not out of the box supply components
     5205@c that are conditionally loaded.  So if you want to have source files
     5206@c (with the test definitions) that will not be loaded except when testing,
     5207@c they should be put elsewhere.
     5208
     5209@c @item
     5210@c The @var{foo-test} system can be defined in an asd file of its own or
     5211@c together with @var{foo}.  An aesthetic preference against cluttering up
     5212@c the filesystem with extra asd files should be balanced against the
     5213@c question of whether one might want to directly load @var{foo-test}.
     5214@c Typically one would not want to do this except in early stages of
     5215@c debugging.
     5216
     5217@c @item
     5218@c Record that testing is implemented by @var{foo-test}.  For example:
     5219@c @example
     5220@c (defsystem @var{foo}
     5221@c    :in-order-to ((test-op (test-op @var{foo-test})))
     5222@c    ....)
     5223
     5224@c (defsystem @var{foo-test}
     5225@c    :depends-on (@var{foo} @var{my-test-library} ...)
     5226@c    ....)
     5227@c @end example
     5228@c @end itemize
     5229
     5230@c This procedure will allow you to support users who do not wish to
     5231@c install your test framework.
     5232
     5233@c One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
     5234@c does not return a value.  So in current versions of ASDF there is no
     5235@c reliable programmatic means of determining whether or not a set of tests
     5236@c has passed, or which tests have failed.  The user must simply read the
     5237@c console output.  This limitation has been the subject of much
     5238@c discussion.
    48095239
    48105240@node How can I cater for documentation generation in my system?, How can I maintain non-Lisp (e.g. C) source files?, How can I cater for unit-testing in my system?, Issues with using and extending ASDF to define systems
     
    48865316(if the component class doesn't specifies a pathname type).
    48875317
    4888 @node How do I create a system definition where all the source files have a .cl extension?,  , I want to put my module's files at the top level.  How do I do this?, Issues with using and extending ASDF to define systems
     5318@node How do I create a system definition where all the source files have a .cl extension?, How do I mark a source file to be loaded only and not compiled?, I want to put my module's files at the top level.  How do I do this?, Issues with using and extending ASDF to define systems
    48895319@subsection How do I create a system definition where all the source files have a .cl extension?
    48905320
     
    49555385@end lisp
    49565386
     5387@node How do I mark a source file to be loaded only and not compiled?, How do I work with readtables?, How do I create a system definition where all the source files have a .cl extension?, Issues with using and extending ASDF to define systems
     5388@subsection How do I mark a source file to be loaded only and not compiled?
     5389
     5390There is no provision in ASDF for ensuring that
     5391some components are always loaded as source, while others are always
     5392compiled.
     5393There is @code{load-source-op} (@pxref{Predefined operations of
     5394ASDF,load-source-op}), but that is an operation to be applied to a
     5395system as a whole, not to one or another specific source files.
     5396While this idea often comes up in discussions,
     5397it doesn't play well with either the linking model of ECL
     5398or with various bundle operations.
     5399In addition, the dependency model of ASDF would have to be modified incompatibly
     5400to allow for such a trick.
     5401@c If your code doesn't compile cleanly, fix it.
     5402@c If compilation makes it slow, use @code{declaim} or @code{eval-when}
     5403@c to adjust your compiler settings,
     5404@c or eschew compilation by @code{eval}uating a quoted source form at load-time.
     5405
     5406@node How do I work with readtables?,  , How do I mark a source file to be loaded only and not compiled?, Issues with using and extending ASDF to define systems
     5407@subsection How do I work with readtables?
     5408
     5409@cindex readtables
     5410
     5411It is possible to configure the lisp syntax by modifying the currently-active readtable.
     5412However, this same readtable is shared globally by all software being compiled by ASDF,
     5413especially since @code{load} and @code{compile-file} both bind @var{*readtable*},
     5414so that its value is the same across the build at the start of every file
     5415(unless overridden by some @code{perform :around} method),
     5416even if a file locally binds it to a different readtable during the build.
     5417
     5418Therefore, the following hygiene restrictions apply. If you don't abide by these restrictions,
     5419there will be situations where your output files will be corrupted during an incremental build.
     5420We are not trying to prescribe new restrictions for the sake of good style:
     5421these restrictions have always applied implicitly, and
     5422we are simply describing what they have always been.
     5423
     5424@itemize
     5425@item It is forbidden to modifying any standard character or standard macro dispatch defined in the CLHS.
     5426@item No two dependencies may assign different meanings to the same non-standard character.
     5427@item Using any non-standard character while expecting the implementation to treat some way
     5428    counts as such an assignment of meaning.
     5429@item libraries need to document these assignments of meaning to non-standard characters.
     5430@item free software libraries will register these changes on:
     5431        @url{http://www.cliki.net/Macro%20Characters}
     5432@end itemize
     5433
     5434If you want to use readtable modifications that cannot abide by those restrictions,
     5435you @emph{must} create a different readtable object and set @var{*readtable*}
     5436to temporarily bind it to your new readtable (which will be undone after processing the file).
     5437
     5438For that, we recommend you use system @code{named-readtables}
     5439to define or combine such readtables using @code{named-readtables:defreadtable}
     5440and use them using @code{named-readtables:in-readtable}.
     5441Equivalently, you can use system @code{cl-syntax},
     5442that itself uses @code{named-readtables},
     5443but may someday do more with, e.g. @var{*print-pprint-dispatch*}.
     5444
     5445For even more advanced syntax modification beyond what a readtable can express,
     5446you may consider either:
     5447@itemize
     5448@item a @code{perform} method that compiles a constant file that contains a single form
     5449  @code{#.*code-read-with-alternate-reader*} in an environment where this special variable
     5450  was bound to the code read by your alternate reader, or
     5451@item using the system @code{reader-interception}.
     5452@end itemize
     5453
     5454Beware that @c unless and until the @code{syntax-control} branch is merged,
     5455it is unsafe to use ASDF from the REPL to compile or load systems
     5456while the readtable isn't the shared readtable previously used to build software.
     5457You @emph{must} manually undo any binding of @var{*readtable*} at the REPL
     5458and restore its initial value whenever you call @code{operate}
     5459(via e.g. @code{load-system}, @code{test-system} or @code{require})
     5460from a REPL that is using a different readtable.
     5461
     5462@subsubsection How should my system use a readtable exported by another system?
     5463
     5464Use from the @code{named-readtables} system the macro @code{named-readtables:in-readtable}.
     5465
     5466If the other system fails to use @code{named-readtables}, fix it and send a patch upstream.
     5467In the day and age of Quicklisp and clbuild, there is little reason
     5468to eschew using such an important library anymore.
     5469
     5470@subsubsection How should my library make a readtable available to other systems?
     5471
     5472Use from the @code{named-readtables} system the macro @code{named-readtables:defreadtable}.
     5473
    49575474@node ASDF development FAQs,  , Issues with using and extending ASDF to define systems, FAQ
    49585475@section ASDF development FAQs
     
    49715488Here's the procedure for experimenting with tests in a REPL:
    49725489@example
     5490;; BEWARE! Some tests expect you to be in the .../asdf/test directory
     5491;; If your REPL is not there yet, change your current directory:
     5492;; under SLIME, you may: ,change-directory ~/common-lisp/asdf/test/
     5493;; otherwise you may evaluate something like:
     5494(require "asdf") (asdf:upgrade-asdf) ;load UIOP & update asdf.lisp
     5495(uiop:chdir (asdf:system-relative-pathname :asdf "test/"))
     5496(setf *default-pathname-defaults* (uiop:getcwd))
     5497
     5498;; Load the test script support.
    49735499(load "script-support.lisp")
    4974 (in-package :asdf-test)
    4975 (compile-load-asdf) ; there are a number of other functions to load ASDF
    4976 ;; experiment with test code from a .script file...
     5500
     5501;; Initialize the script support.
     5502;; This will also change your *package* to asdf-test.
     5503;; NB: this function is also available from package cl-user,
     5504;; and also available with the shorter name da in both packages.
     5505(asdf-test::debug-asdf)
     5506
     5507;; In case you modified ASDF since you last tested it,
     5508;; you need to update asdf.lisp itself by evaluating 'make' in a shell,
     5509;; or (require "asdf") (asdf:load-system :asdf) in another CL REPL,
     5510;; if not done in this REPL above.
     5511;; *Then*, in this REPL, you need to evaluate:
     5512;(asdf-test::compile-load-asdf)
     5513
     5514;; Now, you may experiment with test code from a .script file.
     5515;; See the instructions given at the end of your failing test
     5516;; to identify which form is needed, e.g.
     5517(frob-packages)
     5518(asdf::with-asdf-cache () (load "test-utilities.script"))
    49775519@end example
    49785520
     
    49865528see the @file{TODO} file in the source repository.
    49875529
    4988 Also, bugs that are now tracked on launchpad:
     5530Also, bugs are now tracked on launchpad:
    49895531@url{https://launchpad.net/asdf}.
    49905532
     
    49935535
    49945536@itemize
     5537@item Francois-Rene Rideau:
     5538  ``ASDF 3, or Why Lisp is Now an Acceptable Scripting Language'', 2014.
     5539  This article describes the innovations in ASDF 3 and 3.1,
     5540  as well as historical information on previous versions.
     5541  @url{http://github.com/fare/asdf3-2013}
     5542@item Alastair Bridgewater:
     5543  ``Quick-build'' (private communication), 2012.
     5544  @code{quick-build} is a simple and robust one file, one package build system,
     5545  similar to @code{faslpath}, in 182 lines of code
     5546  (117 of which are not blank, not comments, not docstrings).
     5547  Unhappily, it remains unpublished and its IP status is unclear as of April 2014.
     5548  @code{asdf/package-system} is mostly compatible with it,
     5549  modulo a different setup for toplevel hierarchies.
    49955550@item Zach Beane:
    49965551  ``Quicklisp'', 2011.
     
    50095564  though many other of which still haven't.
    50105565  @url{http://common-lisp.net/projects/xcvb/}
    5011 @item Dan Barlow: ``ASDF Manual'', 2004
     5566@item Peter von Etter:
     5567  ``faslpath'', 2009.
     5568  @code{faslpath} is similar to the latter @code{quick-build}
     5569  and our letter @code{asdf/package-system} extension,
     5570  except that it uses the dot @code{.} rather than the slash @code{/} as a separator.
     5571  @url{https://code.google.com/p/faslpath/}
     5572@item Drew McDermott:
     5573  ``A Framework for Maintaining the Coherence of a Running Lisp,''
     5574  International Lisp Conference, 2005, available in pre-print form at
     5575  @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf}
     5576@item Dan Barlow: ``ASDF Manual'', 2004.
    50125577  Older versions of this document from the days of ASDF 1;
    50135578  they include ideas laid down by Dan Barlow,
     
    50305595  The famous CHINE NUAL describes one of the earliest variants of DEFSYSTEM.
    50315596  @url{https://bitsavers.trailing-edge.com/pdf/mit/cadr/chinual_4thEd_Jul81.pdf}
    5032 @item Drew McDermott: ``A Framework for Maintaining the Coherence of a
    5033   Running Lisp,'' International Lisp Conference, 2005, available in
    5034   pre-print form at @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf}.
    50355597@end itemize
    50365598
  • trunk/abcl/src/org/armedbear/lisp/asdf.lisp

    r14661 r14713  
    11;;; -*- mode: Common-Lisp; Base: 10 ; Syntax: ANSI-Common-Lisp ; buffer-read-only: t; -*-
    2 ;;; This is ASDF 3.1.0.103: Another System Definition Facility.
     2;;; This is ASDF 3.1.2.2: Another System Definition Facility.
    33;;;
    44;;; Feedback, bug reports, and patches are all welcome:
     
    820820          `(apply 'ensure-package ',(parse-define-package-form package clauses))))
    821821    `(progn
    822        #+(or ecl gcl) (defpackage ,package (:use))
     822       #+(or ecl gcl mkcl) (defpackage ,package (:use))
    823823       (eval-when (:compile-toplevel :load-toplevel :execute)
    824824         ,ensure-form))))
     
    16681668except on ABCL where it might change between FASL compilation and runtime."
    16691669    (loop* :with o
    1670            :for (feature . detect) :in '((:os-unix . os-unix-p) (:os-windows . os-windows-p)
    1671                                          (:os-macosx . os-macosx-p)
     1670           :for (feature . detect) :in '((:os-unix . os-unix-p) (:os-macosx . os-macosx-p)
     1671                                         (:os-windows . os-windows-p)
    16721672                                         (:genera . os-genera-p) (:os-oldmac . os-oldmac-p))
    1673            :when (and (not o) (funcall detect)) :do (setf o feature) (pushnew o *features*)
     1673           :when (and (or (not o) (eq feature :os-macosx)) (funcall detect))
     1674           :do (setf o feature) (pushnew feature *features*)
    16741675           :else :do (setf *features* (remove feature *features*))
    16751676           :finally
     
    18511852  (defun getcwd ()
    18521853    "Get the current working directory as per POSIX getcwd(3), as a pathname object"
    1853     (or #+abcl (symbol-call :asdf/filesystem :parse-native-namestring
    1854                             (java:jstatic "getProperty" "java.lang.System" "user.dir")
    1855                                                      :ensure-directory t)
     1854    (or #+abcl (truename (symbol-call :asdf/filesystem :parse-native-namestring
     1855                          (java:jstatic "getProperty" "java.lang.System" "user.dir")
     1856                          :ensure-directory t))
    18561857        #+allegro (excl::current-directory)
    18571858        #+clisp (ext:default-directory)
     
    39903991    (assert (or streamp pathnamep))
    39913992    (let* ((afterp (position :close-stream body))
    3992            (before (if afterp (subseq body 0 (1- afterp)) body))
     3993           (before (if afterp (subseq body 0 afterp) body))
    39933994           (after (when afterp (subseq body (1+ afterp))))
    39943995           (beforef (gensym "BEFORE"))
     
    40104011          ,@(when type `(:type ,type))
    40114012          ,@(when keep `(:keep ,keep))
    4012           ,@(when after `(:after `#',afterf))
     4013          ,@(when after `(:after #',afterf))
    40134014          ,@(when element-type `(:element-type ,element-type))
    40144015          ,@(when external-format `(:external-format ,external-format))))))
     
    44684469                       &key kind output-name prologue-code epilogue-code extra-object-files
    44694470                         (prelude () preludep) (postlude () postludep)
    4470                          (entry-point () entry-point-p) build-args)
     4471                         (entry-point () entry-point-p) build-args no-uiop)
    44714472    (declare (ignorable destination lisp-object-files extra-object-files kind output-name
    44724473                        prologue-code epilogue-code prelude preludep postlude postludep
    4473                         entry-point entry-point-p build-args))
     4474                        entry-point entry-point-p build-args no-uiop))
    44744475    "On ECL, create an executable at pathname DESTINATION from the specified OBJECT-FILES and options"
    44754476    ;; Is it meaningful to run these in the current environment?
     
    44784479    #-(or ecl mkcl) (error "~S not implemented for your implementation (yet)" 'create-image)
    44794480    #+(or ecl mkcl)
    4480     (let ((epilogue-forms
    4481             (append
    4482              (when epilogue-code `(,epilogue-code))
    4483              (when postludep `((setf *image-postlude* ',postlude)))
    4484              (when preludep `((setf *image-prelude* ',prelude)))
    4485              (when entry-point-p `((setf *image-entry-point* ',entry-point)))
    4486              (case kind
    4487                ((:image)
    4488                 (setf kind :program) ;; to ECL, it's just another program.
    4489                 `((setf *image-dumped-p* t)
    4490                   (si::top-level #+ecl t) (quit)))
    4491                ((:program)
    4492                 `((setf *image-dumped-p* :executable)
    4493                   (shell-boolean-exit
    4494                    (restore-image))))))))
     4481    (let ((epilogue-code
     4482            (if no-uiop
     4483                epilogue-code
     4484                (let ((forms
     4485                        (append
     4486                         (when epilogue-code `(,epilogue-code))
     4487                         (when postludep `((setf *image-postlude* ',postlude)))
     4488                         (when preludep `((setf *image-prelude* ',prelude)))
     4489                         (when entry-point-p `((setf *image-entry-point* ',entry-point)))
     4490                         (case kind
     4491                           ((:image)
     4492                            (setf kind :program) ;; to ECL, it's just another program.
     4493                            `((setf *image-dumped-p* t)
     4494                              (si::top-level #+ecl t) (quit)))
     4495                           ((:program)
     4496                            `((setf *image-dumped-p* :executable)
     4497                              (shell-boolean-exit
     4498                               (restore-image))))))))
     4499                  (when forms `(progn ,@forms))))))
    44954500      #+ecl (check-type kind (member :dll :lib :static-library :program :object :fasl))
    44964501      (apply #+ecl 'c::builder #+ecl kind
     
    45054510             (append
    45064511              (when prologue-code `(:prologue-code ,prologue-code))
    4507               (when epilogue-forms `(:epilogue-code (progn ,@epilogue-forms)))
     4512              (when epilogue-code `(:epilogue-code ,epilogue-code))
    45084513              #+mkcl (when extra-object-files `(:object-files ,extra-object-files))
    45094514              build-args)))))
     
    54285433   #+sbcl #:sb-grovel-unknown-constant-condition
    54295434   ;; Functions & Macros
    5430    #:get-optimization-settings #:proclaim-optimization-settings
     5435   #:get-optimization-settings #:proclaim-optimization-settings #:with-optimization-settings
    54315436   #:call-with-muffled-compiler-conditions #:with-muffled-compiler-conditions
    54325437   #:call-with-muffled-loader-conditions #:with-muffled-loader-conditions
     
    54685473  (defvar *previous-optimization-settings* nil
    54695474    "Optimization settings saved by PROCLAIM-OPTIMIZATION-SETTINGS")
     5475  (defparameter +optimization-variables+
     5476    ;; TODO: allegro genera corman mcl
     5477    (or #+(or abcl xcl) '(system::*speed* system::*space* system::*safety* system::*debug*)
     5478        #+clisp '() ;; system::*optimize* is a constant hash-table! (with non-constant contents)
     5479        #+clozure '(ccl::*nx-speed* ccl::*nx-space* ccl::*nx-safety*
     5480                    ccl::*nx-debug* ccl::*nx-cspeed*)
     5481        #+(or cmu scl) '(c::*default-cookie*)
     5482        #+ecl (unless (use-ecl-byte-compiler-p) '(c::*speed* c::*space* c::*safety* c::*debug*))
     5483        #+gcl '(compiler::*speed* compiler::*space* compiler::*compiler-new-safety* compiler::*debug*)
     5484        #+lispworks '(compiler::*optimization-level*)
     5485        #+mkcl '(si::*speed* si::*space* si::*safety* si::*debug*)
     5486        #+sbcl '(sb-c::*policy*)))
    54705487  (defun get-optimization-settings ()
    54715488    "Get current compiler optimization settings, ready to PROCLAIM again"
    5472     #-(or clisp clozure cmu ecl mkcl sbcl scl)
    5473     (warn "~S does not support ~S. Please help me fix that." 'get-optimization-settings (implementation-type))
    5474     #+clozure (ccl:declaration-information 'optimize nil)
    5475     #+(or clisp cmu ecl mkcl sbcl scl)
     5489    #-(or abcl allegro clisp clozure cmu ecl lispworks mkcl sbcl scl xcl)
     5490    (warn "~S does not support ~S. Please help me fix that."
     5491          'get-optimization-settings (implementation-type))
     5492    #+(or abcl allegro clisp clozure cmu ecl lispworks mkcl sbcl scl xcl)
    54765493    (let ((settings '(speed space safety debug compilation-speed #+(or cmu scl) c::brevity)))
    5477       #.`(loop :for x :in settings
    5478                ,@(or #+ecl '(:for v :in '(c::*speed* c::*space* c::*safety* c::*debug*))
    5479                      #+mkcl '(:for v :in '(si::*speed* si::*space* si::*safety* si::*debug*))
    5480                      #+(or cmu scl) '(:for f :in '(c::cookie-speed c::cookie-space c::cookie-safety c::cookie-debug c::cookie-cspeed c::cookie-brevity)))
    5481                :for y = (or #+clisp (gethash x system::*optimize*)
    5482                             #+(or ecl mkcl) (symbol-value v)
    5483                             #+(or cmu scl) (funcall f c::*default-cookie*)
     5494      #.`(loop #+(or allegro clozure)
     5495               ,@'(:with info = #+allegro (sys:declaration-information 'optimize)
     5496                   #+clozure (ccl:declaration-information 'optimize nil))
     5497               :for x :in settings
     5498               ,@(or #+(or abcl ecl gcl mkcl xcl) '(:for v :in +optimization-variables+))
     5499               :for y = (or #+(or allegro clozure) (second (assoc x info)) ; normalize order
     5500                            #+clisp (gethash x system::*optimize* 1)
     5501                            #+(or abcl ecl mkcl xcl) (symbol-value v)
     5502                            #+(or cmu scl) (slot-value c::*default-cookie*
     5503                                                       (case x (compilation-speed 'c::cspeed)
     5504                                                             (otherwise x)))
     5505                            #+lispworks (slot-value compiler::*optimization-level* x)
    54845506                            #+sbcl (cdr (assoc x sb-c::*policy*)))
    54855507               :when y :collect (list x y))))
     
    54895511    (let ((settings (get-optimization-settings)))
    54905512      (unless (equal *previous-optimization-settings* settings)
    5491         (setf *previous-optimization-settings* settings)))))
     5513        (setf *previous-optimization-settings* settings))))
     5514  (defmacro with-optimization-settings ((&optional (settings *optimization-settings*)) &body body)
     5515    #+(or allegro clisp)
     5516    (let ((previous-settings (gensym "PREVIOUS-SETTINGS")))
     5517      `(let ((,previous-settings (get-optimization-settings)))
     5518         ,@(when settings `((proclaim `(optimize ,@,settings))))
     5519         (unwind-protect (progn ,@body)
     5520           (proclaim `(optimize ,@,previous-settings)))))
     5521    #-(or allegro clisp)
     5522    `(let ,(loop :for v :in +optimization-variables+ :collect `(,v ,v))
     5523       ,@(when settings `((proclaim `(optimize ,@,settings))))
     5524       ,@body)))
    54925525
    54935526
     
    65366569   :uiop/configuration :uiop/backward-driver))
    65376570
    6538 #+mkcl (provide :uiop)
     6571;; Provide both lowercase and uppercase, to satisfy more people.
     6572(provide "uiop") (provide "UIOP")
    65396573;;;; -------------------------------------------------------------------------
    65406574;;;; Handle upgrade as forward- and backward-compatibly as possible
     
    66066640         ;; "3.4.5.0.8" would be your eighth local modification of official release 3.4.5
    66076641         ;; "3.4.5.67.8" would be your eighth local modification of development version 3.4.5.67
    6608          (asdf-version "3.1.0.103")
     6642         (asdf-version "3.1.2.2")
    66096643         (existing-version (asdf-version)))
    66106644    (setf *asdf-version* asdf-version)
     
    69646998;;;; version-satisfies
    69656999(with-upgradability ()
     7000  ;; short-circuit testing of null version specifications.
     7001  ;; this is an all-pass, without warning
     7002  (defmethod version-satisfies :around ((c t) (version null))
     7003    t)
    69667004  (defmethod version-satisfies ((c component) version)
    69677005    (unless (and version (slot-boundp c 'version) (component-version c))
    69687006      (when version
    69697007        (warn "Requested version ~S but ~S has no version" version c))
    6970       (return-from version-satisfies t))
     7008      (return-from version-satisfies nil))
    69717009    (version-satisfies (component-version c) version))
    69727010
     
    91279165    ;; If we're in the middle of something, restart it.
    91289166    (when *asdf-cache*
    9129       (let ((l (loop* :for (x y) :being :the hash-keys :of *asdf-cache*
    9130                       :when (eq x 'find-system) :collect y)))
     9167      (let ((l (loop :for k :being :the hash-keys :of *asdf-cache*
     9168                     :when (eq (first k) 'find-system) :collect (second k))))
    91319169        (clrhash *asdf-cache*)
    91329170        (dolist (s l) (find-system s nil)))))
     
    1016310201    ((prologue-code :initform nil :initarg :prologue-code :reader prologue-code)
    1016410202     (epilogue-code :initform nil :initarg :epilogue-code :reader epilogue-code)
     10203     (no-uiop :initform nil :initarg :no-uiop :reader no-uiop)
    1016510204     (prefix-lisp-object-files :initarg :prefix-lisp-object-files
    1016610205                               :initform nil :accessor prefix-lisp-object-files)
     
    1017410213  (defmethod prologue-code ((x t)) nil)
    1017510214  (defmethod epilogue-code ((x t)) nil)
     10215  (defmethod no-uiop ((x t)) nil)
    1017610216  (defmethod prefix-lisp-object-files ((x t)) nil)
    1017710217  (defmethod postfix-lisp-object-files ((x t)) nil)
     
    1027310313      ((member :dll :lib :shared-library :static-library :program :object :program)
    1027410314       (compile-file-type :type bundle-type))
    10275       ((member :image) "image")
     10315      ((member :image) #-allegro "image" #+allegro "dxl")
    1027610316      ((member :dll :shared-library) (cond ((os-macosx-p) "dylib") ((os-unix-p) "so") ((os-windows-p) "dll")))
    1027710317      ((member :lib :static-library) (cond ((os-unix-p) "a")
    10278              ((os-windows-p) (if (featurep '(:or :mingw32 :mingw64)) "a" "lib"))))
     10318                                           ((os-windows-p) (if (featurep '(:or :mingw32 :mingw64)) "a" "lib"))))
    1027910319      ((eql :program) (cond ((os-unix-p) nil) ((os-windows-p) "exe")))))
    1028010320
     
    1033710377    (setf (extra-build-args instance)
    1033810378          (remove-plist-keys
    10339            '(:type :monolithic :name-suffix :epilogue-code :prologue-code :lisp-files)
     10379           '(:type :monolithic :name-suffix :epilogue-code :prologue-code :lisp-files
     10380             :force :force-not :plan-class) ;; TODO: refactor so we don't mix plan and operation arguments
    1034010381           (operation-original-initargs instance))))
    1034110382
     
    1058710628
    1058810629  (defun asdf-library-pathname ()
    10589     #+ecl (compile-file-pathname "sys:asdf" :type :lib)
     10630    #+ecl (or (probe-file* (compile-file-pathname "sys:asdf" :type :lib)) ;; new style
     10631              (probe-file* (compile-file-pathname "sys:asdf" :type :object))) ;; old style
    1059010632    #+mkcl (make-pathname :type (bundle-pathname-type :lib) :defaults #p"sys:contrib;asdf"))
    1059110633
     10634  (defun compiler-library-pathname ()
     10635    #+ecl (compile-file-pathname "sys:cmp" :type :lib)
     10636    #+mkcl (make-pathname :type (bundle-pathname-type :lib) :defaults #p"sys:cmp"))
     10637
    1059210638  (defun make-library-system (name pathname)
    10593     (make-instance 'prebuilt-system :name name :static-library (resolve-symlinks* pathname)))
     10639    (make-instance 'prebuilt-system
     10640                   :name (coerce-name name) :static-library (resolve-symlinks* pathname)))
    1059410641
    1059510642  (defmethod component-depends-on :around ((o image-op) (c system))
     
    1059710644      (flet ((has-it-p (x) (find x deps :test 'equal :key 'coerce-name)))
    1059810645        `((,lib-op
    10599            #+mkcl ,@(unless (has-it-p "cmp")
    10600                       `(,(make-library-system
    10601                           "cmp" (make-pathname :type (bundle-pathname-type :lib)
    10602                                                :defaults #p"sys:cmp"))))
    10603            ,@(unless (or (has-it-p "asdf") (has-it-p "uiop"))
     10646           ,@(unless (or (no-uiop c) (has-it-p "cmp"))
     10647               `(,(make-library-system
     10648                   "cmp" (compiler-library-pathname))))
     10649           ,@(unless (or (no-uiop c) (has-it-p "uiop") (has-it-p "asdf"))
    1060410650               `(,(cond
    1060510651                    ((system-source-directory :uiop) (find-system :uiop))
    1060610652                    ((system-source-directory :asdf) (find-system :asdf))
    10607                     (t (make-fake-asdf-system "asdf" (asdf-library-pathname))))))
     10653                    (t (make-library-system "asdf" (asdf-library-pathname))))))
    1060810654           ,@deps)))))
    1060910655
     
    1062510671               :build-args (or (extra-build-args o) (when programp (extra-build-args c)))
    1062610672               :extra-object-files (or (extra-object-files o) (when programp (extra-object-files c)))
     10673               :no-uiop (no-uiop c)
    1062710674               (when programp `(:entry-point ,(component-entry-point c))))))))
    1062810675
     
    1063810685
    1063910686
    10640 ;;; Backward compatibility with pre-3.1.1 names
     10687;;; Backward compatibility with pre-3.1.2 names
    1064110688(defclass fasl-op (selfward-operation)
    1064210689  ((selfward-operation :initform 'compile-bundle-op :allocation :class)))
     
    1091810965;;;; Package systems in the style of quick-build or faslpath
    1091910966
    10920 (uiop:define-package :asdf/package-system
    10921   (:recycle :asdf/package-system :asdf)
     10967(uiop:define-package :asdf/package-inferred-system
     10968  (:recycle :asdf/package-inferred-system :asdf/package-system :asdf)
    1092210969  (:use :uiop/common-lisp :uiop
    1092310970        :asdf/defsystem ;; Using the old name of :asdf/parse-defsystem for compatibility
    1092410971        :asdf/upgrade :asdf/component :asdf/system :asdf/find-system :asdf/lisp-action)
    1092510972  (:export
    10926    #:package-system #:register-system-packages #:sysdef-package-system-search
    10927    #:*defpackage-forms* #:*package-systems* #:package-system-missing-package-error))
    10928 (in-package :asdf/package-system)
    10929 
    10930 (with-upgradability ()
    10931   (defparameter *defpackage-forms* '(cl:defpackage uiop:define-package))
    10932 
    10933   (defun initial-package-systems-table ()
     10973   #:package-inferred-system #:sysdef-package-inferred-system-search
     10974   #:package-system ;; backward compatibility only. To be removed.
     10975   #:register-system-packages
     10976   #:*defpackage-forms* #:*package-inferred-systems* #:package-inferred-system-missing-package-error))
     10977(in-package :asdf/package-inferred-system)
     10978
     10979(with-upgradability ()
     10980  (defparameter *defpackage-forms* '(defpackage define-package))
     10981
     10982  (defun initial-package-inferred-systems-table ()
    1093410983    (let ((h (make-hash-table :test 'equal)))
    1093510984      (dolist (p (list-all-packages))
     
    1093810987      h))
    1093910988
    10940   (defvar *package-systems* (initial-package-systems-table))
    10941 
    10942   (defclass package-system (system)
     10989  (defvar *package-inferred-systems* (initial-package-inferred-systems-table))
     10990
     10991  (defclass package-inferred-system (system)
    1094310992    ())
     10993
     10994  ;; For backward compatibility only. To be removed in an upcoming release:
     10995  (defclass package-system (package-inferred-system) ())
    1094410996
    1094510997  (defun defpackage-form-p (form)
     
    1095611008      (stream-defpackage-form f)))
    1095711009
    10958   (define-condition package-system-missing-package-error (system-definition-error)
     11010  (define-condition package-inferred-system-missing-package-error (system-definition-error)
    1095911011    ((system :initarg :system :reader error-system)
    1096011012     (pathname :initarg :pathname :reader error-pathname))
    1096111013    (:report (lambda (c s)
    1096211014               (format s (compatfmt "~@<No package form found while ~
    10963                                      trying to define package-system ~A from file ~A~>")
     11015                                     trying to define package-inferred-system ~A from file ~A~>")
    1096411016                       (error-system c) (error-pathname c)))))
    1096511017
     
    1099011042    (let ((name (or (eq system t) (coerce-name system))))
    1099111043      (dolist (p (ensure-list packages))
    10992         (setf (gethash (package-designator-name p) *package-systems*) name))))
     11044        (setf (gethash (package-designator-name p) *package-inferred-systems*) name))))
    1099311045
    1099411046  (defun package-name-system (package-name)
     
    1099611048otherwise return a default system name computed from PACKAGE-NAME."
    1099711049    (check-type package-name string)
    10998     (if-let ((system-name (gethash package-name *package-systems*)))
     11050    (if-let ((system-name (gethash package-name *package-inferred-systems*)))
    1099911051      system-name
    1100011052      (string-downcase package-name)))
    1100111053
    11002   (defun package-system-file-dependencies (file &optional system)
     11054  (defun package-inferred-system-file-dependencies (file &optional system)
    1100311055    (if-let (defpackage-form (file-defpackage-form file))
    1100411056      (remove t (mapcar 'package-name-system (package-dependencies defpackage-form)))
    11005       (error 'package-system-missing-package-error :system system :pathname file)))
    11006 
    11007   (defun same-package-system-p (system name directory subpath dependencies)
    11008     (and (eq (type-of system) 'package-system)
     11057      (error 'package-inferred-system-missing-package-error :system system :pathname file)))
     11058
     11059  (defun same-package-inferred-system-p (system name directory subpath dependencies)
     11060    (and (eq (type-of system) 'package-inferred-system)
    1100911061         (equal (component-name system) name)
    1101011062         (pathname-equal directory (component-pathname system))
     
    1101811070                            (equal (slot-value child 'relative-pathname) subpath))))))))
    1101911071
    11020   (defun sysdef-package-system-search (system)
     11072  (defun sysdef-package-inferred-system-search (system)
    1102111073    (let ((primary (primary-system-name system)))
    1102211074      (unless (equal primary system)
    1102311075        (let ((top (find-system primary nil)))
    11024           (when (typep top 'package-system)
     11076          (when (typep top 'package-inferred-system)
    1102511077            (if-let (dir (system-source-directory top))
    1102611078              (let* ((sub (subseq system (1+ (length primary))))
     
    1102811080                                     :truename *resolve-symlinks*)))
    1102911081                (when (file-pathname-p f)
    11030                   (let ((dependencies (package-system-file-dependencies f system))
     11082                  (let ((dependencies (package-inferred-system-file-dependencies f system))
    1103111083                        (previous (cdr (system-registered-p system))))
    11032                     (if (same-package-system-p previous system dir sub dependencies)
     11084                    (if (same-package-inferred-system-p previous system dir sub dependencies)
    1103311085                        previous
    1103411086                        (eval `(defsystem ,system
    11035                                  :class package-system
     11087                                 :class package-inferred-system
    1103611088                                 :source-file nil
    1103711089                                 :pathname ,dir
     
    1104011092
    1104111093(with-upgradability ()
    11042   (pushnew 'sysdef-package-system-search *system-definition-search-functions*))
     11094  (pushnew 'sysdef-package-inferred-system-search *system-definition-search-functions*)
     11095  (setf *system-definition-search-functions*
     11096        (remove (find-symbol* :sysdef-package-system-search :asdf/package-system nil)
     11097                *system-definition-search-functions*)))
    1104311098;;;; ---------------------------------------------------------------------------
    1104411099;;;; Handle ASDF package upgrade, including implementation-dependent magic.
     
    1105511110   :asdf/output-translations :asdf/source-registry
    1105611111   :asdf/plan :asdf/operate :asdf/parse-defsystem :asdf/bundle :asdf/concatenate-source
    11057    :asdf/backward-internals :asdf/backward-interface :asdf/package-system)
     11112   :asdf/backward-internals :asdf/backward-interface :asdf/package-inferred-system)
    1105811113  ;; Note: (1) we are NOT automatically reexporting everything from previous packages.
    1105911114  ;; (2) we only reexport UIOP functionality when backward-compatibility requires it.
     
    1110211157   #:file-type #:source-file-type
    1110311158
    11104    #:package-system #:register-system-packages
     11159   #:package-inferred-system #:register-system-packages
     11160   #:package-system ;; backward-compatibility during migration, to be removed in a further release.
    1110511161
    1110611162   #:component-children          ; component accessors
     
    1116511221   #:circular-dependency        ; errors
    1116611222   #:duplicate-names #:non-toplevel-system #:non-system-system
    11167    #:package-system-missing-package-error
     11223   #:package-inferred-system-missing-package-error
    1116811224   #:operation-definition-warning #:operation-definition-error
    1116911225
     
    1121511271(uiop/package:define-package :asdf/user
    1121611272  (:nicknames :asdf-user)
    11217   ;; NB: releases before 3.1.1 this :use'd only uiop/package instead of uiop below.
     11273  ;; NB: releases before 3.1.2 this :use'd only uiop/package instead of uiop below.
    1121811274  ;; They also :use'd uiop/common-lisp, that reexports common-lisp and is not included in uiop.
    1121911275  ;; ASDF3 releases from 2.27 to 2.31 called uiop asdf-driver and asdf/foo uiop/foo.
Note: See TracChangeset for help on using the changeset viewer.