source: trunk/abcl/doc/asdf/asdf.texinfo @ 14636

Last change on this file since 14636 was 14636, checked in by mevenson, 4 years ago


File size: 201.0 KB
1\input texinfo          @c -*- texinfo -*-
2@c %**start of header
4@settitle ASDF Manual
5@c %**end of header
7@c We use @&key, etc to escape & from TeX in lambda lists --
8@c so we need to define them for info as well.
9@macro AallowOtherKeys
11@end macro
12@macro Aoptional
14@end macro
15@macro Arest
17@end macro
18@macro Akey
20@end macro
21@macro Abody
23@end macro
25@c for install-info
26@dircategory Software development
28* asdf: (asdf).           Another System Definition Facility (for Common Lisp)
29@end direntry
32This manual describes ASDF, a system definition facility
33for Common Lisp programs and libraries.
35You can find the latest version of this manual at
38ASDF Copyright @copyright{} 2001-2014 Daniel Barlow and contributors.
40This manual Copyright @copyright{} 2001-2014 Daniel Barlow and contributors.
42This manual revised @copyright{} 2009-2014 Robert P. Goldman and Francois-Rene Rideau.
44Permission is hereby granted, free of charge, to any person obtaining
45a copy of this software and associated documentation files (the
46``Software''), to deal in the Software without restriction, including
47without limitation the rights to use, copy, modify, merge, publish,
48distribute, sublicense, and/or sell copies of the Software, and to
49permit persons to whom the Software is furnished to do so, subject to
50the following conditions:
52The above copyright notice and this permission notice shall be
53included in all copies or substantial portions of the Software.
63@end copying
68@title ASDF: Another System Definition Facility
70@c The following two commands start the copyright page.
72@vskip 0pt plus 1filll
74@end titlepage
76@c Output the table of contents at the beginning.
79@c -------------------
83@node Top, Introduction, (dir), (dir)
84@top ASDF: Another System Definition Facility
89* Introduction::
90* Quick start summary::
91* Loading ASDF::
92* Configuring ASDF::
93* Using ASDF::
94* Defining systems with defsystem::
95* The object model of ASDF::
96* Controlling where ASDF searches for systems::
97* Controlling where ASDF saves compiled files::
98* Error handling::
99* Miscellaneous additional functionality::
100* Getting the latest version::
101* FAQ::
102* Ongoing Work::
103* Bibliography::
104* Concept Index::
105* Function and Class Index::
106* Variable Index::              @c @detailmenu
110 --- The Detailed Node Listing ---
112Loading ASDF
114* Loading a pre-installed ASDF::
115* Checking whether ASDF is loaded::
116* Upgrading ASDF::
117* Loading an otherwise installed ASDF::
119Configuring ASDF
121* Configuring ASDF to find your systems::
122* Configuring where ASDF stores object files::
124Defining systems with defsystem
126* The defsystem form::
127* A more involved example::
128* The defsystem grammar::
129* Other code in .asd files::
130* The package-system extension::
132The object model of ASDF
134* Operations::
135* Components::
136* Functions::
140* Predefined operations of ASDF::
141* Creating new operations::
145* Common attributes of components::
146* Pre-defined subclasses of component::
147* Creating new component types::
151* Pre-defined subclasses of component::
152* Creating new component types::
156* Where do I report a bug?::
157* What has changed between ASDF 1 and ASDF 2?::
158* Issues with installing the proper version of ASDF::
159* Issues with configuring ASDF::
160* Issues with using and extending ASDF to define systems::
161* ASDF development FAQs::
163``What has changed between ASDF 1 and ASDF 2?''
165* What are ASDF 1 2 3?::
166* ASDF can portably name files in subdirectories::
167* Output translations::
168* Source Registry Configuration::
169* Usual operations are made easier to the user::
170* Many bugs have been fixed::
171* ASDF itself is versioned::
172* ASDF can be upgraded::
173* Decoupled release cycle::
174* Pitfalls of the transition to ASDF 2::
176Issues with installing the proper version of ASDF
178* My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
179* I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::
181Issues with configuring ASDF
183* How can I customize where fasl files are stored?::
184* How can I wholly disable the compiler output cache?::
186Issues with using and extending ASDF to define systems
188* How can I cater for unit-testing in my system?::
189* How can I cater for documentation generation in my system?::
190* How can I maintain non-Lisp (e.g. C) source files?::
191* I want to put my module's files at the top level.  How do I do this?::
192* How do I create a system definition where all the source files have a .cl extension?::
194ASDF development FAQs
196* How do run the tests interactively in a REPL?::
198@end detailmenu
199@end menu
201@end ifnottex
203@c -------------------
205@node Introduction, Quick start summary, Top, Top
206@comment  node-name,  next,  previous,  up
207@chapter Introduction
208@cindex ASDF-related features
209@vindex *features*
210@cindex Testing for ASDF
211@cindex ASDF versions
212@cindex :asdf
213@cindex :asdf2
214@cindex :asdf3
216ASDF is Another System Definition Facility:
217a tool for specifying how systems of Common Lisp software
218are comprised of components (sub-systems and files),
219and how to operate on these components in the right order
220so that they can be compiled, loaded, tested, etc.
222ASDF presents three faces:
223one for users of Common Lisp software who want to reuse other people's code,
224one for writers of Common Lisp software who want to specify how to build their systems,
225one for implementers of Common Lisp extensions who want to extend the build system.
226@xref{Using ASDF,,Loading a system},
227to learn how to use ASDF to load a system.
228@xref{Defining systems with defsystem},
229to learn how to define a system of your own.
230@xref{The object model of ASDF}, for a description of
231the ASDF internals and how to extend ASDF.
233@emph{Nota Bene}:
234We have released ASDF 2.000 on May 31st 2010,
235and ASDF 3.0.0 on May 15th 2013.
236Releases of ASDF 2 and later have since then been included
237in all actively maintained CL implementations that used to bundle ASDF 1,
238plus some implementations that didn't use to,
239and 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?''}.
241Furthermore, 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).
243For this reason, we have stopped supporting ASDF 1 and ASDF 2.
244If you are using ASDF 1 or ASDF 2 and are experiencing any kind of issues or limitations,
245we recommend you upgrade to ASDF 3
246--- and we explain how to do that. @xref{Loading ASDF}.
247(In the context of compatibility requirements,
248ASDF 2.27, released on Feb 1st 2013, and further 2.x releases up to 2.33,
249count as pre-releases of ASDF 3, and define the :asdf3 feature;
250still, please use the latest release).
252Also note that ASDF is not to be confused with ASDF-Install.
253ASDF-Install is not part of ASDF, but a separate piece of software.
254ASDF-Install is also unmaintained and obsolete.
255We recommend you use Quicklisp instead,
256which works great and is being actively maintained.
257If you want to download software from version control instead of tarballs,
258so you may more easily modify it, we recommend clbuild.
260@node  Quick start summary, Loading ASDF, Introduction, Top
261@chapter Quick start summary
265@item To load an ASDF system:
269Load ASDF itself into your Lisp image, either through
270@code{(require "asdf")} (if it's supplied by your lisp implementation)
271or else through
272@code{(load "/path/to/asdf.lisp")}.  For more details, @ref{Loading ASDF}.
275Make sure ASDF can find system definitions
276through proper source-registry configuration.
277For more details, @xref{Configuring ASDF to find your systems}.
278The simplest way is simply to put all your lisp code in subdirectories of
280Such code will automatically be found.
283Load a system with @code{(asdf:load-system :system)}. @xref{Using ASDF}.
285@end itemize
287@item To make your own ASDF system:
291As above, load and configure ASDF.
294Make a new directory for your system, @code{my-system/} in a location
295where ASDF can find it (@pxref{Configuring ASDF to find your systems}).
298Create an ASDF system definition listing the dependencies of
299your system, its components, and their interdependencies,
300and put it in @file{my-system.asd}.
301This file must have the same name as your system.
302@xref{Defining systems with defsystem}.
305Use @code{(asdf:load-system :my-system)}
306to make sure it's all working properly. @xref{Using ASDF}.
308@end itemize
309@end itemize
311@c FIXME: (1) add a sample project that the user can cut and paste to
312@c get started.  (2) discuss the option of starting with Quicklisp.
318@node Loading ASDF, Configuring ASDF, Quick start summary, Top
319@comment  node-name,  next,  previous,  up
320@chapter Loading ASDF
323* Loading a pre-installed ASDF::
324* Checking whether ASDF is loaded::
325* Upgrading ASDF::
326* Loading an otherwise installed ASDF::
327@end menu
329@node  Loading a pre-installed ASDF, Checking whether ASDF is loaded, Loading ASDF, Loading ASDF
330@section Loading a pre-installed ASDF
332Most recent Lisp implementations include a copy of ASDF 3,
333or at least ASDF 2.
334You can usually load this copy using Common Lisp's @code{require} function.@footnote{
335NB: all implementations except GNU CLISP also accept
336@code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}.
337For portability's sake, you should use @code{(require "asdf")}.
341(require "asdf")
342@end lisp
344As of the writing of this manual,
345the following implementations provide ASDF 3 this way:
346ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, mkcl, SBCL.
347The following implementations only provide ASDF 2:
348LispWorks, mocl, XCL.
349The following implementation doesn't provide ASDF yet but will in an upcoming release:
351The following implementations are obsolete, not actively maintained,
352and most probably will never bundle ASDF:
353Corman CL, GCL, Genera, MCL.
355If the implementation you are using doesn't provide ASDF 2 or ASDF 3,
356see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
357If that implementation is still actively maintained,
358you may also send a bug report to your Lisp vendor and complain
359about their failing to provide ASDF.
361@node Checking whether ASDF is loaded, Upgrading ASDF, Loading a pre-installed ASDF, Loading ASDF
362@section Checking whether ASDF is loaded
364To check whether ASDF is properly loaded in your current Lisp image,
365you can run this form:
369@end lisp
371If it returns a string,
372that is the version of ASDF that is currently installed.
374If it raises an error,
375then either ASDF is not loaded, or
376you are using an old version of ASDF.
378You can check whether an old version is loaded
379by checking if the ASDF package is present.
380The form below will allow you to programmatically determine
381whether a recent version is loaded, an old version is loaded,
382or none at all:
385(when (find-package :asdf)
386  (let ((ver (symbol-value (or (find-symbol (string :*asdf-version*) :asdf)
387                               (find-symbol (string :*asdf-revision*) :asdf)))))
388    (etypecase ver
389      (string ver)
390      (cons (with-output-to-string (s)
391              (loop for (n . m) on ver do (princ n s) (when m (princ "." s)))))
392      (null "1.0"))))
393@end lisp
395If it returns @code{nil} then ASDF is not installed.
396Otherwise it should return a string.
397If it returns @code{"1.0"}, then it can actually be
398any version before 1.77 or so, or some buggy variant of 1.x.
400If you are experiencing problems with ASDF,
401please try upgrading to the latest released version,
402using the method below,
403before you contact us and raise an issue.
405@node  Upgrading ASDF, Loading an otherwise installed ASDF, Checking whether ASDF is loaded, Loading ASDF
406@section Upgrading ASDF
407@c FIXME: tighten this up a bit -- there's a lot of stuff here that
408@c doesn't matter to almost anyone.  Move discussion of updating antique
409@c versions of ASDF down, or encapsulate it.
411If you want to upgrade to a more recent ASDF version,
412you need to install and configure your ASDF just like any other system
413(@pxref{Configuring ASDF to find your systems}).
415If your implementation provides ASDF 3 or later,
416you only need to @code{(require "asdf")}:
417ASDF will automatically look whether an updated version of itself is available
418amongst the regularly configured systems, before it compiles anything else.
420@subsection Notes about ASDF 1 and ASDF 2
422Most implementations provide ASDF 3 in their latest release,
423and we recommend upgrading your implementation rather than using ASDF 1 or 2.
424A few implementations only provide ASDF 2,
425that can be overridden by installing a fasl (see below).
426A few implementations don't provide ASDF,
427but a fasl can be installed to provide it.
428GCL so far is still lacking a usable @code{require} interface.
430If your implementation has no suitable upgrade available (yet),
431or somehow upgrading is not an option,
432we assume you're an expert deliberately using a legacy implementation,
433and are proficient enough to install this fasl.
434Still, the ASDF source repository contains a script
435@file{bin/install-asdf-as-module} that can help you do that.
436It relies on cl-launch 4 for command-line invocation,
437which may depend on ASDF being checked out in @file{~/cl/asdf/}
438if your implementation doesn't even have an ASDF 2;
439but you can run the code it manually if needs be.
441Finally, if your implementation only provides ASDF 2,
442and you can't or won't upgrade it or override its ASDF module,
443you may simply configure ASDF to find a proper upgrade;
444however, to avoid issues with a self-upgrade in mid-build,
445you @emph{must} make sure to upgrade ASDF immediately
446after requiring the builtin ASDF 2:
449(require "asdf")
450;; <--- insert programmatic configuration here if needed
451(asdf:load-system :asdf)
452@end lisp
454@subsection Issues with upgrading ASDF
456Note that there are some limitations to upgrading ASDF:
459Previously loaded ASDF extensions become invalid, and will need to be reloaded.
460Examples include CFFI-Grovel, hacks used by ironclad, etc.
461Since it isn't possible to automatically detect what extensions
462need to be invalidated,
463ASDF will invalidate @emph{all} previously loaded systems
464when it is loaded on top of a forward-incompatible ASDF version.
466@vindex *oldest-forward-compatible-asdf-version*
467Forward incompatibility can be determined using the variable
469which is 2.33 at the time of this writing.}
471Starting with ASDF 3 (2.27 or later),
472this self-upgrade will be automatically attempted as the first step
473to any system operation, to avoid any possibility of
474a catastrophic attempt to self-upgrade in mid-build.
476@c FIXME: Fix grammar below.
478For this and many other reasons,
479you should load, configure and upgrade ASDF
480as one of the very first things done by your build and startup scripts.
481It is safer if you upgrade ASDF and its extensions as a special step
482at the very beginning of whatever script you are running,
483before you start using ASDF to load anything else.
486Until all implementations provide ASDF 3 or later,
487it is unsafe to upgrade ASDF as part of loading a system
488that depends on a more recent version of ASDF,
489since the new one might shadow the old one while the old one is running,
490and the running old one will be confused
491when extensions are loaded into the new one.
492In the meantime, we recommend that your systems should @emph{not} specify
493@code{:depends-on (:asdf)}, or @code{:depends-on ((:version :asdf "3.0.1"))},
494but instead that they check that a recent enough ASDF is installed,
495with such code as:
497(unless (or #+asdf2 (asdf:version-satisfies
498                     (asdf:asdf-version) *required-asdf-version*))
499  (error "FOO requires ASDF ~A or later." *required-asdf-version*))
500@end example
502Until all implementations provide ASDF 3 or later,
503it is unsafe for a system to transitively depend on ASDF
504and not directly depend on ASDF;
505if any of the system you use either depends-on asdf,
506system-depends-on asdf, or transitively does,
507you should also do as well.
508@end itemize
510@node Loading an otherwise installed ASDF,  , Upgrading ASDF, Loading ASDF
511@section Loading an otherwise installed ASDF
513If your implementation doesn't include ASDF,
514if for some reason the upgrade somehow fails,
515does not or cannot apply to your case,
516you will have to install the file @file{asdf.lisp}
517somewhere and load it with:
520(load "/path/to/your/installed/asdf.lisp")
521@end lisp
523The single file @file{asdf.lisp} is all you normally need to use ASDF.
525You can extract this file from latest release tarball on the
526@url{,ASDF website}.
527If you are daring and willing to report bugs, you can get
528the latest and greatest version of ASDF from its git repository.
529@xref{Getting the latest version}.
531For maximum convenience you might want to have ASDF loaded
532whenever you start your Lisp implementation,
533for example by loading it from the startup script or dumping a custom core
534--- check your Lisp implementation's manual for details.
537@node Configuring ASDF, Using ASDF, Loading ASDF, Top
538@comment  node-name,  next,  previous,  up
539@chapter Configuring ASDF
541For standard use cases, ASDF should work pretty much out of the box.
542We recommend you skim the sections on configuring ASDF to find your systems
543and choose the method of installing Lisp software that works best for you.
544Then skip directly to @xref{Using ASDF}. That will probably be enough.
545You are unlikely to have to worry about the way ASDF stores object files,
546and resetting the ASDF configuration is usually only needed in corner cases.
550* Configuring ASDF to find your systems::
551* Configuring ASDF to find your systems --- old style::
552* Configuring where ASDF stores object files::
553* Resetting the ASDF configuration::
554@end menu
556@node Configuring ASDF to find your systems, Configuring where ASDF stores object files, Configuring ASDF, Configuring ASDF
557@section Configuring ASDF to find your systems
559In order to compile and load your systems, ASDF must be configured to find
560the @file{.asd} files that contain system definitions.
562There are a number of different techniques for setting yourself up with
563ASDF, starting from easiest to the most complex:
565@itemize @bullet
568Put all of your systems in subdirectories of
570If you install software there (it can be a symlink),
571you don't need further configuration.
574If you're using some tool to install software (e.g. Quicklisp),
575the authors of that tool should already have configured ASDF.
578If you have more specific desires about how to lay out your software on
579disk, the preferred way to configure where ASDF finds your systems is
580the @code{source-registry} facility,
581fully described in its own chapter of this manual.
582@xref{Controlling where ASDF searches for systems}.  Here is a quick
583recipe for getting started:
585The simplest way to add a path to your search path,
586say @file{/home/luser/.asd-link-farm/}
587is to create the directory
589and there create a file with any name of your choice,
590and with the type @file{conf}@footnote{By requiring the @file{.conf}
591extension, and ignoring other files, ASDF allows you to have disabled files,
592editor backups, etc. in the same directory with your active
593configuration files.
595ASDF will also ignore files whose names start with a @file{.} character.
597It is customary to start the filename with two digits, to control the
598sorting of the @code{conf} files in the source registry directory, and
599thus the order in which the directories will be scanned.},
600for instance @file{42-asd-link-farm.conf},
601containing the line:
603@kbd{(:directory "/home/luser/.asd-link-farm/")}
605If you want all the subdirectories under @file{/home/luser/lisp/}
606to be recursively scanned for @file{.asd} files, instead use:
608@kbd{(:tree "/home/luser/lisp/")}
610ASDF will automatically read your configuration
611the first time you try to find a system.
612If necessary, you can reset the source-registry configuration with:
616@end lisp
618@c FIXME: too specific.  Push this down to discussion of dumping an
619@c image?
621@c And you probably should do so before you dump your Lisp image,
622@c if the configuration may change
623@c between the machine where you save it at the time you save it
624@c and the machine you resume it at the time you resume it.
625@c Actually, you should use @code{(asdf:clear-configuration)}
626@c before you dump your Lisp image, which includes the above.
629In earlier versions of ASDF, the system source registry was configured
630using a global variable, @code{asdf:*central-registry*}.
631For more details about this, see the following section,
632@ref{Configuring ASDF to find your systems --- old style}.
633Unless you need to understand this,
634skip directly to @ref{Configuring where ASDF stores object files}.
636@end itemize
638Note that your Operating System distribution or your system administrator
639may already have configured system-managed libraries for you.
643@node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Configuring ASDF
645@c FIXME: this section should be moved elsewhere.  The novice user
646@c should not be burdened with it. [2014/02/27:rpg]
647@section Configuring ASDF to find your systems --- old style
649The old way to configure ASDF to find your systems is by
650@code{push}ing directory pathnames onto the variable
653You must configure this variable between the time you load ASDF
654and the time you first try to use it.
655Loading and configuring ASDF presumably happen
656as part of some initialization script that builds or starts
657your Common Lisp software system.
658(For instance, some SBCL users used to put it in their @file{~/.sbclrc}.)
660The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
661but is still supported for compatibility with ASDF 1.
662When used, it takes precedence over the above source-registry.@footnote{
663It is possible to further customize
664the system definition file search.
665That's considered advanced use, and covered later:
666search forward for
668@xref{Defining systems with defsystem}.}
670For example, let's say you want ASDF to find the @file{.asd} file
672In your lisp initialization file, you could have the following:
675(require "asdf")
676(push "/home/me/src/foo/" asdf:*central-registry*)
677@end lisp
679Note the trailing slash: when searching for a system,
680ASDF will evaluate each entry of the central registry
681and coerce the result to a pathname.@footnote{
682ASDF will indeed call @code{eval} on each entry.
683It will skip entries that evaluate to @code{nil}.
685Strings and pathname objects are self-evaluating,
686in which case the @code{eval} step does nothing;
687but you may push arbitrary s-expressions onto the central registry.
688These s-expressions may be evaluated to compute context-dependent
689entries, e.g. things that depend
690on the value of shell variables or the identity of the user.
692The variable @code{asdf:*central-registry*} is thus a list of
693``system directory designators''.
694A @dfn{system directory designator} is a form
695which will be evaluated whenever a system is to be found,
696and must evaluate to a directory to look in (or @code{NIL}).
697By ``directory'', we mean
698``designator for a pathname with a non-empty DIRECTORY component''.
700The trailing directory name separator
701is necessary to tell Lisp that you're discussing a directory
702rather than a file.  If you leave it out, ASDF is likely to look in
703@code{/home/me/src/} instead of @code{/home/me/src/foo/} as you
704intended, and fail to find your system definition.
706Typically there are a lot of @file{.asd} files, and
707a common idiom was to put
708@emph{symbolic links} to all of one's @file{.asd} files
709in a common directory
710and push @emph{that} directory (the ``link farm'')
713instead of pushing each individual system directory.
715ASDF knows to follow @emph{symlinks}
716to the actual location of the systems.@footnote{
717On Windows, you can use Windows shortcuts instead of POSIX symlinks.
718if you try aliases under MacOS, we are curious to hear about your experience.}
720For example, if @code{#p"/home/me/cl/systems/"}
721is an element of @code{*central-registry*}, you could set up the
722system @var{foo} as follows:
725$ cd /home/me/cl/systems/
726$ ln -s ~/src/foo/foo.asd .
727@end example
729This old style for configuring ASDF is not recommended for new users,
730but it is supported for old users, and for users who want to programmatically
731control what directories are added to the ASDF search path.
734@node Configuring where ASDF stores object files,  , Configuring ASDF to find your systems, Configuring ASDF
735@section Configuring where ASDF stores object files
736@findex clear-output-translations
738ASDF lets you configure where object files will be stored.
739Sensible defaults are provided and
740you shouldn't normally have to worry about it.
742This allows the same source code repository to be shared
743between several versions of several Common Lisp implementations,
744between several users using different compilation options,
745with users who lack write privileges on shared source directories, etc.
746This also keeps source directories from being cluttered
747with object/fasl files.
749Starting with ASDF 2, the @code{asdf-output-translations} facility
750was added to ASDF itself.  This facility controls where object files will be stored.
751This facility is fully described in a chapter of this manual,
752@ref{Controlling where ASDF saves compiled files}.
754@c FIXME: possibly this should be moved elsewhere.  It's redundant here,
755@c and makes this section of the manual too long and daunting for the
756@c new user. [2014/02/27:rpg]
757@c The simplest way to add a translation to your search path,
758@c say from @file{/foo/bar/baz/quux/}
759@c to @file{/where/i/want/my/fasls/}
760@c is to create the directory
761@c @file{~/.config/common-lisp/asdf-output-translations.conf.d/}
762@c and there create a file with any name of your choice and the type @file{conf},
763@c for instance @file{42-bazquux.conf}
764@c containing the line:
766@c @kbd{("/foo/bar/baz/quux/" "/where/i/want/my/fasls/")}
768@c To disable output translations for source under a given directory,
769@c say @file{/toto/tata/}
770@c you can create a file @file{40-disable-toto.conf}
771@c with the line:
773@c @kbd{("/toto/tata/")}
775@c To wholly disable output translations for all directories,
776@c you can create a file @file{00-disable.conf}
777@c with the line:
779@c @kbd{(t t)}
781@c Note that your Operating System distribution or your system administrator
782@c may already have configured translations for you.
783@c In absence of any configuration, the default is to redirect everything
784@c under an implementation-dependent subdirectory of @file{~/.cache/common-lisp/}.
785@c @xref{Controlling where ASDF searches for systems}, for full details.
787@c The required @file{.conf} extension allows you to have disabled files
788@c or editor backups (ending in @file{~}), and works portably
789@c (for instance, it is a pain to allow both empty and non-empty extension on CLISP).
790@c Excluded are files the name of which start with a @file{.} character.
791@c It is customary to start the filename with two digits
792@c that specify the order in which the directories will be scanned.
794@c ASDF will automatically read your configuration
795@c the first time you try to find a system.
796@c You can reset the source-registry configuration with:
798@c @lisp
799@c (asdf:clear-output-translations)
800@c @end lisp
802@c And you probably should do so before you dump your Lisp image,
803@c if the configuration may change
804@c between the machine where you save it at the time you save it
805@c and the machine you resume it at the time you resume it.
806@c (Once again, you should use @code{(asdf:clear-configuration)}
807@c before you dump your Lisp image, which includes the above.)
809Note that before ASDF 2,
810other ASDF add-ons offered the same functionality,
811each in subtly different and incompatible ways:
812ASDF-Binary-Locations, cl-launch, common-lisp-controller.
813ASDF-Binary-Locations is now not needed anymore and should not be used.
814cl-launch 3.000 and common-lisp-controller 7.2 have been updated
815to delegate object file placement to ASDF.
817@node Resetting the ASDF configuration,  , Configuring where ASDF stores object files, Configuring ASDF
818@c FIXME: this should probably be moved out of the "quickstart" part of
819@c the manual. [2014/02/27:rpg]
820@section Resetting the ASDF configuration
822When you dump and restore an image, or when you tweak your configuration,
823you may want to reset the ASDF configuration.
824For that you may use the following function:
826@defun clear-configuration
827   undoes any ASDF configuration,
828   regarding source-registry or output-translations.
829@end defun
831If you use SBCL, CMUCL or SCL, you may use this snippet
832so that the ASDF configuration be cleared automatically as you dump an image:
835#+(or cmu sbcl scl)
836(pushnew 'clear-configuration
837         #+(or cmu scl) ext:*before-save-initializations*
838         #+sbcl sb-ext:*save-hooks*)
839@end example
841For compatibility with all Lisp implementations, however,
842you might want instead your build script to explicitly call
843@code{(asdf:clear-configuration)} at an appropriate moment before dumping.
845@node  Using ASDF, Defining systems with defsystem, Configuring ASDF, Top
846@chapter Using ASDF
848@section Loading a system
850The system @var{foo} is loaded (and compiled, if necessary)
851by evaluating the following Lisp form:
854(asdf:load-system :@var{foo})
855@end example
857On some implementations (namely recent versions of
858ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP,
859LispWorks, MKCL, SBCL and XCL),
860ASDF hooks into the @code{CL:REQUIRE} facility
861and you can just use:
864(require :@var{foo})
865@end example
867In older versions of ASDF, you needed to use
868@code{(asdf:oos 'asdf:load-op :@var{foo})}.
869If your ASDF is too old to provide @code{asdf:load-system} though
870we recommend that you upgrade to ASDF 3.
871@xref{Loading ASDF,,Loading an otherwise installed ASDF}.
873Note the name of a system is specified as a string or a symbol.
874If a symbol (including a keyword), its name is taken and lowercased.
875The name must be a suitable value for the @code{:name} initarg
876to @code{make-pathname} in whatever filesystem the system is to be
879The lower-casing-symbols behaviour is unconventional,
880but was selected after some consideration.
881The type of systems we want to support
882either have lowercase as customary case (Unix, Mac, Windows)
883or silently convert lowercase to uppercase (lpns).
884@c so this makes more sense than attempting to use @code{:case :common},
885@c which is reported not to work on some implementations
888@section Other Operations
890ASDF provides three commands for the most common system operations:
891@code{load-system}, @code{compile-system} or @code{test-system}.
892It also provides @code{require-system}, a version of @code{load-system}
893that skips trying to update systems that are already loaded.
895Because ASDF is an extensible system
896for defining @emph{operations} on @emph{components},
897it also provides a generic function @code{operate}
898(which is usually abbreviated by @code{oos}).
899You'll use @code{oos} whenever you want to do something beyond
900compiling, loading and testing.
902Output from ASDF and ASDF extensions are sent
903to the CL stream @code{*standard-output*},
904so rebinding that stream around calls to @code{asdf:operate}
905should redirect all output from ASDF operations.
907@c Reminder: before ASDF can operate on a system, however,
908@c it must be able to find and load that system's definition.
909@c @xref{Configuring ASDF,,Configuring ASDF to find your systems}.
911@c FIXME: the following is too complicated for here, especially since
912@c :force hasn't been defined yet.  Move it. [2014/02/27:rpg]
913@findex already-loaded-systems
915For advanced users, note that
916@code{require-system} calls @code{load-system}
917with keyword arguments @code{:force-not (already-loaded-systems)}.
918@code{already-loaded-systems} returns a list of the names of loaded systems.
919@code{load-system} applies @code{operate} with the operation from
920@code{*load-system-operation*}, which by default is @code{load-op},
921the system, and any provided keyword arguments.
924@section Moving on
926That's all you need to know to use ASDF to load systems written by others.
927The rest of this manual deals with writing system definitions
928for Common Lisp software you write yourself,
929including how to extend ASDF to define new operation and component types.
932@node Defining systems with defsystem, The object model of ASDF, Using ASDF, Top
933@comment  node-name,  next,  previous,  up
934@chapter Defining systems with defsystem
936This chapter describes how to use asdf to define systems and develop
941* The defsystem form::
942* A more involved example::
943* The defsystem grammar::
944* Other code in .asd files::
945* The package-system extension::
946@end menu
948@node  The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
949@comment  node-name,  next,  previous,  up
950@section The defsystem form
952Systems can be constructed programmatically
953by instantiating components using @code{make-instance}.
954Most of the time, however, it is much more practical to use
955a static @code{defsystem} form.
956This section begins with an example of a system definition,
957then gives the full grammar of @code{defsystem}.
959Let's look at a simple system.
960This is a complete file that would
961usually be saved as @file{hello-lisp.asd}:
964(in-package :asdf)
966(defsystem "hello-lisp"
967  :description "hello-lisp: a sample Lisp system."
968  :version "0.2.1"
969  :author "Joe User <>"
970  :licence "Public Domain"
971  :components ((:file "packages")
972               (:file "macros" :depends-on ("packages"))
973               (:file "hello" :depends-on ("macros"))))
974@end lisp
976Some notes about this example:
981The file starts with an @code{in-package} form
982to use package @code{asdf}.
983You could instead start your definition by using
984a qualified name @code{asdf:defsystem}.
987If in addition to simply using @code{defsystem},
988you are going to define functions,
989create ASDF extension, globally bind symbols, etc.,
990it is recommended that to avoid namespace pollution between systems,
991you should create your own package for that purpose,
992for instance replacing the above @code{(in-package :asdf)} with:
995(defpackage :foo-system
996  (:use :cl :asdf))
998(in-package :foo-system)
999@end lisp
1002The @code{defsystem} form defines a system named @code{hello-lisp}
1003that contains three source files:
1004@file{packages}, @file{macros} and @file{hello}.
1007The file @file{macros} depends on @file{packages}
1008(presumably because the package it's in is defined in @file{packages}),
1009and the file @file{hello} depends on @file{macros}
1010(and hence, transitively on @file{packages}).
1011This means that ASDF will compile and load @file{packages} and @file{macros}
1012before starting the compilation of file @file{hello}.
1015The files are located in the same directory
1016as the file with the system definition.
1017ASDF resolves symbolic links (or Windows shortcuts)
1018before loading the system definition file and
1019stores its location in the resulting system@footnote{
1020It is possible, though almost never necessary, to override this behaviour.}.
1021This is a good thing because the user can move the system sources
1022without having to edit the system definition.
1024@c FIXME: Should have cross-reference to "Version specifiers" in the
1025@c defsystem grammar, but the cross-referencing is so broken by
1026@c insufficient node breakdown that I have not put one in.
1028Make sure you know how the @code{:version} numbers will be parsed!
1029They are parsed as period-separated lists of integers.
1030I.e., in the example, @code{0.2.1} is to be interpreted,
1031roughly speaking, as @code{(0 2 1)}.
1032In particular, version @code{0.2.1}
1033is interpreted the same as @code{0.0002.1} and
1034is strictly version-less-than version @code{0.20.1},
1035even though the two are the same when interpreted as decimal fractions.
1036Instead of a string representing the version,
1037the @code{:version} argument can be an expression that is resolved to
1038such a string using the following trivial domain-specific language:
1039in addition to being a literal string, it can be an expression of the form
1040@code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)},
1041which will be resolved by reading a form in the specified pathname
1042(read as a subpathname of the current system if relative or a unix-namestring).
1043You may use a @code{uiop:access-at} specifier
1044with the (optional) @code{:at} keyword,
1045by default the specifier is @code{0}, meaning the first form is returned.
1047@cindex :version
1049@end itemize
1051@node  A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
1052@comment  node-name,  next,  previous,  up
1053@section A more involved example
1055Let's illustrate some more involved uses of @code{defsystem} via a
1056slightly convoluted example:
1059(defsystem "foo"
1060  :version "1.0.0"
1061  :components ((:module "mod"
1062                            :components ((:file "bar")
1063                                                  (:file"baz")
1064                                                  (:file "quux"))
1065                            :perform (compile-op :after (op c)
1066                                                  (do-something c))
1067                            :explain (compile-op :after (op c)
1068                                            (explain-something c)))
1069                         (:file "blah")))
1070@end lisp
1072The @code{:module} component named @code{"mod"} is a collection of three files,
1073which will be located in a subdirectory of the main code directory named
1074@file{mod} (this location can be overridden; see the discussion of the
1075@code{:pathname} option in @ref{The defsystem grammar}).
1077The method-form tokens provide a shorthand for defining methods on
1078particular components.  This part
1081                :perform (compile-op :after (op c)
1082                          (do-something c))
1083                :explain (compile-op :after (op c)
1084                          (explain-something c))
1085@end lisp
1087has the effect of
1090(defmethod perform :after ((op compile-op) (c (eql ...)))
1091           (do-something c))
1092(defmethod explain :after ((op compile-op) (c (eql ...)))
1093           (explain-something c))
1094@end lisp
1096where @code{...} is the component in question.
1097In this case @code{...} would expand to something like
1100(find-component "foo" "mod")
1101@end lisp
1103For more details on the syntax of such forms, see @ref{The defsystem
1105For more details on what these methods do, @pxref{Operations} in
1106@ref{The object model of ASDF}.
1108@c The following plunge into the weeds is not appropriate in this
1109@c location. [2010/10/03:rpg]
1110@c note that although this also supports @code{:before} methods,
1111@c they may not do what you want them to ---
1112@c a @code{:before} method on perform @code{((op compile-op) (c (eql ...)))}
1113@c will run after all the dependencies and sub-components have been processed,
1114@c but before the component in question has been compiled.
1116@node  The defsystem grammar, Other code in .asd files, A more involved example, Defining systems with defsystem
1117@comment  node-name,  next,  previous,  up
1118@section The defsystem grammar
1120@c FIXME: @var typesetting not consistently used here.  We should either expand
1121@c its use to everywhere, or we should kill it everywhere.
1125system-definition := ( defsystem system-designator @var{system-option}* )
1127system-option := :defsystem-depends-on system-list
1128                 | :weakly-depends-on @var{system-list}
1129                 | :class class-name (see discussion below)
1130                 | module-option
1131                 | option
1133module-option := :components component-list
1134                 | :serial [ t | nil ]
1136option :=
1137        | :pathname pathname-specifier
1138        | :default-component-class class-name
1139        | :perform method-form
1140        | :explain method-form
1141        | :output-files method-form
1142        | :operation-done-p method-form
1143        | :if-feature feature-expression
1144        | :depends-on ( @var{dependency-def}* )
1145        | :in-order-to ( @var{dependency}+ )
1148system-list := ( @var{simple-component-name}* )
1150component-list := ( @var{component-def}* )
1152component-def  := ( component-type simple-component-name @var{option}* )
1154component-type := :module | :file | :static-file | other-component-type
1156other-component-type := symbol-by-name (@pxref{The defsystem grammar,,Component types})
1158# This is used in :depends-on, as opposed to ``dependency,''
1159# which is used in :in-order-to
1160dependency-def := simple-component-name
1161               | ( :feature @var{feature-expression} dependency-def )
1162               | ( :version simple-component-name version-specifier )
1163               | ( :require module-name )
1165# ``dependency'' is used in :in-order-to, as opposed to
1166# ``dependency-def''
1167dependency := (dependent-op @var{requirement}+)
1168requirement := (required-op @var{required-component}+)
1169dependent-op := operation-name
1170required-op := operation-name
1172simple-component-name := string
1173                      |  symbol
1175pathname-specifier := pathname | string | symbol
1177method-form := (operation-name qual lambda-list @Arest body)
1178qual := method qualifier
1180component-dep-fail-option := :fail | :try-next | :ignore
1182feature-expression := keyword | (:and @var{feature-expression}*)
1183                      | (:or @var{feature-expression}*) | (:not @var{feature-expression})
1184@end example
1187@subsection Component names
1189Component names (@code{simple-component-name})
1190may be either strings or symbols.
1192@subsection Component types
1194Component type names, even if expressed as keywords, will be looked up
1195by name in the current package and in the asdf package, if not found in
1196the current package.  So a component type @code{my-component-type}, in
1197the current package @code{my-system-asd} can be specified as
1198@code{:my-component-type}, or @code{my-component-type}.
1200@code{system} and its subclasses are @emph{not}
1201allowed as component types for such children components.
1203@subsection System class names
1205A system class name will be looked up
1206in the same way as a Component type (see above),
1207except that only @code{system} and its subclasses are allowed.
1208Typically, one will not need to specify a system
1209class name, unless using a non-standard system class defined in some
1210ASDF extension, typically loaded through @code{DEFSYSTEM-DEPENDS-ON},
1211see below.  For such class names in the ASDF package, we recommend that
1212the @code{:class} option be specified using a keyword symbol, such as
1216@end example
1218This practice will ensure that package name conflicts are avoided.
1219Otherwise, the symbol @code{MY-NEW-SYSTEM-SUBCLASS} will be read into
1220the current package @emph{before} it has been exported from the ASDF
1221extension loaded by @code{:defsystem-depends-on}, causing a name
1222conflict in the current package.
1224@subsection Defsystem depends on
1225@cindex :defsystem-depends-on
1227The @code{:defsystem-depends-on} option to @code{defsystem} allows the
1228programmer to specify another ASDF-defined system or set of systems that
1229must be loaded @emph{before} the system definition is processed.
1230Typically this is used to load an ASDF extension that is used in the
1231system definition.
1233@subsection Weakly depends on
1234@cindex :weakly-depends-on
1236We do @emph{NOT} recommend you use this feature.
1237If you are tempted to write a system @var{foo}
1238that weakly-depends-on a system @var{bar},
1239we recommend that you should instead
1240write system @var{foo} in a parametric way,
1241and offer some special variable and/or some hook to specialize its behavior;
1242then you should write a system @var{foo+bar}
1243that does the hooking of things together.
1245The (deprecated) @code{:weakly-depends-on} option to @code{defsystem}
1246allows the programmer to specify another ASDF-defined system or set of systems
1247that ASDF should @emph{try} to load,
1248but need not load in order to be successful.
1249Typically this is used if there are a number of systems
1250that, if present, could provide additional functionality,
1251but which are not necessary for basic function.
1253Currently, although it is specified to be an option only to @code{defsystem},
1254this option is accepted at any component, but it probably
1255only makes sense at the @code{defsystem} level.
1256Programmers are cautioned not
1257to use this component option except at the @code{defsystem} level, as
1258this anomalous behavior may be removed without warning.
1260@c Finally, you might look into the @code{asdf-system-connections} extension,
1261@c that will let you define additional code to be loaded
1262@c when two systems are simultaneously loaded.
1263@c It may or may not be considered good style, but at least it can be used
1264@c in a way that has deterministic behavior independent of load order,
1265@c unlike @code{weakly-depends-on}.
1268@subsection Pathname specifiers
1269@cindex pathname specifiers
1271A pathname specifier (@code{pathname-specifier})
1272may be a pathname, a string or a symbol.
1273When no pathname specifier is given for a component,
1274which is the usual case, the component name itself is used.
1276If a string is given, which is the usual case,
1277the string will be interpreted as a Unix-style pathname
1278where @code{/} characters will be interpreted as directory separators.
1279Usually, Unix-style relative pathnames are used
1280(i.e. not starting with @code{/}, as opposed to absolute pathnames);
1281they are relative to the path of the parent component.
1282Finally, depending on the @code{component-type},
1283the pathname may be interpreted as either a file or a directory,
1284and if it's a file,
1285a file type may be added corresponding to the @code{component-type},
1286or else it will be extracted from the string itself (if applicable).
1288For instance, the @code{component-type} @code{:module}
1289wants a directory pathname, and so a string @code{"foo/bar"}
1290will be interpreted as the pathname @file{#p"foo/bar/"}.
1291On the other hand, the @code{component-type} @code{:file}
1292wants a file of type @code{lisp}, and so a string @code{"foo/bar"}
1293will be interpreted as the pathname @file{#p"foo/bar.lisp"},
1294and a string @code{"foo/bar.quux"}
1295will be interpreted as the pathname @file{#p"foo/bar.quux.lisp"}.
1296Finally, the @code{component-type} @code{:static-file}
1297wants a file without specifying a type, and so a string @code{"foo/bar"}
1298will be interpreted as the pathname @file{#p"foo/bar"},
1299and a string @code{"foo/bar.quux"}
1300will be interpreted as the pathname @file{#p"foo/bar.quux"}.
1302ASDF does not interpret the string @code{".."} to designate the parent
1303directory.  This string will be passed through to the underlying
1304operating system for interpretation.  We @emph{believe} that this will
1305work on all platforms where ASDF is deployed, but do not guarantee this
1306behavior.  A pathname object with a relative directory component of
1307@code{:up} or @code{:back} is the only guaranteed way to specify a
1308parent directory.
1310If a symbol is given, it will be translated into a string,
1311and downcased in the process.
1312The downcasing of symbols is unconventional,
1313but was selected after some consideration.
1314Observations suggest that the type of systems we want to support
1315either have lowercase as customary case (Unix, Mac, windows)
1316or silently convert lowercase to uppercase (lpns),
1317so this makes more sense than attempting to use @code{:case :common}
1318as argument to @code{make-pathname},
1319which is reported not to work on some implementations.
1321Pathname objects may be given to override the path for a component.
1322Such objects are typically specified using reader macros such as @code{#p}
1323or @code{#.(make-pathname ...)}.
1324Note however, that @code{#p...} is
1325a shorthand for @code{#.(parse-namestring ...)}
1326and that the behavior of @code{parse-namestring} is completely non-portable,
1327unless you are using Common Lisp @code{logical-pathname}s,
1328which themselves involve other non-portable behavior
1329(@pxref{The defsystem grammar,,Using logical pathnames}, below).
1330Pathnames made with @code{#.(make-pathname ...)}
1331can usually be done more easily with the string syntax above.
1332The only case that you really need a pathname object is to override
1333the component-type default file type for a given component.
1334Therefore, pathname objects should only rarely be used.
1335Unhappily, ASDF 1 didn't properly support
1336parsing component names as strings specifying paths with directories,
1337and the cumbersome @code{#.(make-pathname ...)} syntax had to be used.
1338An alternative to @code{#.} read-time evaluation is to use
1339@code{(eval `(defsystem ... ,pathname ...))}.
1341Note that when specifying pathname objects,
1342ASDF does not do any special interpretation of the pathname
1343influenced by the component type, unlike the procedure for
1344pathname-specifying strings.
1345On the one hand, you have to be careful to provide a pathname that correctly
1346fulfills whatever constraints are required from that component type
1347(e.g. naming a directory or a file with appropriate type);
1348on the other hand, you can circumvent the file type that would otherwise
1349be forced upon you if you were specifying a string.
1351@subsection Version specifiers
1352@cindex version specifiers
1353@cindex :version
1355Version specifiers are strings to be parsed as period-separated lists of integers.
1356I.e., in the example, @code{"0.2.1"} is to be interpreted,
1357roughly speaking, as @code{(0 2 1)}.
1358In particular, version @code{"0.2.1"} is interpreted the same as @code{"0.0002.1"},
1359though the latter is not canonical and may lead to a warning being issued.
1360Also, @code{"1.3"} and @code{"1.4"} are both strictly @code{uiop:version<} to @code{"1.30"},
1361quite unlike what would have happened
1362had the version strings been interpreted as decimal fractions.
1364System definers are encouraged to use version identifiers of the form
1365@var{x}.@var{y}.@var{z} for
1366major version, minor version and patch level,
1367where significant API incompatibilities are signaled by an increased major number.
1369@xref{Common attributes of components}.
1371@subsection Require
1372@cindex :require dependencies
1374Use the implementation's own @code{require} to load the @var{module-name}.
1377@subsection Using logical pathnames
1378@cindex logical pathnames
1380We do not generally recommend the use of logical pathnames,
1381especially not so to newcomers to Common Lisp.
1382However, we do support the use of logical pathnames by old timers,
1383when such is their preference.
1385To use logical pathnames,
1386you will have to provide a pathname object as a @code{:pathname} specifier
1387to components that use it, using such syntax as
1390You only have to specify such logical pathname
1391for your system or some top-level component.
1392Sub-components' relative pathnames,
1393specified using the string syntax for names,
1394will be properly merged with the pathnames of their parents.
1395The specification of a logical pathname host however is @emph{not}
1396otherwise directly supported in the ASDF syntax
1397for pathname specifiers as strings.
1399The @code{asdf-output-translation} layer will
1400avoid trying to resolve and translate logical pathnames.
1401The advantage of this is that
1402you can define yourself what translations you want to use
1403with the logical pathname facility.
1404The disadvantage is that if you do not define such translations,
1405any system that uses logical pathnames will behave differently under
1406asdf-output-translations than other systems you use.
1408If you wish to use logical pathnames you will have to configure the
1409translations yourself before they may be used.
1410ASDF currently provides no specific support
1411for defining logical pathname translations.
1413Note that the reasons we do not recommend logical pathnames are that
1414(1) there is no portable way to set up logical pathnames before they are used,
1415(2) logical pathnames are limited to only portably use
1416a single character case, digits and hyphens.
1417While you can solve the first issue on your own,
1418describing how to do it on each of fifteen implementations supported by ASDF
1419is more than we can document.
1420As for the second issue, mind that the limitation is notably enforced on SBCL,
1421and that you therefore can't portably violate the limitations
1422but must instead define some encoding of your own and add individual mappings
1423to name physical pathnames that do not fit the restrictions.
1424This can notably be a problem when your Lisp files are part of a larger project
1425in which it is common to name files or directories in a way that
1426includes the version numbers of supported protocols,
1427or in which files are shared with software written
1428in different programming languages where conventions include the use of
1429underscores, dots or CamelCase in pathnames.
1432@subsection Serial dependencies
1433@cindex serial dependencies
1435If the @code{:serial t} option is specified for a module,
1436ASDF will add dependencies for each child component,
1437on all the children textually preceding it.
1438This is done as if by @code{:depends-on}.
1441:serial t
1442:components ((:file "a") (:file "b") (:file "c"))
1443@end lisp
1445is equivalent to
1448:components ((:file "a")
1449             (:file "b" :depends-on ("a"))
1450             (:file "c" :depends-on ("a" "b")))
1451@end lisp
1454@subsection Source location
1456The @code{:pathname} option is optional in all cases for systems
1457defined via @code{defsystem},
1458and in the usual case the user is recommended not to supply it.
1460Instead, ASDF follows a hairy set of rules that are designed so that
1464will load a system from disk
1465and have its pathname default to the right place.
1468This pathname information will not be overwritten with
1470(which could be somewhere else altogether)
1471if the user loads up the @file{.asd} file into his editor
1472and interactively re-evaluates that form.
1473@end enumerate
1475If a system is being loaded for the first time,
1476its top-level pathname will be set to:
1480The host/device/directory parts of @code{*load-truename*},
1481if it is bound.
1483@code{*default-pathname-defaults*}, otherwise.
1484@end itemize
1486If a system is being redefined, the top-level pathname will be
1490changed, if explicitly supplied or obtained from @code{*load-truename*}
1491(so that an updated source location is reflected in the system definition)
1494changed if it had previously been set from @code{*default-pathname-defaults*}
1497left as before, if it had previously been set from @code{*load-truename*}
1498and @code{*load-truename*} is currently unbound
1499(so that a developer can evaluate a @code{defsystem} form
1500from within an editor without clobbering its source location)
1501@end itemize
1503@subsection if-feature option
1504@cindex :if-feature component option
1505@anchor{if-feature-option}      @c redo if this ever becomes a node in
1506@c its own right...
1508This option allows you to specify a feature expression to be evaluated
1509as if by @code{#+} to conditionally include a component in your build.
1510If the expression is false, the component is dropped
1511as well as any dependency pointing to it.
1512As compared to using @code{#+} which is expanded at read-time,
1513this allows you to have an object in your component hierarchy
1514that can be used for manipulations beside building your project, and
1515that is accessible to outside code that wishes to reason about system
1518Programmers should be careful to consider @strong{when} the
1519@code{:if-feature} is evaluated.  Recall that ASDF first computes a
1520build plan, and then executes that plan.  ASDF will check to see whether
1521or not a feature is present @strong{at planning time}, not during the
1522build.  It follows that one cannot use @code{:if-feature} to check
1523features that are set during the course of the build.  It can only be
1524used to check the state of features before any build operations have
1525been performed.
1527This option was added in ASDF 3.  For more information,
1528@xref{required-features, Required features}.
1530@subsection if-component-dep-fails option
1531@cindex :if-component-dep-fails component option
1532This option was removed in ASDF 3.
1533Its semantics was limited in purpose and dubious to explain,
1534and its implementation was breaking a hole into the ASDF object model.
1535Please use the @code{if-feature} option instead.
1537@subsection feature requirement
1538This requirement was removed in ASDF 3.1.
1539It used to ensure that a chain of component dependencies will raise an error,
1540which in conjunction with if-component-dep-fails would offer
1541a roundabout way to express conditional compilation.
1544@node Other code in .asd files, The package-system extension, The defsystem grammar, Defining systems with defsystem
1545@section Other code in .asd files
1547Files containing @code{defsystem} forms
1548are regular Lisp files that are executed by @code{load}.
1549Consequently, you can put whatever Lisp code you like into these files.
1550However, it is recommended to keep such forms to a minimal,
1551and to instead define @code{defsystem} extensions
1552that you use with @code{:defsystem-depends-on}.
1554If however, you might insist on including code in the @code{.asd} file itself,
1555e.g., to examine and adjust the compile-time environment,
1556possibly adding appropriate features to @code{*features*}.
1557If so, here are some conventions we recommend you follow,
1558so that users can control certain details of execution
1559of the Lisp in @file{.asd} files:
1563Any informative output
1564(other than warnings and errors,
1565which are the condition system's to dispose of)
1566should be sent to the standard CL stream @code{*standard-output*},
1567so that users can easily control the disposition
1568of output from ASDF operations.
1569@end itemize
1572@node The package-system extension,  , Other code in .asd files, Defining systems with defsystem
1573@section The package-system extension
1575Starting with ASDF 3.0.3,
1576ASDF supports a one-package-per-file style of programming,
1577whereby each file is its own system,
1578and dependencies are deduced from the @code{defpackage} form.
1580In this style, packages referring to a same-named system (downcased);
1581and if a system is defined with @code{:class package-system},
1582then system names that start with that name
1583(using the slash @code{/} separator)
1584refer to files under the filesystem hierarchy where the system is defined.
1585For instance, if system @code{my-lib} is defined in
1586@file{/foo/bar/my-lib/my-lib.asd}, then system @code{my-lib/src/utility}
1587will be found in file @file{/foo/bar/my-lib/src/utility.lisp}.
1589This style was made popular by @code{faslpath} and @code{quick-build} before,
1590and at the cost of a stricter package discipline,
1591seems to make for more maintainable code.
1592It is used by ASDF itself (starting with ASDF 3) and by @code{lisp-interface-library}.
1594To use this style, choose a toplevel system name, e.g. @code{my-lib},
1595and create a file @file{my-lib.asd}
1596with the @code{:class :package-system} option in its @code{defsystem}.
1597For instance:
1599#-asdf (error "my-lib requires ASDF 3")
1600(defsystem my-lib
1601  :class :package-system
1602  :defsystem-depends-on (:asdf-package-system)
1603  :depends-on (:my-lib/src/all)
1604  :in-order-to ((test-op (load-op :my-lib/test/all)))
1605  :perform (test-op (o c) (symbol-call :my-lib/test/all :test-suite)))
1606(register-system-packages :closer-mop
1607 '(:c2mop :closer-common-lisp :c2cl :closer-common-lisp-user :c2cl-user))
1608@end example
1610In the code above, the
1611@code{:defsystem-depends-on (:asdf-package-system)} is
1612for compatibility with older versions of ASDF 3 (ASDF 2 not supported),
1613and requires the @code{asdf-package-system} library to be present
1614(it is implicitly provided by ASDF starting with ASDF 3.0.3).
1616The function @code{register-system-packages} has to be called to register
1617packages used or provided by your system and its components
1618where the name of the system that provides the package
1619is not the downcase of the package name.
1621File @file{my-lib/src/utility.lisp} might start with:
1624(defpackage :my-lib/src/utility
1625  (:use :closer-common-lisp :my-lib/src/macros :my-lib/src/variables)
1626  (:import-from :cl-ppcre #:register-groups-bind)
1627  (:export #:foo #:bar))
1628@end example
1630And from the @code{:use} and @code{:import-from} clauses,
1631ASDF could tell that you depend on systems @code{closer-mop} (registered above),
1632@code{cl-ppcre} (package and system names match), and
1633@code{my-lib/src/macros} and @code{my-lib/src/variables}
1634(package and system names match, and they will be looked up hierarchically).
1636The form @code{uiop:define-package} is supported as well as @code{defpackage},
1637and has many options that prove useful in this context,
1638such as @code{:use-reexport} and @code{:mix-reexport}
1639that allow for ``inheritance'' of symbols being exported.
1641@node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top
1642@comment  node-name,  next,  previous,  up
1643@chapter The object model of ASDF
1645ASDF is designed in an object-oriented way from the ground up.
1646Both a system's structure and the operations that can be performed on systems
1647follow a extensible protocol.
1649This allows the addition of behaviours:
1650for example, @code{cffi} adds support of special FFI description files
1651to interface with C libraries and of wrapper files to embed C code in Lisp;
1652@code{abcl-jar} supports creating Java JAR archives in ABCL;
1653and @code{poiu} supports for compiling code in parallel using background processes.
1655This chapter deals with @code{component}s and @code{operation}s.
1657A @code{component} represents an individual source file or a group of source files,
1658and the things that get transformed into.
1659A @code{system} is a component at the top level of the component hierarchy.
1660A @code{source-file} is a component representing a single source-file
1661and the successive output files into which it is transformed.
1662A @code{module} is an intermediate component itself grouping several other components,
1663themselves source-files or further modules.
1665An @code{Operation} represents a transformation that can be performed on a component,
1666turning them from source files to intermediate results to final outputs.
1668A pair of an @code{operation} and a @code{component} is called an @code{action}.
1669An @code{action} represents a particular build step to be @code{perform}ed,
1670after all its dependencies have been fulfilled.
1671In the ASDF model, actions depend on other actions.
1672The term @emph{action} itself was used by Kent Pitman in his old article,
1673but was only used by ASDF hackers starting with the ASDF 2;
1674but the concept is ubiquitous since the very beginning of ASDF 1,
1675though previously implicit.
1677Then, there are many @emph{functions} available
1678to users, extenders and implementers of ASDF
1679to use, define or implement the activities
1680that are part of building your software.
1681Though they manipulate @code{action}s,
1682most of these functions do not take as an argument
1683a reified pair (a @code{cons} cell) of an operation and a component;
1684instead, they usually take two separate arguments,
1685which allows to take advantage of the power CLOS-style multiple dispatch
1686for fun and profit.
1688There are many @emph{hooks} in which to add functionality,
1689by customizing the behavior of existing @emph{functions}.
1691Last but not least is the notion of @emph{dependency} between two actions.
1692The structure of dependencies between actions is
1693a directed @emph{dependency graph}.
1694ASDF is invoked by being told to @emph{operate}
1695with some @emph{operation} on some toplevel @emph{system};
1696it will then @emph{traverse} the graph and build a @emph{plan}
1697that follows its structure.
1698To be successfully buildable, this graph of actions but be acyclic.
1699If, as a user, extender or implementer of ASDF, you fail
1700to keep the dependency graph without cycles,
1701ASDF will fail loudly as it eventually finds one.
1702To clearly distinguish the direction of dependencies,
1703ASDF 3 uses the words @emph{requiring} and @emph{required}
1704as applied to an action depending on the other:
1705the requiring action @code{depends-on} the completion of all required actions
1706before it may itself be @code{perform}ed.
1708Using the @code{defsystem} syntax, users may easily express
1709direct dependencies along the graph of the object hierarchy:
1710between a component and its parent, its children, and its siblings.
1711By defining custom CLOS methods, you can express more elaborate dependencies as you wish.
1712Most common operations, such as @code{load-op}, @code{compile-op} or @code{load-source-op}
1713are automatically propagate ``downward'' the component hierarchy and are ``covariant'' with it:
1714to act the operation on the parent module, you must first act it on all the children components,
1715with the action on the parent being parent of the action on each child.
1716Other operations, such as @code{prepare-op} and @code{prepare-source-op}
1717(introduced in ASDF 3) are automatically propagated ``upward'' the component hierarchy
1718and are ``contravariant'' with it:
1719to perform the operation of preparing for compilation of a child component,
1720you must perform the operation of preparing for compilation of its parent component, and so on,
1721ensuring that all the parent's dependencies are (compiled and) loaded
1722before the child component may be compiled and loaded.
1723Yet other operations, such as @code{test-op} or @code{load-fasl-op}
1724remain at the system level, and are not propagated along the hierarchy,
1725but instead do something global on the system.
1728* Operations::
1729* Components::
1730* Functions::
1731@end menu
1733@node  Operations, Components, The object model of ASDF, The object model of ASDF
1734@comment  node-name,  next,  previous,  up
1735@section Operations
1736@cindex operation
1738An @dfn{operation} object of the appropriate type is instantiated
1739whenever the user wants to do something with a system like
1742@item compile all its files
1743@item load the files into a running lisp environment
1744@item copy its source files somewhere else
1745@end itemize
1747Operations can be invoked directly, or examined
1748to see what their effects would be without performing them.
1749There are a bunch of methods specialised on operation and component type
1750that actually do the grunt work.
1751Operations are invoked on systems via @code{operate} (@pxref{operate}).
1753ASDF contains a number of pre-defined @t{operation} classes for common,
1754and even fairly uncommon tasks that you might want to do with it.
1755In addition, ASDF contains ``abstract'' @t{operation} classes that
1756programmers can use as building blocks to define ASDF extensions.  We
1757discuss these in turn below.
1759@c The operation object contains whatever state is relevant for this purpose
1760@c (perhaps a list of visited nodes, for example)
1761@c but primarily is a nice thing to specialise operation methods on
1762@c and easier than having them all be @code{EQL} methods.
1765* Predefined operations of ASDF::
1766* Creating new operations::
1767@end menu
1769Operations are invoked on systems via @code{operate}.
1771@deffn {Generic function} @code{operate} @var{operation} @var{system} @Arest @var{initargs} @Akey @code{force} @code{force-not} @code{verbose} @AallowOtherKeys
1772@deffnx {Generic function} @code{oos} @var{operation} @var{system} @Arest @var{initargs} @Akey @AallowOtherKeys
1773@code{operate} invokes @var{operation} on @var{system}.
1774@code{oos} is a synonym for @code{operate}.
1776@var{operation} is a symbol that is passed, along with the supplied
1777@var{initargs}, to @code{make-instance} to create the operation object.
1778@var{system} is a system designator.
1780The @var{initargs} are passed to the @code{make-instance} call
1781when creating the operation object.
1782Note that dependencies may cause the operation
1783to invoke other operations on the system or its components:
1784the new operations will be created
1785with the same @var{initargs} as the original one.
1787If @var{force} is @code{:all}, then all systems
1788are forced to be recompiled even if not modified since last compilation.
1789If @var{force} is @code{t}, then only the system being loaded
1790is forced to be recompiled even if not modified since last compilation,
1791but other systems are not affected.
1792If @var{force} is a list, then it specifies a list of systems that
1793are forced to be recompiled even if not modified since last compilation.
1794If @var{force-not} is @code{:all}, then all systems
1795are forced not to be recompiled even if modified since last compilation.
1796If @var{force-not} is @code{t}, then all systems but the system being loaded
1797are forced not to be recompiled even if modified since last compilation
1798(note: this was changed in ASDF 3.1.1).
1799If @var{force-not} is a list, then it specifies a list of systems that
1800are forced not to be recompiled even if modified since last compilation.
1802Both @var{force} and @var{force-not} apply to systems that are dependencies and were already compiled.
1803@var{force-not} takes precedences over @var{force},
1804as it should, really, but unhappily only since ASDF 3.1.1.
1805Moreover, systems the name of which is member of the set @var{*immutable-systems*}
1806(represented as an equal hash-table) are always considered @var{forced-not}, and
1807even their @file{.asd} is not refreshed from the filesystem.
1809To see what @code{operate} would do, you can use:
1811(asdf:traverse operation-class system-name)
1812@end example
1814@end deffn
1818@node Predefined operations of ASDF, Creating new operations, Operations, Operations
1819@comment  node-name,  next,  previous,  up
1820@subsection Predefined operations of ASDF
1822All the operations described in this section are in the @code{asdf} package.
1823They are invoked via the @code{operate} generic function.
1826(asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
1827@end lisp
1829@deffn Operation @code{compile-op}
1831This operation compiles the specified component.
1832A @code{cl-source-file} will be @code{compile-file}'d.
1833All the children and dependencies of a system or module
1834will be recursively compiled by @code{compile-op}.
1836@code{compile-op} depends on @code{prepare-op} which
1837itself depends on a @code{load-op} of all of a component's dependencies,
1838as well as of its parent's dependencies.
1839When @code{operate} is called on @code{compile-op},
1840all these dependencies will be loaded as well as compiled;
1841yet, some parts of the system main remain unloaded,
1842because nothing depends on them.
1843Use @code{load-op} to load a system.
1844@end deffn
1846@deffn Operation @code{load-op}
1848This operation loads the compiled code for a specified component.
1849A @code{cl-source-file} will have its compiled fasl @code{load}ed,
1850which fasl is the output of @code{compile-op} that @code{load-op} depends on.
1851All the children and dependencies of a system or module
1852will be recursively loaded by @code{load-op}.
1854@code{load-op} depends on @code{prepare-op} which
1855itself depends on a @code{load-op} of all of a component's dependencies,
1856as well as of its parent's dependencies.
1857@end deffn
1859@deffn Operation @code{prepare-op}
1861This operation ensures that the dependencies of a component
1862and its recursive parents are loaded (as per @code{load-op}),
1863as a prerequisite before @code{compile-op} and @code{load-op} operations
1864may be performed on a given component.
1865@end deffn
1867@deffn Operation @code{load-source-op}, @code{prepare-source-op}
1869@code{load-source-op} will load the source for the files in a module
1870rather than they compiled fasl output.
1871It has a @code{prepare-source-op} analog to @code{prepare-op},
1872that ensures the dependencies are themselves loaded via @code{load-source-op}.
1874There is no provision in ASDF for ensuring that
1875some components are always loaded as source, while others are always compiled.
1876While this idea often comes up in discussions,
1877it actually doesn't play well with either the linking model of ECL
1878or with various bundle operations (see below), and is eventually not workable;
1879also the dependency model of ASDF would have to be modified incompatibly
1880to allow for such trick.
1881If your code doesn't compile cleanly, fix it.
1882If compilation makes it slow, use @code{declaim} or @code{eval-when}
1883to adjust your compiler settings,
1884or eschew compilation by @code{eval}uating a quoted source form at load-time.
1885@end deffn
1888@deffn Operation @code{test-op}
1890This operation will perform some tests on the module.
1891The default method will do nothing.
1892The default dependency is to require
1893@code{load-op} to be performed on the module first.
1894The default @code{operation-done-p} is that the operation is @emph{never} done
1896we assume that if you invoke the @code{test-op},
1897you want to test the system, even if you have already done so.
1899The results of this operation are not defined by ASDF.
1900It has proven difficult to define how the test operation
1901should signal its results to the user
1902in a way that is compatible with all of the various test libraries
1903and test techniques in use in the community.
1905People typically define @code{test-op} methods like thus:
1907(defmethod perform ((o asdf:test-op)
1908                    (s (eql (asdf:find-system @var{:my-system}))))
1909  (asdf:load-system @var{:my-system-test})
1910  (funcall (read-from-string "my-system-test:test-suite")))
1911@end example
1913Using @code{load-system} in the perform method
1914rather than an @code{:in-order-to} dependency,
1915is sometimes necessary for backward compatibility with ASDF 2 and older,
1916to avoid circular dependencies that could arise
1917because of the way these old versions propagate dependencies.
1919If you don't care for compatibility with ASDF 2,
1920you could use the following options in your @code{defsystem} form:
1922  :in-order-to ((test-op (load-op :my-system-test)))
1923  :perform (test-op (o c) (symbol-call :my-system-test :test-suite))
1924@end example
1925@end deffn
1927@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}
1929These are ``bundle'' operations, that can create a single-file ``bundle''
1930for all the contents of each system in an application,
1931or for the entire application.
1933@code{fasl-op} will create a single fasl file for each of the systems needed,
1934grouping all its many fasls in one,
1935so you can deliver each system as a single fasl.
1936@code{monolithic-fasl-op} will create a single fasl file for target system
1937and all its dependencies,
1938so you can deliver your entire application as a single fasl.
1939@code{load-fasl-op} will load the output of @code{fasl-op}
1940(though if it the output is not up-to-date,
1941it will load the intermediate fasls indeed as part of building it);
1942this matters a lot on ECL, where the dynamic linking involved in loading
1943tens of individual fasls can be noticeably more expensive
1944than loading a single one.
1946Once you have created a fasl with @code{fasl-op},
1947you can use @code{precompiled-system} to deliver it in a way
1948that is compatible with clients having dependencies on your system,
1949whether it is distributed as source or as a single binary;
1950the @file{.asd} file to be delivered with the fasl will look like this:
1952(defsystem :mysystem :class :precompiled-system
1953    :fasl (some expression that will evaluate to a pathname))
1954@end example
1955Or you can use @code{binary-op} to let ASDF create such a system for you
1956as well as the @code{fasl-op} output, or @code{monolithic-binary-op}.
1957This allows you to deliver code for your systems or applications
1958as a single file.
1959Of course, if you want to test the result in the current image,
1960@emph{before} you try to use any newly created @file{.asd} files,
1961you should not forget to @code{(asdf:clear-configuration)}
1962or at least @code{(asdf:clear-source-registry)},
1963so it re-populates the source-registry from the filesystem.
1965The @code{program-op} operation will create an executable program
1966from the specified system and its dependencies.
1967You can use UIOP for its pre-image-dump hooks, its post-image-restore hooks,
1968and its access to command-line arguments.
1969And you can specify an entry point @code{my-app:main}
1970by specifying in your @code{defsystem}
1971the option @code{:entry-point "my-app:main"}.
1972Depending on your implementation,
1973running @code{(asdf:operate 'asdf:program-op :my-app)}
1974may quit the current Lisp image upon completion.
1975See the example in
1976@file{test/hello-world-example.asd} and @file{test/hello.lisp},
1977as built and tested by
1978@file{test/test-program.script} and @file{test/make-hello-world.lisp}.
1980There is also @code{lib-op}
1981for building a linkable @file{.a} file (Windows: @file{.lib})
1982from all linkable object dependencies (FFI files, and on ECL, Lisp files too),
1983and its monolithic equivalent @code{monolithic-lib-op}.
1984And there is also @code{dll-op}
1985(respectively its monolithic equivalent @code{monolithic-lib-op})
1986for building a linkable @file{.so} file
1987(Windows: @file{.dll}, MacOS X: @file{.dynlib})
1988to create a single dynamic library
1989for all the extra FFI code to be linked into each of your systems
1990(respectively your entire application).
1992All these ``bundle'' operations are available since ASDF 3
1993on all actively supported Lisp implementations,
1994but may be unavailable on unmaintained legacy implementations.
1995This functionality was previously available for select implementations,
1996as part of a separate system @code{asdf-bundle},
1997itself descended from the ECL-only @code{asdf-ecl}.
1999The pathname of the output of bundle operations
2000is subject to output-translation as usual,
2001unless the operation is equal to
2002the @code{:build-operation} argument to @code{defsystem}.
2003This behavior is not very satisfactory and may change in the future.
2004Maybe you have suggestions on how to better configure it?
2005@end deffn
2007@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}
2009These operation, as their respective names indicate,
2010consist in concatenating all @code{cl-source-file} source files in a system
2011(or in a system and all its dependencies, if monolithic),
2012in the order defined by dependencies,
2013then loading the result, or compiling then loading the result.
2015These operations are useful to deliver a system or application
2016as a single source file,
2017and for testing that said file loads properly, or compiles then loads properly.
2019ASDF itself is notably delivered as a single source file this way
2020using @code{monolithic-concatenate-source-op},
2021transcluding a prelude and the @code{uiop} library
2022before the @code{asdf/defsystem} system itself.
2023@end deffn
2026@node  Creating new operations,  , Predefined operations of ASDF, Operations
2027@comment  node-name,  next,  previous,  up
2028@subsection Creating new operations
2030ASDF was designed to be extensible in an object-oriented fashion.
2031To teach ASDF new tricks, a programmer can implement the behaviour he wants
2032by creating a subclass of @code{operation}.
2034ASDF's pre-defined operations are in no way ``privileged'',
2035but it is requested that developers never use the @code{asdf} package
2036for operations they develop themselves.
2037The rationale for this rule is that we don't want to establish a
2038``global asdf operation name registry'',
2039but also want to avoid name clashes.
2041Your operation @emph{must} usually provide methods
2042for one or more of the following generic functions:
2046@item @code{perform}
2047Unless your operation, like @code{prepare-op},
2048is for dependency propagation only,
2049the most important function for which to define a method
2050is usually @code{perform},
2051which will be called to perform the operation on a specified component,
2052after all dependencies have been performed.
2054The @code{perform} method must call @code{output-files} (see below)
2055to find out where to put its files,
2056because the user is allowed to override the method
2057or tweak the output-translation mechanism.
2058Perform should only use the primary value returned by @code{output-files}.
2059If one and only one output file is expected,
2060it can call @code{output-file} that checks that this is the case
2061and returns the first and only list element.
2063@item @code{output-files}
2064If your perform method has any output,
2065you must define a method for this function.
2066for ASDF to determine where the outputs of performing operation lie.
2068Your method may return two values, a list of pathnames, and a boolean.
2069If the boolean is @code{nil} (or you fail to return multiple values),
2070then enclosing @code{:around} methods may translate these pathnames,
2071e.g. to ensure object files are somehow stored
2072in some implementation-dependent cache.
2073If the boolean is @code{t} then the pathnames are marked
2074not be translated by the enclosing @code{:around} method.
2076@item @code{component-depends-on}
2077If the action of performing the operation on a component has dependencies,
2078you must define a method on @code{component-depends-on}.
2080Your method will take as specialized arguments
2081an operation and a component which together identify an action,
2082and return a list of entries describing actions that this action depends on.
2083The format of entries is described below.
2085It is @emph{strongly} advised that
2086you should always append the results of @code{(call-next-method)}
2087to the results of your method,
2088or ``interesting'' failures will likely occur,
2089unless you're a true specialist of ASDF internals.
2090It is unhappily too late to compatibly use the @code{append} method combination,
2091but conceptually that's the protocol that is being manually implemented.
2093Each entry returned by @code{component-depends-on} is itself a list.
2095The first element of an entry is an operation designator:
2096either an operation object designating itself, or
2097a symbol that names an operation class
2098(that ASDF will instantiate using @code{make-operation}).
2099For instance, @code{load-op}, @code{compile-op} and @code{prepare-op}
2100are common such names, denoting the respective operations.
2102The rest of each entry is a list of component designators:
2103either a component object designating itself,
2104or an identifier to be used with @code{find-component}.
2105@code{find-component} will be called with the current component's parent as parent,
2106and the identifier as second argument.
2107The identifier is typically a string,
2108a symbol (to be downcased as per @code{coerce-name}),
2109or a list of strings or symbols.
2110In particular, the empty list @code{nil} denotes the parent itself.
2112@end itemize
2114An operation @emph{may} provide methods for the following generic functions:
2118@item @code{input-files}
2119A method for this function is often not needed,
2120since ASDF has a pretty clever default @code{input-files} mechanism.
2121You only need create a method if there are multiple ultimate input files,
2122and/or the bottom one doesn't depend
2123on the @code{component-pathname} of the component.
2125@item @code{operation-done-p}
2126You only need to define a method on that function
2127if you can detect conditions that invalidate previous runs of the operation,
2128even though no filesystem timestamp has changed,
2129in which case you return @code{nil} (the default is @code{t}).
2131For instance, the method for @code{test-op} always returns @code{nil},
2132so that tests are always run afresh.
2133Of course, the @code{test-op} for your system could depend
2134on a deterministically repeatable @code{test-report-op},
2135and just read the results from the report files,
2136in which case you could have this method return @code{t}.
2138@end itemize
2140Operations that print output should send that output to the standard
2141CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
2143@node Components, Functions, Operations, The object model of ASDF
2144@comment  node-name,  next,  previous,  up
2145@section Components
2146@cindex component
2147@cindex system
2148@cindex system designator
2149@cindex component designator
2150@vindex *system-definition-search-functions*
2152A @dfn{component} represents a source file or
2153(recursively) a collection of components.
2154A @dfn{system} is (roughly speaking) a top-level component
2155that can be found via @code{find-system}.
2157A @dfn{system designator} is a system itself,
2158or a string or symbol that behaves just like any other component name
2159(including with regard to the case conversion rules for component names).
2161A @dfn{component designator}, relative to a base component,
2162is either a component itself,
2163or a string or symbol,
2164or a list of designators.
2166@defun find-system system-designator @Aoptional (error-p t)
2168Given a system designator, @code{find-system} finds and returns a system.
2169If no system is found, an error of type
2170@code{missing-component} is thrown,
2171or @code{nil} is returned if @code{error-p} is false.
2173To find and update systems, @code{find-system} funcalls each element
2174in the @code{*system-definition-search-functions*} list,
2175expecting a pathname to be returned, or a system object,
2176from which a pathname may be extracted, and that will be registered.
2177The resulting pathname (if any) is loaded
2178if one of the following conditions is true:
2182there is no system of that name in memory
2184the pathname is different from that which was previously loaded
2186the file's @code{last-modified} time exceeds the @code{last-modified} time
2187of the system in memory
2188@end itemize
2190When system definitions are loaded from @file{.asd} files,
2191a new scratch package is created for them to load into,
2192so that different systems do not overwrite each others operations.
2193The user may also wish to (and is recommended to)
2194include @code{defpackage} and @code{in-package} forms
2195in his system definition files, however,
2196so that they can be loaded manually if need be.
2198The default value of @code{*system-definition-search-functions*}
2199is a list of two functions.
2200The first function looks in each of the directories given
2201by evaluating members of @code{*central-registry*}
2202for a file whose name is the name of the system and whose type is @file{asd}.
2203The first such file is returned,
2204whether or not it turns out to actually define the appropriate system.
2205The second function does something similar,
2206for the directories specified in the @code{source-registry}.
2207Hence, it is strongly advised to define a system
2208@var{foo} in the corresponding file @var{foo.asd}.
2209@end defun
2211@defun find-component base path
2213Given a @var{base} component (or designator for such),
2214and a @var{path}, find the component designated by the @var{path}
2215starting from the @var{base}.
2217If @var{path} is a component object, it designates itself,
2218independently from the base.
2220If @var{path} is a string, or symbol denoting a string via @code{coerce-name},
2221then @var{base} is resolved to a component object,
2222which must be a system or module,
2223and the designated component is the child named by the @var{path}.
2225If @var{path} is a @code{cons} cell,
2226@code{find-component} with the base and the @code{car} of the @var{path},
2227and the resulting object is used as the base for a tail call
2228to @code{find-component} with the @code{car} of the @var{path}.
2230If @var{base} is a component object, it designates itself.
2232If @var{base} is null, then @var{path} is used as the base, with @code{nil} as the path.
2234If @var{base} is a string, or symbol denoting a string via @code{coerce-name},
2235it designates a system as per @code{find-system}.
2237If @var{base} is a @code{cons} cell, it designates the component found by
2238@code{find-component} with its @code{car} as base and @code{cdr} as path.
2239@end defun
2243* Common attributes of components::
2244* Pre-defined subclasses of component::
2245* Creating new component types::
2246@end menu
2248@node  Common attributes of components, Pre-defined subclasses of component, Components, Components
2249@comment  node-name,  next,  previous,  up
2250@subsection Common attributes of components
2252All components, regardless of type, have the following attributes.
2253All attributes except @code{name} are optional.
2255@subsubsection Name
2257A component name is a string or a symbol.
2258If a symbol, its name is taken and lowercased.
2260Unless overridden by a @code{:pathname} attribute,
2261the name will be interpreted as a pathname specifier according
2262to a Unix-style syntax.
2263@xref{The defsystem grammar,,Pathname specifiers}.
2265@subsubsection Version identifier
2266@findex version-satisfies
2267@cindex :version
2269This optional attribute specifies a version for the current component.
2270The version should typically be a string of integers separated by dots,
2271for example @samp{1.0.11}.
2272For more information on version specifiers, see @ref{The defsystem grammar}.
2274A version may then be queried by the generic function @code{version-satisfies},
2275to see if @code{:version} dependencies are satisfied,
2276and when specifying dependencies, a constraint of minimal version to satisfy
2277can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
2279Note that in the wild, we typically see version numbering
2280only on components of type @code{system}.
2281Presumably it is much less useful within a given system,
2282wherein the library author is responsible to keep the various files in synch.
2284@subsubsection Required features
2287Traditionally defsystem users have used @code{#+} reader conditionals
2288to include or exclude specific per-implementation files.
2289For example, CFFI, the portable C foreign function interface contained
2290lines like:
2292     #+sbcl       (:file "cffi-sbcl")
2293@end lisp
2294An unfortunate side effect of this approach is that no single
2295implementation can read the entire system.
2296This causes problems if, for example, one wished to design an @code{archive-op}
2297that would create an archive file containing all the sources, since
2298for example the file @code{cffi-sbcl.lisp} above would be invisible when
2299running the @code{archive-op} on any implementation other than SBCL.
2301Starting with ASDF 3,
2302components may therefore have an @code{:if-feature} option.
2303The value of this option should be
2304a feature expression using the same syntax as @code{#+} does.
2305If that feature expression evaluates to false, any reference to the component will be ignored
2306during compilation, loading and/or linking.
2307Since the expression is read by the normal reader,
2308you must explicitly prefix your symbols with @code{:} so they be read as keywords;
2309this is as contrasted with the @code{#+} syntax
2310that implicitly reads symbols in the keyword package by default.
2312For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
2313the given component is only to be compiled and loaded
2314when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
2315You cannot write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
2316since the symbols would not be read as keywords.
2320@subsubsection Dependencies
2322This attribute specifies dependencies of the component on its siblings.
2323It is optional but often necessary.
2325There is an excitingly complicated relationship between the initarg
2326and the method that you use to ask about dependencies
2328Dependencies are between (operation component) pairs.
2329In your initargs for the component, you can say
2332:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
2333              (load-op (load-op "foo")))
2334@end lisp
2336This means the following things:
2339before performing compile-op on this component, we must perform
2340load-op on @var{a} and @var{b}, and compile-op on @var{c},
2342before performing @code{load-op}, we have to load @var{foo}
2343@end itemize
2345The syntax is approximately
2348(this-op @{(other-op required-components)@}+)
2350simple-component-name := string
2351                      |  symbol
2353required-components := simple-component-name
2354                     | (required-components required-components)
2356component-name := simple-component-name
2357                | (:version simple-component-name minimum-version-object)
2358@end verbatim
2360Side note:
2362This is on a par with what ACL defsystem does.
2363mk-defsystem is less general: it has an implied dependency
2366  for all source file x, (load x) depends on (compile x)
2367@end verbatim
2369and using a @code{:depends-on} argument to say that @var{b} depends on
2370@var{a} @emph{actually} means that
2373  (compile b) depends on (load a)
2374@end verbatim
2376This is insufficient for e.g. the McCLIM system, which requires that
2377all the files are loaded before any of them can be compiled ]
2379End side note
2381In ASDF, the dependency information for a given component and operation
2382can be queried using @code{(component-depends-on operation component)},
2383which returns a list
2386((load-op "a") (load-op "b") (compile-op "c") ...)
2387@end lisp
2389@code{component-depends-on} can be subclassed for more specific
2390component/operation types: these need to @code{(call-next-method)}
2391and append the answer to their dependency, unless
2392they have a good reason for completely overriding the default dependencies.
2394If it weren't for CLISP, we'd be using @code{LIST} method
2395combination to do this transparently.
2396But, we need to support CLISP.
2397If you have the time for some CLISP hacking,
2398I'm sure they'd welcome your fixes.
2399@c Doesn't CLISP now support LIST method combination?
2401A minimal version can be specified for a component you depend on
2402(typically another system), by specifying @code{(:version "other-system" "1.2.3")}
2403instead of simply @code{"other-system"} as the dependency.
2404See the discussion of the semantics of @code{:version}
2405in the defsystem grammar.
2407@c FIXME: Should have cross-reference to "Version specifiers" in the
2408@c defsystem grammar, but the cross-referencing is so broken by
2409@c insufficient node breakdown that I have not put one in.
2412@subsubsection pathname
2414This attribute is optional and if absent (which is the usual case),
2415the component name will be used.
2417@xref{The defsystem grammar,,Pathname specifiers},
2418for an explanation of how this attribute is interpreted.
2420Note that the @code{defsystem} macro (used to create a ``top-level'' system)
2421does additional processing to set the filesystem location of
2422the top component in that system.
2423This is detailed elsewhere. @xref{Defining systems with defsystem}.
2426@subsubsection properties
2428This attribute is optional.
2430Packaging systems often require information about files or systems
2431in addition to that specified by ASDF's pre-defined component attributes.
2432Programs that create vendor packages out of ASDF systems therefore
2433have to create ``placeholder'' information to satisfy these systems.
2434Sometimes the creator of an ASDF system may know the additional
2435information and wish to provide it directly.
2437@code{(component-property component property-name)} and
2438associated @code{setf} method will allow
2439the programmatic update of this information.
2440Property names are compared as if by @code{EQL},
2441so use symbols or keywords or something.
2444* Pre-defined subclasses of component::
2445* Creating new component types::
2446@end menu
2448@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
2449@comment  node-name,  next,  previous,  up
2450@subsection Pre-defined subclasses of component
2452@deffn Component source-file
2454A source file is any file that the system does not know how to
2455generate from other components of the system.
2457Note that this is not necessarily the same thing as
2458``a file containing data that is typically fed to a compiler''.
2459If a file is generated by some pre-processor stage
2460(e.g. a @file{.h} file from @file{} by autoconf)
2461then it is not, by this definition, a source file.
2462Conversely, we might have a graphic file
2463that cannot be automatically regenerated,
2464or a proprietary shared library that we received as a binary:
2465these do count as source files for our purposes.
2467Subclasses of source-file exist for various languages.
2468@emph{FIXME: describe these.}
2469@end deffn
2471@deffn Component module
2473A module is a collection of sub-components.
2475A module component has the following extra initargs:
2479@code{:components} the components contained in this module
2483All children components which don't specify their class explicitly
2484are inferred to be of this type.
2488This attribute was removed in ASDF 3. Do not use it.
2489Use @code{:if-feature} instead (@pxref{required-features}, and @pxref{if-feature-option}).
2492@code{:serial} When this attribute is set,
2493each subcomponent of this component is assumed to depend on all subcomponents
2494before it in the list given to @code{:components}, i.e.
2495all of them are loaded before a compile or load operation is performed on it.
2497@end itemize
2499The default operation knows how to traverse a module, so
2500most operations will not need to provide methods specialised on modules.
2502@code{module} may be subclassed to represent components such as
2503foreign-language linked libraries or archive files.
2504@end deffn
2506@deffn Component system
2508@code{system} is a subclass of @code{module}.
2510A system is a module with a few extra attributes for documentation
2511purposes; these are given elsewhere.
2512@xref{The defsystem grammar}.
2514Users can create new classes for their systems:
2515the default @code{defsystem} macro takes a @code{:class} keyword argument.
2516@end deffn
2518@node  Creating new component types,  , Pre-defined subclasses of component, Components
2519@comment  node-name,  next,  previous,  up
2520@subsection Creating new component types
2522New component types are defined by subclassing one of the existing
2523component classes and specializing methods on the new component class.
2525@emph{FIXME: this should perhaps be explained more throughly,
2526not only by example ...}
2528As an example, suppose we have some implementation-dependent
2529functionality that we want to isolate
2530in one subdirectory per Lisp implementation our system supports.
2531We create a subclass of
2535(defclass unportable-cl-source-file (cl-source-file)
2536  ())
2537@end lisp
2539Function @code{asdf:implementation-type} (exported since 2.014.14)
2540gives us the name of the subdirectory.
2541All that's left is to define how to calculate the pathname
2542of an @code{unportable-cl-source-file}.
2545(defmethod component-pathname ((component unportable-cl-source-file))
2546  (merge-pathnames*
2547   (parse-unix-namestring (format nil "~(~A~)/" (asdf:implementation-type)))
2548   (call-next-method)))
2549@end lisp
2551The new component type is used in a @code{defsystem} form in this way:
2554(defsystem :foo
2555    :components
2556    ((:file "packages")
2557     ...
2558     (:unportable-cl-source-file "threads"
2559      :depends-on ("packages" ...))
2560     ...
2561    )
2562@end lisp
2564@node Functions,  , Components, The object model of ASDF
2565@comment  node-name,  next,  previous,  up
2566@section Functions
2567@findex version-satisfies
2569@deffn version-satisfies @var{version} @var{version-spec}
2570Does @var{version} satisfy the @var{version-spec}.  A generic function.
2571ASDF provides built-in methods for @var{version} being a @code{component} or @code{string}.
2572@var{version-spec} should be a string.
2573If it's a component, its version is extracted as a string before further processing.
2575A version string satisfies the version-spec if after parsing,
2576the former is no older than the latter.
2577Therefore @code{"1.9.1"}, @code{"1.9.2"} and @code{"1.10"} all satisfy @code{"1.9.1"},
2578but @code{"1.8.4"} or @code{"1.9"} do not.
2579For more information about how @code{version-satisfies} parses and interprets
2580version strings and specifications,
2581@pxref{The defsystem grammar} (version specifiers) and
2582@ref{Common attributes of components}.
2584Note that in versions of ASDF prior to 3.0.1,
2585including the entire ASDF 1 and ASDF 2 series,
2586@code{version-satisfies} would also require that the version and the version-spec
2587have the same major version number (the first integer in the list);
2588if the major version differed, the version would be considered as not matching the spec.
2589But that feature was not documented, therefore presumably not relied upon,
2590whereas it was a nuisance to several users.
2591Starting with ASDF 3.0.1,
2592@code{version-satisfies} does not treat the major version number specially,
2593and returns T simply if the first argument designates a version that isn't older
2594than the one specified as a second argument.
2595If needs be, the @code{(:version ...)} syntax for specifying dependencies
2596could be in the future extended to specify an exclusive upper bound for compatible versions
2597as well as an inclusive lower bound.
2598@end deffn
2600@node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
2601@comment  node-name,  next,  previous,  up
2602@chapter Controlling where ASDF searches for systems
2604@section Configurations
2606Configurations specify paths where to find system files.
2611The search registry may use some hardcoded wrapping registry specification.
2612This allows some implementations (notably SBCL) to specify where to find
2613some special implementation-provided systems that
2614need to precisely match the version of the implementation itself.
2617An application may explicitly initialize the source-registry configuration
2618using the configuration API
2619(@pxref{Controlling where ASDF searches for systems,Configuration API,Configuration API}, below)
2620in which case this takes precedence.
2621It may itself compute this configuration from the command-line,
2622from a script, from its own configuration file, etc.
2625The source registry will be configured from
2626the environment variable @code{CL_SOURCE_REGISTRY} if it exists.
2629The source registry will be configured from
2630user configuration file
2632(which defaults to
2634if it exists.
2637The source registry will be configured from
2638user configuration directory
2640(which defaults to
2642if it exists.
2645The source registry will be configured from
2646system configuration file
2648if it exists/
2651The source registry will be configured from
2652system configuration directory
2654if it exists.
2657The source registry will be configured from a default configuration.
2658This configuration may allow for implementation-specific systems
2659to be found, for systems to be found the current directory
2660(at the time that the configuration is initialized) as well as
2661@code{:directory} entries for @file{$XDG_DATA_DIRS/common-lisp/systems/} and
2662@code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/}.
2663For instance, SBCL will include directories for its contribs
2664when it can find them; it will look for them where SBCL was installed,
2665or at the location specified by the @code{SBCL_HOME} environment variable.
2667@end enumerate
2669Each of these configurations is specified as an s-expression
2670in a trivial domain-specific language (defined below).
2671Additionally, a more shell-friendly syntax is available
2672for the environment variable (defined yet below).
2674Each of these configurations is only used if the previous
2675configuration explicitly or implicitly specifies that it
2676includes its inherited configuration.
2678Additionally, some implementation-specific directories
2679may be automatically prepended to whatever directories are specified
2680in configuration files, no matter if the last one inherits or not.
2683@section Truenames and other dangers
2685One great innovation of the original ASDF was its ability to leverage
2686@code{CL:TRUENAME} to locate where your source code was and where to build it,
2687allowing for symlink farms as a simple but effective configuration mechanism
2688that is easy to control programmatically.
2689ASDF 3 still supports this configuration style, and it is enabled by default;
2690however we recommend you instead use
2691our source-registry configuration mechanism described below,
2692because it is easier to setup in a portable way across users and implementations.
2694Addtionally, some people dislike truename,
2695either because it is very slow on their system, or
2696because they are using content-addressed storage where the truename of a file
2697is related to a digest of its individual contents,
2698and not to other files in the same intended project.
2699For these people, ASDF 3 allows to eschew the @code{TRUENAME} mechanism,
2700by setting the variable @var{asdf:*resolve-symlinks*} to @code{nil}.
2702PS: Yes, if you haven't read Vernor Vinge's short but great classic
2703``True Names... and Other Dangers'' then you're in for a treat.
2706@section XDG base directory
2708Note that we purport to respect the XDG base directory specification
2709as to where configuration files are located,
2710where data files are located,
2711where output file caches are located.
2712Mentions of XDG variables refer to that document.
2716This specification allows the user to specify some environment variables
2717to customize how applications behave to his preferences.
2719On Windows platforms, when not using Cygwin,
2720instead of the XDG base directory specification,
2721we try to use folder configuration from the registry regarding
2722@code{Common AppData} and similar directories.
2723Since support for querying the Windows registry
2724is not possible to do in reasonable amounts of portable Common Lisp code,
2725ASDF 3 relies on the environment variables that Windows usually exports.
2727@section Backward Compatibility
2729For backward compatibility as well as to provide a practical backdoor for hackers,
2730ASDF will first search for @code{.asd} files in the directories specified in
2732before it searches in the source registry above.
2734@xref{Configuring ASDF,,Configuring ASDF to find your systems --- old style}.
2736By default, @code{asdf:*central-registry*} will be empty.
2738This old mechanism will therefore not affect you if you don't use it,
2739but will take precedence over the new mechanism if you do use it.
2741@section Configuration DSL
2742@cindex :inherit-configuration source config directive
2743@cindex inherit-configuration source config directive
2744@cindex :ignore-invalid-entries source config directive
2745@cindex ignore-invalid-entries source config directive
2746@cindex :directory source config directive
2747@cindex directory source config directive
2748@cindex :tree source config directive
2749@cindex tree source config directive
2750@cindex :exclude source config directive
2751@cindex exclude source config directive
2752@cindex :also-exclude source config directive
2753@cindex also-exclude source config directive
2754@cindex :include source config directive
2755@cindex include source config directive
2756@cindex :default-registry source config directive
2757@cindex default-registry source config directive
2759Here is the grammar of the s-expression (SEXP) DSL for source-registry
2762@c FIXME: This is too wide for happy compilation into pdf.
2765;; A configuration is a single SEXP starting with keyword :source-registry
2766;; followed by a list of directives.
2767CONFIGURATION := (:source-registry DIRECTIVE ...)
2769;; A directive is one of the following:
2772    ;; Your configuration expression MUST contain
2773    ;; exactly one of either of these:
2774    :inherit-configuration | ; splices inherited configuration (often specified last)
2775    :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
2777    ;; forward compatibility directive (since ASDF 2.011.4), useful when
2778    ;; you want to use new configuration features but have to bootstrap a
2779    ;; the newer required ASDF from an older release that doesn't sport said features:
2780    :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
2782    ;; add a single directory to be scanned (no recursion)
2785    ;; add a directory hierarchy, recursing but excluding specified patterns
2788    ;; override the defaults for exclusion patterns
2789    (:exclude EXCLUSION-PATTERN ...) |
2790    ;; augment the defaults for exclusion patterns
2791    (:also-exclude EXCLUSION-PATTERN ...) |
2792    ;; Note that the scope of a an exclude pattern specification is
2793    ;; the rest of the current configuration expression or file.
2795    ;; splice the parsed contents of another config file
2798    ;; This directive specifies that some default must be spliced.
2799    :default-registry
2802DIRECTORY-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a directory name
2805    NIL | ;; Special: skip this entry.
2808EXCLUSION-PATTERN := a string without wildcards, that will be matched exactly
2809  against the name of a any subdirectory in the directory component
2810        of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"}
2811@end example
2813Pathnames are designated using another DSL,
2814shared with the output-translations configuration DSL below.
2815The DSL is resolved by the function @code{asdf::resolve-location},
2816to be documented and exported at some point in the future.
2821    STRING | ;; namestring (better be absolute or bust, directory assumed where applicable).
2822             ;; In output-translations, directory is assumed and **/*.*.* added if it's last.
2823             ;; On MCL, a MacOSX-style POSIX namestring (for MacOS9 style, use #p"...");
2824             ;; Note that none of the above applies to strings used in *central-registry*,
2825             ;; which doesn't use this DSL: they are processed as normal namestrings.
2826             ;; however, you can compute what you put in the *central-registry*
2827             ;; based on the results of say (asdf::resolve-location "/Users/fare/cl/cl-foo/")
2828    PATHNAME | ;; pathname (better be an absolute path, or bust)
2829               ;; In output-translations, unless followed by relative components,
2830               ;; it better have appropriate wildcards, as in **/*.*.*
2831    :HOME | ;; designates the user-homedir-pathname ~/
2832    :USER-CACHE | ;; designates the default location for the user cache
2833    :HERE | ;; designates the location of the configuration file
2834            ;; (or *default-pathname-defaults*, if invoked interactively)
2835    :ROOT ;; magic, for output-translations source only: paths that are relative
2836          ;; to the root of the source host and device
2837    ;; Not valid anymore: :SYSTEM-CACHE (was a security hazard)
2841    STRING | ;; relative directory pathname as interpreted by parse-unix-namestring.
2842             ;; In output translations, if last component, **/*.*.* is added
2843    PATHNAME | ;; pathname; unless last component, directory is assumed.
2844    :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
2845    :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
2846    :DEFAULT-DIRECTORY | ;; a relativized version of the default directory
2847    :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
2848    :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
2849    :*.*.* | ;; any file (since ASDF 2.011.4)
2850    ;; Not supported (anymore): :UID and :USERNAME
2851@end example
2853For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf},
2854which is the default place ASDF looks for this configuration, once contained:
2857  (:tree (:home "cl")) ;; will expand to e.g. "/home/joeluser/cl/"
2858  :inherit-configuration)
2859@end example
2861@section Configuration Directories
2863Configuration directories consist in files each containing
2864a list of directives without any enclosing @code{(:source-registry ...)} form.
2865The files will be sorted by namestring as if by @code{string<} and
2866the lists of directives of these files with be concatenated in order.
2867An implicit @code{:inherit-configuration} will be included
2868at the @emph{end} of the list.
2870This allows for packaging software that has file granularity
2871(e.g. Debian's @code{dpkg} or some future version of @code{clbuild})
2872to easily include configuration information about distributed software.
2874The convention is that, for sorting purposes,
2875the names of files in such a directory begin with two digits
2876that determine the order in which these entries will be read.
2877Also, the type of these files is conventionally @code{"conf"}
2878and as a limitation to some implementations (e.g. GNU clisp),
2879the type cannot be @code{nil}.
2881Directories may be included by specifying a directory pathname
2882or namestring in an @code{:include} directive, e.g.:
2885  (:include "/foo/bar/")
2886@end example
2888Hence, to achieve the same effect as
2889my example @file{~/.config/common-lisp/source-registry.conf} above,
2890I could simply create a file
2892alone in its directory with the following contents:
2894(:tree "/home/fare/cl/")
2895@end example
2897@subsection The :here directive
2899The @code{:here} directive is an absolute pathname designator that
2900refers to the directory containing the configuration file currently
2901being processed.
2903The @code{:here} directive is intended to simplify the delivery of
2904complex CL systems, and for easy configuration of projects shared through
2905revision control systems, in accordance with our design principle that
2906each participant should be able to provide all and only the information
2907available to him or her.
2909Consider a person X who has set up the source code repository for a
2910complex project with a master directory @file{dir/}.  Ordinarily, one
2911might simply have the user add a directive that would look something
2912like this:
2914   (:tree  "path/to/dir")
2915@end example
2916But what if X knows that there are very large subtrees
2917under dir that are filled with, e.g., Java source code, image files for
2918icons, etc.?  All of the asdf system definitions are contained in the
2919subdirectories @file{dir/src/lisp/} and @file{dir/extlib/lisp/}, and
2920these are the only directories that should be searched.
2922In this case, X can put into @file{dir/} a file @file{asdf.conf} that
2923contains the following:
2926   (:tree (:here "src/lisp/"))
2927   (:tree (:here "extlib/lisp"))
2928   (:directory (:here "outlier/")))
2929@end example
2931Then when someone else (call her Y) checks out a copy of this
2932repository, she need only add
2934(:include "/path/to/my/checkout/directory/asdf.conf")
2935@end example
2936to one of her previously-existing asdf source location configuration
2937files, or invoke @code{initialize-source-registry} with a configuration
2938form containing that s-expression.  ASDF will find the .conf file that X
2939has provided, and then set up source locations within the working
2940directory according to X's (relative) instructions.
2942@section Shell-friendly syntax for configuration
2944When considering environment variable @code{CL_SOURCE_REGISTRY}
2945ASDF will skip to next configuration if it's an empty string.
2946It will @code{READ} the string as a SEXP in the DSL
2947if it begins with a paren @code{(}
2948and it will be interpreted much like @code{TEXINPUTS}
2949list of paths, where
2951  * paths are separated
2952   by a @code{:} (colon) on Unix platforms (including cygwin),
2953   by a @code{;} (semicolon) on other platforms (mainly, Windows).
2955  * each entry is a directory to add to the search path.
2957  * if the entry ends with a double slash @code{//}
2958    then it instead indicates a tree in the subdirectories
2959    of which to recurse.
2961  * if the entry is the empty string (which may only appear once),
2962    then it indicates that the inherited configuration should be
2963    spliced there.
2966@section Search Algorithm
2967@vindex *default-source-registry-exclusions*
2969In case that isn't clear, the semantics of the configuration is that
2970when searching for a system of a given name,
2971directives are processed in order.
2973When looking in a directory, if the system is found, the search succeeds,
2974otherwise it continues.
2976When looking in a tree, if one system is found, the search succeeds.
2977If multiple systems are found, the consequences are unspecified:
2978the search may succeed with any of the found systems,
2979or an error may be raised.
2980ASDF currently returns the first system found,
2981XCVB currently raised an error.
2982If none is found, the search continues.
2984Exclude statements specify patterns of subdirectories
2985the systems from which to ignore.
2986Typically you don't want to use copies of files kept by such
2987version control systems as Darcs.
2988Exclude statements are not propagated to further included or inherited
2989configuration files or expressions;
2990instead the defaults are reset around every configuration statement
2991to the default defaults from @code{asdf::*default-source-registry-exclusions*}.
2993Include statements cause the search to recurse with the path specifications
2994from the file specified.
2996An inherit-configuration statement cause the search to recurse with the path
2997specifications from the next configuration
2998(@pxref{Controlling where ASDF searches for systems,,Configurations} above).
3001@section Caching Results
3003The implementation is allowed to either eagerly compute the information
3004from the configurations and file system, or to lazily re-compute it
3005every time, or to cache any part of it as it goes.
3006To explicitly flush any information cached by the system, use the API below.
3009@section Configuration API
3011The specified functions are exported from your build system's package.
3012Thus for ASDF the corresponding functions are in package ASDF,
3013and for XCVB the corresponding functions are in package XCVB.
3015@defun initialize-source-registry @Aoptional PARAMETER
3016   will read the configuration and initialize all internal variables.
3017   You may extend or override configuration
3018   from the environment and configuration files
3019   with the given @var{PARAMETER}, which can be
3020   @code{nil} (no configuration override),
3021   or a SEXP (in the SEXP DSL),
3022   a string (as in the string DSL),
3023   a pathname (of a file or directory with configuration),
3024   or a symbol (fbound to function that when called returns one of the above).
3025@end defun
3027@defun clear-source-registry
3028   undoes any source registry configuration
3029   and clears any cache for the search algorithm.
3030   You might want to call this function
3031   (or better, @code{clear-configuration})
3032   before you dump an image that would be resumed
3033   with a different configuration,
3034   and return an empty configuration.
3035   Note that this does not include clearing information about
3036   systems defined in the current image, only about
3037   where to look for systems not yet defined.
3038@end defun
3040@defun ensure-source-registry @Aoptional PARAMETER
3041   checks whether a source registry has been initialized.
3042   If not, initialize it with the given @var{PARAMETER}.
3043@end defun
3045Every time you use ASDF's @code{find-system}, or
3046anything that uses it (such as @code{operate}, @code{load-system}, etc.),
3047@code{ensure-source-registry} is called with parameter @code{nil},
3048which the first time around causes your configuration to be read.
3049If you change a configuration file,
3050you need to explicitly @code{initialize-source-registry} again,
3051or maybe simply to @code{clear-source-registry} (or @code{clear-configuration})
3052which will cause the initialization to happen next time around.
3054@section Introspection
3056@subsection *source-registry-parameter* variable
3057@vindex *source-registry-parameter*
3059We have made available the variable @code{*source-registry-parameter*}
3060that can be used by code that wishes to introspect about the (past)
3061configuration of ASDF's source registry.  @strong{This variable should
3062never be set!}  It will be set as a side-effect of calling
3063@code{initialize-source-registry}; user code should treat it as
3066@subsection Information about system dependencies
3068ASDF makes available three functions to read system interdependencies.
3069These are intended to aid programmers who wish to perform dependency
3072@defun system-defsystem-depends-on system
3073@end defun
3075@defun system-depends-on system
3076@end defun
3078@defun system-weakly-depends-on system
3079Returns a list of names of systems that are weakly depended on by
3080@var{system}.  Weakly depended on systems are optionally loaded only if
3081ASDF can find them; failure to find such systems does @emph{not} cause an
3082error in loading.
3084Note that the return value for @code{system-weakly-depends-on} is simpler
3085than the return values of the other two system dependency introspection
3087@end defun
3089@section Status
3091This mechanism is vastly successful, and we have declared
3092that @code{asdf:*central-registry*} is not recommended anymore,
3093though we will continue to support it.
3094All hooks into implementation-specific search mechanisms
3095have been integrated in the @code{wrapping-source-registry}
3096that everyone uses implicitly.
3099@section Rejected ideas
3101Alternatives I considered and rejected included:
3104@item Keep @code{asdf:*central-registry*} as the master with its current semantics,
3105   and somehow the configuration parser expands the new configuration
3106   language into a expanded series of directories of subdirectories to
3107   lookup, pre-recursing through specified hierarchies. This is kludgy,
3108   and leaves little space of future cleanups and extensions.
3110@item Keep @code{asdf:*central-registry*} remains the master but extend its semantics
3111   in completely new ways, so that new kinds of entries may be implemented
3112   as a recursive search, etc. This seems somewhat backwards.
3114@item Completely remove @code{asdf:*central-registry*}
3115   and break backwards compatibility.
3116   Hopefully this will happen in a few years after everyone migrate to
3117   a better ASDF and/or to XCVB, but it would be very bad to do it now.
3119@item Replace @code{asdf:*central-registry*} by a symbol-macro with appropriate magic
3120   when you dereference it or setf it. Only the new variable with new
3121   semantics is handled by the new search procedure.
3122   Complex and still introduces subtle semantic issues.
3123@end enumerate
3126I've been suggested the below features, but have rejected them,
3127for the sake of keeping ASDF no more complex than strictly necessary.
3131  More syntactic sugar: synonyms for the configuration directives, such as
3132  @code{(:add-directory X)} for @code{(:directory X)}, or @code{(:add-directory-hierarchy X)}
3133  or @code{(:add-directory X :recurse t)} for @code{(:tree X)}.
3136   The possibility to register individual files instead of directories.
3139  Integrate Xach Beane's tilde expander into the parser,
3140  or something similar that is shell-friendly or shell-compatible.
3141  I'd rather keep ASDF minimal. But maybe this precisely keeps it
3142  minimal by removing the need for evaluated entries that ASDF has?
3143  i.e. uses of @code{USER-HOMEDIR-PATHNAME} and @code{$SBCL_HOME}
3144  Hopefully, these are already superseded by the @code{:default-registry}
3147  Using the shell-unfriendly syntax @code{/**} instead of @code{//} to specify recursion
3148  down a filesystem tree in the environment variable.
3149  It isn't that Lisp friendly either.
3150@end itemize
3152@section TODO
3155@item Add examples
3156@end itemize
3159@section Credits for the source-registry
3161Thanks a lot to Stelian Ionescu for the initial idea.
3163Thanks to Rommel Martinez for the initial implementation attempt.
3165All bad design ideas and implementation bugs are mine, not theirs.
3166But so are good design ideas and elegant implementation tricks.
3168 --- Francois-Rene Rideau @email{}, Mon, 22 Feb 2010 00:07:33 -0500
3172@node Controlling where ASDF saves compiled files, Error handling, Controlling where ASDF searches for systems, Top
3173@comment  node-name,  next,  previous,  up
3174@chapter Controlling where ASDF saves compiled files
3175@cindex asdf-output-translations
3178Each Common Lisp implementation has its own format
3179for compiled files (fasls for short, short for ``fast loading'').
3180If you use multiple implementations
3181(or multiple versions of the same implementation),
3182you'll soon find your source directories
3183littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so on.
3184Worse yet, some implementations use the same file extension
3185while changing formats from version to version (or platform to platform)
3186which means that you'll have to recompile binaries
3187as you switch from one implementation to the next.
3189Since ASDF 2, ASDF includes the @code{asdf-output-translations} facility
3190to mitigate the problem.
3192@section Configurations
3194Configurations specify mappings from input locations to output locations.
3195Once again we rely on the XDG base directory specification for configuration.
3196@xref{Controlling where ASDF searches for systems,,XDG base directory}.
3201Some hardcoded wrapping output translations configuration may be used.
3202This allows special output translations (or usually, invariant directories)
3203to be specified corresponding to the similar special entries in the source registry.
3206An application may explicitly initialize the output-translations
3207configuration using the Configuration API
3208in which case this takes precedence.
3209(@pxref{Controlling where ASDF saves compiled files,,Configuration API}.)
3210It may itself compute this configuration from the command-line,
3211from a script, from its own configuration file, etc.
3214The source registry will be configured from
3215the environment variable @code{ASDF_OUTPUT_TRANSLATIONS} if it exists.
3218The source registry will be configured from
3219user configuration file
3221(which defaults to
3223if it exists.
3226The source registry will be configured from
3227user configuration directory
3229(which defaults to
3231if it exists.
3234The source registry will be configured from
3235system configuration file
3237if it exists.
3240The source registry will be configured from
3241system configuration directory
3243if it exists.
3245@end enumerate
3247Each of these configurations is specified as a SEXP
3248in a trival domain-specific language (defined below).
3249Additionally, a more shell-friendly syntax is available
3250for the environment variable (defined yet below).
3252Each of these configurations is only used if the previous
3253configuration explicitly or implicitly specifies that it
3254includes its inherited configuration.
3256Note that by default, a per-user cache is used for output files.
3257This allows the seamless use of shared installations of software
3258between several users, and takes files out of the way of the developers
3259when they browse source code,
3260at the expense of taking a small toll when developers have to clean up
3261output files and find they need to get familiar with output-translations first.
3264@section Backward Compatibility
3265@cindex ASDF-BINARY-LOCATIONS compatibility
3268We purposefully do NOT provide backward compatibility with earlier versions of
3269@code{ASDF-Binary-Locations} (8 Sept 2009),
3270@code{common-lisp-controller} (7.0) or
3271@code{cl-launch} (2.35),
3272each of which had similar general capabilities.
3273The previous APIs of these programs were not designed
3274for configuration by the end-user
3275in an easy way with configuration files.
3276Recent versions of same packages use
3277the new @code{asdf-output-translations} API as defined below:
3278@code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000).
3279@code{ASDF-Binary-Locations} is fully superseded and not to be used anymore.
3281This incompatibility shouldn't inconvenience many people.
3282Indeed, few people use and customize these packages;
3283these few people are experts who can trivially adapt to the new configuration.
3284Most people are not experts, could not properly configure these features
3285(except inasmuch as the default configuration of
3286@code{common-lisp-controller} and/or @code{cl-launch}
3287might have been doing the right thing for some users),
3288and yet will experience software that ``just works'',
3289as configured by the system distributor, or by default.
3291Nevertheless, if you are a fan of @code{ASDF-Binary-Locations},
3292we provide a limited emulation mode:
3294@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
3295This function will initialize the new @code{asdf-output-translations} facility in a way
3296that emulates the behavior of the old @code{ASDF-Binary-Locations} facility.
3297Where you would previously set global variables
3301@var{*map-all-source-files*} or @var{*source-to-target-mappings*}
3302you will now have to pass the same values as keyword arguments to this function.
3303Note however that as an extension the @code{:source-to-target-mappings} keyword argument
3304will accept any valid pathname designator for @code{asdf-output-translations}
3305instead of just strings and pathnames.
3306@end defun
3308If you insist, you can also keep using the old @code{ASDF-Binary-Locations}
3309(the one available as an extension to load of top of ASDF,
3310not the one built into a few old versions of ASDF),
3311but first you must disable @code{asdf-output-translations}
3312with @code{(asdf:disable-output-translations)},
3313or you might experience ``interesting'' issues.
3315Also, note that output translation is enabled by default.
3316To disable it, use @code{(asdf:disable-output-translations)}.
3319@section Configuration DSL
3321Here is the grammar of the SEXP DSL
3322for @code{asdf-output-translations} configuration:
3325;; A configuration is single SEXP starting with keyword :source-registry
3326;; followed by a list of directives.
3327CONFIGURATION := (:output-translations DIRECTIVE ...)
3329;; A directive is one of the following:
3332    ;; Your configuration expression MUST contain
3333    ;; exactly one of either of these:
3334    :inherit-configuration | ; splices inherited configuration (often specified last)
3335    :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
3337    ;; forward compatibility directive (since ASDF 2.011.4), useful when
3338    ;; you want to use new configuration features but have to bootstrap a
3339    ;; the newer required ASDF from an older release that doesn't sport said features:
3340    :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
3342    ;; include a configuration file or directory
3343    (:include PATHNAME-DESIGNATOR) |
3345    ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/ or something.
3346    :enable-user-cache |
3347    ;; Disable global cache. Map / to /
3348    :disable-cache |
3350    ;; add a single directory to be scanned (no recursion)
3353    ;; use a function to return the translation of a directory designator
3357    NIL | ;; As source: skip this entry. As destination: same as source
3358    T | ;; as source matches anything, as destination leaves pathname unmapped.
3359    ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language
3362    SYMBOL | ;; symbol of a function that takes two arguments,
3363             ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
3364    LAMBDA   ;; A form which evalutates to a function taking two arguments consisting of
3365             ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
3367@end verbatim
3369Relative components better be either relative
3370or subdirectories of the path before them, or bust.
3372The last component, if not a pathname, is notionally completed by @file{/**/*.*}.
3373You can specify more fine-grained patterns
3374by using a pathname object as the last component
3375e.g. @file{#p"some/path/**/foo*/bar-*.fasl"}
3377You may use @code{#+features} to customize the configuration file.
3379The second designator of a mapping may be @code{nil}, indicating that files are not mapped
3380to anything but themselves (same as if the second designator was the same as the first).
3382When the first designator is @code{t},
3383the mapping always matches.
3384When the first designator starts with @code{:root},
3385the mapping matches any host and device.
3386In either of these cases, if the second designator
3387isn't @code{t} and doesn't start with @code{:root},
3388then strings indicating the host and pathname are somehow copied
3389in the beginning of the directory component of the source pathname
3390before it is translated.
3392When the second designator is @code{t}, the mapping is the identity.
3393When the second designator starts with @code{:root},
3394the mapping preserves the host and device of the original pathname.
3395Notably, this allows you to map files
3396to a subdirectory of the whichever directory the file is in.
3397Though the syntax is not quite as easy to use as we'd like,
3398you can have an (source destination) mapping entry such as follows
3399in your configuration file,
3400or you may use @code{enable-asdf-binary-locations-compatibility}
3401with @code{:centralize-lisp-binaries nil}
3402which will do the same thing internally for you:
3404  #.(let ((wild-subdir (make-pathname :directory '(:relative :wild-inferiors)))
3405          (wild-file (make-pathname :name :wild :version :wild :type :wild)))
3406     `((:root ,wild-subdir ,wild-file) ;; Or using the implicit wildcard, just :root
3407       (:root ,wild-subdir :implementation ,wild-file)))
3408@end verbatim
3409Starting with ASDF 2.011.4, you can use the simpler:
3410  @code{`(:root (:root :**/ :implementation :*.*.*))}
3414@code{:include} statements cause the search to recurse with the path specifications
3415from the file specified.
3417If the @code{translate-pathname} mechanism cannot achieve a desired
3418translation, the user may provide a function which provides the
3419required algorithim.  Such a translation function is specified by
3420supplying a list as the second @code{directory-designator}
3421the first element of which is the keyword @code{:function},
3422and the second element of which is
3423either a symbol which designates a function or a lambda expression.
3424The function designated by the second argument must take two arguments,
3425the first being the pathname of the source file,
3426the second being the wildcard that was matched.
3427The result of the function invocation should be the translated pathname.
3429An @code{:inherit-configuration} statement cause the search to recurse with the path
3430specifications from the next configuration.
3431@xref{Controlling where ASDF saves compiled files,,Configurations}, above.
3435@code{:enable-user-cache} is the same as @code{(t :user-cache)}.
3437@code{:disable-cache} is the same as @code{(t t)}.
3439@code{:user-cache} uses the contents of variable @code{asdf::*user-cache*}
3440which by default is the same as using
3441@code{(:home ".cache" "common-lisp" :implementation)}.
3442@end itemize
3445@section Configuration Directories
3447Configuration directories consist in files each contains
3448a list of directives without any enclosing
3449@code{(:output-translations ...)} form.
3450The files will be sorted by namestring as if by @code{string<} and
3451the lists of directives of these files with be concatenated in order.
3452An implicit @code{:inherit-configuration} will be included
3453at the @emph{end} of the list.
3455This allows for packaging software that has file granularity
3456(e.g. Debian's @command{dpkg} or some future version of @command{clbuild})
3457to easily include configuration information about software being distributed.
3459The convention is that, for sorting purposes,
3460the names of files in such a directory begin with two digits
3461that determine the order in which these entries will be read.
3462Also, the type of these files is conventionally @code{"conf"}
3463and as a limitation of some implementations, the type cannot be @code{nil}.
3465Directories may be included by specifying a directory pathname
3466or namestring in an @code{:include} directive, e.g.:
3468  (:include "/foo/bar/")
3469@end verbatim
3471@section Shell-friendly syntax for configuration
3473When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS}
3474ASDF will skip to next configuration if it's an empty string.
3475It will @code{READ} the string as an SEXP in the DSL
3476if it begins with a paren @code{(}
3477and it will be interpreted as a list of directories.
3478Directories should come by pairs, indicating a mapping directive.
3479Entries are separated
3480by a @code{:} (colon) on Unix platforms (including cygwin),
3481by a @code{;} (semicolon) on other platforms (mainly, Windows).
3483The magic empty entry,
3484if it comes in what would otherwise be the first entry in a pair,
3485indicates the splicing of inherited configuration.
3486If it comes as the second entry in a pair,
3487it indicates that the directory specified first is to be left untranslated
3488(which has the same effect as if the directory had been repeated).
3491@section Semantics of Output Translations
3493From the specified configuration,
3494a list of mappings is extracted in a straightforward way:
3495mappings are collected in order, recursing through
3496included or inherited configuration as specified.
3497To this list is prepended some implementation-specific mappings,
3498and is appended a global default.
3500The list is then compiled to a mapping table as follows:
3501for each entry, in order, resolve the first designated directory
3502into an actual directory pathname for source locations.
3503If no mapping was specified yet for that location,
3504resolve the second designated directory to an output location directory
3505add a mapping to the table mapping the source location to the output location,
3506and add another mapping from the output location to itself
3507(unless a mapping already exists for the output location).
3509Based on the table, a mapping function is defined,
3510mapping source pathnames to output pathnames:
3511given a source pathname, locate the longest matching prefix
3512in the source column of the mapping table.
3513Replace that prefix by the corresponding output column
3514in the same row of the table, and return the result.
3515If no match is found, return the source pathname.
3516(A global default mapping the filesystem root to itself
3517may ensure that there will always be a match,
3518with same fall-through semantics).
3520@section Caching Results
3522The implementation is allowed to either eagerly compute the information
3523from the configurations and file system, or to lazily re-compute it
3524every time, or to cache any part of it as it goes.
3525To explicitly flush any information cached by the system, use the API below.
3528@section Output location API
3530The specified functions are exported from package ASDF.
3532@defun initialize-output-translations @Aoptional PARAMETER
3533   will read the configuration and initialize all internal variables.
3534   You may extend or override configuration
3535   from the environment and configuration files
3536   with the given @var{PARAMETER}, which can be
3537   @code{nil} (no configuration override),
3538   or a SEXP (in the SEXP DSL),
3539   a string (as in the string DSL),
3540   a pathname (of a file or directory with configuration),
3541   or a symbol (fbound to function that when called returns one of the above).
3542@end defun
3544@defun disable-output-translations
3545   will initialize output translations in a way
3546   that maps every pathname to itself,
3547   effectively disabling the output translation facility.
3548@end defun
3550@defun clear-output-translations
3551   undoes any output translation configuration
3552   and clears any cache for the mapping algorithm.
3553   You might want to call this function
3554   (or better, @code{clear-configuration})
3555   before you dump an image that would be resumed
3556   with a different configuration,
3557   and return an empty configuration.
3558   Note that this does not include clearing information about
3559   systems defined in the current image, only about
3560   where to look for systems not yet defined.
3561@end defun
3563@defun ensure-output-translations @Aoptional PARAMETER
3564   checks whether output translations have been initialized.
3565   If not, initialize them with the given @var{PARAMETER}.
3566   This function will be called before any attempt to operate on a system.
3567@end defun
3569@defun apply-output-translations PATHNAME
3570   Applies the configured output location translations to @var{PATHNAME}
3571   (calls @code{ensure-output-translations} for the translations).
3572@end defun
3574Every time you use ASDF's @code{output-files}, or
3575anything that uses it (that may compile, such as @code{operate}, @code{perform}, etc.),
3576@code{ensure-output-translations} is called with parameter @code{nil},
3577which the first time around causes your configuration to be read.
3578If you change a configuration file,
3579you need to explicitly @code{initialize-output-translations} again,
3580or maybe @code{clear-output-translations} (or @code{clear-configuration}),
3581which will cause the initialization to happen next time around.
3584@section Credits for output translations
3586Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations},
3587and to Peter van Eynde for @code{Common Lisp Controller}.
3589All bad design ideas and implementation bugs are to mine, not theirs.
3590But so are good design ideas and elegant implementation tricks.
3592 --- Francois-Rene Rideau @email{}
3594@c @section Default locations
3595@c @findex output-files-for-system-and-operation
3597@c The default binary location for each Lisp implementation
3598@c is a subdirectory of each source directory.
3599@c To account for different Lisps, Operating Systems, Implementation versions,
3600@c and so on, ASDF borrows code from SLIME
3601@c to create reasonable custom directory names.
3602@c Here are some examples:
3604@c @itemize
3605@c @item
3606@c SBCL, version 1.0.45 on Mac OS X for Intel: @code{sbcl-1.0.45-darwin-x86}
3608@c @item
3609@c Franz Allegro, version 8.0, ANSI Common Lisp: @code{allegro-8.0a-macosx-x86}
3611@c @item
3612@c Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: @code{allegro-8.1m-macosx-x86}
3613@c @end itemize
3615@c By default, all output file pathnames will be relocated
3616@c to some thus-named subdirectory of @file{~/.cache/common-lisp/}.
3618@c See the document @file{README.asdf-output-translations}
3619@c for a full specification on how to configure @code{asdf-output-translations}.
3621@node  Error handling, Miscellaneous additional functionality, Controlling where ASDF saves compiled files, Top
3622@comment  node-name,  next,  previous,  up
3623@chapter Error handling
3627@section ASDF errors
3629If ASDF detects an incorrect system definition, it will signal a generalised instance of
3632Operations may go wrong (for example when source files contain errors).
3633These are signalled using generalised instances of
3636@section Compilation error and warning handling
3637@vindex *compile-file-warnings-behaviour*
3638@vindex *compile-file-errors-behavior*
3640ASDF checks for warnings and errors when a file is compiled.
3641The variables @var{*compile-file-warnings-behaviour*} and
3643control the handling of any such events.
3644The valid values for these variables are
3645@code{:error}, @code{:warn}, and @code{:ignore}.
3647@node  Miscellaneous additional functionality, Getting the latest version, Error handling, Top
3648@comment  node-name,  next,  previous,  up
3649@chapter Miscellaneous additional functionality
3651ASDF includes several additional features that are generally
3652useful for system definition and development.
3654@section Controlling file compilation
3655@cindex :around-compile
3656@cindex around-compile keyword
3657@cindex compile-check keyword
3658@cindex :compile-check
3659@findex compile-file*
3661When declaring a component (system, module, file),
3662you can specify a keyword argument @code{:around-compile function}.
3663If left unspecified (and therefore unbound),
3664the value will be inherited from the parent component if any,
3665or with a default of @code{nil}
3666if no value is specified in any transitive parent.
3668The argument must be a either @code{nil}, a fbound symbol,
3669a lambda-expression (e.g. @code{(lambda (thunk) ...(funcall thunk ...) ...)})
3670a function object (e.g. using @code{#.#'} but that's discouraged
3671because it prevents the introspection done by e.g. asdf-dependency-grovel),
3672or a string that when @code{read} yields a symbol or a lambda-expression.
3673@code{nil} means the normal compile-file function will be called.
3674A non-nil value designates a function of one argument
3675that will be called with a function that will
3676invoke @code{compile-file*} with various arguments;
3677the around-compile hook may supply additional keyword arguments
3678to pass to that call to @code{compile-file*}.
3680One notable argument that is heeded by @code{compile-file*} is
3682a function called when the compilation was otherwise a success,
3683with the same arguments as @code{compile-file};
3684the function shall return true if the compilation
3685and its resulting compiled file respected all system-specific invariants,
3686and false (@code{nil}) if it broke any of those invariants;
3687it may issue warnings or errors before it returns @code{nil}.
3688(NB: The ability to pass such extra flags
3689is only available starting with ASDF 2.22.3.)
3690This feature is notably exercised by asdf-finalizers.
3692By using a string, you may reference
3693a function, symbol and/or package
3694that will only be created later during the build, but
3695isn't yet present at the time the defsystem form is evaluated.
3696However, if your entire system is using such a hook, you may have to
3697explicitly override the hook with @code{nil} for all the modules and files
3698that are compiled before the hook is defined.
3700Using this hook, you may achieve such effects as:
3701locally renaming packages,
3702binding @var{*readtables*} and other syntax-controlling variables,
3703handling warnings and other conditions,
3704proclaiming consistent optimization settings,
3705saving code coverage information,
3706maintaining meta-data about compilation timings,
3707setting gensym counters and PRNG seeds and other sources of non-determinism,
3708overriding the source-location and/or timestamping systems,
3709checking that some compile-time side-effects were properly balanced,
3712Note that there is no around-load hook. This is on purpose.
3713Some implementations such as ECL, GCL or MKCL link object files,
3714which allows for no such hook.
3715Other implementations allow for concatenating FASL files,
3716which doesn't allow for such a hook either.
3717We aim to discourage something that's not portable,
3718and has some dubious impact on performance and semantics
3719even when it is possible.
3720Things you might want to do with an around-load hook
3721are better done around-compile,
3722though it may at times require some creativity
3723(see e.g. the @code{package-renaming} system).
3726@section Controlling source file character encoding
3728Starting with ASDF 2.21, components accept a @code{:encoding} option
3729so authors may specify which character encoding should be used
3730to read and evaluate their source code.
3731When left unspecified, the encoding is inherited
3732from the parent module or system;
3733if no encoding is specified at any point,
3734the default @code{:autodetect} is assumed.
3735By default, only @code{:default}, @code{:utf-8}
3736and @code{:autodetect} are accepted.
3737@code{:autodetect}, the default, calls
3738@code{*encoding-detection-hook*} which by default always returns
3739@code{*default-encoding*} which itself defaults to @code{:default}.
3741In other words, there now are plenty of extension hooks, but
3742by default ASDF follows the backwards compatible behavior
3743of using whichever @code{:default} encoding your implementation uses,
3744which itself may or may not vary based on environment variables
3745and other locale settings.
3746In practice this means that only source code that only uses ASCII
3747is guaranteed to be read the same on all implementations
3748independently from any user setting.
3750Additionally, for backward-compatibility with older versions of ASDF
3751and/or with implementations that do not support unicode and its many encodings,
3752you may want to use
3753the reader conditionals @code{#+asdf-unicode #+asdf-unicode}
3754to protect any @code{:encoding @emph{encoding}} statement
3755as @code{:asdf-unicode} will be present in @code{*features*}
3756only if you're using a recent ASDF
3757on an implementation that supports unicode.
3758We recommend that you avoid using unprotected @code{:encoding} specifications
3759until after ASDF 2.21 or later becomes widespread, hopefully by the end of 2012.
3761While it offers plenty of hooks for extension,
3762and one such extension is being developed (see below),
3763ASDF itself only recognizes one encoding beside @code{:default},
3764and that is @code{:utf-8}, which is the @emph{de facto} standard,
3765already used by the vast majority of libraries that use more than ASCII.
3766On implementations that do not support unicode,
3767the feature @code{:asdf-unicode} is absent, and
3768the @code{:default} external-format is used
3769to read even source files declared as @code{:utf-8}.
3770On these implementations, non-ASCII characters
3771intended to be read as one CL character
3772may thus end up being read as multiple CL characters.
3773In most cases, this shouldn't affect the software's semantics:
3774comments will be skipped just the same, strings with be read and printed
3775with slightly different lengths, symbol names will be accordingly longer,
3776but none of it should matter.
3777But a few systems that actually depend on unicode characters
3778may fail to work properly, or may work in a subtly different way.
3779See for instance @code{lambda-reader}.
3781We invite you to embrace UTF-8
3782as the encoding for non-ASCII characters starting today,
3783even without any explicit specification in your @code{.asd} files.
3784Indeed, on some implementations and configurations,
3785UTF-8 is already the @code{:default},
3786and loading your code may cause errors if it is encoded in anything but UTF-8.
3787Therefore, even with the legacy behavior,
3788non-UTF-8 is guaranteed to break for some users,
3789whereas UTF-8 is pretty much guaranteed not to break anywhere
3790(provided you do @emph{not} use a BOM),
3791although it might be read incorrectly on some implementations.
3792In the future, we intend to make @code{:utf-8}
3793the default value of @code{*default-encoding*},
3794to be enforced everywhere, so at least the code is guaranteed
3795to be read correctly everywhere it can be.
3797If you need non-standard character encodings for your source code,
3798use the extension system @code{asdf-encodings}, by specifying
3799@code{:defsystem-depends-on (:asdf-encodings)} in your @code{defsystem}.
3800This extension system will register support for more encodings using the
3801@code{*encoding-external-format-hook*} facility,
3802so you can explicitly specify @code{:encoding :latin1}
3803in your @code{.asd} file.
3804Using the @code{*encoding-detection-hook*} it will also
3805eventually implement some autodetection of a file's encoding
3806from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration,
3807or otherwise based on an analysis of octet patterns in the file.
3808At this point, asdf-encoding only supports the encodings
3809that are supported as part of your implementation.
3810Since the list varies depending on implementations,
3811we once again recommend you use @code{:utf-8} everywhere,
3812which is the most portable (next is @code{:latin1}).
3814If you're not using a version of Quicklisp that has it,
3815you may get the source for @code{asdf-encodings} using git:
3816@kbd{git clone git://}
3818@kbd{git clone ssh://}.
3819You can also browse the repository on
3822In the future, we intend to change the default @code{*default-encoding*}
3823to @code{:utf-8}, which is already the de facto standard
3824for most libraries that use non-ASCII characters:
3825utf-8 works everywhere and was backhandedly enforced by
3826a lot of people using SBCL and utf-8 and sending reports to authors
3827so they make their packages compatible.
3828A survey showed only about a handful few libraries
3829are incompatible with non-UTF-8, and then, only in comments,
3830and we believe that authors will adopt UTF-8 when prompted.
3831See the April 2012 discussion on the asdf-devel mailing-list.
3832For backwards compatibility with users who insist on a non-UTF-8 encoding,
3833but cannot immediately transition to using @code{asdf-encodings}
3834(maybe because it isn't ready), it will still be possible to use
3835the @code{:encoding :default} option in your @code{defsystem} form
3836to restore the behavior of ASDF 2.20 and earlier.
3837This shouldn't be required in libraries,
3838because user pressure as mentioned above will already have pushed
3839library authors towards using UTF-8;
3840but authors of end-user programs might care.
3842When you use @code{asdf-encodings}, any further loaded @code{.asd} file
3843will use the autodetection algorithm to determine its encoding;
3844yet if you depend on this detection happening,
3845you may want to explicitly load @code{asdf-encodings} early in your build,
3846for by the time you can use @code{:defsystem-depends-on},
3847it is already too late to load it.
3848In practice, this means that the @code{*default-encoding*}
3849is usually used for @code{.asd} files.
3850Currently, this defaults to @code{:default} for backwards compatibility,
3851and that means that you shouldn't rely on non-ASCII characters in a .asd file.
3852Since component (path)names are the only real data in these files,
3853and non-ASCII characters are not very portable for file names,
3854this isn't too much of an issue.
3855We still encourage you to use either plain ASCII or UTF-8
3856in @code{.asd} files,
3857as we intend to make @code{:utf-8} the default encoding in the future.
3858This might matter, for instance, in meta-data about author's names.
3861@section Miscellaneous Functions
3863These functions are exported by ASDF for your convenience.
3866@defun system-relative-pathname system name @Akey type
3868It's often handy to locate a file relative to some system.
3869The @code{system-relative-pathname} function meets this need.
3871It takes two mandatory arguments @var{system} and @var{name}
3872and a keyword argument @var{type}:
3873@var{system} is name of a system, whereas @var{name} and optionally @var{type}
3874specify a relative pathname, interpreted like a component pathname specifier
3875by @code{coerce-pathname}. @xref{The defsystem grammar,,Pathname specifiers}.
3877It returns a pathname built from the location of the system's
3878source directory and the relative pathname. For example:
3881> (asdf:system-relative-pathname 'cl-ppcre "")
3883@end lisp
3885@end defun
3887@defun system-source-directory system-designator
3889ASDF does not provide a turnkey solution for locating
3890data (or other miscellaneous) files
3891that are distributed together with the source code of a system.
3892Programmers can use @code{system-source-directory} to find such files.
3893Returns a pathname object.
3894The @var{system-designator} may be a string, symbol, or ASDF system object.
3895@end defun
3897@defun clear-system system-designator
3899It is sometimes useful to force recompilation of a previously loaded system.
3900In these cases, it may be useful to @code{(asdf:clear-system :foo)}
3901to remove the system from the table of currently loaded systems;
3902the next time the system @code{foo} or one that depends on it is re-loaded,
3903@code{foo} will then be loaded again.
3904Alternatively, you could touch @code{foo.asd} or
3905remove the corresponding fasls from the output file cache.
3906(It was once conceived that one should provide
3907a list of systems the recompilation of which to force
3908as the @code{:force} keyword argument to @code{load-system};
3909but this has never worked, and though the feature was fixed in ASDF 2.000,
3910it remains @code{cerror}'ed out as nobody ever used it.)
3912Note that this does not and cannot by itself undo the previous loading
3913of the system. Common Lisp has no provision for such an operation,
3914and its reliance on irreversible side-effects to global datastructures
3915makes such a thing impossible in the general case.
3916If the software being re-loaded is not conceived with hot upgrade in mind,
3917this re-loading may cause many errors, warnings or subtle silent problems,
3918as packages, generic function signatures, structures, types, macros, constants, etc.
3919are being redefined incompatibly.
3920It is up to the user to make sure that reloading is possible and has the desired effect.
3921In some cases, extreme measures such as recursively deleting packages,
3922unregistering symbols, defining methods on @code{update-instance-for-redefined-class}
3923and much more are necessary for reloading to happen smoothly.
3924ASDF itself goes through notable pains to make such a hot upgrade possible
3925with respect to its own code, and what it does is ridiculously complex;
3926look at the beginning of @file{asdf.lisp} to see what it does.
3927@end defun
3929@defun register-preloaded-system name @Arest keys
3930A system with name @var{name},
3931created by @code{make-instance} with extra keys @var{keys}
3932(e.g. @code{:version}),
3933is registered as @emph{preloaded}.
3934That is, its code has already been loaded into the current image,
3935and if at some point some other system @code{:depends-on} it yet no source code is found,
3936it is considered as already provided,
3937and ASDF will not raise a @code{missing-component} error.
3939This function is particularly useful if you distribute your code
3940as fasls with either @code{fasl-op} or @code{monolithic-fasl-op},
3941and want to register systems so that dependencies will work uniformly
3942whether you're using your software from source or from fasl.
3943@end defun
3945@defun run-shell-command control-string @Arest args
3947This function is obsolete and present only for the sake of backwards-compatibility:
3948``If it's not backwards, it's not compatible''. We @emph{strongly} discourage its use.
3949Its current behavior is only well-defined on Unix platforms
3950(which include MacOS X and cygwin). On Windows, anything goes.
3951The following documentation is only for the purpose of your migrating away from it
3952in a way that preserves semantics.
3954Instead we recommend the use @code{run-program}, described in the next section, and
3955available as part of ASDF since ASDF 3.
3957@code{run-shell-command} takes as arguments a format @code{control-string}
3958and arguments to be passed to @code{format} after this control-string
3959to produce a string.
3960This string is a command that will be evaluated with a POSIX shell if possible;
3961yet, on Windows, some implementations will use CMD.EXE,
3962while others (like SBCL) will make an attempt at invoking a POSIX shell
3963(and fail if it is not present).
3964@end defun
3966@section Some Utility Functions
3968The below functions are not exported by ASDF itself, but by UIOP, available since ASDF 3.
3969Some of them have precursors in ASDF 2, but we recommend
3970you rely on ASDF 3 for active developments.
3971UIOP provides many, many more utility functions, and we recommend
3972you read its README and sources for more information.
3975@defun parse-unix-namestring name @Akey type defaults dot-dot ensure-directory @AallowOtherKeys
3976Coerce NAME into a PATHNAME using standard Unix syntax.
3978Unix syntax is used whether or not the underlying system is Unix;
3979on such non-Unix systems it is only usable but for relative pathnames;
3980but especially to manipulate relative pathnames portably, it is of crucial
3981to possess a portable pathname syntax independent of the underlying OS.
3982This is what @code{parse-unix-namestring} provides, and why we use it in ASDF.
3984When given a @code{pathname} object, just return it untouched.
3985When given @code{nil}, just return @code{nil}.
3986When given a non-null @code{symbol}, first downcase its name and treat it as a string.
3987When given a @code{string}, portably decompose it into a pathname as below.
3989@code{#\/} separates directory components.
3991The last @code{#\/}-separated substring is interpreted as follows:
39921- If @var{type} is @code{:directory} or @var{ensure-directory} is true,
3993 the string is made the last directory component, and its @code{name} and @code{type} are @code{nil}.
3994 if the string is empty, it's the empty pathname with all slots @code{nil}.
39952- If @var{type} is @code{nil}, the substring is a file-namestring,
3996 and its @code{name} and @code{type} are separated by @code{split-name-type}.
39973- If @var{type} is a string, it is the given @code{type}, and the whole string is the @code{name}.
3999Directory components with an empty name the name @code{.} are removed.
4000Any directory named @code{..} is read as @var{dot-dot},
4001which must be one of @code{:back} or @code{:up} and defaults to @code{:back}.
4003@code{host}, @code{device} and @code{version} components are taken from @var{defaults},
4004which itself defaults to @code{*nil-pathname*}, also used if @var{defaults} is @code{nil}.
4005No host or device can be specified in the string itself,
4006which makes it unsuitable for absolute pathnames outside Unix.
4008For relative pathnames, these components (and hence the defaults) won't matter
4009if you use @code{merge-pathnames*} but will matter if you use @code{merge-pathnames},
4010which is an important reason to always use @code{merge-pathnames*}.
4012Arbitrary keys are accepted, and the parse result is passed to @code{ensure-pathname}
4013with those keys, removing @var{type}, @var{defaults} and @var{dot-dot}.
4014When you're manipulating pathnames that are supposed to make sense portably
4015even though the OS may not be Unixish, we recommend you use @code{:want-relative t}
4016to throw an error if the pathname is absolute
4017@end defun
4019@defun merge-pathnames* specified @Aoptional defaults
4021This function is a replacement for @code{merge-pathnames} that uses the host and device
4022from the @var{defaults} rather than the @var{specified} pathname when the latter
4023is a relative pathname. This allows ASDF and its users to create and use relative pathnames
4024without having to know beforehand what are the host and device
4025of the absolute pathnames they are relative to.
4027@end defun
4029@defun subpathname pathname subpath @Akey type
4031This function takes a @var{pathname} and a @var{subpath} and a @var{type}.
4032If @var{subpath} is already a @code{pathname} object (not namestring),
4033and is an absolute pathname at that, it is returned unchanged;
4034otherwise, @var{subpath} is turned into a relative pathname with given @var{type}
4035as per @code{parse-unix-namestring} with @code{:want-relative t :type }@var{type},
4036then it is merged with the @code{pathname-directory-pathname} of @var{pathname},
4037as per @code{merge-pathnames*}.
4039We strongly encourage the use of this function
4040for portably resolving relative pathnames in your code base.
4041@end defun
4043@defun subpathname* pathname subpath @Akey type
4045This function returns @code{nil} if the base @var{pathname} is @code{nil},
4046otherwise acts like @code{subpathname}.
4047@end defun
4049@defun run-program command @Akey ignore-error-status force-shell input output error-output
4050  if-input-does-not-exist if-output-exists if-error-output-exists
4051  element-type external-format @AallowOtherKeys
4053@code{run-program} takes a @var{command} argument that is either
4054a list of a program name or path and its arguments,
4055or a string to be executed by a shell.
4056It spawns the command, waits for it to return,
4057verifies that it exited cleanly (unless told not too below),
4058and optionally captures and processes its output.
4059It accepts many keyword arguments to configure its behavior.
4061@code{run-program} returns three values: the first for the output,
4062the second for the error-output, and the third for the return value.
4063(Beware that before ASDF, it didn't handle input or error-output,
4064and returned only one value,
4065the one for the output if any handler was specified, or else the exit code;
4066please upgrade ASDF, or at least UIOP, to rely on the new enhanced behavior.)
4068@var{output} is its most important argument;
4069it specifies how the output is captured and processed.
4070If it is @code{nil}, then the output is redirected to the null device,
4071that will discard it.
4072If it is @code{:interactive}, then it is inherited from the current process
4073(beware: this may be different from your @var{*standard-output*},
4074and under SLIME will be on your @code{*inferior-lisp*} buffer).
4075If it is @code{t}, output goes to your current @var{*standard-output*} stream.
4076Otherwise, @var{output} should be a value that is a suitable first argument to
4077@code{slurp-input-stream} (see below), or
4078a list of such a value and keyword arguments.
4079In this case, @code{run-program} will
4080create a temporary stream for the program output;
4081the program output, in that stream,
4082will be processed by a call to @code{slurp-input-stream},
4083using @var{output} as the first argument
4084(or if it's a list the first element of @var{output} and the rest as keywords).
4085The primary value resulting from that call
4086(or @code{nil} if no call was needed)
4087will be the first value returned by @code{run-program}.
4088E.g., using @code{:output :string}
4089will have it return the entire output stream as a string.
4090And using @code{:output '(:string :stripped t)}
4091will have it return the same string stripped of any ending newline.
4093@var{error-output} is similar to @var{output}, except that
4094the resulting value is returned as the second value of @code{run-program}.
4095@code{t} designates the @var{*error-output*}.
4096Also @code{:output} means redirecting the error output to the output stream,
4097in which case @code{nil} is returned.
4099@var{input} is similar to @var{output}, except that
4100@code{vomit-output-stream} is used, no value is returned,
4101and @code{t} designates the @var{*standard-input*}.
4103@code{element-type} and @code{external-format} are passed on
4104to your Lisp implementation, when applicable, for creation of the output stream.
4106One and only one of the stream slurping or vomiting may or may not happen
4107in parallel in parallel with the subprocess,
4108depending on options and implementation,
4109and with priority being given to output processing.
4110Other streams are completely produced or consumed
4111before or after the subprocess is spawned, using temporary files.
4113@code{force-shell} forces evaluation of the command through a shell,
4114even if it was passed as a list rather than a string.
4115If a shell is used, it is @file{/bin/sh} on Unix or @file{CMD.EXE} on Windows,
4116except on implementations that (erroneously, IMNSHO)
4117insist on consulting @code{$SHELL} like clisp.
4119@code{ignore-error-status} causes @code{run-program}
4120to not raise an error if the spawned program exits in error.
4121Following POSIX convention, an error is anything but
4122a normal exit with status code zero.
4123By default, an error of type @code{subprocess-error} is raised in this case.
4125@code{run-program} works on all platforms supported by ASDF, except Genera.
4126See the source code for more documentation.
4128@end defun
4130@defun slurp-input-stream processor input-stream @Akey
4132It's a generic function of two arguments, a target object and an input stream,
4133and accepting keyword arguments.
4134Predefined methods based on the target object are as follow:
4136If the object is a function, the function is called with the stream as argument.
4138If the object is a cons, its first element is applied to its rest appended by
4139a list of the input stream.
4141If the object is an output stream, the contents of the input stream are copied to it.
4142If the @var{linewise} keyword argument is provided, copying happens line by line,
4143and an optional @var{prefix} is printed before each line.
4144Otherwise, copying happen based on a buffer of size @var{buffer-size},
4145using the specified @var{element-type}.
4147If the object is @code{'string} or @code{:string}, the content is captured into a string.
4148Accepted keywords include the @var{element-type} and a flag @var{stripped},
4149which when true causes any single line ending to be removed as per @code{uiop:stripln}.
4151If the object is @code{:lines}, the content is captured as a list of strings,
4152one per line, without line ending. If the @var{count} keyword argument is provided,
4153it is a maximum count of lines to be read.
4155If the object is @code{:line}, the content is capture as with @code{:lines} above,
4156and then its sub-object is extracted with the @var{at} argument,
4157which defaults to @code{0}, extracting the first line.
4158A number will extract the corresponding line.
4159See the documentation for @code{uiop:access-at}.
4161If the object is @code{:forms}, the content is captured as a list of S-expressions,
4162as read by the Lisp reader.
4163If the @var{count} argument is provided,
4164it is a maximum count of lines to be read.
4165We recommend you control the syntax with such macro as
4168If the object is @code{:form}, the content is capture as with @code{:forms} above,
4169and then its sub-object is extracted with the @var{at} argument,
4170which defaults to @code{0}, extracting the first form.
4171A number will extract the corresponding form.
4172See the documentation for @code{uiop:access-at}.
4173We recommend you control the syntax with such macro as
4176@end defun
4179@node Getting the latest version, FAQ, Miscellaneous additional functionality, Top
4180@comment  node-name,  next,  previous,  up
4181@chapter Getting the latest version
4183Decide which version you want.
4184The @code{master} branch is where development happens;
4185its @code{HEAD} is usually OK, including the latest fixes and portability tweaks,
4186but an occasional regression may happen despite our (limited) test suite.
4188The @code{release} branch is what cautious people should be using;
4189it has usually been tested more, and releases are cut at a point
4190where there isn't any known unresolved issue.
4192You may get the ASDF source repository using git:
4193@kbd{git clone git://}
4195You will find the above referenced tags in this repository.
4196You can also browse the repository on
4199Discussion of ASDF development is conducted on the
4200mailing list
4205@node FAQ, Ongoing Work, Getting the latest version, Top
4206@comment  node-name,  next,  previous,  up
4207@chapter FAQ
4210* Where do I report a bug?::
4211* What has changed between ASDF 1 and ASDF 2?::
4212* Issues with installing the proper version of ASDF::
4213* Issues with configuring ASDF::
4214* Issues with using and extending ASDF to define systems::
4215* ASDF development FAQs::
4216@end menu
4218@node Where do I report a bug?, What has changed between ASDF 1 and ASDF 2?, FAQ, FAQ
4219@section  ``Where do I report a bug?''
4221ASDF bugs are tracked on launchpad: @url{}.
4223If you're unsure about whether something is a bug, or for general discussion,
4224use the @url{,asdf-devel mailing list}
4227@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
4228@section ``What has changed between ASDF 1 and ASDF 2?''
4231* What are ASDF 1 2 3?::
4232* ASDF can portably name files in subdirectories::
4233* Output translations::
4234* Source Registry Configuration::
4235* Usual operations are made easier to the user::
4236* Many bugs have been fixed::
4237* ASDF itself is versioned::
4238* ASDF can be upgraded::
4239* Decoupled release cycle::
4240* Pitfalls of the transition to ASDF 2::
4241@end menu
4243@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?
4244@subsection What are ASDF 1, ASDF 2 and ASDF 3?
4246ASDF 1 refers to any release earlier than 1.369 or so (from August 2001 to October 2009),
4247and to any development revision earlier than 2.000 (May 2010).
4248If your copy of ASDF doesn't even contain version information, it's an old ASDF 1.
4249Revisions between 1.656 and 1.728 may count as development releases for ASDF 2.
4251ASDF 2 refers to releases from 2.000 (May 31st 2010) to 2.26 (Oct 30 2012),
4252and any development revision newer than ASDF 1 and older than 2.27 (Feb 1 2013).
4254ASDF 3 refers to releases from 2.27 (Feb 1 2013) to 2.33 and 3.0.0 onward (May 15 2013).
42552.27 to 2.33 count as pre-releases to ASDF 3.
4257All releases of ASDF
4258push @code{:asdf} onto @code{*features*}.
4259Releases starting with ASDF 2
4260 push @code{:asdf2} onto @code{*features*}.
4261Releases starting with ASDF 3 (including 2.27 and later pre-releases)
4262push @code{:asdf3} onto @code{*features*}.
4263Furthermore, releases starting with ASDF 3.1 (March 2014),
4264though they count as ASDF 3, includes enough progress that they
4265push @code{:asdf3.1} onto @code{*features*}.
4266You may depend on the presence or absence of these features
4267to write code that takes advantage of recent ASDF functionality
4268but still works on older versions, or at least detects the old version and signals an error.
4270Additionally, all releases starting with ASDF 2
4271define a function @code{(asdf:asdf-version)} you may use to query the version.
4272All releases starting with 2.013 display the version number prominently
4273on the second line of the @file{asdf.lisp} source file.
4275If you are experiencing problems or limitations of any sort with ASDF 1 or ASDF 2,
4276we recommend that you should upgrade to the latest release, be it ASDF 3 or other.
4279@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?
4280@subsection ASDF can portably name files in subdirectories
4282Common Lisp namestrings are not portable,
4283except maybe for logical pathnamestrings,
4284that themselves have various limitations and require a lot of setup
4285that is itself ultimately non-portable.
4287In ASDF 1, the only portable ways to refer to pathnames inside systems and components
4288were very awkward, using @code{#.(make-pathname ...)} and
4289@code{#.(merge-pathnames ...)}.
4290Even the above were themselves were inadequate in the general case
4291due to host and device issues, unless horribly complex patterns were used.
4292Plenty of simple cases that looked portable actually weren't,
4293leading to much confusion and greavance.
4295ASDF 2 implements its own portable syntax for strings as pathname specifiers.
4296Naming files within a system definition becomes easy and portable again.
4297@xref{Miscellaneous additional functionality,system-relative-pathname},
4301On the other hand, there are places where systems used to accept namestrings
4302where you must now use an explicit pathname object:
4303@code{(defsystem ... :pathname "LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
4304must now be written with the @code{#p} syntax:
4305@code{(defsystem ... :pathname #p"LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
4307@xref{The defsystem grammar,,Pathname specifiers}.
4310@node Output translations, Source Registry Configuration, ASDF can portably name files in subdirectories, What has changed between ASDF 1 and ASDF 2?
4311@subsection Output translations
4313A popular feature added to ASDF was output pathname translation:
4314@code{asdf-binary-locations}, @code{common-lisp-controller},
4315@code{cl-launch} and other hacks were all implementing it in ways
4316both mutually incompatible and difficult to configure.
4318Output pathname translation is essential to share
4319source directories of portable systems across multiple implementations
4320or variants thereof,
4321or source directories of shared installations of systems across multiple users,
4322or combinations of the above.
4324In ASDF 2, a standard mechanism is provided for that,
4326with sensible defaults, adequate configuration languages,
4327a coherent set of configuration files and hooks,
4328and support for non-Unix platforms.
4330@xref{Controlling where ASDF saves compiled files}.
4332@node Source Registry Configuration, Usual operations are made easier to the user, Output translations, What has changed between ASDF 1 and ASDF 2?
4333@subsection Source Registry Configuration
4335Configuring ASDF used to require special magic
4336to be applied just at the right moment,
4337between the moment ASDF is loaded and the moment it is used,
4338in a way that is specific to the user,
4339the implementation he is using and the application he is building.
4341This made for awkward configuration files and startup scripts
4342that could not be shared between users, managed by administrators
4343or packaged by distributions.
4345ASDF 2 provides a well-documented way to configure ASDF,
4346with sensible defaults, adequate configuration languages,
4347and a coherent set of configuration files and hooks.
4349We believe it's a vast improvement because it decouples
4350application distribution from library distribution.
4351The application writer can avoid thinking where the libraries are,
4352and the library distributor (dpkg, clbuild, advanced user, etc.)
4353can configure them once and for every application.
4354Yet settings can be easily overridden where needed,
4355so whoever needs control has exactly as much as required.
4357At the same time, ASDF 2 remains compatible
4358with the old magic you may have in your build scripts
4359(using @code{*central-registry*} and
4361to tailor the ASDF configuration to your build automation needs,
4362and also allows for new magic, simpler and more powerful magic.
4364@xref{Controlling where ASDF searches for systems}.
4367@node Usual operations are made easier to the user, Many bugs have been fixed, Source Registry Configuration, What has changed between ASDF 1 and ASDF 2?
4368@subsection Usual operations are made easier to the user
4370In ASDF 1, you had to use the awkward syntax
4371@code{(asdf:oos 'asdf:load-op :foo)}
4372to load a system,
4373and similarly for @code{compile-op}, @code{test-op}.
4375In ASDF 2, you can use shortcuts for the usual operations:
4376@code{(asdf:load-system :foo)}, and
4377similarly for @code{compile-system}, @code{test-system}.
4380@node Many bugs have been fixed, ASDF itself is versioned, Usual operations are made easier to the user, What has changed between ASDF 1 and ASDF 2?
4381@subsection Many bugs have been fixed
4383The following issues and many others have been fixed:
4387The infamous TRAVERSE function has been revamped completely
4388between ASDF 1 and ASDF 2, with many bugs squashed.
4389In particular, dependencies were not correctly propagated
4390across modules but now are.
4391It has been completely rewritten many times over
4392between ASDF 2.000 and ASDF 3,
4393with fundamental issues in the original model being fixed.
4394Timestamps were not propagated at all, and now are.
4395The internal model of how actions depend on each other
4396is now both consistent and complete.
4397The @code{:version} and
4398the @code{:force (system1 .. systemN)} feature have been fixed.
4401Performance has been notably improved for large systems
4402(say with thousands of components) by using
4403hash-tables instead of linear search,
4404and linear-time list accumulation
4405instead of quadratic-time recursive appends.
4408Many features used to not be portable,
4409especially where pathnames were involved.
4410Windows support was notably quirky because of such non-portability.
4413The internal test suite used to massively fail on many implementations.
4414While still incomplete, it now fully passes
4415on all implementations supported by the test suite,
4416except for GCL (due to GCL bugs).
4419Support was lacking for some implementations.
4420ABCL and GCL were notably wholly broken.
4421ECL extensions were not integrated with ASDF release.
4424The documentation was grossly out of date.
4426@end itemize
4429@node ASDF itself is versioned, ASDF can be upgraded, Many bugs have been fixed, What has changed between ASDF 1 and ASDF 2?
4430@subsection ASDF itself is versioned
4432Between new features, old bugs fixed, and new bugs introduced,
4433there were various releases of ASDF in the wild,
4434and no simple way to check which release had which feature set.
4435People using or writing systems had to either make worst-case assumptions
4436as to what features were available and worked,
4437or take great pains to have the correct version of ASDF installed.
4439With ASDF 2, we provide a new stable set of working features
4440that everyone can rely on from now on.
4441Use @code{#+asdf2} to detect presence of ASDF 2,
4442@code{(asdf:version-satisfies (asdf:asdf-version) "2.345.67")}
4443to check the availability of a version no earlier than required.
4446@node ASDF can be upgraded, Decoupled release cycle, ASDF itself is versioned, What has changed between ASDF 1 and ASDF 2?
4447@subsection ASDF can be upgraded
4449When an old version of ASDF was loaded,
4450it was very hard to upgrade ASDF in your current image
4451without breaking everything.
4452Instead you had to exit the Lisp process and
4453somehow arrange to start a new one from a simpler image.
4454Something that can't be done from within Lisp,
4455making automation of it difficult,
4456which compounded with difficulty in configuration,
4457made the task quite hard.
4458Yet as we saw before, the task would have been required
4459to not have to live with the worst case or non-portable
4460subset of ASDF features.
4462With ASDF 2, it is easy to upgrade
4463from ASDF 2 to later versions from within Lisp,
4464and not too hard to upgrade from ASDF 1 to ASDF 2 from within Lisp.
4465We support hot upgrade of ASDF and any breakage is a bug
4466that we will do our best to fix.
4467There are still limitations on upgrade, though,
4468most notably the fact that after you upgrade ASDF,
4469you must also reload or upgrade all ASDF extensions.
4471@node Decoupled release cycle, Pitfalls of the transition to ASDF 2, ASDF can be upgraded, What has changed between ASDF 1 and ASDF 2?
4472@subsection Decoupled release cycle
4474When vendors were releasing their Lisp implementations with ASDF,
4475they had to basically never change version
4476because neither upgrade nor downgrade was possible
4477without breaking something for someone,
4478and no obvious upgrade path was visible and recommendable.
4480With ASDF 2, upgrade is possible, easy and can be recommended.
4481This means that vendors can safely ship a recent version of ASDF,
4482confident that if a user isn't fully satisfied,
4483he can easily upgrade ASDF and deal
4484with a supported recent version of it.
4485This means that release cycles will be causally decoupled,
4486the practical consequence of which will mean faster convergence
4487towards the latest version for everyone.
4490@node Pitfalls of the transition to ASDF 2,  , Decoupled release cycle, What has changed between ASDF 1 and ASDF 2?
4491@subsection Pitfalls of the transition to ASDF 2
4493The main pitfalls in upgrading to ASDF 2 seem to be related
4494to the output translation mechanism.
4499Output translations is enabled by default. This may surprise some users,
4500most of them in pleasant way (we hope), a few of them in an unpleasant way.
4501It is trivial to disable output translations.
4502@xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
4505Some systems in the large have been known
4506not to play well with output translations.
4507They were relatively easy to fix.
4508Once again, it is also easy to disable output translations,
4509or to override its configuration.
4512The new ASDF output translations are incompatible with ASDF-Binary-Locations.
4513They replace A-B-L, and there is compatibility mode to emulate
4514your previous A-B-L configuration.
4515See @code{enable-asdf-binary-locations-compatibility} in
4516@pxref{Controlling where ASDF saves compiled files,,Backward Compatibility}.
4517But thou shalt not load ABL on top of ASDF 2.
4519@end itemize
4521Other issues include the following:
4526ASDF pathname designators are now specified
4527in places where they were unspecified,
4528and a few small adjustments have to be made to some non-portable defsystems.
4529Notably, in the @code{:pathname} argument
4530to a @code{defsystem} and its components,
4531a logical pathname (or implementation-dependent hierarchical pathname)
4532must now be specified with @code{#p} syntax
4533where the namestring might have previously sufficed;
4534moreover when evaluation is desired @code{#.} must be used,
4535where it wasn't necessary in the toplevel @code{:pathname} argument
4536(but necessary in other @code{:pathname} arguments).
4539There is a slight performance bug, notably on SBCL,
4540when initially searching for @file{asd} files,
4541the implicit @code{(directory "/configured/path/**/*.asd")}
4542for every configured path @code{(:tree "/configured/path/")}
4543in your @code{source-registry} configuration can cause a slight pause.
4544Try to @code{(time (asdf:initialize-source-registry))}
4545to see how bad it is or isn't on your system.
4546If you insist on not having this pause,
4547you can avoid the pause by overriding the default source-registry configuration
4548and not use any deep @code{:tree} entry but only @code{:directory} entries
4549or shallow @code{:tree} entries.
4550Or you can fix your implementation to not be quite that slow
4551when recursing through directories.
4552@emph{Update}: This performance bug fixed the hard way in 2.010.
4555On Windows, only LispWorks supports proper default configuration pathnames
4556based on the Windows registry.
4557Other implementations make do with environment variables,
4558that you may have to define yourself
4559if you're using an older version of Windows.
4560Windows support is somewhat less tested than Unix support.
4561Please help report and fix bugs.
4562@emph{Update}: As of ASDF 2.21, all implementations
4563should now use the same proper default configuration pathnames
4564and they should actually work, though they haven't all been tested.
4567The mechanism by which one customizes a system so that Lisp files
4568may use a different extension from the default @file{.lisp} has changed.
4569Previously, the pathname for a component
4570was lazily computed when operating on a system,
4571and you would
4572@code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
4573  (declare (ignorable component system)) "lis")}.
4574Now, the pathname for a component is eagerly computed when defining the system,
4575and instead you will @code{(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))}
4576and use @code{:default-component-class cl-source-file.lis}
4577as argument to @code{defsystem},
4578as detailed in a @pxref{FAQ,How do I create a system definition where all the source files have a .cl extension?} below.
4580@findex source-file-type
4583@end itemize
4586@node Issues with installing the proper version of ASDF, Issues with configuring ASDF, What has changed between ASDF 1 and ASDF 2?, FAQ
4587@section Issues with installing the proper version of ASDF
4590* My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
4591* I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::
4592@end menu
4594@node My Common Lisp implementation comes with an outdated version of ASDF. What to do?, I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?, Issues with installing the proper version of ASDF, Issues with installing the proper version of ASDF
4595@subsection ``My Common Lisp implementation comes with an outdated version of ASDF. What to do?''
4597We recommend you upgrade ASDF.
4598@xref{Loading ASDF,,Upgrading ASDF}.
4600If this does not work, it is a bug, and you should report it.
4601@xref{FAQ, report-bugs, Where do I report a bug}.
4602In the meantime, you can load @file{asdf.lisp} directly.
4603@xref{Loading ASDF,Loading an otherwise installed ASDF}.
4606@node I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?,  , My Common Lisp implementation comes with an outdated version of ASDF. What to do?, Issues with installing the proper version of ASDF
4607@subsection ``I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?''
4609Since ASDF 2,
4610it should always be a good time to upgrade to a recent version of ASDF.
4611You may consult with the maintainer for which specific version they recommend,
4612but the latest @code{release} should be correct.
4613Though we do try to test ASDF releases against all implementations that we can,
4614we may not be testing against all variants of your implementation,
4615and we may not be running enough tests;
4616we trust you to thoroughly test it with your own implementation
4617before you release it.
4618If there are any issues with the current release,
4619it's a bug that you should report upstream and that we will fix ASAP.
4621As to how to include ASDF, we recommend the following:
4625If ASDF isn't loaded yet, then @code{(require "asdf")}
4626should load the version of ASDF that is bundled with your system.
4627If possible so should @code{(require "ASDF")}.
4628You may have it load some other version configured by the user,
4629if you allow such configuration.
4632If your system provides a mechanism to hook into @code{CL:REQUIRE},
4633then it would be nice to add ASDF to this hook the same way that
4635Please send us appropriate code to this end.
4638You may, like SBCL, have ASDF be implicitly used to require systems
4639that are bundled with your Lisp distribution.
4640If you do have a few magic systems that come with your implementation
4641in a precompiled way such that one should only use the binary version
4642that goes with your distribution, like SBCL does,
4643then you should add them in the beginning of @code{wrapping-source-registry}.
4646If you have magic systems as above, like SBCL does,
4647then we explicitly ask you to @emph{NOT} distribute
4648@file{asdf.asd} as part of those magic systems.
4649You should still include the file @file{asdf.lisp} in your source distribution
4650and precompile it in your binary distribution,
4651but @file{asdf.asd} if included at all,
4652should be secluded from the magic systems,
4653in a separate file hierarchy.
4654Alternatively, you may provide the system
4655after renaming it and its @file{.asd} file to e.g.
4656@code{asdf-ecl} and @file{asdf-ecl.asd}, or
4657@code{sb-asdf} and @file{sb-asdf.asd}.
4658Indeed, if you made @file{asdf.asd} a magic system,
4659then users would no longer be able to upgrade ASDF using ASDF itself
4660to some version of their preference that
4661they maintain independently from your Lisp distribution.
4664If you do not have any such magic systems, or have other non-magic systems
4665that you want to bundle with your implementation,
4666then you may add them to the @code{wrapping-source-registry},
4667and you are welcome to include @file{asdf.asd} amongst them.
4668Non-magic systems should be at the back of the @code{wrapping-source-registry}
4669while magic systems are at the front.
4672Since ASDF 3, the library UIOP comes transcluded in ASDF.
4673But if you want to be nice to users who care for UIOP but not for ASDF,
4674you may package UIOP separately,
4675so that one may @code{(require "uiop")} and not load ASDF,
4676or one may @code{(require "asdf")}
4677which would implicitly require and load the former.
4680Please send us upstream any patches you make to ASDF itself,
4681so we can merge them back in for the benefit of your users
4682when they upgrade to the upstream version.
4684@end itemize
4688@node Issues with configuring ASDF, Issues with using and extending ASDF to define systems, Issues with installing the proper version of ASDF, FAQ
4689@section Issues with configuring ASDF
4692* How can I customize where fasl files are stored?::
4693* How can I wholly disable the compiler output cache?::
4694@end menu
4696@node How can I customize where fasl files are stored?, How can I wholly disable the compiler output cache?, Issues with configuring ASDF, Issues with configuring ASDF
4697@subsection ``How can I customize where fasl files are stored?''
4699@xref{Controlling where ASDF saves compiled files}.
4701Note that in the past there was an add-on to ASDF called
4702@code{ASDF-binary-locations}, developed by Gary King.
4703That add-on has been merged into ASDF proper,
4704then superseded by the @code{asdf-output-translations} facility.
4706Note that use of @code{asdf-output-translations}
4707can interfere with one aspect of your systems
4708--- if your system uses @code{*load-truename*} to find files
4709(e.g., if you have some data files stored with your program),
4710then the relocation that this ASDF customization performs
4711is likely to interfere.
4712Use @code{asdf:system-relative-pathname} to locate a file
4713in the source directory of some system, and
4714use @code{asdf:apply-output-translations} to locate a file
4715whose pathname has been translated by the facility.
4717@node How can I wholly disable the compiler output cache?,  , How can I customize where fasl files are stored?, Issues with configuring ASDF
4718@subsection ``How can I wholly disable the compiler output cache?''
4720To permanently disable the compiler output cache
4721for all future runs of ASDF, you can:
4724mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/
4725echo ':disable-cache' > ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
4726@end example
4728This assumes that you didn't otherwise configure the ASDF files
4729(if you did, edit them again),
4730and don't somehow override the configuration at runtime
4731with a shell variable (see below) or some other runtime command
4732(e.g. some call to @code{asdf:initialize-output-translations}).
4734To disable the compiler output cache in Lisp processes
4735run by your current shell, try (assuming @code{bash} or @code{zsh})
4736(on Unix and cygwin only):
4740@end example
4742To disable the compiler output cache just in the current Lisp process,
4743use (after loading ASDF but before using it):
4747@end example
4749@node Issues with using and extending ASDF to define systems, ASDF development FAQs, Issues with configuring ASDF, FAQ
4750@section Issues with using and extending ASDF to define systems
4753* How can I cater for unit-testing in my system?::
4754* How can I cater for documentation generation in my system?::
4755* How can I maintain non-Lisp (e.g. C) source files?::
4756* I want to put my module's files at the top level.  How do I do this?::
4757* How do I create a system definition where all the source files have a .cl extension?::
4758@end menu
4760@node How can I cater for unit-testing in my system?, How can I cater for documentation generation in my system?, Issues with using and extending ASDF to define systems, Issues with using and extending ASDF to define systems
4761@subsection ``How can I cater for unit-testing in my system?''
4763ASDF provides a predefined test operation, @code{test-op}.
4764@xref{Predefined operations of ASDF, test-op}.
4765The test operation, however, is largely left to the system definer to specify.
4766@code{test-op} has been
4767a topic of considerable discussion on the
4768@url{,asdf-devel mailing list},
4769and on the
4770@url{,launchpad bug-tracker}.
4772Here are some guidelines:
4776For a given system, @var{foo}, you will want to define a corresponding
4777test system, such as @var{foo-test}.  The reason that you will want this
4778separate system is that ASDF does not out of the box supply components
4779that are conditionally loaded.  So if you want to have source files
4780(with the test definitions) that will not be loaded except when testing,
4781they should be put elsewhere.
4784The @var{foo-test} system can be defined in an asd file of its own or
4785together with @var{foo}.  An aesthetic preference against cluttering up
4786the filesystem with extra asd files should be balanced against the
4787question of whether one might want to directly load @var{foo-test}.
4788Typically one would not want to do this except in early stages of
4792Record that testing is implemented by @var{foo-test}.  For example:
4794(defsystem @var{foo}
4795   :in-order-to ((test-op (test-op @var{foo-test})))
4796   ....)
4798(defsystem @var{foo-test}
4799   :depends-on (@var{foo} @var{my-test-library} ...)
4800   ....)
4801@end example
4802@end itemize
4804This procedure will allow you to support users who do not wish to
4805install your test framework.
4807One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
4808does not return a value.  So in current versions of ASDF there is no
4809reliable programmatic means of determining whether or not a set of tests
4810has passed, or which tests have failed.  The user must simply read the
4811console output.  This limitation has been the subject of much
4814@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
4815@subsection ``How can I cater for documentation generation in my system?''
4817Various ASDF extensions provide some kind of @code{doc-op} operation.
4818See also @url{}.
4821@node How can I maintain non-Lisp (e.g. C) source files?, I want to put my module's files at the top level.  How do I do this?, How can I cater for documentation generation in my system?, Issues with using and extending ASDF to define systems
4822@subsection ``How can I maintain non-Lisp (e.g. C) source files?''
4824See @code{cffi}'s @code{cffi-grovel}.
4829@node I want to put my module's files at the top level.  How do I do this?, How do I create a system definition where all the source files have a .cl extension?, How can I maintain non-Lisp (e.g. C) source files?, Issues with using and extending ASDF to define systems
4830@subsection ``I want to put my module's files at the top level.  How do I do this?''
4832By default, the files contained in an asdf module go
4833in a subdirectory with the same name as the module.
4834However, this can be overridden by adding a @code{:pathname ""} argument
4835to the module description.
4836For example, here is how it could be done
4837in the spatial-trees ASDF system definition for ASDF 2:
4840(asdf:defsystem :spatial-trees
4841  :components
4842  ((:module base
4843            :pathname ""
4844            :components
4845            ((:file "package")
4846             (:file "basedefs" :depends-on ("package"))
4847             (:file "rectangles" :depends-on ("package"))))
4848   (:module tree-impls
4849            :depends-on (base)
4850            :pathname ""
4851            :components
4852            ((:file "r-trees")
4853             (:file "greene-trees" :depends-on ("r-trees"))
4854             (:file "rstar-trees" :depends-on ("r-trees"))
4855             (:file "rplus-trees" :depends-on ("r-trees"))
4856             (:file "x-trees" :depends-on ("r-trees" "rstar-trees"))))
4857   (:module viz
4858            :depends-on (base)
4859            :pathname ""
4860            :components
4861            ((:static-file "spatial-tree-viz.lisp")))
4862   (:module tests
4863            :depends-on (base)
4864            :pathname ""
4865            :components
4866            ((:static-file "spatial-tree-test.lisp")))
4867   (:static-file "LICENCE")
4868   (:static-file "TODO")))
4869@end example
4871All of the files in the @code{tree-impls} module are at the top level,
4872instead of in a @file{tree-impls/} subdirectory.
4874Note that the argument to @code{:pathname} can be either a pathname object or a string.
4875A pathname object can be constructed with the @file{#p"foo/bar/"} syntax,
4876but this is discouraged because the results of parsing a namestring are not portable.
4877A pathname can only be portably constructed with such syntax as
4878@code{#.(make-pathname :directory '(:relative "foo" "bar"))},
4879and similarly the current directory can only be portably specified as
4880@code{#.(make-pathname :directory '(:relative))}.
4881However, as of ASDF 2, you can portably use a string to denote a pathname.
4882The string will be parsed as a @code{/}-separated path from the current directory,
4883such that the empty string @code{""} denotes the current directory, and
4884@code{"foo/bar"} (no trailing @code{/} required in the case of modules)
4885portably denotes the same subdirectory as above.
4886When files are specified, the last @code{/}-separated component is interpreted
4887either as the name component of a pathname
4888(if the component class specifies a pathname type),
4889or as a name component plus optional dot-separated type component
4890(if the component class doesn't specifies a pathname type).
4892@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
4893@subsection How do I create a system definition where all the source files have a .cl extension?
4895Starting with ASDF 2.014.14, you may just pass
4896the builtin class @code{} as
4897the @code{:default-component-class} argument to @code{defsystem}:
4900(defsystem my-cl-system
4901  :default-component-class
4902  ...)
4903@end lisp
4905Another builtin class @code{cl-source-file.lsp} is offered
4906for files ending in @file{.lsp}.
4908If you want to use a different extension
4909for which ASDF doesn't provide builtin support,
4910or want to support versions of ASDF
4911earlier than 2.014.14 (but later than 2.000),
4912you can define a class as follows:
4915;; Prologue: make sure we're using a sane package.
4916(defpackage :my-asdf-extension
4917   (:use :asdf :common-lisp)
4918   (:export #:cl-source-file.lis))
4919(in-package :my-asdf-extension)
4921(defclass cl-source-file.lis (cl-source-file)
4922  ((type :initform "lis")))
4923@end lisp
4925Then you can use it as follows:
4927(defsystem my-cl-system
4928  :default-component-class my-asdf-extension:cl-source-file.lis
4929  ...)
4930@end lisp
4932Of course, if you're in the same package, e.g. in the same file,
4933you won't need to use the package qualifier before @code{cl-source-file.lis}.
4934Actually, if all you're doing is defining this class
4935and using it in the same file without other fancy definitions,
4936you might skip package complications:
4939(in-package :asdf)
4940(defclass cl-source-file.lis (cl-source-file)
4941   ((type :initform "lis")))
4942(defsystem my-cl-system
4943  :default-component-class cl-source-file.lis
4944  ...)
4945@end lisp
4947It is possible to achieve the same effect
4948in a way that supports both ASDF 1 and ASDF 2,
4949but really, friends don't let friends use ASDF 1.
4950Please upgrade to ASDF 3.
4951In short, though: do same as above, but
4952@emph{before} you use the class in a @code{defsystem},
4953you also define the following method:
4956(defmethod source-file-type ((f cl-source-file.lis) (s system))
4957  (declare (ignorable f s))
4958  "lis")
4959@end lisp
4961@node ASDF development FAQs,  , Issues with using and extending ASDF to define systems, FAQ
4962@section ASDF development FAQs
4965* How do run the tests interactively in a REPL?::
4966@end menu
4968@node How do run the tests interactively in a REPL?,  , ASDF development FAQs, ASDF development FAQs
4969@subsection How do run the tests interactively in a REPL?
4971This not-so-frequently asked question is primarily for ASDF developers,
4972but those who encounter an unexpected error in some test may be
4973interested, too.
4975Here's the procedure for experimenting with tests in a REPL:
4977(load "script-support.lisp")
4978(in-package :asdf-test)
4979(compile-load-asdf) ; there are a number of other functions to load ASDF
4980;; experiment with test code from a .script file...
4981@end example
4984@comment FIXME: Add a FAQ about how to use a new system class...
4986@comment  node-name,  next,  previous,  up
4987@node  Ongoing Work, Bibliography, FAQ, Top
4988@unnumbered Ongoing Work
4989For an active list of things to be done,
4990see the @file{TODO} file in the source repository.
4992Also, bugs that are now tracked on launchpad:
4995@node Bibliography, Concept Index, Ongoing Work, Top
4996@unnumbered Bibliography
4999@item Zach Beane:
5000  ``Quicklisp'', 2011.
5001  The Quicklisp blog and Xach's livejournal contain information on Quicklisp.
5002  @url{}
5003  @url{}
5004@item Francois-Rene Rideau and Robert Goldman:
5005  ``Evolving ASDF: More Cooperation, Less Coordination'', 2010.
5006  This article describes the main issues solved by ASDF 2.
5007  @url{}
5008  @url{}
5009@item Francois-Rene Rideau and Spencer Brody:
5010  ``XCVB: an eXtensible Component Verifier and Builder for Common Lisp'', 2009.
5011  This article describes XCVB, a proposed competitor for ASDF,
5012  many ideas of which have been incorporated into ASDF 2 and 3,
5013  though many other of which still haven't.
5014  @url{}
5015@item Dan Barlow: ``ASDF Manual'', 2004
5016  Older versions of this document from the days of ASDF 1;
5017  they include ideas laid down by Dan Barlow,
5018  and comparisons with older defsystems (@code{mk-defsystem})
5019  and defsystem (@code{defsystem-4}, kmp's Memo 801).
5020@item Marco Antoniotti and Peter Van Eynde:
5021 ``@code{DEFSYSTEM}: A @code{make} for Common Lisp, A Thoughtful Re-Implementation of an Old Idea'', 2002.
5022  The @file{defsystem-4} proposal available in the CLOCC repository.
5023@item Mark Kantrovitz: ``Defsystem: A Portable Make Facility for Common Lisp'', 1990.
5024  The classic @file{mk-defsystem}, later variants of which
5025  are available in the CLOCC repository as @code{defsystem-3.x}.
5026@item Richard Elliot Robbins:
5027  ``BUILD: A Tool for Maintaining Consistency in Modular Systems'', MIT AI TR 874, 1985.
5028  @url{}
5029@item Kent M. Pitman (kmp): ``The Description of Large Systems'', MIT AI Memo 801, 1984.
5030  Available in updated-for-CL form on the web at
5031  @url{}
5032@item Dan Weinreb and David Moon:
5033  ``Lisp Machine Manual'', MIT, 1981.
5034  The famous CHINE NUAL describes one of the earliest variants of DEFSYSTEM.
5035  @url{}
5036@item Drew McDermott: ``A Framework for Maintaining the Coherence of a
5037  Running Lisp,'' International Lisp Conference, 2005, available in
5038  pre-print form at @url{}.
5039@end itemize
5042@node Concept Index, Function and Class Index, Bibliography, Top
5043@unnumbered Concept Index
5045@printindex cp
5047@node Function and Class Index, Variable Index, Concept Index, Top
5048@unnumbered Function and Class Index
5050@printindex fn
5052@node Variable Index,  , Function and Class Index, Top
5053@unnumbered Variable Index
5055@printindex vr
Note: See TracBrowser for help on using the repository browser.