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

Last change on this file since 12986 was 12986, checked in by Mark Evenson, 11 years ago

Upgrade to ASDF-2.010.1.

File size: 125.0 KB
Line 
1\input texinfo          @c -*- texinfo -*-
2@c %**start of header
3@setfilename asdf.info
4@settitle ASDF Manual
5@c %**end of header
6
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
10&allow-other-keys
11@end macro
12@macro &optional
13&optional
14@end macro
15@macro &rest
16&rest
17@end macro
18@macro &key
19&key
20@end macro
21@macro &body
22&body
23@end macro
24
25@c for install-info
26@dircategory Software development
27@direntry
28* asdf: (asdf).           Another System Definition Facility (for Common Lisp)
29@end direntry
30
31@copying
32This manual describes ASDF, a system definition facility
33for Common Lisp programs and libraries.
34
35You can find the latest version of this manual at
36@url{http://common-lisp.net/project/asdf/asdf.html}.
37
38ASDF Copyright @copyright{} 2001-2010 Daniel Barlow and contributors.
39
40This manual Copyright @copyright{} 2001-2010 Daniel Barlow and contributors.
41
42This manual revised @copyright{} 2009-2010 Robert P. Goldman and Francois-Rene Rideau.
43
44Permission is hereby granted, free of charge, to any person obtaining
45a copy of this software and associated documentation files (the
46``Software''), to deal in the Software without restriction, including
47without limitation the rights to use, copy, modify, merge, publish,
48distribute, sublicense, and/or sell copies of the Software, and to
49permit persons to whom the Software is furnished to do so, subject to
50the following conditions:
51
52The above copyright notice and this permission notice shall be
53included in all copies or substantial portions of the Software.
54
55THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
56EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
57MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
58NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
59LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
60OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
61WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
62
63@end copying
64
65
66
67@titlepage
68@title ASDF: Another System Definition Facility
69
70@c The following two commands start the copyright page.
71@page
72@vskip 0pt plus 1filll
73@insertcopying
74@end titlepage
75
76@c Output the table of contents at the beginning.
77@contents
78
79@c -------------------
80
81@ifnottex
82
83@node Top, Introduction, (dir), (dir)
84@top asdf: another system definition facility
85
86@insertcopying
87
88@menu
89* Introduction::
90* Loading ASDF::
91* Configuring ASDF::
92* Using ASDF::
93* Defining systems with defsystem::
94* The object model of ASDF::
95* Controlling where ASDF searches for systems::
96* Controlling where ASDF saves compiled files::
97* Error handling::
98* Miscellaneous additional functionality::
99* Getting the latest version::
100* FAQ::
101* TODO list::
102* Inspiration::
103* Concept Index::
104* Function and Class Index::
105* Variable Index::
106
107@c @detailmenu
108@c  --- The Detailed Node Listing ---
109
110@c Defining systems with defsystem
111
112@c * The defsystem form::
113@c * A more involved example::
114@c * The defsystem grammar::
115@c * Other code in .asd files::
116
117@c The object model of ASDF
118
119@c * Operations::
120@c * Components::
121
122@c Operations
123
124@c * Predefined operations of ASDF::
125@c * Creating new operations::
126
127@c Components
128
129@c * Common attributes of components::
130@c * Pre-defined subclasses of component::
131@c * Creating new component types::
132
133@c properties
134
135@c * Pre-defined subclasses of component::
136@c * Creating new component types::
137
138@c @end detailmenu
139@end menu
140
141@end ifnottex
142
143@c -------------------
144
145@node Introduction, Loading ASDF, Top, Top
146@comment  node-name,  next,  previous,  up
147@chapter Introduction
148@cindex ASDF-related features
149@vindex *features*
150@cindex Testing for ASDF
151@cindex ASDF versions
152@cindex :asdf
153@cindex :asdf2
154
155ASDF is Another System Definition Facility:
156a tool for specifying how systems of Common Lisp software
157are comprised of components (sub-systems and files),
158and how to operate on these components in the right order
159so that they can be compiled, loaded, tested, etc.
160
161ASDF presents three faces:
162one for users of Common Lisp software who want to reuse other people's code,
163one for writers of Common Lisp software who want to specify how to build their systems,
164one for implementers of Common Lisp extensions who want to extend the build system.
165@xref{Using ASDF,,Loading a system},
166to learn how to use ASDF to load a system.
167@xref{Defining systems with defsystem},
168to learn how to define a system of your own.
169@xref{The object model of ASDF}, for a description of
170the ASDF internals and how to extend ASDF.
171
172@emph{Nota Bene}:
173We have released ASDF 2.000 on May 31st 2010.
174It hopefully will have been it included
175in all CL maintained implementations shortly afterwards.
176@xref{FAQ,,``What has changed between ASDF 1 and ASDF 2?''}.
177
178
179@node Loading ASDF, Configuring ASDF, Introduction, Top
180@comment  node-name,  next,  previous,  up
181@chapter Loading ASDF
182@vindex *central-registry*
183@cindex link farm
184@findex load-system
185@findex compile-system
186@findex test-system
187@cindex system directory designator
188@findex operate
189@findex oos
190
191@c @menu
192@c * Installing ASDF::
193@c @end menu
194
195
196@section Loading a pre-installed ASDF
197
198Many Lisp implementations include a copy of ASDF.
199You can usually load this copy using Common Lisp's @code{require} function:
200
201@lisp
202(require :asdf)
203@end lisp
204
205Consult your Lisp implementation's documentation for details.
206
207Hopefully, ASDF 2 will soon be bundled with every Common Lisp implementation,
208and you can load it that way.
209If it is not, see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below.
210if you are using the latest version of your Lisp vendor's software,
211you may also send a bug report to your Lisp vendor and complain about
212their failing to provide ASDF.
213
214@section Checking whether ASDF is loaded
215
216To check whether ASDF is properly loaded in your current Lisp image,
217you can run this form:
218
219@lisp
220(asdf:asdf-version)
221@end lisp
222
223If it returns a string,
224that is the version of ASDF that is currently installed.
225
226If it raises an error,
227then either ASDF is not loaded, or
228you are using an old version of ASDF.
229
230You can check whether an old version is loaded
231by checking if the ASDF package is present.
232The form below will allow you to programmatically determine
233whether a recent version is loaded, an old version is loaded,
234or none at all:
235
236@lisp
237(or #+asdf2 (asdf:asdf-version) #+asdf :old)
238@end lisp
239
240If it returns a version number, that's the version of ASDF installed.
241If it returns the keyword @code{:OLD},
242then you're using an old version of ASDF (from before 1.635).
243If it returns @code{NIL} then ASDF is not installed.
244
245If you are running a version older than 2.008,
246we recommend that you load a newer ASDF using the method below.
247
248
249@section Upgrading ASDF
250
251If your implementation does provide ASDF 2 or later,
252and you want to upgrade to a more recent version,
253just install ASDF like any other package
254(see @pxref{Loading ASDF,,Loading an otherwise installed ASDF} below),
255configure ASDF as usual (see @pxref{Configuring ASDF} below),
256and upgrade with:
257
258@lisp
259(require :asdf)
260(asdf:load-system :asdf)
261@end lisp
262
263If on the other hand, your implementation only provides an old ASDF,
264you will require a special configuration step and an old-style loading:
265
266@lisp
267(require :asdf)
268(push #p"@var{/path/to/new/asdf/}" asdf:*central-registry*)
269(asdf:oos 'asdf:load-op :asdf)
270@end lisp
271
272Don't forget the trailing @code{/} at the end of your pathname.
273
274Also, note that older versions of ASDF won't redirect their output,
275or at least won't do it according to your usual ASDF 2 configuration.
276You therefore need write access on the directory
277where you install the new ASDF,
278and make sure you're not using it
279for multiple mutually incompatible implementations.
280At worst, you may have to have multiple copies of the new ASDF,
281e.g. one per implementation installation, to avoid clashes.
282
283Finally, note that there are some limitations to upgrading ASDF:
284@itemize
285@item
286Any ASDF extension is invalidated, and will need to be reloaded.
287@item
288It is safer if you upgrade ASDF and its extensions as a special step
289at the very beginning of whatever script you are running,
290before you start using ASDF to load anything else.
291@end itemize
292
293
294@section Loading an otherwise installed ASDF
295
296If your implementation doesn't include ASDF,
297if for some reason the upgrade somehow fails,
298does not or cannot apply to your case,
299you will have to install the file @file{asdf.lisp}
300somewhere and load it with:
301
302@lisp
303(load "/path/to/your/installed/asdf.lisp")
304@end lisp
305
306The single file @file{asdf.lisp} is all you normally need to use ASDF.
307
308You can extract this file from latest release tarball on the
309@url{http://common-lisp.net/project/asdf/,ASDF website}.
310If you are daring and willing to report bugs, you can get
311the latest and greatest version of ASDF from its git repository.
312@xref{Getting the latest version}.
313
314For maximum convenience you might want to have ASDF loaded
315whenever you start your Lisp implementation,
316for example by loading it from the startup script or dumping a custom core
317--- check your Lisp implementation's manual for details.
318
319
320@node Configuring ASDF, Using ASDF, Loading ASDF, Top
321@comment  node-name,  next,  previous,  up
322
323@chapter Configuring ASDF
324
325@section Configuring ASDF to find your systems
326
327So it may compile and load your systems, ASDF must be configured to find
328the @file{.asd} files that contain system definitions.
329
330Since ASDF 2, the preferred way to configure where ASDF finds your systems is
331the @code{source-registry} facility,
332fully described in its own chapter of this manual.
333@xref{Controlling where ASDF searches for systems}.
334
335The default location for a user to install Common Lisp software is under
336@file{~/.local/share/common-lisp/source/}.
337If you install software there, you don't need further configuration.
338If you're installing software yourself at a location that isn't standard,
339you have to tell ASDF where you installed it. See below.
340If you're using some tool to install software,
341the authors of that tool should already have configured ASDF.
342
343The simplest way to add a path to your search path,
344say @file{/home/luser/.asd-link-farm/}
345is to create the directory
346@file{~/.config/common-lisp/source-registry.conf.d/}
347and there create a file with any name of your choice but the type @file{conf},
348for instance @file{42-asd-link-farm.conf}
349containing the line:
350
351@kbd{(:directory "/home/luser/.asd-link-farm/")}
352
353If you want all the subdirectories under @file{/home/luser/lisp/}
354to be recursively scanned for @file{.asd} files, instead use:
355
356@kbd{(:tree "/home/luser/lisp/")}
357
358Note that your Operating System distribution or your system administrator
359may already have configured system-managed libraries for you.
360
361The required @file{.conf} extension allows you to have disabled files
362or editor backups (ending in @file{~}), and works portably
363(for instance, it is a pain to allow both empty and non-empty extension on CLISP).
364Excluded are files the name of which start with a @file{.} character.
365It is customary to start the filename with two digits
366that specify the order in which the directories will be scanned.
367
368ASDF will automatically read your configuration
369the first time you try to find a system.
370You can reset the source-registry configuration with:
371
372@lisp
373(asdf:clear-source-registry)
374@end lisp
375
376And you probably should do so before you dump your Lisp image,
377if the configuration may change
378between the machine where you save it at the time you save it
379and the machine you resume it at the time you resume it.
380
381
382@section Configuring ASDF to find your systems -- old style
383
384The old way to configure ASDF to find your systems is by
385@code{push}ing directory pathnames onto the variable
386@code{asdf:*central-registry*}.
387
388You must configure this variable between the time you load ASDF
389and the time you first try to use it.
390Loading and configuring ASDF presumably happen
391as part of some initialization script that builds or starts
392your Common Lisp software system.
393(For instance, some SBCL users used to put it in their @file{~/.sbclrc}.)
394
395The @code{asdf:*central-registry*} is empty by default in ASDF 2,
396but is still supported for compatibility with ASDF 1.
397When used, it takes precedence over the above source-registry@footnote{
398It is possible to further customize
399the system definition file search.
400That's considered advanced use, and covered later:
401search forward for
402@code{*system-definition-search-functions*}.
403@xref{Defining systems with defsystem}.}.
404
405For instance, if you wanted ASDF to find the @file{.asd} file
406@file{/home/me/src/foo/foo.asd} your initialization script
407could after it loads ASDF with @code{(require :asdf)}
408configure it with:
409
410@lisp
411(push "/home/me/src/foo/" asdf:*central-registry*)
412@end lisp
413
414Note the trailing slash: when searching for a system,
415ASDF will evaluate each entry of the central registry
416and coerce the result to a pathname@footnote{
417ASDF will indeed call @code{EVAL} on each entry.
418It will also skip entries that evaluate to @code{NIL}.
419
420Strings and pathname objects are self-evaluating,
421in which case the @code{EVAL} step does nothing;
422but you may push arbitrary SEXP onto the central registry,
423that will be evaluated to compute e.g. things that depend
424on the value of shell variables or the identity of the user.
425
426The variable @code{asdf:*central-registry*} is thus a list of
427``system directory designators''.
428A @dfn{system directory designator} is a form
429which will be evaluated whenever a system is to be found,
430and must evaluate to a directory to look in.
431By ``directory'' here, we mean
432``designator for a pathname with a supplied DIRECTORY component''.
433}
434at which point the presence of the trailing directory name separator
435is necessary to tell Lisp that you're discussing a directory
436rather than a file.
437
438Typically, however, there are a lot of @file{.asd} files, and
439a common idiom was to have to put
440a bunch of @emph{symbolic links} to @file{.asd} files
441in a common directory
442and push @emph{that} directory (the ``link farm'')
443to the
444@code{asdf:*central-registry*}
445instead of pushing each of the many involved directories
446to the @code{asdf:*central-registry*}.
447ASDF knows how to follow such @emph{symlinks}
448to the actual file location when resolving the paths of system components
449(on Windows, you can use Windows shortcuts instead of POSIX symlinks).
450
451For example, if @code{#p"/home/me/cl/systems/"} (note the trailing slash)
452is a member of @code{*central-registry*}, you could set up the
453system @var{foo} for loading with asdf with the following
454commands at the shell:
455
456@example
457$ cd /home/me/cl/systems/
458$ ln -s ~/src/foo/foo.asd .
459@end example
460
461This old style for configuring ASDF is not recommended for new users,
462but it is supported for old users, and for users who want to programmatically
463control what directories are added to the ASDF search path.
464
465
466@section Configuring where ASDF stores object files
467@findex clear-output-locations
468
469ASDF lets you configure where object files will be stored.
470Sensible defaults are provided and
471you shouldn't normally have to worry about it.
472
473This allows the same source code repository may be shared
474between several versions of several Common Lisp implementations,
475between several users using different compilation options
476and without write privileges on shared source directories, etc.
477This also allows to keep source directories uncluttered
478by plenty of object files.
479
480Starting with ASDF 2, the @code{asdf-output-translations} facility
481was added to ASDF itself, that controls where object files will be stored.
482This facility is fully described in a chapter of this manual,
483@ref{Controlling where ASDF saves compiled files}.
484
485The simplest way to add a translation to your search path,
486say from @file{/foo/bar/baz/quux/}
487to @file{/where/i/want/my/fasls/}
488is to create the directory
489@file{~/.config/common-lisp/asdf-output-translations.conf.d/}
490and there create a file with any name of your choice and the type @file{conf},
491for instance @file{42-bazquux.conf}
492containing the line:
493
494@kbd{("/foo/bar/baz/quux/" "/where/i/want/my/fasls/")}
495
496To disable output translations for source under a given directory,
497say @file{/toto/tata/}
498you can create a file @file{40-disable-toto.conf}
499with the line:
500
501@kbd{("/toto/tata/")}
502
503To wholly disable output translations for all directories,
504you can create a file @file{00-disable.conf}
505with the line:
506
507@kbd{(t t)}
508
509Note that your Operating System distribution or your system administrator
510may already have configured translations for you.
511In absence of any configuration, the default is to redirect everything
512under an implementation-dependent subdirectory of @file{~/.cache/common-lisp/}.
513@xref{Controlling where ASDF searches for systems}, for full details.
514
515The required @file{.conf} extension allows you to have disabled files
516or editor backups (ending in @file{~}), and works portably
517(for instance, it is a pain to allow both empty and non-empty extension on CLISP).
518Excluded are files the name of which start with a @file{.} character.
519It is customary to start the filename with two digits
520that specify the order in which the directories will be scanned.
521
522ASDF will automatically read your configuration
523the first time you try to find a system.
524You can reset the source-registry configuration with:
525
526@lisp
527(asdf:clear-output-translations)
528@end lisp
529
530And you probably should do so before you dump your Lisp image,
531if the configuration may change
532between the machine where you save it at the time you save it
533and the machine you resume it at the time you resume it.
534
535Finally note that before ASDF 2,
536other ASDF add-ons offered the same functionality,
537each in subtly different and incompatible ways:
538ASDF-Binary-Locations, cl-launch, common-lisp-controller.
539ASDF-Binary-Locations is now not needed anymore and should not be used.
540cl-launch 3.000 and common-lisp-controller 7.2 have been updated
541to just delegate this functionality to ASDF.
542
543@node Using ASDF, Defining systems with defsystem, Configuring ASDF, Top
544@comment  node-name,  next,  previous,  up
545
546@chapter Using ASDF
547
548@section Loading a system
549
550The system @var{foo} is loaded (and compiled, if necessary)
551by evaluating the following Lisp form:
552
553@example
554(asdf:load-system :@var{foo})
555@end example
556
557On some implementations (namely recent versions of
558ABCL, Clozure CL, CLISP, CMUCL, ECL, SBCL and SCL),
559ASDF hooks into the @code{CL:REQUIRE} facility
560and you can just use:
561
562@example
563(require :@var{foo})
564@end example
565
566In older versions of ASDF, you needed to use
567@code{(asdf:oos 'asdf:load-op :@var{foo})}.
568If your ASDF is too old to provide @code{asdf:load-system} though
569we recommend that you upgrade to ASDF 2.
570@xref{Loading ASDF,,Loading an otherwise installed ASDF}.
571
572Note the name of a system is specified as a string or a symbol,
573typically a keyword.
574If a symbol (including a keyword), its name is taken and lowercased.
575The name must be a suitable value for the @code{:name} initarg
576to @code{make-pathname} in whatever filesystem the system is to be found.
577The lower-casing-symbols behaviour is unconventional,
578but was selected after some consideration.
579Observations suggest that the type of systems we want to support
580either have lowercase as customary case (unix, mac, windows)
581or silently convert lowercase to uppercase (lpns),
582so this makes more sense than attempting to use @code{:case :common},
583which is reported not to work on some implementations
584
585
586@section Other Operations
587
588ASDF provides three commands for the most common system operations:
589@code{load-system}, @code{compile-system} or @code{test-system}.
590
591Because ASDF is an extensible system
592for defining @emph{operations} on @emph{components},
593it also provides a generic function @code{operate}
594(which is usually abbreviated by @code{oos}).
595You'll use @code{oos} whenever you want to do something beyond
596compiling, loading and testing.
597
598Output from ASDF and ASDF extensions are supposed to be sent
599to the CL stream @code{*standard-output*},
600and so rebinding that stream around calls to @code{asdf:operate}
601should redirect all output from ASDF operations.
602
603Reminder: before ASDF can operate on a system, however,
604it must be able to find and load that system's definition.
605@xref{Configuring ASDF,,Configuring ASDF to find your systems}.
606
607
608@section Summary
609
610To use ASDF:
611
612@itemize
613@item
614Load ASDF itself into your Lisp image, either through
615@code{(require :asdf)} or else through
616@code{(load "/path/to/asdf.lisp")}.
617
618@item
619Make sure ASDF can find system definitions
620thanks to proper source-registry configuration.
621
622@item
623Load a system with @code{(load-system :my-system)}
624or use some other operation on some system of your choice.
625
626@end itemize
627
628@section Moving on
629
630That's all you need to know to use ASDF to load systems written by others.
631The rest of this manual deals with writing system definitions
632for Common Lisp software you write yourself,
633including how to extend ASDF to define new operation and component types.
634
635
636@node Defining systems with defsystem, The object model of ASDF, Using ASDF, Top
637@comment  node-name,  next,  previous,  up
638@chapter Defining systems with defsystem
639
640This chapter describes how to use asdf to define systems and develop
641software.
642
643
644@menu
645* The defsystem form::
646* A more involved example::
647* The defsystem grammar::
648* Other code in .asd files::
649@end menu
650
651@node  The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
652@comment  node-name,  next,  previous,  up
653@section The defsystem form
654
655Systems can be constructed programmatically
656by instantiating components using @code{make-instance}.
657Most of the time, however, it is much more practical to use
658a static @code{defsystem} form.
659This section begins with an example of a system definition,
660then gives the full grammar of @code{defsystem}.
661
662Let's look at a simple system.
663This is a complete file that would
664usually be saved as @file{hello-lisp.asd}:
665
666@lisp
667(in-package :asdf)
668
669(defsystem "hello-lisp"
670  :description "hello-lisp: a sample Lisp system."
671  :version "0.2"
672  :author "Joe User <joe@@example.com>"
673  :licence "Public Domain"
674  :components ((:file "packages")
675               (:file "macros" :depends-on ("packages"))
676               (:file "hello" :depends-on ("macros"))))
677@end lisp
678
679Some notes about this example:
680
681@itemize
682
683@item
684The file starts with an @code{in-package} form
685to use package @code{asdf}.
686You could instead start your definition by using
687a qualified name @code{asdf:defsystem}.
688
689@item
690If in addition to simply using @code{defsystem},
691you are going to define functions,
692create ASDF extension, globally bind symbols, etc.,
693it is recommended that to avoid namespace pollution between systems,
694you should create your own package for that purpose,
695for instance replacing the above @code{(in-package :asdf)} with:
696
697@lisp
698(defpackage :foo-system
699  (:use :cl :asdf))
700
701(in-package :foo-system)
702@end lisp
703
704@item
705The @code{defsystem} form defines a system named @code{hello-lisp}
706that contains three source files:
707@file{packages}, @file{macros} and @file{hello}.
708
709@item
710The file @file{macros} depends on @file{packages}
711(presumably because the package it's in is defined in @file{packages}),
712and the file @file{hello} depends on @file{macros}
713(and hence, transitively on @file{packages}).
714This means that ASDF will compile and load @file{packages} and @file{macros}
715before starting the compilation of file @file{hello}.
716
717@item
718The files are located in the same directory
719as the file with the system definition.
720ASDF resolves symbolic links (or Windows shortcuts)
721before loading the system definition file and
722stores its location in the resulting system@footnote{
723It is possible, though almost never necessary, to override this behaviour.}.
724This is a good thing because the user can move the system sources
725without having to edit the system definition.
726
727@end itemize
728
729@node  A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
730@comment  node-name,  next,  previous,  up
731@section A more involved example
732
733Let's illustrate some more involved uses of @code{defsystem} via a
734slightly convoluted example:
735
736@lisp
737(defsystem "foo"
738  :version "1.0"
739  :components ((:module "mod"
740                            :components ((:file "bar")
741                                                  (:file"baz")
742                                                  (:file "quux"))
743                            :perform (compile-op :after (op c)
744                                                  (do-something c))
745                            :explain (compile-op :after (op c)
746                                            (explain-something c)))
747                         (:file "blah")))
748@end lisp
749
750The @code{:module} component named @code{"mod"} is a collection of three files,
751which will be located in a subdirectory of the main code directory named
752@file{mod} (this location can be overridden; see the discussion of the
753@code{:pathname} option in @ref{The defsystem grammar}).
754
755The method-form tokens provide a shorthand for defining methods on
756particular components.  This part
757
758@lisp
759                :perform (compile-op :after (op c)
760                          (do-something c))
761                :explain (compile-op :after (op c)
762                          (explain-something c))
763@end lisp
764
765has the effect of
766
767@lisp
768(defmethod perform :after ((op compile-op) (c (eql ...)))
769           (do-something c))
770(defmethod explain :after ((op compile-op) (c (eql ...)))
771           (explain-something c))
772@end lisp
773
774where @code{...} is the component in question.
775In this case @code{...} would expand to something like
776
777@lisp
778(find-component (find-system "foo") "mod")
779@end lisp
780
781For more details on the syntax of such forms, see @ref{The defsystem
782grammar}.
783For more details on what these methods do, @pxref{Operations} in
784@ref{The object model of ASDF}.
785
786@c The following plunge into the weeds is not appropriate in this
787@c location. [2010/10/03:rpg]
788@c note that although this also supports @code{:before} methods,
789@c they may not do what you want them to ---
790@c a @code{:before} method on perform @code{((op compile-op) (c (eql ...)))}
791@c will run after all the dependencies and sub-components have been processed,
792@c but before the component in question has been compiled.
793
794@node  The defsystem grammar, Other code in .asd files, A more involved example, Defining systems with defsystem
795@comment  node-name,  next,  previous,  up
796@section The defsystem grammar
797
798@c FIXME: @var typesetting not consistently used here.  We should either expand
799@c its use to everywhere, or we should kill it everywhere.
800
801
802@example
803system-definition := ( defsystem system-designator @var{system-option}* )
804
805system-option := :defsystem-depends-on system-list
806                 | module-option
807                 | option
808
809module-option := :components component-list
810                 | :serial [ t | nil ]
811                 | :if-component-dep-fails component-dep-fail-option
812
813option :=
814        | :pathname pathname-specifier
815        | :default-component-class class-name
816        | :perform method-form
817        | :explain method-form
818        | :output-files method-form
819        | :operation-done-p method-form
820        | :depends-on ( @var{dependency-def}* )
821        | :in-order-to ( @var{dependency}+ )
822
823
824system-list := ( @var{simple-component-name}* )
825
826component-list := ( @var{component-def}* )
827
828component-def  := ( component-type simple-component-name @var{option}* )
829
830component-type := :system | :module | :file | :static-file | other-component-type
831
832other-component-type := symbol-by-name (@pxref{The defsystem grammar,,Component types})
833
834dependency-def := simple-component-name
835               | ( :feature name )
836               | ( :version simple-component-name version-specifier)
837
838dependency := (dependent-op @var{requirement}+)
839requirement := (required-op @var{required-component}+)
840             | (feature feature-name)
841dependent-op := operation-name
842required-op := operation-name | feature
843
844simple-component-name := string
845                      |  symbol
846
847pathname-specifier := pathname | string | symbol
848
849method-form := (operation-name qual lambda-list @&rest body)
850qual := method qualifier
851
852component-dep-fail-option := :fail | :try-next | :ignore
853@end example
854
855
856
857@subsection Component names
858
859Component names (@code{simple-component-name})
860may be either strings or symbols.
861
862@subsection Component types
863
864Component type names, even if expressed as keywords, will be looked up
865by name in the current package and in the asdf package, if not found in
866the current package.  So a component type @code{my-component-type}, in
867the current package @code{my-system-asd} can be specified as
868@code{:my-component-type}, or @code{my-component-type}.
869
870@subsection Defsystem depends on
871
872The @code{:defsystem-depends-on} option to @code{defsystem} allows the
873programmer to specify another ASDF-defined system or set of systems that
874must be loaded @emph{before} the system definition is processed.
875Typically this is used to load an ASDF extension that is used in the
876system definition.
877
878@subsection Pathname specifiers
879@cindex pathname specifiers
880
881A pathname specifier (@code{pathname-specifier})
882may be a pathname, a string or a symbol.
883When no pathname specifier is given for a component,
884which is the usual case, the component name itself is used.
885
886If a string is given, which is the usual case,
887the string will be interpreted as a Unix-style pathname
888where @code{/} characters will be interpreted as directory separators.
889Usually, Unix-style relative pathnames are used
890(i.e. not starting with @code{/}, as opposed to absolute pathnames);
891they are relative to the path of the parent component.
892Finally, depending on the @code{component-type},
893the pathname may be interpreted as either a file or a directory,
894and if it's a file,
895a file type may be added corresponding to the @code{component-type},
896or else it will be extracted from the string itself (if applicable).
897
898For instance, the @code{component-type} @code{:module}
899wants a directory pathname, and so a string @code{"foo/bar"}
900will be interpreted as the pathname @file{#p"foo/bar/"}.
901On the other hand, the @code{component-type} @code{:file}
902wants a file of type @code{lisp}, and so a string @code{"foo/bar"}
903will be interpreted as the pathname @file{#p"foo/bar.lisp"},
904and a string @code{"foo/bar.quux"}
905will be interpreted as the pathname @file{#p"foo/bar.quux.lisp"}.
906Finally, the @code{component-type} @code{:static-file}
907wants a file without specifying a type, and so a string @code{"foo/bar"}
908will be interpreted as the pathname @file{#p"foo/bar"},
909and a string @code{"foo/bar.quux"}
910will be interpreted as the pathname @file{#p"foo/bar.quux"}.
911
912ASDF does not interpret the string @code{".."} to designate the parent
913directory.  This string will be passed through to the underlying
914operating system for interpretation.  We @emph{believe} that this will
915work on all platforms where ASDF is deployed, but do not guarantee this
916behavior.  A pathname object with a relative directory component of
917@code{:up} or @code{:back} is the only guaranteed way to specify a
918parent directory.
919
920If a symbol is given, it will be translated into a string,
921and downcased in the process.
922The downcasing of symbols is unconventional,
923but was selected after some consideration.
924Observations suggest that the type of systems we want to support
925either have lowercase as customary case (Unix, Mac, windows)
926or silently convert lowercase to uppercase (lpns),
927so this makes more sense than attempting to use @code{:case :common}
928as argument to @code{make-pathname},
929which is reported not to work on some implementations.
930
931Pathname objects may be given to override the path for a component.
932Such objects are typically specified using reader macros such as @code{#p}
933or @code{#.(make-pathname ...)}.
934Note however, that @code{#p...} is a shorthand for @code{#.(parse-namestring ...)}
935and that the behavior of @code{parse-namestring} is completely non-portable,
936unless you are using Common Lisp @code{logical-pathname}s
937(@pxref{The defsystem grammar,,Warning about logical pathnames}, below).
938Pathnames made with @code{#.(make-pathname ...)}
939can usually be done more easily with the string syntax above.
940The only case that you really need a pathname object is to override
941the component-type default file type for a given component.
942Therefore, pathname objects should only rarely be used.
943Unhappily, ASDF 1 didn't properly support
944parsing component names as strings specifying paths with directories,
945and the cumbersome @code{#.(make-pathname ...)} syntax had to be used.
946
947Note that when specifying pathname objects,
948ASDF does not do any special interpretation of the pathname
949influenced by the component type, unlike the procedure for
950pathname-specifying strings.
951On the one hand, you have to be careful to provide a pathname that correctly
952fulfills whatever constraints are required from that component type
953(e.g. naming a directory or a file with appropriate type);
954on the other hand, you can circumvent the file type that would otherwise
955be forced upon you if you were specifying a string.
956
957
958@subsection Warning about logical pathnames
959@cindex logical pathnames
960
961We recommend that you not use logical pathnames
962in your asdf system definitions at this point,
963but logical pathnames @emph{are} supported.
964
965To use logical pathnames,
966you will have to provide a pathname object as a @code{:pathname} specifier
967to components that use it, using such syntax as
968@code{#p"LOGICAL-HOST:absolute;path;to;component.lisp"}.
969
970You only have to specify such logical pathname for your system or
971some top-level component.  Sub-components' relative pathnames, specified
972using the string syntax
973for names, will be properly merged with the pathnames of their parents.
974The specification of a logical pathname host however is @emph{not}
975otherwise directly supported in the ASDF syntax
976for pathname specifiers as strings.
977
978The @code{asdf-output-translation} layer will
979avoid trying to resolve and translate logical-pathnames.
980The advantage of this is that you can define yourself what translations you want to use
981with the logical pathname facility.
982The disadvantage is that if you do not define such translations, any
983system that uses logical pathnames will behave differently under
984asdf-output-translations than other systems you use.
985
986If you wish to use logical pathnames you will have to configure the
987translations yourself before they may be used.
988ASDF currently provides no specific support
989for defining logical pathname translations.
990
991
992@subsection Serial dependencies
993@cindex serial dependencies
994
995If the @code{:serial t} option is specified for a module,
996ASDF will add dependencies for each child component,
997on all the children textually preceding it.
998This is done as if by @code{:depends-on}.
999
1000@lisp
1001:serial t
1002:components ((:file "a") (:file "b") (:file "c"))
1003@end lisp
1004
1005is equivalent to
1006
1007@lisp
1008:components ((:file "a")
1009             (:file "b" :depends-on ("a"))
1010             (:file "c" :depends-on ("a" "b")))
1011@end lisp
1012
1013
1014@subsection Source location
1015
1016The @code{:pathname} option is optional in all cases for systems
1017defined via @code{defsystem},
1018and in the usual case the user is recommended not to supply it.
1019
1020Instead, ASDF follows a hairy set of rules that are designed so that
1021@enumerate
1022@item
1023@code{find-system}
1024will load a system from disk
1025and have its pathname default to the right place.
1026@item
1027This pathname information will not be overwritten with
1028@code{*default-pathname-defaults*}
1029(which could be somewhere else altogether)
1030if the user loads up the @file{.asd} file into his editor
1031and interactively re-evaluates that form.
1032@end enumerate
1033
1034If a system is being loaded for the first time,
1035its top-level pathname will be set to:
1036
1037@itemize
1038@item
1039The host/device/directory parts of @code{*load-truename*},
1040if it is bound.
1041@item
1042@code{*default-pathname-defaults*}, otherwise.
1043@end itemize
1044
1045If a system is being redefined, the top-level pathname will be
1046
1047@itemize
1048@item
1049changed, if explicitly supplied or obtained from @code{*load-truename*}
1050(so that an updated source location is reflected in the system definition)
1051@item
1052changed if it had previously been set from @code{*default-pathname-defaults*}
1053@item
1054left as before, if it had previously been set from @code{*load-truename*}
1055and @code{*load-truename*} is currently unbound
1056(so that a developer can evaluate a @code{defsystem} form
1057from within an editor without clobbering its source location)
1058@end itemize
1059
1060@subsection if-component-dep-fails option
1061
1062This option is only appropriate for module components (including
1063systems), not individual source files.
1064
1065For more information about this option, @pxref{Pre-defined subclasses of component}.
1066
1067@node Other code in .asd files,  , The defsystem grammar, Defining systems with defsystem
1068@section Other code in .asd files
1069
1070Files containing @code{defsystem} forms
1071are regular Lisp files that are executed by @code{load}.
1072Consequently, you can put whatever Lisp code you like into these files
1073(e.g., code that examines the compile-time environment
1074and adds appropriate features to @code{*features*}).
1075However, some conventions should be followed,
1076so that users can control certain details of execution
1077of the Lisp in @file{.asd} files:
1078
1079@itemize
1080@item
1081Any informative output
1082(other than warnings and errors,
1083which are the condition system's to dispose of)
1084should be sent to the standard CL stream @code{*standard-output*},
1085so that users can easily control the disposition
1086of output from ASDF operations.
1087@end itemize
1088
1089
1090@node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top
1091@comment  node-name,  next,  previous,  up
1092@chapter The object model of ASDF
1093
1094ASDF is designed in an object-oriented way from the ground up.
1095Both a system's structure and the operations that can be performed on systems
1096follow a protocol.
1097ASDF is extensible to new operations and to new component types.
1098This allows the addition of behaviours:
1099for example, a new component could be added for Java JAR archives,
1100and methods specialised on @code{compile-op} added for it
1101that would accomplish the relevant actions.
1102
1103This chapter deals with @emph{components}, the building blocks of a system,
1104and @emph{operations}, the actions that can be performed on a system.
1105
1106
1107
1108@menu
1109* Operations::
1110* Components::
1111@end menu
1112
1113@node  Operations, Components, The object model of ASDF, The object model of ASDF
1114@comment  node-name,  next,  previous,  up
1115@section Operations
1116@cindex operation
1117
1118An @dfn{operation} object of the appropriate type is instantiated
1119whenever the user wants to do something with a system like
1120
1121@itemize
1122@item compile all its files
1123@item load the files into a running lisp environment
1124@item copy its source files somewhere else
1125@end itemize
1126
1127Operations can be invoked directly, or examined
1128to see what their effects would be without performing them.
1129@emph{FIXME: document how!}
1130There are a bunch of methods specialised on operation and component type
1131that actually do the grunt work.
1132
1133The operation object contains whatever state is relevant for this purpose
1134(perhaps a list of visited nodes, for example)
1135but primarily is a nice thing to specialise operation methods on
1136and easier than having them all be @code{EQL} methods.
1137
1138Operations are invoked on systems via @code{operate}.
1139@anchor{operate}
1140@deffn {Generic function} @code{operate} @var{operation} @var{system} @&rest @var{initargs}
1141@deffnx {Generic function} @code{oos} @var{operation} @var{system} @&rest @var{initargs}
1142@code{operate} invokes @var{operation} on @var{system}.
1143@code{oos} is a synonym for @code{operate}.
1144
1145@var{operation} is a symbol that is passed, along with the supplied
1146@var{initargs}, to @code{make-instance} to create the operation object.
1147@var{system} is a system designator.
1148
1149The @var{initargs} are passed to the @code{make-instance} call
1150when creating the operation object.
1151Note that dependencies may cause the operation
1152to invoke other operations on the system or its components:
1153the new operations will be created
1154with the same @var{initargs} as the original one.
1155
1156@end deffn
1157
1158@menu
1159* Predefined operations of ASDF::
1160* Creating new operations::
1161@end menu
1162
1163@node Predefined operations of ASDF, Creating new operations, Operations, Operations
1164@comment  node-name,  next,  previous,  up
1165@subsection Predefined operations of ASDF
1166
1167All the operations described in this section are in the @code{asdf} package.
1168They are invoked via the @code{operate} generic function.
1169
1170@lisp
1171(asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
1172@end lisp
1173
1174@deffn Operation @code{compile-op} @&key @code{proclamations}
1175
1176This operation compiles the specified component.
1177If proclamations are supplied, they will be proclaimed.
1178This is a good place to specify optimization settings.
1179
1180When creating a new component type,
1181you should provide methods for @code{compile-op}.
1182
1183When @code{compile-op} is invoked,
1184component dependencies often cause some parts of the system
1185to be loaded as well as compiled.
1186Invoking @code{compile-op}
1187does not necessarily load all the parts of the system, though;
1188use @code{load-op} to load a system.
1189@end deffn
1190
1191@deffn Operation @code{load-op} @&key @code{proclamations}
1192
1193This operation loads a system.
1194
1195The default methods for @code{load-op} compile files before loading them.
1196For parity, your own methods on new component types should probably do so too.
1197@end deffn
1198
1199@deffn Operation @code{load-source-op}
1200
1201This operation will load the source for the files in a module
1202even if the source files have been compiled.
1203Systems sometimes have knotty dependencies
1204which require that sources are loaded
1205before they can be compiled.
1206This is how you do that.
1207
1208If you are creating a component type,
1209you need to implement this operation --- at least, where meaningful.
1210@end deffn
1211
1212@anchor{test-op}
1213@deffn Operation @code{test-op}
1214
1215This operation will perform some tests on the module.
1216The default method will do nothing.
1217The default dependency is to require
1218@code{load-op} to be performed on the module first.
1219The default @code{operation-done-p} is that the operation is @emph{never} done
1220---
1221we assume that if you invoke the @code{test-op},
1222you want to test the system, even if you have already done so.
1223
1224The results of this operation are not defined by ASDF.
1225It has proven difficult to define how the test operation
1226should signal its results to the user
1227in a way that is compatible with all of the various test libraries
1228and test techniques in use in the community.
1229@end deffn
1230
1231@c @deffn Operation test-system-version @&key minimum
1232
1233@c Asks the system whether it satisfies a version requirement.
1234
1235@c The default method accepts a string, which is expected to contain of a
1236@c number of integers separated by #\. characters.  The method is not
1237@c recursive.  The component satisfies the version dependency if it has
1238@c the same major number as required and each of its sub-versions is
1239@c greater than or equal to the sub-version number required.
1240
1241@c @lisp
1242@c (defun version-satisfies (x y)
1243@c   (labels ((bigger (x y)
1244@c           (cond ((not y) t)
1245@c                 ((not x) nil)
1246@c                 ((> (car x) (car y)) t)
1247@c                 ((= (car x) (car y))
1248@c                  (bigger (cdr x) (cdr y))))))
1249@c     (and (= (car x) (car y))
1250@c       (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
1251@c @end lisp
1252
1253@c If that doesn't work for your system, you can override it.  I hope
1254@c you have as much fun writing the new method as @verb{|#lisp|} did
1255@c reimplementing this one.
1256@c @end deffn
1257
1258@c @deffn Operation feature-dependent-op
1259
1260@c An instance of @code{feature-dependent-op} will ignore any components
1261@c which have a @code{features} attribute, unless the feature combination
1262@c it designates is satisfied by @code{*features*}.  This operation is
1263@c not intended to be instantiated directly, but other operations may
1264@c inherit from it.
1265
1266@c @end deffn
1267
1268@node  Creating new operations,  , Predefined operations of ASDF, Operations
1269@comment  node-name,  next,  previous,  up
1270@subsection Creating new operations
1271
1272ASDF was designed to be extensible in an object-oriented fashion.
1273To teach ASDF new tricks, a programmer can implement the behaviour he wants
1274by creating a subclass of @code{operation}.
1275
1276ASDF's pre-defined operations are in no way ``privileged'',
1277but it is requested that developers never use the @code{asdf} package
1278for operations they develop themselves.
1279The rationale for this rule is that we don't want to establish a
1280``global asdf operation name registry'',
1281but also want to avoid name clashes.
1282
1283An operation must provide methods for the following generic functions
1284when invoked with an object of type @code{source-file}:
1285@emph{FIXME describe this better}
1286
1287@itemize
1288
1289@item @code{output-files}
1290The @code{output-files} method determines where the method will put its files.
1291It returns two values, a list of pathnames, and a boolean.
1292If the boolean is @code{T} then the pathnames are marked
1293not be translated by enclosing @code{:around} methods.
1294If the boolean is @code{NIL} then enclosing @code{:around} methods
1295may translate these pathnames, e.g. to ensure object files
1296are somehow stored in some implementation-dependent cache.
1297@item @code{perform}
1298The @code{perform} method must call @code{output-files}
1299to find out where to put its files,
1300because the user is allowed to override.
1301@item @code{output-files}
1302for local policy @code{explain}
1303@item @code{operation-done-p},
1304if you don't like the default one
1305
1306@end itemize
1307
1308Operations that print output should send that output to the standard
1309CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
1310
1311@node Components,  , Operations, The object model of ASDF
1312@comment  node-name,  next,  previous,  up
1313@section Components
1314@cindex component
1315@cindex system
1316@cindex system designator
1317@vindex *system-definition-search-functions*
1318
1319A @dfn{component} represents a source file or
1320(recursively) a collection of components.
1321A @dfn{system} is (roughly speaking) a top-level component
1322that can be found via @code{find-system}.
1323
1324A @dfn{system designator} is a string or symbol
1325and behaves just like any other component name
1326(including with regard to the case conversion rules for component names).
1327
1328
1329@defun find-system system-designator &optional (error-p t)
1330
1331Given a system designator, @code{find-system} finds and returns a system.
1332If no system is found, an error of type
1333@code{missing-component} is thrown,
1334or @code{nil} is returned if @code{error-p} is false.
1335
1336To find and update systems, @code{find-system} funcalls each element
1337in the @code{*system-definition-search-functions*} list,
1338expecting a pathname to be returned.
1339The resulting pathname is loaded if either of the following conditions is true:
1340
1341@itemize
1342@item
1343there is no system of that name in memory
1344@item
1345the file's @code{last-modified} time exceeds the @code{last-modified} time
1346of the system in memory
1347@end itemize
1348
1349When system definitions are loaded from @file{.asd} files,
1350a new scratch package is created for them to load into,
1351so that different systems do not overwrite each others operations.
1352The user may also wish to (and is recommended to)
1353include @code{defpackage} and @code{in-package} forms
1354in his system definition files, however,
1355so that they can be loaded manually if need be.
1356
1357The default value of @code{*system-definition-search-functions*}
1358is a list of two functions.
1359The first function looks in each of the directories given
1360by evaluating members of @code{*central-registry*}
1361for a file whose name is the name of the system and whose type is @file{asd}.
1362The first such file is returned,
1363whether or not it turns out to actually define the appropriate system.
1364The second function does something similar,
1365for the directories specified in the @code{source-registry}.
1366Hence, it is strongly advised to define a system
1367@var{foo} in the corresponding file @var{foo.asd}.
1368@end defun
1369
1370
1371@menu
1372* Common attributes of components::
1373* Pre-defined subclasses of component::
1374* Creating new component types::
1375@end menu
1376
1377@node  Common attributes of components, Pre-defined subclasses of component, Components, Components
1378@comment  node-name,  next,  previous,  up
1379@subsection Common attributes of components
1380
1381All components, regardless of type, have the following attributes.
1382All attributes except @code{name} are optional.
1383
1384@subsubsection Name
1385
1386A component name is a string or a symbol.
1387If a symbol, its name is taken and lowercased.
1388
1389Unless overridden by a @code{:pathname} attribute,
1390the name will be interpreted as a pathname specifier according
1391to a Unix-style syntax.
1392@xref{The defsystem grammar,,Pathname specifiers}.
1393
1394@subsubsection Version identifier
1395
1396This optional attribute is used by the @code{test-system-version} operation.
1397@xref{Predefined operations of ASDF}.
1398For the default method of @code{test-system-version},
1399the version should be a string of integers separated by dots,
1400for example @samp{1.0.11}.
1401
1402@emph{Nota Bene}:
1403This operation, planned for ASDF 1,
1404is still not implement yet as of ASDF 2.
1405Don't hold your breath.
1406
1407
1408@subsubsection Required features
1409
1410@emph{FIXME: This subsection seems to contradict the
1411@code{defsystem} grammar subsection,
1412which doesn't provide any obvious way to specify required features.
1413Furthermore, in 2009, discussions on the
1414@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
1415suggested that the specification of required features may be broken,
1416and that no one may have been using them for a while.
1417Please contact the
1418@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
1419if you are interested in getting this features feature fixed.}
1420
1421Traditionally defsystem users have used reader conditionals
1422to include or exclude specific per-implementation files.
1423This means that any single implementation cannot read the entire system,
1424which becomes a problem if it doesn't wish to compile it,
1425but instead for example to create an archive file containing all the sources,
1426as it will omit to process the system-dependent sources for other systems.
1427
1428Each component in an asdf system may therefore specify features using
1429the same syntax as @code{#+} does, and it will (somehow) be ignored for
1430certain operations unless the feature conditional is a member of
1431@code{*features*}.
1432
1433
1434@subsubsection Dependencies
1435
1436This attribute specifies dependencies of the component on its siblings.
1437It is optional but often necessary.
1438
1439There is an excitingly complicated relationship between the initarg
1440and the method that you use to ask about dependencies
1441
1442Dependencies are between (operation component) pairs.
1443In your initargs for the component, you can say
1444
1445@lisp
1446:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
1447              (load-op (load-op "foo")))
1448@end lisp
1449
1450This means the following things:
1451@itemize
1452@item
1453before performing compile-op on this component, we must perform
1454load-op on @var{a} and @var{b}, and compile-op on @var{c},
1455@item
1456before performing @code{load-op}, we have to load @var{foo}
1457@end itemize
1458
1459The syntax is approximately
1460
1461@verbatim
1462(this-op {(other-op required-components)}+)
1463
1464required-components := component-name
1465                     | (required-components required-components)
1466
1467component-name := string
1468                | (:version string minimum-version-object)
1469@end verbatim
1470
1471Side note:
1472
1473This is on a par with what ACL defsystem does.
1474mk-defsystem is less general: it has an implied dependency
1475
1476@verbatim
1477  for all x, (load x) depends on (compile x)
1478@end verbatim
1479
1480and using a @code{:depends-on} argument to say that @var{b} depends on
1481@var{a} @emph{actually} means that
1482
1483@verbatim
1484  (compile b) depends on (load a)
1485@end verbatim
1486
1487This is insufficient for e.g. the McCLIM system, which requires that
1488all the files are loaded before any of them can be compiled ]
1489
1490End side note
1491
1492In ASDF, the dependency information for a given component and operation
1493can be queried using @code{(component-depends-on operation component)},
1494which returns a list
1495
1496@lisp
1497((load-op "a") (load-op "b") (compile-op "c") ...)
1498@end lisp
1499
1500@code{component-depends-on} can be subclassed for more specific
1501component/operation types: these need to @code{(call-next-method)}
1502and append the answer to their dependency, unless
1503they have a good reason for completely overriding the default dependencies.
1504
1505If it weren't for CLISP, we'd be using @code{LIST} method
1506combination to do this transparently.
1507But, we need to support CLISP.
1508If you have the time for some CLISP hacking,
1509I'm sure they'd welcome your fixes.
1510@c Doesn't CLISP now support LIST method combination?
1511
1512@subsubsection pathname
1513
1514This attribute is optional and if absent (which is the usual case),
1515the component name will be used.
1516
1517@xref{The defsystem grammar,,Pathname specifiers},
1518for an explanation of how this attribute is interpreted.
1519
1520Note that the @code{defsystem} macro (used to create a ``top-level'' system)
1521does additional processing to set the filesystem location of
1522the top component in that system.
1523This is detailed elsewhere. @xref{Defining systems with defsystem}.
1524
1525
1526@subsubsection properties
1527
1528This attribute is optional.
1529
1530Packaging systems often require information about files or systems
1531in addition to that specified by ASDF's pre-defined component attributes.
1532Programs that create vendor packages out of ASDF systems therefore
1533have to create ``placeholder'' information to satisfy these systems.
1534Sometimes the creator of an ASDF system may know the additional
1535information and wish to provide it directly.
1536
1537@code{(component-property component property-name)} and
1538associated @code{setf} method will allow
1539the programmatic update of this information.
1540Property names are compared as if by @code{EQL},
1541so use symbols or keywords or something.
1542
1543@menu
1544* Pre-defined subclasses of component::
1545* Creating new component types::
1546@end menu
1547
1548@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
1549@comment  node-name,  next,  previous,  up
1550@subsection Pre-defined subclasses of component
1551
1552@deffn Component source-file
1553
1554A source file is any file that the system does not know how to
1555generate from other components of the system.
1556
1557Note that this is not necessarily the same thing as
1558``a file containing data that is typically fed to a compiler''.
1559If a file is generated by some pre-processor stage
1560(e.g. a @file{.h} file from @file{.h.in} by autoconf)
1561then it is not, by this definition, a source file.
1562Conversely, we might have a graphic file
1563that cannot be automatically regenerated,
1564or a proprietary shared library that we received as a binary:
1565these do count as source files for our purposes.
1566
1567Subclasses of source-file exist for various languages.
1568@emph{FIXME: describe these.}
1569@end deffn
1570
1571@deffn Component module
1572
1573A module is a collection of sub-components.
1574
1575A module component has the following extra initargs:
1576
1577@itemize
1578@item
1579@code{:components} the components contained in this module
1580
1581@item
1582@code{:default-component-class}
1583All children components which don't specify their class explicitly
1584are inferred to be of this type.
1585
1586@item
1587@code{:if-component-dep-fails}
1588This attribute takes one of the values
1589@code{:fail}, @code{:try-next}, @code{:ignore},
1590its default value is @code{:fail}.
1591The other values can be used for implementing conditional compilation
1592based on implementation @code{*features*},
1593for the case where it is not necessary for all files in a module to be
1594compiled.
1595@emph{FIXME: such conditional compilation has been reported
1596to be broken in 2009.}
1597
1598@item
1599@code{:serial} When this attribute is set,
1600each subcomponent of this component is assumed to depend on all subcomponents
1601before it in the list given to @code{:components}, i.e.
1602all of them are loaded before a compile or load operation is performed on it.
1603
1604@end itemize
1605
1606The default operation knows how to traverse a module, so
1607most operations will not need to provide methods specialised on modules.
1608
1609@code{module} may be subclassed to represent components such as
1610foreign-language linked libraries or archive files.
1611@end deffn
1612
1613@deffn Component system
1614
1615@code{system} is a subclass of @code{module}.
1616
1617A system is a module with a few extra attributes for documentation
1618purposes; these are given elsewhere.
1619@xref{The defsystem grammar}.
1620
1621Users can create new classes for their systems:
1622the default @code{defsystem} macro takes a @code{:class} keyword argument.
1623@end deffn
1624
1625@node  Creating new component types,  , Pre-defined subclasses of component, Components
1626@comment  node-name,  next,  previous,  up
1627@subsection Creating new component types
1628
1629New component types are defined by subclassing one of the existing
1630component classes and specializing methods on the new component class.
1631
1632@emph{FIXME: this should perhaps be explained more throughly,
1633not only by example ...}
1634
1635As an example, suppose we have some implementation-dependent
1636functionality that we want to isolate
1637in one subdirectory per Lisp implementation our system supports.
1638We create a subclass of
1639@code{cl-source-file}:
1640
1641@lisp
1642(defclass unportable-cl-source-file (cl-source-file)
1643  ())
1644@end lisp
1645
1646A hypothetical function @code{system-dependent-dirname}
1647gives us the name of the subdirectory.
1648All that's left is to define how to calculate the pathname
1649of an @code{unportable-cl-source-file}.
1650
1651@lisp
1652(defmethod component-pathname ((component unportable-cl-source-file))
1653  (let ((pathname (call-next-method))
1654        (name (string-downcase (system-dependent-dirname))))
1655    (merge-pathnames*
1656     (make-pathname :directory (list :relative name))
1657     pathname)))
1658@end lisp
1659
1660The new component type is used in a @code{defsystem} form in this way:
1661
1662@lisp
1663(defsystem :foo
1664    :components
1665    ((:file "packages")
1666     ...
1667     (:unportable-cl-source-file "threads"
1668      :depends-on ("packages" ...))
1669     ...
1670    )
1671@end lisp
1672
1673@node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
1674@comment  node-name,  next,  previous,  up
1675@chapter Controlling where ASDF searches for systems
1676
1677@section Configurations
1678
1679Configurations specify paths where to find system files.
1680
1681@enumerate
1682
1683@item
1684The search registry may use some hardcoded wrapping registry specification.
1685This allows some implementations (notably SBCL) to specify where to find
1686some special implementation-provided systems that
1687need to precisely match the version of the implementation itself.
1688
1689@item
1690An application may explicitly initialize the source-registry configuration
1691using the configuration API
1692(@pxref{Controlling where ASDF searches for systems,Configuration API,Configuration API}, below)
1693in which case this takes precedence.
1694It may itself compute this configuration from the command-line,
1695from a script, from its own configuration file, etc.
1696
1697@item
1698The source registry will be configured from
1699the environment variable @code{CL_SOURCE_REGISTRY} if it exists.
1700
1701@item
1702The source registry will be configured from
1703user configuration file
1704@file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf}
1705(which defaults to
1706@file{~/.config/common-lisp/source-registry.conf})
1707if it exists.
1708
1709@item
1710The source registry will be configured from
1711user configuration directory
1712@file{$XDG_CONFIG_DIRS/common-lisp/source-registry.conf.d/}
1713(which defaults to
1714@file{~/.config/common-lisp/source-registry.conf.d/})
1715if it exists.
1716
1717@item
1718The source registry will be configured from
1719system configuration file
1720@file{/etc/common-lisp/source-registry.conf}
1721if it exists/
1722
1723@item
1724The source registry will be configured from
1725system configuration directory
1726@file{/etc/common-lisp/source-registry.conf.d/}
1727if it exists.
1728
1729@item
1730The source registry will be configured from a default configuration.
1731This configuration may allow for implementation-specific systems
1732to be found, for systems to be found the current directory
1733(at the time that the configuration is initialized) as well as
1734@code{:directory} entries for @file{$XDG_DATA_DIRS/common-lisp/systems/} and
1735@code{:tree} entries for @file{$XDG_DATA_DIRS/common-lisp/source/}.
1736For instance, SBCL will include directories for its contribs
1737when it can find them; it will look for them where SBCL was installed,
1738or at the location specified by the @code{SBCL_HOME} environment variable.
1739
1740@end enumerate
1741
1742Each of these configurations is specified as an s-expression
1743in a trivial domain-specific language (defined below).
1744Additionally, a more shell-friendly syntax is available
1745for the environment variable (defined yet below).
1746
1747Each of these configurations is only used if the previous
1748configuration explicitly or implicitly specifies that it
1749includes its inherited configuration.
1750
1751Additionally, some implementation-specific directories
1752may be automatically prepended to whatever directories are specified
1753in configuration files, no matter if the last one inherits or not.
1754
1755@section XDG base directory
1756
1757Note that we purport to respect the XDG base directory specification
1758as to where configuration files are located,
1759where data files are located,
1760where output file caches are located.
1761Mentions of XDG variables refer to that document.
1762
1763@url{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}
1764
1765This specification allows the user to specify some environment variables
1766to customize how applications behave to his preferences.
1767
1768On Windows platforms, when not using Cygwin,
1769instead of the XDG base directory specification,
1770we try to use folder configuration from the registry regarding
1771@code{Common AppData} and similar directories.
1772However, support for querying the Windows registry is limited as of ASDF 2,
1773and on many implementations, we may fall back to always using the defaults
1774without consulting the registry.
1775Patches welcome.
1776
1777@section Backward Compatibility
1778
1779For backward compatibility as well as to provide a practical backdoor for hackers,
1780ASDF will first search for @code{.asd} files in the directories specified in
1781@code{asdf:*central-registry*}
1782before it searches in the source registry above.
1783
1784@xref{Configuring ASDF,,Configuring ASDF to find your systems -- old style}.
1785
1786By default, @code{asdf:*central-registry*} will be empty.
1787
1788This old mechanism will therefore not affect you if you don't use it,
1789but will take precedence over the new mechanism if you do use it.
1790
1791@section Configuration DSL
1792
1793Here is the grammar of the s-expression (SEXP) DSL for source-registry configuration:
1794
1795@example
1796;; A configuration is a single SEXP starting with keyword :source-registry
1797;; followed by a list of directives.
1798CONFIGURATION := (:source-registry DIRECTIVE ...)
1799
1800;; A directive is one of the following:
1801DIRECTIVE :=
1802    ;; INHERITANCE DIRECTIVE:
1803    ;; Your configuration expression MUST contain
1804    ;; exactly one of either of these:
1805    :inherit-configuration | ; splices inherited configuration (often specified last)
1806    :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
1807
1808    ;; add a single directory to be scanned (no recursion)
1809    (:directory DIRECTORY-PATHNAME-DESIGNATOR) |
1810
1811    ;; add a directory hierarchy, recursing but excluding specified patterns
1812    (:tree DIRECTORY-PATHNAME-DESIGNATOR) |
1813
1814    ;; override the defaults for exclusion patterns
1815    (:exclude PATTERN ...) |
1816    ;; augment the defaults for exclusion patterns
1817    (:also-exclude PATTERN ...) |
1818    ;; Note that the scope of a an exclude pattern specification is
1819    ;; the rest of the current configuration expression or file.
1820
1821    ;; splice the parsed contents of another config file
1822    (:include REGULAR-FILE-PATHNAME-DESIGNATOR) |
1823
1824    ;; This directive specifies that some default must be spliced.
1825    :default-registry
1826
1827REGULAR-FILE-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a file
1828DIRECTORY-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a directory name
1829
1830PATHNAME-DESIGNATOR :=
1831    NULL | ;; Special: skip this entry.
1832    ABSOLUTE-COMPONENT-DESIGNATOR |
1833    (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...)
1834
1835ABSOLUTE-COMPONENT-DESIGNATOR :=
1836    STRING | ;; namestring (better be absolute or bust, directory assumed where applicable)
1837    PATHNAME | ;; pathname (better be an absolute path, or bust)
1838    :HOME | ;; designates the user-homedir-pathname ~/
1839    :USER-CACHE | ;; designates the default location for the user cache
1840    :SYSTEM-CACHE ;; designates the default location for the system cache
1841
1842RELATIVE-COMPONENT-DESIGNATOR :=
1843    STRING | ;; namestring (directory assumed where applicable)
1844    PATHNAME | ;; pathname
1845    :IMPLEMENTATION | ;; a directory based on implementation, e.g. sbcl-1.0.32.30-linux-x86-64
1846    :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
1847    :UID | ;; current UID -- not available on Windows
1848    :USER ;; current USER name -- NOT IMPLEMENTED(!)
1849
1850PATTERN := a string without wildcards, that will be matched exactly
1851  against the name of a any subdirectory in the directory component
1852        of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"}
1853@end example
1854
1855For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf},
1856which is the default place ASDF looks for this configuration,
1857once contained:
1858@example
1859(:source-registry
1860  (:tree (:home "cl")) ;; will expand to e.g. "/home/joeluser/cl/"
1861  :inherit-configuration)
1862@end example
1863
1864@section Configuration Directories
1865
1866Configuration directories consist in files each contains
1867a list of directives without any enclosing @code{(:source-registry ...)} form.
1868The files will be sorted by namestring as if by @code{string<} and
1869the lists of directives of these files with be concatenated in order.
1870An implicit @code{:inherit-configuration} will be included
1871at the @emph{end} of the list.
1872
1873This allows for packaging software that has file granularity
1874(e.g. Debian's @code{dpkg} or some future version of @code{clbuild})
1875to easily include configuration information about distributed software.
1876
1877The convention is that, for sorting purposes,
1878the names of files in such a directory begin with two digits
1879that determine the order in which these entries will be read.
1880Also, the type of these files is conventionally @code{"conf"}
1881and as a limitation to some implementations (e.g. GNU clisp),
1882the type cannot be @code{NIL}.
1883
1884Directories may be included by specifying a directory pathname
1885or namestring in an @code{:include} directive, e.g.:
1886
1887@example
1888  (:include "/foo/bar/")
1889@end example
1890
1891Hence, to achieve the same effect as
1892my example @file{~/.config/common-lisp/source-registry.conf} above,
1893I could simply create a file
1894@file{~/.config/common-lisp/source-registry.conf.d/33-home-fare-cl.conf}
1895alone in its directory with the following contents:
1896@example
1897(:tree "/home/fare/cl/")
1898@end example
1899
1900
1901@section Shell-friendly syntax for configuration
1902
1903When considering environment variable @code{CL_SOURCE_REGISTRY}
1904ASDF will skip to next configuration if it's an empty string.
1905It will @code{READ} the string as a SEXP in the DSL
1906if it begins with a paren @code{(}
1907and it will be interpreted much like @code{TEXINPUTS}
1908list of paths, where
1909
1910  * paths are separated
1911   by a @code{:} (colon) on Unix platforms (including cygwin),
1912   by a @code{;} (semicolon) on other platforms (mainly, Windows).
1913
1914  * each entry is a directory to add to the search path.
1915
1916  * if the entry ends with a double slash @code{//}
1917    then it instead indicates a tree in the subdirectories
1918    of which to recurse.
1919
1920  * if the entry is the empty string (which may only appear once),
1921    then it indicates that the inherited configuration should be
1922    spliced there.
1923
1924
1925@section Search Algorithm
1926@vindex *default-source-registry-exclusions*
1927
1928In case that isn't clear, the semantics of the configuration is that
1929when searching for a system of a given name,
1930directives are processed in order.
1931
1932When looking in a directory, if the system is found, the search succeeds,
1933otherwise it continues.
1934
1935When looking in a tree, if one system is found, the search succeeds.
1936If multiple systems are found, the consequences are unspecified:
1937the search may succeed with any of the found systems,
1938or an error may be raised.
1939ASDF currently returns the first system found,
1940XCVB currently raised an error.
1941If none is found, the search continues.
1942
1943Exclude statements specify patterns of subdirectories
1944the systems from which to ignore.
1945Typically you don't want to use copies of files kept by such
1946version control systems as Darcs.
1947Exclude statements are not propagated to further included or inherited
1948configuration files or expressions;
1949instead the defaults are reset around every configuration statement
1950to the default defaults from @code{asdf::*default-source-registry-exclusions*}.
1951
1952Include statements cause the search to recurse with the path specifications
1953from the file specified.
1954
1955An inherit-configuration statement cause the search to recurse with the path
1956specifications from the next configuration
1957(@pxref{Controlling where ASDF searches for systems,,Configurations} above).
1958
1959
1960@section Caching Results
1961
1962The implementation is allowed to either eagerly compute the information
1963from the configurations and file system, or to lazily re-compute it
1964every time, or to cache any part of it as it goes.
1965To explicitly flush any information cached by the system, use the API below.
1966
1967
1968@section Configuration API
1969
1970The specified functions are exported from your build system's package.
1971Thus for ASDF the corresponding functions are in package ASDF,
1972and for XCVB the corresponding functions are in package XCVB.
1973
1974@defun initialize-source-registry @&optional PARAMETER
1975   will read the configuration and initialize all internal variables.
1976   You may extend or override configuration
1977   from the environment and configuration files
1978   with the given @var{PARAMETER}, which can be
1979   @code{NIL} (no configuration override),
1980   or a SEXP (in the SEXP DSL),
1981   a string (as in the string DSL),
1982   a pathname (of a file or directory with configuration),
1983   or a symbol (fbound to function that when called returns one of the above).
1984@end defun
1985
1986@defun clear-source-registry
1987   undoes any source registry configuration
1988   and clears any cache for the search algorithm.
1989   You might want to call this function
1990   (or better, @code{clear-configuration})
1991   before you dump an image that would be resumed
1992   with a different configuration,
1993   and return an empty configuration.
1994   Note that this does not include clearing information about
1995   systems defined in the current image, only about
1996   where to look for systems not yet defined.
1997@end defun
1998
1999@defun ensure-source-registry @&optional PARAMETER
2000   checks whether a source registry has been initialized.
2001   If not, initialize it with the given @var{PARAMETER}.
2002@end defun
2003
2004Every time you use ASDF's @code{find-system}, or
2005anything that uses it (such as @code{operate}, @code{load-system}, etc.),
2006@code{ensure-source-registry} is called with parameter NIL,
2007which the first time around causes your configuration to be read.
2008If you change a configuration file,
2009you need to explicitly @code{initialize-source-registry} again,
2010or maybe simply to @code{clear-source-registry} (or @code{clear-configuration})
2011which will cause the initialization to happen next time around.
2012
2013
2014@section Future
2015
2016If this mechanism is successful, in the future, we may declare
2017@code{asdf:*central-registry*} obsolete and eventually remove it.
2018Any hook into implementation-specific search mechanisms will by then
2019have been integrated in the @code{:default-configuration} which everyone
2020should either explicitly use or implicit inherit. Some shell syntax
2021for it should probably be added somehow.
2022
2023But we're not there yet. For now, let's see how practical this new
2024source-registry is.
2025
2026
2027@section Rejected ideas
2028
2029Alternatives I considered and rejected included:
2030
2031@enumerate
2032@item Keep @code{asdf:*central-registry*} as the master with its current semantics,
2033   and somehow the configuration parser expands the new configuration
2034   language into a expanded series of directories of subdirectories to
2035   lookup, pre-recursing through specified hierarchies. This is kludgy,
2036   and leaves little space of future cleanups and extensions.
2037
2038@item Keep @code{asdf:*central-registry*} remains the master but extend its semantics
2039   in completely new ways, so that new kinds of entries may be implemented
2040   as a recursive search, etc. This seems somewhat backwards.
2041
2042@item Completely remove @code{asdf:*central-registry*}
2043   and break backwards compatibility.
2044   Hopefully this will happen in a few years after everyone migrate to
2045   a better ASDF and/or to XCVB, but it would be very bad to do it now.
2046
2047@item Replace @code{asdf:*central-registry*} by a symbol-macro with appropriate magic
2048   when you dereference it or setf it. Only the new variable with new
2049   semantics is handled by the new search procedure.
2050   Complex and still introduces subtle semantic issues.
2051@end enumerate
2052
2053
2054I've been suggested the below features, but have rejected them,
2055for the sake of keeping ASDF no more complex than strictly necessary.
2056
2057@itemize
2058@item
2059  More syntactic sugar: synonyms for the configuration directives, such as
2060  @code{(:add-directory X)} for @code{(:directory X)}, or @code{(:add-directory-hierarchy X)}
2061  or @code{(:add-directory X :recurse t)} for @code{(:tree X)}.
2062
2063@item
2064   The possibility to register individual files instead of directories.
2065
2066@item
2067  Integrate Xach Beane's tilde expander into the parser,
2068  or something similar that is shell-friendly or shell-compatible.
2069  I'd rather keep ASDF minimal. But maybe this precisely keeps it
2070  minimal by removing the need for evaluated entries that ASDF has?
2071  i.e. uses of @code{USER-HOMEDIR-PATHNAME} and @code{$SBCL_HOME}
2072  Hopefully, these are already superseded by the @code{:default-registry}
2073
2074@item
2075  Using the shell-unfriendly syntax @code{/**} instead of @code{//} to specify recursion
2076  down a filesystem tree in the environment variable.
2077  It isn't that Lisp friendly either.
2078@end itemize
2079
2080@section TODO
2081
2082@itemize
2083@item Add examples
2084@end itemize
2085
2086
2087@section Credits for the source-registry
2088
2089Thanks a lot to Stelian Ionescu for the initial idea.
2090
2091Thanks to Rommel Martinez for the initial implementation attempt.
2092
2093All bad design ideas and implementation bugs are to mine, not theirs.
2094But so are good design ideas and elegant implementation tricks.
2095
2096 --- Francois-Rene Rideau @email{fare@@tunes.org}, Mon, 22 Feb 2010 00:07:33 -0500
2097
2098
2099
2100@node Controlling where ASDF saves compiled files, Error handling, Controlling where ASDF searches for systems, Top
2101@comment  node-name,  next,  previous,  up
2102@chapter Controlling where ASDF saves compiled files
2103@cindex asdf-output-translations
2104@vindex ASDF_OUTPUT_TRANSLATIONS
2105
2106Each Common Lisp implementation has its own format
2107for compiled files (fasls for short, short for ``fast loading'').
2108If you use multiple implementations
2109(or multiple versions of the same implementation),
2110you'll soon find your source directories
2111littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so on.
2112Worse yet, some implementations use the same file extension
2113while changing formats from version to version (or platform to platform)
2114which means that you'll have to recompile binaries
2115as you switch from one implementation to the next.
2116
2117ASDF 2 includes the @code{asdf-output-translations} facility
2118to mitigate the problem.
2119
2120@section Configurations
2121
2122Configurations specify mappings from input locations to output locations.
2123Once again we rely on the XDG base directory specification for configuration.
2124@xref{Controlling where ASDF searches for systems,,XDG base directory}.
2125
2126@enumerate
2127
2128@item
2129Some hardcoded wrapping output translations configuration may be used.
2130This allows special output translations (or usually, invariant directories)
2131to be specified corresponding to the similar special entries in the source registry.
2132
2133@item
2134An application may explicitly initialize the output-translations
2135configuration using the Configuration API
2136in which case this takes precedence.
2137(@pxref{Controlling where ASDF saves compiled files,,Configuration API}.)
2138It may itself compute this configuration from the command-line,
2139from a script, from its own configuration file, etc.
2140
2141@item
2142The source registry will be configured from
2143the environment variable @code{ASDF_OUTPUT_TRANSLATIONS} if it exists.
2144
2145@item
2146The source registry will be configured from
2147user configuration file
2148@file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf}
2149(which defaults to
2150@file{~/.config/common-lisp/asdf-output-translations.conf})
2151if it exists.
2152
2153@item
2154The source registry will be configured from
2155user configuration directory
2156@file{$XDG_CONFIG_DIRS/common-lisp/asdf-output-translations.conf.d/}
2157(which defaults to
2158@file{~/.config/common-lisp/asdf-output-translations.conf.d/})
2159if it exists.
2160
2161@item
2162The source registry will be configured from
2163system configuration file
2164@file{/etc/common-lisp/asdf-output-translations.conf}
2165if it exists.
2166
2167@item
2168The source registry will be configured from
2169system configuration directory
2170@file{/etc/common-lisp/asdf-output-translations.conf.d/}
2171if it exists.
2172
2173@end enumerate
2174
2175Each of these configurations is specified as a SEXP
2176in a trival domain-specific language (defined below).
2177Additionally, a more shell-friendly syntax is available
2178for the environment variable (defined yet below).
2179
2180Each of these configurations is only used if the previous
2181configuration explicitly or implicitly specifies that it
2182includes its inherited configuration.
2183
2184Note that by default, a per-user cache is used for output files.
2185This allows the seamless use of shared installations of software
2186between several users, and takes files out of the way of the developers
2187when they browse source code,
2188at the expense of taking a small toll when developers have to clean up
2189output files and find they need to get familiar with output-translations first.
2190
2191
2192@section Backward Compatibility
2193
2194@c FIXME -- I think we should provide an easy way
2195@c to get behavior equivalent to A-B-L and
2196@c I will propose a technique for doing this.
2197
2198We purposefully do NOT provide backward compatibility with earlier versions of
2199@code{ASDF-Binary-Locations} (8 Sept 2009),
2200@code{common-lisp-controller} (7.0) or
2201@code{cl-launch} (2.35),
2202each of which had similar general capabilities.
2203The previous APIs of these programs were not designed
2204for configuration by the end-user
2205in an easy way with configuration files.
2206Recent versions of same packages use
2207the new @code{asdf-output-translations} API as defined below:
2208@code{common-lisp-controller} (7.2) and @code{cl-launch} (3.000).
2209@code{ASDF-Binary-Locations} is fully superseded and not to be used anymore.
2210
2211This incompatibility shouldn't inconvenience many people.
2212Indeed, few people use and customize these packages;
2213these few people are experts who can trivially adapt to the new configuration.
2214Most people are not experts, could not properly configure these features
2215(except inasmuch as the default configuration of
2216@code{common-lisp-controller} and/or @code{cl-launch}
2217might have been doing the right thing for some users),
2218and yet will experience software that ``just works'',
2219as configured by the system distributor, or by default.
2220
2221Nevertheless, if you are a fan of @code{ASDF-Binary-Locations},
2222we provide a limited emulation mode:
2223
2224@defun asdf:enable-asdf-binary-locations-compatibility @&key centralize-lisp-binaries default-toplevel-directory include-per-user-information map-all-source-files source-to-target-mappings
2225This function will initialize the new @code{asdf-output-translations} facility in a way
2226that emulates the behavior of the old @code{ASDF-Binary-Locations} facility.
2227Where you would previously set global variables
2228@var{*centralize-lisp-binaries*},
2229@var{*default-toplevel-directory*},
2230@var{*include-per-user-information*},
2231@var{*map-all-source-files*} or @var{*source-to-target-mappings*}
2232you will now have to pass the same values as keyword arguments to this function.
2233Note however that as an extension the @code{:source-to-target-mappings} keyword argument
2234will accept any valid pathname designator for @code{asdf-output-translations}
2235instead of just strings and pathnames.
2236@end defun
2237
2238If you insist, you can also keep using the old @code{ASDF-Binary-Locations}
2239(the one available as an extension to load of top of ASDF,
2240not the one built into a few old versions of ASDF),
2241but first you must disable @code{asdf-output-translations}
2242with @code{(asdf:disable-output-translations)},
2243or you might experience ``interesting'' issues.
2244
2245Also, note that output translation is enabled by default.
2246To disable it, use @code{(asdf:disable-output-translations)}.
2247
2248
2249@section Configuration DSL
2250
2251Here is the grammar of the SEXP DSL
2252for @code{asdf-output-translations} configuration:
2253
2254@verbatim
2255;; A configuration is single SEXP starting with keyword :source-registry
2256;; followed by a list of directives.
2257CONFIGURATION := (:output-translations DIRECTIVE ...)
2258
2259;; A directive is one of the following:
2260DIRECTIVE :=
2261    ;; INHERITANCE DIRECTIVE:
2262    ;; Your configuration expression MUST contain
2263    ;; exactly one of either of these:
2264    :inherit-configuration | ; splices inherited configuration (often specified last)
2265    :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere)
2266
2267    ;; include a configuration file or directory
2268    (:include PATHNAME-DESIGNATOR) |
2269
2270    ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.35-x86-64/ or something.
2271    :enable-user-cache |
2272    ;; Disable global cache. Map / to /
2273    :disable-cache |
2274
2275    ;; add a single directory to be scanned (no recursion)
2276    (DIRECTORY-DESIGNATOR DIRECTORY-DESIGNATOR)
2277
2278    ;; use a function to return the translation of a directory designator
2279    (DIRECTORY-DESIGNATOR (:function TRANSLATION-FUNCTION))
2280
2281DIRECTORY-DESIGNATOR :=
2282    T | ;; as source matches anything, as destination leaves pathname unmapped.
2283    ABSOLUTE-COMPONENT-DESIGNATOR |
2284    (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...)
2285
2286ABSOLUTE-COMPONENT-DESIGNATOR :=
2287    NULL | ;; As source: skip this entry. As destination: same as source
2288    :ROOT | ;; magic: paths that are relative to the root of the source host and device
2289    STRING | ;; namestring (directory is assumed, better be absolute or bust, ``/**/*.*'' added)
2290    PATHNAME | ;; pathname (better be an absolute directory or bust)
2291    :HOME | ;; designates the user-homedir-pathname ~/
2292    :USER-CACHE | ;; designates the default location for the user cache
2293    :SYSTEM-CACHE ;; designates the default location for the system cache
2294
2295RELATIVE-COMPONENT-DESIGNATOR :=
2296    STRING | ;; namestring, directory is assumed. If the last component, /**/*.* is added
2297    PATHNAME | ;; pathname unless last component, directory is assumed.
2298    :IMPLEMENTATION | ;; a directory based on implementation, e.g. sbcl-1.0.32.30-linux-x86-64
2299    :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
2300    :UID | ;; current UID -- not available on Windows
2301    :USER ;; current USER name -- NOT IMPLEMENTED(!)
2302
2303TRANSLATION-FUNCTION :=
2304    SYMBOL | ;; symbol of a function that takes two arguments,
2305             ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
2306    LAMBDA   ;; A form which evalutates to a function taking two arguments consisting of
2307             ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR
2308
2309@end verbatim
2310
2311Relative components better be either relative
2312or subdirectories of the path before them, or bust.
2313
2314The last component, if not a pathname, is notionally completed by @file{/**/*.*}.
2315You can specify more fine-grained patterns
2316by using a pathname object as the last component
2317e.g. @file{#p"some/path/**/foo*/bar-*.fasl"}
2318
2319You may use @code{#+features} to customize the configuration file.
2320
2321The second designator of a mapping may be @code{NIL}, indicating that files are not mapped
2322to anything but themselves (same as if the second designator was the same as the first).
2323
2324When the first designator is @code{t},
2325the mapping always matches.
2326When the first designator starts with @code{:root},
2327the mapping matches any host and device.
2328In either of these cases, if the second designator
2329isn't @code{t} and doesn't start with @code{:root},
2330then strings indicating the host and pathname are somehow copied
2331in the beginning of the directory component of the source pathname
2332before it is translated.
2333
2334When the second designator is @code{t}, the mapping is the identity.
2335When the second designator starts with @code{root},
2336the mapping preserves the host and device of the original pathname.
2337
2338@code{:include} statements cause the search to recurse with the path specifications
2339from the file specified.
2340
2341If the @code{translate-pathname} mechanism cannot achieve a desired
2342translation, the user may provide a function which provides the
2343required algorithim.  Such a translation function is specified by
2344supplying a list as the second @code{directory-designator}
2345the first element of which is the keyword @code{:function},
2346and the second element of which is
2347either a symbol which designates a function or a lambda expression.
2348The function designated by the second argument must take two arguments,
2349the first being the pathname of the source file,
2350the second being the wildcard that was matched.
2351The result of the function invocation should be the translated pathname.
2352
2353An @code{:inherit-configuration} statement cause the search to recurse with the path
2354specifications from the next configuration.
2355@xref{Controlling where ASDF saves compiled files,,Configurations}, above.
2356
2357@itemize
2358@item
2359@code{:enable-user-cache} is the same as @code{(t :user-cache)}.
2360@item
2361@code{:disable-cache} is the same as @code{(t t)}.
2362@item
2363@code{:user-cache} uses the contents of variable @code{asdf::*user-cache*}
2364which by default is the same as using
2365@code{(:home ".cache" "common-lisp" :implementation)}.
2366@item
2367@code{:system-cache} uses the contents of variable @code{asdf::*system-cache*}
2368which by default is the same as using
2369@code{("/var/cache/common-lisp" :uid :implementation-type)}
2370(on Unix and cygwin), or something semi-sensible on Windows.
2371@end itemize
2372
2373
2374@section Configuration Directories
2375
2376Configuration directories consist in files each contains
2377a list of directives without any enclosing
2378@code{(:output-translations ...)} form.
2379The files will be sorted by namestring as if by @code{string<} and
2380the lists of directives of these files with be concatenated in order.
2381An implicit @code{:inherit-configuration} will be included
2382at the @emph{end} of the list.
2383
2384This allows for packaging software that has file granularity
2385(e.g. Debian's @command{dpkg} or some future version of @command{clbuild})
2386to easily include configuration information about software being distributed.
2387
2388The convention is that, for sorting purposes,
2389the names of files in such a directory begin with two digits
2390that determine the order in which these entries will be read.
2391Also, the type of these files is conventionally @code{"conf"}
2392and as a limitation of some implementations, the type cannot be @code{NIL}.
2393
2394Directories may be included by specifying a directory pathname
2395or namestring in an @code{:include} directive, e.g.:
2396@verbatim
2397  (:include "/foo/bar/")
2398@end verbatim
2399
2400@section Shell-friendly syntax for configuration
2401
2402When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS}
2403ASDF will skip to next configuration if it's an empty string.
2404It will @code{READ} the string as an SEXP in the DSL
2405if it begins with a paren @code{(}
2406and it will be interpreted as a list of directories.
2407Directories should come by pairs, indicating a mapping directive.
2408Entries are separated
2409by a @code{:} (colon) on Unix platforms (including cygwin),
2410by a @code{;} (semicolon) on other platforms (mainly, Windows).
2411
2412The magic empty entry,
2413if it comes in what would otherwise be the first entry in a pair,
2414indicates the splicing of inherited configuration.
2415If it comes as the second entry in a pair,
2416it indicates that the directory specified first is to be left untranslated
2417(which has the same effect as if the directory had been repeated).
2418
2419
2420@section Semantics of Output Translations
2421
2422From the specified configuration,
2423a list of mappings is extracted in a straightforward way:
2424mappings are collected in order, recursing through
2425included or inherited configuration as specified.
2426To this list is prepended some implementation-specific mappings,
2427and is appended a global default.
2428
2429The list is then compiled to a mapping table as follows:
2430for each entry, in order, resolve the first designated directory
2431into an actual directory pathname for source locations.
2432If no mapping was specified yet for that location,
2433resolve the second designated directory to an output location directory
2434add a mapping to the table mapping the source location to the output location,
2435and add another mapping from the output location to itself
2436(unless a mapping already exists for the output location).
2437
2438Based on the table, a mapping function is defined,
2439mapping source pathnames to output pathnames:
2440given a source pathname, locate the longest matching prefix
2441in the source column of the mapping table.
2442Replace that prefix by the corresponding output column
2443in the same row of the table, and return the result.
2444If no match is found, return the source pathname.
2445(A global default mapping the filesystem root to itself
2446may ensure that there will always be a match,
2447with same fall-through semantics).
2448
2449@section Caching Results
2450
2451The implementation is allowed to either eagerly compute the information
2452from the configurations and file system, or to lazily re-compute it
2453every time, or to cache any part of it as it goes.
2454To explicitly flush any information cached by the system, use the API below.
2455
2456
2457@section Output location API
2458
2459The specified functions are exported from package ASDF.
2460
2461@defun initialize-output-translations @&optional PARAMETER
2462   will read the configuration and initialize all internal variables.
2463   You may extend or override configuration
2464   from the environment and configuration files
2465   with the given @var{PARAMETER}, which can be
2466   @code{NIL} (no configuration override),
2467   or a SEXP (in the SEXP DSL),
2468   a string (as in the string DSL),
2469   a pathname (of a file or directory with configuration),
2470   or a symbol (fbound to function that when called returns one of the above).
2471@end defun
2472
2473@defun disable-output-translations
2474   will initialize output translations in a way
2475   that maps every pathname to itself,
2476   effectively disabling the output translation facility.
2477@end defun
2478
2479@defun clear-output-translations
2480   undoes any output translation configuration
2481   and clears any cache for the mapping algorithm.
2482   You might want to call this function
2483   (or better, @code{clear-configuration})
2484   before you dump an image that would be resumed
2485   with a different configuration,
2486   and return an empty configuration.
2487   Note that this does not include clearing information about
2488   systems defined in the current image, only about
2489   where to look for systems not yet defined.
2490@end defun
2491
2492@defun ensure-output-translations @&optional PARAMETER
2493   checks whether output translations have been initialized.
2494   If not, initialize them with the given @var{PARAMETER}.
2495   This function will be called before any attempt to operate on a system.
2496@end defun
2497
2498@defun apply-output-translations PATHNAME
2499   Applies the configured output location translations to @var{PATHNAME}
2500   (calls @code{ensure-output-translations} for the translations).
2501@end defun
2502
2503Every time you use ASDF's @code{output-files}, or
2504anything that uses it (that may compile, such as @code{operate}, @code{perform}, etc.),
2505@code{ensure-output-translations} is called with parameter NIL,
2506which the first time around causes your configuration to be read.
2507If you change a configuration file,
2508you need to explicitly @code{initialize-output-translations} again,
2509or maybe @code{clear-output-translations} (or @code{clear-configuration}),
2510which will cause the initialization to happen next time around.
2511
2512
2513@section Credits for output translations
2514
2515Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations},
2516and to Peter van Eynde for @code{Common Lisp Controller}.
2517
2518All bad design ideas and implementation bugs are to mine, not theirs.
2519But so are good design ideas and elegant implementation tricks.
2520
2521 --- Francois-Rene Rideau @email{fare@@tunes.org}
2522
2523@c @section Default locations
2524@c @findex output-files-for-system-and-operation
2525
2526@c The default binary location for each Lisp implementation
2527@c is a subdirectory of each source directory.
2528@c To account for different Lisps, Operating Systems, Implementation versions,
2529@c and so on, ASDF borrows code from SLIME
2530@c to create reasonable custom directory names.
2531@c Here are some examples:
2532
2533@c @itemize
2534@c @item
2535@c SBCL, version 1.0 on Mac OS X for intel: @code{sbcl-1.0-darwin-x86}
2536
2537@c @item
2538@c Franz Allegro, version 8.0, ANSI Common Lisp: @code{allegro-8.0a-macosx-x86}
2539
2540@c @item
2541@c Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: @code{allegro-8.1m-macosx-x86}
2542@c @end itemize
2543
2544@c By default, all output file pathnames will be relocated
2545@c to some thus-named subdirectory of @file{~/.cache/common-lisp/}.
2546
2547@c See the document @file{README.asdf-output-translations}
2548@c for a full specification on how to configure @code{asdf-output-translations}.
2549
2550@node  Error handling, Miscellaneous additional functionality, Controlling where ASDF saves compiled files, Top
2551@comment  node-name,  next,  previous,  up
2552@chapter Error handling
2553@findex SYSTEM-DEFINITION-ERROR
2554@findex OPERATION-ERROR
2555
2556@section ASDF errors
2557
2558If ASDF detects an incorrect system definition, it will signal a generalised instance of
2559@code{SYSTEM-DEFINITION-ERROR}.
2560
2561Operations may go wrong (for example when source files contain errors).
2562These are signalled using generalised instances of
2563@code{OPERATION-ERROR}.
2564
2565@section Compilation error and warning handling
2566@vindex *compile-file-warnings-behaviour*
2567@vindex *compile-file-errors-behavior*
2568
2569ASDF checks for warnings and errors when a file is compiled.
2570The variables @var{*compile-file-warnings-behaviour*} and
2571@var{*compile-file-errors-behavior*}
2572control the handling of any such events.
2573The valid values for these variables are
2574@code{:error}, @code{:warn}, and @code{:ignore}.
2575
2576@node  Miscellaneous additional functionality, Getting the latest version, Error handling, Top
2577@comment  node-name,  next,  previous,  up
2578@chapter Miscellaneous additional functionality
2579
2580@emph{FIXME:  Add discussion of @code{run-shell-command}?  Others?}
2581
2582ASDF includes several additional features that are generally
2583useful for system definition and development. These include:
2584
2585@defun system-relative-pathname system name @&key type
2586
2587It's often handy to locate a file relative to some system.
2588The @code{system-relative-pathname} function meets this need.
2589It takes two arguments: the name of a system and a relative pathname.
2590It returns a pathname built from the location of the system's source file
2591and the relative pathname. For example
2592
2593@lisp
2594> (asdf:system-relative-pathname 'cl-ppcre #p"regex.data")
2595#P"/repository/other/cl-ppcre/regex.data"
2596@end lisp
2597
2598Instead of a pathname, you can provide a symbol or a string,
2599and optionally a keyword argument @code{type}.
2600The arguments will then be interpreted in the same way
2601as pathname specifiers for components.
2602@xref{The defsystem grammar,,Pathname specifiers}.
2603@end defun
2604
2605@defun system-source-directory system-designator
2606
2607ASDF does not provide a turnkey solution for locating
2608data (or other miscellaneous) files
2609that are distributed together with the source code of a system.
2610Programmers can use @code{system-source-directory} to find such files.
2611Returns a pathname object.
2612The @var{system-designator} may be a string, symbol, or ASDF system object.
2613@end defun
2614
2615@defun clear-system system-designator
2616
2617It is sometimes useful to force recompilation of a previously loaded system.
2618In these cases, it may be useful to @code{(asdf:clear-system :foo)}
2619to remove the system from the table of currently loaded systems;
2620the next time the system @code{foo} or one that depends on it is re-loaded,
2621@code{foo} will then be loaded again.
2622Alternatively, you could touch @code{foo.asd} or
2623remove the corresponding fasls from the output file cache.
2624(It was once conceived that one should provide
2625a list of systems the recompilation of which to force
2626as the @code{:force} keyword argument to @code{load-system};
2627but this has never worked, and though the feature was fixed in ASDF 2.000,
2628it remains @code{cerror}'ed out as nobody ever used it.)
2629
2630Note that this does not and cannot by itself undo the previous loading
2631of the system. Common Lisp has no provision for such an operation,
2632and its reliance on irreversible side-effects to global datastructures
2633makes such a thing impossible in the general case.
2634If the software being re-loaded is not conceived with hot upgrade in mind,
2635this re-loading may cause many errors, warnings or subtle silent problems,
2636as packages, generic function signatures, structures, types, macros, constants, etc.
2637are being redefined incompatibly.
2638It is up to the user to make sure that reloading is possible and has the desired effect.
2639In some cases, extreme measures such as recursively deleting packages,
2640unregistering symbols, defining methods on @code{update-instance-for-redefined-class}
2641and much more are necessary for reloading to happen smoothly.
2642ASDF itself goes through notable pains to make such a hot upgrade possible
2643with respect to its own code, and what it does is ridiculously complex;
2644look at the beginning of @file{asdf.lisp} to see what it does.
2645@end defun
2646
2647@node Getting the latest version, FAQ, Miscellaneous additional functionality, Top
2648@comment  node-name,  next,  previous,  up
2649@chapter Getting the latest version
2650
2651Decide which version you want.
2652HEAD is the newest version and usually OK, whereas
2653RELEASE is for cautious people
2654(e.g. who already have systems using ASDF that they don't want broken),
2655a slightly older version about which none of the HEAD users have complained.
2656There is also a STABLE version, which is earlier than release.
2657
2658You may get the ASDF source repository using git:
2659@kbd{git clone git://common-lisp.net/projects/asdf/asdf.git}
2660
2661You will find the above referenced tags in this repository.
2662You can also browse the repository on
2663@url{http://common-lisp.net/gitweb?p=projects/asdf/asdf.git}.
2664
2665Discussion of ASDF development is conducted on the
2666mailing list
2667@kbd{asdf-devel@@common-lisp.net}.
2668@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel}
2669
2670
2671@node FAQ, TODO list, Getting the latest version, Top
2672@comment  node-name,  next,  previous,  up
2673@chapter FAQ
2674
2675@section  ``Where do I report a bug?''
2676
2677ASDF bugs are tracked on launchpad: @url{https://launchpad.net/asdf}.
2678
2679If you're unsure about whether something is a bug, or for general discussion,
2680use the @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
2681
2682
2683@section ``What has changed between ASDF 1 and ASDF 2?''
2684
2685@subsection What are ASDF 1 and ASDF 2?
2686
2687On May 31st 2010, we have released ASDF 2.
2688ASDF 2 refers to release 2.000 and later.
2689(Releases between 1.656 and 1.728 were development releases for ASDF 2.)
2690ASDF 1 to any release earlier than 1.369 or so.
2691If your ASDF doesn't sport a version, it's an old ASDF 1.
2692
2693ASDF 2 and its release candidates push
2694@code{:asdf2} onto @code{*features*} so that if you are writing
2695ASDF-dependent code you may check for this feature
2696to see if the new API is present.
2697@emph{All} versions of ASDF should have the @code{:asdf} feature.
2698
2699If you are experiencing problems or limitations of any sort with ASDF 1,
2700we recommend that you should upgrade to ASDF 2,
2701or whatever is the latest release.
2702
2703
2704@subsection ASDF can portably name files in subdirectories
2705
2706Common Lisp namestrings are not portable,
2707except maybe for logical pathnamestrings,
2708that themselves have various limitations and require a lot of setup
2709that is itself ultimately non-portable.
2710
2711In ASDF 1, the only portable ways to refer to pathnames inside systems and components
2712were very awkward, using @code{#.(make-pathname ...)} and
2713@code{#.(merge-pathnames ...)}.
2714Even the above were themselves were inadequate in the general case
2715due to host and device issues, unless horribly complex patterns were used.
2716Plenty of simple cases that looked portable actually weren't,
2717leading to much confusion and greavance.
2718
2719ASDF 2 implements its own portable syntax for strings as pathname specifiers.
2720Naming files within a system definition becomes easy and portable again.
2721@xref{Miscellaneous additional functionality,asdf:system-relative-pathname},
2722@code{asdf-utilities:merge-pathnames*},
2723@code{asdf::merge-component-name-type}.
2724
2725On the other hand, there are places where systems used to accept namestrings
2726where you must now use an explicit pathname object:
2727@code{(defsystem ... :pathname "LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
2728must now be written with the @code{#p} syntax:
2729@code{(defsystem ... :pathname #p"LOGICAL-HOST:PATH;TO;SYSTEM;" ...)}
2730
2731@xref{The defsystem grammar,,Pathname specifiers}.
2732
2733
2734@subsection Output translations
2735
2736A popular feature added to ASDF was output pathname translation:
2737@code{asdf-binary-locations}, @code{common-lisp-controller},
2738@code{cl-launch} and other hacks were all implementing it in ways
2739both mutually incompatible and difficult to configure.
2740
2741Output pathname translation is essential to share
2742source directories of portable systems across multiple implementations
2743or variants thereof,
2744or source directories of shared installations of systems across multiple users,
2745or combinations of the above.
2746
2747In ASDF 2, a standard mechanism is provided for that,
2748@code{asdf-output-translations},
2749with sensible defaults, adequate configuration languages,
2750a coherent set of configuration files and hooks,
2751and support for non-Unix platforms.
2752
2753@xref{Controlling where ASDF saves compiled files}.
2754
2755@subsection Source Registry Configuration
2756
2757Configuring ASDF used to require special magic
2758to be applied just at the right moment,
2759between the moment ASDF is loaded and the moment it is used,
2760in a way that is specific to the user,
2761the implementation he is using and the application he is building.
2762
2763This made for awkward configuration files and startup scripts
2764that could not be shared between users, managed by administrators
2765or packaged by distributions.
2766
2767ASDF 2 provides a well-documented way to configure ASDF,
2768with sensible defaults, adequate configuration languages,
2769and a coherent set of configuration files and hooks.
2770
2771We believe it's a vast improvement because it decouples
2772application distribution from library distribution.
2773The application writer can avoid thinking where the libraries are,
2774and the library distributor (dpkg, clbuild, advanced user, etc.)
2775can configure them once and for every application.
2776Yet settings can be easily overridden where needed,
2777so whoever needs control has exactly as much as required.
2778
2779At the same time, ASDF 2 remains compatible
2780with the old magic you may have in your build scripts
2781(using @code{*central-registry*} and
2782@code{*system-definition-search-functions*})
2783to tailor the ASDF configuration to your build automation needs,
2784and also allows for new magic, simpler and more powerful magic.
2785
2786@xref{Controlling where ASDF searches for systems}.
2787
2788
2789@subsection Usual operations are made easier to the user
2790
2791In ASDF 1, you had to use the awkward syntax
2792@code{(asdf:oos 'asdf:load-op :foo)}
2793to load a system,
2794and similarly for @code{compile-op}, @code{test-op}.
2795
2796In ASDF 2, you can use shortcuts for the usual operations:
2797@code{(asdf:load-system :foo)}, and
2798similarly for @code{compile-system}, @code{test-system}.
2799
2800
2801@subsection Many bugs have been fixed
2802
2803The following issues and many others have been fixed:
2804
2805@itemize
2806@item
2807The infamous TRAVERSE function has been revamped significantly,
2808with many bugs squashed.
2809In particular, dependencies were not correctly propagated
2810across submodules within a system but now are.
2811The :version and :feature features and
2812the :force (system1 .. systemN) feature have been fixed.
2813
2814@item
2815Performance has been notably improved for large systems
2816(say with thousands of components) by using
2817hash-tables instead of linear search,
2818and linear-time list accumulation
2819instead of quadratic-time recursive appends.
2820
2821@item
2822Many features used to not be portable,
2823especially where pathnames were involved.
2824Windows support was notably quirky because of such non-portability.
2825
2826@item
2827The internal test suite used to massively fail on many implementations.
2828While still incomplete, it now fully passes
2829on all implementations supported by the test suite,
2830except for GCL (due to GCL bugs).
2831
2832@item
2833Support was lacking for some implementations.
2834ABCL and GCL were notably wholly broken.
2835ECL extensions were not integrated in the ASDF release.
2836
2837@item
2838The documentation was grossly out of date.
2839
2840@end itemize
2841
2842
2843@subsection ASDF itself is versioned
2844
2845Between new features, old bugs fixed, and new bugs introduced,
2846there were various releases of ASDF in the wild,
2847and no simple way to check which release had which feature set.
2848People using or writing systems had to either make worst-case assumptions
2849as to what features were available and worked,
2850or take great pains to have the correct version of ASDF installed.
2851
2852With ASDF 2, we provide a new stable set of working features
2853that everyone can rely on from now on.
2854Use @code{#+asdf2} to detect presence of ASDF 2,
2855@code{(asdf:version-satisfies (asdf:asdf-version) "2.000")}
2856to check the availability of a version no earlier than required.
2857
2858
2859@subsection ASDF can be upgraded
2860
2861When an old version of ASDF was loaded,
2862it was very hard to upgrade ASDF in your current image
2863without breaking everything.
2864Instead you have to exit the Lisp process and
2865somehow arrange to start a new one from a simpler image.
2866Something that can't be done from within Lisp,
2867making automation of it difficult,
2868which compounded with difficulty in configuration,
2869made the task quite hard.
2870Yet as we saw before, the task would have been required
2871to not have to live with the worst case or non-portable
2872subset of ASDF features.
2873
2874With ASDF 2, it is easy to upgrade
2875from ASDF 2 to later versions from within Lisp,
2876and not too hard to upgrade from ASDF 1 to ASDF 2 from within Lisp.
2877We support hot upgrade of ASDF and any breakage is a bug
2878that we will do our best to fix.
2879There are still limitations on upgrade, though,
2880most notably the fact that after you upgrade ASDF,
2881you must also reload or upgrade all ASDF extensions.
2882
2883@subsection Decoupled release cycle
2884
2885When vendors were releasing their Lisp implementations with ASDF,
2886they had to basically never change version
2887because neither upgrade nor downgrade was possible
2888without breaking something for someone,
2889and no obvious upgrade path was visible and recommendable.
2890
2891With ASDF 2, upgrade is possible, easy and can be recommended.
2892This means that vendors can safely ship a recent version of ASDF,
2893confident that if a user isn't fully satisfied,
2894he can easily upgrade ASDF and deal
2895with a supported recent version of it.
2896This means that release cycles will be causally decoupled,
2897the practical consequence of which will mean faster convergence
2898towards the latest version for everyone.
2899
2900
2901@subsection Pitfalls of the transition to ASDF 2
2902
2903The main pitfalls in upgrading to ASDF 2 seem to be related
2904to the output translation mechanism.
2905
2906@itemize
2907
2908@item
2909Output translations is enabled by default. This may surprise some users,
2910most of them in pleasant way (we hope), a few of them in an unpleasant way.
2911It is trivial to disable output translations.
2912@xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
2913
2914@item
2915Some systems in the large have been known not to play well with output translations.
2916They were relatively easy to fix.
2917Once again, it is also easy to disable output translations,
2918or to override its configuration.
2919
2920@item
2921The new ASDF output translations are incompatible with ASDF-Binary-Locations.
2922They replace A-B-L, and there is compatibility mode to emulate
2923your previous A-B-L configuration.
2924See @code{asdf:enable-asdf-binary-locations-compatibility} in
2925@pxref{Controlling where ASDF saves compiled files,,Backward Compatibility}.
2926But thou shall not load ABL on top of ASDF 2.
2927
2928@end itemize
2929
2930Other issues include the following:
2931
2932@itemize
2933
2934@item
2935ASDF pathname designators are now specified in places where they were unspecified,
2936and a few small adjustments have to be made to some non-portable defsystems.
2937Notably, in the @code{:pathname} argument to a @code{defsystem} and its components,
2938a logical pathname (or implementation-dependent hierarchical pathname)
2939must now be specified with @code{#p} syntax
2940where the namestring might have previously sufficed;
2941moreover when evaluation is desired @code{#.} must be used,
2942where it wasn't necessary in the toplevel @code{:pathname} argument.
2943
2944@item
2945There is a slight performance bug, notably on SBCL,
2946when initially searching for @file{asd} files,
2947the implicit @code{(directory "/configured/path/**/*.asd")}
2948for every configured path @code{(:tree "/configured/path/")}
2949in your @code{source-registry} configuration can cause a slight pause.
2950Try to @code{(time (asdf:initialize-source-registry))}
2951to see how bad it is or isn't on your system.
2952If you insist on not having this pause,
2953you can avoid the pause by overriding the default source-registry configuration
2954and not use any deep @code{:tree} entry but only @code{:directory} entries
2955or shallow @code{:tree} entries.
2956Or you can fix your implementation to not be quite that slow
2957when recursing through directories.
2958
2959@item
2960On Windows, only LispWorks supports proper default configuration pathnames
2961based on the Windows registry.
2962Other implementations make do with environment variables.
2963Windows support is somewhat less tested than Unix support.
2964Please help report and fix bugs.
2965
2966@item
2967The mechanism by which one customizes a system so that Lisp files
2968may use a different extension from the default @file{.lisp} has changed.
2969Previously, the pathname for a component was lazily computed when operating on a system,
2970and you would
2971@code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
2972  (declare (ignorable component system)) "cl")}.
2973Now, the pathname for a component is eagerly computed when defining the system,
2974and instead you will @code{(defclass my-cl-source-file (cl-source-file) ((type :iniform "cl")))}
2975and use @code{:default-component-class my-cl-source-file} as argument to @code{defsystem},
2976as detailed in a @pxref{FAQ,How do I create a system definition where all the source files have a .cl extension?} below.
2977
2978@findex source-file-type
2979
2980
2981@end itemize
2982
2983
2984@section Issues with installing the proper version of ASDF
2985
2986@subsection ``My Common Lisp implementation comes with an outdated version of ASDF. What to do?''
2987
2988We recommend you upgrade ASDF.
2989@xref{Loading ASDF,,Upgrading ASDF}.
2990
2991If this does not work, it is a bug, and you should report it.
2992@xref{FAQ, report-bugs, Where do I report a bug}.
2993In the meantime, you can load @file{asdf.lisp} directly.
2994@xref{Loading ASDF,Loading an otherwise installed ASDF}.
2995
2996
2997@subsection ``I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?''
2998
2999Starting with current candidate releases of ASDF 2,
3000it should always be a good time to upgrade to a recent ASDF.
3001You may consult with the maintainer for which specific version they recommend,
3002but the latest RELEASE should be correct.
3003We trust you to thoroughly test it with your implementation before you release it.
3004If there are any issues with the current release,
3005it's a bug that you should report upstream and that we will fix ASAP.
3006
3007As to how to include ASDF, we recommend the following:
3008
3009@itemize
3010@item
3011If ASDF isn't loaded yet, then @code{(require :asdf)}
3012should load the version of ASDF that is bundled with your system.
3013You may have it load some other version configured by the user,
3014if you allow such configuration.
3015
3016@item
3017If your system provides a mechanism to hook into @code{CL:REQUIRE},
3018then it would be nice to add ASDF to this hook the same way that
3019ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it.
3020
3021@item
3022You may, like SBCL, have ASDF be implicitly used to require systems
3023that are bundled with your Lisp distribution.
3024If you do have a few magic systems that come with your implementation
3025in a precompiled way such that one should only use the binary version
3026that goes with your distribution, like SBCL does,
3027then you should add them in the beginning of @code{wrapping-source-registry}.
3028
3029@item
3030If you have magic systems as above, like SBCL does,
3031then we explicitly ask you to @emph{NOT} distribute
3032@file{asdf.asd} as part of those magic systems.
3033You should still include the file @file{asdf.lisp} in your source distribution
3034and precompile it in your binary distribution,
3035but @file{asdf.asd} if included at all,
3036should be secluded from the magic systems,
3037in a separate file hierarchy;
3038alternatively, you may provide the system
3039after renaming it and its @file{.asd} file to e.g.
3040@code{asdf-ecl} and @file{asdf-ecl.asd}, or
3041@code{sb-asdf} and @file{sb-asdf.asd}.
3042Indeed, if you made @file{asdf.asd} a magic system,
3043then users would no longer be able to upgrade ASDF using ASDF itself
3044to some version of their preference that
3045they maintain independently from your Lisp distribution.
3046
3047@item
3048If you do not have any such magic systems, or have other non-magic systems
3049that you want to bundle with your implementation,
3050then you may add them to the @code{default-source-registry},
3051and you are welcome to include @file{asdf.asd} amongst them.
3052
3053@item
3054Please send us upstream any patches you make to ASDF itself,
3055so we can merge them back in for the benefit of your users
3056when they upgrade to the upstream version.
3057
3058@end itemize
3059
3060
3061
3062@section Issues with configuring ASDF
3063
3064@subsection ``How can I customize where fasl files are stored?''
3065
3066@xref{Controlling where ASDF saves compiled files}.
3067
3068Note that in the past there was an add-on to ASDF called
3069@code{ASDF-binary-locations}, developed by Gary King.
3070That add-on has been merged into ASDF proper,
3071then superseded by the @code{asdf-output-translations} facility.
3072
3073Note that use of @code{asdf-output-translations}
3074can interfere with one aspect of your systems
3075--- if your system uses @code{*load-truename*} to find files
3076(e.g., if you have some data files stored with your program),
3077then the relocation that this ASDF customization performs
3078is likely to interfere.
3079Use @code{asdf:system-relative-pathname} to locate a file
3080in the source directory of some system, and
3081use @code{asdf:apply-output-translations} to locate a file
3082whose pathname has been translated by the facility.
3083
3084@subsection ``How can I wholly disable the compiler output cache?''
3085
3086To permanently disable the compiler output cache
3087for all future runs of ASDF, you can:
3088
3089@example
3090mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/
3091echo ':disable-cache' > ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
3092@end example
3093
3094This assumes that you didn't otherwise configure the ASDF files
3095(if you did, edit them again),
3096and don't somehow override the configuration at runtime
3097with a shell variable (see below) or some other runtime command
3098(e.g. some call to @code{asdf:initialize-output-translations}).
3099
3100To disable the compiler output cache in Lisp processes
3101run by your current shell, try (assuming @code{bash} or @code{zsh})
3102(on Unix and cygwin only):
3103
3104@example
3105export ASDF_OUTPUT_TRANSLATIONS=/:
3106@end example
3107
3108To disable the compiler output cache just in the current Lisp process,
3109use (after loading ASDF but before using it):
3110
3111@example
3112(asdf:disable-output-translations)
3113@end example
3114
3115@section Issues with using and extending ASDF to define systems
3116
3117@subsection ``How can I cater for unit-testing in my system?''
3118
3119ASDF provides a predefined test operation, @code{test-op}.
3120@xref{Predefined operations of ASDF, test-op}.
3121The test operation, however, is largely left to the system definer to specify.
3122@code{test-op} has been
3123a topic of considerable discussion on the
3124@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list},
3125and on the
3126@url{https://launchpad.net/asdf,launchpad bug-tracker}.
3127
3128Here are some guidelines:
3129
3130@itemize
3131@item
3132For a given system, @var{foo}, you will want to define a corresponding
3133test system, such as @var{foo-test}.  The reason that you will want this
3134separate system is that ASDF does not out of the box supply components
3135that are conditionally loaded.  So if you want to have source files
3136(with the test definitions) that will not be loaded except when testing,
3137they should be put elsewhere.
3138
3139@item
3140The @var{foo-test} system can be defined in an asd file of its own or
3141together with @var{foo}.  An aesthetic preference against cluttering up
3142the filesystem with extra asd files should be balanced against the
3143question of whether one might want to directly load @var{foo-test}.
3144Typically one would not want to do this except in early stages of
3145debugging.
3146
3147@item
3148Record that testing is implemented by @var{foo-test}.  For example:
3149@example
3150(defsystem @var{foo}
3151   :in-order-to ((test-op (test-op @var{foo-test})))
3152   ....)
3153
3154(defsystem @var{foo-test}
3155   :depends-on (@var{foo} @var{my-test-library} ...)
3156   ....)
3157@end example
3158@end itemize
3159
3160This procedure will allow you to support users who do not wish to
3161install your test framework.
3162
3163One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
3164does not return a value.  So in current versions of ASDF there is no
3165reliable programmatic means of determining whether or not a set of tests
3166has passed, or which tests have failed.  The user must simply read the
3167console output.  This limitation has been the subject of much
3168discussion.
3169
3170@subsection ``How can I cater for documentation generation in my system?''
3171
3172The ASDF developers are currently working to add a @code{doc-op}
3173to the set of predefined ASDF operations.
3174@xref{Predefined operations of ASDF}.
3175See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
3176
3177
3178
3179@subsection ``How can I maintain non-Lisp (e.g. C) source files?''
3180
3181See @code{cffi}'s @code{cffi-grovel}.
3182
3183@anchor{report-bugs}
3184
3185
3186@subsection ``I want to put my module's files at the top level.  How do I do this?''
3187
3188By default, the files contained in an asdf module go
3189in a subdirectory with the same name as the module.
3190However, this can be overridden by adding a @code{:pathname ""} argument
3191to the module description.
3192For example, here is how it could be done
3193in the spatial-trees ASDF system definition for ASDF 2:
3194
3195@example
3196(asdf:defsystem :spatial-trees
3197  :components
3198  ((:module base
3199            :pathname ""
3200            :components
3201            ((:file "package")
3202             (:file "basedefs" :depends-on ("package"))
3203             (:file "rectangles" :depends-on ("package"))))
3204   (:module tree-impls
3205            :depends-on (base)
3206            :pathname ""
3207            :components
3208            ((:file "r-trees")
3209             (:file "greene-trees" :depends-on ("r-trees"))
3210             (:file "rstar-trees" :depends-on ("r-trees"))
3211             (:file "rplus-trees" :depends-on ("r-trees"))
3212             (:file "x-trees" :depends-on ("r-trees" "rstar-trees"))))
3213   (:module viz
3214            :depends-on (base)
3215            :pathname ""
3216            :components
3217            ((:static-file "spatial-tree-viz.lisp")))
3218   (:module tests
3219            :depends-on (base)
3220            :pathname ""
3221            :components
3222            ((:static-file "spatial-tree-test.lisp")))
3223   (:static-file "LICENCE")
3224   (:static-file "TODO")))
3225@end example
3226
3227All of the files in the @code{tree-impls} module are at the top level,
3228instead of in a @file{tree-impls/} subdirectory.
3229
3230Note that the argument to @code{:pathname} can be either a pathname object or a string.
3231A pathname object can be constructed with the @file{#p"foo/bar/"} syntax,
3232but this is discouraged because the results of parsing a namestring are not portable.
3233A pathname can only be portably constructed with such syntax as
3234@code{#.(make-pathname :directory '(:relative "foo" "bar"))},
3235and similarly the current directory can only be portably specified as
3236@code{#.(make-pathname :directory '(:relative))}.
3237However, as of ASDF 2, you can portably use a string to denote a pathname.
3238The string will be parsed as a @code{/}-separated path from the current directory,
3239such that the empty string @code{""} denotes the current directory, and
3240@code{"foo/bar"} (no trailing @code{/} required in the case of modules)
3241portably denotes the same subdirectory as above.
3242When files are specified, the last @code{/}-separated component is interpreted
3243either as the name component of a pathname
3244(if the component class specifies a pathname type),
3245or as a name component plus optional dot-separated type component
3246(if the component class doesn't specifies a pathname type).
3247
3248@subsection How do I create a system definition where all the source files have a .cl extension?
3249
3250First, create a new @code{cl-source-file} subclass that provides an
3251initform for the @code{type} slot:
3252
3253@lisp
3254(defclass my-cl-source-file (cl-source-file)
3255   ((type :initform "cl")))
3256@end lisp
3257
3258To support both ASDF 1 and ASDF 2,
3259you may omit the above @code{type} slot definition and instead define:
3260
3261@lisp
3262(defmethod source-file-type ((f my-cl-source-file) (m module))
3263  (declare (ignorable f m))
3264  "cl")
3265@end lisp
3266
3267Then make your system use this subclass in preference to the standard
3268one:
3269
3270@lisp
3271(defsystem my-cl-system
3272  :default-component-class my-cl-source-file
3273   ....
3274)
3275@end lisp
3276
3277We assume that these definitions are loaded into a package that uses
3278@code{ASDF}.
3279
3280
3281
3282@node  TODO list, Inspiration, FAQ, Top
3283@comment  node-name,  next,  previous,  up
3284@chapter TODO list
3285
3286Here is an old list of things to do,
3287in addition to the bugs that are now tracked on launchpad:
3288@url{https://launchpad.net/asdf}.
3289
3290@section Outstanding spec questions, things to add
3291
3292** packaging systems
3293
3294*** manual page component?
3295
3296** style guide for .asd files
3297
3298You should either use keywords or be careful
3299with the package that you evaluate defsystem forms in.
3300Otherwise @code{(defsystem partition ...)}
3301being read in the @code{cl-user} package
3302will intern a @code{cl-user:partition} symbol,
3303which will then collide with the @code{partition:partition} symbol.
3304
3305Actually there's a hairier packages problem to think about too.
3306@code{in-order-to} is not a keyword:
3307if you read @code{defsystem} forms in a package that doesn't use ASDF,
3308odd things might happen.
3309
3310
3311** extending defsystem with new options
3312
3313You might not want to write a whole parser,
3314but just to add options to the existing syntax.
3315Reinstate @code{parse-option} or something akin.
3316
3317
3318** document all the error classes
3319
3320** what to do with compile-file failure
3321
3322Should check the primary return value from compile-file and see if
3323that gets us any closer to a sensible error handling strategy
3324
3325** foreign files
3326
3327lift unix-dso stuff from db-sockets
3328
3329** Diagnostics
3330
3331A ``dry run'' of an operation can be made with the following form:
3332
3333@lisp
3334(traverse (make-instance '<operation-name>)
3335          (find-system <system-name>)
3336          'explain)
3337@end lisp
3338
3339This uses unexported symbols.
3340What would be a nice interface for this functionality?
3341
3342@section Missing bits in implementation
3343
3344** reuse the same scratch package whenever a system is reloaded from disk
3345
3346** proclamations probably aren't
3347
3348** when a system is reloaded with fewer components than it previously had, odd things happen
3349
3350We should do something inventive when processing a @code{defsystem} form,
3351like take the list of kids and @code{setf} the slot to @code{nil},
3352then transfer children from old to new list as they're found.
3353
3354** (stuff that might happen later)
3355
3356*** Propagation of the @code{:force} option.
3357
3358``I notice that
3359
3360        @code{(asdf:compile-system :araneida :force t)}
3361
3362also forces compilation of every other system the @code{:araneida} system depends on.
3363This is rarely useful to me;
3364usually, when I want to force recompilation of something more than a single source file,
3365I want to recompile only one system.
3366So it would be more useful to have @code{make-sub-operation}
3367refuse to propagate @code{:force t} to other systems, and
3368propagate only something like @code{:force :recursively}.
3369
3370Ideally what we actually want is some kind of criterion that says
3371to which systems (and which operations) a @code{:force} switch will propagate.
3372
3373The problem is perhaps that ``force'' is a pretty meaningless concept.
3374How obvious is it that @code{load :force t} should force @emph{compilation}?
3375But we don't really have the right dependency setup
3376for the user to compile @code{:force t} and expect it to work
3377(files will not be loaded after compilation, so the compile
3378environment for subsequent files will be emptier than it needs to be)
3379
3380What does the user actually want to do when he forces?
3381Usually, for me, update for use with a new version of the Lisp compiler.
3382Perhaps for recovery when he suspects that something has gone wrong.
3383Or else when he's changed compilation options or configuration
3384in some way that's not reflected in the dependency graph.
3385
3386Other possible interface: have a ``revert'' function akin to @code{make clean}.
3387
3388@lisp
3389(asdf:revert 'asdf:compile-op 'araneida)
3390@end lisp
3391
3392would delete any files produced by @code{(compile-system :araneida)}.
3393Of course, it wouldn't be able to do much about stuff in the image itself.
3394
3395How would this work?
3396
3397@code{traverse}
3398
3399There's a difference between a module's dependencies (peers)
3400and its components (children).
3401Perhaps there's a similar difference in operations?
3402For example, @code{(load "use") depends-on (load "macros")} is a peer,
3403whereas @code{(load "use") depends-on (compile "use")}
3404is more of a ``subservient'' relationship.
3405
3406@node  Inspiration, Concept Index, TODO list, Top
3407@comment  node-name,  next,  previous,  up
3408@chapter Inspiration
3409
3410@section mk-defsystem (defsystem-3.x)
3411
3412We aim to solve basically the same problems as @code{mk-defsystem} does.
3413However, our architecture for extensibility
3414better exploits CL language features (and is documented),
3415and we intend to be portable rather than just widely-ported.
3416No slight on the @code{mk-defsystem} authors and maintainers is intended here;
3417that implementation has the unenviable task
3418of supporting pre-ANSI implementations, which is no longer necessary.
3419
3420The surface defsystem syntax of asdf is more-or-less compatible with
3421@code{mk-defsystem}, except that we do not support
3422the @code{source-foo} and @code{binary-foo} prefixes
3423for separating source and binary files, and
3424we advise the removal of all options to specify pathnames.
3425
3426The @code{mk-defsystem} code for topologically sorting
3427a module's dependency list was very useful.
3428
3429@section defsystem-4 proposal
3430
3431Marco and Peter's proposal for defsystem 4 served as the driver for
3432many of the features in here.  Notable differences are:
3433
3434@itemize
3435@item
3436We don't specify output files or output file extensions
3437as part of the system.
3438
3439If you want to find out what files an operation would create,
3440ask the operation.
3441
3442@item
3443We don't deal with CL packages
3444
3445If you want to compile in a particular package, use an @code{in-package} form
3446in that file (ilisp / SLIME will like you more if you do this anyway)
3447
3448@item
3449There is no proposal here that @code{defsystem} does version control.
3450
3451A system has a given version which can be used to check dependencies,
3452but that's all.
3453@end itemize
3454
3455The defsystem 4 proposal tends to look more at the external features,
3456whereas this one centres on a protocol for system introspection.
3457
3458@section kmp's ``The Description of Large Systems'', MIT AI Memo 801
3459
3460Available in updated-for-CL form on the web at
3461@url{http://nhplace.com/kent/Papers/Large-Systems.html}
3462
3463In our implementation we borrow kmp's overall @code{PROCESS-OPTIONS}
3464and concept to deal with creating component trees
3465from @code{defsystem} surface syntax.
3466[ this is not true right now, though it used to be and
3467probably will be again soon ]
3468
3469
3470@c -------------------
3471
3472
3473@node Concept Index, Function and Class Index, Inspiration, Top
3474@unnumbered Concept Index
3475
3476@printindex cp
3477
3478@node Function and Class Index, Variable Index, Concept Index, Top
3479@unnumbered Function and Class Index
3480
3481@printindex fn
3482
3483@node Variable Index,  , Function and Class Index, Top
3484@unnumbered Variable Index
3485
3486@printindex vr
3487
3488@bye
Note: See TracBrowser for help on using the repository browser.