1 \input texinfo @c -*- texinfo -*-
7 @c We use @&key, etc to escape & from TeX in lambda lists --
8 @c so we need to define them for info as well.
9 @macro &allow-other-keys
32 @dircategory Software development
34 * asdf: (asdf). Another System Definition Facility (for Common Lisp)
38 This manual describes ASDF, a system definition facility
39 for Common Lisp programs and libraries.
41 You can find the latest version of this manual at
42 @url{http://common-lisp.net/project/asdf/asdf.html}.
44 ASDF Copyright @copyright{} 2001-2013 Daniel Barlow and contributors.
46 This manual Copyright @copyright{} 2001-2013 Daniel Barlow and contributors.
48 This manual revised @copyright{} 2009-2013 Robert P. Goldman and Francois-Rene Rideau.
50 Permission is hereby granted, free of charge, to any person obtaining
51 a copy of this software and associated documentation files (the
52 ``Software''), to deal in the Software without restriction, including
53 without limitation the rights to use, copy, modify, merge, publish,
54 distribute, sublicense, and/or sell copies of the Software, and to
55 permit persons to whom the Software is furnished to do so, subject to
56 the following conditions:
58 The above copyright notice and this permission notice shall be
59 included in all copies or substantial portions of the Software.
61 THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
62 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
63 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
64 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
65 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
66 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
67 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
74 @title ASDF: Another System Definition Facility
76 @c The following two commands start the copyright page.
78 @vskip 0pt plus 1filll
82 @c Output the table of contents at the beginning.
85 @c -------------------
89 @node Top, Introduction, (dir), (dir)
90 @top asdf: another system definition facility
99 * Defining systems with defsystem::
100 * The object model of ASDF::
101 * Controlling where ASDF searches for systems::
102 * Controlling where ASDF saves compiled files::
104 * Miscellaneous additional functionality::
105 * Getting the latest version::
110 * Function and Class Index::
114 @c --- The Detailed Node Listing ---
116 @c Defining systems with defsystem
118 @c * The defsystem form::
119 @c * A more involved example::
120 @c * The defsystem grammar::
121 @c * Other code in .asd files::
123 @c The object model of ASDF
131 @c * Predefined operations of ASDF::
132 @c * Creating new operations::
136 @c * Common attributes of components::
137 @c * Pre-defined subclasses of component::
138 @c * Creating new component types::
142 @c * Pre-defined subclasses of component::
143 @c * Creating new component types::
150 @c -------------------
152 @node Introduction, Loading ASDF, Top, Top
153 @comment node-name, next, previous, up
154 @chapter Introduction
155 @cindex ASDF-related features
157 @cindex Testing for ASDF
158 @cindex ASDF versions
163 ASDF is Another System Definition Facility:
164 a tool for specifying how systems of Common Lisp software
165 are comprised of components (sub-systems and files),
166 and how to operate on these components in the right order
167 so that they can be compiled, loaded, tested, etc.
169 ASDF presents three faces:
170 one for users of Common Lisp software who want to reuse other people's code,
171 one for writers of Common Lisp software who want to specify how to build their systems,
172 one for implementers of Common Lisp extensions who want to extend the build system.
173 @xref{Using ASDF,,Loading a system},
174 to learn how to use ASDF to load a system.
175 @xref{Defining systems with defsystem},
176 to learn how to define a system of your own.
177 @xref{The object model of ASDF}, for a description of
178 the ASDF internals and how to extend ASDF.
181 We have released ASDF 2.000 on May 31st 2010,
182 and ASDF 3.0 on January 31st 2013.
183 Releases of ASDF 2 and later have since then been included
184 in all actively maintained CL implementations that used to bundle ASDF 1,
185 plus some implementations that didn't use to,
186 and has been made to work with all actively used CL implementations and a few more.
187 @xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
188 Furthermore, it is possible to upgrade from ASDF 1 to ASDF 2 or ASDF 3 on the fly.
189 For this reason, we have stopped supporting ASDF 1 and ASDF 2.
190 If you are using ASDF 1 or ASDF 2 and are experiencing any kind of issues or limitations,
191 we recommend you upgrade to ASDF 3
192 --- and we explain how to do that. @xref{Loading ASDF}.
194 Also note that ASDF is not to be confused with ASDF-Install.
195 ASDF-Install is not part of ASDF, but a separate piece of software.
196 ASDF-Install is also unmaintained and obsolete.
197 We recommend you use Quicklisp instead,
198 which works great and is being actively maintained.
199 If you want to download software from version control instead of tarballs,
200 so you may more easily modify it, we recommend clbuild.
203 @node Loading ASDF, Configuring ASDF, Introduction, Top
204 @comment node-name, next, previous, up
205 @chapter Loading ASDF
206 @vindex *central-registry*
209 @findex require-system
210 @findex compile-system
212 @cindex system directory designator
217 @c * Installing ASDF::
221 @section Loading a pre-installed ASDF
223 Most recent Lisp implementations include a copy of ASDF 2, and soon ASDF 3.
224 You can usually load this copy using Common Lisp's @code{require} function:
230 As of the writing of this manual,
231 the following implementations provide ASDF 2 this way:
232 abcl allegro ccl clisp cmucl ecl lispworks mkcl sbcl xcl.
233 The following implementation doesn't provide it yet but will in an upcoming release:
235 The following implementations are obsolete, not actively maintained,
236 and most probably will never bundle it:
237 cormanlisp gcl genera mcl.
239 If the implementation you are using doesn't provide ASDF 2 or ASDF 3,
240 see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
241 If that implementation is still actively maintained,
242 you may also send a bug report to your Lisp vendor and complain
243 about their failing to provide ASDF.
245 NB: all implementations except clisp also accept
246 @code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}.
247 For portability's sake, you probably want to use @code{(require "asdf")}.
250 @section Checking whether ASDF is loaded
252 To check whether ASDF is properly loaded in your current Lisp image,
253 you can run this form:
259 If it returns a string,
260 that is the version of ASDF that is currently installed.
262 If it raises an error,
263 then either ASDF is not loaded, or
264 you are using an old version of ASDF.
266 You can check whether an old version is loaded
267 by checking if the ASDF package is present.
268 The form below will allow you to programmatically determine
269 whether a recent version is loaded, an old version is loaded,
273 (when (find-package :asdf)
274 (let ((ver (symbol-value (or (find-symbol (string :*asdf-version*) :asdf)
275 (find-symbol (string :*asdf-revision*) :asdf)))))
278 (cons (with-output-to-string (s)
279 (loop for (n . m) on ver do (princ n s) (when m (princ "." s)))))
283 If it returns @code{NIL} then ASDF is not installed.
284 Otherwise it should return a string.
285 If it returns @code{"1.0"}, then it can actually be
286 any version before 1.77 or so, or some buggy variant of 1.x.
288 If you are experiencing problems with ASDF,
289 please try upgrading to the latest released version,
290 using the method below,
291 before you contact us and raise an issue.
294 @section Upgrading ASDF
296 If your implementation provides ASDF 3 or later,
297 you only need to @code{(require "asdf")}:
298 ASDF will automatically look whether an updated version of itself is available
299 amongst the regularly configured systems, before it compiles anything else.
300 See @pxref{Configuring ASDF} below.
302 If your implementation does provide ASDF 2 or later,
303 but not ASDF 3 or later,
304 and you want to upgrade to a more recent version,
305 you need to install and configure your ASDF as above,
306 and additionally, you need to explicitly tell ASDF to load itself,
307 right after you require your implementation's old ASDF 2:
311 (asdf:load-system :asdf)
314 If on the other hand, your implementation only provides an old ASDF,
315 you will require a special configuration step and an old-style loading.
316 Take special attention to not omit the trailing directory separator
317 @code{/} at the end of your pathname:
321 (push #p"@var{/path/to/new/asdf/}" asdf:*central-registry*)
322 (asdf:oos 'asdf:load-op :asdf)
325 Note that ASDF 1 won't redirect its output files,
326 or at least won't do it according to your usual ASDF 2 configuration.
327 You therefore need write access on the directory
328 where you install the new ASDF,
329 and make sure you're not using it
330 for multiple mutually incompatible implementations.
331 At worst, you may have to have multiple copies of the new ASDF,
332 e.g. one per implementation installation, to avoid clashes.
333 Note that to our knowledge all implementations that provide ASDF
334 provide ASDF 2 in their latest release, so
335 you may want to upgrade your implementation rather than go through that hoop.
337 Finally, if you are using an unmaintained implementation
338 that does not provide ASDF at all,
339 see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
341 Note that there are some limitations to upgrading ASDF:
344 Previously loaded ASDF extension becomes invalid, and will need to be reloaded.
345 This applies to e.g. CFFI-Grovel, or to hacks used by ironclad, etc.
346 Since it isn't possible to automatically detect what extensions are present
347 that need to be invalidated,
348 ASDF will actually invalidate all previously loaded systems
349 when it is loaded on top of a different ASDF version,
350 starting with ASDF 2.014.8 (as far as releases go, 2.015);
351 and it will automatically attempt this self-upgrade as its very first step
352 starting with ASDF 3.
355 For this an many other reasons,
356 it important reason to load, configure and upgrade ASDF (if needed)
357 as one of the very first things done by your build and startup scripts.
358 Until all implementations provide ASDF 3 or later,
359 it is safer if you upgrade ASDF and its extensions as a special step
360 at the very beginning of whatever script you are running,
361 before you start using ASDF to load anything else;
362 even afterwards, it is still a good idea, to avoid having to
363 load and reload code twice as it gets invalidated.
366 Until all implementations provide ASDF 3 or later,
367 it is unsafe to upgrade ASDF as part of loading a system
368 that depends on a more recent version of ASDF,
369 since the new one might shadow the old one while the old one is running,
370 and the running old one will be confused
371 when extensions are loaded into the new one.
372 In the meantime, we recommend that your systems should @emph{not} specify
373 @code{:depends-on (:asdf)}, or @code{:depends-on ((:version :asdf "2.010"))},
374 but instead that they check that a recent enough ASDF is installed,
377 (unless (or #+asdf2 (asdf:version-satisfies
378 (asdf:asdf-version) *required-asdf-version*))
379 (error "FOO requires ASDF ~A or later." *required-asdf-version*))
382 Until all implementations provide ASDF 3 or later,
383 it is unsafe for a system to transitively depend on ASDF
384 and not directly depend on ASDF;
385 if any of the system you use either depends-on asdf,
386 system-depends-on asdf, or transitively does,
387 you should also do as well.
391 @section Loading an otherwise installed ASDF
393 If your implementation doesn't include ASDF,
394 if for some reason the upgrade somehow fails,
395 does not or cannot apply to your case,
396 you will have to install the file @file{asdf.lisp}
397 somewhere and load it with:
400 (load "/path/to/your/installed/asdf.lisp")
403 The single file @file{asdf.lisp} is all you normally need to use ASDF.
405 You can extract this file from latest release tarball on the
406 @url{http://common-lisp.net/project/asdf/,ASDF website}.
407 If you are daring and willing to report bugs, you can get
408 the latest and greatest version of ASDF from its git repository.
409 @xref{Getting the latest version}.
411 For maximum convenience you might want to have ASDF loaded
412 whenever you start your Lisp implementation,
413 for example by loading it from the startup script or dumping a custom core
414 --- check your Lisp implementation's manual for details.
417 @node Configuring ASDF, Using ASDF, Loading ASDF, Top
418 @comment node-name, next, previous, up
420 @chapter Configuring ASDF
422 @section Configuring ASDF to find your systems
424 So it may compile and load your systems, ASDF must be configured to find
425 the @file{.asd} files that contain system definitions.
427 Since ASDF 2, the preferred way to configure where ASDF finds your systems is
428 the @code{source-registry} facility,
429 fully described in its own chapter of this manual.
430 @xref{Controlling where ASDF searches for systems}.
432 The default location for a user to install Common Lisp software is under
433 @file{~/.local/share/common-lisp/source/}.
434 If you install software there (it can be a symlink),
435 you don't need further configuration.
436 If you're installing software yourself at a location that isn't standard,
437 you have to tell ASDF where you installed it. See below.
438 If you're using some tool to install software (e.g. Quicklisp),
439 the authors of that tool should already have configured ASDF.
441 The simplest way to add a path to your search path,
442 say @file{/home/luser/.asd-link-farm/}
443 is to create the directory
444 @file{~/.config/common-lisp/source-registry.conf.d/}
445 and there create a file with any name of your choice,
446 and with the type @file{conf},
447 for instance @file{42-asd-link-farm.conf}
450 @kbd{(:directory "/home/luser/.asd-link-farm/")}
452 If you want all the subdirectories under @file{/home/luser/lisp/}
453 to be recursively scanned for @file{.asd} files, instead use:
455 @kbd{(:tree "/home/luser/lisp/")}
457 Note that your Operating System distribution or your system administrator
458 may already have configured system-managed libraries for you.
460 The required @file{.conf} extension allows you to have disabled files
461 or editor backups (ending in @file{~}), and works portably
462 (for instance, it is a pain to allow both empty and non-empty extension on CLISP).
463 Excluded are files the name of which start with a @file{.} character.
464 It is customary to start the filename with two digits
465 that specify the order in which the directories will be scanned.
467 ASDF will automatically read your configuration
468 the first time you try to find a system.
469 You can reset the source-registry configuration with:
472 (asdf:clear-source-registry)
475 And you probably should do so before you dump your Lisp image,
476 if the configuration may change
477 between the machine where you save it at the time you save it
478 and the machine you resume it at the time you resume it.
479 Actually, you should use @code{(asdf:clear-configuration)}
480 before you dump your Lisp image, which includes the above.
483 @section Configuring ASDF to find your systems --- old style
485 The old way to configure ASDF to find your systems is by
486 @code{push}ing directory pathnames onto the variable
487 @code{asdf:*central-registry*}.
489 You must configure this variable between the time you load ASDF
490 and the time you first try to use it.
491 Loading and configuring ASDF presumably happen
492 as part of some initialization script that builds or starts
493 your Common Lisp software system.
494 (For instance, some SBCL users used to put it in their @file{~/.sbclrc}.)
496 The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
497 but is still supported for compatibility with ASDF 1.
498 When used, it takes precedence over the above source-registry@footnote{
499 It is possible to further customize
500 the system definition file search.
501 That's considered advanced use, and covered later:
503 @code{*system-definition-search-functions*}.
504 @xref{Defining systems with defsystem}.}.
506 For instance, if you wanted ASDF to find the @file{.asd} file
507 @file{/home/me/src/foo/foo.asd} your initialization script
508 could after it loads ASDF with @code{(require "asdf")}
512 (push "/home/me/src/foo/" asdf:*central-registry*)
515 Note the trailing slash: when searching for a system,
516 ASDF will evaluate each entry of the central registry
517 and coerce the result to a pathname@footnote{
518 ASDF will indeed call @code{EVAL} on each entry.
519 It will also skip entries that evaluate to @code{NIL}.
521 Strings and pathname objects are self-evaluating,
522 in which case the @code{EVAL} step does nothing;
523 but you may push arbitrary SEXP onto the central registry,
524 that will be evaluated to compute e.g. things that depend
525 on the value of shell variables or the identity of the user.
527 The variable @code{asdf:*central-registry*} is thus a list of
528 ``system directory designators''.
529 A @dfn{system directory designator} is a form
530 which will be evaluated whenever a system is to be found,
531 and must evaluate to a directory to look in.
532 By ``directory'' here, we mean
533 ``designator for a pathname with a supplied DIRECTORY component''.
535 at which point the presence of the trailing directory name separator
536 is necessary to tell Lisp that you're discussing a directory
539 Typically, however, there are a lot of @file{.asd} files, and
540 a common idiom was to have to put
541 a bunch of @emph{symbolic links} to @file{.asd} files
542 in a common directory
543 and push @emph{that} directory (the ``link farm'')
545 @code{asdf:*central-registry*}
546 instead of pushing each of the many involved directories
547 to the @code{asdf:*central-registry*}.
548 ASDF knows how to follow such @emph{symlinks}
549 to the actual file location when resolving the paths of system components
550 (on Windows, you can use Windows shortcuts instead of POSIX symlinks;
551 if you try aliases under MacOS, we are curious to hear about your experience).
553 For example, if @code{#p"/home/me/cl/systems/"} (note the trailing slash)
554 is a member of @code{*central-registry*}, you could set up the
555 system @var{foo} for loading with asdf with the following
556 commands at the shell:
559 $ cd /home/me/cl/systems/
560 $ ln -s ~/src/foo/foo.asd .
563 This old style for configuring ASDF is not recommended for new users,
564 but it is supported for old users, and for users who want to programmatically
565 control what directories are added to the ASDF search path.
568 @section Configuring where ASDF stores object files
569 @findex clear-output-translations
571 ASDF lets you configure where object files will be stored.
572 Sensible defaults are provided and
573 you shouldn't normally have to worry about it.
575 This allows the same source code repository may be shared
576 between several versions of several Common Lisp implementations,
577 between several users using different compilation options
578 and without write privileges on shared source directories, etc.
579 This also allows to keep source directories uncluttered
580 by plenty of object files.
582 Starting with ASDF 2, the @code{asdf-output-translations} facility
583 was added to ASDF itself, that controls where object files will be stored.
584 This facility is fully described in a chapter of this manual,
585 @ref{Controlling where ASDF saves compiled files}.
587 The simplest way to add a translation to your search path,
588 say from @file{/foo/bar/baz/quux/}
589 to @file{/where/i/want/my/fasls/}
590 is to create the directory
591 @file{~/.config/common-lisp/asdf-output-translations.conf.d/}
592 and there create a file with any name of your choice and the type @file{conf},
593 for instance @file{42-bazquux.conf}
596 @kbd{("/foo/bar/baz/quux/" "/where/i/want/my/fasls/")}
598 To disable output translations for source under a given directory,
599 say @file{/toto/tata/}
600 you can create a file @file{40-disable-toto.conf}
603 @kbd{("/toto/tata/")}
605 To wholly disable output translations for all directories,
606 you can create a file @file{00-disable.conf}
611 Note that your Operating System distribution or your system administrator
612 may already have configured translations for you.
613 In absence of any configuration, the default is to redirect everything
614 under an implementation-dependent subdirectory of @file{~/.cache/common-lisp/}.
615 @xref{Controlling where ASDF searches for systems}, for full details.
617 The required @file{.conf} extension allows you to have disabled files
618 or editor backups (ending in @file{~}), and works portably
619 (for instance, it is a pain to allow both empty and non-empty extension on CLISP).
620 Excluded are files the name of which start with a @file{.} character.
621 It is customary to start the filename with two digits
622 that specify the order in which the directories will be scanned.
624 ASDF will automatically read your configuration
625 the first time you try to find a system.
626 You can reset the source-registry configuration with:
629 (asdf:clear-output-translations)
632 And you probably should do so before you dump your Lisp image,
633 if the configuration may change
634 between the machine where you save it at the time you save it
635 and the machine you resume it at the time you resume it.
636 (Once again, you should use @code{(asdf:clear-configuration)}
637 before you dump your Lisp image, which includes the above.)
639 Finally note that before ASDF 2,
640 other ASDF add-ons offered the same functionality,
641 each in subtly different and incompatible ways:
642 ASDF-Binary-Locations, cl-launch, common-lisp-controller.
643 ASDF-Binary-Locations is now not needed anymore and should not be used.
644 cl-launch 3.000 and common-lisp-controller 7.2 have been updated
645 to just delegate this functionality to ASDF.
647 @node Using ASDF, Defining systems with defsystem, Configuring ASDF, Top
648 @comment node-name, next, previous, up
651 @section Resetting Configuration
653 When you dump and restore an image, or when you tweak your configuration,
654 you may want to reset the ASDF configuration.
655 For that you may use the following function:
657 @defun clear-configuration
658 undoes any ASDF configuration,
659 regarding source-registry or output-translations.
662 If you use SBCL, CMUCL or SCL, you may use this snippet
663 so that the ASDF configuration be cleared automatically as you dump an image:
667 (pushnew 'clear-configuration
668 #+(or cmu scl) ext:*before-save-initializations*
669 #+sbcl sb-ext:*save-hooks*)
672 For compatibility with all Lisp implementations, however,
673 you might want instead your build script to explicitly call
674 @code{(asdf:clear-configuration)} at an appropriate moment before dumping.
679 @section Loading a system
681 The system @var{foo} is loaded (and compiled, if necessary)
682 by evaluating the following Lisp form:
685 (asdf:load-system :@var{foo})
688 On some implementations (namely recent versions of
689 ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP,
690 LispWorks, MKCL, SBCL and XCL),
691 ASDF hooks into the @code{CL:REQUIRE} facility
692 and you can just use:
698 In older versions of ASDF, you needed to use
699 @code{(asdf:oos 'asdf:load-op :@var{foo})}.
700 If your ASDF is too old to provide @code{asdf:load-system} though
701 we recommend that you upgrade to ASDF 3.
702 @xref{Loading ASDF,,Loading an otherwise installed ASDF}.
704 Note the name of a system is specified as a string or a symbol,
706 If a symbol (including a keyword), its name is taken and lowercased.
707 The name must be a suitable value for the @code{:name} initarg
708 to @code{make-pathname} in whatever filesystem the system is to be found.
709 The lower-casing-symbols behaviour is unconventional,
710 but was selected after some consideration.
711 Observations suggest that the type of systems we want to support
712 either have lowercase as customary case (unix, mac, windows)
713 or silently convert lowercase to uppercase (lpns),
714 so this makes more sense than attempting to use @code{:case :common},
715 which is reported not to work on some implementations
718 @section Other Operations
720 ASDF provides three commands for the most common system operations:
721 @code{load-system}, @code{compile-system} or @code{test-system}.
722 It also provides @code{require-system}, a version of @code{load-system}
723 that skips trying to update systems that are already loaded.
725 Because ASDF is an extensible system
726 for defining @emph{operations} on @emph{components},
727 it also provides a generic function @code{operate}
728 (which is usually abbreviated by @code{oos}).
729 You'll use @code{oos} whenever you want to do something beyond
730 compiling, loading and testing.
732 Output from ASDF and ASDF extensions are supposed to be sent
733 to the CL stream @code{*standard-output*},
734 and so rebinding that stream around calls to @code{asdf:operate}
735 should redirect all output from ASDF operations.
737 Reminder: before ASDF can operate on a system, however,
738 it must be able to find and load that system's definition.
739 @xref{Configuring ASDF,,Configuring ASDF to find your systems}.
741 For the advanced users, note that
742 @code{require-system} calls @code{load-system}
743 with keyword arguments @code{:force-not (loaded-systems)}.
744 @code{loaded-systems} returns a list of the names of loaded systems.
745 @code{load-system} applies @code{operate} with the operation from
746 @code{*load-system-operation*}, which by default is @code{load-op},
747 the system, and any provided keyword arguments.
755 Load ASDF itself into your Lisp image, either through
756 @code{(require "asdf")} or else through
757 @code{(load "/path/to/asdf.lisp")}.
760 Make sure ASDF can find system definitions
761 thanks to proper source-registry configuration.
764 Load a system with @code{(asdf:load-system :my-system)}
765 or use some other operation on some system of your choice.
771 That's all you need to know to use ASDF to load systems written by others.
772 The rest of this manual deals with writing system definitions
773 for Common Lisp software you write yourself,
774 including how to extend ASDF to define new operation and component types.
777 @node Defining systems with defsystem, The object model of ASDF, Using ASDF, Top
778 @comment node-name, next, previous, up
779 @chapter Defining systems with defsystem
781 This chapter describes how to use asdf to define systems and develop
786 * The defsystem form::
787 * A more involved example::
788 * The defsystem grammar::
789 * Other code in .asd files::
792 @node The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
793 @comment node-name, next, previous, up
794 @section The defsystem form
796 Systems can be constructed programmatically
797 by instantiating components using @code{make-instance}.
798 Most of the time, however, it is much more practical to use
799 a static @code{defsystem} form.
800 This section begins with an example of a system definition,
801 then gives the full grammar of @code{defsystem}.
803 Let's look at a simple system.
804 This is a complete file that would
805 usually be saved as @file{hello-lisp.asd}:
810 (defsystem "hello-lisp"
811 :description "hello-lisp: a sample Lisp system."
813 :author "Joe User <joe@@example.com>"
814 :licence "Public Domain"
815 :components ((:file "packages")
816 (:file "macros" :depends-on ("packages"))
817 (:file "hello" :depends-on ("macros"))))
820 Some notes about this example:
825 The file starts with an @code{in-package} form
826 to use package @code{asdf}.
827 You could instead start your definition by using
828 a qualified name @code{asdf:defsystem}.
831 If in addition to simply using @code{defsystem},
832 you are going to define functions,
833 create ASDF extension, globally bind symbols, etc.,
834 it is recommended that to avoid namespace pollution between systems,
835 you should create your own package for that purpose,
836 for instance replacing the above @code{(in-package :asdf)} with:
839 (defpackage :foo-system
842 (in-package :foo-system)
846 The @code{defsystem} form defines a system named @code{hello-lisp}
847 that contains three source files:
848 @file{packages}, @file{macros} and @file{hello}.
851 The file @file{macros} depends on @file{packages}
852 (presumably because the package it's in is defined in @file{packages}),
853 and the file @file{hello} depends on @file{macros}
854 (and hence, transitively on @file{packages}).
855 This means that ASDF will compile and load @file{packages} and @file{macros}
856 before starting the compilation of file @file{hello}.
859 The files are located in the same directory
860 as the file with the system definition.
861 ASDF resolves symbolic links (or Windows shortcuts)
862 before loading the system definition file and
863 stores its location in the resulting system@footnote{
864 It is possible, though almost never necessary, to override this behaviour.}.
865 This is a good thing because the user can move the system sources
866 without having to edit the system definition.
868 @c FIXME: Should have cross-reference to "Version specifiers" in the
869 @c defsystem grammar, but the cross-referencing is so broken by
870 @c insufficient node breakdown that I have not put one in.
872 Make sure you know how the @code{:version} numbers will be parsed! They
873 are parsed as period-separated lists of integers. I.e., in the example,
874 @code{0.2.1} is to be interpreted, roughly speaking, as @code{(0 2 1)}.
875 In particular, version @code{0.2.1} is interpreted the same as
876 @code{0.0002.1} and is strictly version-less-than version @code{0.20.1},
877 even though the two are the same when interpreted as decimal fractions.
878 Instead of a string representing the version,
879 the @code{:version} argument can be an expression that is resolved to
880 such a string using the following trivial domain-specific language:
881 in addition to being a literal string, it can be an expression of the form
882 @code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)},
883 which will be resolved by reading a form
884 in the specified pathname
885 (read as a subpathname of the current system if relative or a unix-namestring).
886 You may use an access-at specifier with the (optional) :at keyword,
887 by default the specifier is 0, meaning the first form is returned.
893 @node A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
894 @comment node-name, next, previous, up
895 @section A more involved example
897 Let's illustrate some more involved uses of @code{defsystem} via a
898 slightly convoluted example:
903 :components ((:module "mod"
904 :components ((:file "bar")
907 :perform (compile-op :after (op c)
909 :explain (compile-op :after (op c)
910 (explain-something c)))
914 The @code{:module} component named @code{"mod"} is a collection of three files,
915 which will be located in a subdirectory of the main code directory named
916 @file{mod} (this location can be overridden; see the discussion of the
917 @code{:pathname} option in @ref{The defsystem grammar}).
919 The method-form tokens provide a shorthand for defining methods on
920 particular components. This part
923 :perform (compile-op :after (op c)
925 :explain (compile-op :after (op c)
926 (explain-something c))
932 (defmethod perform :after ((op compile-op) (c (eql ...)))
934 (defmethod explain :after ((op compile-op) (c (eql ...)))
935 (explain-something c))
938 where @code{...} is the component in question.
939 In this case @code{...} would expand to something like
942 (find-component (find-system "foo") "mod")
945 For more details on the syntax of such forms, see @ref{The defsystem
947 For more details on what these methods do, @pxref{Operations} in
948 @ref{The object model of ASDF}.
950 @c The following plunge into the weeds is not appropriate in this
951 @c location. [2010/10/03:rpg]
952 @c note that although this also supports @code{:before} methods,
953 @c they may not do what you want them to ---
954 @c a @code{:before} method on perform @code{((op compile-op) (c (eql ...)))}
955 @c will run after all the dependencies and sub-components have been processed,
956 @c but before the component in question has been compiled.
958 @node The defsystem grammar, Other code in .asd files, A more involved example, Defining systems with defsystem
959 @comment node-name, next, previous, up
960 @section The defsystem grammar
962 @c FIXME: @var typesetting not consistently used here. We should either expand
963 @c its use to everywhere, or we should kill it everywhere.
967 system-definition := ( defsystem system-designator @var{system-option}* )
969 system-option := :defsystem-depends-on system-list
970 | :weakly-depends-on @var{system-list}
971 | :class class-name (see discussion below)
975 module-option := :components component-list
976 | :serial [ t | nil ]
979 | :pathname pathname-specifier
980 | :default-component-class class-name
981 | :perform method-form
982 | :explain method-form
983 | :output-files method-form
984 | :operation-done-p method-form
985 | :if-feature feature-expression
986 | :depends-on ( @var{dependency-def}* )
987 | :in-order-to ( @var{dependency}+ )
990 system-list := ( @var{simple-component-name}* )
992 component-list := ( @var{component-def}* )
994 component-def := ( component-type simple-component-name @var{option}* )
996 component-type := :system | :module | :file | :static-file | other-component-type
998 other-component-type := symbol-by-name (@pxref{The defsystem grammar,,Component types})
1000 dependency-def := simple-component-name
1002 | ( :version simple-component-name version-specifier)
1004 dependency := (dependent-op @var{requirement}+)
1005 requirement := (required-op @var{required-component}+)
1006 | (feature feature-name)
1007 dependent-op := operation-name
1008 required-op := operation-name | feature
1010 simple-component-name := string
1013 pathname-specifier := pathname | string | symbol
1015 method-form := (operation-name qual lambda-list @&rest body)
1016 qual := method qualifier
1018 component-dep-fail-option := :fail | :try-next | :ignore
1020 feature-expression := keyword | (:and @var{feature-expression}*)
1021 | (:or @var{feature-expression}*) | (:not @var{feature-expression})
1025 @subsection Component names
1027 Component names (@code{simple-component-name})
1028 may be either strings or symbols.
1030 @subsection Component types
1032 Component type names, even if expressed as keywords, will be looked up
1033 by name in the current package and in the asdf package, if not found in
1034 the current package. So a component type @code{my-component-type}, in
1035 the current package @code{my-system-asd} can be specified as
1036 @code{:my-component-type}, or @code{my-component-type}.
1038 @subsection System class names
1040 A system class name will be looked up in the same way as a Component
1041 type (see above). Typically, one will not need to specify a system
1042 class name, unless using a non-standard system class defined in some
1043 ASDF extension, typically loaded through @code{DEFSYSTEM-DEPENDS-ON},
1044 see below. For such class names in the ASDF package, we recommend that
1045 the @code{:class} option be specified using a keyword symbol, such as
1048 :class :MY-NEW-SYSTEM-SUBCLASS
1051 This practice will ensure that package name conflicts are avoided.
1052 Otherwise, the symbol @code{MY-NEW-SYSTEM-SUBCLASS} will be read into
1053 the current package @emph{before} it has been exported from the ASDF
1054 extension loaded by @code{:defsystem-depends-on}, causing a name
1055 conflict in the current package.
1057 @subsection Defsystem depends on
1058 @cindex :defsystem-depends-on
1060 The @code{:defsystem-depends-on} option to @code{defsystem} allows the
1061 programmer to specify another ASDF-defined system or set of systems that
1062 must be loaded @emph{before} the system definition is processed.
1063 Typically this is used to load an ASDF extension that is used in the
1066 @subsection Weakly depends on
1067 @cindex :weakly-depends-on
1069 We do @emph{NOT} recommend you use this feature.
1070 If you are tempted to write a system @var{foo}
1071 that weakly-depends-on a system @var{bar},
1072 we recommend that you should instead
1073 write system @var{foo} in a parametric way,
1074 and offer some special variable and/or some hook to specialize its behavior;
1075 then you should write a system @var{foo+bar}
1076 that does the hooking of things together.
1078 The (deprecated) @code{:weakly-depends-on} option to @code{defsystem}
1079 allows the programmer to specify another ASDF-defined system or set of systems
1080 that ASDF should @emph{try} to load,
1081 but need not load in order to be successful.
1082 Typically this is used if there are a number of systems
1083 that, if present, could provide additional functionality,
1084 but which are not necessary for basic function.
1086 Currently, although it is specified to be an option only to @code{defsystem},
1087 this option is accepted at any component, but it probably
1088 only makes sense at the @code{defsystem} level.
1089 Programmers are cautioned not
1090 to use this component option except at the @code{defsystem} level, as
1091 this anomalous behavior may be removed without warning.
1093 @subsection Pathname specifiers
1094 @cindex pathname specifiers
1096 A pathname specifier (@code{pathname-specifier})
1097 may be a pathname, a string or a symbol.
1098 When no pathname specifier is given for a component,
1099 which is the usual case, the component name itself is used.
1101 If a string is given, which is the usual case,
1102 the string will be interpreted as a Unix-style pathname
1103 where @code{/} characters will be interpreted as directory separators.
1104 Usually, Unix-style relative pathnames are used
1105 (i.e. not starting with @code{/}, as opposed to absolute pathnames);
1106 they are relative to the path of the parent component.
1107 Finally, depending on the @code{component-type},
1108 the pathname may be interpreted as either a file or a directory,
1110 a file type may be added corresponding to the @code{component-type},
1111 or else it will be extracted from the string itself (if applicable).
1113 For instance, the @code{component-type} @code{:module}
1114 wants a directory pathname, and so a string @code{"foo/bar"}
1115 will be interpreted as the pathname @file{#p"foo/bar/"}.
1116 On the other hand, the @code{component-type} @code{:file}
1117 wants a file of type @code{lisp}, and so a string @code{"foo/bar"}
1118 will be interpreted as the pathname @file{#p"foo/bar.lisp"},
1119 and a string @code{"foo/bar.quux"}
1120 will be interpreted as the pathname @file{#p"foo/bar.quux.lisp"}.
1121 Finally, the @code{component-type} @code{:static-file}
1122 wants a file without specifying a type, and so a string @code{"foo/bar"}
1123 will be interpreted as the pathname @file{#p"foo/bar"},
1124 and a string @code{"foo/bar.quux"}
1125 will be interpreted as the pathname @file{#p"foo/bar.quux"}.
1127 ASDF does not interpret the string @code{".."} to designate the parent
1128 directory. This string will be passed through to the underlying
1129 operating system for interpretation. We @emph{believe} that this will
1130 work on all platforms where ASDF is deployed, but do not guarantee this
1131 behavior. A pathname object with a relative directory component of
1132 @code{:up} or @code{:back} is the only guaranteed way to specify a
1135 If a symbol is given, it will be translated into a string,
1136 and downcased in the process.
1137 The downcasing of symbols is unconventional,
1138 but was selected after some consideration.
1139 Observations suggest that the type of systems we want to support
1140 either have lowercase as customary case (Unix, Mac, windows)
1141 or silently convert lowercase to uppercase (lpns),
1142 so this makes more sense than attempting to use @code{:case :common}
1143 as argument to @code{make-pathname},
1144 which is reported not to work on some implementations.
1146 Pathname objects may be given to override the path for a component.
1147 Such objects are typically specified using reader macros such as @code{#p}
1148 or @code{#.(make-pathname ...)}.
1149 Note however, that @code{#p...} is a shorthand for @code{#.(parse-namestring ...)}
1150 and that the behavior of @code{parse-namestring} is completely non-portable,
1151 unless you are using Common Lisp @code{logical-pathname}s
1152 (@pxref{The defsystem grammar,,Using logical pathnames}, below).
1153 Pathnames made with @code{#.(make-pathname ...)}
1154 can usually be done more easily with the string syntax above.
1155 The only case that you really need a pathname object is to override
1156 the component-type default file type for a given component.
1157 Therefore, pathname objects should only rarely be used.
1158 Unhappily, ASDF 1 didn't properly support
1159 parsing component names as strings specifying paths with directories,
1160 and the cumbersome @code{#.(make-pathname ...)} syntax had to be used.
1161 An alternative to @code{#.} read-time evaluation is to use
1162 @code{(eval `(defsystem ... ,pathname ...))}.
1164 Note that when specifying pathname objects,
1165 ASDF does not do any special interpretation of the pathname
1166 influenced by the component type, unlike the procedure for
1167 pathname-specifying strings.
1168 On the one hand, you have to be careful to provide a pathname that correctly
1169 fulfills whatever constraints are required from that component type
1170 (e.g. naming a directory or a file with appropriate type);
1171 on the other hand, you can circumvent the file type that would otherwise
1172 be forced upon you if you were specifying a string.
1174 @subsection Version specifiers
1175 @cindex version specifiers
1178 Version specifiers are parsed as period-separated lists of integers. I.e., in the example,
1179 @code{0.2.1} is to be interpreted, roughly speaking, as @code{(0 2 1)}.
1180 In particular, version @code{0.2.1} is interpreted the same as
1181 @code{0.0002.1} and is strictly version-less-than version @code{0.20.1},
1182 even though the two are the same when interpreted as decimal fractions.
1184 System definers are encouraged to use version identifiers of the form
1185 @var{x}.@var{y}.@var{z} for major version, minor version (compatible
1186 API) and patch level.
1188 @xref{Common attributes of components}.
1191 @subsection Using logical pathnames
1192 @cindex logical pathnames
1194 We do not generally recommend the use of logical pathnames,
1195 especially not so to newcomers to Common Lisp.
1196 However, we do support the use of logical pathnames by old timers,
1197 when such is their preference.
1199 To use logical pathnames,
1200 you will have to provide a pathname object as a @code{:pathname} specifier
1201 to components that use it, using such syntax as
1202 @code{#p"LOGICAL-HOST:absolute;path;to;component.lisp"}.
1204 You only have to specify such logical pathname
1205 for your system or some top-level component.
1206 Sub-components' relative pathnames,
1207 specified using the string syntax for names,
1208 will be properly merged with the pathnames of their parents.
1209 The specification of a logical pathname host however is @emph{not}
1210 otherwise directly supported in the ASDF syntax
1211 for pathname specifiers as strings.
1213 The @code{asdf-output-translation} layer will
1214 avoid trying to resolve and translate logical pathnames.
1215 The advantage of this is that
1216 you can define yourself what translations you want to use
1217 with the logical pathname facility.
1218 The disadvantage is that if you do not define such translations,
1219 any system that uses logical pathnames will behave differently under
1220 asdf-output-translations than other systems you use.
1222 If you wish to use logical pathnames you will have to configure the
1223 translations yourself before they may be used.
1224 ASDF currently provides no specific support
1225 for defining logical pathname translations.
1227 Note that the reasons we do not recommend logical pathnames are that
1228 (1) there is no portable way to set up logical pathnames before they are used,
1229 (2) logical pathnames are limited to only portably use
1230 a single character case, digits and hyphens.
1231 While you can solve the first issue on your own,
1232 describing how to do it on each of fifteen implementations supported by ASDF
1233 is more than we can document.
1234 As for the second issue, mind that the limitation is notably enforced on SBCL,
1235 and that you therefore can't portably violate the limitations
1236 but must instead define some encoding of your own and add individual mappings
1237 to name physical pathnames that do not fit the restrictions.
1238 This can notably be a problem when your Lisp files are part of a larger project
1239 in which it is common to name files or directories in a way that
1240 includes the version numbers of supported protocols,
1241 or in which files are shared with software written
1242 in different programming languages where conventions include the use of
1243 underscores, dots or CamelCase in pathnames.
1246 @subsection Serial dependencies
1247 @cindex serial dependencies
1249 If the @code{:serial t} option is specified for a module,
1250 ASDF will add dependencies for each child component,
1251 on all the children textually preceding it.
1252 This is done as if by @code{:depends-on}.
1256 :components ((:file "a") (:file "b") (:file "c"))
1262 :components ((:file "a")
1263 (:file "b" :depends-on ("a"))
1264 (:file "c" :depends-on ("a" "b")))
1268 @subsection Source location
1270 The @code{:pathname} option is optional in all cases for systems
1271 defined via @code{defsystem},
1272 and in the usual case the user is recommended not to supply it.
1274 Instead, ASDF follows a hairy set of rules that are designed so that
1278 will load a system from disk
1279 and have its pathname default to the right place.
1282 This pathname information will not be overwritten with
1283 @code{*default-pathname-defaults*}
1284 (which could be somewhere else altogether)
1285 if the user loads up the @file{.asd} file into his editor
1286 and interactively re-evaluates that form.
1289 If a system is being loaded for the first time,
1290 its top-level pathname will be set to:
1294 The host/device/directory parts of @code{*load-truename*},
1297 @code{*default-pathname-defaults*}, otherwise.
1300 If a system is being redefined, the top-level pathname will be
1304 changed, if explicitly supplied or obtained from @code{*load-truename*}
1305 (so that an updated source location is reflected in the system definition)
1308 changed if it had previously been set from @code{*default-pathname-defaults*}
1311 left as before, if it had previously been set from @code{*load-truename*}
1312 and @code{*load-truename*} is currently unbound
1313 (so that a developer can evaluate a @code{defsystem} form
1314 from within an editor without clobbering its source location)
1317 @subsection if-feature option
1318 This option allows you to specify a feature expression to be evaluated
1319 as if by @code{#+} to conditionally include a component in your build.
1320 If the expression is false, the component is dropped
1321 as well as any dependency pointing to it.
1322 As compared to using @code{#+} which is expanded at read-time,
1323 this allows you to have an object in your component hierarchy
1324 that can be used for manipulations beside building your project.
1325 This option was added in ASDF 3.
1327 @subsection if-component-dep-fails option
1328 This option was removed in ASDF 3.
1329 Its semantics was limited in purpose and dubious to explain,
1330 and its implementation was breaking a hole into the ASDF object model.
1331 Please use the @code{if-feature} option instead.
1333 @node Other code in .asd files, , The defsystem grammar, Defining systems with defsystem
1334 @section Other code in .asd files
1336 Files containing @code{defsystem} forms
1337 are regular Lisp files that are executed by @code{load}.
1338 Consequently, you can put whatever Lisp code you like into these files
1339 (e.g., code that examines the compile-time environment
1340 and adds appropriate features to @code{*features*}).
1341 However, some conventions should be followed,
1342 so that users can control certain details of execution
1343 of the Lisp in @file{.asd} files:
1347 Any informative output
1348 (other than warnings and errors,
1349 which are the condition system's to dispose of)
1350 should be sent to the standard CL stream @code{*standard-output*},
1351 so that users can easily control the disposition
1352 of output from ASDF operations.
1356 @node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top
1357 @comment node-name, next, previous, up
1358 @chapter The object model of ASDF
1360 ASDF is designed in an object-oriented way from the ground up.
1361 Both a system's structure and the operations that can be performed on systems
1362 follow a extensible protocol.
1364 This allows the addition of behaviours:
1365 for example, @code{cffi} adds support of special FFI description files
1366 to interface with C libraries and of wrapper files to embed C code in Lisp;
1367 @code{abcl-jar} supports creating Java JAR archives in ABCL;
1368 and @code{poiu} supports for compiling code in parallel using background processes.
1370 This chapter deals with @code{component}s and @code{operation}s.
1372 A @code{component} represents an individual source file or a group of source files,
1373 and the things that get transformed into.
1374 A @code{system} is a component at the top level of the component hierarchy.
1375 A @code{source-file} is a component representing a single source-file
1376 and the successive output files into which it is transformed.
1377 A @code{module} is an intermediate component itself grouping several other components,
1378 themselves source-files or further modules.
1380 An @code{Operation} represents a transformation that can be performed on a component,
1381 turning them from source files to intermediate results to final outputs.
1383 A pair of an @code{operation} and a @code{component} is called an @code{action}.
1384 An @code{action} represents a particular build step to be @code{perform}ed,
1385 after all its dependencies have been fulfilled.
1386 In the ASDF model, actions depend on other actions.
1387 The term @emph{action} itself was used by Kent Pitman in his old article,
1388 but was only used by ASDF hackers starting with the ASDF 2;
1389 but the concept is ubiquitous since the very beginning of ASDF 1,
1390 though previously implicit.
1392 Then, there are many @emph{functions} available
1393 to users, extenders and implementers of ASDF
1394 to use, define or implement the activities
1395 that are part of building your software.
1396 Though they manipulate @code{action}s,
1397 most of these functions do not take as an argument
1398 a reified pair (a CONS cell) of an operation and a component;
1399 instead, they usually take two separate arguments,
1400 which allows to take advantage of the power CLOS-style multiple dispatch
1403 There are many @emph{hooks} in which to add functionality,
1404 by customizing the behavior of existing @emph{functions}.
1406 Last but not least is the notion of @emph{dependency} between two actions.
1407 The structure of dependencies between actions is
1408 a directed @emph{dependency graph}.
1409 ASDF is invoked by being told to @emph{operate}
1410 with some @emph{operation} on some toplevel @emph{system};
1411 it will then @emph{traverse} the graph and build a @emph{plan}
1412 that follows its structure.
1413 To be successfully buildable, this graph of actions but be acyclic.
1414 If, as a user, extender or implementer of ASDF, you fail
1415 to keep the dependency graph without cycles,
1416 ASDF will fail loudly as it eventually finds one.
1417 To clearly distinguish the direction of dependencies,
1418 ASDF 3 uses the words @emph{requiring} and @emph{required}
1419 as applied to an action depending on the other:
1420 the requiring action @code{depends-on} the completion of all required actions
1421 before it may itself be @code{perform}ed.
1423 Using the @code{defsystem} syntax, users may easily express
1424 direct dependencies along the graph of the object hierarchy:
1425 between a component and its parent, its children, and its siblings.
1426 By defining custom CLOS methods, you can express more elaborate dependencies as you wish.
1427 Most common operations, such as @code{load-op}, @code{compile-op} or @code{load-source-op}
1428 are automatically propagate ``downward'' the component hierarchy and are ``covariant'' with it:
1429 to act the operation on the parent module, you must first act it on all the children components,
1430 with the action on the parent being parent of the action on each child.
1431 Other operations, such as @code{prepare-op} and @code{prepare-source-op}
1432 (introduced in ASDF 3) are automatically propagated ``upward'' the component hierarchy
1433 and are ``contravariant'' with it:
1434 to perform the operation of preparing for compilation of a child component,
1435 you must perform the operation of preparing for compilation of its parent component, and so on,
1436 ensuring that all the parent's dependencies are (compiled and) loaded
1437 before the child component may be compiled and loaded.
1438 Yet other operations, such as @code{test-op} or @code{load-fasl-op}
1439 remain at the system level, and are not propagated along the hierarchy,
1440 but instead do something global on the system.
1448 @node Operations, Components, The object model of ASDF, The object model of ASDF
1449 @comment node-name, next, previous, up
1453 An @dfn{operation} object of the appropriate type is instantiated
1454 whenever the user wants to do something with a system like
1457 @item compile all its files
1458 @item load the files into a running lisp environment
1459 @item copy its source files somewhere else
1462 Operations can be invoked directly, or examined
1463 to see what their effects would be without performing them.
1464 There are a bunch of methods specialised on operation and component type
1465 that actually do the grunt work.
1467 The operation object contains whatever state is relevant for this purpose
1468 (perhaps a list of visited nodes, for example)
1469 but primarily is a nice thing to specialise operation methods on
1470 and easier than having them all be @code{EQL} methods.
1472 Operations are invoked on systems via @code{operate}.
1474 @deffn {Generic function} @code{operate} @var{operation} @var{system} @&rest @var{initargs} @&key @code{force} @code{force-not} @code{verbose} @&allow-other-keys
1475 @deffnx {Generic function} @code{oos} @var{operation} @var{system} @&rest @var{initargs} @&key @&allow-other-keys
1476 @code{operate} invokes @var{operation} on @var{system}.
1477 @code{oos} is a synonym for @code{operate}.
1479 @var{operation} is a symbol that is passed, along with the supplied
1480 @var{initargs}, to @code{make-instance} to create the operation object.
1481 @var{system} is a system designator.
1483 The @var{initargs} are passed to the @code{make-instance} call
1484 when creating the operation object.
1485 Note that dependencies may cause the operation
1486 to invoke other operations on the system or its components:
1487 the new operations will be created
1488 with the same @var{initargs} as the original one.
1490 If @var{force} is @code{:all}, then all systems
1491 are forced to be recompiled even if not modified since last compilation.
1492 If @var{force} is @code{t}, then only the system being loaded
1493 is forced to be recompiled even if not modified since last compilation,
1494 but other systems are not affected.
1495 If @var{force} is a list, then it specifies a list of systems that
1496 are forced to be recompiled even if not modified since last compilation.
1497 If @var{force-not} is @code{:all}, then all systems
1498 are forced not to be recompiled even if modified since last compilation.
1499 If @var{force-not} is @code{t}, then only the system being loaded
1500 is forced not to be recompiled even if modified since last compilation,
1501 but other systems are not affected.
1502 If @var{force-not} is a list, then it specifies a list of systems that
1503 are forced not to be recompiled even if modified since last compilation.
1504 @var{force} takes precedences over @var{force-not};
1505 both of them apply to systems that are dependencies and were already compiled.
1507 To see what @code{operate} would do, you can use:
1509 (asdf::traverse (make-instance operation-class initargs ...) (find-system system-name))
1515 * Predefined operations of ASDF::
1516 * Creating new operations::
1519 @node Predefined operations of ASDF, Creating new operations, Operations, Operations
1520 @comment node-name, next, previous, up
1521 @subsection Predefined operations of ASDF
1523 All the operations described in this section are in the @code{asdf} package.
1524 They are invoked via the @code{operate} generic function.
1527 (asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
1530 @deffn Operation @code{compile-op} @&key @code{proclamations}
1532 This operation compiles the specified component.
1533 If proclamations are supplied, they will be proclaimed.
1534 This is a good place to specify optimization settings.
1536 When creating a new component type,
1537 you should provide methods for @code{compile-op}.
1539 When @code{compile-op} is invoked,
1540 component dependencies often cause some parts of the system
1541 to be loaded as well as compiled.
1542 Invoking @code{compile-op}
1543 does not necessarily load all the parts of the system, though;
1544 use @code{load-op} to load a system.
1547 @deffn Operation @code{load-op} @&key @code{proclamations}
1549 This operation loads a system.
1551 The default methods for @code{load-op} compile files before loading them.
1552 For parity, your own methods on new component types should probably do so too.
1555 @deffn Operation @code{parent-load-op} @&key @code{proclamations}
1557 This operation ensures that the dependencies
1558 of a module, and its parent, and so on, are loaded (as per @code{load-op})
1559 before the components within that module may be operated upon.
1561 By default, all operations depend on this @code{parent-operation}
1562 for actions on components to depend on this ``parent operation'' being acted on the parent.
1564 The default methods for @code{load-op} compile files before loading them.
1565 For parity, your own methods on new component types should probably do so too.
1568 @deffn Operation @code{load-source-op}
1570 This operation will load the source for the files in a module
1571 even if the source files have been compiled.
1572 Systems sometimes have knotty dependencies
1573 which require that sources are loaded
1574 before they can be compiled.
1575 This is how you do that.
1577 If you are creating a component type,
1578 you need to implement this operation --- at least, where meaningful.
1582 @deffn Operation @code{test-op}
1584 This operation will perform some tests on the module.
1585 The default method will do nothing.
1586 The default dependency is to require
1587 @code{load-op} to be performed on the module first.
1588 The default @code{operation-done-p} is that the operation is @emph{never} done
1590 we assume that if you invoke the @code{test-op},
1591 you want to test the system, even if you have already done so.
1593 The results of this operation are not defined by ASDF.
1594 It has proven difficult to define how the test operation
1595 should signal its results to the user
1596 in a way that is compatible with all of the various test libraries
1597 and test techniques in use in the community.
1599 People typically define @code{test-op} methods like thus:
1601 (defmethod perform ((o asdf:test-op) (s (eql (asdf:find-system @var{:mysystem}))))
1602 (asdf:load-system @var{:mysystem})
1603 (eval (read-from-string "(some expression that runs the tests)"))
1608 @deffn Operation @code{load-fasl-op}
1610 This operation will load and create if need be
1611 a single fasl file for all the files in each loaded system.
1612 (Its compilation-only equivalent is @code{asdf::fasl-op}.)
1614 Once you have created such a fasl,
1615 you can use @code{precompiled-system} to deliver it in a way
1616 that is compatible with clients having asdf dependencies
1617 on your system whether it is distributed as source of as a single binary.
1619 On your build platform, you run something like that:
1621 @code{(asdf:operate 'load-fasl-op @var{:mysystem})}
1624 And on your delivery platform, a form like this is evaluated
1625 in a prologue or at some point before you save your image:
1627 (defsystem :mysystem :class :precompiled-system
1628 :fasl (some expression that will evaluate to a pathname))
1631 Of course, @emph{before} you define such systems,
1632 you should not forget to @code{(asdf:clear-configuration)}.
1634 @code{load-fasl-op} is available on all actively supported Lisp implementations,
1635 and on those implementations only, and only since ASDF 3.
1636 This functionality was previously available for select implementations,
1637 as part of a separate system @code{asdf-bundle},
1638 itself descended from @code{asdf-ecl}.
1642 @c @deffn Operation test-system-version @&key minimum
1644 @c Asks the system whether it satisfies a version requirement.
1646 @c The default method accepts a string, which is expected to contain of a
1647 @c number of integers separated by #\. characters. The method is not
1648 @c recursive. The component satisfies the version dependency if it has
1649 @c the same major number as required and each of its sub-versions is
1650 @c greater than or equal to the sub-version number required.
1653 @c (defun version-satisfies (x y)
1654 @c (labels ((bigger (x y)
1655 @c (cond ((not y) t)
1657 @c ((> (car x) (car y)) t)
1658 @c ((= (car x) (car y))
1659 @c (bigger (cdr x) (cdr y))))))
1660 @c (and (= (car x) (car y))
1661 @c (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
1664 @c If that doesn't work for your system, you can override it. I hope
1665 @c you have as much fun writing the new method as @verb{|#lisp|} did
1666 @c reimplementing this one.
1669 @c @deffn Operation feature-dependent-op
1671 @c An instance of @code{feature-dependent-op} will ignore any components
1672 @c which have a @code{features} attribute, unless the feature combination
1673 @c it designates is satisfied by @code{*features*}. This operation is
1674 @c not intended to be instantiated directly, but other operations may
1679 @node Creating new operations, , Predefined operations of ASDF, Operations
1680 @comment node-name, next, previous, up
1681 @subsection Creating new operations
1683 ASDF was designed to be extensible in an object-oriented fashion.
1684 To teach ASDF new tricks, a programmer can implement the behaviour he wants
1685 by creating a subclass of @code{operation}.
1687 ASDF's pre-defined operations are in no way ``privileged'',
1688 but it is requested that developers never use the @code{asdf} package
1689 for operations they develop themselves.
1690 The rationale for this rule is that we don't want to establish a
1691 ``global asdf operation name registry'',
1692 but also want to avoid name clashes.
1694 An operation must provide methods for the following generic functions
1695 when invoked with an object of type @code{source-file}:
1696 @emph{FIXME describe this better}
1700 @item @code{input-files}
1701 ASDF has a pretty clever default @code{input-files} mechanism.
1702 You only need create a method if there are multiple ultimate input files,
1703 and/or the bottom one doesn't depend
1704 on the @code{component-pathname} of the component.
1706 @item @code{output-files}
1707 The @code{output-files} method determines where the method will put its files.
1708 It returns two values, a list of pathnames, and a boolean.
1709 If the boolean is @code{T} then the pathnames are marked
1710 not be translated by enclosing @code{:around} methods.
1711 If the boolean is @code{NIL} then enclosing @code{:around} methods
1712 may translate these pathnames, e.g. to ensure object files
1713 are somehow stored in some implementation-dependent cache.
1715 @item @code{perform}
1716 The @code{perform} method must call @code{output-files}
1717 to find out where to put its files,
1718 because the user is allowed to override.
1719 @item @code{output-files}
1720 for local policy @code{explain}
1722 @item @code{operation-done-p}
1723 You only need to define a method on that function
1724 if you can detect conditions that invalidate previous runs of the operation,
1725 even though no filesystem timestamp has changed,
1726 in which case you return @code{nil} (the default is @code{t}).
1728 For instance, the method for @code{test-op} always returns @code{nil},
1729 so that tests are always run afresh.
1730 Of course, the @code{test-op} for your system could depend
1731 on a deterministically repeatable @code{test-report-op},
1732 and just read the results from the report files.
1734 @item @code{component-depends-on}
1735 When you add new operations, you probably need to explain
1736 how they relate to loading, compiling, testing, etc.,
1737 in terms of dependencies between actions.
1739 That's where you typically define methods on @code{component-depends-on}.
1740 Your method will take as arguments
1741 some properly specialized operation
1742 and a component denoting a current action,
1743 and return a list of entries,
1744 denoting the children actions that the current action depends on.
1745 The format of entries is described below.
1747 It is @emph{strongly} advised that
1748 you should always append the results of @code{(call-next-method)}
1749 to the results of your method,
1750 or ``interesting'' failures will likely occur,
1751 unless you're a true specialist of ASDF internals.
1753 Each entry returned by @code{component-depends-on} is itself a list.
1755 The first element of an entry is the name of an operation:
1756 a symbol that you can use with @code{make-instance}
1757 (ASDF will instead use with @code{asdf::make-sub-operation}),
1758 to create a related operation for use in a build plan.
1759 For instance, @code{load-op} and @code{compile-op}
1760 are common such names, denoting the respective operations.
1762 The rest of an entry is a list of identifiers
1763 each denote a component such that
1764 the pair of the previous operation and this component
1765 is a children action of current action.
1767 Identifiers follow the @code{defsystem} grammar
1768 previously documented.
1769 The main format for identifiers is a string or symbol
1770 (that will be downcase as per @code{coerce-name}),
1771 and looked up against the sibling list of the parent module's children components,
1772 as per @code{find-component}.
1773 As a special case, @code{nil} denotes the parent itself.
1774 Other syntaxes are allowed, for instance to specify a component with a version.
1778 Operations that print output should send that output to the standard
1779 CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
1781 @node Components, Functions, Operations, The object model of ASDF
1782 @comment node-name, next, previous, up
1786 @cindex system designator
1787 @vindex *system-definition-search-functions*
1789 A @dfn{component} represents a source file or
1790 (recursively) a collection of components.
1791 A @dfn{system} is (roughly speaking) a top-level component
1792 that can be found via @code{find-system}.
1794 A @dfn{system designator} is a string or symbol
1795 and behaves just like any other component name
1796 (including with regard to the case conversion rules for component names).
1799 @defun find-system system-designator &optional (error-p t)
1801 Given a system designator, @code{find-system} finds and returns a system.
1802 If no system is found, an error of type
1803 @code{missing-component} is thrown,
1804 or @code{nil} is returned if @code{error-p} is false.
1806 To find and update systems, @code{find-system} funcalls each element
1807 in the @code{*system-definition-search-functions*} list,
1808 expecting a pathname to be returned, or a system object,
1809 from which a pathname may be extracted, and that will be registered.
1810 The resulting pathname (if any) is loaded
1811 if one of the following conditions is true:
1815 there is no system of that name in memory
1817 the pathname is different from that which was previously loaded
1819 the file's @code{last-modified} time exceeds the @code{last-modified} time
1820 of the system in memory
1823 When system definitions are loaded from @file{.asd} files,
1824 a new scratch package is created for them to load into,
1825 so that different systems do not overwrite each others operations.
1826 The user may also wish to (and is recommended to)
1827 include @code{defpackage} and @code{in-package} forms
1828 in his system definition files, however,
1829 so that they can be loaded manually if need be.
1831 The default value of @code{*system-definition-search-functions*}
1832 is a list of two functions.
1833 The first function looks in each of the directories given
1834 by evaluating members of @code{*central-registry*}
1835 for a file whose name is the name of the system and whose type is @file{asd}.
1836 The first such file is returned,
1837 whether or not it turns out to actually define the appropriate system.
1838 The second function does something similar,
1839 for the directories specified in the @code{source-registry}.
1840 Hence, it is strongly advised to define a system
1841 @var{foo} in the corresponding file @var{foo.asd}.
1846 * Common attributes of components::
1847 * Pre-defined subclasses of component::
1848 * Creating new component types::
1851 @node Common attributes of components, Pre-defined subclasses of component, Components, Components
1852 @comment node-name, next, previous, up
1853 @subsection Common attributes of components
1855 All components, regardless of type, have the following attributes.
1856 All attributes except @code{name} are optional.
1860 A component name is a string or a symbol.
1861 If a symbol, its name is taken and lowercased.
1863 Unless overridden by a @code{:pathname} attribute,
1864 the name will be interpreted as a pathname specifier according
1865 to a Unix-style syntax.
1866 @xref{The defsystem grammar,,Pathname specifiers}.
1868 @subsubsection Version identifier
1869 @findex version-satisfies
1872 This optional attribute is used by the generic function
1873 @code{version-satisfies}, which tests to see if @code{:version}
1874 dependencies are satisfied.
1875 the version should be a string of integers separated by dots,
1876 for example @samp{1.0.11}.
1877 For more information on the semantics of version specifiers, see @ref{The defsystem grammar}.
1879 @c This optional attribute is intended to be used by the @code{test-system-version} operation.
1880 @c @xref{Predefined operations of ASDF}.
1881 @c @emph{Nota Bene}:
1882 @c This operation, planned for ASDF 1,
1883 @c is still not implemented yet as of ASDF 3.
1884 @c Don't hold your breath.
1888 @subsubsection Required features
1890 @emph{FIXME: This subsection seems to contradict the
1891 @code{defsystem} grammar subsection,
1892 which doesn't provide any obvious way to specify required features.
1893 Furthermore, in 2009, discussions on the
1894 @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
1895 suggested that the specification of required features may be broken,
1896 and that no one may have been using them for a while.
1898 @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
1899 if you are interested in getting this features feature fixed.}
1901 Traditionally defsystem users have used reader conditionals
1902 to include or exclude specific per-implementation files.
1903 This means that any single implementation cannot read the entire system,
1904 which becomes a problem if it doesn't wish to compile it,
1905 but instead for example to create an archive file containing all the sources,
1906 as it will omit to process the system-dependent sources for other systems.
1908 Each component in an asdf system may therefore specify features using
1909 the same syntax as @code{#+} does, and it will (somehow) be ignored for
1910 certain operations unless the feature conditional is a member of
1914 @subsubsection Dependencies
1916 This attribute specifies dependencies of the component on its siblings.
1917 It is optional but often necessary.
1919 There is an excitingly complicated relationship between the initarg
1920 and the method that you use to ask about dependencies
1922 Dependencies are between (operation component) pairs.
1923 In your initargs for the component, you can say
1926 :in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
1927 (load-op (load-op "foo")))
1930 This means the following things:
1933 before performing compile-op on this component, we must perform
1934 load-op on @var{a} and @var{b}, and compile-op on @var{c},
1936 before performing @code{load-op}, we have to load @var{foo}
1939 The syntax is approximately
1942 (this-op {(other-op required-components)}+)
1944 simple-component-name := string
1947 required-components := simple-component-name
1948 | (required-components required-components)
1950 component-name := simple-component-name
1951 | (:version simple-component-name minimum-version-object)
1956 This is on a par with what ACL defsystem does.
1957 mk-defsystem is less general: it has an implied dependency
1960 for all source file x, (load x) depends on (compile x)
1963 and using a @code{:depends-on} argument to say that @var{b} depends on
1964 @var{a} @emph{actually} means that
1967 (compile b) depends on (load a)
1970 This is insufficient for e.g. the McCLIM system, which requires that
1971 all the files are loaded before any of them can be compiled ]
1975 In ASDF, the dependency information for a given component and operation
1976 can be queried using @code{(component-depends-on operation component)},
1977 which returns a list
1980 ((load-op "a") (load-op "b") (compile-op "c") ...)
1983 @code{component-depends-on} can be subclassed for more specific
1984 component/operation types: these need to @code{(call-next-method)}
1985 and append the answer to their dependency, unless
1986 they have a good reason for completely overriding the default dependencies.
1988 If it weren't for CLISP, we'd be using @code{LIST} method
1989 combination to do this transparently.
1990 But, we need to support CLISP.
1991 If you have the time for some CLISP hacking,
1992 I'm sure they'd welcome your fixes.
1993 @c Doesn't CLISP now support LIST method combination?
1995 See the discussion of the semantics of @code{:version} in the defsystem
1998 @c FIXME: Should have cross-reference to "Version specifiers" in the
1999 @c defsystem grammar, but the cross-referencing is so broken by
2000 @c insufficient node breakdown that I have not put one in.
2003 @subsubsection pathname
2005 This attribute is optional and if absent (which is the usual case),
2006 the component name will be used.
2008 @xref{The defsystem grammar,,Pathname specifiers},
2009 for an explanation of how this attribute is interpreted.
2011 Note that the @code{defsystem} macro (used to create a ``top-level'' system)
2012 does additional processing to set the filesystem location of
2013 the top component in that system.
2014 This is detailed elsewhere. @xref{Defining systems with defsystem}.
2017 @subsubsection properties
2019 This attribute is optional.
2021 Packaging systems often require information about files or systems
2022 in addition to that specified by ASDF's pre-defined component attributes.
2023 Programs that create vendor packages out of ASDF systems therefore
2024 have to create ``placeholder'' information to satisfy these systems.
2025 Sometimes the creator of an ASDF system may know the additional
2026 information and wish to provide it directly.
2028 @code{(component-property component property-name)} and
2029 associated @code{setf} method will allow
2030 the programmatic update of this information.
2031 Property names are compared as if by @code{EQL},
2032 so use symbols or keywords or something.
2035 * Pre-defined subclasses of component::
2036 * Creating new component types::
2039 @node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
2040 @comment node-name, next, previous, up
2041 @subsection Pre-defined subclasses of component
2043 @deffn Component source-file
2045 A source file is any file that the system does not know how to
2046 generate from other components of the system.
2048 Note that this is not necessarily the same thing as
2049 ``a file containing data that is typically fed to a compiler''.
2050 If a file is generated by some pre-processor stage
2051 (e.g. a @file{.h} file from @file{.h.in} by autoconf)
2052 then it is not, by this definition, a source file.
2053 Conversely, we might have a graphic file
2054 that cannot be automatically regenerated,
2055 or a proprietary shared library that we received as a binary:
2056 these do count as source files for our purposes.
2058 Subclasses of source-file exist for various languages.
2059 @emph{FIXME: describe these.}
2062 @deffn Component module
2064 A module is a collection of sub-components.
2066 A module component has the following extra initargs:
2070 @code{:components} the components contained in this module
2073 @code{:default-component-class}
2074 All children components which don't specify their class explicitly
2075 are inferred to be of this type.
2078 @code{:if-component-dep-fails}
2079 This attribute was removed in ASDF 3. Do not use it.
2080 Use @code{:if-feature} instead.
2083 @code{:serial} When this attribute is set,
2084 each subcomponent of this component is assumed to depend on all subcomponents
2085 before it in the list given to @code{:components}, i.e.
2086 all of them are loaded before a compile or load operation is performed on it.
2090 The default operation knows how to traverse a module, so
2091 most operations will not need to provide methods specialised on modules.
2093 @code{module} may be subclassed to represent components such as
2094 foreign-language linked libraries or archive files.
2097 @deffn Component system
2099 @code{system} is a subclass of @code{module}.
2101 A system is a module with a few extra attributes for documentation
2102 purposes; these are given elsewhere.
2103 @xref{The defsystem grammar}.
2105 Users can create new classes for their systems:
2106 the default @code{defsystem} macro takes a @code{:class} keyword argument.
2109 @node Creating new component types, , Pre-defined subclasses of component, Components
2110 @comment node-name, next, previous, up
2111 @subsection Creating new component types
2113 New component types are defined by subclassing one of the existing
2114 component classes and specializing methods on the new component class.
2116 @emph{FIXME: this should perhaps be explained more throughly,
2117 not only by example ...}
2119 As an example, suppose we have some implementation-dependent
2120 functionality that we want to isolate
2121 in one subdirectory per Lisp implementation our system supports.
2122 We create a subclass of
2123 @code{cl-source-file}:
2126 (defclass unportable-cl-source-file (cl-source-file)
2130 Function @code{asdf:implementation-type} (exported since 2.014.14)
2131 gives us the name of the subdirectory.
2132 All that's left is to define how to calculate the pathname
2133 of an @code{unportable-cl-source-file}.
2136 (defmethod component-pathname ((component unportable-cl-source-file))
2138 (coerce-pathname (format nil "~(~A~)/" (asdf:implementation-type)))
2139 (call-next-method)))
2142 The new component type is used in a @code{defsystem} form in this way:
2149 (:unportable-cl-source-file "threads"
2150 :depends-on ("packages" ...))
2155 @node Functions, , Components, The object model of ASDF
2156 @comment node-name, next, previous, up
2158 @findex version-satisfies
2160 @deffn version-satisfies @var{version} @var{version-spec}
2161 Does @var{version} satisfy the @var{version-spec}. A generic function.
2162 ASDF provides built-in methods for @var{version} being a
2163 @code{component} or @code{string}. @var{version-spec} should be a
2166 In the wild, we typically see version numbering only on components of
2169 For more information about how @code{version-satisfies} interprets
2170 version strings and specifications, @pxref{The defsystem grammar} and
2171 @ref{Common attributes of components}.
2174 @node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
2175 @comment node-name, next, previous, up
2176 @chapter Controlling where ASDF searches for systems
2178 @section Configurations
2180 Configurations specify paths where to find system files.
2185 The search registry may use some hardcoded wrapping registry specification.
2186 This allows some implementations (notably SBCL) to specify where to find
2187 some special implementation-provided systems that
2188 need to precisely match the version of the implementation itself.
2191 An application may explicitly initialize the source-registry configuration
2192 using the configuration API
2193 (@pxref{Controlling where ASDF searches for systems,Configuration API,Configuration API}, below)
2194 in which case this takes precedence.
2195 It may itself compute this configuration from the command-line,
2196 from a script, from its own configuration file, etc.
2199 The source registry will be configured from
2200 the environment variable @code{CL_SOURCE_REGISTRY} if it exists.
2203 The source registry will be configured from
2204 user configuration file
2205 @file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf}
2207 @file{~/.config/common-lisp/source-registry.conf})
2211 The source registry will be configured from
2212 user configuration directory
2213 @file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf.d/}
2215 @file{~/.config/common-lisp/source-registry.conf.d/})
2219 The source registry will be configured from
2220 system configuration file
2221 @file{/etc/common-lisp/source-registry.conf}
2225 The source registry will be configured from
2226 system configuration directory
2227 @file{/etc/common-lisp/source-registry.conf.d/}
2231 The source registry will be configured from a default configuration.
2232 This configuration may allow for implementation-specific systems
2233 to be found, for systems to be found the current directory
2234 (at the time that the configuration is initialized) as well as
2235 @code{:directory} entries for @file{$XDG_DATA_DIRS/common-lisp/systems/} and
2236 @code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/}.
2237 For instance, SBCL will include directories for its contribs
2238 when it can find them; it will look for them where SBCL was installed,
2239 or at the location specified by the @code{SBCL_HOME} environment variable.
2243 Each of these configurations is specified as an s-expression
2244 in a trivial domain-specific language (defined below).
2245 Additionally, a more shell-friendly syntax is available
2246 for the environment variable (defined yet below).
2248 Each of these configurations is only used if the previous
2249 configuration explicitly or implicitly specifies that it
2250 includes its inherited configuration.
2252 Additionally, some implementation-specific directories
2253 may be automatically prepended to whatever directories are specified
2254 in configuration files, no matter if the last one inherits or not.
2257 @section Truenames and other dangers
2259 One great innovation of the original ASDF was its ability to leverage
2260 @code{CL:TRUENAME} to locate where your source code was and where to build it,
2261 allowing for symlink farms as a simple but effective configuration mechanism
2262 that is easy to control programmatically.
2263 ASDF 3 still supports this configuration style, and it is enabled by default;
2264 however we recommend you instead use
2265 our source-registry configuration mechanism described below,
2266 because it is easier to setup in a portable way across users and implementations.
2268 Addtionally, some people dislike truename,
2269 either because it is very slow on their system, or
2270 because they are using content-addressed storage where the truename of a file
2271 is related to a digest of its individual contents,
2272 and not to other files in the same intended project.
2273 For these people, ASDF 3 allows to eschew the @code{TRUENAME} mechanism,
2274 by setting the variable @var{asdf:*resolve-symlinks*} to @code{NIL}.
2276 PS: Yes, if you haven't read Vernor Vinge's short but great classic
2277 ``True Names... and Other Dangers'' then you're in for a treat.
2280 @section XDG base directory
2282 Note that we purport to respect the XDG base directory specification
2283 as to where configuration files are located,
2284 where data files are located,
2285 where output file caches are located.
2286 Mentions of XDG variables refer to that document.
2288 @url{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}
2290 This specification allows the user to specify some environment variables
2291 to customize how applications behave to his preferences.
2293 On Windows platforms, when not using Cygwin,
2294 instead of the XDG base directory specification,
2295 we try to use folder configuration from the registry regarding
2296 @code{Common AppData} and similar directories.
2297 Since support for querying the Windows registry
2298 is not possible to do in reasonable amounts of portable Common Lisp code,
2299 ASDF 3 relies on the environment variables that Windows usually exports.
2301 @section Backward Compatibility
2303 For backward compatibility as well as to provide a practical backdoor for hackers,
2304 ASDF will first search for @code{.asd} files in the directories specified in
2305 @code{asdf:*central-registry*}
2306 before it searches in the source registry above.
2308 @xref{Configuring ASDF,,Configuring ASDF to find your systems --- old style}.
2310 By default, @code{asdf:*central-registry*} will be empty.
2312 This old mechanism will therefore not affect you if you don't use it,
2313 but will take precedence over the new mechanism if you do use it.
2315 @section Configuration DSL
2317 Here is the grammar of the s-expression (SEXP) DSL for source-registry
2320 @c FIXME: This is too wide for happy compilation into pdf.
2323 ;; A configuration is a single SEXP starting with keyword :source-registry
2324 ;; followed by a list of directives.
2325 CONFIGURATION := (:source-registry DIRECTIVE ...)
2327 ;; A directive is one of the following:
2329 ;; INHERITANCE DIRECTIVE:
2330 ;; Your configuration expression MUST contain
2331 ;; exactly one of either of these:
2332 :inherit-configuration | ; splices inherited configuration (often specified last)
2333 :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
2335 ;; forward compatibility directive (since ASDF 2.011.4), useful when
2336 ;; you want to use new configuration features but have to bootstrap a
2337 ;; the newer required ASDF from an older release that doesn't sport said features:
2338 :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
2340 ;; add a single directory to be scanned (no recursion)
2341 (:directory DIRECTORY-PATHNAME-DESIGNATOR) |
2343 ;; add a directory hierarchy, recursing but excluding specified patterns
2344 (:tree DIRECTORY-PATHNAME-DESIGNATOR) |
2346 ;; override the defaults for exclusion patterns
2347 (:exclude EXCLUSION-PATTERN ...) |
2348 ;; augment the defaults for exclusion patterns
2349 (:also-exclude EXCLUSION-PATTERN ...) |
2350 ;; Note that the scope of a an exclude pattern specification is
2351 ;; the rest of the current configuration expression or file.
2353 ;; splice the parsed contents of another config file
2354 (:include REGULAR-FILE-PATHNAME-DESIGNATOR) |
2356 ;; This directive specifies that some default must be spliced.
2359 REGULAR-FILE-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a file
2360 DIRECTORY-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a directory name
2362 PATHNAME-DESIGNATOR :=
2363 NIL | ;; Special: skip this entry.
2364 ABSOLUTE-COMPONENT-DESIGNATOR ;; see pathname DSL
2366 EXCLUSION-PATTERN := a string without wildcards, that will be matched exactly
2367 against the name of a any subdirectory in the directory component
2368 of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"}
2371 Pathnames are designated using another DSL,
2372 shared with the output-translations configuration DSL below.
2373 The DSL is resolved by the function @code{asdf::resolve-location},
2374 to be documented and exported at some point in the future.
2377 ABSOLUTE-COMPONENT-DESIGNATOR :=
2378 (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
2379 STRING | ;; namestring (better be absolute or bust, directory assumed where applicable).
2380 ;; In output-translations, directory is assumed and **/*.*.* added if it's last.
2381 ;; On MCL, a MacOSX-style POSIX namestring (for MacOS9 style, use #p"...");
2382 ;; Note that none of the above applies to strings used in *central-registry*,
2383 ;; which doesn't use this DSL: they are processed as normal namestrings.
2384 ;; however, you can compute what you put in the *central-registry*
2385 ;; based on the results of say (asdf::resolve-location "/Users/fare/cl/cl-foo/")
2386 PATHNAME | ;; pathname (better be an absolute path, or bust)
2387 ;; In output-translations, unless followed by relative components,
2388 ;; it better have appropriate wildcards, as in **/*.*.*
2389 :HOME | ;; designates the user-homedir-pathname ~/
2390 :USER-CACHE | ;; designates the default location for the user cache
2391 :HERE | ;; designates the location of the configuration file
2392 ;; (or *default-pathname-defaults*, if invoked interactively)
2393 :ROOT ;; magic, for output-translations source only: paths that are relative
2394 ;; to the root of the source host and device
2395 ;; Not valid anymore: :SYSTEM-CACHE (was a security hazard)
2397 RELATIVE-COMPONENT-DESIGNATOR :=
2398 (RELATIVE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
2399 STRING | ;; relative directory pathname as interpreted by coerce-pathname.
2400 ;; In output translations, if last component, **/*.*.* is added
2401 PATHNAME | ;; pathname; unless last component, directory is assumed.
2402 :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
2403 :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
2404 :DEFAULT-DIRECTORY | ;; a relativized version of the default directory
2405 :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
2406 :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
2407 :*.*.* | ;; any file (since ASDF 2.011.4)
2408 ;; Not supported (anymore): :UID and :USERNAME
2411 For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf},
2412 which is the default place ASDF looks for this configuration, once contained:
2415 (:tree (:home "cl")) ;; will expand to e.g. "/home/joeluser/cl/"
2416 :inherit-configuration)
2419 @section Configuration Directories
2421 Configuration directories consist in files each containing
2422 a list of directives without any enclosing @code{(:source-registry ...)} form.
2423 The files will be sorted by namestring as if by @code{string<} and
2424 the lists of directives of these files with be concatenated in order.
2425 An implicit @code{:inherit-configuration} will be included
2426 at the @emph{end} of the list.
2428 This allows for packaging software that has file granularity
2429 (e.g. Debian's @code{dpkg} or some future version of @code{clbuild})
2430 to easily include configuration information about distributed software.
2432 The convention is that, for sorting purposes,
2433 the names of files in such a directory begin with two digits
2434 that determine the order in which these entries will be read.
2435 Also, the type of these files is conventionally @code{"conf"}
2436 and as a limitation to some implementations (e.g. GNU clisp),
2437 the type cannot be @code{NIL}.
2439 Directories may be included by specifying a directory pathname
2440 or namestring in an @code{:include} directive, e.g.:
2443 (:include "/foo/bar/")
2446 Hence, to achieve the same effect as
2447 my example @file{~/.config/common-lisp/source-registry.conf} above,
2448 I could simply create a file
2449 @file{~/.config/common-lisp/source-registry.conf.d/33-home-fare-cl.conf}
2450 alone in its directory with the following contents:
2452 (:tree "/home/fare/cl/")
2455 @subsection The :here directive
2457 The @code{:here} directive is an absolute pathname designator that
2458 refers to the directory containing the configuration file currently
2461 The @code{:here} directive is intended to simplify the delivery of
2462 complex CL systems, and for easy configuration of projects shared through
2463 revision control systems, in accordance with our design principle that
2464 each participant should be able to provide all and only the information
2465 available to him or her.
2467 Consider a person X who has set up the source code repository for a
2468 complex project with a master directory @file{dir/}. Ordinarily, one
2469 might simply have the user add a directive that would look something
2472 (:tree "path/to/dir")
2474 But what if X knows that there are very large subtrees
2475 under dir that are filled with, e.g., Java source code, image files for
2476 icons, etc.? All of the asdf system definitions are contained in the
2477 subdirectories @file{dir/src/lisp/} and @file{dir/extlib/lisp/}, and
2478 these are the only directories that should be searched.
2480 In this case, X can put into @file{dir/} a file @file{asdf.conf} that
2481 contains the following:
2484 (:tree (:here "src/lisp/"))
2485 (:tree (:here "extlib/lisp"))
2486 (:directory (:here "outlier/")))
2489 Then when someone else (call her Y) checks out a copy of this
2490 repository, she need only add
2492 (:include "/path/to/my/checkout/directory/asdf.conf")
2494 to one of her previously-existing asdf source location configuration
2495 files, or invoke @code{initialize-source-registry} with a configuration
2496 form containing that s-expression. ASDF will find the .conf file that X
2497 has provided, and then set up source locations within the working
2498 directory according to X's (relative) instructions.
2500 @section Shell-friendly syntax for configuration
2502 When considering environment variable @code{CL_SOURCE_REGISTRY}
2503 ASDF will skip to next configuration if it's an empty string.
2504 It will @code{READ} the string as a SEXP in the DSL
2505 if it begins with a paren @code{(}
2506 and it will be interpreted much like @code{TEXINPUTS}
2507 list of paths, where
2509 * paths are separated
2510 by a @code{:} (colon) on Unix platforms (including cygwin),
2511 by a @code{;} (semicolon) on other platforms (mainly, Windows).
2513 * each entry is a directory to add to the search path.
2515 * if the entry ends with a double slash @code{//}
2516 then it instead indicates a tree in the subdirectories
2517 of which to recurse.
2519 * if the entry is the empty string (which may only appear once),
2520 then it indicates that the inherited configuration should be
2524 @section Search Algorithm
2525 @vindex *default-source-registry-exclusions*
2527 In case that isn't clear, the semantics of the configuration is that
2528 when searching for a system of a given name,
2529 directives are processed in order.
2531 When looking in a directory, if the system is found, the search succeeds,
2532 otherwise it continues.
2534 When looking in a tree, if one system is found, the search succeeds.
2535 If multiple systems are found, the consequences are unspecified:
2536 the search may succeed with any of the found systems,
2537 or an error may be raised.
2538 ASDF currently returns the first system found,
2539 XCVB currently raised an error.
2540 If none is found, the search continues.
2542 Exclude statements specify patterns of subdirectories
2543 the systems from which to ignore.
2544 Typically you don't want to use copies of files kept by such
2545 version control systems as Darcs.
2546 Exclude statements are not propagated to further included or inherited
2547 configuration files or expressions;
2548 instead the defaults are reset around every configuration statement
2549 to the default defaults from @code{asdf::*default-source-registry-exclusions*}.
2551 Include statements cause the search to recurse with the path specifications
2552 from the file specified.
2554 An inherit-configuration statement cause the search to recurse with the path
2555 specifications from the next configuration
2556 (@pxref{Controlling where ASDF searches for systems,,Configurations} above).
2559 @section Caching Results
2561 The implementation is allowed to either eagerly compute the information
2562 from the configurations and file system, or to lazily re-compute it
2563 every time, or to cache any part of it as it goes.
2564 To explicitly flush any information cached by the system, use the API below.
2567 @section Configuration API
2569 The specified functions are exported from your build system's package.
2570 Thus for ASDF the corresponding functions are in package ASDF,
2571 and for XCVB the corresponding functions are in package XCVB.
2573 @defun initialize-source-registry @&optional PARAMETER
2574 will read the configuration and initialize all internal variables.
2575 You may extend or override configuration
2576 from the environment and configuration files
2577 with the given @var{PARAMETER}, which can be
2578 @code{NIL} (no configuration override),
2579 or a SEXP (in the SEXP DSL),
2580 a string (as in the string DSL),
2581 a pathname (of a file or directory with configuration),
2582 or a symbol (fbound to function that when called returns one of the above).
2585 @defun clear-source-registry
2586 undoes any source registry configuration
2587 and clears any cache for the search algorithm.
2588 You might want to call this function
2589 (or better, @code{clear-configuration})
2590 before you dump an image that would be resumed
2591 with a different configuration,
2592 and return an empty configuration.
2593 Note that this does not include clearing information about
2594 systems defined in the current image, only about
2595 where to look for systems not yet defined.
2598 @defun ensure-source-registry @&optional PARAMETER
2599 checks whether a source registry has been initialized.
2600 If not, initialize it with the given @var{PARAMETER}.
2603 Every time you use ASDF's @code{find-system}, or
2604 anything that uses it (such as @code{operate}, @code{load-system}, etc.),
2605 @code{ensure-source-registry} is called with parameter NIL,
2606 which the first time around causes your configuration to be read.
2607 If you change a configuration file,
2608 you need to explicitly @code{initialize-source-registry} again,
2609 or maybe simply to @code{clear-source-registry} (or @code{clear-configuration})
2610 which will cause the initialization to happen next time around.
2615 This mechanism is vastly successful, and we have declared
2616 that @code{asdf:*central-registry*} is not recommended anymore,
2617 though we will continue to support it.
2618 All hooks into implementation-specific search mechanisms
2619 have been integrated in the @code{wrapping-source-registry}
2620 that everyone uses implicitly.
2623 @section Rejected ideas
2625 Alternatives I considered and rejected included:
2628 @item Keep @code{asdf:*central-registry*} as the master with its current semantics,
2629 and somehow the configuration parser expands the new configuration
2630 language into a expanded series of directories of subdirectories to
2631 lookup, pre-recursing through specified hierarchies. This is kludgy,
2632 and leaves little space of future cleanups and extensions.
2634 @item Keep @code{asdf:*central-registry*} remains the master but extend its semantics
2635 in completely new ways, so that new kinds of entries may be implemented
2636 as a recursive search, etc. This seems somewhat backwards.
2638 @item Completely remove @code{asdf:*central-registry*}
2639 and break backwards compatibility.
2640 Hopefully this will happen in a few years after everyone migrate to
2641 a better ASDF and/or to XCVB, but it would be very bad to do it now.
2643 @item Replace @code{asdf:*central-registry*} by a symbol-macro with appropriate magic
2644 when you dereference it or setf it. Only the new variable with new
2645 semantics is handled by the new search procedure.
2646 Complex and still introduces subtle semantic issues.
2650 I've been suggested the below features, but have rejected them,
2651 for the sake of keeping ASDF no more complex than strictly necessary.
2655 More syntactic sugar: synonyms for the configuration directives, such as
2656 @code{(:add-directory X)} for @code{(:directory X)}, or @code{(:add-directory-hierarchy X)}
2657 or @code{(:add-directory X :recurse t)} for @code{(:tree X)}.
2660 The possibility to register individual files instead of directories.
2663 Integrate Xach Beane's tilde expander into the parser,
2664 or something similar that is shell-friendly or shell-compatible.
2665 I'd rather keep ASDF minimal. But maybe this precisely keeps it
2666 minimal by removing the need for evaluated entries that ASDF has?
2667 i.e. uses of @code{USER-HOMEDIR-PATHNAME} and @code{$SBCL_HOME}
2668 Hopefully, these are already superseded by the @code{:default-registry}
2671 Using the shell-unfriendly syntax @code{/**} instead of @code{//} to specify recursion
2672 down a filesystem tree in the environment variable.
2673 It isn't that Lisp friendly either.
2683 @section Credits for the source-registry
2685 Thanks a lot to Stelian Ionescu for the initial idea.
2687 Thanks to Rommel Martinez for the initial implementation attempt.
2689 All bad design ideas and implementation bugs are to mine, not theirs.
2690 But so are good design ideas and elegant implementation tricks.
2692 --- Francois-Rene Rideau @email{fare@@tunes.org}, Mon, 22 Feb 2010 00:07:33 -0500
2696 @node Controlling where ASDF saves compiled files, Error handling, Controlling where ASDF searches for systems, Top
2697 @comment node-name, next, previous, up
2698 @chapter Controlling where ASDF saves compiled files
2699 @cindex asdf-output-translations
2700 @vindex ASDF_OUTPUT_TRANSLATIONS
2702 Each Common Lisp implementation has its own format
2703 for compiled files (fasls for short, short for ``fast loading'').
2704 If you use multiple implementations
2705 (or multiple versions of the same implementation),
2706 you'll soon find your source directories
2707 littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so on.
2708 Worse yet, some implementations use the same file extension
2709 while changing formats from version to version (or platform to platform)
2710 which means that you'll have to recompile binaries
2711 as you switch from one implementation to the next.
2713 Since ASDF 2, ASDF includes the @code{asdf-output-translations} facility
2714 to mitigate the problem.
2716 @section Configurations
2718 Configurations specify mappings from input locations to output locations.
2719 Once again we rely on the XDG base directory specification for configuration.
2720 @xref{Controlling where ASDF searches for systems,,XDG base directory}.
2725 Some hardcoded wrapping output translations configuration may be used.
2726 This allows special output translations (or usually, invariant directories)
2727 to be specified corresponding to the similar special entries in the source registry.
2730 An application may explicitly initialize the output-translations
2731 configuration using the Configuration API
2732 in which case this takes precedence.
2733 (@pxref{Controlling where ASDF saves compiled files,,Configuration API}.)
2734 It may itself compute this configuration from the command-line,
2735 from a script, from its own configuration file, etc.
2738 The source registry will be configured from
2739 the environment variable @code{ASDF_OUTPUT_TRANSLATIONS} if it exists.
2742 The source registry will be configured from
2743 user configuration file
2744 @file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf}
2746 @file{~/.config/common-lisp/asdf-output-translations.conf})
2750 The source registry will be configured from
2751 user configuration directory
2752 @file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf.d/}
2754 @file{~/.config/common-lisp/asdf-output-translations.conf.d/})
2758 The source registry will be configured from
2759 system configuration file
2760 @file{/etc/common-lisp/asdf-output-translations.conf}
2764 The source registry will be configured from
2765 system configuration directory
2766 @file{/etc/common-lisp/asdf-output-translations.conf.d/}
2771 Each of these configurations is specified as a SEXP
2772 in a trival domain-specific language (defined below).
2773 Additionally, a more shell-friendly syntax is available
2774 for the environment variable (defined yet below).
2776 Each of these configurations is only used if the previous
2777 configuration explicitly or implicitly specifies that it
2778 includes its inherited configuration.
2780 Note that by default, a per-user cache is used for output files.
2781 This allows the seamless use of shared installations of software
2782 between several users, and takes files out of the way of the developers
2783 when they browse source code,
2784 at the expense of taking a small toll when developers have to clean up
2785 output files and find they need to get familiar with output-translations first.
2788 @section Backward Compatibility
2789 @cindex ASDF-BINARY-LOCATIONS compatibility
2792 We purposefully do NOT provide backward compatibility with earlier versions of
2793 @code{ASDF-Binary-Locations} (8 Sept 2009),
2794 @code{common-lisp-controller} (7.0) or
2795 @code{cl-launch} (2.35),
2796 each of which had similar general capabilities.
2797 The previous APIs of these programs were not designed
2798 for configuration by the end-user
2799 in an easy way with configuration files.
2800 Recent versions of same packages use
2801 the new @code{asdf-output-translations} API as defined below:
2802 @code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000).
2803 @code{ASDF-Binary-Locations} is fully superseded and not to be used anymore.
2805 This incompatibility shouldn't inconvenience many people.
2806 Indeed, few people use and customize these packages;
2807 these few people are experts who can trivially adapt to the new configuration.
2808 Most people are not experts, could not properly configure these features
2809 (except inasmuch as the default configuration of
2810 @code{common-lisp-controller} and/or @code{cl-launch}
2811 might have been doing the right thing for some users),
2812 and yet will experience software that ``just works'',
2813 as configured by the system distributor, or by default.
2815 Nevertheless, if you are a fan of @code{ASDF-Binary-Locations},
2816 we provide a limited emulation mode:
2818 @defun enable-asdf-binary-locations-compatibility @&key centralize-lisp-binaries default-toplevel-directory include-per-user-information map-all-source-files source-to-target-mappings
2819 This function will initialize the new @code{asdf-output-translations} facility in a way
2820 that emulates the behavior of the old @code{ASDF-Binary-Locations} facility.
2821 Where you would previously set global variables
2822 @var{*centralize-lisp-binaries*},
2823 @var{*default-toplevel-directory*},
2824 @var{*include-per-user-information*},
2825 @var{*map-all-source-files*} or @var{*source-to-target-mappings*}
2826 you will now have to pass the same values as keyword arguments to this function.
2827 Note however that as an extension the @code{:source-to-target-mappings} keyword argument
2828 will accept any valid pathname designator for @code{asdf-output-translations}
2829 instead of just strings and pathnames.
2832 If you insist, you can also keep using the old @code{ASDF-Binary-Locations}
2833 (the one available as an extension to load of top of ASDF,
2834 not the one built into a few old versions of ASDF),
2835 but first you must disable @code{asdf-output-translations}
2836 with @code{(asdf:disable-output-translations)},
2837 or you might experience ``interesting'' issues.
2839 Also, note that output translation is enabled by default.
2840 To disable it, use @code{(asdf:disable-output-translations)}.
2843 @section Configuration DSL
2845 Here is the grammar of the SEXP DSL
2846 for @code{asdf-output-translations} configuration:
2849 ;; A configuration is single SEXP starting with keyword :source-registry
2850 ;; followed by a list of directives.
2851 CONFIGURATION := (:output-translations DIRECTIVE ...)
2853 ;; A directive is one of the following:
2855 ;; INHERITANCE DIRECTIVE:
2856 ;; Your configuration expression MUST contain
2857 ;; exactly one of either of these:
2858 :inherit-configuration | ; splices inherited configuration (often specified last)
2859 :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
2861 ;; forward compatibility directive (since ASDF 2.011.4), useful when
2862 ;; you want to use new configuration features but have to bootstrap a
2863 ;; the newer required ASDF from an older release that doesn't sport said features:
2864 :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out
2866 ;; include a configuration file or directory
2867 (:include PATHNAME-DESIGNATOR) |
2869 ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/ or something.
2870 :enable-user-cache |
2871 ;; Disable global cache. Map / to /
2874 ;; add a single directory to be scanned (no recursion)
2875 (DIRECTORY-DESIGNATOR DIRECTORY-DESIGNATOR)
2877 ;; use a function to return the translation of a directory designator
2878 (DIRECTORY-DESIGNATOR (:function TRANSLATION-FUNCTION))
2880 DIRECTORY-DESIGNATOR :=
2881 NIL | ;; As source: skip this entry. As destination: same as source
2882 T | ;; as source matches anything, as destination leaves pathname unmapped.
2883 ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language
2885 TRANSLATION-FUNCTION :=
2886 SYMBOL | ;; symbol of a function that takes two arguments,
2887 ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
2888 LAMBDA ;; A form which evalutates to a function taking two arguments consisting of
2889 ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
2893 Relative components better be either relative
2894 or subdirectories of the path before them, or bust.
2896 The last component, if not a pathname, is notionally completed by @file{/**/*.*}.
2897 You can specify more fine-grained patterns
2898 by using a pathname object as the last component
2899 e.g. @file{#p"some/path/**/foo*/bar-*.fasl"}
2901 You may use @code{#+features} to customize the configuration file.
2903 The second designator of a mapping may be @code{NIL}, indicating that files are not mapped
2904 to anything but themselves (same as if the second designator was the same as the first).
2906 When the first designator is @code{t},
2907 the mapping always matches.
2908 When the first designator starts with @code{:root},
2909 the mapping matches any host and device.
2910 In either of these cases, if the second designator
2911 isn't @code{t} and doesn't start with @code{:root},
2912 then strings indicating the host and pathname are somehow copied
2913 in the beginning of the directory component of the source pathname
2914 before it is translated.
2916 When the second designator is @code{t}, the mapping is the identity.
2917 When the second designator starts with @code{:root},
2918 the mapping preserves the host and device of the original pathname.
2919 Notably, this allows you to map files
2920 to a subdirectory of the whichever directory the file is in.
2921 Though the syntax is not quite as easy to use as we'd like,
2922 you can have an (source destination) mapping entry such as follows
2923 in your configuration file,
2924 or you may use @code{enable-asdf-binary-locations-compatibility}
2925 with @code{:centralize-lisp-binaries nil}
2926 which will do the same thing internally for you:
2928 #.(let ((wild-subdir (make-pathname :directory '(:relative :wild-inferiors)))
2929 (wild-file (make-pathname :name :wild :version :wild :type :wild)))
2930 `((:root ,wild-subdir ,wild-file) ;; Or using the implicit wildcard, just :root
2931 (:root ,wild-subdir :implementation ,wild-file)))
2933 Starting with ASDF 2.011.4, you can use the simpler:
2934 @code{`(:root (:root :**/ :implementation :*.*.*))}
2938 @code{:include} statements cause the search to recurse with the path specifications
2939 from the file specified.
2941 If the @code{translate-pathname} mechanism cannot achieve a desired
2942 translation, the user may provide a function which provides the
2943 required algorithim. Such a translation function is specified by
2944 supplying a list as the second @code{directory-designator}
2945 the first element of which is the keyword @code{:function},
2946 and the second element of which is
2947 either a symbol which designates a function or a lambda expression.
2948 The function designated by the second argument must take two arguments,
2949 the first being the pathname of the source file,
2950 the second being the wildcard that was matched.
2951 The result of the function invocation should be the translated pathname.
2953 An @code{:inherit-configuration} statement cause the search to recurse with the path
2954 specifications from the next configuration.
2955 @xref{Controlling where ASDF saves compiled files,,Configurations}, above.
2959 @code{:enable-user-cache} is the same as @code{(t :user-cache)}.
2961 @code{:disable-cache} is the same as @code{(t t)}.
2963 @code{:user-cache} uses the contents of variable @code{asdf::*user-cache*}
2964 which by default is the same as using
2965 @code{(:home ".cache" "common-lisp" :implementation)}.
2967 @code{:system-cache} uses the contents of variable @code{asdf::*system-cache*}
2968 which by default is the same as using
2969 @code{("/var/cache/common-lisp" :uid :implementation-type)}
2970 (on Unix and cygwin), or something semi-sensible on Windows.
2974 @section Configuration Directories
2976 Configuration directories consist in files each contains
2977 a list of directives without any enclosing
2978 @code{(:output-translations ...)} form.
2979 The files will be sorted by namestring as if by @code{string<} and
2980 the lists of directives of these files with be concatenated in order.
2981 An implicit @code{:inherit-configuration} will be included
2982 at the @emph{end} of the list.
2984 This allows for packaging software that has file granularity
2985 (e.g. Debian's @command{dpkg} or some future version of @command{clbuild})
2986 to easily include configuration information about software being distributed.
2988 The convention is that, for sorting purposes,
2989 the names of files in such a directory begin with two digits
2990 that determine the order in which these entries will be read.
2991 Also, the type of these files is conventionally @code{"conf"}
2992 and as a limitation of some implementations, the type cannot be @code{NIL}.
2994 Directories may be included by specifying a directory pathname
2995 or namestring in an @code{:include} directive, e.g.:
2997 (:include "/foo/bar/")
3000 @section Shell-friendly syntax for configuration
3002 When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS}
3003 ASDF will skip to next configuration if it's an empty string.
3004 It will @code{READ} the string as an SEXP in the DSL
3005 if it begins with a paren @code{(}
3006 and it will be interpreted as a list of directories.
3007 Directories should come by pairs, indicating a mapping directive.
3008 Entries are separated
3009 by a @code{:} (colon) on Unix platforms (including cygwin),
3010 by a @code{;} (semicolon) on other platforms (mainly, Windows).
3012 The magic empty entry,
3013 if it comes in what would otherwise be the first entry in a pair,
3014 indicates the splicing of inherited configuration.
3015 If it comes as the second entry in a pair,
3016 it indicates that the directory specified first is to be left untranslated
3017 (which has the same effect as if the directory had been repeated).
3020 @section Semantics of Output Translations
3022 From the specified configuration,
3023 a list of mappings is extracted in a straightforward way:
3024 mappings are collected in order, recursing through
3025 included or inherited configuration as specified.
3026 To this list is prepended some implementation-specific mappings,
3027 and is appended a global default.
3029 The list is then compiled to a mapping table as follows:
3030 for each entry, in order, resolve the first designated directory
3031 into an actual directory pathname for source locations.
3032 If no mapping was specified yet for that location,
3033 resolve the second designated directory to an output location directory
3034 add a mapping to the table mapping the source location to the output location,
3035 and add another mapping from the output location to itself
3036 (unless a mapping already exists for the output location).
3038 Based on the table, a mapping function is defined,
3039 mapping source pathnames to output pathnames:
3040 given a source pathname, locate the longest matching prefix
3041 in the source column of the mapping table.
3042 Replace that prefix by the corresponding output column
3043 in the same row of the table, and return the result.
3044 If no match is found, return the source pathname.
3045 (A global default mapping the filesystem root to itself
3046 may ensure that there will always be a match,
3047 with same fall-through semantics).
3049 @section Caching Results
3051 The implementation is allowed to either eagerly compute the information
3052 from the configurations and file system, or to lazily re-compute it
3053 every time, or to cache any part of it as it goes.
3054 To explicitly flush any information cached by the system, use the API below.
3057 @section Output location API
3059 The specified functions are exported from package ASDF.
3061 @defun initialize-output-translations @&optional PARAMETER
3062 will read the configuration and initialize all internal variables.
3063 You may extend or override configuration
3064 from the environment and configuration files
3065 with the given @var{PARAMETER}, which can be
3066 @code{NIL} (no configuration override),
3067 or a SEXP (in the SEXP DSL),
3068 a string (as in the string DSL),
3069 a pathname (of a file or directory with configuration),
3070 or a symbol (fbound to function that when called returns one of the above).
3073 @defun disable-output-translations
3074 will initialize output translations in a way
3075 that maps every pathname to itself,
3076 effectively disabling the output translation facility.
3079 @defun clear-output-translations
3080 undoes any output translation configuration
3081 and clears any cache for the mapping algorithm.
3082 You might want to call this function
3083 (or better, @code{clear-configuration})
3084 before you dump an image that would be resumed
3085 with a different configuration,
3086 and return an empty configuration.
3087 Note that this does not include clearing information about
3088 systems defined in the current image, only about
3089 where to look for systems not yet defined.
3092 @defun ensure-output-translations @&optional PARAMETER
3093 checks whether output translations have been initialized.
3094 If not, initialize them with the given @var{PARAMETER}.
3095 This function will be called before any attempt to operate on a system.
3098 @defun apply-output-translations PATHNAME
3099 Applies the configured output location translations to @var{PATHNAME}
3100 (calls @code{ensure-output-translations} for the translations).
3103 Every time you use ASDF's @code{output-files}, or
3104 anything that uses it (that may compile, such as @code{operate}, @code{perform}, etc.),
3105 @code{ensure-output-translations} is called with parameter NIL,
3106 which the first time around causes your configuration to be read.
3107 If you change a configuration file,
3108 you need to explicitly @code{initialize-output-translations} again,
3109 or maybe @code{clear-output-translations} (or @code{clear-configuration}),
3110 which will cause the initialization to happen next time around.
3113 @section Credits for output translations
3115 Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations},
3116 and to Peter van Eynde for @code{Common Lisp Controller}.
3118 All bad design ideas and implementation bugs are to mine, not theirs.
3119 But so are good design ideas and elegant implementation tricks.
3121 --- Francois-Rene Rideau @email{fare@@tunes.org}
3123 @c @section Default locations
3124 @c @findex output-files-for-system-and-operation
3126 @c The default binary location for each Lisp implementation
3127 @c is a subdirectory of each source directory.
3128 @c To account for different Lisps, Operating Systems, Implementation versions,
3129 @c and so on, ASDF borrows code from SLIME
3130 @c to create reasonable custom directory names.
3131 @c Here are some examples:
3135 @c SBCL, version 1.0.45 on Mac OS X for Intel: @code{sbcl-1.0.45-darwin-x86}
3138 @c Franz Allegro, version 8.0, ANSI Common Lisp: @code{allegro-8.0a-macosx-x86}
3141 @c Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: @code{allegro-8.1m-macosx-x86}
3144 @c By default, all output file pathnames will be relocated
3145 @c to some thus-named subdirectory of @file{~/.cache/common-lisp/}.
3147 @c See the document @file{README.asdf-output-translations}
3148 @c for a full specification on how to configure @code{asdf-output-translations}.
3150 @node Error handling, Miscellaneous additional functionality, Controlling where ASDF saves compiled files, Top
3151 @comment node-name, next, previous, up
3152 @chapter Error handling
3153 @findex SYSTEM-DEFINITION-ERROR
3154 @findex OPERATION-ERROR
3156 @section ASDF errors
3158 If ASDF detects an incorrect system definition, it will signal a generalised instance of
3159 @code{SYSTEM-DEFINITION-ERROR}.
3161 Operations may go wrong (for example when source files contain errors).
3162 These are signalled using generalised instances of
3163 @code{OPERATION-ERROR}.
3165 @section Compilation error and warning handling
3166 @vindex *compile-file-warnings-behaviour*
3167 @vindex *compile-file-errors-behavior*
3169 ASDF checks for warnings and errors when a file is compiled.
3170 The variables @var{*compile-file-warnings-behaviour*} and
3171 @var{*compile-file-errors-behavior*}
3172 control the handling of any such events.
3173 The valid values for these variables are
3174 @code{:error}, @code{:warn}, and @code{:ignore}.
3176 @node Miscellaneous additional functionality, Getting the latest version, Error handling, Top
3177 @comment node-name, next, previous, up
3178 @chapter Miscellaneous additional functionality
3180 ASDF includes several additional features that are generally
3181 useful for system definition and development.
3183 @section Controlling file compilation
3185 When declaring a component (system, module, file),
3186 you can specify a keyword argument @code{:around-compile function}.
3187 If left unspecified (and therefore unbound),
3188 the value will be inherited from the parent component if any,
3189 or with a default of @code{nil}
3190 if no value is specified in any transitive parent.
3192 The argument must be a either @code{nil}, a fbound symbol,
3193 a lambda-expression (e.g. @code{(lambda (thunk) ...(funcall thunk ...) ...)})
3194 a function object (e.g. using @code{#.#'} but that's discouraged
3195 because it prevents the introspection done by e.g. asdf-dependency-grovel),
3196 or a string that when @code{read} yields a symbol or a lambda-expression.
3197 @code{nil} means the normal compile-file function will be called.
3198 A non-nil value designates a function of one argument
3199 that will be called with a function that will
3200 invoke @code{compile-file*} with various arguments;
3201 the around-compile hook may supply additional keyword arguments
3202 to pass to that call to @code{compile-file*}.
3204 One notable argument that is heeded by @code{compile-file*} is
3205 @code{:compile-check},
3206 a function called when the compilation was otherwise a success,
3207 with the same arguments as @code{compile-file};
3208 the function shall return true if the compilation
3209 and its resulting compiled file respected all system-specific invariants,
3210 and false (@code{nil}) if it broke any of those invariants;
3211 it may issue warnings or errors before it returns @code{nil}.
3212 (NB: The ability to pass such extra flags
3213 is only available starting with ASDF 2.22.3.)
3214 This feature is notably exercised by asdf-finalizers.
3216 By using a string, you may reference
3217 a function, symbol and/or package
3218 that will only be created later during the build, but
3219 isn't yet present at the time the defsystem form is evaluated.
3220 However, if your entire system is using such a hook, you may have to
3221 explicitly override the hook with @code{nil} for all the modules and files
3222 that are compiled before the hook is defined.
3224 Using this hook, you may achieve such effects as:
3225 locally renaming packages,
3226 binding @var{*readtables*} and other syntax-controlling variables,
3227 handling warnings and other conditions,
3228 proclaiming consistent optimization settings,
3229 saving code coverage information,
3230 maintaining meta-data about compilation timings,
3231 setting gensym counters and PRNG seeds and other sources of non-determinism,
3232 overriding the source-location and/or timestamping systems,
3233 checking that some compile-time side-effects were properly balanced,
3236 Note that there is no around-load hook. This is on purpose.
3237 Some implementations such as ECL, GCL or MKCL link object files,
3238 which allows for no such hook.
3239 Other implementations allow for concatenating FASL files,
3240 which doesn't allow for such a hook either.
3241 We aim to discourage something that's not portable,
3242 and has some dubious impact on performance and semantics
3243 even when it is possible.
3244 Things you might want to do with an around-load hook
3245 are better done around-compile,
3246 though it may at times require some creativity
3247 (see e.g. the @code{package-renaming} system).
3250 @section Controlling source file character encoding
3252 Starting with ASDF 2.21, components accept a @code{:encoding} option
3253 so authors may specify which character encoding should be used
3254 to read and evaluate their source code.
3255 When left unspecified, the encoding is inherited
3256 from the parent module or system;
3257 if no encoding is specified at any point,
3258 the default @code{:autodetect} is assumed.
3259 By default, only @code{:default}, @code{:utf-8}
3260 and @code{:autodetect} are accepted.
3261 @code{:autodetect}, the default, calls
3262 @code{*encoding-detection-hook*} which by default always returns
3263 @code{*default-encoding*} which itself defaults to @code{:default}.
3265 In other words, there now are plenty of extension hooks, but
3266 by default ASDF follows the backwards compatible behavior
3267 of using whichever @code{:default} encoding your implementation uses,
3268 which itself may or may not vary based on environment variables
3269 and other locale settings.
3270 In practice this means that only source code that only uses ASCII
3271 is guaranteed to be read the same on all implementations
3272 independently from any user setting.
3274 Additionally, for backward-compatibility with older versions of ASDF
3275 and/or with implementations that do not support unicode and its many encodings,
3277 the reader conditionals @code{#+asdf-unicode #+asdf-unicode}
3278 to protect any @code{:encoding @emph{encoding}} statement
3279 as @code{:asdf-unicode} will be present in @code{*features*}
3280 only if you're using a recent ASDF
3281 on an implementation that supports unicode.
3282 We recommend that you avoid using unprotected @code{:encoding} specifications
3283 until after ASDF 2.21 or later becomes widespread, hopefully by the end of 2012.
3285 While it offers plenty of hooks for extension,
3286 and one such extension is being developed (see below),
3287 ASDF itself only recognizes one encoding beside @code{:default},
3288 and that is @code{:utf-8}, which is the @emph{de facto} standard,
3289 already used by the vast majority of libraries that use more than ASCII.
3290 On implementations that do not support unicode,
3291 the feature @code{:asdf-unicode} is absent, and
3292 the @code{:default} external-format is used
3293 to read even source files declared as @code{:utf-8}.
3294 On these implementations, non-ASCII characters
3295 intended to be read as one CL character
3296 may thus end up being read as multiple CL characters.
3297 In most cases, this shouldn't affect the software's semantics:
3298 comments will be skipped just the same, strings with be read and printed
3299 with slightly different lengths, symbol names will be accordingly longer,
3300 but none of it should matter.
3301 But a few systems that actually depend on unicode characters
3302 may fail to work properly, or may work in a subtly different way.
3303 See for instance @code{lambda-reader}.
3305 We invite you to embrace UTF-8
3306 as the encoding for non-ASCII characters starting today,
3307 even without any explicit specification in your @code{.asd} files.
3308 Indeed, on some implementations and configurations,
3309 UTF-8 is already the @code{:default},
3310 and loading your code may cause errors if it is encoded in anything but UTF-8.
3311 Therefore, even with the legacy behavior,
3312 non-UTF-8 is guaranteed to break for some users,
3313 whereas UTF-8 is pretty much guaranteed not to break anywhere
3314 (provided you do @emph{not} use a BOM),
3315 although it might be read incorrectly on some implementations.
3316 In the future, we intend to make @code{:utf-8}
3317 the default value of @code{*default-encoding*},
3318 to be enforced everywhere, so at least the code is guaranteed
3319 to be read correctly everywhere it can be.
3321 If you need non-standard character encodings for your source code,
3322 use the extension system @code{asdf-encodings}, by specifying
3323 @code{:defsystem-depends-on (:asdf-encodings)} in your @code{defsystem}.
3324 This extension system will register support for more encodings using the
3325 @code{*encoding-external-format-hook*} facility,
3326 so you can explicitly specify @code{:encoding :latin1}
3327 in your @code{.asd} file.
3328 Using the @code{*encoding-detection-hook*} it will also
3329 eventually implement some autodetection of a file's encoding
3330 from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration,
3331 or otherwise based on an analysis of octet patterns in the file.
3332 At this point, asdf-encoding only supports the encodings
3333 that are supported as part of your implementation.
3334 Since the list varies depending on implementations,
3335 we once again recommend you use @code{:utf-8} everywhere,
3336 which is the most portable (next is @code{:latin1}).
3338 If you're not using a version of Quicklisp that has it,
3339 you may get the source for @code{asdf-encodings} using git:
3340 @kbd{git clone git://common-lisp.net/projects/asdf/asdf-encodings.git}
3342 @kbd{git clone ssh://common-lisp.net/project/asdf/git/asdf-encodings.git}.
3343 You can also browse the repository on
3344 @url{http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git}.
3346 In the future, we intend to change the default @code{*default-encoding*}
3347 to @code{:utf-8}, which is already the de facto standard
3348 for most libraries that use non-ASCII characters:
3349 utf-8 works everywhere and was backhandedly enforced by
3350 a lot of people using SBCL and utf-8 and sending reports to authors
3351 so they make their packages compatible.
3352 A survey showed only about a handful few libraries
3353 are incompatible with non-UTF-8, and then, only in comments,
3354 and we believe that authors will adopt UTF-8 when prompted.
3355 See the April 2012 discussion on the asdf-devel mailing-list.
3356 For backwards compatibility with users who insist on a non-UTF-8 encoding,
3357 but cannot immediately transition to using @code{asdf-encodings}
3358 (maybe because it isn't ready), it will still be possible to use
3359 the @code{:encoding :default} option in your @code{defsystem} form
3360 to restore the behavior of ASDF 2.20 and earlier.
3361 This shouldn't be required in libraries,
3362 because user pressure as mentioned above will already have pushed
3363 library authors towards using UTF-8;
3364 but authors of end-user programs might care.
3366 When you use @code{asdf-encodings}, any further loaded @code{.asd} file
3367 will use the autodetection algorithm to determine its encoding;
3368 yet if you depend on this detection happening,
3369 you may want to explicitly load @code{asdf-encodings} early in your build,
3370 for by the time you can use @code{:defsystem-depends-on},
3371 it is already too late to load it.
3372 In practice, this means that the @code{*default-encoding*}
3373 is usually used for @code{.asd} files.
3374 Currently, this defaults to @code{:default} for backwards compatibility,
3375 and that means that you shouldn't rely on non-ASCII characters in a .asd file.
3376 Since component (path)names are the only real data in these files,
3377 and non-ASCII characters are not very portable for file names,
3378 this isn't too much of an issue.
3379 We still encourage you to use either plain ASCII or UTF-8
3380 in @code{.asd} files,
3381 as we intend to make @code{:utf-8} the default encoding in the future.
3382 This might matter, for instance, in meta-data about author's names.
3385 @section Miscellaneous Functions
3387 Most of these functions are not exported by ASDF anymore,
3388 but only used for private purposes of ASDF.
3389 Please use ASDF-UTILS for the same functions exported from a stable library.
3391 @defun coerce-pathname name @&key type defaults
3393 This function (available starting with ASDF 2.012.11)
3394 takes an argument, and portably interprets it as a pathname.
3395 If the argument @var{name} is a pathname or @code{nil}, it is passed through;
3396 if it's a symbol, it's interpreted as a string by downcasing it;
3397 if it's a string, it is first separated using @code{/} into substrings;
3398 the leading substrings denote subdirectories of a relative pathname.
3399 If @var{type} is @code{:directory} or the string ends with @code{/},
3400 the last substring is also a subdirectory;
3401 if @var{type} is a string, it is used as the type of the pathname, and
3402 the last substring is the name component of the pathname;
3403 if @var{type} is @code{nil}, the last substring specifies both name and type components
3404 of the pathname, with the last @code{.} separating them, or only the name component
3405 if there's no last @code{.} or if there is only one dot and it's the first character.
3406 The host, device and version components come from @var{defaults}, which defaults to
3407 @var{*default-pathname-defaults*}; but that shouldn't matter if you use @code{merge-pathnames*}.
3411 @defun merge-pathnames* @&key specified defaults
3413 This function is a replacement for @code{merge-pathnames} that uses the host and device
3414 from the @var{defaults} rather than the @var{specified} pathname when the latter
3415 is a relative pathname. This allows ASDF and its users to create and use relative pathnames
3416 without having to know beforehand what are the host and device
3417 of the absolute pathnames they are relative to.
3421 @defun system-relative-pathname system name @&key type
3423 It's often handy to locate a file relative to some system.
3424 The @code{system-relative-pathname} function meets this need.
3426 It takes two mandatory arguments @var{system} and @var{name}
3427 and a keyword argument @var{type}:
3428 @var{system} is name of a system, whereas @var{name} and optionally @var{type}
3429 specify a relative pathname, interpreted like a component pathname specifier
3430 by @code{coerce-pathname}. @xref{The defsystem grammar,,Pathname specifiers}.
3432 It returns a pathname built from the location of the system's
3433 source directory and the relative pathname. For example:
3436 > (asdf:system-relative-pathname 'cl-ppcre "regex.data")
3437 #P"/repository/other/cl-ppcre/regex.data"
3442 @defun system-source-directory system-designator
3444 ASDF does not provide a turnkey solution for locating
3445 data (or other miscellaneous) files
3446 that are distributed together with the source code of a system.
3447 Programmers can use @code{system-source-directory} to find such files.
3448 Returns a pathname object.
3449 The @var{system-designator} may be a string, symbol, or ASDF system object.
3452 @defun clear-system system-designator
3454 It is sometimes useful to force recompilation of a previously loaded system.
3455 In these cases, it may be useful to @code{(asdf:clear-system :foo)}
3456 to remove the system from the table of currently loaded systems;
3457 the next time the system @code{foo} or one that depends on it is re-loaded,
3458 @code{foo} will then be loaded again.
3459 Alternatively, you could touch @code{foo.asd} or
3460 remove the corresponding fasls from the output file cache.
3461 (It was once conceived that one should provide
3462 a list of systems the recompilation of which to force
3463 as the @code{:force} keyword argument to @code{load-system};
3464 but this has never worked, and though the feature was fixed in ASDF 2.000,
3465 it remains @code{cerror}'ed out as nobody ever used it.)
3467 Note that this does not and cannot by itself undo the previous loading
3468 of the system. Common Lisp has no provision for such an operation,
3469 and its reliance on irreversible side-effects to global datastructures
3470 makes such a thing impossible in the general case.
3471 If the software being re-loaded is not conceived with hot upgrade in mind,
3472 this re-loading may cause many errors, warnings or subtle silent problems,
3473 as packages, generic function signatures, structures, types, macros, constants, etc.
3474 are being redefined incompatibly.
3475 It is up to the user to make sure that reloading is possible and has the desired effect.
3476 In some cases, extreme measures such as recursively deleting packages,
3477 unregistering symbols, defining methods on @code{update-instance-for-redefined-class}
3478 and much more are necessary for reloading to happen smoothly.
3479 ASDF itself goes through notable pains to make such a hot upgrade possible
3480 with respect to its own code, and what it does is ridiculously complex;
3481 look at the beginning of @file{asdf.lisp} to see what it does.
3486 run-program takes a @var{COMMAND} argument that is either
3487 a list of a program path and its arguments,
3488 or a string to be executed by a shell.
3489 It spawns the command, waits for it to return,
3490 verifies that it exited cleanly (unless told not too below),
3491 and optionally captures and processes its output.
3492 It accepts many keyword arguments to configure its behavior.
3494 @code{output} is its most important argument;
3495 it specifies how the output is captured and processed.
3496 If it is @code{nil}, then the output is not captured.
3497 If it is @code{:interactive}, then
3498 input and output are inherited from the current process,
3499 which the subprocess can control until it exits.
3500 Otherwise, the output is captured and redirected to a stream,
3501 and processed by @code{slurp-input-stream} with the object as first argument.
3504 @code{element-type} and @code{external-format} are passed on
3505 to your Lisp implementation, when available, for creation of the output stream.
3507 @code{force-shell} forces evaluation of the command through a shell,
3508 even if it was passed as a list rather than a string.
3510 @code{ignore-error-status} causes @code{run-program}
3511 to not raise an error if the spawned program exits in error.
3512 Following POSIX convention, an error is anything but
3513 a normal exit with status code zero.
3515 run-program works on all platforms supported by ASDF, except Genera.
3519 @defun slurp-input-stream
3521 It's a generic function of two arguments, a target object and an input stream,
3522 and accepting keyword arguments.
3523 Predefined methods based on the target object are as follow:
3525 If the object is a function, the function is called with the stream as argument.
3527 If the object is a cons, its first element is applied to its rest appended by
3528 a list of the input stream.
3530 If the object is an output stream, the contents of the input stream are copied to it.
3531 If the linewise argument is provided, copying happens line by line,
3532 and an optional prefix is printed before each line.
3533 Otherwise, copying happen based on a buffer of size buffer-size,
3534 using the element-type.
3536 If the object is 'string or :string, the content is captured into a string
3537 of the given element-type.
3539 If the object is :lines, the content is captured as a list of strings,
3540 one per line, without line ending. If the count argument is provided,
3541 it is a maximum count of lines to be read.
3543 If the object is :line, the content is capture as with :lines above,
3544 and then its sub-object is extracted with the path argument,
3545 which defaults to 0, extracting the first line.
3546 A number will extract the corresponding line.
3547 See the documentation for asdf-driver:sub-object.
3549 If the object is :forms, the content is captured as a list of S-expressions,
3550 as read by the Lisp reader.
3551 If the count argument is provided,
3552 it is a maximum count of lines to be read.
3553 We recommend you control the syntax with such macro as
3554 asdf-driver:with-safe-io-syntax.
3556 If the object is :form, the content is capture as with :forms above,
3557 and then its sub-object is extracted with the path argument,
3558 which defaults to 0, extracting the first form.
3559 A number will extract the corresponding form.
3560 See the documentation for asdf-driver:sub-object.
3561 We recommend you control the syntax with such macro as
3562 asdf-driver:with-safe-io-syntax.
3566 @defun run-shell-command
3568 This function is obsolete and present only for the sake of backwards-compatibility:
3569 ``If it's not backwards, it's not compatible''. We strongly discourage its use.
3570 Its current behavior is only well-defined on Unix platforms
3571 (which include MacOS X and cygwin). On Windows, anything goes.
3572 The following documentation is only for the purpose of your migrating away from it
3573 in a way that preserves semantics.
3575 Instead we recommend the use @code{run-program} above
3576 available as part of ASDF since ASDF 3.
3578 @code{run-shell-command} takes as arguments a @code{format} control-string
3579 and arguments to be passed to @code{format} after this control-string
3580 to produce a string.
3581 This string is a command that will be evaluated with a POSIX shell if possible;
3582 yet, on Windows, some implementations will use CMD.EXE,
3583 while others (like SBCL) will make an attempt at invoking a POSIX shell
3584 (and fail if it is not present).
3588 @node Getting the latest version, FAQ, Miscellaneous additional functionality, Top
3589 @comment node-name, next, previous, up
3590 @chapter Getting the latest version
3592 Decide which version you want.
3593 The @code{master} branch is where development happens;
3594 its @code{HEAD} is usually OK, including the latest fixes and portability tweaks,
3595 but an occasional regression may happen despite our (limited) test suite.
3597 The @code{release} branch is what cautious people should be using;
3598 it has usually been tested more, and releases are cut at a point
3599 where there isn't any known unresolved issue.
3601 You may get the ASDF source repository using git:
3602 @kbd{git clone git://common-lisp.net/projects/asdf/asdf.git}
3604 You will find the above referenced tags in this repository.
3605 You can also browse the repository on
3606 @url{http://common-lisp.net/gitweb?p=projects/asdf/asdf.git}.
3608 Discussion of ASDF development is conducted on the
3610 @kbd{asdf-devel@@common-lisp.net}.
3611 @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel}
3614 @node FAQ, TODO list, Getting the latest version, Top
3615 @comment node-name, next, previous, up
3618 @section ``Where do I report a bug?''
3620 ASDF bugs are tracked on launchpad: @url{https://launchpad.net/asdf}.
3622 If you're unsure about whether something is a bug, or for general discussion,
3623 use the @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
3626 @section ``What has changed between ASDF 1 and ASDF 2?''
3628 @subsection What are ASDF 1 and ASDF 2?
3630 On May 31st 2010, we have released ASDF 2.
3631 ASDF 2 refers to release 2.000 and later.
3632 (Releases between 1.656 and 1.728 were development releases for ASDF 2.)
3633 ASDF 1 to any release earlier than 1.369 or so.
3634 If your ASDF doesn't sport a version, it's an old ASDF 1.
3636 ASDF 2 and its release candidates push
3637 @code{:asdf2} onto @code{*features*} so that if you are writing
3638 ASDF-dependent code you may check for this feature
3639 to see if the new API is present.
3640 @emph{All} versions of ASDF should have the @code{:asdf} feature.
3642 Additionally, all versions of ASDF 2
3643 define a function @code{(asdf:asdf-version)} you may use to query the version;
3644 and the source code of recent versions of ASDF 2 features the version number
3645 prominently on the second line of its source code.
3647 If you are experiencing problems or limitations of any sort with ASDF 1,
3648 we recommend that you should upgrade to ASDF 2,
3649 or whatever is the latest release.
3652 @subsection ASDF can portably name files in subdirectories
3654 Common Lisp namestrings are not portable,
3655 except maybe for logical pathnamestrings,
3656 that themselves have various limitations and require a lot of setup
3657 that is itself ultimately non-portable.
3659 In ASDF 1, the only portable ways to refer to pathnames inside systems and components
3660 were very awkward, using @code{#.(make-pathname ...)} and
3661 @code{#.(merge-pathnames ...)}.
3662 Even the above were themselves were inadequate in the general case
3663 due to host and device issues, unless horribly complex patterns were used.
3664 Plenty of simple cases that looked portable actually weren't,
3665 leading to much confusion and greavance.
3667 ASDF 2 implements its own portable syntax for strings as pathname specifiers.
3668 Naming files within a system definition becomes easy and portable again.
3669 @xref{Miscellaneous additional functionality,asdf:system-relative-pathname},
3670 @code{merge-pathnames*},
3671 @code{coerce-pathname}.
3673 On the other hand, there are places where systems used to accept namestrings
3674 where you must now use an explicit pathname object:
3675 @code{(defsystem ... :pathname "LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
3676 must now be written with the @code{#p} syntax:
3677 @code{(defsystem ... :pathname #p"LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
3679 @xref{The defsystem grammar,,Pathname specifiers}.
3682 @subsection Output translations
3684 A popular feature added to ASDF was output pathname translation:
3685 @code{asdf-binary-locations}, @code{common-lisp-controller},
3686 @code{cl-launch} and other hacks were all implementing it in ways
3687 both mutually incompatible and difficult to configure.
3689 Output pathname translation is essential to share
3690 source directories of portable systems across multiple implementations
3691 or variants thereof,
3692 or source directories of shared installations of systems across multiple users,
3693 or combinations of the above.
3695 In ASDF 2, a standard mechanism is provided for that,
3696 @code{asdf-output-translations},
3697 with sensible defaults, adequate configuration languages,
3698 a coherent set of configuration files and hooks,
3699 and support for non-Unix platforms.
3701 @xref{Controlling where ASDF saves compiled files}.
3703 @subsection Source Registry Configuration
3705 Configuring ASDF used to require special magic
3706 to be applied just at the right moment,
3707 between the moment ASDF is loaded and the moment it is used,
3708 in a way that is specific to the user,
3709 the implementation he is using and the application he is building.
3711 This made for awkward configuration files and startup scripts
3712 that could not be shared between users, managed by administrators
3713 or packaged by distributions.
3715 ASDF 2 provides a well-documented way to configure ASDF,
3716 with sensible defaults, adequate configuration languages,
3717 and a coherent set of configuration files and hooks.
3719 We believe it's a vast improvement because it decouples
3720 application distribution from library distribution.
3721 The application writer can avoid thinking where the libraries are,
3722 and the library distributor (dpkg, clbuild, advanced user, etc.)
3723 can configure them once and for every application.
3724 Yet settings can be easily overridden where needed,
3725 so whoever needs control has exactly as much as required.
3727 At the same time, ASDF 2 remains compatible
3728 with the old magic you may have in your build scripts
3729 (using @code{*central-registry*} and
3730 @code{*system-definition-search-functions*})
3731 to tailor the ASDF configuration to your build automation needs,
3732 and also allows for new magic, simpler and more powerful magic.
3734 @xref{Controlling where ASDF searches for systems}.
3737 @subsection Usual operations are made easier to the user
3739 In ASDF 1, you had to use the awkward syntax
3740 @code{(asdf:oos 'asdf:load-op :foo)}
3742 and similarly for @code{compile-op}, @code{test-op}.
3744 In ASDF 2, you can use shortcuts for the usual operations:
3745 @code{(asdf:load-system :foo)}, and
3746 similarly for @code{compile-system}, @code{test-system}.
3749 @subsection Many bugs have been fixed
3751 The following issues and many others have been fixed:
3755 The infamous TRAVERSE function has been revamped completely
3756 between ASDF 1 and ASDF 2, with many bugs squashed.
3757 In particular, dependencies were not correctly propagated
3758 across modules but now are.
3759 It has been completely rewritten many times over
3760 between ASDF 2.000 and ASDF 3,
3761 with fundamental issues in the original model being fixed.
3762 Timestamps were not propagated at all, and now are.
3763 The internal model of how actions depend on each other
3764 is now both consistent and complete.
3766 the :force (system1 .. systemN) feature have been fixed.
3769 Performance has been notably improved for large systems
3770 (say with thousands of components) by using
3771 hash-tables instead of linear search,
3772 and linear-time list accumulation
3773 instead of quadratic-time recursive appends.
3776 Many features used to not be portable,
3777 especially where pathnames were involved.
3778 Windows support was notably quirky because of such non-portability.
3781 The internal test suite used to massively fail on many implementations.
3782 While still incomplete, it now fully passes
3783 on all implementations supported by the test suite,
3784 except for GCL (due to GCL bugs).
3787 Support was lacking for some implementations.
3788 ABCL and GCL were notably wholly broken.
3789 ECL extensions were not integrated with ASDF release.
3792 The documentation was grossly out of date.
3797 @subsection ASDF itself is versioned
3799 Between new features, old bugs fixed, and new bugs introduced,
3800 there were various releases of ASDF in the wild,
3801 and no simple way to check which release had which feature set.
3802 People using or writing systems had to either make worst-case assumptions
3803 as to what features were available and worked,
3804 or take great pains to have the correct version of ASDF installed.
3806 With ASDF 2, we provide a new stable set of working features
3807 that everyone can rely on from now on.
3808 Use @code{#+asdf2} to detect presence of ASDF 2,
3809 @code{(asdf:version-satisfies (asdf:asdf-version) "2.345.67")}
3810 to check the availability of a version no earlier than required.
3813 @subsection ASDF can be upgraded
3815 When an old version of ASDF was loaded,
3816 it was very hard to upgrade ASDF in your current image
3817 without breaking everything.
3818 Instead you had to exit the Lisp process and
3819 somehow arrange to start a new one from a simpler image.
3820 Something that can't be done from within Lisp,
3821 making automation of it difficult,
3822 which compounded with difficulty in configuration,
3823 made the task quite hard.
3824 Yet as we saw before, the task would have been required
3825 to not have to live with the worst case or non-portable
3826 subset of ASDF features.
3828 With ASDF 2, it is easy to upgrade
3829 from ASDF 2 to later versions from within Lisp,
3830 and not too hard to upgrade from ASDF 1 to ASDF 2 from within Lisp.
3831 We support hot upgrade of ASDF and any breakage is a bug
3832 that we will do our best to fix.
3833 There are still limitations on upgrade, though,
3834 most notably the fact that after you upgrade ASDF,
3835 you must also reload or upgrade all ASDF extensions.
3837 @subsection Decoupled release cycle
3839 When vendors were releasing their Lisp implementations with ASDF,
3840 they had to basically never change version
3841 because neither upgrade nor downgrade was possible
3842 without breaking something for someone,
3843 and no obvious upgrade path was visible and recommendable.
3845 With ASDF 2, upgrade is possible, easy and can be recommended.
3846 This means that vendors can safely ship a recent version of ASDF,
3847 confident that if a user isn't fully satisfied,
3848 he can easily upgrade ASDF and deal
3849 with a supported recent version of it.
3850 This means that release cycles will be causally decoupled,
3851 the practical consequence of which will mean faster convergence
3852 towards the latest version for everyone.
3855 @subsection Pitfalls of the transition to ASDF 2
3857 The main pitfalls in upgrading to ASDF 2 seem to be related
3858 to the output translation mechanism.
3863 Output translations is enabled by default. This may surprise some users,
3864 most of them in pleasant way (we hope), a few of them in an unpleasant way.
3865 It is trivial to disable output translations.
3866 @xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
3869 Some systems in the large have been known
3870 not to play well with output translations.
3871 They were relatively easy to fix.
3872 Once again, it is also easy to disable output translations,
3873 or to override its configuration.
3876 The new ASDF output translations are incompatible with ASDF-Binary-Locations.
3877 They replace A-B-L, and there is compatibility mode to emulate
3878 your previous A-B-L configuration.
3879 See @code{enable-asdf-binary-locations-compatibility} in
3880 @pxref{Controlling where ASDF saves compiled files,,Backward Compatibility}.
3881 But thou shalt not load ABL on top of ASDF 2.
3885 Other issues include the following:
3890 ASDF pathname designators are now specified
3891 in places where they were unspecified,
3892 and a few small adjustments have to be made to some non-portable defsystems.
3893 Notably, in the @code{:pathname} argument
3894 to a @code{defsystem} and its components,
3895 a logical pathname (or implementation-dependent hierarchical pathname)
3896 must now be specified with @code{#p} syntax
3897 where the namestring might have previously sufficed;
3898 moreover when evaluation is desired @code{#.} must be used,
3899 where it wasn't necessary in the toplevel @code{:pathname} argument
3900 (but necessary in other @code{:pathname} arguments).
3903 There is a slight performance bug, notably on SBCL,
3904 when initially searching for @file{asd} files,
3905 the implicit @code{(directory "/configured/path/**/*.asd")}
3906 for every configured path @code{(:tree "/configured/path/")}
3907 in your @code{source-registry} configuration can cause a slight pause.
3908 Try to @code{(time (asdf:initialize-source-registry))}
3909 to see how bad it is or isn't on your system.
3910 If you insist on not having this pause,
3911 you can avoid the pause by overriding the default source-registry configuration
3912 and not use any deep @code{:tree} entry but only @code{:directory} entries
3913 or shallow @code{:tree} entries.
3914 Or you can fix your implementation to not be quite that slow
3915 when recursing through directories.
3916 @emph{Update}: This performance bug fixed the hard way in 2.010.
3919 On Windows, only LispWorks supports proper default configuration pathnames
3920 based on the Windows registry.
3921 Other implementations make do with environment variables,
3922 that you may have to define yourself
3923 if you're using an older version of Windows.
3924 Windows support is somewhat less tested than Unix support.
3925 Please help report and fix bugs.
3926 @emph{Update}: As of ASDF 2.21, all implementations
3927 should now use the same proper default configuration pathnames
3928 and they should actually work, though they haven't all been tested.
3931 The mechanism by which one customizes a system so that Lisp files
3932 may use a different extension from the default @file{.lisp} has changed.
3933 Previously, the pathname for a component
3934 was lazily computed when operating on a system,
3936 @code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
3937 (declare (ignorable component system)) "lis")}.
3938 Now, the pathname for a component is eagerly computed when defining the system,
3939 and instead you will @code{(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))}
3940 and use @code{:default-component-class cl-source-file.lis}
3941 as argument to @code{defsystem},
3942 as detailed in a @pxref{FAQ,How do I create a system definition where all the source files have a .cl extension?} below.
3944 @findex source-file-type
3950 @section Issues with installing the proper version of ASDF
3952 @subsection ``My Common Lisp implementation comes with an outdated version of ASDF. What to do?''
3954 We recommend you upgrade ASDF.
3955 @xref{Loading ASDF,,Upgrading ASDF}.
3957 If this does not work, it is a bug, and you should report it.
3958 @xref{FAQ, report-bugs, Where do I report a bug}.
3959 In the meantime, you can load @file{asdf.lisp} directly.
3960 @xref{Loading ASDF,Loading an otherwise installed ASDF}.
3963 @subsection ``I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?''
3966 it should always be a good time to upgrade to a recent version of ASDF.
3967 You may consult with the maintainer for which specific version they recommend,
3968 but the latest @code{release} should be correct.
3969 We trust you to thoroughly test it with your implementation
3970 before you release it.
3971 If there are any issues with the current release,
3972 it's a bug that you should report upstream and that we will fix ASAP.
3974 As to how to include ASDF, we recommend the following:
3978 If ASDF isn't loaded yet, then @code{(require "asdf")}
3979 should load the version of ASDF that is bundled with your system.
3980 If possible so should @code{(require "ASDF")}.
3981 You may have it load some other version configured by the user,
3982 if you allow such configuration.
3985 If your system provides a mechanism to hook into @code{CL:REQUIRE},
3986 then it would be nice to add ASDF to this hook the same way that
3987 ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it.
3988 Please send us appropriate code to this end.
3991 You may, like SBCL, have ASDF be implicitly used to require systems
3992 that are bundled with your Lisp distribution.
3993 If you do have a few magic systems that come with your implementation
3994 in a precompiled way such that one should only use the binary version
3995 that goes with your distribution, like SBCL does,
3996 then you should add them in the beginning of @code{wrapping-source-registry}.
3999 If you have magic systems as above, like SBCL does,
4000 then we explicitly ask you to @emph{NOT} distribute
4001 @file{asdf.asd} as part of those magic systems.
4002 You should still include the file @file{asdf.lisp} in your source distribution
4003 and precompile it in your binary distribution,
4004 but @file{asdf.asd} if included at all,
4005 should be secluded from the magic systems,
4006 in a separate file hierarchy.
4007 Alternatively, you may provide the system
4008 after renaming it and its @file{.asd} file to e.g.
4009 @code{asdf-ecl} and @file{asdf-ecl.asd}, or
4010 @code{sb-asdf} and @file{sb-asdf.asd}.
4011 Indeed, if you made @file{asdf.asd} a magic system,
4012 then users would no longer be able to upgrade ASDF using ASDF itself
4013 to some version of their preference that
4014 they maintain independently from your Lisp distribution.
4017 If you do not have any such magic systems, or have other non-magic systems
4018 that you want to bundle with your implementation,
4019 then you may add them to the @code{wrapping-source-registry},
4020 and you are welcome to include @file{asdf.asd} amongst them.
4021 Non-magic systems should be at the back of the @code{wrapping-source-registry}
4022 while magic systems are at the front.
4025 Please send us upstream any patches you make to ASDF itself,
4026 so we can merge them back in for the benefit of your users
4027 when they upgrade to the upstream version.
4033 @section Issues with configuring ASDF
4035 @subsection ``How can I customize where fasl files are stored?''
4037 @xref{Controlling where ASDF saves compiled files}.
4039 Note that in the past there was an add-on to ASDF called
4040 @code{ASDF-binary-locations}, developed by Gary King.
4041 That add-on has been merged into ASDF proper,
4042 then superseded by the @code{asdf-output-translations} facility.
4044 Note that use of @code{asdf-output-translations}
4045 can interfere with one aspect of your systems
4046 --- if your system uses @code{*load-truename*} to find files
4047 (e.g., if you have some data files stored with your program),
4048 then the relocation that this ASDF customization performs
4049 is likely to interfere.
4050 Use @code{asdf:system-relative-pathname} to locate a file
4051 in the source directory of some system, and
4052 use @code{asdf:apply-output-translations} to locate a file
4053 whose pathname has been translated by the facility.
4055 @subsection ``How can I wholly disable the compiler output cache?''
4057 To permanently disable the compiler output cache
4058 for all future runs of ASDF, you can:
4061 mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/
4062 echo ':disable-cache' > ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
4065 This assumes that you didn't otherwise configure the ASDF files
4066 (if you did, edit them again),
4067 and don't somehow override the configuration at runtime
4068 with a shell variable (see below) or some other runtime command
4069 (e.g. some call to @code{asdf:initialize-output-translations}).
4071 To disable the compiler output cache in Lisp processes
4072 run by your current shell, try (assuming @code{bash} or @code{zsh})
4073 (on Unix and cygwin only):
4076 export ASDF_OUTPUT_TRANSLATIONS=/:
4079 To disable the compiler output cache just in the current Lisp process,
4080 use (after loading ASDF but before using it):
4083 (asdf:disable-output-translations)
4086 @section Issues with using and extending ASDF to define systems
4088 @subsection ``How can I cater for unit-testing in my system?''
4090 ASDF provides a predefined test operation, @code{test-op}.
4091 @xref{Predefined operations of ASDF, test-op}.
4092 The test operation, however, is largely left to the system definer to specify.
4093 @code{test-op} has been
4094 a topic of considerable discussion on the
4095 @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list},
4097 @url{https://launchpad.net/asdf,launchpad bug-tracker}.
4099 Here are some guidelines:
4103 For a given system, @var{foo}, you will want to define a corresponding
4104 test system, such as @var{foo-test}. The reason that you will want this
4105 separate system is that ASDF does not out of the box supply components
4106 that are conditionally loaded. So if you want to have source files
4107 (with the test definitions) that will not be loaded except when testing,
4108 they should be put elsewhere.
4111 The @var{foo-test} system can be defined in an asd file of its own or
4112 together with @var{foo}. An aesthetic preference against cluttering up
4113 the filesystem with extra asd files should be balanced against the
4114 question of whether one might want to directly load @var{foo-test}.
4115 Typically one would not want to do this except in early stages of
4119 Record that testing is implemented by @var{foo-test}. For example:
4121 (defsystem @var{foo}
4122 :in-order-to ((test-op (test-op @var{foo-test})))
4125 (defsystem @var{foo-test}
4126 :depends-on (@var{foo} @var{my-test-library} ...)
4131 This procedure will allow you to support users who do not wish to
4132 install your test framework.
4134 One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
4135 does not return a value. So in current versions of ASDF there is no
4136 reliable programmatic means of determining whether or not a set of tests
4137 has passed, or which tests have failed. The user must simply read the
4138 console output. This limitation has been the subject of much
4141 @subsection ``How can I cater for documentation generation in my system?''
4143 The ASDF developers are currently working to add a @code{doc-op}
4144 to the set of predefined ASDF operations.
4145 @xref{Predefined operations of ASDF}.
4146 See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
4150 @subsection ``How can I maintain non-Lisp (e.g. C) source files?''
4152 See @code{cffi}'s @code{cffi-grovel}.
4154 @anchor{report-bugs}
4157 @subsection ``I want to put my module's files at the top level. How do I do this?''
4159 By default, the files contained in an asdf module go
4160 in a subdirectory with the same name as the module.
4161 However, this can be overridden by adding a @code{:pathname ""} argument
4162 to the module description.
4163 For example, here is how it could be done
4164 in the spatial-trees ASDF system definition for ASDF 2:
4167 (asdf:defsystem :spatial-trees
4173 (:file "basedefs" :depends-on ("package"))
4174 (:file "rectangles" :depends-on ("package"))))
4180 (:file "greene-trees" :depends-on ("r-trees"))
4181 (:file "rstar-trees" :depends-on ("r-trees"))
4182 (:file "rplus-trees" :depends-on ("r-trees"))
4183 (:file "x-trees" :depends-on ("r-trees" "rstar-trees"))))
4188 ((:static-file "spatial-tree-viz.lisp")))
4193 ((:static-file "spatial-tree-test.lisp")))
4194 (:static-file "LICENCE")
4195 (:static-file "TODO")))
4198 All of the files in the @code{tree-impls} module are at the top level,
4199 instead of in a @file{tree-impls/} subdirectory.
4201 Note that the argument to @code{:pathname} can be either a pathname object or a string.
4202 A pathname object can be constructed with the @file{#p"foo/bar/"} syntax,
4203 but this is discouraged because the results of parsing a namestring are not portable.
4204 A pathname can only be portably constructed with such syntax as
4205 @code{#.(make-pathname :directory '(:relative "foo" "bar"))},
4206 and similarly the current directory can only be portably specified as
4207 @code{#.(make-pathname :directory '(:relative))}.
4208 However, as of ASDF 2, you can portably use a string to denote a pathname.
4209 The string will be parsed as a @code{/}-separated path from the current directory,
4210 such that the empty string @code{""} denotes the current directory, and
4211 @code{"foo/bar"} (no trailing @code{/} required in the case of modules)
4212 portably denotes the same subdirectory as above.
4213 When files are specified, the last @code{/}-separated component is interpreted
4214 either as the name component of a pathname
4215 (if the component class specifies a pathname type),
4216 or as a name component plus optional dot-separated type component
4217 (if the component class doesn't specifies a pathname type).
4219 @subsection How do I create a system definition where all the source files have a .cl extension?
4221 Starting with ASDF 2.014.14, you may just pass
4222 the builtin class @code{cl-source-file.cl} as
4223 the @code{:default-component-class} argument to @code{defsystem}:
4226 (defsystem my-cl-system
4227 :default-component-class cl-source-file.cl
4231 Another builtin class @code{cl-source-file.lsp} is offered
4232 for files ending in @file{.lsp}.
4234 If you want to use a different extension
4235 for which ASDF doesn't provide builtin support,
4236 or want to support versions of ASDF
4237 earlier than 2.014.14 (but later than 2.000),
4238 you can define a class as follows:
4241 ;; Prologue: make sure we're using a sane package.
4242 (defpackage :my-asdf-extension
4243 (:use :asdf :common-lisp)
4244 (:export #:cl-source-file.lis))
4245 (in-package :my-asdf-extension)
4247 (defclass cl-source-file.lis (cl-source-file)
4248 ((type :initform "lis")))
4251 Then you can use it as follows:
4253 (defsystem my-cl-system
4254 :default-component-class my-asdf-extension:cl-source-file.lis
4258 Of course, if you're in the same package, e.g. in the same file,
4259 you won't need to use the package qualifier before @code{cl-source-file.lis}.
4260 Actually, if all you're doing is defining this class
4261 and using it in the same file without other fancy definitions,
4262 you might skip package complications:
4266 (defclass cl-source-file.lis (cl-source-file)
4267 ((type :initform "lis")))
4268 (defsystem my-cl-system
4269 :default-component-class cl-source-file.lis
4273 It is possible to achieve the same effect
4274 in a way that supports both ASDF 1 and ASDF 2,
4275 but really, friends don't let friends use ASDF 1.
4276 Please upgrade to ASDF 3.
4277 In short, though: do same as above, but
4278 @emph{before} you use the class in a @code{defsystem},
4279 you also define the following method:
4282 (defmethod source-file-type ((f cl-source-file.lis) (s system))
4283 (declare (ignorable f s))
4287 @comment FIXME: Add a FAQ about how to use a new system class...
4290 @node TODO list, Inspiration, FAQ, Top
4291 @comment node-name, next, previous, up
4294 Here is an old list of things to do,
4295 in addition to the bugs that are now tracked on launchpad:
4296 @url{https://launchpad.net/asdf}.
4298 @section Outstanding spec questions, things to add
4300 ** packaging systems
4302 *** manual page component?
4304 ** style guide for .asd files
4306 You should either use keywords or be careful
4307 with the package that you evaluate defsystem forms in.
4308 Otherwise @code{(defsystem partition ...)}
4309 being read in the @code{cl-user} package
4310 will intern a @code{cl-user:partition} symbol,
4311 which will then collide with the @code{partition:partition} symbol.
4313 Actually there's a hairier packages problem to think about too.
4314 @code{in-order-to} is not a keyword:
4315 if you read @code{defsystem} forms in a package that doesn't use ASDF,
4316 odd things might happen.
4319 ** extending defsystem with new options
4321 You might not want to write a whole parser,
4322 but just to add options to the existing syntax.
4323 Reinstate @code{parse-option} or something akin.
4328 A ``dry run'' of an operation can be made with the following form:
4331 (let ((asdf::*verbose-out* *standard-output*))
4332 (loop :for (op . comp) :in
4333 (asdf::traverse (make-instance '<operation-name> :force t)
4334 (asdf:find-system <system-name>))
4335 :do (asdf:explain op comp)))
4338 This uses unexported symbols.
4339 What would be a nice interface for this functionality?
4341 @section Missing bits in implementation
4343 ** reuse the same scratch package whenever a system is reloaded from disk
4345 Have a package ASDF-USER instead of all these temporary packages?
4347 ** proclamations probably aren't
4349 ** A revert function
4351 Other possible interface: have a ``revert'' function akin to @code{make clean}.
4354 (asdf:revert 'asdf:compile-op 'araneida)
4357 would delete any files produced by @code{(compile-system :araneida)}.
4358 Of course, it wouldn't be able to do much about stuff in the image itself.
4360 How would this work?
4364 There's a difference between a module's dependencies (peers)
4365 and its components (children).
4366 Perhaps there's a similar difference in operations?
4367 For example, @code{(load "use") depends-on (load "macros")} is a peer,
4368 whereas @code{(load "use") depends-on (compile "use")}
4369 is more of a ``subservient'' relationship.
4371 @node Inspiration, Concept Index, TODO list, Top
4372 @comment node-name, next, previous, up
4373 @chapter Inspiration
4375 @section mk-defsystem (defsystem-3.x)
4377 We aim to solve basically the same problems as @code{mk-defsystem} does.
4378 However, our architecture for extensibility
4379 better exploits CL language features (and is documented),
4380 and we intend to be portable rather than just widely-ported.
4381 No slight on the @code{mk-defsystem} authors and maintainers is intended here;
4382 that implementation has the unenviable task
4383 of supporting pre-ANSI implementations, which is no longer necessary.
4385 The surface defsystem syntax of asdf is more-or-less compatible with
4386 @code{mk-defsystem}, except that we do not support
4387 the @code{source-foo} and @code{binary-foo} prefixes
4388 for separating source and binary files, and
4389 we advise the removal of all options to specify pathnames.
4391 The @code{mk-defsystem} code for topologically sorting
4392 a module's dependency list was very useful.
4394 @section defsystem-4 proposal
4396 Marco and Peter's proposal for defsystem 4 served as the driver for
4397 many of the features in here. Notable differences are:
4401 We don't specify output files or output file extensions
4402 as part of the system.
4404 If you want to find out what files an operation would create,
4408 We don't deal with CL packages
4410 If you want to compile in a particular package, use an @code{in-package} form
4411 in that file (ilisp / SLIME will like you more if you do this anyway)
4414 There is no proposal here that @code{defsystem} does version control.
4416 A system has a given version which can be used to check dependencies,
4420 The defsystem 4 proposal tends to look more at the external features,
4421 whereas this one centres on a protocol for system introspection.
4423 @section kmp's ``The Description of Large Systems'', MIT AI Memo 801
4425 Available in updated-for-CL form on the web at
4426 @url{http://nhplace.com/kent/Papers/Large-Systems.html}
4428 In our implementation we borrow kmp's overall @code{PROCESS-OPTIONS}
4429 and concept to deal with creating component trees
4430 from @code{defsystem} surface syntax.
4431 [ this is not true right now, though it used to be and
4432 probably will be again soon ]
4435 @c -------------------
4438 @node Concept Index, Function and Class Index, Inspiration, Top
4439 @unnumbered Concept Index
4443 @node Function and Class Index, Variable Index, Concept Index, Top
4444 @unnumbered Function and Class Index
4448 @node Variable Index, , Function and Class Index, Top
4449 @unnumbered Variable Index