1 \input texinfo @c -*- texinfo -*-
8 This manual describes asdf, a system definition facility for Common
9 Lisp programs and libraries.
11 asdf Copyright @copyright{} 2001-2004 Daniel Barlow and contributors
13 This manual Copyright @copyright{} 2001-2004 Daniel Barlow and
16 Permission is hereby granted, free of charge, to any person obtaining
17 a copy of this software and associated documentation files (the
18 ``Software''), to deal in the Software without restriction, including
19 without limitation the rights to use, copy, modify, merge, publish,
20 distribute, sublicense, and/or sell copies of the Software, and to
21 permit persons to whom the Software is furnished to do so, subject to
22 the following conditions:
24 The above copyright notice and this permission notice shall be
25 included in all copies or substantial portions of the Software.
27 THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
28 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
29 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
30 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
31 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
32 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
33 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
40 @title asdf: another system definition facility
42 @c The following two commands start the copyright page.
44 @vskip 0pt plus 1filll
48 @c Output the table of contents at the beginning.
51 @c -------------------
55 @node Top, Using asdf to load systems, (dir), (dir)
56 @top asdf: another system definition facility
61 * Using asdf to load systems::
62 * Defining systems with defsystem::
63 * The object model of asdf::
65 * Compilation error and warning handling::
66 * Getting the latest version::
68 * missing bits in implementation::
71 * Function and Class Index::
75 --- The Detailed Node Listing ---
77 Defining systems with defsystem
79 * The defsystem form::
80 * A more involved example::
81 * The defsystem grammar::
83 The object model of asdf
90 * Predefined operations of asdf::
91 * Creating new operations::
95 * Common attributes of components::
96 * Pre-defined subclasses of component::
97 * Creating new component types::
101 * Pre-defined subclasses of component::
102 * Creating new component types::
109 @c -------------------
112 @node Using asdf to load systems, Defining systems with defsystem, Top, Top
113 @comment node-name, next, previous, up
114 @chapter Using asdf to load systems
115 @cindex system directory designator
116 @vindex *central-registry*
118 This chapter describes how to use asdf to compile and load ready-made
119 Lisp programs and libraries.
121 @section Downloading asdf
123 Some Lisp implementations (such as SBCL and OpenMCL) come with asdf
124 included already, so you don't need to download it separately.
125 Consult your Lisp system's documentation. If you need to download
126 asdf and install it by hand, the canonical source is the cCLan CVS
128 @url{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/}.
130 @section Setting up asdf
132 The single file @file{asdf.lisp} is all you need to use asdf normally.
133 Once you load it in a running Lisp, you're ready to use asdf. For
134 maximum convenience you might want to have asdf loaded whenever you
135 start your Lisp implementation, for example by loading it from the
136 startup script or dumping a custom core -- check your Lisp
137 implementation's manual for details.
139 The variable @code{asdf:*central-registry*} is a list of ``system
140 directory designators''@footnote{When we say ``directory'' here, we
141 mean ``designator for a pathname with a supplied DIRECTORY
142 component''.}. A @dfn{system directory designator} is a form which
143 will be evaluated whenever a system is to be found, and must evaluate
144 to a directory to look in. You might want to set or augment
145 @code{*central-registry*} in your Lisp init file, for example:
148 (setf asdf:*central-registry*
149 (list* '*default-pathname-defaults*
150 #p"/home/me/cl/systems/"
151 #p"/usr/share/common-lisp/systems/"
152 asdf:*central-registry*))
155 @section Setting up a system to be loaded
157 To compile and load a system, you need to ensure that a symbolic link to its
158 system definition is in one of the directories in
159 @code{*central-registry*}@footnote{It is possible to customize the
160 system definition file search. That's considered advanced use, and
161 covered later: search forward for
162 @code{*system-definition-search-functions*}. @xref{Defining systems
165 For example, if @code{#p"/home/me/cl/systems/"} (note the trailing
166 slash) is a member of @code{*central-registry*}, you would set up a
167 system @var{foo} that is stored in a directory
168 @file{/home/me/src/foo/} for loading with asdf with the following
169 commands at the shell (this has to be done only once):
172 $ cd /home/me/cl/systems/
173 $ ln -s ~/src/foo/foo.asd .
176 @section Loading a system
178 The system @var{foo} is loaded (and compiled, if necessary) by
179 evaluating the following form in your Lisp implementation:
182 (asdf:operate 'asdf:load-op '@var{foo})
185 That's all you need to know to use asdf to load systems written by
186 others. The rest of this manual deals with writing system
187 definitions for Lisp software you write yourself.
189 @node Defining systems with defsystem, The object model of asdf, Using asdf to load systems, Top
190 @comment node-name, next, previous, up
191 @chapter Defining systems with defsystem
193 This chapter describes how to use asdf to define systems and develop
198 * The defsystem form::
199 * A more involved example::
200 * The defsystem grammar::
203 @node The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
204 @comment node-name, next, previous, up
205 @section The defsystem form
207 Systems can be constructed programmatically by instantiating
208 components using make-instance. Most of the time, however, it is much
209 more practical to use a static @code{defsystem} form. This section
210 begins with an example of a system definition, then gives the full
211 grammar of @code{defsystem}.
213 Let's look at a simple system. This is a complete file that would
214 usually be saved as @file{hello-lisp.asd}:
217 (defpackage hello-lisp-system
218 (:use :common-lisp :asdf))
220 (in-package :hello-lisp-system)
222 (defsystem "hello-lisp"
223 :description "hello-lisp: a sample Lisp system."
225 :author "Joe User <joe@@example.com>"
226 :licence "Public Domain"
227 :components ((:file "packages")
228 (:file "macros" :depends-on ("packages"))
229 (:file "hello" :depends-on ("macros"))))
232 Some notes about this example:
237 The file starts with @code{defpackage} and @code{in-package} forms to
238 make and use a package expressly for defining this system in. This
239 package is named by taking the system name and suffixing
240 @code{-system} - note that it is @emph{not} the same package as you
241 will use for the application code.
243 This is not absolutely required by asdf, but helps avoid namespace
244 pollution and so is considered good form.
247 The defsystem form defines a system named "hello-lisp" that contains
248 three source files: @file{packages}, @file{macros} and @file{hello}.
251 The file @file{macros} depends on @file{packages} (presumably because
252 the package it's in is defined in @file{packages}), and the file
253 @file{hello} depends on @file{macros} (and hence, transitively on
254 @file{packages}). This means that asdf will compile and load
255 @file{packages} and @file{macros} before starting the compilation of
260 The files are located in the same directory as the file with the
261 system definition. asdf resolves symbolic links before loading the system
262 definition file and stores its location in the resulting
263 system@footnote{It is possible, though almost never necessary, to
264 override this behaviour.}. This is a good thing because the user can
265 move the system sources without having to edit the system definition.
269 @node A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
270 @comment node-name, next, previous, up
271 @section A more involved example
273 Let's illustrate some more involved uses of @code{defsystem} via a
274 slightly convoluted example:
279 :components ((:module "foo" :components ((:file "bar") (:file"baz")
281 :perform (compile-op :after (op c)
283 :explain (compile-op :after (op c)
284 (explain-something c)))
288 The method-form tokens need explaining: essentially, this part:
291 :perform (compile-op :after (op c)
293 :explain (compile-op :after (op c)
294 (explain-something c))
300 (defmethod perform :after ((op compile-op) (c (eql ...)))
302 (defmethod explain :after ((op compile-op) (c (eql ...)))
303 (explain-something c))
306 where @code{...} is the component in question; note that although this
307 also supports @code{:before} methods, they may not do what you want
308 them to -- a @code{:before} method on perform @code{((op compile-op) (c
309 (eql ...)))} will run after all the dependencies and sub-components
310 have been processed, but before the component in question has been
313 @node The defsystem grammar, , A more involved example, Defining systems with defsystem
314 @comment node-name, next, previous, up
315 @section The defsystem grammar
318 system-definition := ( defsystem system-designator {option}* )
320 option := :components component-list
322 | :default-component-class
323 | :perform method-form
324 | :explain method-form
325 | :output-files method-form
326 | :operation-done-p method-form
327 | :depends-on ( {simple-component-name}* )
328 | :serial [ t | nil ]
329 | :in-order-to ( {dependency}+ )
331 component-list := ( {component-def}* )
333 component-def := simple-component-name
334 | ( component-type name {option}* )
336 component-type := :module | :file | :system | other-component-type
338 dependency := (dependent-op {requirement}+)
339 requirement := (required-op {required-component}+)
340 | (feature feature-name)
341 dependent-op := operation-name
342 required-op := operation-name | feature
345 @subsection Serial dependencies
347 If the @code{:serial t} option is specified for a module, asdf will add
348 dependencies for each each child component, on all the children
349 textually preceding it. This is done as if by @code{:depends-on}.
352 :components ((:file "a") (:file "b") (:file "c"))
359 :components ((:file "a")
360 (:file "b" :depends-on ("a"))
361 (:file "c" :depends-on ("a" "b")))
365 @subsection Source location
367 The @code{:pathname} option is optional in all cases for systems
368 defined via @code{defsystem}, and in the usual case the user is
369 recommended not to supply it.
371 Instead, asdf follows a hairy set of rules that are designed so that
373 @item @code{find-system} will load a system from disk and have its pathname
374 default to the right place
375 @item this pathname information will not be
376 overwritten with @code{*default-pathname-defaults*} (which could be
377 somewhere else altogether) if the user loads up the @file{.asd} file
378 into his editor and interactively re-evaluates that form.
381 If a system is being loaded for the first time, its top-level pathname
385 @item The host/device/directory parts of @code{*load-truename*}, if it is bound
386 @item @code{*default-pathname-defaults*}, otherwise
389 If a system is being redefined, the top-level pathname will be
393 changed, if explicitly supplied or obtained from
394 @code{*load-truename*} (so that an updated source location is
395 reflected in the system definition)
397 changed if it had previously been set from
398 @code{*default-pathname-defaults*}
400 left as before, if it had previously been set from
401 @code{*load-truename*} and @code{*load-truename*} is currently
402 unbound (so that a developer can evaluate a @code{defsystem} form from
403 within an editor without clobbering its source location)
408 @node The object model of asdf, Error handling, Defining systems with defsystem, Top
409 @comment node-name, next, previous, up
410 @chapter The object model of asdf
412 asdf is designed in an object-oriented way from the ground up. Both a
413 system's structure and the operations that can be performed on systems
414 follow a protocol. asdf is extensible to new operations and to new
415 component types. This allows the addition of behaviours: for example,
416 a new component could be added for Java JAR archives, and methods
417 specialised on @code{compile-op} added for it that would accomplish the
420 This chapter deals with @emph{components}, the building blocks of a
421 system, and @emph{operations}, the actions that can be performed on a
431 @node Operations, Components, The object model of asdf, The object model of asdf
432 @comment node-name, next, previous, up
436 An @dfn{operation} object of the appropriate type is instantiated
437 whenever the user wants to do something with a system like
440 @item compile all its files
441 @item load the files into a running lisp environment
442 @item copy its source files somewhere else
445 Operations can be invoked directly, or examined to see what their
446 effects would be without performing them. @emph{FIXME: document how!} There
447 are a bunch of methods specialised on operation and component type
448 that actually do the grunt work.
450 The operation object contains whatever state is relevant for this
451 purpose (perhaps a list of visited nodes, for example) but primarily
452 is a nice thing to specialise operation methods on and easier than
453 having them all be EQL methods.
455 Operations are invoked on systems via @code{operate}.
457 @deffn {Generic function} operate operation system &rest initargs
458 @deffnx {Generic function} oos operation system &rest initargs
459 @code{operate} invokes @var{operation} on @var{system}. @code{oos}
460 is a synonym for @code{operate}.
462 @var{operation} is a symbol that is passed, along with the supplied
463 @var{initargs}, to @code{make-instance} to create the operation object.
464 @var{system} is a system designator.
466 The initargs are passed to the @code{make-instance} call when creating
467 the operation object. Note that dependencies may cause the operation
468 to invoke other operations on the system or its components: the new
469 operations will be created with the same initargs as the original one.
474 * Predefined operations of asdf::
475 * Creating new operations::
478 @node Predefined operations of asdf, Creating new operations, Operations, Operations
479 @comment node-name, next, previous, up
480 @subsection Predefined operations of asdf
482 All the operations described in this section are in the @code{asdf}
483 package. They are invoked via the @code{operate} generic function.
486 (asdf:operate 'asdf:@var{operation-name} '@var{system-name} @{@var{operation-options ...}@})
489 @deffn Operation compile-op &key proclamations
491 This operation compiles the specified component. If proclamations are
492 supplied, they will be proclaimed. This is a good place to specify
493 optimization settings.
495 When creating a new component type, you should provide methods for
498 When @code{compile-op} is invoked, component dependencies often cause
499 some parts of the system to be loaded as well as compiled. Invoking
500 @code{compile-op} does not necessarily load all the parts of the
501 system, though; use @code{load-op} to load a system.
504 @deffn Operation load-op &key proclamations
506 This operation loads a system.
508 The default methods for @code{load-op} compile files before loading them.
509 For parity, your own methods on new component types should probably do
513 @deffn Operation load-source-op
515 This operation will load the source for the files in a module even if
516 the source files have been compiled. Systems sometimes have knotty
517 dependencies which require that sources are loaded before they can be
518 compiled. This is how you do that.
520 If you are creating a component type, you need to implement this
521 operation - at least, where meaningful.
524 @deffn Operation test-system-version &key minimum
526 Asks the system whether it satisfies a version requirement.
528 The default method accepts a string, which is expected to contain of a
529 number of integers separated by #\. characters. The method is not
530 recursive. The component satisfies the version dependency if it has
531 the same major number as required and each of its sub-versions is
532 greater than or equal to the sub-version number required.
535 (defun version-satisfies (x y)
536 (labels ((bigger (x y)
539 ((> (car x) (car y)) t)
541 (bigger (cdr x) (cdr y))))))
542 (and (= (car x) (car y))
543 (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
546 If that doesn't work for your system, you can override it. I hope
547 you have as much fun writing the new method as @verb{|#lisp|} did
548 reimplementing this one.
551 @deffn Operation feature-dependent-op
553 An instance of @code{feature-dependent-op} will ignore any components
554 which have a @code{features} attribute, unless the feature combination
555 it designates is satisfied by @code{*features*}. This operation is
556 not intended to be instantiated directly, but other operations may
561 @node Creating new operations, , Predefined operations of asdf, Operations
562 @comment node-name, next, previous, up
563 @subsection Creating new operations
565 asdf was designed to be extensible in an object-oriented fashion. To
566 teach asdf new tricks, a programmer can implement the behaviour he
567 wants by creating a subclass of @code{operation}.
570 asdf's pre-defined operations are in no way ``privileged'', but it is
571 requested that developers never use the @code{asdf} package for
572 operations they develop themselves. The rationale for this rule is
573 that we don't want to establish a ``global asdf operation name
574 registry'', but also want to avoid name clashes.
576 An operation must provide methods for the following generic functions
577 when invoked with an object of type @code{source-file}: @emph{FIXME describe
582 @item @code{output-files}
584 The @code{perform} method must call @code{output-files} to find out
585 where to put its files, because the user is allowed to override
586 @item @code{output-files} for local policy @code{explain}
587 @item @code{operation-done-p}, if you don't like the default one
591 @node Components, , Operations, The object model of asdf
592 @comment node-name, next, previous, up
596 @cindex system designator
597 @vindex *system-definition-search-functions*
599 A @dfn{component} represents a source file or (recursively) a
600 collection of components. A @dfn{system} is (roughly speaking) a
601 top-level component that can be found via @code{find-system}.
603 A @dfn{system designator} is a string or symbol and behaves just like
604 any other component name (including with regard to the case conversion
605 rules for component names).
608 @defun find-system system-designator &optional (error-p t)
610 Given a system designator, @code{find-system} finds and returns a
611 system. If no system is found, an error of type
612 @code{missing-component} is thrown, or @code{nil} is returned if
613 @code{error-p} is false.
615 To find and update systems, @code{find-system} funcalls each element
616 in the @code{*system-definition-search-functions*} list, expecting a
617 pathname to be returned. The resulting pathname is loaded if either
618 of the following conditions is true:
621 @item there is no system of that name in memory
622 @item the file's last-modified time exceeds the last-modified time of the
626 When system definitions are loaded from @file{.asd} files, a new
627 scratch package is created for them to load into, so that different
628 systems do not overwrite each others operations. The user may also
629 wish to (and is recommended to) include @code{defpackage} and
630 @code{in-package} forms in his system definition files, however, so
631 that they can be loaded manually if need be.
633 The default value of @code{*system-definition-search-functions*} is a
634 function that looks in each of the directories given by evaluating
635 members of @code{*central-registry*} for a file whose name is the
636 name of the system and whose type is @file{asd}. The first such file
637 is returned, whether or not it turns out to actually define the
638 appropriate system. Hence, it is strongly advised to define a system
639 @var{foo} in the corresponding file @var{foo.asd}.
644 * Common attributes of components::
645 * Pre-defined subclasses of component::
646 * Creating new component types::
649 @node Common attributes of components, Pre-defined subclasses of component, Components, Components
650 @comment node-name, next, previous, up
651 @subsection Common attributes of components
653 All components, regardless of type, have the following attributes.
654 All attributes except @code{name} are optional.
658 A component name is a string or a symbol. If a symbol, its name is
659 taken and lowercased. The name must be a suitable value for the
660 @code{:name} initarg to @code{make-pathname} in whatever filesystem
661 the system is to be found.
663 The lower-casing-symbols behaviour is unconventional, but was selected
664 after some consideration. Observations suggest that the type of
665 systems we want to support either have lowercase as customary case
666 (Unix, Mac, windows) or silently convert lowercase to uppercase
667 (lpns), so this makes more sense than attempting to use @code{:case
668 :common} as argument to @code{make-pathname}, which is reported not to
669 work on some implementations
671 @subsubsection Version identifier
673 This optional attribute is used by the test-system-version
674 operation. @xref{Predefined operations of asdf}. For the default method of
675 test-system-version, the version should be a string of intergers
676 separated by dots, for example @samp{1.0.11}.
678 @subsubsection Required features
680 Traditionally defsystem users have used reader conditionals to include
681 or exclude specific per-implementation files. This means that any
682 single implementation cannot read the entire system, which becomes a
683 problem if it doesn't wish to compile it, but instead for example to
684 create an archive file containing all the sources, as it will omit to
685 process the system-dependent sources for other systems.
687 Each component in an asdf system may therefore specify features using
688 the same syntax as #+ does, and it will (somehow) be ignored for
689 certain operations unless the feature conditional is a member of
693 @subsubsection Dependencies
695 This attribute specifies dependencies of the component on its
696 siblings. It is optional but often necessary.
698 There is an excitingly complicated relationship between the initarg
699 and the method that you use to ask about dependencies
701 Dependencies are between (operation component) pairs. In your
702 initargs for the component, you can say
705 :in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
706 (load-op (load-op "foo")))
709 This means the following things:
712 before performing compile-op on this component, we must perform
713 load-op on @var{a} and @var{b}, and compile-op on @var{c},
715 before performing @code{load-op}, we have to load @var{foo}
718 The syntax is approximately
721 (this-op {(other-op required-components)}+)
723 required-components := component-name
724 | (required-components required-components)
726 component-name := string
727 | (:version string minimum-version-object)
732 This is on a par with what ACL defsystem does. mk-defsystem is less
733 general: it has an implied dependency
736 for all x, (load x) depends on (compile x)
739 and using a @code{:depends-on} argument to say that @var{b} depends on
740 @var{a} @emph{actually} means that
743 (compile b) depends on (load a)
746 This is insufficient for e.g. the McCLIM system, which requires that
747 all the files are loaded before any of them can be compiled ]
751 In asdf, the dependency information for a given component and
752 operation can be queried using @code{(component-depends-on operation
753 component)}, which returns a list
756 ((load-op "a") (load-op "b") (compile-op "c") ...)
759 @code{component-depends-on} can be subclassed for more specific
760 component/operation types: these need to @code{(call-next-method)} and
761 append the answer to their dependency, unless they have a good reason
762 for completely overriding the default dependencies
764 (If it weren't for CLISP, we'd be using a @code{LIST} method
765 combination to do this transparently. But, we need to support CLISP.
766 If you have the time for some CLISP hacking, I'm sure they'd welcome
769 @subsubsection pathname
771 This attribute is optional and if absent will be inferred from the
772 component's name, type (the subclass of source-file), and the location
775 The rules for this inference are:
779 @item the host is taken from the parent
780 @item pathname type is @code{(source-file-type component system)}
781 @item the pathname case option is @code{:local}
782 @item the pathname is merged against the parent
787 @item the host is taken from the parent
788 @item the name and type are @code{NIL}
789 @item the directory is @code{(:relative component-name)}
790 @item the pathname case option is @code{:local}
791 @item the pathname is merged against the parent
794 Note that the DEFSYSTEM operator (used to create a ``top-level''
795 system) does additional processing to set the filesystem location of
796 the top component in that system. This is detailed
797 elsewhere, @xref{Defining systems with defsystem}.
799 The answer to the frequently asked question "how do I create a system
800 definition where all the source files have a .cl extension" is thus
803 (defmethod source-file-type ((c cl-source-file) (s (eql (find-system 'my-sys))))
807 @subsubsection properties
809 This attribute is optional.
811 Packaging systems often require information about files or systems in
812 addition to that specified by asdf's pre-defined component attributes.
813 Programs that create vendor packages out of asdf systems therefore
814 have to create ``placeholder'' information to satisfy these systems.
815 Sometimes the creator of an asdf system may know the additional
816 information and wish to provide it directly.
818 (component-property component property-name) and associated setf
819 method will allow the programmatic update of this information.
820 Property names are compared as if by @code{EQL}, so use symbols or
821 keywords or something.
824 * Pre-defined subclasses of component::
825 * Creating new component types::
828 @node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
829 @comment node-name, next, previous, up
830 @subsection Pre-defined subclasses of component
832 @deffn Component source-file
834 A source file is any file that the system does not know how to
835 generate from other components of the system.
837 Note that this is not necessarily the same thing as ``a file
838 containing data that is typically fed to a compiler''. If a file is
839 generated by some pre-processor stage (e.g. a @file{.h} file from
840 @file{.h.in} by autoconf) then it is not, by this definition, a source
841 file. Conversely, we might have a graphic file that cannot be
842 automatically regenerated, or a proprietary shared library that we
843 received as a binary: these do count as source files for our purposes.
845 Subclasses of source-file exist for various languages. @emph{FIXME:
849 @deffn Component module
851 A module is a collection of sub-components.
853 A module component has the following extra initargs:
857 @code{:components} the components contained in this module
860 @code{:default-component-class} All child components which don't
861 specify their class explicitly are inferred to be of this type.
864 @code{:if-component-dep-fails} This attribute takes one of the values
865 @code{:fail}, @code{:try-next}, @code{:ignore}, its default value is
866 @code{:fail}. The other values can be used for implementing
867 conditional compilation based on implementation @code{*features*}, for
868 the case where it is not necessary for all files in a module to be
872 @code{:serial} When this attribute is set, each subcomponent of this
873 component is assumed to depend on all subcomponents before it in the
874 list given to @code{:components}, i.e. all of them are loaded before
875 a compile or load operation is performed on it.
879 The default operation knows how to traverse a module, so most
880 operations will not need to provide methods specialised on modules.
882 @code{module} may be subclassed to represent components such as
883 foreign-language linked libraries or archive files.
886 @deffn Component system
888 @code{system} is a subclass of @code{module}.
890 A system is a module with a few extra attributes for documentation
891 purposes; these are given elsewhere. @xref{The defsystem grammar}.
893 Users can create new classes for their systems: the default
894 @code{defsystem} macro takes a @code{:classs} keyword
898 @node Creating new component types, , Pre-defined subclasses of component, Components
899 @comment node-name, next, previous, up
900 @subsection Creating new component types
902 New component types are defined by subclassing one of the existing
903 component classes and specializing methods on the new component class.
905 @emph{FIXME: this should perhaps be explained more throughly, not only by
908 As an example, suppose we have some implementation-dependent
909 functionality that we want to isolate in one subdirectory per Lisp
910 implementation our system supports. We create a subclass of
911 @code{cl-source-file}:
914 (defclass unportable-cl-source-file (cl-source-file)
918 A hypothetical function @code{system-dependent-dirname} gives us the
919 name of the subdirectory. All that's left is to define how to
920 calculate the pathname of an @code{unportable-cl-source-file}.
923 (defmethod component-pathname ((component unportable-cl-source-file))
924 (let ((pathname (call-next-method))
925 (name (string-downcase (system-dependent-dirname))))
927 (make-pathname :directory (list :relative name))
931 The new component type is used in a @code{defsystem} form in this way:
938 (:unportable-cl-source-file "threads"
939 :depends-on ("packages" ...))
944 @node Error handling, Compilation error and warning handling, The object model of asdf, Top
945 @comment node-name, next, previous, up
946 @chapter Error handling
947 @findex SYSTEM-DEFINITION-ERROR
948 @findex OPERATION-ERROR
950 It is an error to define a system incorrectly: an implementation may
951 detect this and signal a generalised instance of
952 @code{SYSTEM-DEFINITION-ERROR}.
954 Operations may go wrong (for example when source files contain
955 errors). These are signalled using generalised instances of
956 @code{OPERATION-ERROR}.
958 @node Compilation error and warning handling, Getting the latest version, Error handling, Top
959 @comment node-name, next, previous, up
960 @chapter Compilation error and warning handling
961 @vindex *compile-file-warnings-behaviour*
962 @vindex *compile-file-errors-behavior*
964 ASDF checks for warnings and errors when a file is compiled. The
965 variables @code{*compile-file-warnings-behaviour*} and
966 @code{*compile-file-errors-behavior*} controls the handling of any
967 such events. The valid values for these variables are @code{:error},
968 @code{:warn}, and @code{:ignore}.
970 @node Getting the latest version, TODO list, Compilation error and warning handling, Top
971 @comment node-name, next, previous, up
972 @chapter Getting the latest version
976 Decide which version you want. HEAD is the newest version and
977 usually OK, whereas RELEASE is for cautious people (e.g. who already
978 have systems using asdf that they don't want broken), a slightly older
979 version about which none of the HEAD users have complained.
982 Check it out from sourceforge cCLan CVS:
984 @kbd{cvs -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan login}
986 (no password: just press @key{Enter})
988 @kbd{cvs -z3 -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan co -r RELEASE asdf}
990 or for the bleeding edge, instead
992 @kbd{cvs -z3 -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan co -A asdf}
996 If you are tracking the bleeding edge, you may want to subscribe to
997 the cclan-commits mailing list (see
998 @url{http://sourceforge.net/mail/?group_id=28536}) to receive commit
999 messages and diffs whenever changes are made.
1001 For more CVS information, look at
1002 @url{http://sourceforge.net/cvs/?group_id=28536}.
1007 @node TODO list, missing bits in implementation, Getting the latest version, Top
1008 @comment node-name, next, previous, up
1011 * Outstanding spec questions, things to add
1013 ** packaging systems
1015 *** manual page component?
1017 ** style guide for .asd files
1019 You should either use keywords or be careful with the package that you
1020 evaluate defsystem forms in. Otherwise (defsystem partition ...)
1021 being read in the cl-user package will intern a cl-user:partition
1022 symbol, which will then collide with the partition:partition symbol.
1024 Actually there's a hairier packages problem to think about too.
1025 in-order-to is not a keyword: if you read defsystem forms in a package
1026 that doesn't use ASDF, odd things might happen
1028 ** extending defsystem with new options
1030 You might not want to write a whole parser, but just to add options to
1031 the existing syntax. Reinstate parse-option or something akin
1033 ** document all the error classes
1035 ** what to do with compile-file failure
1037 Should check the primary return value from compile-file and see if
1038 that gets us any closer to a sensible error handling strategy
1042 lift unix-dso stuff from db-sockets
1046 A ``dry run'' of an operation can be made with the following form:
1049 (traverse (make-instance '<operation-name>)
1050 (find-system <system-name>)
1054 This uses unexported symbols. What would be a nice interface for this
1057 @node missing bits in implementation, Inspiration, TODO list, Top
1058 @comment node-name, next, previous, up
1059 @chapter missing bits in implementation
1063 ** reuse the same scratch package whenever a system is reloaded from disk
1065 ** rules for system pathname defaulting are not yet implemented properly
1067 ** proclamations probably aren't
1069 ** when a system is reloaded with fewer components than it previously
1070 had, odd things happen
1072 we should do something inventive when processing a defsystem form,
1073 like take the list of kids and setf the slot to nil, then transfer
1074 children from old to new list as they're found
1076 ** traverse may become a normal function
1078 If you're defining methods on traverse, speak up.
1081 ** a lot of load-op methods can be rewritten to use input-files
1086 ** (stuff that might happen later)
1088 *** david lichteblau's patch for symlink resolution?
1090 *** Propagation of the :force option. ``I notice that
1092 (oos 'compile-op :araneida :force t)
1094 also forces compilation of every other system the :araneida system
1095 depends on. This is rarely useful to me; usually, when I want to force
1096 recompilation of something more than a single source file, I want to
1097 recompile only one system. So it would be more useful to have
1098 make-sub-operation refuse to propagate @code{:force t} to other systems, and
1099 propagate only something like @code{:force :recursively}.
1101 Ideally what we actually want is some kind of criterion that says to
1102 which systems (and which operations) a @code{:force} switch will
1105 The problem is perhaps that `force' is a pretty meaningless concept.
1106 How obvious is it that @code{load :force t} should force
1107 @emph{compilation}? But we don't really have the right dependency
1108 setup for the user to compile @code{:force t} and expect it to work
1109 (files will not be loaded after compilation, so the compile
1110 environment for subsequent files will be emptier than it needs to be)
1112 What does the user actually want to do when he forces? Usually, for
1113 me, update for use with a new version of the lisp compiler. Perhaps
1114 for recovery when he suspects that something has gone wrong. Or else
1115 when he's changed compilation options or configuration in some way
1116 that's not reflected in the dependency graph.
1118 Other possible interface: have a 'revert' function akin to 'make clean'
1121 (asdf:revert 'asdf:compile-op 'araneida)
1124 would delete any files produced by 'compile-op 'araneida. Of course, it
1125 wouldn't be able to do much about stuff in the image itself.
1127 How would this work?
1131 There's a difference between a module's dependencies (peers) and its
1132 components (children). Perhaps there's a similar difference in
1133 operations? For example, @code{(load "use") depends-on (load "macros")} is a
1134 peer, whereas @code{(load "use") depends-on (compile "use")} is more of a
1135 `subservient' relationship.
1137 @node Inspiration, Concept Index, missing bits in implementation, Top
1138 @comment node-name, next, previous, up
1139 @chapter Inspiration
1141 @section mk-defsystem (defsystem-3.x)
1143 We aim to solve basically the same problems as mk-defsystem does.
1144 However, our architecture for extensibility better exploits CL
1145 language features (and is documented), and we intend to be portable
1146 rather than just widely-ported. No slight on the mk-defsystem authors
1147 and maintainers is intended here; that implementation has the
1148 unenviable task of supporting pre-ANSI implementations, which is
1149 no longer necessary.
1151 The surface defsystem syntax of asdf is more-or-less compatible with
1152 mk-defsystem, except that we do not support the @code{source-foo} and
1153 @code{binary-foo} prefixes for separating source and binary files, and
1154 we advise the removal of all options to specify pathnames.
1156 The mk-defsystem code for topologically sorting a module's dependency
1157 list was very useful.
1159 @section defsystem-4 proposal
1161 Marco and Peter's proposal for defsystem 4 served as the driver for
1162 many of the features in here. Notable differences are:
1166 We don't specify output files or output file extensions as part of the
1169 If you want to find out what files an operation would create, ask the
1173 We don't deal with CL packages
1175 If you want to compile in a particular package, use an in-package form
1176 in that file (ilisp / SLIME will like you more if you do this anyway)
1179 There is no proposal here that defsystem does version control.
1181 A system has a given version which can be used to check dependencies,
1185 The defsystem 4 proposal tends to look more at the external features,
1186 whereas this one centres on a protocol for system introspection.
1188 @section kmp's ``The Description of Large Systems'', MIT AI Memu 801
1190 Available in updated-for-CL form on the web at
1191 @url{http://world.std.com/~pitman/Papers/Large-Systems.html}
1193 In our implementation we borrow kmp's overall PROCESS-OPTIONS and
1194 concept to deal with creating component trees from defsystem surface
1195 syntax. [ this is not true right now, though it used to be and
1196 probably will be again soon ]
1199 @c -------------------
1202 @node Concept Index, Function and Class Index, Inspiration, Top
1203 @unnumbered Concept Index
1207 @node Function and Class Index, Variable Index, Concept Index, Top
1208 @unnumbered Function and Class Index
1212 @node Variable Index, , Function and Class Index, Top
1213 @unnumbered Variable Index