1 \input texinfo @c -*- texinfo -*-
8 @c We use @&key, etc to escape & from TeX in lambda lists --
9 @c so we need to define them for info as well.
10 @macro AallowOtherKeys
27 @dircategory Software development
29 * asdf: (asdf). Another System Definition Facility (for Common Lisp)
33 This manual describes ASDF, a system definition facility
34 for Common Lisp programs and libraries.
36 You can find the latest version of this manual at
37 @url{https://common-lisp.net/project/asdf/asdf.html}.
39 ASDF Copyright @copyright{} 2001-2016 Daniel Barlow and contributors.
41 This manual Copyright @copyright{} 2001-2016 Daniel Barlow and contributors.
43 This manual revised @copyright{} 2009-2016 Robert P. Goldman and Francois-Rene Rideau.
45 Permission is hereby granted, free of charge, to any person obtaining
46 a copy of this software and associated documentation files (the
47 ``Software''), to deal in the Software without restriction, including
48 without limitation the rights to use, copy, modify, merge, publish,
49 distribute, sublicense, and/or sell copies of the Software, and to
50 permit persons to whom the Software is furnished to do so, subject to
51 the following conditions:
53 The above copyright notice and this permission notice shall be
54 included in all copies or substantial portions of the Software.
56 THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
57 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
58 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
59 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
60 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
61 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
62 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
67 @title ASDF: Another System Definition Facility
68 @subtitle Manual for Version 3.3.1
69 @c The following two commands start the copyright page.
71 @vskip 0pt plus 1filll
75 @c Output the table of contents at the beginning.
78 @c -------------------
82 @node Top, Introduction, (dir), (dir)
83 @top ASDF: Another System Definition Facility
85 Manual for Version 3.3.1
93 * Quick start summary::
97 * Defining systems with defsystem::
98 * The object model of ASDF::
99 * Controlling where ASDF searches for systems::
100 * Controlling where ASDF saves compiled files::
102 * Miscellaneous additional functionality::
103 * Getting the latest version::
108 * Function and Class Index::
109 * Variable Index:: @c @detailmenu
113 --- The Detailed Node Listing ---
117 * Loading a pre-installed ASDF::
118 * Checking whether ASDF is loaded::
120 * Replacing your implementation's ASDF::
121 * Loading ASDF from source::
125 * Configuring ASDF to find your systems::
126 * Configuring ASDF to find your systems --- old style::
127 * Configuring where ASDF stores object files::
128 * Resetting the ASDF configuration::
133 * Convenience Functions::
136 Defining systems with defsystem
138 * The defsystem form::
139 * A more involved example::
140 * The defsystem grammar::
141 * Other code in .asd files::
142 * The package-inferred-system extension::
144 The Object model of ASDF
153 * Predefined operations of ASDF::
154 * Creating new operations::
158 * Common attributes of components::
159 * Pre-defined subclasses of component::
160 * Creating new component types::
164 * Pre-defined subclasses of component::
165 * Creating new component types::
167 Controlling where ASDF searches for systems
170 * Truenames and other dangers::
171 * XDG base directory::
172 * Backward Compatibility::
173 * Configuration DSL::
174 * Configuration Directories::
175 * Shell-friendly syntax for configuration::
178 * Configuration API::
183 * Credits for the source-registry::
185 Configuration Directories
187 * The here directive::
191 * *source-registry-parameter* variable::
192 * Information about system dependencies::
194 Controlling where ASDF saves compiled files
196 * Output Configurations::
197 * Output Backward Compatibility::
198 * Output Configuration DSL::
199 * Output Configuration Directories::
200 * Output Shell-friendly syntax for configuration::
201 * Semantics of Output Translations::
202 * Output Caching Results::
203 * Output location API::
204 * Credits for output translations::
206 Miscellaneous additional functionality
208 * Controlling file compilation::
209 * Controlling source file character encoding::
210 * Miscellaneous Functions::
211 * Some Utility Functions::
215 * Where do I report a bug?::
217 * What has changed between ASDF 1 ASDF 2 and ASDF 3?::
218 * Issues with installing the proper version of ASDF::
219 * Issues with configuring ASDF::
220 * Issues with using and extending ASDF to define systems::
221 * ASDF development FAQs::
223 ``What has changed between ASDF 1, ASDF 2, and ASDF 3?''
225 * What are ASDF 1 2 3?::
226 * How do I detect the ASDF version?::
227 * ASDF can portably name files in subdirectories::
228 * Output translations::
229 * Source Registry Configuration::
230 * Usual operations are made easier to the user::
231 * Many bugs have been fixed::
232 * ASDF itself is versioned::
233 * ASDF can be upgraded::
234 * Decoupled release cycle::
235 * Pitfalls of the transition to ASDF 2::
236 * Pitfalls of the upgrade to ASDF 3::
237 * What happened to the bundle operations::
239 Issues with installing the proper version of ASDF
241 * My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
242 * I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::
243 * After upgrading ASDF, ASDF (and Quicklisp) can't find my systems: After upgrading ASDF.
245 Issues with configuring ASDF
247 * How can I customize where fasl files are stored?::
248 * How can I wholly disable the compiler output cache?::
250 Issues with using and extending ASDF to define systems
252 * How can I cater for unit-testing in my system?::
253 * How can I cater for documentation generation in my system?::
254 * How can I maintain non-Lisp (e.g. C) source files?::
255 * I want to put my module's files at the top level. How do I do this?::
256 * How do I create a system definition where all the source files have a .cl extension?::
257 * How do I mark a source file to be loaded only and not compiled?::
258 * How do I work with readtables?::
259 * How can I capture ASDF's output?::
260 * LOAD-PATHNAME has a weird value::
262 ASDF development FAQs
264 * How do I run the tests interactively in a REPL?::
271 @c -------------------
273 @node Introduction, Quick start summary, Top, Top
274 @comment node-name, next, previous, up
275 @chapter Introduction
276 @cindex ASDF-related features
278 @cindex Testing for ASDF
279 @cindex ASDF versions
284 ASDF is Another System Definition Facility:
285 a tool for specifying how systems of Common Lisp software
286 are made up of components (sub-systems and files),
287 and how to operate on these components in the right order
288 so that they can be compiled, loaded, tested, etc.
289 If you are new to ASDF, @pxref{Quick start summary,,the quick start
292 ASDF presents three faces:
293 one for users of Common Lisp software who want to reuse other people's code,
294 one for writers of Common Lisp software who want to specify how to build their systems,
295 and one for implementers of Common Lisp extensions who want to extend
299 to learn how to use ASDF to load a system.
300 @xref{Defining systems with defsystem},
301 to learn how to define a system of your own.
302 @xref{The object model of ASDF}, for a description of
303 the ASDF internals and how to extend ASDF.
306 ASDF is @emph{not} a tool for library and system @emph{installation};
307 it plays a role like @code{make} or @code{ant}, not like a package manager.
308 In particular, ASDF should not to be confused with Quicklisp or ASDF-Install,
309 that attempt to find and download ASDF systems for you.
310 Despite what the name might suggest,
311 ASDF-Install was never a part of ASDF, it was a separate piece of software.
312 ASDF-Install is also unmaintained and obsolete.
313 We recommend you use Quicklisp
314 (@uref{http://www.quicklisp.org/}) instead,
315 a Common Lisp package manager which works well and is being actively maintained.
316 If you want to download software from version control instead of tarballs,
317 so you may more easily modify it,
318 we recommend clbuild (@uref{http://common-lisp.net/project/clbuild/}).
319 As for where on your filesystem to install Common Lisp software,
320 we recommend subdirectories of @file{~/common-lisp/}:
321 starting with ASDF 3.1.2 (2014), this hierarchy is included
322 in the default source-registry configuration.
324 Finally, note that this manual is incomplete.
325 All the bases are covered,
326 but many advanced topics are only barely alluded to,
327 and there is not much in terms of examples.
328 The source code remains the ultimate source of information,
329 free software systems in Quicklisp remain the best source of examples,
330 and the mailing-list the best place to ask for help.
333 @node Quick start summary, Loading ASDF, Introduction, Top
334 @chapter Quick start summary
338 @item To load an ASDF system:
342 Load ASDF itself into your Lisp image, using
343 @code{(require "asdf")}.
344 Check that you have a recent version using @code{(asdf:asdf-version)}.
345 For more details, or if any of the above fails, @pxref{Loading ASDF}.
348 Make sure software is installed where ASDF can find it.
349 The simplest way is to put all your Lisp code in subdirectories of
350 @file{~/common-lisp/} (starting with ASDF 3.1.2),
351 or @file{~/.local/share/common-lisp/source/}
352 (for ASDF 2 and later, or if you want to keep source in a hidden directory).
353 For more details, @pxref{Configuring ASDF to find your systems}.
356 Load your system with @code{(asdf:load-system "@var{my-system}")}.
361 @item To make your own ASDF system:
365 As above, load and configure ASDF.
368 Make a new directory for your system, @code{@var{my-system}/},
369 again in a location where ASDF can find it.
370 All else being equal, the easiest location is probably
371 @file{~/common-lisp/my-system/}.
372 @xref{Configuring ASDF to find your systems}.
376 Create an ASDF system definition listing the dependencies of
377 your system, its components, and their interdependencies,
378 and put it in @file{@var{my-system}.asd}.
379 This file must have the same name as your system, all lowercase.
380 @xref{Defining systems with defsystem}.
383 Use @code{(asdf:load-system "@var{my-system}")}
384 to make sure it's all working properly. @xref{Using ASDF}.
389 @c FIXME: (1) add a sample project that the user can cut and paste to
390 @c get started. (2) discuss the option of starting with Quicklisp.
396 @node Loading ASDF, Configuring ASDF, Quick start summary, Top
397 @comment node-name, next, previous, up
398 @chapter Loading ASDF
401 * Loading a pre-installed ASDF::
402 * Checking whether ASDF is loaded::
404 * Replacing your implementation's ASDF::
405 * Loading ASDF from source::
408 @node Loading a pre-installed ASDF, Checking whether ASDF is loaded, Loading ASDF, Loading ASDF
409 @section Loading a pre-installed ASDF
411 The recommended way to load ASDF is via:
416 All actively maintained Lisp implementations now include a copy of ASDF 3
417 that you can load this way using Common Lisp's @code{require} function.@footnote{
418 NB: all implementations except GNU CLISP also accept
419 @code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}.
420 For portability's sake, you should use @code{(require "asdf")}.
423 If the implementation you are using doesn't provide a recent ASDF 3,
424 we recommend you upgrade it.
425 If for some reason you would rather not upgrade it,
426 we recommend you replace your implementation's ASDF.
427 @xref{Replacing your implementation's ASDF}.
428 If all else fails, see @pxref{Loading ASDF from source} below.
430 If you use an actively maintained implementation that fails to provide
431 an up-to-date enough stable release of ASDF,
432 you may also send a bug report to your Lisp vendor and complain about it
433 --- or you may fix the issue yourself if it's free software.
435 As of the writing of this manual,
436 the following implementations provide ASDF 3 this way:
437 ABCL, Allegro CL, CLASP, Clozure CL, CMUCL, ECL, GNU CLISP, LispWorks, MKCL, SBCL.
438 The following implementations only provide ASDF 2:
440 The following implementations don't provide ASDF:
441 Corman CL, GCL, Genera, MCL, SCL.
442 The latter implementations are not actively maintained (except maybe GCL);
443 if some of them are ever released again, they probably will include ASDF 3.
445 For maximum convenience you might want to have ASDF loaded
446 whenever you start your Lisp implementation,
447 for example by loading it from the startup script or dumping a custom core
448 --- check your Lisp implementation's manual for details.
449 SLIME notably sports a @code{slime-asdf} contrib that makes life easier with ASDF.
452 @node Checking whether ASDF is loaded, Upgrading ASDF, Loading a pre-installed ASDF, Loading ASDF
453 @section Checking whether ASDF is loaded
455 To check that ASDF is properly loaded, you can run this form:
461 If it returns a string,
462 that is the version of ASDF that is currently installed.
463 If that version is suitably recent (say, 3.1.2 or later),
464 then you can skip directly to next chapter: @xref{Configuring ASDF}.
466 If it raises an error,
467 then either ASDF is not loaded, or
468 you are using a very old version of ASDF,
469 and need to install ASDF 3.
471 For more precision in detecting versions old and new,
472 @pxref{How do I detect the ASDF version?}.
474 If you are experiencing problems with ASDF,
475 please try upgrading to the latest released version,
476 using the method below,
477 before you contact us and raise an issue.
479 @node Upgrading ASDF, Replacing your implementation's ASDF, Checking whether ASDF is loaded, Loading ASDF
480 @section Upgrading ASDF
481 @c FIXME: tighten this up a bit -- there's a lot of stuff here that
482 @c doesn't matter to almost anyone. Move discussion of updating antique
483 @c versions of ASDF down, or encapsulate it.
485 If your implementation already provides ASDF 3 or later (and it should),
486 but you want a more recent ASDF version than your implementation provides, then
487 you just need to ensure the more recent ASDF is installed in a configured path,
488 like any other system.
489 We recommend you download an official tarball or checkout a release from git into
490 @file{~/common-lisp/asdf/}.
491 (@pxref{Configuring ASDF to find your systems}).
493 Once the source code for ASDF is installed,
494 you don't need any extra step to load it beyond the usual @code{(require "asdf")}:
495 ASDF 3 will automatically look whether an updated version of itself is available
496 amongst the regularly configured systems, before it compiles anything else.
498 If your implementation fails to provide ASDF 3 or later,
499 @pxref{Replacing your implementation's ASDF}.
502 @node Replacing your implementation's ASDF, Loading ASDF from source, Upgrading ASDF, Loading ASDF
503 @section Replacing your implementation's ASDF
505 All maintained implementations now provide ASDF 3 in their latest release.
506 If yours doesn't, we recommend you upgrade it.
508 Now, if you insist on using an old implementation
509 that didn't provide ASDF or provided an old version,
510 we recommend installing a recent ASDF, as explained below,
511 into your implementation's installation directory.
512 Thus your modified implementation will now provide ASDF 3.
513 This requires proper write permissions and
514 may necessitate execution as a system administrator.
516 The ASDF source repository contains a tool to
517 help you upgrade your implementation's ASDF.
518 You can invoke it from the shell command-line as
519 @code{tools/asdf-tools install-asdf lispworks}
520 (where you can replace @code{lispworks} by the name of the relevant implementation),
521 or you can @code{(load "tools/install-asdf.lisp")} from your Lisp REPL.
524 Allegro CL, Clozure CL, CMU CL, ECL, GCL, GNU CLISP, LispWorks, MKCL, SBCL, SCL, XCL.
525 It doesn't work on ABCL, Corman CL, Genera, MCL, MOCL.
526 Happily, ABCL is usually pretty up to date and shouldn't need that script.
527 GCL requires a very recent version, and hasn't been tested much.
528 Corman CL, Genera, MCL are obsolete anyway.
532 @node Loading ASDF from source, , Replacing your implementation's ASDF, Loading ASDF
533 @section Loading ASDF from source
535 If you write build scripts that must remain portable to old machines with old implementations
536 that you cannot ensure have been upgraded or modified to provide a recent ASDF,
537 you may have to install the file @file{asdf.lisp}
538 somewhere and load it with:
541 (load "/path/to/your/installed/asdf.lisp")
544 The single file @file{asdf.lisp} is all you normally need to use ASDF.
546 You can extract this file from latest release tarball on the
547 @url{https://common-lisp.net/project/asdf/,ASDF website}.
548 If you are daring and willing to report bugs, you can get
549 the latest and greatest version of ASDF from its git repository.
550 @xref{Getting the latest version}.
552 For scripts that try to use ASDF simply via @code{require} at first, and
553 make heroic attempts to load it the hard way if at first they don't succeed,
554 see @file{tools/load-asdf.lisp} distributed with the ASDF source repository,
555 or the code of @url{https://cliki.net/cl-launch,@code{cl-launch}}.
558 @node Configuring ASDF, Using ASDF, Loading ASDF, Top
559 @comment node-name, next, previous, up
560 @chapter Configuring ASDF
562 For standard use cases, ASDF should work pretty much out of the box.
563 We recommend you skim the sections on configuring ASDF to find your systems
564 and choose the method of installing Lisp software that works best for you.
565 Then skip directly to @xref{Using ASDF}. That will probably be enough.
566 You are unlikely to have to worry about the way ASDF stores object files,
567 and resetting the ASDF configuration is usually only needed in corner cases.
571 * Configuring ASDF to find your systems::
572 * Configuring ASDF to find your systems --- old style::
573 * Configuring where ASDF stores object files::
574 * Resetting the ASDF configuration::
577 @node Configuring ASDF to find your systems, Configuring ASDF to find your systems --- old style, Configuring ASDF, Configuring ASDF
578 @section Configuring ASDF to find your systems
580 In order to compile and load your systems, ASDF must be configured to find
581 the @file{.asd} files that contain system definitions.
583 There are a number of different techniques for setting yourself up with
584 ASDF, starting from easiest to the most complex:
589 Put all of your systems in one of the standard locations,
593 @file{~/common-lisp/} or
595 @file{~/.local/share/common-lisp/source/}.
597 If you install software there, you don't need further
598 configuration.@footnote{
599 @file{~/common-lisp/} is only included in
600 the default configuration
601 starting with ASDF 3.1.2 or later.
602 If your implementation provides an earlier variant of ASDF,
603 you may need to explicitly configure it to use this path,
604 as further explained.
606 You can then skip to the next section. @xref{Loading a system}.
609 If you're using some tool to install software (e.g. Quicklisp),
610 the authors of that tool should already have configured ASDF.
613 If you have more specific desires about how to lay out your software on
614 disk, the preferred way to configure where ASDF finds your systems is
615 the @code{source-registry} facility,
616 fully described in its own chapter of this manual.
617 @xref{Controlling where ASDF searches for systems}.
618 Here is a quick recipe for getting started.
620 First create the directory
621 @file{~/.config/common-lisp/source-registry.conf.d/}@footnote{
622 For Windows users, and starting with ASDF 3.1.5, start from your
623 @file{%LOCALAPPDATA%}, which is usually @file{~/AppData/Local/}
624 (but you can ask in a @code{CMD.EXE} terminal
625 @code{echo %LOCALAPPDATA%} to make sure)
626 and underneath create a subpath
627 @file{config/common-lisp/source-registry.conf.d/}.
629 there create a file with any name of your choice
630 but with the type @file{conf}@footnote{
631 By requiring the @file{.conf}
632 extension, and ignoring other files, ASDF allows you to have disabled files,
633 editor backups, etc. in the same directory with your active
636 ASDF will also ignore files whose names start with a @file{.} character.
638 It is customary to start the filename with two digits, to control the
639 sorting of the @code{conf} files in the source registry directory, and
640 thus the order in which the directories will be scanned.
642 for instance @file{50-luser-lisp.conf};
643 in this file, add the following line
644 to tell ASDF to recursively scan all the subdirectories under @file{/home/luser/lisp/}
645 for @file{.asd} files:
646 @kbd{(:tree "/home/luser/lisp/")}
648 That's enough. You may replace @file{/home/luser/lisp/} by wherever you want to install your source code.
649 You don't actually need to specify anything if you use the default @file{~/common-lisp/} as above
650 and your implementation provides ASDF 3.1.2 or later.
651 If your implementation provides an earlier variant of ASDF 3,
652 you might want to specify @kbd{(:tree (:home "common-lisp/"))} for bootstrap purposes,
653 then install a recent source tree of ASDF under @file{~/common-lisp/asdf/}.
655 If you prefer to use a ``link farm'', which is faster to use but costlier to manage than a recursive traversal,
656 say at @file{/home/luser/.asd-link-farm/}, then
657 you may instead (or additionally) create a file @file{42-asd-link-farm.conf}, containing the line:
658 @kbd{(:directory "/home/luser/.asd-link-farm/")}
660 ASDF will automatically read your configuration
661 the first time you try to find a system.
662 If necessary, you can reset the source-registry configuration with:
665 (asdf:clear-source-registry)
669 In earlier versions of ASDF, the system source registry was configured
670 using a global variable, @code{asdf:*central-registry*}.
671 For more details about this, see the following section,
672 @ref{Configuring ASDF to find your systems --- old style}.
673 Unless you need to understand this,
674 skip directly to @ref{Configuring where ASDF stores object files}.
678 Note that your Operating System distribution or your system administrator
679 may already have configured system-managed libraries for you.
683 @node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Configuring ASDF
684 @section Configuring ASDF to find your systems --- old style
687 @c FIXME: this section should be moved elsewhere. The novice user
688 @c should not be burdened with it. [2014/02/27:rpg]
690 Novices may skip this section.
691 Please @emph{do not} use the central-registry if you are a novice,
692 and @emph{do not} instruct novices to use the central-registry.
693 @c ``Experts may read it then proceed to ...''
694 @c some better section explaining
695 @c *central-registry* vs source-registry vs *system-definition-search-functions*,
696 @c and .../asdf/tools/cl-source-registry-cache.lisp
698 The old way to configure ASDF to find your systems is by
699 @code{push}ing directory pathnames onto the variable
700 @code{asdf:*central-registry*}.
702 You @emph{must} configure this variable @emph{after} you load ASDF 3 or later,
703 yet @emph{before} the first time you try to use it.
704 This loading and configuring of ASDF must happen
705 as part of some initialization script:
706 typically, either a script you maintain that builds your project,
707 or your implementation's initialization script
708 (e.g. @file{~/.sbclrc} for SBCL).
710 Also, if you are using an ancient ASDF 2 or earlier to load ASDF 3 or later,
711 then after it loads the ancient ASDF, your script @emph{must} configure
712 the central-registry a first time to tell ASDF 1 or 2 where to find ASDF 3,
713 then load ASDF 3 with e.g. @code{(asdf:operate 'asdf:load-op "asdf")},
714 then configure the central-registry again, because
715 ASDF 3 will not preserve the central-registry from ASDF 2 when upgrading.
716 You should probably be using the source-registry instead, which will be preserved
717 (unless you manually called @code{asdf:initialize-source-registry} with an argument,
718 in which case you will have to do it again indeed).
719 However, if you are using an ancient ASDF 2 or earlier,
720 we @emph{strongly} recommend that you should instead upgrade your implementation,
721 or overwrite the ancient ASDF installation with a more recent one:
722 @xref{Replacing your implementation's ASDF}.
724 The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
725 but is still supported for compatibility with ASDF 1.
726 When used, it takes precedence over the above source-registry.@footnote{
727 It is possible to further customize
728 the system definition file search.
729 That's considered advanced use, and covered later:
731 @code{*system-definition-search-functions*}.
732 @xref{Defining systems with defsystem}.}
734 For example, let's say you want ASDF to find the @file{.asd} file
735 @file{/home/me/src/foo/foo.asd}.
736 In your Lisp initialization file, you could have the following:
740 (push "/home/me/src/foo/" asdf:*central-registry*)
743 Note the trailing slash: when searching for a system,
744 ASDF will evaluate each entry of the central registry
745 and coerce the result to a pathname.@footnote{
746 ASDF will indeed call @code{eval} on each entry.
747 It will skip entries that evaluate to @code{nil}.
749 Strings and pathname objects are self-evaluating,
750 in which case the @code{eval} step does nothing;
751 but you may push arbitrary s-expressions onto the central registry.
752 These s-expressions may be evaluated to compute context-dependent
753 entries, e.g. things that depend
754 on the value of shell variables or the identity of the user.
756 The variable @code{asdf:*central-registry*} is thus a list of
757 ``system directory designators''.
758 A @dfn{system directory designator} is a form
759 which will be evaluated whenever a system is to be found,
760 and must evaluate to a directory to look in (or @code{nil}).
761 By ``directory'', we mean
762 ``designator for a pathname with a non-empty DIRECTORY component''.
764 The trailing directory name separator
765 is necessary to tell Lisp that you're discussing a directory
766 rather than a file. If you leave it out, ASDF is likely to look in
767 @code{/home/me/src/} instead of @code{/home/me/src/foo/} as you
768 intended, and fail to find your system definition.
769 Modern versions of ASDF will issue an error and offer you to
770 remove such entries from the central-registry.
772 Typically there are a lot of @file{.asd} files, and
773 a common idiom was to put
774 @emph{symbolic links} to all of one's @file{.asd} files
775 in a common directory
776 and push @emph{that} directory (the ``link farm'')
778 @code{asdf:*central-registry*},
779 instead of pushing each individual system directory.
781 ASDF knows to follow @emph{symlinks}
782 to the actual location of the systems.@footnote{
783 On Windows, you can use Windows shortcuts instead of POSIX symlinks.
784 if you try aliases under MacOS, we are curious to hear about your experience.
787 For example, if @code{#p"/home/me/cl/systems/"}
788 is an element of @code{*central-registry*}, you could set up the
789 system @var{foo} as follows:
792 $ cd /home/me/cl/systems/
793 $ ln -s ~/src/foo/foo.asd .
796 This old style for configuring ASDF is not recommended for new users,
797 but it is supported for old users, and for users who want a simple way to
798 programmatically control what directories are added to the ASDF search path.
801 @node Configuring where ASDF stores object files, Resetting the ASDF configuration, Configuring ASDF to find your systems --- old style, Configuring ASDF
802 @section Configuring where ASDF stores object files
803 @findex clear-output-translations
805 ASDF lets you configure where object files will be stored.
806 Sensible defaults are provided and
807 you shouldn't normally have to worry about it.
809 This allows the same source code repository to be shared
810 between several versions of several Common Lisp implementations,
811 between several users using different compilation options,
812 with users who lack write privileges on shared source directories, etc.
813 This also keeps source directories from being cluttered
814 with object/fasl files.
816 Starting with ASDF 2, the @code{asdf-output-translations} facility
817 was added to ASDF itself. This facility controls where object files will be stored.
818 This facility is fully described in a chapter of this manual,
819 @ref{Controlling where ASDF saves compiled files}.
821 @c FIXME: possibly this should be moved elsewhere. It's redundant here,
822 @c and makes this section of the manual too long and daunting for the
823 @c new user. [2014/02/27:rpg]
824 @c The simplest way to add a translation to your search path,
825 @c say from @file{/foo/bar/baz/quux/}
826 @c to @file{/where/i/want/my/fasls/}
827 @c is to create the directory
828 @c @file{~/.config/common-lisp/asdf-output-translations.conf.d/}
829 @c and there create a file with any name of your choice and the type @file{conf},
830 @c for instance @file{42-bazquux.conf}
831 @c containing the line:
833 @c @kbd{("/foo/bar/baz/quux/" "/where/i/want/my/fasls/")}
835 @c To disable output translations for source under a given directory,
836 @c say @file{/toto/tata/}
837 @c you can create a file @file{40-disable-toto.conf}
840 @c @kbd{("/toto/tata/")}
842 @c To wholly disable output translations for all directories,
843 @c you can create a file @file{00-disable.conf}
848 @c Note that your Operating System distribution or your system administrator
849 @c may already have configured translations for you.
850 @c In absence of any configuration, the default is to redirect everything
851 @c under an implementation-dependent subdirectory of @file{~/.cache/common-lisp/}.
852 @c @xref{Controlling where ASDF searches for systems}, for full details.
854 @c The required @file{.conf} extension allows you to have disabled files
855 @c or editor backups (ending in @file{~}), and works portably
856 @c (for instance, it is a pain to allow both empty and non-empty extension on CLISP).
857 @c Excluded are files the name of which start with a @file{.} character.
858 @c It is customary to start the filename with two digits
859 @c that specify the order in which the directories will be scanned.
861 @c ASDF will automatically read your configuration
862 @c the first time you try to find a system.
863 @c You can reset the source-registry configuration with:
866 @c (asdf:clear-output-translations)
869 @c And you probably should do so before you dump your Lisp image,
870 @c if the configuration may change
871 @c between the machine where you save it at the time you save it
872 @c and the machine you resume it at the time you resume it.
873 @c (Once again, you should use @code{(asdf:clear-configuration)}
874 @c before you dump your Lisp image, which includes the above.)
876 Note that before ASDF 2,
877 other ASDF add-ons offered the same functionality,
878 each in subtly different and incompatible ways:
879 ASDF-Binary-Locations, cl-launch, common-lisp-controller.
880 ASDF-Binary-Locations is now not needed anymore and should not be used.
881 cl-launch 3.000 and common-lisp-controller 7.2 have been updated
882 to delegate object file placement to ASDF.
884 @node Resetting the ASDF configuration, , Configuring where ASDF stores object files, Configuring ASDF
885 @section Resetting the ASDF configuration
887 @c FIXME: this should probably be moved out of the "quickstart" part of
888 @c the manual. [2014/02/27:rpg]
891 When you dump and restore an image, or when you tweak your configuration,
892 you may want to reset the ASDF configuration.
893 For that you may use the following function:
895 @defun clear-configuration
896 Undoes any ASDF configuration
897 regarding source-registry or output-translations.
900 @vindex *image-dump-hook*
901 This function is pushed onto the @code{uiop:*image-dump-hook*} by default,
902 which means that if you save an image using @code{uiop:dump-image},
903 or via @code{asdf:image-op} and @code{asdf:program-op},
904 it will be automatically called to clear your configuration.
905 If for some reason you prefer to call your implementation's underlying functionality,
906 be sure to call @code{clear-configuration} manually,
907 or push it into your implementation's equivalent of @code{uiop:*image-dump-hook*},
908 e.g. @code{sb-ext:*save-hooks*} on SBCL, or @code{ext:*before-save-initializations*}
909 on CMUCL and SCL, etc.
911 @node Using ASDF, Defining systems with defsystem, Configuring ASDF, Top
916 * Convenience Functions::
920 @node Loading a system, Convenience Functions, Using ASDF, Using ASDF
921 @section Loading a system
923 The system @var{foo} is loaded (and compiled, if necessary)
924 by evaluating the following Lisp form:
927 (asdf:load-system :@var{foo})
930 On some implementations (@pxref{Convenience Functions}),
931 ASDF hooks into the @code{cl:require} facility and you can just use:
937 Note that the canonical name of a system is a string, conventionally lowercase.
938 A system name can also be specified as a symbol (including a keyword),
939 in which case its @code{symbol-name} is taken and lowercased.
940 The name must be a suitable value for the @code{:name} initarg
941 to @code{make-pathname} in whatever filesystem the system is to be found.
943 The lower-casing-symbols behaviour is unconventional,
944 but was selected after some consideration.
945 The type of systems we want to support
946 either have lowercase as customary case (Unix, Mac, Windows)
947 or silently convert lowercase to uppercase (lpns).
948 @c so this makes more sense than attempting to use @code{:case :common},
949 @c which is reported not to work on some implementations
952 @node Convenience Functions, Moving on, Loading a system, Using ASDF
953 @section Convenience Functions
955 @c I believe thes are all unnecessary because of the function macros
956 @c below [2016/01/30:rpg]
957 @c @findex load-system
958 @c @findex compile-system
959 @c @findex test-system
960 @c @findex require-system
963 ASDF provides three commands for the most common system operations:
964 @code{load-system}, @code{compile-system}, and @code{test-system}.
966 ASDF also provides @code{require-system}, a variant of @code{load-system}
967 that skips loading systems that are already loaded. This is sometimes
968 useful, for example, in order to avoid re-loading libraries that come
969 pre-loaded into your lisp implementation.
971 ASDF also provides @code{make}, a way of allowing system developers to
972 choose a default operation for their systems. For example, a developer
973 who has created a system intended to format a specific document, might
974 make document-formatting the default operation invoked by @code{make},
975 instead of loading. If the system developer doesn't specify in the
976 system definition, the default operation will be loading.
978 @c FIXME: We seem to export @findex bundle-system also, that some ECL users seem to rely on.
979 @c But it's probably better that bundle operations have their own manual chapter at some point.
982 @c FIXME: There should be a @defun for OPERATE, but there isn't. Not
983 @c sure where it belongs... The discussion here is just confusing if
984 @c the reader doesn't understand how ASDF works. [2016/01/30:rpg]
988 Because ASDF is an extensible system
989 for defining @emph{operations} on @emph{components},
990 it also provides a generic function @code{operate},
991 so you may arbitrarily operate on your systems beyond the default operations.
992 (At the interactive REPL, users often use its shorter alias @code{oos},
993 which stands for operate-on-system, a name inherited from @code{mk-defsystem}.)
994 You'll use @code{operate} whenever you want to do something beyond
995 compiling, loading and testing.
997 @c Reminder: before ASDF can operate on a system, however,
998 @c it must be able to find and load that system's definition.
999 @c @xref{Configuring ASDF to find your systems}.
1001 @c FIXME: the following is too complicated for here, especially since
1002 @c :force hasn't been defined yet. Move it. [2014/02/27:rpg]
1004 @vindex *load-system-operation*
1005 @findex already-loaded-systems
1007 @defun load-system system @Arest{} keys @Akey{} force force-not verbose version @AallowOtherKeys{}
1008 Apply @code{operate} with the operation from
1009 @code{*load-system-operation*}
1010 the @var{system}, and any provided keyword arguments.
1011 @code{*load-system-operation*} by default is @code{load-op};
1012 it would be @code{load-bundle-op} by default on ECL,
1013 if only an implementation bug were fixed.
1014 Calling @code{load-system} is the regular, recommended way
1015 to load a system into the current image.
1018 @defun compile-system system @Arest{} keys @Akey{} force force-not verbose version @AallowOtherKeys{}
1019 Apply @code{operate} with the operation @code{compile-op},
1020 the @var{system}, and any provided keyword arguments.
1021 This will make sure all the files in the system are compiled,
1022 but not necessarily load any of them in the current image;
1023 on most systems, it will @emph{not} load all compiled files in the current image.
1024 This function exists for symmetry with @code{load-system} but is not recommended
1025 unless you are writing build scripts and know what you're doing.
1026 But then, you might be interested in @code{program-op} rather than @code{compile-op}.
1029 @defun test-system system @Arest{} keys @Akey{} force force-not verbose version @AallowOtherKeys{}
1030 Apply @code{operate} with the operation @code{test-op},
1031 the @var{system}, and any provided keyword arguments.
1035 @defun make system @Arest{} keys @Akey{} @AallowOtherKeys{}
1036 Do ``The Right Thing'' with your system.
1037 Starting with ASDF 3.1, this function @code{make} is also available.
1038 The default behaviour is to load the system as if by @code{load-system};
1039 but system authors can override this default in their system definition
1040 they may specify an alternate operation as the intended use of their system,
1041 with a @code{:build-operation} option in the @code{defsystem} form
1042 (@pxref{The defsystem grammar, build-operation}),
1043 and an intended output pathname for that operation with
1044 @code{:build-pathname}.
1045 @c Document :build-operation in the defsystem section.
1046 @c Document in the extension section that for richer programmatic access, you may instead use an overriding
1047 @c @code{(defmethod component-depends-on ((o build-op) (s system))
1049 This function is experimental and largely untested. Use at your own risk.
1051 @cindex build-operation
1053 @defun require-system system @Arest{} keys @Akey{} @AallowOtherKeys{}
1054 @code{require-system} skips any update to systems that have already been loaded,
1055 in the spirit of @code{cl:require}.
1056 It does it by calling @code{load-system} with a keyword option
1057 excluding already loaded systems.@footnote{
1058 For the curious, the option is @code{:force-not (already-loaded-systems)}.
1060 On actively maintained free software implementations
1061 (namely recent versions of ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL),
1062 once ASDF itself is loaded, @code{cl:require} too can load ASDF systems,
1063 by falling back on @code{require-system}
1064 for module names not recognized by the implementation.
1065 (Note however that @code{require-system} does @emph{not} fall back on @code{cl:require};
1066 that would introduce an ``interesting'' potential infinite loop to break somehow.)
1068 @code{cl:require} and @code{require-system} are appropriate to load code
1069 that is not being modified during the current programming session.
1070 @code{cl:require} will notably load the implementation-provided extension modules;
1071 @code{require-system} won't, unless they are also defined as systems somehow,
1072 which SBCL and MKCL do.
1073 @code{require-system} may also be used to load any number of ASDF systems
1074 that the user isn't either developing or debugging,
1075 for which a previously installed version is deemed to be satisfactory;
1076 @code{cl:require} on the above-mentioned implementations will delegate to @code{require-system}
1077 and may load them as well.
1078 But for code that you are actively developing, debugging, or otherwise modifying,
1079 you should use @code{load-system}, so ASDF will pick on your modifications
1080 and transitively re-build the modified files and everything that depends on them
1081 (that the requested @var{system} itself depends on ---
1082 ASDF itself never builds anything unless
1083 it's an explicitly requested system or the dependencies thereof).
1087 @node Moving on, , Convenience Functions, Using ASDF
1090 That's all you need to know to use ASDF to load systems written by others.
1091 The rest of this manual deals with writing system definitions
1092 for Common Lisp software you write yourself,
1093 including how to extend ASDF to define new operation and component types.
1096 @node Defining systems with defsystem, The object model of ASDF, Using ASDF, Top
1097 @comment node-name, next, previous, up
1098 @chapter Defining systems with defsystem
1100 This chapter describes how to use ASDF to define systems and develop
1105 * The defsystem form::
1106 * A more involved example::
1107 * The defsystem grammar::
1108 * Other code in .asd files::
1109 * The package-inferred-system extension::
1112 @node The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
1113 @comment node-name, next, previous, up
1114 @section The defsystem form
1119 This section begins with an example of a system definition,
1120 then gives the full grammar of @code{defsystem}.
1122 Let's look at a simple system.
1123 This is a complete file that should be saved as @file{hello-lisp.asd}
1124 (in order that ASDF can find it
1125 when ordered to operate on the system named @code{"hello-lisp"}).
1128 ;; Usual Lisp comments are allowed here
1130 (defsystem "hello-lisp"
1131 :description "hello-lisp: a sample Lisp system."
1133 :author "Joe User <joe@@example.com>"
1134 :licence "Public Domain"
1135 :depends-on ("optima.ppcre" "command-line-arguments")
1136 :components ((:file "packages")
1137 (:file "macros" :depends-on ("packages"))
1138 (:file "hello" :depends-on ("macros"))))
1141 Some notes about this example:
1146 The @code{defsystem} form defines a system named @code{hello-lisp}
1147 that contains three source files:
1148 @file{packages.lisp}, @file{macros.lisp} and @file{hello.lisp}.
1151 The @file{.lisp} suffix is implicit for Lisp source files.
1152 The source files are located in the same directory
1153 as the @code{.asd} file with the system definition.
1154 @c FIXME: the following should live somewhere, but not in the quickstart
1155 @c page. [2014/05/03:rpg]
1156 @c ASDF resolves symbolic links (or Windows shortcuts)
1157 @c before loading the system definition file and
1158 @c stores its location in the resulting system@footnote{
1159 @c It is possible, though almost never necessary, to override this behaviour.}.
1160 @c This is a good thing because the user can move the system sources
1161 @c without having to edit the system definition.
1163 @c FIXME: The first example system should probably use just :serial T.
1165 The file @file{macros} depends on @file{packages}
1166 (presumably because the package it's in is defined in @file{packages}),
1167 and the file @file{hello} depends on @file{macros}
1168 (and hence, transitively on @file{packages}).
1169 This means that ASDF will compile and load @file{packages} then @file{macros}
1170 before starting the compilation of file @file{hello}.
1173 This example system has external dependencies on two other systems,
1174 @code{optima.ppcre} (that provides a friendly interface to matching regular expressions),
1175 and @code{command-line-arguments} (that provides a way to parse arguments passed from the shell command line).
1176 To use this system, ASDF must be configured to find installed copies of these systems;
1177 it will load them before it tries to compile and load @code{hello-lisp}.
1180 This system also defines a bunch of metadata.
1181 While it is optional to define these fields
1182 (and other fields like @code{:bug-tracker}, @code{:mailto}, @code{:long-name},
1183 @code{:long-description}, @code{:source-control}),
1184 it is strongly recommended to define the fields @code{:description}, @code{:version}, @code{:author}, and @code{:licence},
1185 especially if you intend your software to be eventually included in Quicklisp.
1187 @c FIXME: Should have cross-reference to "Version specifiers" in the
1188 @c defsystem grammar, but the cross-referencing is so broken by
1189 @c insufficient node breakdown that I have not put one in.
1190 @c FIXME: this is way too detailed for the first example!
1193 Make sure you know how the @code{:version} numbers will be parsed!
1194 Only period-separated non-negative integers are accepted at present.
1195 See below Version specifiers in @ref{The defsystem grammar}.
1198 This file contains a single form, the @code{defsystem} declaration.
1199 No @code{in-package} form, no @code{asdf:} package prefix, no nothing.
1200 Just the one naked @code{defsystem} form.
1201 This is what we recommend.
1202 More complex system definition files are possible with arbitrary Lisp code,
1203 but we recommend that you keep it simple if you can.
1204 This will make your system definitions more robust and more future-proof.
1210 This is all you need to know to define simple systems.
1211 The next example is much more involved, to give you a glimpse of how you can do more complex things.
1212 However, since it's ultimately arbitrary Lisp code, there is no bottom to the rabbit hole.
1213 @c FIXME: divide the next example into many examples, to introduce fewer concepts at once.
1216 @node A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
1217 @comment node-name, next, previous, up
1218 @section A more involved example
1221 Let's illustrate some more involved uses of @code{defsystem} via a
1222 slightly convoluted example:
1225 (in-package :asdf-user)
1228 :version (:read-file-form "variables" :at (3 2))
1231 (:file "variables" :depends-on ("package"))
1233 :depends-on ("package")
1235 :components ((:file "utils")
1238 (:static-file "data.raw"))
1239 :output-files (compile-op (o c) (list "data.cooked"))
1240 :perform (compile-op :after (o c)
1242 :in (component-pathname (find-component c "data.raw"))
1243 :out (first (output-files o c)))))
1244 (:file "foo" :depends-on ("mod"))))
1246 (defmethod action-description
1247 ((o compile-op) (c (eql (find-component "foo" "mod"))))
1251 Here are some notes about this example:
1256 The main thing this file does is define a system @code{foo}.
1257 It also contains other Lisp forms, which we'll examine below.
1260 Besides Lisp source files, this system contains a @code{:module} component
1261 named @code{"mod"}, which is a collection of three Lisp source files
1262 @file{utils.lisp}, @file{reader.lisp}, @file{cooker.lisp} and @file{data.raw}
1265 Note that the @code{:static-file} does not have an implicit file type,
1266 unlike the Lisp source files.
1269 This files will be located in a subdirectory of the main code directory named
1270 @file{mod/} (this location could have been overridden to be
1271 in the same directory, or in a different subdirectory;
1272 see the discussion of the @code{:pathname} option in @ref{The defsystem grammar}).
1275 The @code{:serial t} says that each sub-component of @code{mod} depends on the previous components,
1276 so that @file{cooker.lisp} depends-on @file{utils.lisp}, which depends-on @file{reader.lisp}.
1277 Also @file{data.raw} depends on all of them, but that doesn't matter since it's a static file;
1278 on the other hand, if it appeared first, then all the Lisp files would be recompiled
1279 when the data is modified, which is probably not what is desired in this case.
1282 The method-form tokens provide a shorthand for defining methods on
1283 particular components. This part
1286 :output-files (compile-op (o c) (list "data.cooked"))
1287 :perform (compile-op :after (o c)
1289 :in (component-pathname (find-component c "data.raw"))
1290 :out (first (output-files o c))))
1296 (defmethod output-files ((o compile-op) (c (eql ...)))
1297 (list "data.cooked"))
1298 (defmethod perform :after ((o compile-op) (c (eql ...)))
1300 :in (component-pathname (find-component c "data.raw"))
1301 :out (first (output-files o c))))
1304 where @code{...} is the component in question.
1305 In this case @code{...} would expand to something like
1308 (find-component "foo" "mod")
1311 For more details on the syntax of such forms,
1312 @pxref{The defsystem grammar}.
1313 For more details on what these methods do, @pxref{Operations} in
1314 @ref{The object model of ASDF}.
1317 There is an additional @code{defmethod} with a similar effect,
1318 because ASDF (as of ASDF 3.1.5)
1319 fails to accept inline-methods as above for @code{action-description},
1320 instead only supporting the deprecated @code{explain} interface.
1322 @c FIXME: The following plunge into detail weeds is not appropriate in this
1323 @c location. [2010/10/03:rpg]
1324 @c note that although this also supports @code{:before} methods,
1325 @c they may not do what you want them to ---
1326 @c a @code{:before} method on perform @code{((op compile-op) (c (eql ...)))}
1327 @c will run after all the dependencies and sub-components have been processed,
1328 @c but before the component in question has been compiled.
1331 In this case, these methods describe how this module defines code
1332 that it then uses to cook some data.
1335 Importantly, ASDF is told about the input and output files
1336 used by the data cooker,
1337 and to make sure everyone agrees,
1338 the cooking function explicitly uses ASDF to access pathnames
1339 to the input and output data.
1341 @c FIXME: move most of this package discussion to its own section,
1342 @c and leave only a reference here.
1345 The file starts with a form @code{(in-package :asdf-user)},
1346 but it is actually redundant, not necessary and not recommended.
1347 But yet more complex cases (also not recommended) may usefully use an @code{in-package} form.
1350 Indeed, ASDF does not load @file{.asd} files simply with @code{cl:load},
1351 and neither should you.
1352 You should let ASDF find and load them when you operate on systems.
1353 If you somehow @emph{must} load a @file{.asd} file,
1354 use the same function @code{asdf:load-asd} that ASDF uses.
1355 Among other things, it already binds the @code{*package*} to @code{asdf-user}.
1356 Recent versions of SLIME (2013-02 and later) know to do that when you @kbd{C-c C-k}
1357 when you use the @code{slime-asdf} contrib.
1360 You shouldn't use an @code{in-package} form
1361 if you're keeping things simple.
1362 You should only use @code{in-package} (and before it, a @code{defpackage})
1363 when you're going to define new classes, functions, variables, macros, etc.,
1364 in the @code{.asd} file, and want to thereby avoid name clashes.
1365 Manuals for old versions of ASDF recommended use of such an idiom in @file{.asd} files,
1366 but as of ASDF 3, we recommend that you don't do that anymore,
1367 and instead define any ASDF extensions in their own system,
1368 on which you can then declare a dependency using @code{:defsystem-depends-on}.
1369 @xref{The defsystem grammar}.
1372 More generally, you can always rely on symbols
1373 from packages @code{asdf}, @code{common-lisp} and @code{uiop}
1374 being available in @code{.asd} files ---
1375 most importantly including @code{defsystem}.
1376 It is therefore redundant and in bad taste to use a package-prefixed @code{asdf:defsystem} symbol
1377 in a @file{.asd} file.
1378 Just use @code{(defsystem ...)}.
1379 Only package-prefix it when somehow dynamically generating system definitions
1380 from a package that doesn't already use the ASDF package.
1383 @code{asdf-user} is actually only available starting since ASDF 3, but then again,
1384 ASDF 1 and 2 did crazy things with packages that ASDF 3 has stopped doing@footnote{
1385 ASDF 1 and 2 (up until 2.26)
1386 used to dynamically create and delete temporary packages @code{asdf@emph{N}},
1387 one for each @file{.asd} file, in a misguided attempt to thereby reduce name clashes;
1388 but it failed at that goal and only made things more complex.
1389 ASDF 3 just uses a shared package @code{asdf-user} instead,
1390 and relies on the usual Common Lisp conventions to avoid clashes.
1391 As far as package oddities go, you may just notice that
1392 the @code{asdf-user} package also uses @code{uiop/common-lisp},
1393 a variant of the @code{common-lisp} package that papers over
1394 deficiencies in more obscure Common Lisp implementations;
1395 but unless you care about Corman Lisp, GCL, Genera or MCL, you shouldn't be concerned.
1397 and since all implementations provide ASDF 3, you shouldn't care about compatibility with ASDF 2.
1398 We do not support ASDF 2 anymore, and we recommend that neither should you.
1401 Starting with ASDF 3.1, @code{asdf-user} uses @code{uiop},
1402 whereas in earlier variants of ASDF 3 it only used @code{uiop/package}.
1403 We recommend you either prefix use of UIOP functions with the package prefix @code{uiop:},
1404 or make sure your system @code{:depends-on ((:version "asdf" "3.1.2"))}
1405 or has a @code{#-asdf3.1 (error "MY-SYSTEM requires ASDF 3.1.2")}.
1408 Finally, we elided most metadata, but showed how you can have ASDF automatically extract
1409 the system's version from a source file. In this case, the 3rd subform of the 4th form
1410 (note that Lisp uses 0-based indexing, English uses 1-based indexing).
1411 Presumably, the 4th form looks like @code{(defparameter *foo-version* "5.6.7")}.
1416 @node The defsystem grammar, Other code in .asd files, A more involved example, Defining systems with defsystem
1417 @comment node-name, next, previous, up
1418 @section The defsystem grammar
1420 @cindex DEFSYSTEM grammar
1422 @c FIXME: @var typesetting not consistently used here. We should either expand
1423 @c its use to everywhere, or we should kill it everywhere.
1427 system-definition := ( defsystem system-designator @var{system-option}* )
1429 system-option := :defsystem-depends-on system-list
1430 | :weakly-depends-on @var{system-list}
1431 | :class class-name (see discussion below)
1432 | :build-operation @var{operation-name}
1437 # These are only available since ASDF 3 (actually its alpha release 2.27)
1438 system-option := :homepage string
1439 | :bug-tracker string
1442 | :source-control source-control
1443 | :version version-specifier
1445 source-control := (keyword string)
1447 module-option := :components component-list
1448 | :serial [ t | nil ]
1451 | :pathname pathname-specifier
1452 | :default-component-class class-name
1453 | :perform method-form
1454 | :explain method-form
1455 | :output-files method-form
1456 | :operation-done-p method-form
1457 | :if-feature feature-expression
1458 | :depends-on ( @var{dependency-def}* )
1459 | :in-order-to ( @var{dependency}+ )
1462 system-list := ( @var{simple-component-name}* )
1464 component-list := ( @var{component-def}* )
1466 component-def := ( component-type simple-component-name @var{option}* )
1468 component-type := :module | :file | :static-file | other-component-type
1470 other-component-type := symbol-by-name
1471 (@pxref{The defsystem grammar,,Component types})
1473 # This is used in :depends-on, as opposed to ``dependency,''
1474 # which is used in :in-order-to
1475 dependency-def := simple-component-name
1476 | ( :feature @var{feature-expression} dependency-def )
1477 # (@pxref{The defsystem grammar,,Feature dependencies})
1478 | ( :version simple-component-name version-specifier )
1479 | ( :require module-name )
1481 # ``dependency'' is used in :in-order-to, as opposed to
1482 # ``dependency-def''
1483 dependency := (dependent-op @var{requirement}+)
1484 requirement := (required-op @var{required-component}+)
1485 dependent-op := operation-name
1486 required-op := operation-name
1488 simple-component-name := string
1491 pathname-specifier := pathname | string | symbol
1493 version-specifier := string
1494 | (:read-file-form <pathname-specifier> <form-specifier>?)
1495 | (:read-file-line <pathname-specifier> <line-specifier>?)
1496 line-specifier := :at integer # base zero
1497 form-specifier := :at [ integer | ( integer+ )]
1499 method-form := (operation-name qual lambda-list @Arest{} body)
1500 qual := method qualifier?
1502 feature-expression := keyword
1503 | (:and @var{feature-expression}*)
1504 | (:or @var{feature-expression}*)
1505 | (:not @var{feature-expression})
1509 @subsection Component names
1511 Component names (@code{simple-component-name})
1512 may be either strings or symbols.
1514 @subsection Component types
1516 Component type names, even if expressed as keywords, will be looked up
1517 by name in the current package and in the asdf package, if not found in
1518 the current package. So a component type @code{my-component-type}, in
1519 the current package @code{my-system-asd} can be specified as
1520 @code{:my-component-type}, or @code{my-component-type}.
1522 @code{system} and its subclasses are @emph{not}
1523 allowed as component types for such children components.
1525 @subsection System class names
1527 A system class name will be looked up
1528 in the same way as a Component type (see above),
1529 except that only @code{system} and its subclasses are allowed.
1530 Typically, one will not need to specify a system
1531 class name, unless using a non-standard system class defined in some
1532 ASDF extension, typically loaded through @code{DEFSYSTEM-DEPENDS-ON},
1533 see below. For such class names in the ASDF package, we recommend that
1534 the @code{:class} option be specified using a keyword symbol, such as
1537 :class :MY-NEW-SYSTEM-SUBCLASS
1540 This practice will ensure that package name conflicts are avoided.
1541 Otherwise, the symbol @code{MY-NEW-SYSTEM-SUBCLASS} will be read into
1542 the current package @emph{before} it has been exported from the ASDF
1543 extension loaded by @code{:defsystem-depends-on}, causing a name
1544 conflict in the current package.
1546 @subsection Defsystem depends on
1547 @cindex :defsystem-depends-on
1549 The @code{:defsystem-depends-on} option to @code{defsystem} allows the
1550 programmer to specify another ASDF-defined system or set of systems that
1551 must be loaded @emph{before} the system definition is processed.
1552 Typically this is used to load an ASDF extension that is used in the
1555 @subsection Build-operation
1556 @cindex :build-operation
1558 The @code{:build-operation} option to @code{defsystem} allows the
1559 programmer to specify an operation that will be applied, in place of
1560 @code{load-op} when @code{make} (@pxref{Convenience Functions, make})
1561 is run on the system. The option
1562 value should be the name of an operation. E.g., @code{:build-operation doc-op}
1565 experimental and largely untested. Use at your own risk.
1567 @subsection Weakly depends on
1568 @cindex :weakly-depends-on
1570 We do @emph{NOT} recommend you use this feature.
1571 If you are tempted to write a system @var{foo}
1572 that weakly-depends-on a system @var{bar},
1573 we recommend that you should instead
1574 write system @var{foo} in a parametric way,
1575 and offer some special variable and/or some hook to specialize its behaviour;
1576 then you should write a system @var{foo+bar}
1577 that does the hooking of things together.
1579 The (deprecated) @code{:weakly-depends-on} option to @code{defsystem}
1580 allows the programmer to specify another ASDF-defined system or set of systems
1581 that ASDF should @emph{try} to load,
1582 but need not load in order to be successful.
1583 Typically this is used if there are a number of systems
1584 that, if present, could provide additional functionality,
1585 but which are not necessary for basic function.
1587 Currently, although it is specified to be an option only to @code{defsystem},
1588 this option is accepted at any component, but it probably
1589 only makes sense at the @code{defsystem} level.
1590 Programmers are cautioned not
1591 to use this component option except at the @code{defsystem} level, as
1592 this anomalous behaviour may be removed without warning.
1594 @c Finally, you might look into the @code{asdf-system-connections} extension,
1595 @c that will let you define additional code to be loaded
1596 @c when two systems are simultaneously loaded.
1597 @c It may or may not be considered good style, but at least it can be used
1598 @c in a way that has deterministic behaviour independent of load order,
1599 @c unlike @code{weakly-depends-on}.
1602 @subsection Pathname specifiers
1603 @cindex pathname specifiers
1605 A pathname specifier (@code{pathname-specifier})
1606 may be a pathname, a string or a symbol.
1607 When no pathname specifier is given for a component,
1608 which is the usual case, the component name itself is used.
1610 If a string is given, which is the usual case,
1611 the string will be interpreted as a Unix-style pathname
1612 where @code{/} characters will be interpreted as directory separators.
1613 Usually, Unix-style relative pathnames are used
1614 (i.e. not starting with @code{/}, as opposed to absolute pathnames);
1615 they are relative to the path of the parent component.
1616 Finally, depending on the @code{component-type},
1617 the pathname may be interpreted as either a file or a directory,
1619 a file type may be added corresponding to the @code{component-type},
1620 or else it will be extracted from the string itself (if applicable).
1622 For instance, the @code{component-type} @code{:module}
1623 wants a directory pathname, and so a string @code{"foo/bar"}
1624 will be interpreted as the pathname @file{#p"foo/bar/"}.
1625 On the other hand, the @code{component-type} @code{:file}
1626 wants a file of type @code{lisp}, and so a string @code{"foo/bar"}
1627 will be interpreted as the pathname @file{#p"foo/bar.lisp"},
1628 and a string @code{"foo/bar.quux"}
1629 will be interpreted as the pathname @file{#p"foo/bar.quux.lisp"}.
1630 Finally, the @code{component-type} @code{:static-file}
1631 wants a file without specifying a type, and so a string @code{"foo/bar"}
1632 will be interpreted as the pathname @file{#p"foo/bar"},
1633 and a string @code{"foo/bar.quux"}
1634 will be interpreted as the pathname @file{#p"foo/bar.quux"}.
1636 ASDF interprets the string @code{".."}
1637 as the pathname directory component word @code{:back},
1638 which when merged, goes back one level in the directory hierarchy.
1640 If a symbol is given, it will be translated into a string,
1641 and downcased in the process.
1642 The downcasing of symbols is unconventional,
1643 but was selected after some consideration.
1644 Observations suggest that the type of systems we want to support
1645 either have lowercase as customary case (Unix, Mac, windows)
1646 or silently convert lowercase to uppercase (lpns),
1647 so this makes more sense than attempting to use @code{:case :common}
1648 as argument to @code{make-pathname},
1649 which is reported not to work on some implementations.
1651 Pathname objects may be given to override the path for a component.
1652 Such objects are typically specified using reader macros such as @code{#p}
1653 or @code{#.(make-pathname ...)}.
1654 Note however, that @code{#p...} is
1655 a shorthand for @code{#.(parse-namestring ...)}
1656 and that the behaviour of @code{parse-namestring} is completely non-portable,
1657 unless you are using Common Lisp @code{logical-pathname}s,
1658 which themselves involve other non-portable behaviour
1659 (@pxref{The defsystem grammar,,Using logical pathnames}, below).
1660 Pathnames made with @code{#.(make-pathname ...)}
1661 can usually be done more easily with the string syntax above.
1662 The only case that you really need a pathname object is to override
1663 the component-type default file type for a given component.
1664 Therefore, pathname objects should only rarely be used.
1665 Unhappily, ASDF 1 used not to properly support
1666 parsing component names as strings specifying paths with directories,
1667 and the cumbersome @code{#.(make-pathname ...)} syntax had to be used.
1668 An alternative to @code{#.} read-time evaluation is to use
1669 @code{(eval `(defsystem ... ,pathname ...))}.
1671 Note that when specifying pathname objects,
1672 ASDF does not do any special interpretation of the pathname
1673 influenced by the component type, unlike the procedure for
1674 pathname-specifying strings.
1675 On the one hand, you have to be careful to provide a pathname that correctly
1676 fulfills whatever constraints are required from that component type
1677 (e.g. naming a directory or a file with appropriate type);
1678 on the other hand, you can circumvent the file type that would otherwise
1679 be forced upon you if you were specifying a string.
1681 @subsection Version specifiers
1682 @cindex version specifiers
1685 Version specifiers are strings to be parsed as period-separated lists of integers.
1686 I.e., in the example, @code{"0.2.1"} is to be interpreted,
1687 roughly speaking, as @code{(0 2 1)}.
1688 In particular, version @code{"0.2.1"} is interpreted the same as @code{"0.0002.1"},
1689 though the latter is not canonical and may lead to a warning being issued.
1690 Also, @code{"1.3"} and @code{"1.4"} are both strictly @code{uiop:version<} to @code{"1.30"},
1691 quite unlike what would have happened
1692 had the version strings been interpreted as decimal fractions.
1694 Instead of a string representing the version,
1695 the @code{:version} argument can be an expression that is resolved to
1696 such a string using the following trivial domain-specific language:
1697 in addition to being a literal string, it can be an expression of the form
1698 @code{(:read-file-form <pathname-or-string> [:at <access-at-specifier]>)},
1699 or @code{(:read-file-line <pathname-or-string> [:at
1700 <access-at-specifier]?>)}.
1701 As the name suggests, the former will be resolved by reading a form in the specified pathname
1702 (read as a subpathname of the current system if relative or a
1703 unix-namestring), and the latter by reading a line.
1704 You may use a @code{uiop:access-at} specifier
1705 with the @code{:at} keyword,
1706 by default the specifier is @code{0}, meaning the first form/line is
1708 For @code{:read-file-form},
1709 subforms can also be specified, with e.g. @code{(1 2 2)} specifying
1710 ``the third subform (index 2) of the third subform (index 2) of the second form (index 1)''
1711 in the file (mind the off-by-one error in the English language).
1713 System definers are encouraged to use version identifiers of the form
1714 @var{x}.@var{y}.@var{z} for
1715 major version, minor version and patch level,
1716 where significant API incompatibilities are signaled by an increased major number.
1718 @xref{Common attributes of components}.
1721 @cindex :require dependencies
1723 Use the implementation's own @code{require} to load the @var{module-name}.
1725 It is good taste to use @code{:if-feature @emph{:implementation-name}}
1726 rather than @code{#+@emph{implementation-name}}
1727 to only depend on the specified module on the specific implementation that provides it.
1728 @xref{if-feature-option}.
1730 @subsection Feature dependencies
1731 @cindex :feature dependencies
1733 A feature dependency is of the form
1734 @code{(:feature @var{feature-expression} @var{dependency})}
1735 If the @var{feature-expression} is satisfied by the running lisp at the
1736 time the system definition is parsed, then the @var{dependency} will be
1737 added to the system's dependencies. If the @var{feature-expression} is
1738 @emph{not} satisfied, then the feature dependency form is ignored.
1740 Note that this means that @code{:feature} @strong{cannot} be used to
1741 enforce a feature dependency for the system in question. I.e., it
1742 cannot be used to require that a feature hold in order for the system
1743 definition to be loaded. E.g., one cannot use @code{(:feature :sbcl)}
1744 to require that a system only be used on SBCL.
1746 Feature dependencies are not to be confused with the obsolete
1747 feature requirement (@pxref{The defsystem grammar,,feature requirement}), or
1748 with @code{if-feature}.
1750 @subsection Using logical pathnames
1751 @cindex logical pathnames
1753 We do not generally recommend the use of logical pathnames,
1754 especially not so to newcomers to Common Lisp.
1755 However, we do support the use of logical pathnames by old timers,
1756 when such is their preference.
1758 To use logical pathnames,
1759 you will have to provide a pathname object as a @code{:pathname} specifier
1760 to components that use it, using such syntax as
1761 @code{#p"LOGICAL-HOST:absolute;path;to;component.lisp"}.
1763 You only have to specify such logical pathname
1764 for your system or some top-level component.
1765 Sub-components' relative pathnames,
1766 specified using the string syntax for names,
1767 will be properly merged with the pathnames of their parents.
1768 The specification of a logical pathname host however is @emph{not}
1769 otherwise directly supported in the ASDF syntax
1770 for pathname specifiers as strings.
1772 The @code{asdf-output-translation} layer will
1773 avoid trying to resolve and translate logical pathnames.
1774 The advantage of this is that
1775 you can define yourself what translations you want to use
1776 with the logical pathname facility.
1777 The disadvantage is that if you do not define such translations,
1778 any system that uses logical pathnames will behave differently under
1779 asdf-output-translations than other systems you use.
1781 If you wish to use logical pathnames you will have to configure the
1782 translations yourself before they may be used.
1783 ASDF currently provides no specific support
1784 for defining logical pathname translations.
1786 Note that the reasons we do not recommend logical pathnames are that
1787 (1) there is no portable way to set up logical pathnames @emph{before} they are used,
1788 (2) logical pathnames are limited to only portably use
1789 a single character case, digits and hyphens.
1790 While you can solve the first issue on your own,
1791 describing how to do it on each of fifteen implementations supported by ASDF
1792 is more than we can document.
1793 As for the second issue, mind that the limitation is notably enforced on SBCL,
1794 and that you therefore can't portably violate the limitations
1795 but must instead define some encoding of your own and add individual mappings
1796 to name physical pathnames that do not fit the restrictions.
1797 This can notably be a problem when your Lisp files are part of a larger project
1798 in which it is common to name files or directories in a way that
1799 includes the version numbers of supported protocols,
1800 or in which files are shared with software written
1801 in different programming languages where conventions include the use of
1802 underscores, dots or CamelCase in pathnames.
1805 @subsection Serial dependencies
1806 @cindex serial dependencies
1808 If the @code{:serial t} option is specified for a module,
1809 ASDF will add dependencies for each child component,
1810 on all the children textually preceding it.
1811 This is done as if by @code{:depends-on}.
1815 :components ((:file "a") (:file "b") (:file "c"))
1821 :components ((:file "a")
1822 (:file "b" :depends-on ("a"))
1823 (:file "c" :depends-on ("a" "b")))
1827 @subsection Source location (@code{:pathname})
1829 The @code{:pathname} option is optional in all cases for systems
1830 defined via @code{defsystem}, and generally is unnecessary. In the
1831 simple case, source files will be found in the same directory as the
1832 system or, in the case of modules, in a subdirectory with the same name
1835 @c FIXME: This should be moved elsewhere -- it's too much detail for the
1838 More specifically, ASDF follows a hairy set of rules that are designed so that
1842 will load a system from disk
1843 and have its pathname default to the right place.
1846 This pathname information will not be overwritten with
1847 @code{*default-pathname-defaults*}
1848 (which could be somewhere else altogether)
1849 if the user loads up the @file{.asd} file into his editor
1850 and interactively re-evaluates that form.
1853 If a system is being loaded for the first time,
1854 its top-level pathname will be set to:
1858 The host/device/directory parts of @code{*load-truename*},
1861 @code{*default-pathname-defaults*}, otherwise.
1864 If a system is being redefined, the top-level pathname will be
1868 changed, if explicitly supplied or obtained from @code{*load-truename*}
1869 (so that an updated source location is reflected in the system definition)
1872 changed if it had previously been set from @code{*default-pathname-defaults*}
1875 left as before, if it had previously been set from @code{*load-truename*}
1876 and @code{*load-truename*} is currently unbound
1877 (so that a developer can evaluate a @code{defsystem} form
1878 from within an editor without clobbering its source location)
1881 @subsection if-feature option
1882 @cindex :if-feature component option
1883 @anchor{if-feature-option} @c redo if this ever becomes a node in
1886 This option allows you to specify a feature expression to be evaluated
1887 as if by @code{#+} to conditionally include a component in your build.
1888 If the expression is false, the component is dropped
1889 as well as any dependency pointing to it.
1890 As compared to using @code{#+} which is expanded at read-time,
1891 this allows you to have an object in your component hierarchy
1892 that can be used for manipulations beside building your project, and
1893 that is accessible to outside code that wishes to reason about system
1896 Programmers should be careful to consider @strong{when} the
1897 @code{:if-feature} is evaluated. Recall that ASDF first computes a
1898 build plan, and then executes that plan. ASDF will check to see whether
1899 or not a feature is present @strong{at planning time}, not during the
1900 build. It follows that one cannot use @code{:if-feature} to check
1901 features that are set during the course of the build. It can only be
1902 used to check the state of features before any build operations have
1905 This option was added in ASDF 3. For more information,
1906 @xref{required-features, Required features}.
1908 @subsection feature requirement
1909 This requirement was removed in ASDF 3.1. Please do not use it. In
1910 most cases, @code{:if-feature} (@pxref{if-feature-option}) will provide
1911 an adequate substitute.
1913 The @code{feature} requirement used to ensure that a chain of component
1914 dependencies would fail when a key feature was absent.
1915 Used in conjunction with @code{:if-component-dep-fails}
1917 a roundabout way to express conditional compilation.
1920 @node Other code in .asd files, The package-inferred-system extension, The defsystem grammar, Defining systems with defsystem
1921 @section Other code in .asd files
1923 Files containing @code{defsystem} forms
1924 are regular Lisp files that are executed by @code{load}.
1925 Consequently, you can put whatever Lisp code you like into these files.
1926 However, it is recommended to keep such forms to a minimal,
1927 and to instead define @code{defsystem} extensions
1928 that you use with @code{:defsystem-depends-on}.
1930 If however, you might insist on including code in the @file{.asd} file itself,
1931 e.g., to examine and adjust the compile-time environment,
1932 possibly adding appropriate features to @code{*features*}.
1933 If so, here are some conventions we recommend you follow,
1934 so that users can control certain details of execution
1935 of the Lisp in @file{.asd} files:
1939 Any informative output
1940 (other than warnings and errors,
1941 which are the condition system's to dispose of)
1942 should be sent to the standard CL stream @code{*standard-output*},
1943 so that users can easily control the disposition
1944 of output from ASDF operations.
1948 @node The package-inferred-system extension, , Other code in .asd files, Defining systems with defsystem
1949 @section The package-inferred-system extension
1951 Starting with release 3.1.2,
1952 ASDF supports a one-package-per-file style of programming,
1953 whereby each file is its own system,
1954 and dependencies are deduced from the @code{defpackage} form
1955 (or its variant @code{uiop:define-package}).
1957 In this style, packages refer to a system with the same name (downcased);
1958 and if a system is defined with @code{:class package-inferred-system},
1959 then system names that start with that name
1960 (using the slash @code{/} separator)
1961 refer to files under the filesystem hierarchy where the system is defined.
1962 For instance, if system @code{my-lib} is defined in
1963 @file{/foo/bar/my-lib/my-lib.asd}, then system @code{my-lib/src/utility}
1964 will be found in file @file{/foo/bar/my-lib/src/utility.lisp}.
1966 This style was made popular by @code{faslpath} and @code{quick-build} before,
1967 and at the cost of a stricter package discipline,
1968 seems to make for more maintainable code.
1969 It is used by ASDF itself (starting with ASDF 3), by @code{lisp-interface-library},
1970 and a few other libraries.
1972 To use this style, choose a toplevel system name, e.g. @code{my-lib},
1973 and create a file @file{my-lib.asd}
1974 with the @code{:class :package-inferred-system} option in its @code{defsystem}.
1977 #-asdf3.1 (error "my-lib requires ASDF 3.1")
1979 :class :package-inferred-system
1980 :depends-on ("my-lib/interface/all"
1982 "my-lib/extras/all")
1983 :in-order-to ((test-op (load-op "my-lib/test/all")))
1984 :perform (test-op (o c) (symbol-call :my-lib/test/all :test-suite)))
1986 (defsystem "my-lib/test" :depends-on ("my-lib/test/all"))
1988 (register-system-packages "my-lib/interface/all" '(:my-lib-interface))
1989 (register-system-packages "my-lib/src/all" '(:my-lib-implementation))
1990 (register-system-packages "my-lib/test/all" '(:my-lib-test))
1992 (register-system-packages
1994 '(:c2mop :closer-common-lisp :c2cl :closer-common-lisp-user :c2cl-user))
1997 In the code above, the first line checks that we are using ASDF 3.1,
1998 which provides @code{package-inferred-system}.
2000 The function @code{register-system-packages} has to be called to register
2001 packages used or provided by your system and its components
2002 where the name of the system that provides the package
2003 is not the downcase of the package name.
2005 Then, file @file{interface/order.lisp} under the @code{lil} hierarchy,
2006 that defines abstract interfaces for order comparisons,
2007 starts with the following form,
2008 dependencies being trivially computed from the @code{:use} and @code{:mix} clauses:
2011 (uiop:define-package :lil/interface/order
2012 (:use :closer-common-lisp
2013 :lil/interface/definition
2015 :lil/interface/eq :lil/interface/group)
2016 (:mix :fare-utils :uiop :alexandria)
2020 ASDF can tell that this file depends on system @code{closer-mop} (registered above),
2021 @code{lil/interface/definition}, @code{lil/interface/base},
2022 @code{lil/interface/eq}, and @code{lil/interface/group}
2023 (package and system names match, and they will be looked up hierarchically).
2025 ASDF also detects dependencies from @code{:import-from} clauses.
2026 You may thus import a well-defined set of symbols from an existing package
2027 as loaded from suitably named system;
2028 or if you prefer to use any such symbol fully qualified by a package prefix,
2029 you may declare a dependency on such a package and its corresponding system
2030 via an @code{:import-from} clause with an empty list of symbols, as in:
2033 (defpackage :foo/bar
2035 (:import-from :foo/baz #:sym1 #:sym2)
2036 (:import-from :foo/quux)
2040 The form @code{uiop:define-package} is supported as well as @code{defpackage},
2041 and has many options that prove useful in this context,
2042 such as @code{:use-reexport} and @code{:mix-reexport}
2043 that allow for ``inheritance'' of symbols being exported.
2045 Note that starting with ASDF 3.1.5.6 only, ASDF will look for source files under
2046 the @code{component-pathname} as specified via the @code{:pathname} option,
2047 whereas earlier versions ignore this option and use the @code{system-source-directory}
2048 where the @file{.asd} file resides.
2050 @c See this blog post about it:
2051 @c @url{http://davazp.net/2014/11/26/modern-library-with-asdf-and-package-inferred-system.html}
2054 @node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top
2055 @comment node-name, next, previous, up
2056 @chapter The Object model of ASDF
2060 ASDF is designed in an object-oriented way from the ground up.
2061 Both a system's structure and the operations that can be performed on systems
2062 follow an extensible protocol, allowing programmers to add new behaviours to ASDF.
2063 For example, @code{cffi} adds support for special FFI description files
2064 that interface with C libraries and for wrapper files that embed C code in Lisp.
2065 @code{asdf-jar} supports creating Java JAR archives in ABCL.
2066 @code{poiu} supports compiling code in parallel using background processes.
2068 The key classes in ASDF are @code{component} and @code{operation}.
2069 A @code{component} represents an individual source file or a group of source files,
2070 and the products (e.g., fasl files) produced from it.
2071 An @code{operation} represents a transformation that can be performed on a component,
2072 turning them from source files to intermediate results to final outputs.
2073 Components are related by @emph{dependencies}, specified in system
2076 When ordered to @code{operate} with some operation on a component (usually a system),
2077 ASDF will first compute a @emph{plan}
2078 by traversing the dependency graph using function @code{make-plan}.@footnote{
2079 Historically, the function that built a plan was
2080 called @code{traverse}, and returned a list of actions;
2081 it was deprecated in favor of @code{make-plan} (that returns a plan object)
2082 when the @code{plan} objects were introduced with ASDF 3;
2083 the old function is kept for backward compatibility and debugging purposes only,
2084 and may be removed in the near future.
2086 The resulting plan object contains an ordered list of @emph{actions}.
2087 An action is a pair of an @code{operation} and a @code{component},
2088 representing a particular build step to be @code{perform}ed.
2089 The ordering of the plan ensures that no action is performed before
2090 all its dependencies have been fulfilled.@footnote{
2091 The term @emph{action}
2092 was used by Kent Pitman in his article, ``The Description of Large Systems,''
2093 (@pxref{Bibliography}),
2094 and we suspect might be traced to @code{make}.
2095 Although the term was only used by ASDF hackers starting with ASDF 2,
2096 the concept was there since the very beginning of ASDF 1,
2097 just not clearly articulated.
2100 In this chapter, we describe ASDF's object-oriented protocol,
2101 the classes that make it up, and the generic functions on those classes.
2102 These generic functions often take
2103 both an operation and a component as arguments:
2104 much of the power and configurability of ASDF is provided by
2105 this use of CLOS's multiple dispatch.
2106 We will describe the built-in component and operation classes, and
2107 explain how to extend the ASDF protocol by defining new classes and
2108 methods for ASDF's generic functions.
2109 We will also describe the many @emph{hooks} that can be configured to
2110 customize the behaviour of existing @emph{functions}.
2112 @c FIXME: Swap operations and components.
2113 @c FIXME: Possibly add a description of the PLAN object.
2114 @c Not critical, since the user isn't expected to interact with it.
2122 @node Operations, Components, The object model of ASDF, The object model of ASDF
2123 @comment node-name, next, previous, up
2127 An @dfn{operation} object of the appropriate type is instantiated
2128 whenever the user wants to do something with a system like
2131 @item compile all its files
2132 @item load the files into a running lisp environment
2133 @item copy its source files somewhere else
2136 Operations can be invoked directly, or examined
2137 to see what their effects would be without performing them.
2138 There are a bunch of methods specialised on operation and component type
2139 that actually do the grunt work.
2140 Operations are invoked on systems via @code{operate} (@pxref{operate}).
2142 ASDF contains a number of pre-defined @t{operation} classes for common,
2143 and even fairly uncommon tasks that you might want to do with it.
2144 In addition, ASDF contains ``abstract'' @t{operation} classes that
2145 programmers can use as building blocks to define ASDF extensions. We
2146 discuss these in turn below.
2148 @c The operation object contains whatever state is relevant for this purpose
2149 @c (perhaps a list of visited nodes, for example)
2150 @c but primarily is a nice thing to specialise operation methods on
2151 @c and easier than having them all be @code{EQL} methods.
2154 * Predefined operations of ASDF::
2155 * Creating new operations::
2158 Operations are invoked on systems via @code{operate}.
2160 @deffn {Generic function} @code{operate} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @code{force} @code{force-not} @code{verbose} @AallowOtherKeys
2161 @deffnx {Generic function} @code{oos} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @AallowOtherKeys{}
2162 @code{operate} invokes @var{operation} on @var{system}.
2163 @code{oos} is a synonym for @code{operate} (it stands for operate-on-system).
2165 @var{operation} is an operation designator:
2166 it can be an operation object itself, or, typically,
2167 a symbol that is passed to @code{make-operation} (which will call @code{make-instance}),
2168 to create the operation object.
2169 @var{component} is a component designator:
2170 it can be a component object itself, or, typically,
2171 a string or symbol (to be @code{string-downcase}d) that names a system,
2172 more rarely a list of strings or symbols that designate a subcomponent of a system.
2174 The ability to pass @var{initargs} to @code{make-operation} is now deprecated, and will be removed.
2175 For more details, @pxref{make-operation}.
2176 Note that dependencies may cause the operation
2177 to invoke other operations on the system or its components:
2178 the new operations may or may not be created
2179 with the same @var{initargs} as the original one (for the moment).
2181 If @var{force} is @code{:all}, then all systems
2182 are forced to be recompiled even if not modified since last compilation.
2183 If @var{force} is @code{t}, then only the system being loaded
2184 is forced to be recompiled even if not modified since last compilation,
2185 but other systems are not affected.
2186 If @var{force} is a list, then it specifies a list of systems that
2187 are forced to be recompiled even if not modified since last compilation.
2188 If @var{force-not} is @code{:all}, then all systems
2189 are forced not to be recompiled even if modified since last compilation.
2190 If @var{force-not} is @code{t}, then all systems but the system being loaded
2191 are forced not to be recompiled even if modified since last compilation
2192 (note: this was changed in ASDF 3.1.2).
2193 If @var{force-not} is a list, then it specifies a list of systems that
2194 are forced not to be recompiled even if modified since last compilation.
2196 @findex register-immutable-system
2197 @cindex immutable systems
2198 Both @var{force} and @var{force-not} apply to systems that are dependencies and were already compiled.
2199 @var{force-not} takes precedences over @var{force},
2200 as it should, really, but unhappily only since ASDF 3.1.2.
2201 Moreover, systems which have been registered as immutable by @code{register-immutable-system} (since ASDF 3.1.5)
2202 are always considered @var{forced-not}, and even their @file{.asd} are not refreshed from the filesystem.
2203 @xref{Miscellaneous Functions}.
2206 To see what @code{operate} would do, you can use:
2208 (asdf:traverse operation-class system-name)
2213 @defun @code{make-operation} @var{operation-class} @Arest{} @var{initargs}
2214 @anchor{make-operation}
2216 The @var{initargs} are passed to @code{make-instance} call
2217 when creating the operation object.
2219 @strong{Note:}@var{initargs} for @code{operation}s are now deprecated,
2220 and will be removed from ASDF in the near future.
2222 @strong{Note:} @code{operation} instances must @strong{never} be created
2223 using @code{make-instance} directly: only through
2224 @code{make-operation}. Attempts to directly make @code{operation}
2225 instances will cause a run-time error.
2229 @node Predefined operations of ASDF, Creating new operations, Operations, Operations
2230 @comment node-name, next, previous, up
2231 @subsection Predefined operations of ASDF
2232 @c FIXME: All these deffn's should be replaced with deftyp. Also, we
2233 @c should set up an appropriate index.
2235 All the operations described in this section are in the @code{asdf} package.
2236 They are invoked via the @code{operate} generic function.
2239 (asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
2242 @deffn Operation @code{compile-op}
2244 This operation compiles the specified component.
2245 A @code{cl-source-file} will be @code{compile-file}'d.
2246 All the children and dependencies of a system or module
2247 will be recursively compiled by @code{compile-op}.
2249 @code{compile-op} depends on @code{prepare-op} which
2250 itself depends on a @code{load-op} of all of a component's dependencies,
2251 as well as of its parent's dependencies.
2252 When @code{operate} is called on @code{compile-op},
2253 all these dependencies will be loaded as well as compiled;
2254 yet, some parts of the system main remain unloaded,
2255 because nothing depends on them.
2256 Use @code{load-op} to load a system.
2259 @deffn Operation @code{load-op}
2261 This operation loads the compiled code for a specified component.
2262 A @code{cl-source-file} will have its compiled fasl @code{load}ed,
2263 which fasl is the output of @code{compile-op} that @code{load-op} depends on.
2265 @code{load-op} will recursively load all the children of a system or module.
2267 @code{load-op} also depends on @code{prepare-op} which
2268 itself depends on a @code{load-op} of all of a component's dependencies,
2269 as well as of its parent's dependencies.
2272 @deffn Operation @code{prepare-op}
2274 This operation ensures that the dependencies of a component
2275 and its recursive parents are loaded (as per @code{load-op}),
2276 as a prerequisite before @code{compile-op} and @code{load-op} operations
2277 may be performed on a given component.
2280 @deffn Operation @code{load-source-op}, @code{prepare-source-op}
2282 @code{load-source-op} will load the source for the files in a module
2283 rather than the compiled fasl output.
2284 It has a @code{prepare-source-op} analog to @code{prepare-op},
2285 that ensures the dependencies are themselves loaded via @code{load-source-op}.
2290 @deffn Operation @code{test-op}
2292 This operation will perform some tests on the module.
2293 The default method will do nothing.
2294 The default dependency is to require
2295 @code{load-op} to be performed on the module first.
2296 Its default @code{operation-done-p} method returns @code{nil},
2297 which means that the operation is @emph{never} done
2299 we assume that if you invoke the @code{test-op},
2300 you want to test the system, even if you have already done so.
2302 The results of this operation are not defined by ASDF.
2303 It has proven difficult to define how the test operation
2304 should signal its results to the user
2305 in a way that is compatible with all of the various test libraries
2306 and test techniques in use in the community, and
2307 given the fact that ASDF operations do not return a value indicating
2309 For those willing to go to the effort, we suggest defining conditions to
2310 signal when a @code{test-op} fails, and storing in those conditions
2311 information that describes which tests fail.
2313 People typically define a separate test @emph{system} to hold the tests.
2314 Doing this avoids unnecessarily adding a test framework as a dependency
2315 on a library. For example, one might have
2318 :in-order-to ((test-op (test-op "foo/test")))
2321 (defsystem "foo/test"
2322 :depends-on ("foo" "fiveam") ; fiveam is a test framework library
2326 Then one defines @code{perform} methods on
2327 @code{test-op} such as the following:
2329 (defsystem "foo/test"
2330 :depends-on ("foo" "fiveam") ; fiveam is a test framework library
2331 :perform (test-op (o s)
2332 (uiop:symbol-call :fiveam '#:run!
2333 (uiop:find-symbol* '#:foo-test-suite
2342 @deffn Operation @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op}, @code{lib-op}, @code{monolithic-lib-op}, @code{dll-op}, @code{monolithic-dll-op}, @code{image-op}, @code{program-op}
2344 These are ``bundle'' operations, that can create a single-file ``bundle''
2345 for all the contents of each system in an application,
2346 or for the entire application.
2348 @code{compile-bundle-op} will create a single fasl file for each of the systems needed,
2349 grouping all its many fasls in one,
2350 so you can deliver each system as a single fasl
2351 @code{monolithic-compile-bundle-op} will create a single fasl file for the target system
2352 and all its dependencies,
2353 so you can deliver your entire application as a single fasl.
2354 @code{load-bundle-op} will load the output of @code{compile-bundle-op}.
2355 Note that if it the output is not up-to-date,
2356 @code{compile-bundle-op} may load the intermediate fasls as a side-effect.
2357 Bundling fasls together matters a lot on ECL,
2358 where the dynamic linking involved in loading tens of individual fasls
2359 can be noticeably more expensive than loading a single one.
2361 NB: @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op} were respectively called
2362 @code{fasl-op}, @code{monolithic-fasl-op}, @code{load-fasl-op}, @code{monolithic-load-fasl-op}, @code{binary-op}, @code{monolithic-binary-op} before ASDF 3.1.
2363 The old names still exist for backward compatibility,
2364 though they poorly label what is going on.
2366 Once you have created a fasl with @code{compile-bundle-op},
2367 you can use @code{precompiled-system} to deliver it in a way
2368 that is compatible with clients having dependencies on your system,
2369 whether it is distributed as source or as a single binary;
2370 the @file{.asd} file to be delivered with the fasl will look like this:
2372 (defsystem :mysystem :class :precompiled-system
2373 :fasl (some expression that will evaluate to a pathname))
2375 Or you can use @code{deliver-asd-op} to let ASDF create such a system for you
2376 as well as the @code{compile-bundle-op} output,
2377 or @code{monolithic-deliver-asd-op}.
2378 This allows you to deliver code for your systems or applications
2380 Of course, if you want to test the result in the current image,
2381 @emph{before} you try to use any newly created @file{.asd} files,
2382 you should not forget to @code{(asdf:clear-configuration)}
2383 or at least @code{(asdf:clear-source-registry)},
2384 so it re-populates the source-registry from the filesystem.
2386 The @code{program-op} operation will create an executable program
2387 from the specified system and its dependencies.
2388 You can use UIOP for its pre-image-dump hooks, its post-image-restore hooks,
2389 and its access to command-line arguments.
2390 And you can specify an entry point @code{my-app:main}
2391 by specifying in your @code{defsystem}
2392 the option @code{:entry-point "my-app:main"}.
2393 Depending on your implementation,
2394 running @code{(asdf:operate 'asdf:program-op :my-app)}
2395 may quit the current Lisp image upon completion.
2397 @file{test/hello-world-example.asd} and @file{test/hello.lisp},
2398 as built and tested by
2399 @file{test/test-program.script} and @file{test/make-hello-world.lisp}.
2400 @code{image-op} will dump an image that may not be standalone
2401 and does not start its own function,
2402 but follows the usual execution convention of the underlying Lisp,
2403 just with more code pre-loaded,
2404 for use as an intermediate build result or with a wrapper invocation script.
2406 There is also @code{lib-op}
2407 for building a linkable @file{.a} file (Windows: @file{.lib})
2408 from all linkable object dependencies (FFI files, and on ECL, Lisp files too),
2409 and its monolithic equivalent @code{monolithic-lib-op}.
2410 And there is also @code{dll-op}
2411 (respectively its monolithic equivalent @code{monolithic-lib-op})
2412 for building a linkable @file{.so} file
2413 (Windows: @file{.dll}, MacOS X: @file{.dynlib})
2414 to create a single dynamic library
2415 for all the extra FFI code to be linked into each of your systems
2416 (respectively your entire application).
2418 All these ``bundle'' operations are available since ASDF 3
2419 on all actively supported Lisp implementations,
2420 but may be unavailable on unmaintained legacy implementations.
2421 This functionality was previously available for select implementations,
2422 as part of a separate system @code{asdf-bundle},
2423 itself descended from the ECL-only @code{asdf-ecl}.
2425 The pathname of the output of bundle operations
2426 is subject to output-translation as usual,
2427 unless the operation is equal to
2428 the @code{:build-operation} argument to @code{defsystem}.
2429 This behaviour is not very satisfactory and may change in the future.
2430 Maybe you have suggestions on how to better configure it?
2433 @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}
2435 These operations, as their respective names indicate,
2436 will concatenate all the @code{cl-source-file} source files in a system
2437 (or in a system and all its dependencies, if monolithic),
2438 in the order defined by dependencies,
2439 then load the result, or compile and then load the result.
2441 These operations are useful to deliver a system or application
2442 as a single source file,
2443 and for testing that said file loads properly, or compiles and then loads properly.
2445 ASDF itself is delivered as a single source file this way,
2446 using @code{monolithic-concatenate-source-op},
2447 prepending a prelude and the @code{uiop} library
2448 before the @code{asdf/defsystem} system itself.
2452 @node Creating new operations, , Predefined operations of ASDF, Operations
2453 @comment node-name, next, previous, up
2454 @subsection Creating new operations
2456 ASDF was designed to be extensible in an object-oriented fashion.
2457 To teach ASDF new tricks, a programmer can implement the behaviour he wants
2458 by creating a subclass of @code{operation}.
2460 ASDF's pre-defined operations are in no way ``privileged'',
2461 but it is requested that developers never use the @code{asdf} package
2462 for operations they develop themselves.
2463 The rationale for this rule is that we don't want to establish a
2464 ``global asdf operation name registry'',
2465 but also want to avoid name clashes.
2467 Your operation @emph{must} usually provide methods
2468 for one or more of the following generic functions:
2473 @item @code{perform}
2474 Unless your operation, like @code{prepare-op},
2475 is for dependency propagation only,
2476 the most important function for which to define a method
2477 is usually @code{perform},
2478 which will be called to perform the operation on a specified component,
2479 after all dependencies have been performed.
2481 The @code{perform} method must call @code{input-files} and @code{output-files} (see below)
2482 to locate its inputs and outputs,
2483 because the user is allowed to override the method
2484 or tweak the output-translation mechanism.
2485 Perform should only use the primary value returned by @code{output-files}.
2486 If one and only one output file is expected,
2487 it can call @code{output-file} that checks that this is the case
2488 and returns the first and only list element.
2490 @findex output-files
2491 @item @code{output-files}
2492 If your perform method has any output,
2493 you must define a method for this function.
2494 for ASDF to determine where the outputs of performing operation lie.
2496 Your method may return two values, a list of pathnames, and a boolean.
2497 If the boolean is @code{nil} (or you fail to return multiple values),
2498 then enclosing @code{:around} methods may translate these pathnames,
2499 e.g. to ensure object files are somehow stored
2500 in some implementation-dependent cache.
2501 If the boolean is @code{t} then the pathnames are marked
2502 not be translated by the enclosing @code{:around} method.
2504 @findex component-depends-on
2505 @item @code{component-depends-on}
2506 If the action of performing the operation on a component has dependencies,
2507 you must define a method on @code{component-depends-on}.
2509 Your method will take as specialized arguments
2510 an operation and a component which together identify an action,
2511 and return a list of entries describing actions that this action depends on.
2512 The format of entries is described below.
2514 It is @emph{strongly} advised that
2515 you should always append the results of @code{(call-next-method)}
2516 to the results of your method,
2517 or ``interesting'' failures will likely occur,
2518 unless you're a true specialist of ASDF internals.
2519 It is unhappily too late to compatibly use the @code{append} method combination,
2520 but conceptually that's the protocol that is being manually implemented.
2522 Each entry returned by @code{component-depends-on} is itself a list.
2524 The first element of an entry is an operation designator:
2525 either an operation object designating itself, or
2526 a symbol that names an operation class
2527 (that ASDF will instantiate using @code{make-operation}).
2528 For instance, @code{load-op}, @code{compile-op} and @code{prepare-op}
2529 are common such names, denoting the respective operations.
2531 @c FIXME COERCE-NAME is referenced, but not defined.
2533 @findex find-component
2534 The rest of each entry is a list of component designators:
2535 either a component object designating itself,
2536 or an identifier to be used with @code{find-component}.
2537 @code{find-component} will be called with the current component's parent as parent,
2538 and the identifier as second argument.
2539 The identifier is typically a string,
2540 a symbol (to be downcased as per @code{coerce-name}),
2541 or a list of strings or symbols.
2542 In particular, the empty list @code{nil} denotes the parent itself.
2546 An operation @emph{may} provide methods for the following generic functions:
2550 @item @code{input-files}
2552 A method for this function is often not needed,
2553 since ASDF has a pretty clever default @code{input-files} mechanism.
2554 You only need create a method if there are multiple ultimate input
2556 Most operations inherit from @code{selfward-operation}, which
2557 appropriately sets the input-files to include the source file itself.
2559 @c FIXME: Add documentation of built-in operation types.
2561 @defun input-files operation component
2562 Return a list of pathnames that represent the input to @var{operation}
2563 performed on @var{component}.
2566 @item @code{operation-done-p}
2567 @findex operation-done-p
2568 You only need to define a method on that function
2569 if you can detect conditions that invalidate previous runs of the operation,
2570 even though no filesystem timestamp has changed,
2571 in which case you return @code{nil} (the default is @code{t}).
2573 For instance, the method for @code{test-op} always returns @code{nil},
2574 so that tests are always run afresh.
2575 Of course, the @code{test-op} for your system could depend
2576 on a deterministically repeatable @code{test-report-op},
2577 and just read the results from the report files,
2578 in which case you could have this method return @code{t}.
2582 Operations that print output should send that output to the standard
2583 CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
2585 @node Components, Dependencies, Operations, The object model of ASDF
2586 @comment node-name, next, previous, up
2590 @cindex system designator
2591 @cindex component designator
2592 @vindex *system-definition-search-functions*
2594 A @code{component} represents an individual source file or a group of source files,
2595 and the things that get transformed into.
2596 A @code{system} is a component at the top level of the component hierarchy,
2597 that can be found via @code{find-system}.
2598 A @code{source-file} is a component representing a single source-file
2599 and the successive output files into which it is transformed.
2600 A @code{module} is an intermediate component itself grouping several other components,
2601 themselves source-files or further modules.
2603 A @dfn{system designator} is a system itself,
2604 or a string or symbol that behaves just like any other component name
2605 (including with regard to the case conversion rules for component names).
2607 A @dfn{component designator}, relative to a base component,
2608 is either a component itself,
2609 or a string or symbol,
2610 or a list of designators.
2612 @defun find-system system-designator @Aoptional{} (error-p t)
2614 Given a system designator, @code{find-system} finds and returns a system.
2615 If no system is found, an error of type
2616 @code{missing-component} is thrown,
2617 or @code{nil} is returned if @code{error-p} is false.
2619 To find and update systems, @code{find-system} funcalls each element
2620 in the @code{*system-definition-search-functions*} list,
2621 expecting a pathname to be returned, or a system object,
2622 from which a pathname may be extracted, and that will be registered.
2623 The resulting pathname (if any) is loaded
2624 if one of the following conditions is true:
2628 there is no system of that name in memory
2630 the pathname is different from that which was previously loaded
2632 the file's @code{last-modified} time exceeds the @code{last-modified} time
2633 of the system in memory
2636 @cindex ASDF-USER package
2637 When system definitions are loaded from @file{.asd} files,
2638 they are implicitly loaded into the @code{ASDF-USER} package,
2639 which uses @code{ASDF}, @code{UIOP} and @code{UIOP/COMMON-LISP}@footnote{
2640 Note that between releases 2.27 and 3.0.3, only @code{UIOP/PACKAGE},
2641 not all of @code{UIOP}, was used; if you want your code to work
2642 with releases earlier than 3.1.2, you may have to explicitly define a package
2643 that uses @code{UIOP}, or use proper package prefix to your symbols, as in
2644 @code{uiop:version<}.}
2645 Programmers who do anything non-trivial in a @file{.asd} file,
2646 such as defining new variables, functions or classes,
2647 should include @code{defpackage} and @code{in-package} forms in this file,
2648 so they will not overwrite each others' extensions.
2649 Such forms might also help the files behave identically
2650 if loaded manually with @code{cl:load} for development or debugging,
2651 though we recommend you use the function @code{asdf::load-asd} instead,
2652 which the @code{slime-asdf} contrib knows about.
2654 The default value of @code{*system-definition-search-functions*}
2655 is a list of three functions.
2656 The first function looks in each of the directories given
2657 by evaluating members of @code{*central-registry*}
2658 for a file whose name is the name of the system and whose type is @file{asd};
2659 the first such file is returned,
2660 whether or not it turns out to actually define the appropriate system.
2661 The second function does something similar,
2662 for the directories specified in the @code{source-registry},
2663 but searches the filesystem only once and caches its results.
2664 The third function makes the @code{package-inferred-system} extension work,
2665 @pxref{The package-inferred-system extension}.
2667 Because of the way these search functions are defined,
2668 you should put the definition for a system
2669 @var{foo} in a file named @file{foo.asd},
2670 in a directory that is
2671 in the central registry or
2672 which can be found using the
2673 source registry configuration.
2675 @c FIXME: Move this discussion to the system definition grammar, or somewhere else.
2676 @anchor{System names}
2677 @cindex System names
2678 @cindex Primary system name
2679 @findex primary-system-name
2680 It is often useful to define multiple systems in a same file,
2681 but ASDF can only locate a system's definition file based on the system
2684 ASDF 3's system search algorithm has been extended to
2685 allow a file @file{foo.asd} to contain
2686 secondary systems named @var{foo/bar}, @var{foo/baz}, @var{foo/quux}, etc.,
2687 in addition to the primary system named @var{foo}.
2688 The first component of a system name,
2689 separated by the slash character, @code{/},
2690 is called the primary name of a system.
2691 The primary name may be
2692 extracted by function @code{asdf::primary-system-name};
2693 when ASDF 3 is told to find a system whose name has a slash,
2694 it will first attempt to load the corresponding primary system,
2695 and will thus see any such definitions, and/or any
2696 definition of a @code{package-inferred-system}.@footnote{
2697 ASDF 2.26 and earlier versions
2698 do not support this primary system name convention.
2699 With these versions of ASDF
2700 you must explicitly load @file{foo.asd}
2701 before you can use system @var{foo/bar} defined therein,
2702 e.g. using @code{(asdf:find-system "foo")}.
2703 We do not support ASDF 2, and recommend that you should upgrade to ASDF 3.
2705 If your file @file{foo.asd} also defines systems
2706 that do not follow this convention, e.g., a system named @var{foo-test},
2707 ASDF will not be able to automatically locate a definition for these systems,
2708 and will only see their definition
2709 if you explicitly find or load the primary system
2710 using e.g. @code{(asdf:find-system "foo")} before you try to use them.
2711 We strongly recommend against this practice,
2712 though it is currently supported for backward compatibility.
2716 @defun primary-system-name name
2718 Internal (not exported) function, @code{asdf::primary-system-name}.
2719 Returns the primary system name (the portion before
2720 the slash, @code{/}, in a secondary system name) from @var{name}.
2724 @defun locate-system name
2726 This function should typically @emph{not} be invoked directly. It is
2727 exported as part of the API only for programmers who wish to provide
2728 their own @code{*system-definition-search-functions*}.
2730 Given a system @var{name} designator,
2731 try to locate where to load the system definition from.
2732 @c (This does not include the loading of the system definition,
2733 @c which is done by @code{find-system},
2734 @c or the loading of the system itself, which is done by @code{load-system};
2735 @c however, for systems the definition of which has already been loaded,
2736 @c @code{locate-system} may return an object of class @code{system}.)
2737 Returns five values: @var{foundp}, @var{found-system}, @var{pathname},
2738 @var{previous}, and @var{previous-time}.
2739 @var{foundp} is true when a system was found,
2740 either a new as yet unregistered one, or a previously registered one.
2741 The @var{found-system} return value
2742 will be a @code{system} object, if a system definition is found in your
2744 @c This system may be registered (by @code{register-system}) or may not, if
2745 @c it's preloaded code. Fare writes:
2746 @c In the case of preloaded code, as for "asdf", "uiop", etc.,
2747 @c themselves, the system objects are not registered until after they are
2748 @c initially located by sysdef-preloaded-system-search as a fallback when
2749 @c no source code was found.
2750 The system definition will @emph{not} be
2751 loaded if it hasn't been loaded already.
2752 @var{pathname} when not null is a path from which to load the system,
2753 either associated with @var{found-system}, or with the @var{previous} system.
2754 If @var{previous} is not null, it will be a @emph{previously loaded}
2755 @code{system} object of the same name (note that the system
2756 @emph{definition} is previously-loaded: the system itself may or may not be).
2757 @var{previous-time} when not null is
2758 the timestamp of the previous system definition file, at the
2759 time when the @var{previous} system definition was loaded.
2761 For example, if your current registry has @file{foo.asd} in
2762 @file{/current/path/to/foo.asd},
2763 but system @code{foo} was previously loaded from @file{/previous/path/to/foo.asd}
2764 then @var{locate-system} will return the following values:
2767 @var{foundp} will be @code{t},
2769 @var{found-system} will be @code{nil},
2771 @var{pathname} will be @code{#p"/current/path/to/foo.asd"},
2773 @var{previous} will be an object of type @code{SYSTEM} with
2774 @code{system-source-file} slot value of
2775 @code{#p"/previous/path/to/foo.asd"}
2777 @var{previous-time} will be the timestamp of
2778 @code{#p"/previous/path/to/foo.asd"} at the time it was loaded.
2782 @defun find-component base path
2784 Given a @var{base} component (or designator for such),
2785 and a @var{path}, find the component designated by the @var{path}
2786 starting from the @var{base}.
2788 If @var{path} is a component object, it designates itself,
2789 independently from the base.
2792 If @var{path} is a string, or symbol denoting a string via @code{coerce-name},
2793 then @var{base} is resolved to a component object,
2794 which must be a system or module,
2795 and the designated component is the child named by the @var{path}.
2797 If @var{path} is a @code{cons} cell,
2798 @code{find-component} with the base and the @code{car} of the @var{path},
2799 and the resulting object is used as the base for a tail call
2800 to @code{find-component} with the @code{car} of the @var{path}.
2802 If @var{base} is a component object, it designates itself.
2804 If @var{base} is null, then @var{path} is used as the base, with @code{nil} as the path.
2806 If @var{base} is a string, or symbol denoting a string via @code{coerce-name},
2807 it designates a system as per @code{find-system}.
2809 If @var{base} is a @code{cons} cell, it designates the component found by
2810 @code{find-component} with its @code{car} as base and @code{cdr} as path.
2815 * Common attributes of components::
2816 * Pre-defined subclasses of component::
2817 * Creating new component types::
2820 @node Common attributes of components, Pre-defined subclasses of component, Components, Components
2821 @comment node-name, next, previous, up
2822 @subsection Common attributes of components
2824 All components, regardless of type, have the following attributes.
2825 All attributes except @code{name} are optional.
2829 A component name is a string or a symbol.
2830 If a symbol, its name is taken and lowercased. This translation is
2831 performed by the exported function @code{coerce-name}.
2833 Unless overridden by a @code{:pathname} attribute,
2834 the name will be interpreted as a pathname specifier according
2835 to a Unix-style syntax.
2836 @xref{The defsystem grammar,,Pathname specifiers}.
2838 @subsubsection Version identifier
2839 @findex version-satisfies
2842 This optional attribute specifies a version for the current component.
2843 The version should typically be a string of integers separated by dots,
2844 for example @samp{1.0.11}.
2845 For more information on version specifiers, see @ref{The defsystem grammar}.
2847 A version may then be queried by the generic function @code{version-satisfies},
2848 to see if @code{:version} dependencies are satisfied,
2849 and when specifying dependencies, a constraint of minimal version to satisfy
2850 can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
2852 Note that in the wild, we typically see version numbering
2853 only on components of type @code{system}.
2854 Presumably it is much less useful within a given system,
2855 wherein the library author is responsible to keep the various files in synch.
2857 @subsubsection Required features
2858 @anchor{required-features}
2860 Traditionally defsystem users have used @code{#+} reader conditionals
2861 to include or exclude specific per-implementation files.
2862 For example, CFFI, the portable C foreign function interface contained
2865 #+sbcl (:file "cffi-sbcl")
2867 An unfortunate side effect of this approach is that no single
2868 implementation can read the entire system.
2869 This causes problems if, for example, one wished to design an @code{archive-op}
2870 that would create an archive file containing all the sources, since
2871 for example the file @code{cffi-sbcl.lisp} above would be invisible when
2872 running the @code{archive-op} on any implementation other than SBCL.
2874 Starting with ASDF 3,
2875 components may therefore have an @code{:if-feature} option.
2876 The value of this option should be
2877 a feature expression using the same syntax as @code{#+} does.
2878 If that feature expression evaluates to false, any reference to the component will be ignored
2879 during compilation, loading and/or linking.
2880 Since the expression is read by the normal reader,
2881 you must explicitly prefix your symbols with @code{:} so they be read as keywords;
2882 this is as contrasted with the @code{#+} syntax
2883 that implicitly reads symbols in the keyword package by default.
2885 For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
2886 the given component is only to be compiled and loaded
2887 when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
2888 You cannot write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
2889 since the symbols would not be read as keywords.
2891 @xref{if-feature-option}.
2893 @subsubsection Dependencies
2895 This attribute specifies dependencies of the component on its siblings.
2896 It is optional but often necessary.
2898 There is an excitingly complicated relationship between the initarg
2899 and the method that you use to ask about dependencies
2901 Dependencies are between (operation component) pairs.
2902 In your initargs for the component, you can say
2905 :in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
2906 (load-op (load-op "foo")))
2909 This means the following things:
2912 before performing compile-op on this component, we must perform
2913 load-op on @var{a} and @var{b}, and compile-op on @var{c},
2915 before performing @code{load-op}, we have to load @var{foo}
2918 The syntax is approximately
2921 (this-op @{(other-op required-components)@}+)
2923 simple-component-name := string
2926 required-components := simple-component-name
2927 | (required-components required-components)
2929 component-name := simple-component-name
2930 | (:version simple-component-name minimum-version-object)
2935 This is on a par with what ACL defsystem does.
2936 mk-defsystem is less general: it has an implied dependency
2939 for all source file x, (load x) depends on (compile x)
2942 and using a @code{:depends-on} argument to say that @var{b} depends on
2943 @var{a} @emph{actually} means that
2946 (compile b) depends on (load a)
2949 This is insufficient for e.g. the McCLIM system, which requires that
2950 all the files are loaded before any of them can be compiled ]
2954 In ASDF, the dependency information for a given component and operation
2955 can be queried using @code{(component-depends-on operation component)},
2956 which returns a list
2959 ((load-op "a") (load-op "b") (compile-op "c") ...)
2962 @code{component-depends-on} can be subclassed for more specific
2963 component/operation types: these need to @code{(call-next-method)}
2964 and append the answer to their dependency, unless
2965 they have a good reason for completely overriding the default dependencies.
2967 If it weren't for CLISP, we'd be using @code{LIST} method
2968 combination to do this transparently.
2969 But, we need to support CLISP.
2970 If you have the time for some CLISP hacking,
2971 I'm sure they'd welcome your fixes.
2972 @c Doesn't CLISP now support LIST method combination?
2974 A minimal version can be specified for a component you depend on
2975 (typically another system), by specifying @code{(:version "other-system" "1.2.3")}
2976 instead of simply @code{"other-system"} as the dependency.
2977 See the discussion of the semantics of @code{:version}
2978 in the defsystem grammar.
2980 @c FIXME: Should have cross-reference to "Version specifiers" in the
2981 @c defsystem grammar, but the cross-referencing is so broken by
2982 @c insufficient node breakdown that I have not put one in.
2985 @subsubsection pathname
2987 This attribute is optional and if absent (which is the usual case),
2988 the component name will be used.
2990 @xref{The defsystem grammar,,Pathname specifiers},
2991 for an explanation of how this attribute is interpreted.
2993 Note that the @code{defsystem} macro (used to create a ``top-level'' system)
2994 does additional processing to set the filesystem location of
2995 the top component in that system.
2996 This is detailed elsewhere. @xref{Defining systems with defsystem}.
2998 To find the CL pathname corresponding to a component, use
3000 @defun component-pathname component
3001 Returns the pathname corresponding to @var{component}. For components
3002 such as source files, this will be a filename pathname. For example:
3005 CL-USER> (asdf:component-pathname (asdf:find-system "xmls"))
3006 #P"/Users/rpg/lisp/xmls/"
3012 CL-USER> (asdf:component-pathname
3013 (asdf:find-component
3014 (asdf:find-system "xmls") "xmls"))
3015 #P"/Users/rpg/lisp/xmls/xmls.lisp"
3022 @subsubsection properties
3024 This attribute is optional.
3026 Packaging systems often require information about files or systems
3027 in addition to that specified by ASDF's pre-defined component attributes.
3028 Programs that create vendor packages out of ASDF systems therefore
3029 have to create ``placeholder'' information to satisfy these systems.
3030 Sometimes the creator of an ASDF system may know the additional
3031 information and wish to provide it directly.
3033 @code{(component-property component property-name)} and
3034 associated @code{setf} method will allow
3035 the programmatic update of this information.
3036 Property names are compared as if by @code{EQL},
3037 so use symbols or keywords or something.
3040 * Pre-defined subclasses of component::
3041 * Creating new component types::
3044 @node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
3045 @comment node-name, next, previous, up
3046 @subsection Pre-defined subclasses of component
3048 @deffn Component source-file
3050 A source file is any file that the system does not know how to
3051 generate from other components of the system.
3053 Note that this is not necessarily the same thing as
3054 ``a file containing data that is typically fed to a compiler''.
3055 If a file is generated by some pre-processor stage
3056 (e.g. a @file{.h} file from @file{.h.in} by autoconf)
3057 then it is not, by this definition, a source file.
3058 Conversely, we might have a graphic file
3059 that cannot be automatically regenerated,
3060 or a proprietary shared library that we received as a binary:
3061 these do count as source files for our purposes.
3063 Subclasses of source-file exist for various languages.
3064 @emph{FIXME: describe these.}
3067 @deffn Component module
3069 A module is a collection of sub-components.
3071 A module component has the following extra initargs:
3075 @code{:components} the components contained in this module
3078 @code{:default-component-class}
3079 All children components which don't specify their class explicitly
3080 are inferred to be of this type.
3083 @code{:if-component-dep-fails}
3084 This attribute was removed in ASDF 3. Do not use it.
3085 Use @code{:if-feature} instead (@pxref{required-features}, and @pxref{if-feature-option}).
3088 @code{:serial} When this attribute is set,
3089 each subcomponent of this component is assumed to depend on all subcomponents
3090 before it in the list given to @code{:components}, i.e.
3091 all of them are loaded before a compile or load operation is performed on it.
3095 The default operation knows how to traverse a module, so
3096 most operations will not need to provide methods specialised on modules.
3098 @code{module} may be subclassed to represent components such as
3099 foreign-language linked libraries or archive files.
3102 @deffn Component system
3104 @code{system} is a subclass of @code{module}.
3106 A system is a module with a few extra attributes for documentation
3107 purposes; these are given elsewhere.
3108 @xref{The defsystem grammar}.
3110 Users can create new classes for their systems:
3111 the default @code{defsystem} macro takes a @code{:class} keyword argument.
3114 @node Creating new component types, , Pre-defined subclasses of component, Components
3115 @comment node-name, next, previous, up
3116 @subsection Creating new component types
3118 New component types are defined by subclassing one of the existing
3119 component classes and specializing methods on the new component class.
3121 @c FIXME: this should perhaps be explained more thoroughly,
3122 @c not only by example ...
3124 As an example, suppose we have some implementation-dependent
3125 functionality that we want to isolate
3126 in one subdirectory per Lisp implementation our system supports.
3127 We create a subclass of
3128 @code{cl-source-file}:
3131 (defclass unportable-cl-source-file (cl-source-file)
3135 Function @code{asdf:implementation-type} (exported since 2.014.14)
3136 gives us the name of the subdirectory.
3137 All that's left is to define how to calculate the pathname
3138 of an @code{unportable-cl-source-file}.
3141 (defmethod component-pathname ((component unportable-cl-source-file))
3143 (parse-unix-namestring (format nil "~(~A~)/" (asdf:implementation-type)))
3144 (call-next-method)))
3147 The new component type is used in a @code{defsystem} form in this way:
3154 (:unportable-cl-source-file "threads"
3155 :depends-on ("packages" ...))
3160 @node Dependencies, Functions, Components, The object model of ASDF
3161 @section Dependencies
3162 @c FIXME: Moved this material here, but it isn't very comfortable
3163 @c here.... Also needs to be revised to be coherent.
3165 To be successfully build-able, this graph of actions must be acyclic.
3166 If, as a user, extender or implementer of ASDF, you introduce
3167 a cycle into the dependency graph,
3168 ASDF will fail loudly.
3169 To clearly distinguish the direction of dependencies,
3170 ASDF 3 uses the words @emph{requiring} and @emph{required}
3171 as applied to an action depending on the other:
3172 the requiring action @code{depends-on} the completion of all required actions
3173 before it may itself be @code{perform}ed.
3175 Using the @code{defsystem} syntax, users may easily express
3176 direct dependencies along the graph of the object hierarchy:
3177 between a component and its parent, its children, and its siblings.
3178 By defining custom CLOS methods, you can express more elaborate dependencies as you wish.
3179 Most common operations, such as @code{load-op}, @code{compile-op} or @code{load-source-op}
3180 are automatically propagate ``downward'' the component hierarchy and are ``covariant'' with it:
3181 to act the operation on the parent module, you must first act it on all the children components,
3182 with the action on the parent being parent of the action on each child.
3183 Other operations, such as @code{prepare-op} and @code{prepare-source-op}
3184 (introduced in ASDF 3) are automatically propagated ``upward'' the component hierarchy
3185 and are ``contravariant'' with it:
3186 to perform the operation of preparing for compilation of a child component,
3187 you must perform the operation of preparing for compilation of its parent component, and so on,
3188 ensuring that all the parent's dependencies are (compiled and) loaded
3189 before the child component may be compiled and loaded.
3190 Yet other operations, such as @code{test-op} or @code{load-bundle-op}
3191 remain at the system level, and are not propagated along the hierarchy,
3192 but instead do something global on the system.
3195 @node Functions, , Dependencies, The object model of ASDF
3196 @comment node-name, next, previous, up
3199 @c FIXME: this does not belong here....
3200 @defun version-satisfies @var{version} @var{version-spec}
3201 Does @var{version} satisfy the @var{version-spec}. A generic function.
3202 ASDF provides built-in methods for @var{version} being a @code{component} or @code{string}.
3203 @var{version-spec} should be a string.
3204 If it's a component, its version is extracted as a string before further processing.
3206 A version string satisfies the version-spec if after parsing,
3207 the former is no older than the latter.
3208 Therefore @code{"1.9.1"}, @code{"1.9.2"} and @code{"1.10"} all satisfy @code{"1.9.1"},
3209 but @code{"1.8.4"} or @code{"1.9"} do not.
3210 For more information about how @code{version-satisfies} parses and interprets
3211 version strings and specifications,
3212 @pxref{The defsystem grammar} (version specifiers) and
3213 @ref{Common attributes of components}.
3215 Note that in versions of ASDF prior to 3.0.1,
3216 including the entire ASDF 1 and ASDF 2 series,
3217 @code{version-satisfies} would also require that the version and the version-spec
3218 have the same major version number (the first integer in the list);
3219 if the major version differed, the version would be considered as not matching the spec.
3220 But that feature was not documented, therefore presumably not relied upon,
3221 whereas it was a nuisance to several users.
3222 Starting with ASDF 3.0.1,
3223 @code{version-satisfies} does not treat the major version number specially,
3224 and returns T simply if the first argument designates a version that isn't older
3225 than the one specified as a second argument.
3226 If needs be, the @code{(:version ...)} syntax for specifying dependencies
3227 could be in the future extended to specify an exclusive upper bound for compatible versions
3228 as well as an inclusive lower bound.
3231 @node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
3232 @comment node-name, next, previous, up
3233 @chapter Controlling where ASDF searches for systems
3239 * Truenames and other dangers::
3240 * XDG base directory::
3241 * Backward Compatibility::
3242 * Configuration DSL::
3243 * Configuration Directories::
3244 * Shell-friendly syntax for configuration::
3245 * Search Algorithm::
3247 * Configuration API::
3252 * Credits for the source-registry::
3255 @node Configurations, Truenames and other dangers, Controlling where ASDF searches for systems, Controlling where ASDF searches for systems
3256 @section Configurations
3258 Configurations specify paths where to find system files.
3263 The search registry may use some hardcoded wrapping registry specification.
3264 This allows some implementations (notably SBCL) to specify where to find
3265 some special implementation-provided systems that
3266 need to precisely match the version of the implementation itself.
3269 An application may explicitly initialize the source-registry configuration
3270 using the configuration API
3271 (@pxref{Controlling where ASDF searches for systems,Configuration API,Configuration API}, below)
3272 in which case this takes precedence.
3273 It may itself compute this configuration from the command-line,
3274 from a script, from its own configuration file, etc.
3277 The source registry will be configured from
3278 the environment variable @code{CL_SOURCE_REGISTRY} if it exists.
3281 The source registry will be configured from
3282 user configuration file
3283 @file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf}
3285 @file{~/.config/common-lisp/source-registry.conf})
3289 The source registry will be configured from
3290 user configuration directory
3291 @file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf.d/}
3293 @file{~/.config/common-lisp/source-registry.conf.d/})
3297 The source registry will be configured from
3298 default user configuration trees
3299 @file{~/common-lisp/} (since ASDF 3.1.2 only),
3300 @file{~/.sbcl/systems/} (on SBCL only),
3301 @file{$XDG_DATA_HOME/common-lisp/systems/} (no recursion, link farm)
3302 @file{$XDG_DATA_HOME/common-lisp/source/}.
3303 The @code{XDG_DATA_HOME} directory defaults to @file{~/.local/share/}.
3304 On Windows, the @code{local-appdata} and @code{appdata} directories are used instead.
3307 The source registry will be configured from
3308 system configuration file
3309 @file{/etc/common-lisp/source-registry.conf}
3313 The source registry will be configured from
3314 system configuration directory
3315 @file{/etc/common-lisp/source-registry.conf.d/}
3319 The source registry will be configured from a default configuration.
3320 This configuration may allow for implementation-specific systems
3321 to be found, for systems to be found the current directory
3322 (at the time that the configuration is initialized) as well as
3323 @code{:directory} entries for @file{$XDG_DATA_DIRS/common-lisp/systems/} and
3324 @code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/},
3325 where @code{XDG_DATA_DIRS} defaults to @file{/usr/local/share} and @file{/usr/share} on Unix,
3326 and the @code{common-appdata} directory on Windows.
3329 The source registry may include implementation-dependent directories
3330 that correspond to implementation-provided extensions.
3334 Each of these configurations is specified as an s-expression
3335 in a trivial domain-specific language (defined below).
3336 Additionally, a more shell-friendly syntax is available
3337 for the environment variable (defined yet below).
3339 Each of these configurations is only used if the previous
3340 configuration explicitly or implicitly specifies that it
3341 includes its inherited configuration.
3343 Additionally, some implementation-specific directories
3344 may be automatically prepended to whatever directories are specified
3345 in configuration files, no matter if the last one inherits or not.
3347 @node Truenames and other dangers, XDG base directory, Configurations, Controlling where ASDF searches for systems
3348 @section Truenames and other dangers
3350 One great innovation of the original ASDF was its ability to leverage
3351 @code{CL:TRUENAME} to locate where your source code was and where to build it,
3352 allowing for symlink farms as a simple but effective configuration mechanism
3353 that is easy to control programmatically.
3354 ASDF 3 still supports this configuration style, and it is enabled by default;
3355 however we recommend you instead use
3356 our source-registry configuration mechanism described below,
3357 because it is easier to setup in a portable way across users and implementations.
3359 Additionally, some people dislike truename,
3360 either because it is very slow on their system, or
3361 because they are using content-addressed storage where the truename of a file
3362 is related to a digest of its individual contents,
3363 and not to other files in the same intended project.
3364 For these people, ASDF 3 allows to eschew the @code{TRUENAME} mechanism,
3365 by setting the variable @var{asdf:*resolve-symlinks*} to @code{nil}.
3367 PS: Yes, if you haven't read Vernor Vinge's short but great classic
3368 ``True Names... and Other Dangers'' then you're in for a treat.
3370 @node XDG base directory, Backward Compatibility, Truenames and other dangers, Controlling where ASDF searches for systems
3371 @section XDG base directory
3373 Note that we purport to respect the XDG base directory specification
3374 as to where configuration files are located,
3375 where data files are located,
3376 where output file caches are located.
3377 Mentions of XDG variables refer to that document.
3379 @url{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}
3381 This specification allows the user to specify some environment variables
3382 to customize how applications behave to his preferences.
3384 On Windows platforms, even when not using Cygwin, and starting with ASDF 3.1.5,
3385 we still do a best effort at following the XDG base directory specification,
3386 even though it doesn't exactly fit common practice for Windows applications.
3387 However, we replace the fixed Unix paths @file{~/.local}, @file{/usr/local} and @file{/usr}
3388 with their rough Windows equivalent @file{Local AppData}, @file{AppData}, @file{Common AppData}, etc.
3389 Since support for querying the Windows registry
3390 is not possible to do in reasonable amounts of portable Common Lisp code,
3391 ASDF 3 relies on the environment variables that Windows usually exports,
3392 and are hopefully in synch with the Windows registry.
3393 If you care about the details, see @file{uiop/configuration.lisp} and don't hesitate to suggest improvements.
3395 @node Backward Compatibility, Configuration DSL, XDG base directory, Controlling where ASDF searches for systems
3396 @section Backward Compatibility
3398 For backward compatibility as well as to provide a practical backdoor for hackers,
3399 ASDF will first search for @file{.asd} files in the directories specified in
3400 @code{asdf:*central-registry*}
3401 before it searches in the source registry above.
3403 @xref{Configuring ASDF,,Configuring ASDF to find your systems --- old style}.
3405 By default, @code{asdf:*central-registry*} will be empty.
3407 This old mechanism will therefore not affect you if you don't use it,
3408 but will take precedence over the new mechanism if you do use it.
3410 @node Configuration DSL, Configuration Directories, Backward Compatibility, Controlling where ASDF searches for systems
3411 @section Configuration DSL
3412 @cindex :inherit-configuration source config directive
3413 @cindex inherit-configuration source config directive
3414 @cindex :ignore-invalid-entries source config directive
3415 @cindex ignore-invalid-entries source config directive
3416 @cindex :directory source config directive
3417 @cindex directory source config directive
3418 @cindex :tree source config directive
3419 @cindex tree source config directive
3420 @cindex :exclude source config directive
3421 @cindex exclude source config directive
3422 @cindex :also-exclude source config directive
3423 @cindex also-exclude source config directive
3424 @cindex :include source config directive
3425 @cindex include source config directive
3426 @cindex :default-registry source config directive
3427 @cindex default-registry source config directive
3429 Here is the grammar of the s-expression (SEXP) DSL for source-registry
3432 @c FIXME: This is too wide for happy compilation into pdf.
3435 ;; A configuration is a single SEXP starting with the keyword
3436 ;; :source-registry followed by a list of directives.
3437 CONFIGURATION := (:source-registry DIRECTIVE ...)
3439 ;; A directive is one of the following:
3441 ;; INHERITANCE DIRECTIVE:
3442 ;; Your configuration expression MUST contain
3443 ;; exactly one of the following:
3444 :inherit-configuration |
3445 ;; splices inherited configuration (often specified last) or
3446 :ignore-inherited-configuration |
3447 ;; drop inherited configuration (specified anywhere)
3449 ;; forward compatibility directive (since ASDF 2.011.4), useful when
3450 ;; you want to use new configuration features but have to bootstrap
3451 ;; the newer required ASDF from an older release that doesn't
3452 ;; support said features:
3453 :ignore-invalid-entries |
3455 ;; add a single directory to be scanned (no recursion)
3456 (:directory DIRECTORY-PATHNAME-DESIGNATOR) |
3458 ;; add a directory hierarchy, recursing but
3459 ;; excluding specified patterns
3460 (:tree DIRECTORY-PATHNAME-DESIGNATOR) |
3462 ;; override the defaults for exclusion patterns
3463 (:exclude EXCLUSION-PATTERN ...) |
3464 ;; augment the defaults for exclusion patterns
3465 (:also-exclude EXCLUSION-PATTERN ...) |
3466 ;; Note that the scope of a an exclude pattern specification is
3467 ;; the rest of the current configuration expression or file.
3469 ;; splice the parsed contents of another config file
3470 (:include REGULAR-FILE-PATHNAME-DESIGNATOR) |
3472 ;; This directive specifies that some default must be spliced.
3475 REGULAR-FILE-PATHNAME-DESIGNATOR
3476 := PATHNAME-DESIGNATOR ; interpreted as a file
3477 DIRECTORY-PATHNAME-DESIGNATOR
3478 := PATHNAME-DESIGNATOR ; interpreted as a directory
3480 PATHNAME-DESIGNATOR :=
3481 NIL | ;; Special: skip this entry.
3482 ABSOLUTE-COMPONENT-DESIGNATOR ;; see pathname DSL
3484 EXCLUSION-PATTERN := a string without wildcards, that will be matched
3485 exactly against the name of a any subdirectory in the directory
3486 component of a path. e.g. @code{"_darcs"} will match
3487 @file{#p"/foo/bar/_darcs/src/bar.asd"}
3490 Pathnames are designated using another DSL,
3491 shared with the output-translations configuration DSL below.
3492 The DSL is resolved by the function @code{asdf::resolve-location},
3493 to be documented and exported at some point in the future.
3496 ABSOLUTE-COMPONENT-DESIGNATOR :=
3497 (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
3499 ;; namestring (better be absolute or bust, directory assumed where
3500 ;; applicable). In output-translations, directory is assumed and
3501 ;; **/*.*.* added if it's last. On MCL, a MacOSX-style POSIX
3502 ;; namestring (for MacOS9 style, use #p"..."); Note that none of the
3503 ;; above applies to strings used in *central-registry*, which
3504 ;; doesn't use this DSL: they are processed as normal namestrings.
3505 ;; however, you can compute what you put in the *central-registry*
3506 ;; based on the results of say
3507 ;; (asdf::resolve-location "/Users/fare/cl/cl-foo/")
3509 ;; pathname (better be an absolute path, or bust)
3510 ;; In output-translations, unless followed by relative components,
3511 ;; it better have appropriate wildcards, as in **/*.*.*
3512 :HOME | ; designates the user-homedir-pathname ~/
3513 :USER-CACHE | ; designates the default location for the user cache
3515 ;; designates the location of the configuration file
3516 ;; (or *default-pathname-defaults*, if invoked interactively)
3518 ;; magic, for output-translations source only: paths that are relative
3519 ;; to the root of the source host and device
3521 They keyword :SYSTEM-CACHE is not accepted in ASDF 3.1 and beyond: it
3522 was a security hazard.
3524 RELATIVE-COMPONENT-DESIGNATOR :=
3525 (RELATIVE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
3527 ;; relative directory pathname as interpreted by
3528 ;; parse-unix-namestring.
3529 ;; In output translations, if last component, **/*.*.* is added
3530 PATHNAME | ; pathname; unless last component, directory is assumed.
3532 ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
3533 :IMPLEMENTATION-TYPE |
3534 ;; a directory based on lisp-implementation-type only, e.g. sbcl
3535 :DEFAULT-DIRECTORY |
3536 ;; a relativized version of the default directory
3537 :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
3538 :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
3539 :*.*.* | ;; any file (since ASDF 2.011.4)
3541 The keywords :UID and :USERNAME are no longer supported.
3544 For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf},
3545 which is the default place ASDF looks for this configuration, once contained:
3548 (:tree (:home "cl")) ;; will expand to e.g. "/home/joeluser/cl/"
3549 :inherit-configuration)
3552 @node Configuration Directories, Shell-friendly syntax for configuration, Configuration DSL, Controlling where ASDF searches for systems
3553 @section Configuration Directories
3555 Configuration directories consist in files each containing
3556 a list of directives without any enclosing @code{(:source-registry ...)} form.
3557 The files will be sorted by namestring as if by @code{string<} and
3558 the lists of directives of these files with be concatenated in order.
3559 An implicit @code{:inherit-configuration} will be included
3560 at the @emph{end} of the list.
3562 System-wide or per-user Common Lisp software distributions
3563 such as Debian packages or some future version of @code{clbuild}
3564 may then include files such as
3565 @file{/etc/common-lisp/source-registry.conf.d/10-foo.conf} or
3566 @file{~/.config/common-lisp/source-registry.conf.d/10-foo.conf}
3567 to easily and modularly register configuration information
3568 about software being distributed.
3570 The convention is that, for sorting purposes,
3571 the names of files in such a directory begin with two digits
3572 that determine the order in which these entries will be read.
3573 Also, the type of these files must be @file{.conf},
3574 which not only simplifies the implementation by allowing
3575 for more portable techniques in finding those files,
3576 but also makes it trivial to disable a file, by renaming it to a different file type.
3578 Directories may be included by specifying a directory pathname
3579 or namestring in an @code{:include} directive, e.g.:
3582 (:include "/foo/bar/")
3585 Hence, to achieve the same effect as
3586 my example @file{~/.config/common-lisp/source-registry.conf} above,
3587 I could simply create a file
3588 @file{~/.config/common-lisp/source-registry.conf.d/33-home-fare-cl.conf}
3589 alone in its directory with the following contents:
3591 (:tree "/home/fare/cl/")
3595 * The here directive::
3598 @node The here directive, , Configuration Directories, Configuration Directories
3599 @subsection The :here directive
3601 The @code{:here} directive is an absolute pathname designator that
3602 refers to the directory containing the configuration file currently
3605 The @code{:here} directive is intended to simplify the delivery of
3606 complex CL systems, and for easy configuration of projects shared through
3607 revision control systems, in accordance with our design principle that
3608 each participant should be able to provide all and only the information
3609 available to him or her.
3611 Consider a person X who has set up the source code repository for a
3612 complex project with a master directory @file{dir/}. Ordinarily, one
3613 might simply have the user add a directive that would look something
3616 (:tree "path/to/dir")
3618 But what if X knows that there are very large subtrees
3619 under dir that are filled with, e.g., Java source code, image files for
3620 icons, etc.? All of the asdf system definitions are contained in the
3621 subdirectories @file{dir/src/lisp/} and @file{dir/extlib/lisp/}, and
3622 these are the only directories that should be searched.
3624 In this case, X can put into @file{dir/} a file @file{asdf.conf} that
3625 contains the following:
3628 (:tree (:here "src/lisp/"))
3629 (:tree (:here "extlib/lisp"))
3630 (:directory (:here "outlier/")))
3633 Then when someone else (call her Y) checks out a copy of this
3634 repository, she need only add
3636 (:include "/path/to/my/checkout/directory/asdf.conf")
3638 to one of her previously-existing asdf source location configuration
3639 files, or invoke @code{initialize-source-registry} with a configuration
3640 form containing that s-expression. ASDF will find the .conf file that X
3641 has provided, and then set up source locations within the working
3642 directory according to X's (relative) instructions.
3644 @node Shell-friendly syntax for configuration, Search Algorithm, Configuration Directories, Controlling where ASDF searches for systems
3645 @section Shell-friendly syntax for configuration
3647 When considering environment variable @code{CL_SOURCE_REGISTRY}
3648 ASDF will skip to next configuration if it's an empty string.
3649 It will @code{READ} the string as a SEXP in the DSL
3650 if it begins with a paren @code{(},
3651 otherwise it will be interpreted much like @code{TEXINPUTS},
3652 as a list of paths, where
3654 * paths are separated
3655 by a @code{:} (colon) on Unix platforms (including cygwin),
3656 by a @code{;} (semicolon) on other platforms (mainly, Windows).
3658 * each entry is a directory to add to the search path.
3660 * if the entry ends with a double slash @code{//}
3661 then it instead indicates a tree in the subdirectories
3662 of which to recurse.
3664 * if the entry is the empty string (which may only appear once),
3665 then it indicates that the inherited configuration should be
3668 @node Search Algorithm, Caching Results, Shell-friendly syntax for configuration, Controlling where ASDF searches for systems
3669 @section Search Algorithm
3670 @vindex *default-source-registry-exclusions*
3672 In case that isn't clear, the semantics of the configuration is that
3673 when searching for a system of a given name,
3674 directives are processed in order.
3676 When looking in a directory, if the system is found, the search succeeds,
3677 otherwise it continues.
3679 When looking in a tree, if one system is found, the search succeeds.
3680 If multiple systems are found, the consequences are unspecified:
3681 the search may succeed with any of the found systems,
3682 or an error may be raised.
3683 ASDF 3.2.1 or later returns the pathname whose normalized directory component
3684 has the shortest length (as a list), and breaks ties by choosing the system
3685 with the smallest @code{unix-namestring} when compared with @code{string<}.
3686 Earlier versions of ASDF return ASDF return the first system found,
3687 which is implementation-dependent, and may or may not be the pathname
3688 with the smallest @code{unix-namestring} when compared with @code{string<}.
3689 XCVB raises an error.
3690 If none is found, the search continues.
3692 Exclude statements specify patterns of subdirectories
3693 the systems from which to ignore.
3694 Typically you don't want to use copies of files kept by such
3695 version control systems as Darcs.
3696 Exclude statements are not propagated to further included or inherited
3697 configuration files or expressions;
3698 instead the defaults are reset around every configuration statement
3699 to the default defaults from @code{asdf::*default-source-registry-exclusions*}.
3701 Include statements cause the search to recurse with the path specifications
3702 from the file specified.
3704 An inherit-configuration statement cause the search to recurse with the path
3705 specifications from the next configuration
3706 (@pxref{Configurations} above).
3709 @node Caching Results, Configuration API, Search Algorithm, Controlling where ASDF searches for systems
3710 @section Caching Results
3712 The implementation is allowed to either eagerly compute the information
3713 from the configurations and file system, or to lazily re-compute it
3714 every time, or to cache any part of it as it goes.
3715 In practice, the recommended @code{source-registry} eagerly collects and caches results
3716 and you need to explicitly flush the cache for change to be taken into account,
3717 whereas the old-style @code{*central-registry*} mechanism queries the filesystem every time.
3719 To explicitly flush any information cached by the system
3720 after a change was made in the filesystem, @xref{Configuration API},
3721 and e.g. call @code{asdf:clear-source-registry}.
3723 Starting with ASDF 3.1.4, you can also explicitly build a persistent cache
3724 of the @file{.asd} files found under a tree:
3725 when recursing into a directory declared by @code{:tree} and its transitive subdirectories,
3726 if a file @file{.cl-source-registry.cache} exists containing a form
3727 that is a list starting with @code{:source-registry-cache} followed by a list of strings,
3728 as in @code{(:source-registry-cache @emph{"foo/bar.asd" "path/to/more.asd" ...})},
3729 then the strings are assumed to be @code{unix-namestring}s designating
3730 the available asd files under that tree, and the recursion otherwise stops.
3731 The list can also be empty, allowing to stop a costly recursion in a huge directory tree.
3733 To update such a cache after you install, update or remove source repositories,
3734 you can run a script distributed with ASDF:
3735 @code{tools/cl-source-registry-cache.lisp @emph{/path/to/directory}}.
3736 To wholly invalidate the cache, you can
3737 delete the file @file{.cl-source-registry.cache} in that directory.
3738 In either case, for an existing Lisp process to see this change,
3739 it needs to clear its own cache with e.g. @code{(asdf:clear-source-registry)}.
3741 Developers may safely create a cache in their development tree,
3742 and we recommend they do it at the top of their source tree if
3743 it contains more than a small number of files and directories;
3744 they only need update it when they create, remove or move @file{.asd} files.
3745 Software distribution managers may also safely create such a cache,
3746 but they must be careful to update it every time they install, update or remove
3747 a software source repository or installation package.
3748 Finally, advanced developers who juggle with a lot of code
3749 in their @code{source-registry} may manually manage such a cache,
3750 to allow for faster startup of Lisp programs.
3752 This persistence cache can help you reduce startup latency.
3753 For instance, on one machine with hundreds of source repositories,
3754 such a cache shaves half a second at the startup
3755 of every @code{#!/usr/bin/cl} script using SBCL, more on other implementations;
3756 this makes a notable difference as to
3757 their subjective interactivity and usability.
3758 The speedup will only happen if the implementation-provided ASDF is recent enough
3759 (3.1.3.7 or later); it is not enough for a recent ASDF upgrade to be present,
3760 since the upgrade will itself be found but
3761 after the old version has scanned the directories without heeding such a cache.
3762 To upgrade the implementation-provided ASDF,
3763 @pxref{Replacing your implementation's ASDF}.
3766 @node Configuration API, Introspection, Caching Results, Controlling where ASDF searches for systems
3767 @section Configuration API
3769 The specified functions are exported from your build system's package.
3770 Thus for ASDF the corresponding functions are in package ASDF,
3771 and for XCVB the corresponding functions are in package XCVB.
3773 @defun initialize-source-registry @Aoptional{} PARAMETER
3774 will read the configuration and initialize all internal variables.
3775 You may extend or override configuration
3776 from the environment and configuration files
3777 with the given @var{PARAMETER}, which can be
3778 @code{nil} (no configuration override),
3779 or a SEXP (in the SEXP DSL),
3780 a string (as in the string DSL),
3781 a pathname (of a file or directory with configuration),
3782 or a symbol (fbound to function that when called returns one of the above).
3785 @defun clear-source-registry
3786 undoes any source registry configuration
3787 and clears any cache for the search algorithm.
3788 You might want to call this function
3789 (or better, @code{clear-configuration})
3790 before you dump an image that would be resumed
3791 with a different configuration,
3792 and return an empty configuration.
3793 Note that this does not include clearing information about
3794 systems defined in the current image, only about
3795 where to look for systems not yet defined.
3798 @defun ensure-source-registry @Aoptional{} PARAMETER
3799 checks whether a source registry has been initialized.
3800 If not, initialize it with the given @var{PARAMETER}.
3803 Every time you use ASDF's @code{find-system}, or
3804 anything that uses it (such as @code{operate}, @code{load-system}, etc.),
3805 @code{ensure-source-registry} is called with parameter @code{nil},
3806 which the first time around causes your configuration to be read.
3807 If you change a configuration file,
3808 you need to explicitly @code{initialize-source-registry} again,
3809 or maybe simply to @code{clear-source-registry} (or @code{clear-configuration})
3810 which will cause the initialization to happen next time around.
3812 @node Introspection, Status, Configuration API, Controlling where ASDF searches for systems
3813 @section Introspection
3816 * *source-registry-parameter* variable::
3817 * Information about system dependencies::
3820 @node *source-registry-parameter* variable, Information about system dependencies, Introspection, Introspection
3821 @subsection *source-registry-parameter* variable
3822 @vindex *source-registry-parameter*
3824 We have made available the variable @code{*source-registry-parameter*}
3825 that can be used by code that wishes to introspect about the (past)
3826 configuration of ASDF's source registry. @strong{This variable should
3827 never be set!} It will be set as a side-effect of calling
3828 @code{initialize-source-registry}; user code should treat it as
3831 @node Information about system dependencies, , *source-registry-parameter* variable, Introspection
3832 @subsection Information about system dependencies
3834 ASDF makes available three functions to read system interdependencies.
3835 These are intended to aid programmers who wish to perform dependency
3838 @defun system-defsystem-depends-on system
3841 @defun system-depends-on system
3844 @defun system-weakly-depends-on system
3845 Returns a list of names of systems that are weakly depended on by
3846 @var{system}. Weakly depended on systems are optionally loaded only if
3847 ASDF can find them; failure to find such systems does @emph{not} cause an
3850 Note that the return value for @code{system-weakly-depends-on} is simpler
3851 than the return values of the other two system dependency introspection
3855 @node Status, Rejected ideas, Introspection, Controlling where ASDF searches for systems
3858 This mechanism is vastly successful, and we have declared
3859 that @code{asdf:*central-registry*} is not recommended anymore,
3860 though we will continue to support it.
3861 All hooks into implementation-specific search mechanisms
3862 have been integrated in the @code{wrapping-source-registry}
3863 that everyone uses implicitly.
3865 @node Rejected ideas, TODO, Status, Controlling where ASDF searches for systems
3866 @section Rejected ideas
3868 Alternatives I (FRR) considered and rejected while developing ASDF 2 included:
3871 @item Keep @code{asdf:*central-registry*} as the master with its current semantics,
3872 and somehow the configuration parser expands the new configuration
3873 language into a expanded series of directories of subdirectories to
3874 lookup, pre-recursing through specified hierarchies. This is kludgy,
3875 and leaves little space of future cleanups and extensions.
3877 @item Keep @code{asdf:*central-registry*} as the master but extend its semantics
3878 in completely new ways, so that new kinds of entries may be implemented
3879 as a recursive search, etc. This seems somewhat backwards.
3881 @item Completely remove @code{asdf:*central-registry*}
3882 and break backwards compatibility.
3883 Hopefully this will happen in a few years after everyone migrate to
3884 a better ASDF and/or to XCVB, but it would be very bad to do it now.
3886 @item Replace @code{asdf:*central-registry*} by a symbol-macro with appropriate magic
3887 when you dereference it or setf it. Only the new variable with new
3888 semantics is handled by the new search procedure.
3889 Complex and still introduces subtle semantic issues.
3893 I've been suggested the below features, but have rejected them,
3894 for the sake of keeping ASDF no more complex than strictly necessary.
3898 More syntactic sugar: synonyms for the configuration directives, such as
3899 @code{(:add-directory X)} for @code{(:directory X)}, or @code{(:add-directory-hierarchy X)}
3900 or @code{(:add-directory X :recurse t)} for @code{(:tree X)}.
3903 The possibility to register individual files instead of directories.
3906 Integrate Xach Beane's tilde expander into the parser,
3907 or something similar that is shell-friendly or shell-compatible.
3908 I'd rather keep ASDF minimal. But maybe this precisely keeps it
3909 minimal by removing the need for evaluated entries that ASDF has?
3910 i.e. uses of @code{USER-HOMEDIR-PATHNAME} and @code{$SBCL_HOME}
3911 Hopefully, these are already superseded by the @code{:default-registry}
3914 Using the shell-unfriendly syntax @code{/**} instead of TEXINPUTS-like @code{//} to specify recursion
3915 down a filesystem tree in the environment variable.
3916 It isn't that Lisp friendly either.
3919 @node TODO, Credits for the source-registry, Rejected ideas, Controlling where ASDF searches for systems
3926 @node Credits for the source-registry, , TODO, Controlling where ASDF searches for systems
3927 @section Credits for the source-registry
3929 Thanks a lot to Stelian Ionescu for the initial idea.
3931 Thanks to Rommel Martinez for the initial implementation attempt.
3933 All bad design ideas and implementation bugs are mine, not theirs.
3934 But so are good design ideas and elegant implementation tricks.
3936 --- Francois-Rene Rideau @email{fare@@tunes.org}, Mon, 22 Feb 2010 00:07:33 -0500
3940 @node Controlling where ASDF saves compiled files, Error handling, Controlling where ASDF searches for systems, Top
3941 @comment node-name, next, previous, up
3942 @chapter Controlling where ASDF saves compiled files
3943 @cindex asdf-output-translations
3944 @vindex ASDF_OUTPUT_TRANSLATIONS
3946 Each Common Lisp implementation has its own format
3947 for compiled files or fasls.@footnote{``FASL'' is short for ``FASt Loading.''}
3948 If you use multiple implementations
3949 (or multiple versions of the same implementation),
3950 you'll soon find your source directories
3951 littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so
3953 Worse yet, multiple implementations use the same file extension and
3954 some implementations maintain the same file extension
3955 while changing formats from version to version (or platform to
3957 This can lead to many errors and much confusion
3958 as you switch from one implementation to the next.
3959 Finally, this requires write access to the source directory,
3960 and therefore precludes sharing of a same source code directory between multiple users.
3962 Since ASDF 2, ASDF includes the @code{asdf-output-translations} facility
3963 to mitigate the problem.
3966 * Output Configurations::
3967 * Output Backward Compatibility::
3968 * Output Configuration DSL::
3969 * Output Configuration Directories::
3970 * Output Shell-friendly syntax for configuration::
3971 * Semantics of Output Translations::
3972 * Output Caching Results::
3973 * Output location API::
3974 * Credits for output translations::
3977 @node Output Configurations, Output Backward Compatibility, Controlling where ASDF saves compiled files, Controlling where ASDF saves compiled files
3978 @section Configurations
3980 @c FIXME: Explain how configurations work: can't expect reader will have
3981 @c looked at previous chapter. Probably cut and paste will do.
3984 Configurations specify mappings from input locations to output locations.
3985 Once again we rely on the XDG base directory specification for configuration.
3986 @xref{Controlling where ASDF searches for systems,,XDG base directory}.
3991 Some hardcoded wrapping output translations configuration may be used.
3992 This allows special output translations (or usually, invariant directories)
3993 to be specified corresponding to the similar special entries in the source registry.
3996 An application may explicitly initialize the output-translations
3997 configuration using the Configuration API
3998 in which case this takes precedence.
3999 (@pxref{Controlling where ASDF saves compiled files,,Configuration API}.)
4000 It may itself compute this configuration from the command-line,
4001 from a script, from its own configuration file, etc.
4004 The source registry will be configured from
4005 the environment variable @code{ASDF_OUTPUT_TRANSLATIONS} if it exists.
4008 The source registry will be configured from
4009 user configuration file
4010 @file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf}
4012 @file{~/.config/common-lisp/asdf-output-translations.conf})
4016 The source registry will be configured from
4017 user configuration directory
4018 @file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf.d/}
4020 @file{~/.config/common-lisp/asdf-output-translations.conf.d/})
4024 The source registry will be configured from
4025 system configuration file
4026 @file{/etc/common-lisp/asdf-output-translations.conf}
4030 The source registry will be configured from
4031 system configuration directory
4032 @file{/etc/common-lisp/asdf-output-translations.conf.d/}
4037 Each of these configurations is specified as a SEXP
4038 in a trivial domain-specific language (@pxref{Configuration DSL}).
4039 Additionally, a more shell-friendly syntax is available
4040 for the environment variable (@pxref{Shell-friendly syntax for configuration}).
4042 When processing an entry in the above list of configuration methods,
4043 ASDF will stop unless that entry
4044 explicitly or implicitly specifies that it
4045 includes its inherited configuration.
4047 Note that by default, a per-user cache is used for output files.
4048 This allows the seamless use of shared installations of software
4049 between several users, and takes files out of the way of the developers
4050 when they browse source code,
4051 at the expense of taking a small toll when developers have to clean up
4052 output files and find they need to get familiar with output-translations
4053 first.@footnote{A @code{CLEAN-OP} would be a partial solution to this problem.}
4056 @node Output Backward Compatibility, Output Configuration DSL, Output Configurations, Controlling where ASDF saves compiled files
4057 @section Backward Compatibility
4058 @cindex ASDF-BINARY-LOCATIONS compatibility
4059 @c FIXME: Demote this section -- the typical reader doesn't care about
4060 @c backwards compatibility.
4063 We purposely do @emph{not} provide backward compatibility with earlier versions of
4064 @code{ASDF-Binary-Locations} (8 Sept 2009),
4065 @code{common-lisp-controller} (7.0) or
4066 @code{cl-launch} (2.35),
4067 each of which had similar general capabilities.
4068 The APIs of these programs were not designed
4069 for easy user configuration
4070 through configuration files.
4071 Recent versions of @code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000)
4072 use the new @code{asdf-output-translations} API as defined below.
4073 @code{ASDF-Binary-Locations} is fully superseded and not to be used anymore.
4075 This incompatibility shouldn't inconvenience many people.
4076 Indeed, few people use and customize these packages;
4077 these few people are experts who can trivially adapt to the new configuration.
4078 Most people are not experts, could not properly configure these features
4079 (except inasmuch as the default configuration of
4080 @code{common-lisp-controller} and/or @code{cl-launch}
4081 might have been doing the right thing for some users),
4082 and yet will experience software that ``just works'',
4083 as configured by the system distributor, or by default.
4085 Nevertheless, if you are a fan of @code{ASDF-Binary-Locations},
4086 we provide a limited emulation mode:
4088 @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
4089 This function will initialize the new @code{asdf-output-translations} facility in a way
4090 that emulates the behaviour of the old @code{ASDF-Binary-Locations} facility.
4091 Where you would previously set global variables
4092 @var{*centralize-lisp-binaries*},
4093 @var{*default-toplevel-directory*},
4094 @var{*include-per-user-information*},
4095 @var{*map-all-source-files*} or @var{*source-to-target-mappings*}
4096 you will now have to pass the same values as keyword arguments to this function.
4097 Note however that as an extension the @code{:source-to-target-mappings} keyword argument
4098 will accept any valid pathname designator for @code{asdf-output-translations}
4099 instead of just strings and pathnames.
4102 If you insist, you can also keep using the old @code{ASDF-Binary-Locations}
4103 (the one available as an extension to load of top of ASDF,
4104 not the one built into a few old versions of ASDF),
4105 but first you must disable @code{asdf-output-translations}
4106 with @code{(asdf:disable-output-translations)},
4107 or you might experience ``interesting'' issues.
4109 Also, note that output translation is enabled by default.
4110 To disable it, use @code{(asdf:disable-output-translations)}.
4112 @node Output Configuration DSL, Output Configuration Directories, Output Backward Compatibility, Controlling where ASDF saves compiled files
4113 @section Configuration DSL
4115 Here is the grammar of the SEXP DSL
4116 for @code{asdf-output-translations} configuration:
4119 ;; A configuration is single SEXP starting with keyword :source-registry
4120 ;; followed by a list of directives.
4121 CONFIGURATION := (:output-translations DIRECTIVE ...)
4123 ;; A directive is one of the following:
4125 ;; INHERITANCE DIRECTIVE:
4126 ;; Your configuration expression MUST contain
4127 ;; exactly one of either of these:
4128 :inherit-configuration |
4129 ;; splices inherited configuration (often specified last)
4130 :ignore-inherited-configuration |
4131 ;; drop inherited configuration (specified anywhere)
4133 ;; forward compatibility directive (since ASDF 2.011.4), useful when
4134 ;; you want to use new configuration features but have to bootstrap a
4135 ;; the newer required ASDF from an older release that doesn't have
4137 :ignore-invalid-entries |
4139 ;; include a configuration file or directory
4140 (:include PATHNAME-DESIGNATOR) |
4142 ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/
4144 :enable-user-cache |
4145 ;; Disable global cache. Map / to /
4148 ;; add a single directory to be scanned (no recursion)
4149 (DIRECTORY-DESIGNATOR DIRECTORY-DESIGNATOR)
4151 ;; use a function to return the translation of a directory designator
4152 (DIRECTORY-DESIGNATOR (:function TRANSLATION-FUNCTION))
4154 DIRECTORY-DESIGNATOR :=
4155 NIL | ; As source: skip this entry. As destination: same as source
4156 T | ; as source matches anything, as destination
4157 ; maps pathname to itself.
4158 ABSOLUTE-COMPONENT-DESIGNATOR ; same as in the source-registry language
4160 TRANSLATION-FUNCTION :=
4161 SYMBOL | ;; symbol naming a function that takes two arguments:
4162 ;; the pathname to be translated and the matching
4163 ;; DIRECTORY-DESIGNATOR
4164 LAMBDA ;; A form which evaluates to a function taking two arguments:
4165 ;; the pathname to be translated and the matching
4166 ;; DIRECTORY-DESIGNATOR
4170 Relative components better be either relative
4171 or subdirectories of the path before them, or bust.
4173 @c FIXME: the following assumes that the reader is familiar with the use
4174 @c of this pattern in logical pathnames, which may not be a reasonable
4175 @c assumption. Expand.
4176 The last component, if not a pathname, is notionally completed by @file{/**/*.*}.
4177 You can specify more fine-grained patterns
4178 by using a pathname object as the last component
4179 e.g. @file{#p"some/path/**/foo*/bar-*.fasl"}
4181 You may use @code{#+features} to customize the configuration file.
4183 The second designator of a mapping may be @code{nil}, indicating that files are not mapped
4184 to anything but themselves (same as if the second designator was the same as the first).
4186 When the first designator is @code{t},
4187 the mapping always matches.
4188 When the first designator starts with @code{:root},
4189 the mapping matches any host and device.
4190 In either of these cases, if the second designator
4191 isn't @code{t} and doesn't start with @code{:root},
4192 then strings indicating the host and pathname are somehow copied
4193 in the beginning of the directory component of the source pathname
4194 before it is translated.
4196 When the second designator is @code{t}, the mapping is the identity.
4197 When the second designator starts with @code{:root},
4198 the mapping preserves the host and device of the original pathname.
4199 Notably, this allows you to map files
4200 to a subdirectory of the whichever directory the file is in.
4201 Though the syntax is not quite as easy to use as we'd like,
4202 you can have an (source destination) mapping entry such as follows
4203 in your configuration file,
4204 or you may use @code{enable-asdf-binary-locations-compatibility}
4205 with @code{:centralize-lisp-binaries nil}
4206 which will do the same thing internally for you:
4208 #.(let ((wild-subdir
4209 (make-pathname :directory '(:relative :wild-inferiors)))
4211 (make-pathname :name :wild :version :wild :type :wild)))
4212 `((:root ,wild-subdir ,wild-file)
4213 (:root ,wild-subdir :implementation ,wild-file)))
4215 Starting with ASDF 2.011.4, you can use the simpler:
4216 @code{`(:root (:root :**/ :implementation :*.*.*))}
4220 @code{:include} statements cause the search to recurse with the path specifications
4221 from the file specified.
4223 If the @code{translate-pathname} mechanism cannot achieve a desired
4224 translation, the user may provide a function which provides the
4225 required algorithm. Such a translation function is specified by
4226 supplying a list as the second @code{directory-designator}
4227 the first element of which is the keyword @code{:function},
4228 and the second element of which is
4229 either a symbol which designates a function or a lambda expression.
4230 The function designated by the second argument must take two arguments,
4231 the first being the pathname of the source file,
4232 the second being the wildcard that was matched.
4233 When invoked, the function should return the translated pathname.
4235 An @code{:inherit-configuration} statement causes the search to recurse with the path
4236 specifications from the next configuration in the bulleted list.
4237 @xref{Controlling where ASDF saves compiled files,,Configurations}, above.
4239 @vindex @code{asdf::*user-cache*}
4242 @code{:enable-user-cache} is the same as @code{(t :user-cache)}.
4244 @code{:disable-cache} is the same as @code{(t t)}.
4246 @code{:user-cache} uses the contents of variable @code{asdf::*user-cache*}
4247 which by default is the same as using
4248 @code{(:home ".cache" "common-lisp" :implementation)}.
4252 @node Output Configuration Directories, Output Shell-friendly syntax for configuration, Output Configuration DSL, Controlling where ASDF saves compiled files
4253 @section Configuration Directories
4255 Configuration directories consist of files, each of which contains
4256 a list of directives without any enclosing
4257 @code{(:output-translations ...)} form.
4258 The files will be sorted by namestring as if by @code{string<} and
4259 the lists of directives of these files with be concatenated in order.
4260 An implicit @code{:inherit-configuration} will be included
4261 at the @emph{end} of the list.
4263 System-wide or per-user Common Lisp software distributions
4264 such as Debian packages or some future version of @code{clbuild}
4265 may then include files such as
4266 @file{/etc/common-lisp/asdf-output-translations.conf.d/10-foo.conf} or
4267 @file{~/.config/common-lisp/asdf-output-translations.conf.d/10-foo.conf}
4268 to easily and modularly register configuration information
4269 about software being distributed.
4271 The convention is that, for sorting purposes,
4272 the names of files in such a directory begin with two digits
4273 that determine the order in which these entries will be read.
4274 Also, the type of these files must be @file{.conf},
4275 which not only simplifies the implementation by allowing
4276 for more portable techniques in finding those files,
4277 but also makes it trivial to disable a file, by renaming it to a different file type.
4279 Directories may be included by specifying a directory pathname
4280 or namestring in an @code{:include} directive, e.g.:
4283 (:include "/foo/bar/")
4286 @node Output Shell-friendly syntax for configuration, Semantics of Output Translations, Output Configuration Directories, Controlling where ASDF saves compiled files
4287 @section Shell-friendly syntax for configuration
4289 When processing the environment variable
4290 @code{ASDF_OUTPUT_TRANSLATIONS}:
4292 @item ASDF will skip to the next configuration if it's an empty string.
4293 @item ASDF will @code{READ} the string as an SEXP in the DSL, if it
4294 begins with a parenthesis @code{(}.
4295 @item Otherwise ASDF will interpret the value as a list of directories
4299 In the directory list format,
4300 directories should come in pairs, each pair indicating a mapping directive.
4301 Entries are separated
4302 by a @code{:} (colon) on Unix platforms (including Mac and cygwin), and
4303 by a @code{;} (semicolon) on other platforms (mainly, Windows).
4305 The magic empty entry,
4306 if it comes in what would otherwise be the first entry in a pair,
4307 indicates the splicing of inherited configuration;
4308 the next entry (if any) then starts a new pair.
4309 If the second entry in a pair is empty,
4310 it indicates that the directory in the first entry is to be left untranslated
4311 (which has the same effect as if the directory had been repeated).
4313 For example, @code{"/foo:/bar::/baz:"} means:
4314 specify that outputs for things under directory @file{/foo/}
4315 are translated to be under @file{/bar/};
4316 then include the inherited configuration;
4317 then specify that outputs for things under directory @file{/baz/} are not translated.
4320 @node Semantics of Output Translations, Output Caching Results, Output Shell-friendly syntax for configuration, Controlling where ASDF saves compiled files
4321 @section Semantics of Output Translations
4323 From the specified configuration,
4324 a list of mappings is extracted in a straightforward way:
4325 mappings are collected in order, recursing through
4326 included or inherited configuration as specified.
4327 To this list is prepended some implementation-specific mappings,
4328 and is appended a global default.
4330 The list is then compiled to a mapping table as follows:
4331 for each entry, in order, resolve the first designated directory
4332 into an actual directory pathname for source locations.
4333 If no mapping was specified yet for that location,
4334 resolve the second designated directory to an output location directory
4335 add a mapping to the table mapping the source location to the output location,
4336 and add another mapping from the output location to itself
4337 (unless a mapping already exists for the output location).
4339 Based on the table, a mapping function is defined,
4340 mapping source pathnames to output pathnames:
4341 given a source pathname, locate the longest matching prefix
4342 in the source column of the mapping table.
4343 Replace that prefix by the corresponding output column
4344 in the same row of the table, and return the result.
4345 If no match is found, return the source pathname.
4346 (A global default mapping the filesystem root to itself
4347 may ensure that there will always be a match,
4348 with same fall-through semantics).
4350 @node Output Caching Results, Output location API, Semantics of Output Translations, Controlling where ASDF saves compiled files
4351 @section Caching Results
4353 The implementation is allowed to either eagerly compute the information
4354 from the configurations and file system, or to lazily re-compute it
4355 every time, or to cache any part of it as it goes.
4356 To explicitly flush any information cached by the system, use the API below.
4359 @node Output location API, Credits for output translations, Output Caching Results, Controlling where ASDF saves compiled files
4360 @section Output location API
4362 The specified functions are exported from package ASDF.
4364 @defun initialize-output-translations @Aoptional{} PARAMETER
4365 will read the configuration and initialize all internal variables.
4366 You may extend or override configuration
4367 from the environment and configuration files
4368 with the given @var{PARAMETER}, which can be
4369 @code{nil} (no configuration override),
4370 or a SEXP (in the SEXP DSL),
4371 a string (as in the string DSL),
4372 a pathname (of a file or directory with configuration),
4373 or a symbol (fbound to function that when called returns one of the above).
4376 @defun disable-output-translations
4377 will initialize output translations in a way
4378 that maps every pathname to itself,
4379 effectively disabling the output translation facility.
4382 @defun clear-output-translations
4383 undoes any output translation configuration
4384 and clears any cache for the mapping algorithm.
4385 You might want to call this function
4386 (or better, @code{clear-configuration})
4387 before you dump an image that would be resumed
4388 with a different configuration,
4389 and return an empty configuration.
4390 Note that this does not include clearing information about
4391 systems defined in the current image, only about
4392 where to look for systems not yet defined.
4395 @defun ensure-output-translations @Aoptional{} PARAMETER
4396 checks whether output translations have been initialized.
4397 If not, initialize them with the given @var{PARAMETER}.
4398 This function will be called before any attempt to operate on a system.
4401 @defun apply-output-translations PATHNAME
4402 Applies the configured output location translations to @var{PATHNAME}
4403 (calls @code{ensure-output-translations} for the translations).
4406 Every time you use ASDF's @code{output-files}, or
4407 anything that uses it (that may compile, such as @code{operate}, @code{perform}, etc.),
4408 @code{ensure-output-translations} is called with parameter @code{nil},
4409 which the first time around causes your configuration to be read.
4410 If you change a configuration file,
4411 you need to explicitly @code{initialize-output-translations} again,
4412 or maybe @code{clear-output-translations} (or @code{clear-configuration}),
4413 which will cause the initialization to happen next time around.
4416 @node Credits for output translations, , Output location API, Controlling where ASDF saves compiled files
4417 @section Credits for output translations
4419 Thanks a lot to Peter van Eynde for @code{Common Lisp Controller}
4420 and to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations}.
4422 All bad design ideas and implementation bugs are to mine, not theirs.
4423 But so are good design ideas and elegant implementation tricks.
4425 --- Francois-Rene Rideau @email{fare@@tunes.org}
4427 @c @section Default locations
4428 @c @findex output-files-for-system-and-operation
4430 @c The default binary location for each Lisp implementation
4431 @c is a subdirectory of each source directory.
4432 @c To account for different Lisps, Operating Systems, Implementation versions,
4433 @c and so on, ASDF borrows code from SLIME
4434 @c to create reasonable custom directory names.
4435 @c Here are some examples:
4439 @c SBCL, version 1.0.45 on Mac OS X for Intel: @code{sbcl-1.0.45-darwin-x86}
4442 @c Franz Allegro, version 8.0, ANSI Common Lisp: @code{allegro-8.0a-macosx-x86}
4445 @c Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: @code{allegro-8.1m-macosx-x86}
4448 @c By default, all output file pathnames will be relocated
4449 @c to some thus-named subdirectory of @file{~/.cache/common-lisp/}.
4451 @c See the document @file{README.asdf-output-translations}
4452 @c for a full specification on how to configure @code{asdf-output-translations}.
4454 @node Error handling, Miscellaneous additional functionality, Controlling where ASDF saves compiled files, Top
4455 @comment node-name, next, previous, up
4456 @chapter Error handling
4457 @findex SYSTEM-DEFINITION-ERROR
4458 @findex OPERATION-ERROR
4460 @section ASDF errors
4462 If ASDF detects an incorrect system definition, it will signal a generalised instance of
4463 @code{SYSTEM-DEFINITION-ERROR}.
4465 Operations may go wrong (for example when source files contain errors).
4466 These are signalled using generalised instances of
4467 @code{OPERATION-ERROR}.
4469 @section Compilation error and warning handling
4470 @vindex *compile-file-warnings-behaviour*
4471 @vindex *compile-file-failure-behaviour*
4473 ASDF checks for warnings and errors when a file is compiled.
4474 The variables @var{*compile-file-warnings-behaviour*} and
4475 @var{*compile-file-failure-behaviour*}
4476 control the handling of any such events.
4477 The valid values for these variables are
4478 @code{:error}, @code{:warn}, and @code{:ignore}.
4480 @node Miscellaneous additional functionality, Getting the latest version, Error handling, Top
4481 @comment node-name, next, previous, up
4482 @chapter Miscellaneous additional functionality
4484 ASDF includes several additional features that are generally
4485 useful for system definition and development.
4488 * Controlling file compilation::
4489 * Controlling source file character encoding::
4490 * Miscellaneous Functions::
4491 * Some Utility Functions::
4494 @node Controlling file compilation, Controlling source file character encoding, Miscellaneous additional functionality, Miscellaneous additional functionality
4495 @section Controlling file compilation
4496 @cindex :around-compile
4497 @cindex around-compile keyword
4498 @cindex compile-check keyword
4499 @cindex :compile-check
4500 @findex compile-file*
4502 @c FIXME: Needs rewrite. Start with motivation -- why are we doing
4503 @c this? (there is some, but it's buried). Also, all of a sudden in
4504 @c the middle of the discussion we start talking about a "hook," which
4507 When declaring a component (system, module, file),
4508 you can specify a keyword argument @code{:around-compile function}.
4509 If left unspecified (and therefore unbound),
4510 the value will be inherited from the parent component if any,
4511 or with a default of @code{nil}
4512 if no value is specified in any transitive parent.
4514 The argument must be either @code{nil}, an fbound symbol,
4515 a lambda-expression (e.g. @code{(lambda (thunk) ...(funcall thunk ...) ...)})
4516 a function object (e.g. using @code{#.#'} but that's discouraged
4517 because it prevents the introspection done by e.g. asdf-dependency-grovel),
4518 or a string that when @code{read} yields a symbol or a lambda-expression.
4519 @code{nil} means the normal compile-file function will be called.
4520 A non-nil value designates a function of one argument
4521 that will be called with a function that will
4522 invoke @code{compile-file*} with various arguments;
4523 the around-compile hook may supply additional keyword arguments
4524 to pass to that call to @code{compile-file*}.
4526 One notable argument that is heeded by @code{compile-file*} is
4527 @code{:compile-check},
4528 a function called when the compilation was otherwise a success,
4529 with the same arguments as @code{compile-file};
4530 the function shall return true if the compilation
4531 and its resulting compiled file respected all system-specific invariants,
4532 and false (@code{nil}) if it broke any of those invariants;
4533 it may issue warnings or errors before it returns @code{nil}.
4534 (NB: The ability to pass such extra flags
4535 is only available starting with ASDF 2.22.3.)
4536 This feature is notably exercised by asdf-finalizers.
4538 By using a string, you may reference
4539 a function, symbol and/or package
4540 that will only be created later during the build, but
4541 isn't yet present at the time the defsystem form is evaluated.
4542 However, if your entire system is using such a hook, you may have to
4543 explicitly override the hook with @code{nil} for all the modules and files
4544 that are compiled before the hook is defined.
4546 Using this hook, you may achieve such effects as:
4547 locally renaming packages,
4548 binding @var{*readtables*} and other syntax-controlling variables,
4549 handling warnings and other conditions,
4550 proclaiming consistent optimization settings,
4551 saving code coverage information,
4552 maintaining meta-data about compilation timings,
4553 setting gensym counters and PRNG seeds and other sources of non-determinism,
4554 overriding the source-location and/or timestamping systems,
4555 checking that some compile-time side-effects were properly balanced,
4558 Note that there is no around-load hook. This is on purpose.
4559 Some implementations such as ECL, GCL or MKCL link object files,
4560 which allows for no such hook.
4561 Other implementations allow for concatenating FASL files,
4562 which doesn't allow for such a hook either.
4563 We aim to discourage something that's not portable,
4564 and has some dubious impact on performance and semantics
4565 even when it is possible.
4566 Things you might want to do with an around-load hook
4567 are better done around-compile,
4568 though it may at times require some creativity
4569 (see e.g. the @code{package-renaming} system).
4572 @node Controlling source file character encoding, Miscellaneous Functions, Controlling file compilation, Miscellaneous additional functionality
4573 @section Controlling source file character encoding
4575 Starting with ASDF 2.21, components accept a @code{:encoding} option
4576 so authors may specify which character encoding should be used
4577 to read and evaluate their source code.
4578 When left unspecified, the encoding is inherited
4579 from the parent module or system;
4580 if no encoding is specified at any point,
4581 or if @code{nil} is explicitly specified,
4582 an extensible protocol described below is followed,
4583 that ultimately defaults to @code{:utf-8} since ASDF 3.
4585 The protocol to determine the encoding is
4586 to call the function @code{detect-encoding},
4587 which itself, if provided a valid file,
4588 calls the function specified by @var{*encoding-detection-hook*},
4589 or else defaults to the @var{*default-encoding*}.
4590 The @var{*encoding-detection-hook*} is by default bound
4591 to function @code{always-default-encoding},
4592 that always returns the contents of @var{*default-encoding*}.
4593 @var{*default-encoding*} is bound to @code{:utf-8} by default
4594 (before ASDF 3, the default was @code{:default}).
4596 Whichever encoding is returned must be a portable keyword,
4597 that will be translated to an implementation-specific external-format designator
4598 by function @code{encoding-external-format},
4599 which itself simply calls the function specified @var{*encoding-external-format-hook*};
4600 that function by default is @code{default-encoding-external-format},
4601 that only recognizes @code{:utf-8} and @code{:default},
4602 and translates the former to the implementation-dependent @var{*utf-8-external-format*},
4603 and the latter to itself (that itself is portable but has an implementation-dependent meaning).
4605 In other words, there now are plenty of extension hooks, but
4606 by default ASDF enforces the previous @emph{de facto} standard behaviour
4607 of using @code{:utf-8}, independently from
4608 whatever configuration the user may be using.
4609 Thus, system authors can now rely on @code{:utf-8}
4610 being used while compiling their files,
4611 even if the user is currently using @code{:koi8-r} or @code{:euc-jp}
4612 as their interactive encoding.
4613 (Before ASDF 3, there was no such guarantee, @code{:default} was used,
4614 and only plain ASCII was safe to include in source code.)
4616 Some legacy implementations only support 8-bit characters,
4617 and some implementations provide 8-bit only variants.
4618 On these implementations, the @var{*utf-8-external-format*}
4619 gracefully falls back to @code{:default},
4620 and Unicode characters will be read as multi-character mojibake.
4621 To detect such situations, UIOP will push the @code{:asdf-unicode} feature
4622 on implementations that support Unicode, and you can use reader-conditionalization
4623 to protect any @code{:encoding @emph{encoding}} statement, as in
4624 @code{#+asdf-unicode :encoding #+asdf-unicode :utf-8}.
4625 We recommend that you avoid using unprotected @code{:encoding} specifications
4626 until after ASDF 2.21 or later becomes widespread.
4627 As of May 2016, all maintained implementations provide ASDF 3.1,
4628 so you may prudently start using this and other features without such protection.
4630 While it offers plenty of hooks for extension,
4631 and one such extension is available (see @code{asdf-encodings} below),
4632 ASDF itself only recognizes one encoding beside @code{:default},
4633 and that is @code{:utf-8}, which is the @emph{de facto} standard,
4634 already used by the vast majority of libraries that use more than ASCII.
4635 On implementations that do not support unicode,
4636 the feature @code{:asdf-unicode} is absent, and
4637 the @code{:default} external-format is used
4638 to read even source files declared as @code{:utf-8}.
4639 On these implementations, non-ASCII characters
4640 intended to be read as one CL character
4641 may thus end up being read as multiple CL characters.
4642 In most cases, this shouldn't affect the software's semantics:
4643 comments will be skipped just the same, strings with be read and printed
4644 with slightly different lengths, symbol names will be accordingly longer,
4645 but none of it should matter.
4646 But a few systems that actually depend on unicode characters
4647 may fail to work properly, or may work in a subtly different way.
4648 See for instance @code{lambda-reader}.
4650 We invite you to embrace UTF-8
4651 as the encoding for non-ASCII characters starting today,
4652 even without any explicit specification in your @file{.asd} files.
4653 Indeed, on some implementations and configurations,
4654 UTF-8 is already the @code{:default},
4655 and loading your code may cause errors if it is encoded in anything but UTF-8.
4656 Therefore, even with the legacy behaviour,
4657 non-UTF-8 is guaranteed to break for some users,
4658 whereas UTF-8 is pretty much guaranteed not to break anywhere
4659 (provided you do @emph{not} use a BOM),
4660 although it might be read incorrectly on some implementations.
4661 @code{:utf-8} has been the default value of @code{*default-encoding*} since ASDF 3.
4663 If you need non-standard character encodings for your source code,
4664 use the extension system @code{asdf-encodings}, by specifying
4665 @code{:defsystem-depends-on ("asdf-encodings")} in your @code{defsystem}.
4666 This extension system will register support for more encodings using the
4667 @code{*encoding-external-format-hook*} facility,
4668 so you can explicitly specify @code{:encoding :latin1}
4669 in your @file{.asd} file.
4670 Using the @code{*encoding-detection-hook*} it will also
4671 eventually implement some autodetection of a file's encoding
4672 from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration,
4673 or otherwise based on an analysis of octet patterns in the file.
4674 At this point, @code{asdf-encoding} only supports the encodings
4675 that are supported as part of your implementation.
4676 Since the list varies depending on implementations,
4677 we still recommend you use @code{:utf-8} everywhere,
4678 which is the most portable (next to it is @code{:latin1}).
4680 Recent versions of Quicklisp include @code{asdf-encodings};
4681 if you're not using it, you may get this extension using git:
4682 @kbd{git clone https://gitlab.common-lisp.net/asdf/asdf-encodings.git}
4684 @kbd{git clone git@@gitlab.common-lisp.net:asdf/asdf-encodings.git}.
4685 You can also browse the repository on
4686 @url{https://gitlab.common-lisp.net/asdf/asdf-encodings}.
4688 When you use @code{asdf-encodings},
4689 any @file{.asd} file loaded
4690 will use the autodetection algorithm to determine its encoding.
4691 If you depend on this detection happening,
4692 you should explicitly load @code{asdf-encodings} early in your build.
4693 Note that @code{:defsystem-depends-on} cannot be used here: by the time
4694 the @code{:defsystem-depends-on} is loaded, the enclosing
4695 @code{defsystem} form has already been read.
4697 In practice, this means that the @code{*default-encoding*}
4698 is usually used for @file{.asd} files.
4699 Currently, this defaults to @code{:utf-8}, and
4700 you should be safe using Unicode characters in those files.
4701 This might matter, for instance, in meta-data about author's names.
4702 Otherwise, the main data in these files is component (path)names,
4703 and we don't recommend using non-ASCII characters for these,
4704 for the result probably isn't very portable.
4706 @node Miscellaneous Functions, Some Utility Functions, Controlling source file character encoding, Miscellaneous additional functionality
4707 @section Miscellaneous Functions
4709 These functions are exported by ASDF for your convenience.
4711 @anchor{system-relative-pathname}
4712 @defun system-relative-pathname system name @Akey{} type
4714 It's often handy to locate a file relative to some system.
4715 The @code{system-relative-pathname} function meets this need.
4717 It takes two mandatory arguments @var{system} and @var{name}
4718 and a keyword argument @var{type}:
4719 @var{system} is name of a system, whereas @var{name} and optionally @var{type}
4720 specify a relative pathname, interpreted like a component pathname specifier
4721 by @code{coerce-pathname}. @xref{The defsystem grammar,,Pathname specifiers}.
4723 It returns a pathname built from the location of the system's
4724 source directory and the relative pathname. For example:
4727 > (asdf:system-relative-pathname 'cl-ppcre "regex.data")
4728 #P"/repository/other/cl-ppcre/regex.data"
4733 @defun system-source-directory system-designator
4735 ASDF does not provide a turnkey solution for locating
4736 data (or other miscellaneous) files
4737 that are distributed together with the source code of a system.
4738 Programmers can use @code{system-source-directory} to find such files.
4739 Returns a pathname object.
4740 The @var{system-designator} may be a string, symbol, or ASDF system object.
4743 @defun clear-system system-designator
4745 It is sometimes useful to force recompilation of a previously loaded system.
4746 For these cases, @code{(asdf:clear-system :foo)}
4747 will remove the system from the table of currently loaded systems:
4748 the next time the system @code{foo} or one that depends on it is re-loaded,
4749 @code{foo} will be loaded again.@footnote{Alternatively, you could touch @code{foo.asd} or
4750 remove the corresponding fasls from the output file cache.}
4752 Note that this does not and cannot undo
4753 the previous loading of the system.
4754 Common Lisp has no provision for such an operation,
4755 and its reliance on irreversible side-effects to global data structures
4756 makes such a thing impossible in the general case.
4757 If the software being re-loaded is not conceived with hot upgrade in mind,
4758 re-loading may cause many errors, warnings or subtle silent problems,
4759 as packages, generic function signatures, structures, types, macros, constants, etc.
4760 are being redefined incompatibly.
4761 It is up to the user to make sure that reloading is possible and has the desired effect.
4762 In some cases, extreme measures such as recursively deleting packages,
4763 unregistering symbols, defining methods on @code{update-instance-for-redefined-class}
4764 and much more are necessary for reloading to happen smoothly.
4765 ASDF itself goes to extensive effort to make a hot upgrade possible
4766 with respect to its own code.
4767 If you want, you can reuse some of its utilities such as
4768 @code{uiop:define-package} and @code{uiop:with-upgradability},
4769 and get inspiration (or disinspiration)
4770 from what it does in @file{header.lisp} and @file{upgrade.lisp}.
4773 @defun register-preloaded-system name @Arest{} keys @Akey{} version @AallowOtherKeys{}
4774 A system with name @var{name},
4775 created by @code{make-instance} with extra keys @var{keys}
4776 (e.g. @code{:version}),
4777 is registered as @emph{preloaded}.
4778 If @var{version} is @code{t} (default), then the version is copied from the defined system
4779 of the same name (if registered) or else is @code{nil}
4780 (this automatic copy of version is only available starting since ASDF 3.1.8).
4782 A preloaded system is considered as having already been loaded into the current image,
4783 and if at some point some other system @code{:depends-on} it yet no source code is found,
4784 it is considered as already provided,
4785 and ASDF will not raise a @code{missing-component} error.
4787 This function is particularly useful if you distribute your code
4788 as fasls with either @code{compile-bundle-op} or @code{monolithic-compile-bundle-op},
4789 and want to register systems so that dependencies will work uniformly
4790 whether you're using your software from source or from fasl.
4792 Note that if the system was already defined or loaded from source code,
4793 its build information will remain active until you call @code{clear-system} on it,
4794 at which point a system without build information will be registered in its place.
4797 @defun register-immutable-system name @Arest{} keys
4798 A system with name @var{name} is registered as preloaded,
4799 and additionally is marked as @emph{immutable}:
4800 that is, attempts to compile or load it will be succeed
4801 without actually reading, creating or loading any file,
4802 as if the system was passed as a @code{force-not} argument
4803 to all calls to @code{plan} or @code{operate}.
4804 There will be no search for an updated @file{.asd} file
4805 to override the loaded version,
4806 whether from the source-register or any other method.
4808 If a @var{version} keyword argument is specified as @code{t} or left unspecified,
4809 then the version is copied from the defined system
4810 of the same name (if registered) or else is @code{nil}.
4811 This automatic copy of version is available starting
4812 since immutable systems have been available in ASDF 3.1.5.
4814 This function, available since ASDF 3.1.5, is particularly useful
4815 if you distribute a large body of code as a precompiled image,
4816 and want to allow users to extend the image with further extension systems,
4817 but without making thousands of filesystem requests looking for inexistent
4818 (or worse, out of date) source code
4819 for all the systems that came bundled with the image but aren't
4820 distributed as source code to regular users.
4821 @cindex immutable systems
4824 @defun run-shell-command control-string @Arest{} args
4826 This function is obsolete and present only for the sake of backwards-compatibility:
4827 ``If it's not backwards, it's not compatible''. We @emph{strongly} discourage its use.
4828 Its current behaviour is only well-defined on Unix platforms
4829 (which include MacOS X and cygwin). On Windows, anything goes.
4830 The following documentation is only for the purpose of your migrating away from it
4831 in a way that preserves semantics.
4833 Instead we recommend the use @code{run-program}, described in the next section, and
4834 available as part of ASDF since ASDF 3.
4836 @code{run-shell-command} takes as arguments a format @code{control-string}
4837 and arguments to be passed to @code{format} after this control-string
4838 to produce a string.
4839 This string is a command that will be evaluated with a POSIX shell if possible;
4840 yet, on Windows, some implementations will use CMD.EXE,
4841 while others (like SBCL) will make an attempt at invoking a POSIX shell
4842 (and fail if it is not present).
4845 @node Some Utility Functions, , Miscellaneous Functions, Miscellaneous additional functionality
4846 @section Some Utility Functions
4848 The below functions are not exported by ASDF itself, but by UIOP, available since ASDF 3.
4849 Some of them have precursors in ASDF 2, but we recommend that for active developments,
4850 you should rely on the package UIOP as included in ASDF 3.
4851 UIOP provides many, many more utility functions, and we recommend
4852 you read its @file{README.md} and sources for more information.
4855 @defun parse-unix-namestring name @Akey{} type defaults dot-dot ensure-directory @AallowOtherKeys
4856 Coerce @var{name} into a @var{pathname} using standard Unix syntax.
4858 Unix syntax is used whether or not the underlying system is Unix;
4859 on non-Unix systems it is only usable for relative pathnames.
4860 In order to manipulate relative pathnames portably, it is crucial
4861 to possess a portable pathname syntax independent of the underlying OS.
4862 This is what @code{parse-unix-namestring} provides, and why we use it in ASDF.
4864 When given a @code{pathname} object, just return it untouched.
4865 When given @code{nil}, just return @code{nil}.
4866 When given a non-null @code{symbol}, first downcase its name and treat it as a string.
4867 When given a @code{string}, portably decompose it into a pathname as below.
4869 @code{#\/} separates directory components.
4871 The last @code{#\/}-separated substring is interpreted as follows:
4872 1- If @var{type} is @code{:directory} or @var{ensure-directory} is true,
4873 the string is made the last directory component, and its @code{name} and @code{type} are @code{nil}.
4874 if the string is empty, it's the empty pathname with all slots @code{nil}.
4875 2- If @var{type} is @code{nil}, the substring is a file-namestring,
4876 and its @code{name} and @code{type} are separated by @code{split-name-type}.
4877 3- If @var{type} is a string, it is the given @code{type}, and the whole string is the @code{name}.
4879 Directory components with an empty name the name @code{.} are removed.
4880 Any directory named @code{..} is read as @var{dot-dot},
4881 which must be one of @code{:back} or @code{:up} and defaults to @code{:back}.
4883 @vindex *nil-pathname*
4884 @code{host}, @code{device} and @code{version} components are taken from @var{defaults},
4885 which itself defaults to @code{*nil-pathname*}.
4886 @code{*nil-pathname*} is also used if @var{defaults} is @code{nil}.
4887 No host or device can be specified in the string itself,
4888 which makes it unsuitable for absolute pathnames outside Unix.
4890 For relative pathnames, these components (and hence the defaults) won't matter
4891 if you use @code{merge-pathnames*} but will matter if you use @code{merge-pathnames},
4892 which is an important reason to always use @code{merge-pathnames*}.
4894 Arbitrary keys are accepted, and the parse result is passed to @code{ensure-pathname}
4895 with those keys, removing @var{type}, @var{defaults} and @var{dot-dot}.
4896 When you're manipulating pathnames that are supposed to make sense portably
4897 even though the OS may not be Unixish, we recommend you use @code{:want-relative t}
4898 so that @code{parse-unix-namestring} will throw an error if the pathname is absolute.
4901 @defun merge-pathnames* specified @Aoptional{} defaults
4903 This function is a replacement for @code{merge-pathnames} that uses the host and device
4904 from the @var{defaults} rather than the @var{specified} pathname when the latter
4905 is a relative pathname. This allows ASDF and its users to create and use relative pathnames
4906 without having to know beforehand what are the host and device
4907 of the absolute pathnames they are relative to.
4911 @defun subpathname pathname subpath @Akey{} type
4913 This function takes a @var{pathname} and a @var{subpath} and a @var{type}.
4914 If @var{subpath} is already a @code{pathname} object (not namestring),
4915 and is an absolute pathname at that, it is returned unchanged;
4916 otherwise, @var{subpath} is turned into a relative pathname with given @var{type}
4917 as per @code{parse-unix-namestring} with @code{:want-relative t :type }@var{type},
4918 then it is merged with the @code{pathname-directory-pathname} of @var{pathname},
4919 as per @code{merge-pathnames*}.
4921 We strongly encourage the use of this function
4922 for portably resolving relative pathnames in your code base.
4925 @defun subpathname* pathname subpath @Akey{} type
4927 This function returns @code{nil} if the base @var{pathname} is @code{nil},
4928 otherwise acts like @code{subpathname}.
4931 @defun run-program command @Akey{} ignore-error-status force-shell input output @
4932 error-output if-input-does-not-exist if-output-exists if-error-output-exists @
4933 element-type external-format @AallowOtherKeys
4935 @code{run-program} takes a @var{command} argument that is either
4936 a list of a program name or path and its arguments,
4937 or a string to be executed by a shell.
4938 It spawns the command, waits for it to return,
4939 verifies that it exited cleanly (unless told not too below),
4940 and optionally captures and processes its output.
4941 It accepts many keyword arguments to configure its behaviour.
4943 @code{run-program} returns three values: the first for the output,
4944 the second for the error-output, and the third for the return value.
4945 (Beware that before ASDF 3.0.2.11, it didn't handle input or error-output,
4946 and returned only one value,
4947 the one for the output if any handler was specified, or else the exit code;
4948 please upgrade ASDF, or at least UIOP, to rely on the new enhanced behaviour.)
4950 @var{output} is its most important argument;
4951 it specifies how the output is captured and processed.
4952 If it is @code{nil}, then the output is redirected to the null device,
4953 that will discard it.
4954 If it is @code{:interactive}, then it is inherited from the current process
4955 (beware: this may be different from your @var{*standard-output*},
4956 and under SLIME will be on your @code{*inferior-lisp*} buffer).
4957 If it is @code{t}, output goes to your current @var{*standard-output*} stream.
4958 Otherwise, @var{output} should be a value that is a suitable first argument to
4959 @code{slurp-input-stream} (see below), or
4960 a list of such a value and keyword arguments.
4961 In this case, @code{run-program} will
4962 create a temporary stream for the program output;
4963 the program output, in that stream,
4964 will be processed by a call to @code{slurp-input-stream},
4965 using @var{output} as the first argument
4966 (or if it's a list the first element of @var{output} and the rest as keywords).
4967 The primary value resulting from that call
4968 (or @code{nil} if no call was needed)
4969 will be the first value returned by @code{run-program}.
4970 E.g., using @code{:output :string}
4971 will have it return the entire output stream as a string.
4972 And using @code{:output '(:string :stripped t)}
4973 will have it return the same string stripped of any ending newline.
4975 @var{error-output} is similar to @var{output}, except that
4976 the resulting value is returned as the second value of @code{run-program}.
4977 @code{t} designates the @var{*error-output*}.
4978 Also @code{:output} means redirecting the error output to the output stream,
4979 in which case @code{nil} is returned.
4981 @var{input} is similar to @var{output}, except that
4982 @code{vomit-output-stream} is used, no value is returned,
4983 and @code{t} designates the @var{*standard-input*}.
4985 @code{element-type} and @code{external-format} are passed on
4986 to your Lisp implementation, when applicable, for creation of the output stream.
4988 One and only one of the stream slurping or vomiting may or may not happen
4989 in parallel in parallel with the subprocess,
4990 depending on options and implementation,
4991 and with priority being given to output processing.
4992 Other streams are completely produced or consumed
4993 before or after the subprocess is spawned, using temporary files.
4995 @code{force-shell} forces evaluation of the command through a shell,
4996 even if it was passed as a list rather than a string.
4997 If a shell is used, it is @file{/bin/sh} on Unix or @file{CMD.EXE} on Windows,
4998 except on implementations that (erroneously, IMNSHO)
4999 insist on consulting @code{$SHELL} like clisp.
5001 @code{ignore-error-status} causes @code{run-program}
5002 to not raise an error if the spawned program exits in error.
5003 Following POSIX convention, an error is anything but
5004 a normal exit with status code zero.
5005 By default, an error of type @code{subprocess-error} is raised in this case.
5007 @code{run-program} works on all platforms supported by ASDF, except Genera.
5008 See the source code for more documentation.
5012 @defun slurp-input-stream processor input-stream @Akey{}
5014 @code{slurp-input-stream} is a generic function of two arguments, a target object and an input stream,
5015 and accepting keyword arguments.
5016 Predefined methods based on the target object are as follows:
5020 If the object is a function, the function is called with the stream as argument.
5022 @item If the object is a cons, its first element is applied to its rest appended by
5023 a list of the input stream.
5025 @item If the object is an output stream, the contents of the input stream are copied to it.
5026 If the @var{linewise} keyword argument is provided, copying happens line by line,
5027 and an optional @var{prefix} is printed before each line.
5028 Otherwise, copying happen based on a buffer of size @var{buffer-size},
5029 using the specified @var{element-type}.
5031 @item If the object is @code{'string} or @code{:string}, the content is captured into a string.
5032 Accepted keywords include the @var{element-type} and a flag @var{stripped},
5033 which when true causes any single line ending to be removed as per @code{uiop:stripln}.
5035 @item If the object is @code{:lines}, the content is captured as a list of strings,
5036 one per line, without line ending. If the @var{count} keyword argument is provided,
5037 it is a maximum count of lines to be read.
5039 @item If the object is @code{:line}, the content is captured as with @code{:lines} above,
5040 and then its sub-object is extracted with the @var{at} argument,
5041 which defaults to @code{0}, extracting the first line.
5042 A number will extract the corresponding line.
5043 See the documentation for @code{uiop:access-at}.
5045 @item If the object is @code{:forms}, the content is captured as a list of s-expressions,
5046 as read by the Lisp reader.
5047 If the @var{count} argument is provided,
5048 it is a maximum count of lines to be read.
5049 We recommend you control the syntax with such macro as
5050 @code{uiop:with-safe-io-syntax}.
5052 @item If the object is @code{:form}, the content is captured as with @code{:forms} above,
5053 and then its sub-object is extracted with the @var{at} argument,
5054 which defaults to @code{0}, extracting the first form.
5055 A number will extract the corresponding form.
5056 See the documentation for @code{uiop:access-at}.
5057 We recommend you control the syntax with such macro as
5058 @code{uiop:with-safe-io-syntax}.
5063 @node Getting the latest version, FAQ, Miscellaneous additional functionality, Top
5064 @comment node-name, next, previous, up
5065 @chapter Getting the latest version
5068 Decide which version you want.
5069 The @code{master} branch is where development happens;
5070 its @code{HEAD} is usually OK, including the latest fixes and portability tweaks,
5071 but an occasional regression may happen despite our (limited) test suite.
5073 The @code{release} branch is what cautious people should be using;
5074 it has usually been tested more, and releases are cut at a point
5075 where there isn't any known unresolved issue.
5077 You may get the ASDF source repository using git:
5078 @kbd{git clone https://gitlab.common-lisp.net/asdf/asdf.git}
5080 You will find the above referenced tags in this repository.
5081 You can also browse the repository on
5082 @url{https://gitlab.common-lisp.net/asdf/asdf}.
5084 Discussion of ASDF development is conducted on the
5085 mailing list (@pxref{Mailing list}).
5087 @node FAQ, Ongoing Work, Getting the latest version, Top
5088 @comment node-name, next, previous, up
5092 * Where do I report a bug?::
5094 * What has changed between ASDF 1 ASDF 2 and ASDF 3?::
5095 * Issues with installing the proper version of ASDF::
5096 * Issues with configuring ASDF::
5097 * Issues with using and extending ASDF to define systems::
5098 * ASDF development FAQs::
5101 @node Where do I report a bug?, Mailing list, FAQ, FAQ
5102 @section ``Where do I report a bug?''
5105 ASDF bugs are tracked on launchpad: @url{https://launchpad.net/asdf}.
5107 If you're unsure about whether something is a bug, or for general discussion,
5108 use the asdf-devel mailing list (@pxref{Mailing list}).
5110 @node Mailing list, What has changed between ASDF 1 ASDF 2 and ASDF 3?, Where do I report a bug?, FAQ
5111 @section Mailing list
5112 @cindex mailing list
5114 Discussion of ASDF development is conducted on the
5116 @kbd{asdf-devel@@common-lisp.net}.
5117 @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel}
5120 @node What has changed between ASDF 1 ASDF 2 and ASDF 3?, Issues with installing the proper version of ASDF, Mailing list, FAQ
5121 @section ``What has changed between ASDF 1, ASDF 2, and ASDF 3?''
5123 We released ASDF 2.000 on May 31st 2010,
5124 ASDF 3.0.0 on May 15th 2013,
5125 ASDF 3.1.2 on May 6th 2014.
5126 Releases of ASDF 2 and now ASDF 3 have since then been included
5127 in all actively maintained CL implementations that used to bundle ASDF 1,
5128 plus many implementations that previously did not.
5129 ASDF has been made to work with all actively maintained CL
5130 implementations and even a few implementations that are @emph{not}
5131 actively maintained.
5133 Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly
5134 (though we recommend instead upgrading your implementation or replacing its ASDF module).
5135 For this reason, we have stopped supporting ASDF 1 and ASDF 2.
5136 If you are using ASDF 1 or ASDF 2 and are experiencing any kind of issues or limitations,
5137 we recommend you upgrade to ASDF 3
5138 --- and we explain how to do that. @xref{Loading ASDF}.
5140 Note that in the context of compatibility requirements,
5141 ASDF 2.27, released on Feb 1st 2013, and further releases up to 2.33,
5142 count as pre-releases of ASDF 3, and define the @code{:asdf3} feature,
5143 though the first stable release of ASDF 3 was release 3.0.1.
5144 Significant new or improved functionality were added in ASDF 3.1;
5145 the @code{:asdf3.1} feature is present in recent enough versions to detect this functionality;
5146 the first stable release since then was ASDF 3.1.2.
5147 New @code{*features*} are only added at major milestones,
5148 and the next one will probably be @code{:asdf3.2}.
5152 * What are ASDF 1 2 3?::
5153 * How do I detect the ASDF version?::
5154 * ASDF can portably name files in subdirectories::
5155 * Output translations::
5156 * Source Registry Configuration::
5157 * Usual operations are made easier to the user::
5158 * Many bugs have been fixed::
5159 * ASDF itself is versioned::
5160 * ASDF can be upgraded::
5161 * Decoupled release cycle::
5162 * Pitfalls of the transition to ASDF 2::
5163 * Pitfalls of the upgrade to ASDF 3::
5164 * What happened to the bundle operations::
5167 @node What are ASDF 1 2 3?, How do I detect the ASDF version?, What has changed between ASDF 1 ASDF 2 and ASDF 3?, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5168 @subsection What are ASDF 1, ASDF 2, and ASDF 3?
5170 ASDF 1 refers to any release earlier than 1.369 or so (from August 2001 to October 2009),
5171 and to any development revision earlier than 2.000 (May 2010).
5172 If your copy of ASDF doesn't even contain version information, it's an old ASDF 1.
5173 Revisions between 1.656 and 1.728 may count as development releases for ASDF 2.
5175 ASDF 2 refers to releases from 2.000 (May 31st 2010) to 2.26 (Oct 30th 2012),
5176 and any development revision newer than ASDF 1 and older than 2.27 (Feb 1st 2013).
5178 ASDF 3 refers to releases from 2.27 (Feb 1st 2013) to 2.33 and 3.0.0 onward (May 15th 2013).
5179 2.27 to 2.33 count as pre-releases to ASDF 3.
5181 ASDF 3.1 refers to releases from 3.1.2 (May 6th 2014) onward.
5182 These releases are also considered part of ASDF 3.
5184 @node How do I detect the ASDF version?, ASDF can portably name files in subdirectories, What are ASDF 1 2 3?, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5185 @subsection How do I detect the ASDF version?
5186 @findex asdf-version
5189 All releases of ASDF
5190 push @code{:asdf} onto @code{*features*}.
5191 Releases starting with ASDF 2
5192 push @code{:asdf2} onto @code{*features*}.
5193 Releases starting with ASDF 3 (including 2.27 and later pre-releases)
5194 push @code{:asdf3} onto @code{*features*}.
5195 Furthermore, releases starting with ASDF 3.1.2 (May 2014),
5196 though they count as ASDF 3, include enough progress that they
5197 also push @code{:asdf3.1} onto @code{*features*}.
5198 You may depend on the presence or absence of these features
5199 to write code that takes advantage of recent ASDF functionality
5200 but still works on older versions, or at least detects the old version and signals an error.
5202 Additionally, all releases starting with ASDF 2
5203 define a function @code{(asdf:asdf-version)} you may use to query the version.
5204 All releases starting with 2.013 display the version number prominently
5205 on the second line of the @file{asdf.lisp} source file.
5207 If you are experiencing problems or limitations of any sort with ASDF 1 or ASDF 2,
5208 we recommend that you should upgrade to the latest release, be it ASDF 3 or other.
5210 Finally, here is a code snippet to programmatically determine what version of ASDF is loaded, if any,
5211 that works on all versions including very old ones:
5214 (when (find-package :asdf)
5215 (let ((ver (symbol-value
5216 (or (find-symbol (string :*asdf-version*) :asdf)
5217 (find-symbol (string :*asdf-revision*) :asdf)))))
5220 (cons (with-output-to-string (s)
5221 (loop for (n . m) on ver
5223 (when m (princ "." s)))))
5227 If it returns @code{nil} then ASDF is not installed.
5228 Otherwise it should return a string.
5229 If it returns @code{"1.0"}, then it can actually be
5230 any version before 1.77 or so, or some buggy variant of 1.x.
5231 If it returns anything older than @code{"3.0.1"},
5232 you really need to upgrade your implementation or at least upgrade its ASDF.
5233 @xref{Replacing your implementation's ASDF}.
5237 @node ASDF can portably name files in subdirectories, Output translations, How do I detect the ASDF version?, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5238 @subsection ASDF can portably name files in subdirectories
5240 Common Lisp namestrings are not portable,
5241 except maybe for logical pathname namestrings,
5242 that themselves have various limitations and require a lot of setup
5243 that is itself ultimately non-portable.
5245 In ASDF 1, the only portable ways to refer to pathnames inside systems and components
5246 were very awkward, using @code{#.(make-pathname ...)} and
5247 @code{#.(merge-pathnames ...)}.
5248 Even the above were themselves were inadequate in the general case
5249 due to host and device issues, unless horribly complex patterns were used.
5250 Plenty of simple cases that looked portable actually weren't,
5251 leading to much confusion and greavance.
5253 ASDF 2 implements its own portable syntax for strings as pathname specifiers.
5254 Naming files within a system definition becomes easy and portable again.
5255 @xref{Miscellaneous additional functionality,system-relative-pathname},
5256 @code{merge-pathnames*},
5257 @code{coerce-pathname}.
5259 On the other hand, there are places where systems used to accept namestrings
5260 where you must now use an explicit pathname object:
5261 @code{(defsystem ... :pathname "LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
5262 must now be written with the @code{#p} syntax:
5263 @code{(defsystem ... :pathname #p"LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
5265 @xref{The defsystem grammar,,Pathname specifiers}.
5268 @node Output translations, Source Registry Configuration, ASDF can portably name files in subdirectories, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5269 @subsection Output translations
5271 A popular feature added to ASDF was output pathname translation:
5272 @code{asdf-binary-locations}, @code{common-lisp-controller},
5273 @code{cl-launch} and other hacks were all implementing it in ways
5274 both mutually incompatible and difficult to configure.
5276 Output pathname translation is essential to share
5277 source directories of portable systems across multiple implementations
5278 or variants thereof,
5279 or source directories of shared installations of systems across multiple users,
5280 or combinations of the above.
5282 In ASDF 2, a standard mechanism is provided for that,
5283 @code{asdf-output-translations},
5284 with sensible defaults, adequate configuration languages,
5285 a coherent set of configuration files and hooks,
5286 and support for non-Unix platforms.
5288 @xref{Controlling where ASDF saves compiled files}.
5290 @node Source Registry Configuration, Usual operations are made easier to the user, Output translations, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5291 @subsection Source Registry Configuration
5293 Configuring ASDF used to require special magic
5294 to be applied just at the right moment,
5295 between the moment ASDF is loaded and the moment it is used,
5296 in a way that is specific to the user,
5297 the implementation he is using and the application he is building.
5299 This made for awkward configuration files and startup scripts
5300 that could not be shared between users, managed by administrators
5301 or packaged by distributions.
5303 ASDF 2 provides a well-documented way to configure ASDF,
5304 with sensible defaults, adequate configuration languages,
5305 and a coherent set of configuration files and hooks.
5307 We believe it's a vast improvement because it decouples
5308 application distribution from library distribution.
5309 The application writer can avoid thinking where the libraries are,
5310 and the library distributor (dpkg, clbuild, advanced user, etc.)
5311 can configure them once and for every application.
5312 Yet settings can be easily overridden where needed,
5313 so whoever needs control has exactly as much as required.
5315 At the same time, ASDF 2 remains compatible
5316 with the old magic you may have in your build scripts
5317 (using @code{*central-registry*} and
5318 @code{*system-definition-search-functions*})
5319 to tailor the ASDF configuration to your build automation needs,
5320 and also allows for new magic, simpler and more powerful magic.
5322 @xref{Controlling where ASDF searches for systems}.
5325 @node Usual operations are made easier to the user, Many bugs have been fixed, Source Registry Configuration, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5326 @subsection Usual operations are made easier to the user
5328 In ASDF 1, you had to use the awkward syntax
5329 @code{(asdf:oos 'asdf:load-op :foo)}
5331 and similarly for @code{compile-op}, @code{test-op}.
5333 In ASDF 2, you can use shortcuts for the usual operations:
5334 @code{(asdf:load-system :foo)}, and
5335 similarly for @code{compile-system}, @code{test-system}.
5338 @node Many bugs have been fixed, ASDF itself is versioned, Usual operations are made easier to the user, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5339 @subsection Many bugs have been fixed
5341 The following issues and many others have been fixed:
5345 The infamous TRAVERSE function has been revamped completely
5346 between ASDF 1 and ASDF 2, with many bugs squashed.
5347 In particular, dependencies were not correctly propagated
5348 across modules but now are.
5349 It has been completely rewritten many times over
5350 between ASDF 2.000 and ASDF 3,
5351 with fundamental issues in the original model being fixed.
5352 Timestamps were not propagated at all, and now are.
5353 The internal model of how actions depend on each other
5354 is now both consistent and complete.
5355 The @code{:version} and
5356 the @code{:force (system1 .. systemN)} feature have been fixed.
5359 Performance has been notably improved for large systems
5360 (say with thousands of components) by using
5361 hash-tables instead of linear search,
5362 and linear-time list accumulation instead of cubic time recursive append,
5363 for an overall @emph{O(n)} complexity vs @emph{O(n^4)}.
5366 Many features used to not be portable,
5367 especially where pathnames were involved.
5368 Windows support was notably quirky because of such non-portability.
5371 The internal test suite used to massively fail on many implementations.
5372 While still incomplete, it now fully passes
5373 on all implementations supported by the test suite,
5374 though some tests are commented out on a few implementations.
5377 Support was lacking for some implementations.
5378 ABCL and GCL were notably wholly broken.
5379 ECL extensions were not integrated with ASDF release.
5382 The documentation was grossly out of date.
5387 @node ASDF itself is versioned, ASDF can be upgraded, Many bugs have been fixed, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5388 @subsection ASDF itself is versioned
5390 Between new features, old bugs fixed, and new bugs introduced,
5391 there were various releases of ASDF in the wild,
5392 and no simple way to check which release had which feature set.
5393 People using or writing systems had to either make worst-case assumptions
5394 as to what features were available and worked,
5395 or take great pains to have the correct version of ASDF installed.
5397 With ASDF 2, we provide a new stable set of working features
5398 that everyone can rely on from now on.
5399 Use @code{#+asdf2} to detect presence of ASDF 2,
5400 @code{(asdf:version-satisfies (asdf:asdf-version) "2.345.67")}
5401 to check the availability of a version no earlier than required.
5404 @node ASDF can be upgraded, Decoupled release cycle, ASDF itself is versioned, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5405 @subsection ASDF can be upgraded
5407 When an old version of ASDF was loaded,
5408 it was very hard to upgrade ASDF in your current image
5409 without breaking everything.
5410 Instead you had to exit the Lisp process and
5411 somehow arrange to start a new one from a simpler image.
5412 Something that can't be done from within Lisp,
5413 making automation of it difficult,
5414 which compounded with difficulty in configuration,
5415 made the task quite hard.
5416 Yet as we saw before, the task would have been required
5417 to not have to live with the worst case or non-portable
5418 subset of ASDF features.
5420 With ASDF 2, it is easy to upgrade
5421 from ASDF 2 to later versions from within Lisp,
5422 and not too hard to upgrade from ASDF 1 to ASDF 2 from within Lisp.
5423 We support hot upgrade of ASDF and any breakage is a bug
5424 that we will do our best to fix.
5425 There are still limitations on upgrade, though,
5426 most notably the fact that after you upgrade ASDF,
5427 you must also reload or upgrade all ASDF extensions.
5429 @node Decoupled release cycle, Pitfalls of the transition to ASDF 2, ASDF can be upgraded, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5430 @subsection Decoupled release cycle
5432 When vendors were releasing their Lisp implementations with ASDF,
5433 they had to basically never change version
5434 because neither upgrade nor downgrade was possible
5435 without breaking something for someone,
5436 and no obvious upgrade path was visible and recommendable.
5438 With ASDF 2, upgrade is possible, easy and can be recommended.
5439 This means that vendors can safely ship a recent version of ASDF,
5440 confident that if a user isn't fully satisfied,
5441 he can easily upgrade ASDF and deal
5442 with a supported recent version of it.
5443 This means that release cycles will be causally decoupled,
5444 the practical consequence of which will mean faster convergence
5445 towards the latest version for everyone.
5448 @node Pitfalls of the transition to ASDF 2, Pitfalls of the upgrade to ASDF 3, Decoupled release cycle, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5449 @subsection Pitfalls of the transition to ASDF 2
5451 The main pitfalls in upgrading to ASDF 2 seem to be related
5452 to the output translation mechanism.
5457 Output translations is enabled by default. This may surprise some users,
5458 most of them in pleasant way (we hope), a few of them in an unpleasant way.
5459 It is trivial to disable output translations.
5460 @xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
5463 Some systems in the large have been known
5464 not to play well with output translations.
5465 They were relatively easy to fix.
5466 Once again, it is also easy to disable output translations,
5467 or to override its configuration.
5470 The new ASDF output translations are incompatible with ASDF-Binary-Locations.
5471 They replace A-B-L, and there is compatibility mode to emulate
5472 your previous A-B-L configuration.
5473 See @code{enable-asdf-binary-locations-compatibility} in
5474 @pxref{Controlling where ASDF saves compiled files,,Backward Compatibility}.
5475 But thou shalt not load ABL on top of ASDF 2.
5479 Other issues include the following:
5484 ASDF pathname designators are now specified
5485 in places where they were unspecified,
5486 and a few small adjustments have to be made to some non-portable defsystems.
5487 Notably, in the @code{:pathname} argument
5488 to a @code{defsystem} and its components,
5489 a logical pathname (or implementation-dependent hierarchical pathname)
5490 must now be specified with @code{#p} syntax
5491 where the namestring might have previously sufficed;
5492 moreover when evaluation is desired @code{#.} must be used,
5493 where it wasn't necessary in the toplevel @code{:pathname} argument
5494 (but necessary in other @code{:pathname} arguments).
5497 There is a slight performance bug, notably on SBCL,
5498 when initially searching for @file{asd} files,
5499 the implicit @code{(directory "/configured/path/**/*.asd")}
5500 for every configured path @code{(:tree "/configured/path/")}
5501 in your @code{source-registry} configuration can cause a slight pause.
5502 Try to @code{(time (asdf:initialize-source-registry))}
5503 to see how bad it is or isn't on your system.
5504 If you insist on not having this pause,
5505 you can avoid the pause by overriding the default source-registry configuration
5506 and not use any deep @code{:tree} entry but only @code{:directory} entries
5507 or shallow @code{:tree} entries.
5508 Or you can fix your implementation to not be quite that slow
5509 when recursing through directories.
5510 @emph{Update}: This performance bug fixed the hard way in 2.010.
5513 On Windows, only LispWorks supports proper default configuration pathnames
5514 based on the Windows registry.
5515 Other implementations make do with environment variables,
5516 that you may have to define yourself
5517 if you're using an older version of Windows.
5518 Windows support is somewhat less tested than Unix support.
5519 Please help report and fix bugs.
5520 @emph{Update}: As of ASDF 2.21, all implementations
5521 should now use the same proper default configuration pathnames
5522 and they should actually work, though they haven't all been tested.
5525 The mechanism by which one customizes a system so that Lisp files
5526 may use a different extension from the default @file{.lisp} has changed.
5527 Previously, the pathname for a component
5528 was lazily computed when operating on a system,
5530 @code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
5531 (declare (ignorable component system)) "lis")}.
5532 Now, the pathname for a component is eagerly computed when defining the system,
5533 and instead you will @code{(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))}
5534 and use @code{:default-component-class cl-source-file.lis}
5535 as argument to @code{defsystem},
5536 as detailed in a @pxref{FAQ,How do I create a system definition where all the source files have a .cl extension?} below.
5537 @code{source-file-type} is deprecated. To access a component's
5538 file-type, use @code{file-type}, instead. @code{source-file-type} will
5541 @findex source-file-type
5547 @node Pitfalls of the upgrade to ASDF 3, What happened to the bundle operations, Pitfalls of the transition to ASDF 2, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5548 @subsection Pitfalls of the upgrade to ASDF 3
5550 While ASDF 3 is largely compatible with ASDF 2,
5551 there are a few pitfalls when upgrading from ASDF 2,
5552 due to limitations in ASDF 2.
5557 ASDF 2 was designed so it could be upgraded;
5558 but upgrading it required a special setup at the beginning of your build files.
5559 Failure to upgrade it early could result in catastrophic attempt to self-upgrade in mid-build.
5562 Starting with ASDF 3 (2.27 or later),
5563 ASDF will automatically attempt to upgrade itself
5564 as the first step before any system operation,
5565 to avoid any possibility of such catastrophic mid-build self-upgrade.
5566 But that doesn't help if your old implementation still provides ASDF 2.
5569 It was unsafe in ASDF 2 for a system definition to declare a dependency on ASDF,
5570 since it could trigger such catastrophe for users who were not carefully configured.
5571 If you declare a dependency on a recent enough ASDF,
5572 yet want to be nice with these potentially misconfigured users,
5573 we recommend that you not only specify a recent ASDF in your dependencies with
5574 @code{:depends-on ((:version "asdf" "3.1.2"))},
5575 but that you @emph{also} check that ASDF 3 is installed,
5576 or else the upgrade catastrophe might happen before that specification is checked,
5577 by starting your @file{.asd} file with a version check as follows:
5579 #-asdf3 (error "@var{MY-SYSTEM} requires ASDF 3.1.2")
5583 When you upgrade from too old a version of ASDF,
5584 previously loaded ASDF extensions become invalid, and will need to be reloaded.
5585 Example extensions include CFFI-Grovel, hacks used by ironclad, etc.
5586 Since it isn't possible to automatically detect what extensions
5587 need to be invalidated and what systems use them,
5588 ASDF will invalidate @emph{all} previously loaded systems
5589 when it is loaded on top of a forward-incompatible ASDF version.
5591 @vindex *oldest-forward-compatible-asdf-version*
5592 Forward incompatibility can be determined using the variable
5593 @code{asdf/upgrade::*oldest-forward-compatible-asdf-version*},
5594 which is 2.33 at the time of this writing.}
5597 To write a portable build script, you need to rely on a recent version of UIOP,
5598 but until you have ensured a recent ASDF is loaded,
5599 you can't rely on UIOP being present,
5600 and thus must manually avoid all the pathname pitfalls when loading ASDF itself.
5603 Bugs in CMUCL and XCL prevent upgrade of ASDF from an old forward-incompatible version.
5604 Happily, CMUCL comes with a recent ASDF,
5605 and XCL is more of a working demo than something you'd use seriously anyway.
5608 For the above reasons, your build and startup scripts
5609 should load ASDF 3, configure it, and upgrade it,
5610 among the very first things they do.
5611 They should ensure that only ASDF 3 or later is used indeed,
5612 and error out if ASDF 2 or earlier was used.
5615 Now that (since May 2016) all maintained implementations
5616 (i.e. having had at least one release since 2014,
5617 or a commit on their public source code repository)
5618 provide ASDF 3.1 or later,
5619 the simple solution is just to use code as below in your setup,
5620 and when it fails, upgrade your implementation or replace its ASDF.
5621 (@pxref{Replacing your implementation's ASDF}):
5624 #-asdf3.1 (error "ASDF 3.1 or bust")
5628 For scripts that try to use ASDF simply via @code{require} at first, and
5629 make heroic attempts to load it the hard way if at first they don't succeed,
5630 see @file{tools/load-asdf.lisp} distributed with the ASDF source repository,
5631 or the code of @url{https://cliki.net/cl-launch,@code{cl-launch}}.
5633 @item @anchor{reinitializeASDFAfterUpgrade}
5634 Note that in addition to the pitfalls and constraints above,
5635 these heroic scripts (should you wish to write or modify one),
5636 must take care to configure ASDF @emph{twice}.
5637 A first time, right after you load the old ASDF 2 (or 1!)
5638 and before you upgrade to the new ASDF 3,
5639 so it may find where you put ASDF 3.
5640 A second time, because most implementations can't handle a smooth upgrade from ASDF 2 to ASDF 3,
5641 so ASDF 3 doesn't try (anymore) and loses any configuration from ASDF 2.
5643 (ignore-errors (funcall 'require "asdf")) ;; <--- try real hard
5644 ;; <--- insert heroics here, if that failed to provide ASDF 2 or 3
5645 ;; <--- insert configuration here, if that succeeded
5646 (asdf:load-system "asdf")
5647 ;; <--- re-configure here, too, in case at first you got ASDF 2
5653 @node What happened to the bundle operations, , Pitfalls of the upgrade to ASDF 3, What has changed between ASDF 1 ASDF 2 and ASDF 3?
5654 @subsection What happened to the bundle operations?
5656 @tindex fasl-op (obsolete)
5657 @tindex load-fasl-op (obsolete)
5658 @tindex binary-op (obsolete)
5659 @tindex monolithic-fasl-op (obsolete)
5660 @tindex monolithic-load-fasl-op (obsolete)
5661 @tindex monolithic-binary-op (obsolete)
5662 @tindex compile-bundle-op
5663 @tindex load-bundle-op
5664 @tindex deliver-asd-op
5665 @tindex monolithic-compile-bundle-op
5666 @tindex monolithic-load-bundle-op
5667 @tindex monolithic-deliver-asd-op
5669 @code{asdf-ecl} and its short-lived successor @code{asdf-bundle} are no more,
5670 having been replaced by code now built into ASDF 3.
5671 Moreover, the name of the bundle operations has changed since ASDF 3.1.3.
5672 Starting with ASDF 3.2.0, @code{load-system}
5673 will once again use @code{load-bundle-op} instead of @code{load-op} on ECL,
5674 as originally intended by @code{asdf-ecl} authors, but disabled for a long time
5675 due to bugs in both ECL and ASDF.
5677 Note that some of the bundle operations were renamed after ASDF 3.1.3,
5678 and the old names have been removed.
5679 Old bundle operations, and their modern equivalents are:
5683 @code{fasl-op} is now @code{compile-bundle-op}
5685 @code{load-fasl-op} is now @code{load-bundle-op}
5687 @code{binary-op} is now @code{deliver-asd-op}
5689 @code{monolithic-fasl-op} is now @code{monolithic-compile-bundle-op}
5691 @code{monolithic-load-fasl-op} is now @code{monolithic-load-bundle-op}
5693 @code{monolithic-binary-op} is now @code{monolithic-deliver-asd-op}
5698 @node Issues with installing the proper version of ASDF, Issues with configuring ASDF, What has changed between ASDF 1 ASDF 2 and ASDF 3?, FAQ
5699 @section Issues with installing the proper version of ASDF
5702 * My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
5703 * I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::
5704 * After upgrading ASDF, ASDF (and Quicklisp) can't find my systems: After upgrading ASDF.
5707 @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
5708 @subsection ``My Common Lisp implementation comes with an outdated version of ASDF. What to do?''
5710 If you have a recent implementation, it should already come with ASDF 3 or later.
5711 If you need a more recent version than is provided,
5712 we recommend you simply upgrade ASDF by installing a recent version
5713 in a path configured in your source-registry.
5714 @xref{Upgrading ASDF}.
5716 If you have an old implementation that does not provide ASDF 3,
5717 we recommend you replace your implementation's ASDF.
5718 @xref{Replacing your implementation's ASDF}.
5721 @node I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?, After upgrading ASDF, My Common Lisp implementation comes with an outdated version of ASDF. What to do?, Issues with installing the proper version of ASDF
5722 @subsection ``I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?''
5725 it should always be a good time to upgrade to a recent version of ASDF.
5726 You may consult with the maintainer for which specific version they recommend,
5727 but the latest @code{release} should be correct.
5728 Though we do try to test ASDF releases against all implementations that we can,
5729 we may not be testing against all variants of your implementation,
5730 and we may not be running enough tests;
5731 we trust you to thoroughly test it with your own implementation
5732 before you release it.
5733 If there are any issues with the current release,
5734 it's a bug that you should report upstream and that we will fix ASAP.
5736 As to how to include ASDF, we recommend the following:
5740 If ASDF isn't loaded yet, then @code{(require "asdf")}
5741 should load the version of ASDF that is bundled with your system.
5742 If possible so should @code{(require "ASDF")}.
5743 You may have it load some other version configured by the user,
5744 if you allow such configuration.
5747 If your system provides a mechanism to hook into @code{cl:require},
5748 then it would be nice to add ASDF to this hook the same way that
5749 ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it.
5750 Please send us appropriate code to this end.
5753 You may, like SBCL since 1.1.13 or MKCL since 1.1.9,
5754 have ASDF create bundle FASLs
5755 that are provided as modules by your Lisp distribution.
5756 You may also, but we don't recommend that anymore,
5757 as in SBCL up until 1.1.12, have ASDF be implicitly used
5758 to @code{cl:require} these modules that are provided by your Lisp distribution;
5759 if you do, you should add these modules in the beginning of both
5760 @code{wrapping-source-registry} and @code{wrapping-output-translations}.
5763 If you have magic systems as above, like SBCL used to do,
5764 then we explicitly ask you to @emph{NOT} distribute
5765 @file{asdf.asd} as part of those magic systems.
5766 You should still include the file @file{asdf.lisp} in your source distribution
5767 and precompile it in your binary distribution,
5768 but @file{asdf.asd} if included at all,
5769 should be secluded from the magic systems,
5770 in a separate file hierarchy.
5771 Alternatively, you may provide the system
5772 after renaming it and its @file{.asd} file to e.g.
5773 @code{asdf-ecl} and @file{asdf-ecl.asd}, or
5774 @code{sb-asdf} and @file{sb-asdf.asd}.
5775 Indeed, if you made @file{asdf.asd} a magic system,
5776 then users would no longer be able to upgrade ASDF using ASDF itself
5777 to some version of their preference that
5778 they maintain independently from your Lisp distribution.
5781 If you do not have any such magic systems, or have other non-magic systems
5782 that you want to bundle with your implementation,
5783 then you may add them to the @code{wrapping-source-registry},
5784 and you are welcome to include @file{asdf.asd} amongst them.
5785 Non-magic systems should be at the back of the @code{wrapping-source-registry}
5786 while magic systems are at the front.
5787 If they are precompiled,
5788 they should also be in the @code{wrapping-output-translations}.
5791 Since ASDF 3, the library UIOP comes transcluded in ASDF.
5792 But if you want to be nice to users who care for UIOP but not for ASDF,
5793 you may package UIOP separately,
5794 so that one may @code{(require "uiop")} and not load ASDF,
5795 or one may @code{(require "asdf")}
5796 which would implicitly require and load the former.
5799 Please send us upstream any patches you make to ASDF itself,
5800 so we can merge them back in for the benefit of your users
5801 when they upgrade to the upstream version.
5805 @node After upgrading ASDF, , I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?, Issues with installing the proper version of ASDF
5806 @subsection After upgrading ASDF, ASDF (and Quicklisp) can't find my systems
5807 @vindex *central-registry*
5810 When you upgrade the ASDF running in your Lisp image
5811 from an ancient ASDF 2 or older to ASDF 3 or newer,
5812 then you may have to re-configure ASDF.
5813 If your configuration only consists in
5814 using the source-registry and output-translations (as it should),
5815 and if you are not explicitly calling @code{asdf:initialize-source-registry}
5816 or @code{asdf:initialize-output-translations} with a non-nil argument,
5817 then ASDF will reconfigure itself.
5818 Otherwise, you will have to configure ASDF 2 (or older) to find ASDF 3,
5819 then configure ASDF 3.
5820 Notably, @var{*central-registry*} is not maintained across upgrades from ASDF 2.
5821 @xref{reinitializeASDFAfterUpgrade,note about ASDF reconfiguration after upgrade}.
5823 Problems like this may be experienced if one loads Quicklisp
5824 (which as of this writing bundles an obsolete ASDF version 2.26),
5825 upgrades ASDF, and then tries to load new systems.
5826 The correct solution is to load the most up-to-date ASDF you can,
5827 @emph{then} configure it, @emph{then} load Quicklisp and any other extension.
5828 Do @emph{not} try to upgrade from ASDF 2 @emph{after} loading Quicklisp,
5829 for it will leave both ASDF and Quicklisp badly misconfigured.
5830 For details see the discussion at the above cross-reference.
5832 Also, if you are experiencing such failures due to Quicklisp shipping an ancient ASDF,
5833 please complain to Zach Beane about it.
5836 @node Issues with configuring ASDF, Issues with using and extending ASDF to define systems, Issues with installing the proper version of ASDF, FAQ
5837 @section Issues with configuring ASDF
5840 * How can I customize where fasl files are stored?::
5841 * How can I wholly disable the compiler output cache?::
5844 @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
5845 @subsection ``How can I customize where fasl files are stored?''
5847 @xref{Controlling where ASDF saves compiled files}.
5849 Note that in the past there was an add-on to ASDF called
5850 @code{ASDF-binary-locations}, developed by Gary King.
5851 That add-on has been merged into ASDF proper,
5852 then superseded by the @code{asdf-output-translations} facility.
5854 Note that use of @code{asdf-output-translations}
5855 can interfere with one aspect of your systems
5856 --- if your system uses @code{*load-truename*} to find files
5857 (e.g., if you have some data files stored with your program),
5858 then the relocation that this ASDF customization performs
5859 is likely to interfere.
5860 Use @code{asdf:system-relative-pathname} to locate a file
5861 in the source directory of some system, and
5862 use @code{asdf:apply-output-translations} to locate a file
5863 whose pathname has been translated by the facility.
5865 @node How can I wholly disable the compiler output cache?, , How can I customize where fasl files are stored?, Issues with configuring ASDF
5866 @subsection ``How can I wholly disable the compiler output cache?''
5868 To permanently disable the compiler output cache
5869 for all future runs of ASDF, you can:
5872 mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/
5873 echo ':disable-cache' > \
5874 ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
5877 This assumes that you didn't otherwise configure the ASDF files
5878 (if you did, edit them again),
5879 and don't somehow override the configuration at runtime
5880 with a shell variable (see below) or some other runtime command
5881 (e.g. some call to @code{asdf:initialize-output-translations}).
5883 To disable the compiler output cache in Lisp processes
5884 run by your current shell, try (assuming @code{bash} or @code{zsh})
5885 (on Unix and cygwin only):
5888 export ASDF_OUTPUT_TRANSLATIONS=/:
5891 To disable the compiler output cache just in the current Lisp process,
5892 use (after loading ASDF but before using it):
5895 (asdf:disable-output-translations)
5898 Note that this does @emph{NOT} belong in a @file{.asd} file.
5899 Please do not tamper with ASDF configuration from a @file{.asd} file,
5900 and only do this from your personal configuration or build scripts.
5902 @node Issues with using and extending ASDF to define systems, ASDF development FAQs, Issues with configuring ASDF, FAQ
5903 @section Issues with using and extending ASDF to define systems
5906 * How can I cater for unit-testing in my system?::
5907 * How can I cater for documentation generation in my system?::
5908 * How can I maintain non-Lisp (e.g. C) source files?::
5909 * I want to put my module's files at the top level. How do I do this?::
5910 * How do I create a system definition where all the source files have a .cl extension?::
5911 * How do I mark a source file to be loaded only and not compiled?::
5912 * How do I work with readtables?::
5913 * How can I capture ASDF's output?::
5914 * LOAD-PATHNAME has a weird value::
5917 @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
5918 @subsection ``How can I cater for unit-testing in my system?''
5920 ASDF provides a predefined test operation, @code{test-op}.
5921 @xref{Predefined operations of ASDF, test-op}.
5922 The test operation, however, is largely left to the system definer to specify.
5923 @code{test-op} has been
5924 a topic of considerable discussion on the
5925 @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
5926 (@pxref{Mailing list}),
5928 @url{https://launchpad.net/asdf,launchpad bug-tracker} (@pxref{Where do I report a bug?}).
5929 We provide some guidelines in the discussion of @code{test-op}.
5931 @c cut the following because it's discussed in the discussion of test-op.
5932 @c Here are some guidelines:
5936 @c For a given system, @var{foo}, you will want to define a corresponding
5937 @c test system, such as @var{foo-test}. The reason that you will want this
5938 @c separate system is that ASDF does not out of the box supply components
5939 @c that are conditionally loaded. So if you want to have source files
5940 @c (with the test definitions) that will not be loaded except when testing,
5941 @c they should be put elsewhere.
5944 @c The @var{foo-test} system can be defined in an asd file of its own or
5945 @c together with @var{foo}. An aesthetic preference against cluttering up
5946 @c the filesystem with extra asd files should be balanced against the
5947 @c question of whether one might want to directly load @var{foo-test}.
5948 @c Typically one would not want to do this except in early stages of
5952 @c Record that testing is implemented by @var{foo-test}. For example:
5954 @c (defsystem @var{foo}
5955 @c :in-order-to ((test-op (test-op @var{foo-test})))
5958 @c (defsystem @var{foo-test}
5959 @c :depends-on (@var{foo} @var{my-test-library} ...)
5964 @c This procedure will allow you to support users who do not wish to
5965 @c install your test framework.
5967 @c One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
5968 @c does not return a value. So in current versions of ASDF there is no
5969 @c reliable programmatic means of determining whether or not a set of tests
5970 @c has passed, or which tests have failed. The user must simply read the
5971 @c console output. This limitation has been the subject of much
5974 @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
5975 @subsection ``How can I cater for documentation generation in my system?''
5977 Various ASDF extensions provide some kind of @code{doc-op} operation.
5978 See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
5981 @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
5982 @subsection ``How can I maintain non-Lisp (e.g. C) source files?''
5984 See @code{cffi}'s @code{cffi-grovel}.
5986 @anchor{report-bugs}
5989 @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
5990 @subsection ``I want to put my module's files at the top level. How do I do this?''
5992 By default, the files contained in an asdf module go
5993 in a subdirectory with the same name as the module.
5994 However, this can be overridden by adding a @code{:pathname ""} argument
5995 to the module description.
5996 For example, here is how it could be done
5997 in the spatial-trees ASDF system definition for ASDF 2 or later:
6000 (asdf:defsystem "spatial-trees"
6006 (:file "basedefs" :depends-on ("package"))
6007 (:file "rectangles" :depends-on ("package"))))
6009 :depends-on ("base")
6013 (:file "greene-trees" :depends-on ("r-trees"))
6014 (:file "rstar-trees" :depends-on ("r-trees"))
6015 (:file "rplus-trees" :depends-on ("r-trees"))
6016 (:file "x-trees" :depends-on ("r-trees" "rstar-trees"))))
6018 :depends-on ("base")
6021 ((:static-file "spatial-tree-viz.lisp")))
6023 :depends-on ("base")
6026 ((:static-file "spatial-tree-test.lisp")))
6027 (:static-file "LICENCE")
6028 (:static-file "TODO")))
6031 All of the files in the @code{tree-impls} module are at the top level,
6032 instead of in a @file{tree-impls/} subdirectory.
6034 Note that the argument to @code{:pathname} can be either a pathname object or a string.
6035 A pathname object can be constructed with the @file{#p"foo/bar/"} syntax,
6036 but this is discouraged because the results of parsing a namestring are not portable.
6037 A pathname can only be portably constructed with such syntax as
6038 @code{#.(make-pathname :directory '(:relative "foo" "bar"))},
6039 and similarly the current directory can only be portably specified as
6040 @code{#.(make-pathname :directory '(:relative))}.
6041 However, as of ASDF 2, you can portably use a string to denote a pathname.
6042 The string will be parsed as a @code{/}-separated path from the current directory,
6043 such that the empty string @code{""} denotes the current directory, and
6044 @code{"foo/bar"} (no trailing @code{/} required in the case of modules)
6045 portably denotes the same subdirectory as above.
6046 When files are specified, the last @code{/}-separated component is interpreted
6047 either as the name component of a pathname
6048 (if the component class specifies a pathname type),
6049 or as a name component plus optional dot-separated type component
6050 (if the component class doesn't specifies a pathname type).
6052 @node How do I create a system definition where all the source files have a .cl extension?, How do I mark a source file to be loaded only and not compiled?, I want to put my module's files at the top level. How do I do this?, Issues with using and extending ASDF to define systems
6053 @subsection How do I create a system definition where all the source files have a .cl extension?
6055 Starting with ASDF 2.014.14, you may just pass
6056 the builtin class @code{cl-source-file.cl} as
6057 the @code{:default-component-class} argument to @code{defsystem}:
6060 (defsystem my-cl-system
6061 :default-component-class cl-source-file.cl
6065 Another builtin class @code{cl-source-file.lsp} is offered
6066 for files ending in @file{.lsp}.
6068 If you want to use a different extension
6069 for which ASDF doesn't provide builtin support,
6070 or want to support versions of ASDF
6071 earlier than 2.014.14 (but later than 2.000),
6072 you can define a class as follows:
6075 ;; Prologue: make sure we're using a sane package.
6076 (defpackage :my-asdf-extension
6077 (:use :asdf :common-lisp)
6078 (:export #:cl-source-file.lis))
6079 (in-package :my-asdf-extension)
6081 (defclass cl-source-file.lis (cl-source-file)
6082 ((type :initform "lis")))
6085 Then you can use it as follows:
6087 (defsystem my-cl-system
6088 :default-component-class my-asdf-extension:cl-source-file.lis
6092 Of course, if you're in the same package, e.g. in the same file,
6093 you won't need to use the package qualifier before @code{cl-source-file.lis}.
6094 Actually, if all you're doing is defining this class
6095 and using it in the same file without other fancy definitions,
6096 you might skip package complications:
6100 (defclass cl-source-file.lis (cl-source-file)
6101 ((type :initform "lis")))
6102 (defsystem my-cl-system
6103 :default-component-class cl-source-file.lis
6107 @node How do I mark a source file to be loaded only and not compiled?, How do I work with readtables?, How do I create a system definition where all the source files have a .cl extension?, Issues with using and extending ASDF to define systems
6108 @subsection How do I mark a source file to be loaded only and not compiled?
6110 There is no provision in ASDF for ensuring that
6111 some components are always loaded as source, while others are always
6113 There is @code{load-source-op} (@pxref{Predefined operations of
6114 ASDF,load-source-op}), but that is an operation to be applied to a
6115 system as a whole, not to one or another specific source files.
6116 While this idea often comes up in discussions,
6117 it doesn't play well with either the linking model of ECL
6118 or with various bundle operations.
6119 In addition, the dependency model of ASDF would have to be modified incompatibly
6120 to allow for such a trick.
6121 @c If your code doesn't compile cleanly, fix it.
6122 @c If compilation makes it slow, use @code{declaim} or @code{eval-when}
6123 @c to adjust your compiler settings,
6124 @c or eschew compilation by @code{eval}uating a quoted source form at load-time.
6126 @node How do I work with readtables?, How can I capture ASDF's output?, How do I mark a source file to be loaded only and not compiled?, Issues with using and extending ASDF to define systems
6127 @subsection How do I work with readtables?
6131 It is possible to configure the lisp syntax by modifying the currently-active readtable.
6132 However, this same readtable is shared globally by all software being compiled by ASDF,
6133 especially since @code{load} and @code{compile-file} both bind @var{*readtable*},
6134 so that its value is the same across the build at the start of every file
6135 (unless overridden by some @code{perform :around} method),
6136 even if a file locally binds it to a different readtable during the build.
6138 Therefore, the following hygiene restrictions apply. If you don't abide by these restrictions,
6139 there will be situations where your output files will be corrupted during an incremental build.
6140 We are not trying to prescribe new restrictions for the sake of good style:
6141 these restrictions have always applied implicitly, and
6142 we are simply describing what they have always been.
6145 @item It is forbidden to modifying any standard character or standard macro dispatch defined in the CLHS.
6146 @item No two dependencies may assign different meanings to the same non-standard character.
6147 @item Using any non-standard character while expecting the implementation to treat some way
6148 counts as such an assignment of meaning.
6149 @item libraries need to document these assignments of meaning to non-standard characters.
6150 @item free software libraries will register these changes on:
6151 @url{http://www.cliki.net/Macro%20Characters}
6154 If you want to use readtable modifications that cannot abide by those restrictions,
6155 you @emph{must} create a different readtable object and set @var{*readtable*}
6156 to temporarily bind it to your new readtable (which will be undone after processing the file).
6158 For that, we recommend you use system @code{named-readtables}
6159 to define or combine such readtables using @code{named-readtables:defreadtable}
6160 and use them using @code{named-readtables:in-readtable}.
6161 Equivalently, you can use system @code{cl-syntax},
6162 that itself uses @code{named-readtables},
6163 but may someday do more with, e.g. @var{*print-pprint-dispatch*}.
6165 For even more advanced syntax modification beyond what a readtable can express,
6166 you may consider either:
6168 @item a @code{perform} method that compiles a constant file that contains a single form
6169 @code{#.*code-read-with-alternate-reader*} in an environment where this special variable
6170 was bound to the code read by your alternate reader, or
6171 @item using the system @code{reader-interception}.
6174 Beware that @c unless and until the @code{syntax-control} branch is merged,
6175 it is unsafe to use ASDF from the REPL to compile or load systems
6176 while the readtable isn't the shared readtable previously used to build software.
6177 You @emph{must} manually undo any binding of @var{*readtable*} at the REPL
6178 and restore its initial value whenever you call @code{operate}
6179 (via e.g. @code{load-system}, @code{test-system} or @code{require})
6180 from a REPL that is using a different readtable.
6182 @subsubsection How should my system use a readtable exported by another system?
6184 Use from the @code{named-readtables} system the macro @code{named-readtables:in-readtable}.
6186 If the other system fails to use @code{named-readtables}, fix it and send a patch upstream.
6187 In the day and age of Quicklisp and clbuild, there is little reason
6188 to eschew using such an important library anymore.
6190 @subsubsection How should my library make a readtable available to other systems?
6192 Use from the @code{named-readtables} system the macro @code{named-readtables:defreadtable}.
6194 @node How can I capture ASDF's output?, LOAD-PATHNAME has a weird value, How do I work with readtables?, Issues with using and extending ASDF to define systems
6195 @subsection How can I capture ASDF's output?
6198 @cindex Capturing ASDF output
6199 @vindex *standard-output*
6201 Output from ASDF and ASDF extensions are sent to the CL stream
6202 @code{*standard-output*}, so rebinding that stream around calls to
6203 @code{asdf:operate} should redirect all output from ASDF operations.
6205 @node LOAD-PATHNAME has a weird value, , How can I capture ASDF's output?, Issues with using and extending ASDF to define systems
6206 @subsection *LOAD-PATHNAME* and *LOAD-TRUENAME* have weird values, help!
6207 @vindex *LOAD-PATHNAME*
6208 @vindex *LOAD-TRUENAME*
6210 Conventional Common Lisp code may use @code{*LOAD-TRUENAME*} or @code{*LOAD-PATHNAME*} to find
6211 files adjacent to source files. This will generally @emph{not} work in
6212 ASDF-loaded systems. Recall that ASDF relocates the FASL files it
6213 builds, typically to a special cache directory. Thus the value of
6214 @code{*LOAD-PATHNAME*} and @code{*LOAD-TRUENAME*} at load time, when ASDF is loading your system,
6215 will typically be a pathname in that cache directory, and useless to you
6216 for finding other system components.
6218 There are two ways to work around this problem:
6220 @findex system-relative-pathname
6222 Use the @code{system-relative-pathname} function. This can readily be
6223 used from outside the system, but it is probably not good software
6224 engineering to require a source file @emph{of} a system to know what
6225 system it is going to be part of. Contained objects should not have to
6226 know their containers.
6228 Store the pathname at compile time, so that you get the pathname of the
6229 source file, which is presumably what you want. To do this, you can
6230 capture the value of @code{(or *compile-file-pathname* *load-truename*)}
6231 (or @code{*LOAD-PATHNAME*}, if you prefer)
6232 in a macro expansion or other compile-time evaluated context.
6236 @node ASDF development FAQs, , Issues with using and extending ASDF to define systems, FAQ
6237 @section ASDF development FAQs
6240 * How do I run the tests interactively in a REPL?::
6243 @node How do I run the tests interactively in a REPL?, , ASDF development FAQs, ASDF development FAQs
6244 @subsection How do I run the tests interactively in a REPL?
6246 This not-so-frequently asked question is primarily for ASDF developers,
6247 but those who encounter an unexpected error in some test may be
6250 Here's the procedure for experimenting with tests in a REPL:
6252 ;; BEWARE! Some tests expect you to be in the .../asdf/test directory
6253 ;; If your REPL is not there yet, change your current directory:
6254 ;; under SLIME, you may: ,change-directory ~/common-lisp/asdf/test/
6255 ;; otherwise you may evaluate something like:
6256 (require "asdf") (asdf:upgrade-asdf) ;load UIOP & update asdf.lisp
6257 (uiop:chdir (asdf:system-relative-pathname :asdf "test/"))
6258 (setf *default-pathname-defaults* (uiop:getcwd))
6260 ;; Load the test script support.
6261 (load "script-support.lisp")
6263 ;; Initialize the script support for interaction.
6264 ;; This will also change your *package* to asdf-test
6265 ;; after frobbing the asdf-test package to make it usable.
6266 ;; NB: this function is also available from package cl-user,
6267 ;; and also available with the shorter name da in both packages.
6268 (asdf-test:debug-asdf)
6270 ;; Now, you may experiment with test code from a .script file.
6271 ;; See the instructions given at the end of your failing test
6272 ;; to identify which form is needed, e.g.
6273 (run-test-script "test-utilities.script")
6277 @comment FIXME: Add a FAQ about how to use a new system class...
6279 @comment node-name, next, previous, up
6280 @node Ongoing Work, Bibliography, FAQ, Top
6281 @unnumbered Ongoing Work
6282 For an active list of things to be done,
6283 see the @file{TODO} file in the source repository.
6285 Also, bugs are currently tracked on launchpad:
6286 @url{https://launchpad.net/asdf}.
6288 @node Bibliography, Concept Index, Ongoing Work, Top
6289 @unnumbered Bibliography
6292 @item Francois-Rene Rideau:
6293 ``ASDF 3, or Why Lisp is Now an Acceptable Scripting Language'', 2014.
6294 This article describes the innovations in ASDF 3 and 3.1,
6295 as well as historical information on previous versions.
6296 @url{https://github.com/fare/asdf3-2013}
6297 @item Alastair Bridgewater:
6298 ``Quick-build'' (private communication), 2012.
6299 @code{quick-build} is a simple and robust one file, one package build system,
6300 similar to @code{faslpath}, in 182 lines of code
6301 (117 of which are not blank, not comments, not docstrings).
6302 Unhappily, it remains unpublished and its IP status is unclear as of April 2014.
6303 @code{asdf/package-system} is mostly compatible with it,
6304 modulo a different setup for toplevel hierarchies.
6306 ``Quicklisp'', 2011.
6307 The Quicklisp blog and Xach's livejournal contain information on Quicklisp.
6308 @url{http://blog.quicklisp.org/}
6309 @url{http://xach.livejournal.com/}
6310 @item Francois-Rene Rideau and Robert Goldman:
6311 ``Evolving ASDF: More Cooperation, Less Coordination'', 2010.
6312 This article describes the main issues solved by ASDF 2,
6313 and exposes its design principles.
6314 @url{https://common-lisp.net/project/asdf/doc/ilc2010draft.pdf}
6315 @url{https://gitlab.common-lisp.org/asdf/ilc2010}
6316 @item Francois-Rene Rideau and Spencer Brody:
6317 ``XCVB: an eXtensible Component Verifier and Builder for Common Lisp'', 2009.
6318 This article describes XCVB, a proposed competitor for ASDF;
6319 many of its ideas have been incorporated into ASDF 2 and 3,
6320 though many other ideas still haven't.
6321 @url{https://common-lisp.net/project/xcvb/}
6322 @item Peter von Etter:
6324 @code{faslpath} is similar to the latter @code{quick-build}
6325 and our yet latter @code{asdf/package-system} extension,
6326 except that it uses dot @code{.} rather than slash @code{/} as a separator.
6327 @url{https://code.google.com/p/faslpath/}
6328 @item Drew McDermott:
6329 ``A Framework for Maintaining the Coherence of a Running Lisp,''
6330 International Lisp Conference, 2005, available in pre-print form at
6331 @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf}
6332 @item Dan Barlow: ``ASDF Manual'', 2004.
6333 Older versions of this document from the days of ASDF 1;
6334 they include ideas laid down by Dan Barlow,
6335 and comparisons with older defsystems (@code{mk-defsystem})
6336 and defsystem (@code{defsystem-4}, kmp's Memo 801).
6337 @item Marco Antoniotti and Peter Van Eynde:
6338 ``@code{DEFSYSTEM}: A @code{make} for Common Lisp, A Thoughtful Re-Implementation of an Old Idea'', 2002.
6339 The @file{defsystem-4} proposal available in the CLOCC repository.
6340 @item Mark Kantrovitz: ``Defsystem: A Portable Make Facility for Common Lisp'', 1990.
6341 The classic @file{mk-defsystem}, later variants of which
6342 are available in the CLOCC repository as @code{defsystem-3.x}.
6343 @item Richard Elliot Robbins:
6344 ``BUILD: A Tool for Maintaining Consistency in Modular Systems'', MIT AI TR 874, 1985.
6345 @url{ftp://publications.ai.mit.edu/ai-publications/pdf/AITR-874.pdf}
6346 @item Kent M. Pitman (kmp): ``The Description of Large Systems'', MIT AI Memo 801, 1984.
6347 Available in updated-for-CL form on the web at
6348 @url{http://nhplace.com/kent/Papers/Large-Systems.html}
6349 @item Dan Weinreb and David Moon:
6350 ``Lisp Machine Manual'', MIT, 1981.
6351 The famous CHINE NUAL describes one of the earliest variants of DEFSYSTEM.
6352 @url{https://bitsavers.trailing-edge.com/pdf/mit/cadr/chinual_4thEd_Jul81.pdf}
6356 @node Concept Index, Function and Class Index, Bibliography, Top
6357 @unnumbered Concept Index
6361 @node Function and Class Index, Variable Index, Concept Index, Top
6362 @unnumbered Function and Class Index
6366 @node Variable Index, , Function and Class Index, Top
6367 @unnumbered Variable Index
6373 @c LocalWords: clbuild tarballs defsystem Quicklisp initarg uiop fasl
6374 @c LocalWords: namestring initargs fasls