1.0.20.23: get rid of IGNORE-ERRORS in SB-INTROSPECT
[sbcl.git] / contrib / asdf / asdf.texinfo
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 for install-info
8 @dircategory Software development
9 @direntry
10 * asdf: (asdf).           another system definition facility
11 @end direntry
12
13 @copying
14 This manual describes asdf, a system definition facility for Common
15 Lisp programs and libraries.
16      
17 asdf Copyright @copyright{} 2001-2004 Daniel Barlow and contributors
18
19 This manual Copyright @copyright{} 2001-2004 Daniel Barlow and
20 contributors
21
22 Permission is hereby granted, free of charge, to any person obtaining
23 a copy of this software and associated documentation files (the
24 ``Software''), to deal in the Software without restriction, including
25 without limitation the rights to use, copy, modify, merge, publish,
26 distribute, sublicense, and/or sell copies of the Software, and to
27 permit persons to whom the Software is furnished to do so, subject to
28 the following conditions:
29
30 The above copyright notice and this permission notice shall be
31 included in all copies or substantial portions of the Software.
32
33 THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
34 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
35 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
36 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
37 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
38 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
39 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
40
41 @end copying
42
43
44
45 @titlepage
46 @title asdf: another system definition facility
47      
48 @c The following two commands start the copyright page.
49 @page
50 @vskip 0pt plus 1filll
51 @insertcopying
52 @end titlepage
53      
54 @c Output the table of contents at the beginning.
55 @contents
56
57 @c -------------------
58
59 @ifnottex
60
61 @node Top, Using asdf to load systems, (dir), (dir)
62 @top asdf: another system definition facility
63      
64 @insertcopying
65
66 @menu
67 * Using asdf to load systems::  
68 * Defining systems with defsystem::  
69 * The object model of asdf::    
70 * Error handling::              
71 * Compilation error and warning handling::  
72 * Getting the latest version::  
73 * TODO list::                   
74 * missing bits in implementation::  
75 * Inspiration::                 
76 * Concept Index::               
77 * Function and Class Index::    
78 * Variable Index::              
79
80 @detailmenu
81  --- The Detailed Node Listing ---
82
83 Defining systems with defsystem
84
85 * The defsystem form::          
86 * A more involved example::     
87 * The defsystem grammar::       
88
89 The object model of asdf
90
91 * Operations::                  
92 * Components::                  
93
94 Operations
95
96 * Predefined operations of asdf::  
97 * Creating new operations::     
98
99 Components
100
101 * Common attributes of components::  
102 * Pre-defined subclasses of component::  
103 * Creating new component types::  
104
105 properties
106
107 * Pre-defined subclasses of component::  
108 * Creating new component types::  
109
110 @end detailmenu
111 @end menu
112
113 @end ifnottex
114
115 @c -------------------
116
117
118 @node  Using asdf to load systems, Defining systems with defsystem, Top, Top
119 @comment  node-name,  next,  previous,  up
120 @chapter Using asdf to load systems
121 @cindex system directory designator
122 @vindex *central-registry*
123
124 This chapter describes how to use asdf to compile and load ready-made
125 Lisp programs and libraries.
126
127 @section Downloading asdf
128
129 Some Lisp implementations (such as SBCL and OpenMCL) come with asdf
130 included already, so you don't need to download it separately.
131 Consult your Lisp system's documentation.  If you need to download
132 asdf and install it by hand, the canonical source is the cCLan CVS
133 repository at
134 @url{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/}.
135
136 @section Setting up asdf
137
138 The single file @file{asdf.lisp} is all you need to use asdf normally.
139 Once you load it in a running Lisp, you're ready to use asdf.  For
140 maximum convenience you might want to have asdf loaded whenever you
141 start your Lisp implementation, for example by loading it from the
142 startup script or dumping a custom core -- check your Lisp
143 implementation's manual for details.
144
145 The variable @code{asdf:*central-registry*} is a list of ``system
146 directory designators''@footnote{When we say ``directory'' here, we
147 mean ``designator for a pathname with a supplied DIRECTORY
148 component''.}.  A @dfn{system directory designator} is a form which
149 will be evaluated whenever a system is to be found, and must evaluate
150 to a directory to look in.  You might want to set or augment
151 @code{*central-registry*} in your Lisp init file, for example:
152
153 @lisp
154 (setf asdf:*central-registry*
155   (list* '*default-pathname-defaults*
156          #p"/home/me/cl/systems/"
157          #p"/usr/share/common-lisp/systems/"
158          asdf:*central-registry*))
159 @end lisp
160
161 @section Setting up a system to be loaded
162
163 To compile and load a system, you need to ensure that a symbolic link to its
164 system definition is in one of the directories in
165 @code{*central-registry*}@footnote{It is possible to customize the
166 system definition file search.  That's considered advanced use, and
167 covered later: search forward for
168 @code{*system-definition-search-functions*}.  @xref{Defining systems
169 with defsystem}.}.
170
171 For example, if @code{#p"/home/me/cl/systems/"} (note the trailing
172 slash) is a member of @code{*central-registry*}, you would set up a
173 system @var{foo} that is stored in a directory
174 @file{/home/me/src/foo/} for loading with asdf with the following
175 commands at the shell (this has to be done only once):
176
177 @example
178 $ cd /home/me/cl/systems/
179 $ ln -s ~/src/foo/foo.asd .
180 @end example
181
182 @section Loading a system
183
184 The system @var{foo} is loaded (and compiled, if necessary) by
185 evaluating the following form in your Lisp implementation:
186
187 @example
188 (asdf:operate 'asdf:load-op '@var{foo})
189 @end example
190
191 That's all you need to know to use asdf to load systems written by
192 others.  The rest of this manual deals with writing system
193 definitions for Lisp software you write yourself.
194
195 @node   Defining systems with defsystem, The object model of asdf, Using asdf to load systems, Top
196 @comment  node-name,  next,  previous,  up
197 @chapter Defining systems with defsystem
198
199 This chapter describes how to use asdf to define systems and develop
200 software.
201
202
203 @menu
204 * The defsystem form::          
205 * A more involved example::     
206 * The defsystem grammar::       
207 @end menu
208
209 @node  The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
210 @comment  node-name,  next,  previous,  up
211 @section The defsystem form
212
213 Systems can be constructed programmatically by instantiating
214 components using make-instance.  Most of the time, however, it is much
215 more practical to use a static @code{defsystem} form.  This section
216 begins with an example of a system definition, then gives the full
217 grammar of @code{defsystem}.
218
219 Let's look at a simple system.  This is a complete file that would
220 usually be saved as @file{hello-lisp.asd}:
221
222 @lisp
223 (defpackage hello-lisp-system
224   (:use :common-lisp :asdf))
225
226 (in-package :hello-lisp-system)
227
228 (defsystem "hello-lisp"
229     :description "hello-lisp: a sample Lisp system."
230     :version "0.2"
231     :author "Joe User <joe@@example.com>"
232     :licence "Public Domain"
233     :components ((:file "packages")
234                  (:file "macros" :depends-on ("packages"))
235                  (:file "hello" :depends-on ("macros"))))
236 @end lisp
237
238 Some notes about this example:
239
240 @itemize
241
242 @item
243 The file starts with @code{defpackage} and @code{in-package} forms to
244 make and use a package expressly for defining this system in.  This
245 package is named by taking the system name and suffixing
246 @code{-system} - note that it is @emph{not} the same package as you
247 will use for the application code.
248
249 This is not absolutely required by asdf, but helps avoid namespace
250 pollution and so is considered good form. 
251
252 @item
253 The defsystem form defines a system named "hello-lisp" that contains
254 three source files: @file{packages}, @file{macros} and @file{hello}.
255
256 @item
257 The file @file{macros} depends on @file{packages} (presumably because
258 the package it's in is defined in @file{packages}), and the file
259 @file{hello} depends on @file{macros} (and hence, transitively on
260 @file{packages}).  This means that asdf will compile and load
261 @file{packages} and @file{macros} before starting the compilation of
262 file @file{hello}.
263
264
265 @item
266 The files are located in the same directory as the file with the
267 system definition.  asdf resolves symbolic links before loading the system
268 definition file and stores its location in the resulting
269 system@footnote{It is possible, though almost never necessary, to
270 override this behaviour.}.  This is a good thing because the user can
271 move the system sources without having to edit the system definition.
272
273 @end itemize
274
275 @node  A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
276 @comment  node-name,  next,  previous,  up
277 @section A more involved example
278
279 Let's illustrate some more involved uses of @code{defsystem} via a
280 slightly convoluted example:
281
282 @lisp
283 (defsystem "foo"
284   :version "1.0"
285   :components ((:module "foo" :components ((:file "bar") (:file"baz") 
286                                            (:file "quux"))
287                 :perform (compile-op :after (op c)
288                           (do-something c))
289                 :explain (compile-op :after (op c)
290                           (explain-something c)))
291                (:file "blah")))
292 @end lisp
293
294 The method-form tokens need explaining: essentially, this part:
295
296 @lisp
297                 :perform (compile-op :after (op c)
298                           (do-something c))
299                 :explain (compile-op :after (op c)
300                           (explain-something c))
301 @end lisp
302
303 has the effect of
304
305 @lisp
306 (defmethod perform :after ((op compile-op) (c (eql ...)))
307            (do-something c))
308 (defmethod explain :after ((op compile-op) (c (eql ...)))
309            (explain-something c))
310 @end lisp
311
312 where @code{...} is the component in question; note that although this
313 also supports @code{:before} methods, they may not do what you want
314 them to -- a @code{:before} method on perform @code{((op compile-op) (c
315 (eql ...)))}  will run after all the dependencies and sub-components
316 have been processed, but before the component in question has been
317 compiled.
318
319 @node  The defsystem grammar,  , A more involved example, Defining systems with defsystem
320 @comment  node-name,  next,  previous,  up
321 @section The defsystem grammar
322
323 @verbatim
324 system-definition := ( defsystem system-designator {option}* )
325
326 option := :components component-list
327         | :pathname pathname
328         | :default-component-class
329         | :perform method-form 
330         | :explain method-form
331         | :output-files  method-form
332         | :operation-done-p method-form
333         | :depends-on ( {simple-component-name}* ) 
334         | :serial [ t | nil ]
335         | :in-order-to ( {dependency}+ )
336
337 component-list := ( {component-def}* )
338                 
339 component-def  := simple-component-name
340                 | ( component-type name {option}* )
341
342 component-type := :module | :file | :system | other-component-type
343
344 dependency := (dependent-op {requirement}+)
345 requirement := (required-op {required-component}+)
346              | (feature feature-name)
347 dependent-op := operation-name
348 required-op := operation-name | feature
349 @end verbatim
350
351 @subsection Serial dependencies
352
353 If the @code{:serial t} option is specified for a module, asdf will add
354 dependencies for each each child component, on all the children
355 textually preceding it.  This is done as if by @code{:depends-on}.
356
357 @lisp
358 :components ((:file "a") (:file "b") (:file "c"))
359 :serial t
360 @end lisp
361
362 is equivalent to
363
364 @lisp
365 :components ((:file "a") 
366              (:file "b" :depends-on ("a"))
367              (:file "c" :depends-on ("a" "b")))
368 @end lisp
369
370
371 @subsection Source location
372
373 The @code{:pathname} option is optional in all cases for systems
374 defined via @code{defsystem}, and in the usual case the user is
375 recommended not to supply it.
376
377 Instead, asdf follows a hairy set of rules that are designed so that
378 @enumerate
379 @item @code{find-system} will load a system from disk and have its pathname
380 default to the right place
381 @item this pathname information will not be
382 overwritten with @code{*default-pathname-defaults*} (which could be
383 somewhere else altogether) if the user loads up the @file{.asd} file
384 into his editor and interactively re-evaluates that form.
385 @end enumerate
386
387 If a system is being loaded for the first time, its top-level pathname
388 will be set to:
389
390 @itemize
391 @item The host/device/directory parts of @code{*load-truename*}, if it is bound
392 @item @code{*default-pathname-defaults*}, otherwise
393 @end itemize
394
395 If a system is being redefined, the top-level pathname will be
396
397 @itemize
398 @item
399 changed, if explicitly supplied or obtained from
400 @code{*load-truename*} (so that an updated source location is
401 reflected in the system definition)
402 @item
403 changed if it had previously been set from
404 @code{*default-pathname-defaults*}
405 @item
406 left as before, if it had previously been set from
407 @code{*load-truename*} and @code{*load-truename*} is currently
408 unbound (so that a developer can evaluate a @code{defsystem} form from
409 within an editor without clobbering its source location)
410 @end itemize
411
412
413
414 @node The object model of asdf, Error handling, Defining systems with defsystem, Top
415 @comment  node-name,  next,  previous,  up
416 @chapter The object model of asdf
417
418 asdf is designed in an object-oriented way from the ground up.  Both a
419 system's structure and the operations that can be performed on systems
420 follow a protocol.  asdf is extensible to new operations and to new
421 component types.  This allows the addition of behaviours: for example,
422 a new component could be added for Java JAR archives, and methods
423 specialised on @code{compile-op} added for it that would accomplish the
424 relevant actions.
425
426 This chapter deals with @emph{components}, the building blocks of a
427 system, and @emph{operations}, the actions that can be performed on a
428 system.
429
430
431
432 @menu
433 * Operations::                  
434 * Components::                  
435 @end menu
436
437 @node  Operations, Components, The object model of asdf, The object model of asdf
438 @comment  node-name,  next,  previous,  up
439 @section Operations
440 @cindex operation
441
442 An @dfn{operation} object of the appropriate type is instantiated
443 whenever the user wants to do something with a system like
444
445 @itemize
446 @item compile all its files
447 @item load the files into a running lisp environment
448 @item copy its source files somewhere else
449 @end itemize
450
451 Operations can be invoked directly, or examined to see what their
452 effects would be without performing them.  @emph{FIXME: document how!}  There
453 are a bunch of methods specialised on operation and component type
454 that actually do the grunt work.
455
456 The operation object contains whatever state is relevant for this
457 purpose (perhaps a list of visited nodes, for example) but primarily
458 is a nice thing to specialise operation methods on and easier than
459 having them all be EQL methods.
460
461 Operations are invoked on systems via @code{operate}.
462
463 @deffn {Generic function} operate operation system &rest initargs
464 @deffnx {Generic function} oos operation system &rest initargs
465 @code{operate} invokes @var{operation} on @var{system}.  @code{oos}
466 is a synonym for @code{operate}.
467
468 @var{operation} is a symbol that is passed, along with the supplied
469 @var{initargs}, to @code{make-instance} to create the operation object.
470 @var{system} is a system designator.
471
472 The initargs are passed to the @code{make-instance} call when creating
473 the operation object.  Note that dependencies may cause the operation
474 to invoke other operations on the system or its components: the new
475 operations will be created with the same initargs as the original one.
476
477 @end deffn
478
479 @menu
480 * Predefined operations of asdf::  
481 * Creating new operations::     
482 @end menu
483
484 @node Predefined operations of asdf, Creating new operations, Operations, Operations
485 @comment  node-name,  next,  previous,  up
486 @subsection Predefined operations of asdf
487
488 All the operations described in this section are in the @code{asdf}
489 package.  They are invoked via the @code{operate} generic function.
490
491 @lisp
492 (asdf:operate 'asdf:@var{operation-name} '@var{system-name} @{@var{operation-options ...}@})
493 @end lisp
494
495 @deffn Operation compile-op &key proclamations
496
497 This operation compiles the specified component.  If proclamations are
498 supplied, they will be proclaimed.  This is a good place to specify
499 optimization settings.
500
501 When creating a new component type, you should provide methods for
502 @code{compile-op}.
503
504 When @code{compile-op} is invoked, component dependencies often cause
505 some parts of the system to be loaded as well as compiled.  Invoking
506 @code{compile-op} does not necessarily load all the parts of the
507 system, though; use @code{load-op} to load a system.
508 @end deffn
509
510 @deffn Operation load-op &key proclamations
511
512 This operation loads a system.
513
514 The default methods for @code{load-op} compile files before loading them.
515 For parity, your own methods on new component types should probably do
516 so too.
517 @end deffn
518
519 @deffn Operation load-source-op
520
521 This operation will load the source for the files in a module even if
522 the source files have been compiled. Systems sometimes have knotty
523 dependencies which require that sources are loaded before they can be
524 compiled.  This is how you do that.
525
526 If you are creating a component type, you need to implement this
527 operation - at least, where meaningful.
528 @end deffn
529
530 @deffn Operation test-system-version &key minimum
531
532 Asks the system whether it satisfies a version requirement.
533
534 The default method accepts a string, which is expected to contain of a
535 number of integers separated by #\. characters.  The method is not
536 recursive.  The component satisfies the version dependency if it has
537 the same major number as required and each of its sub-versions is
538 greater than or equal to the sub-version number required.
539
540 @lisp
541 (defun version-satisfies (x y)
542   (labels ((bigger (x y)
543              (cond ((not y) t)
544                    ((not x) nil)
545                    ((> (car x) (car y)) t)
546                    ((= (car x) (car y))
547                     (bigger (cdr x) (cdr y))))))
548     (and (= (car x) (car y))
549          (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
550 @end lisp
551
552 If that doesn't work for your system, you can override it.  I hope
553 you have as much fun writing the new method as @verb{|#lisp|} did
554 reimplementing this one.
555 @end deffn
556
557 @deffn Operation feature-dependent-op
558
559 An instance of @code{feature-dependent-op} will ignore any components
560 which have a @code{features} attribute, unless the feature combination
561 it designates is satisfied by @code{*features*}.  This operation is
562 not intended to be instantiated directly, but other operations may
563 inherit from it.
564
565 @end deffn
566
567 @node  Creating new operations,  , Predefined operations of asdf, Operations
568 @comment  node-name,  next,  previous,  up
569 @subsection Creating new operations
570
571 asdf was designed to be extensible in an object-oriented fashion.  To
572 teach asdf new tricks, a programmer can implement the behaviour he
573 wants by creating a subclass of @code{operation}.
574
575
576 asdf's pre-defined operations are in no way ``privileged'', but it is
577 requested that developers never use the @code{asdf} package for
578 operations they develop themselves.  The rationale for this rule is
579 that we don't want to establish a ``global asdf operation name
580 registry'', but also want to avoid name clashes.
581
582 An operation must provide methods for the following generic functions
583 when invoked with an object of type @code{source-file}:  @emph{FIXME describe
584 this better}
585
586 @itemize
587
588 @item @code{output-files}
589 @item @code{perform}
590 The @code{perform} method must call @code{output-files} to find out
591 where to put its files, because the user is allowed to override
592 @item @code{output-files} for local policy @code{explain}
593 @item @code{operation-done-p}, if you don't like the default one
594
595 @end itemize
596
597 @node Components,  , Operations, The object model of asdf
598 @comment  node-name,  next,  previous,  up
599 @section Components
600 @cindex component
601 @cindex system
602 @cindex system designator
603 @vindex *system-definition-search-functions*
604
605 A @dfn{component} represents a source file or (recursively) a
606 collection of components.  A @dfn{system} is (roughly speaking) a
607 top-level component that can be found via @code{find-system}.
608
609 A @dfn{system designator} is a string or symbol and behaves just like
610 any other component name (including with regard to the case conversion
611 rules for component names).
612
613
614 @defun find-system system-designator &optional (error-p t)
615
616 Given a system designator, @code{find-system} finds and returns a
617 system.  If no system is found, an error of type
618 @code{missing-component} is thrown, or @code{nil} is returned if
619 @code{error-p} is false.
620
621 To find and update systems, @code{find-system} funcalls each element
622 in the @code{*system-definition-search-functions*} list, expecting a
623 pathname to be returned.  The resulting pathname is loaded if either
624 of the following conditions is true:
625
626 @itemize
627 @item there is no system of that name in memory
628 @item the file's last-modified time exceeds the last-modified time of the
629   system in memory
630 @end itemize
631
632 When system definitions are loaded from @file{.asd} files, a new
633 scratch package is created for them to load into, so that different
634 systems do not overwrite each others operations.  The user may also
635 wish to (and is recommended to) include @code{defpackage} and
636 @code{in-package} forms in his system definition files, however, so
637 that they can be loaded manually if need be.
638
639 The default value of @code{*system-definition-search-functions*} is a
640 function that looks in each of the directories given by evaluating
641 members of @code{*central-registry*} for a file whose name is the
642 name of the system and whose type is @file{asd}.  The first such file
643 is returned, whether or not it turns out to actually define the
644 appropriate system.  Hence, it is strongly advised to define a system
645 @var{foo} in the corresponding file @var{foo.asd}.
646 @end defun
647
648
649 @menu
650 * Common attributes of components::  
651 * Pre-defined subclasses of component::  
652 * Creating new component types::  
653 @end menu
654
655 @node  Common attributes of components, Pre-defined subclasses of component, Components, Components
656 @comment  node-name,  next,  previous,  up
657 @subsection Common attributes of components
658
659 All components, regardless of type, have the following attributes.
660 All attributes except @code{name} are optional.
661
662 @subsubsection Name
663
664 A component name is a string or a symbol.  If a symbol, its name is
665 taken and lowercased.  The name must be a suitable value for the
666 @code{:name} initarg to @code{make-pathname} in whatever filesystem
667 the system is to be found.
668
669 The lower-casing-symbols behaviour is unconventional, but was selected
670 after some consideration.  Observations suggest that the type of
671 systems we want to support either have lowercase as customary case
672 (Unix, Mac, windows) or silently convert lowercase to uppercase
673 (lpns), so this makes more sense than attempting to use @code{:case
674 :common} as argument to @code{make-pathname}, which is reported not to
675 work on some implementations
676
677 @subsubsection Version identifier
678
679 This optional attribute is used by the test-system-version
680 operation. @xref{Predefined operations of asdf}.  For the default method of
681 test-system-version, the version should be a string of intergers
682 separated by dots, for example @samp{1.0.11}.
683
684 @subsubsection Required features
685
686 Traditionally defsystem users have used reader conditionals to include
687 or exclude specific per-implementation files.  This means that any
688 single implementation cannot read the entire system, which becomes a
689 problem if it doesn't wish to compile it, but instead for example to
690 create an archive file containing all the sources, as it will omit to
691 process the system-dependent sources for other systems.
692
693 Each component in an asdf system may therefore specify features using
694 the same syntax as #+ does, and it will (somehow) be ignored for
695 certain operations unless the feature conditional is a member of
696 @code{*features*}.
697
698
699 @subsubsection Dependencies
700
701 This attribute specifies dependencies of the component on its
702 siblings.  It is optional but often necessary.
703
704 There is an excitingly complicated relationship between the initarg
705 and the method that you use to ask about dependencies
706
707 Dependencies are between (operation component) pairs.  In your
708 initargs for the component, you can say
709
710 @lisp
711 :in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
712               (load-op (load-op "foo")))
713 @end lisp
714
715 This means the following things:
716 @itemize
717 @item
718 before performing compile-op on this component, we must perform
719 load-op on @var{a} and @var{b}, and compile-op on @var{c},
720 @item
721 before performing @code{load-op}, we have to load @var{foo}
722 @end itemize
723
724 The syntax is approximately
725
726 @verbatim
727 (this-op {(other-op required-components)}+)
728
729 required-components := component-name
730                      | (required-components required-components)
731
732 component-name := string
733                 | (:version string minimum-version-object)
734 @end verbatim
735
736 Side note:
737
738 This is on a par with what ACL defsystem does.  mk-defsystem is less
739 general: it has an implied dependency
740
741 @verbatim
742   for all x, (load x) depends on (compile x)
743 @end verbatim
744
745 and using a @code{:depends-on} argument to say that @var{b} depends on
746 @var{a} @emph{actually} means that
747
748 @verbatim
749   (compile b) depends on (load a) 
750 @end verbatim
751
752 This is insufficient for e.g. the McCLIM system, which requires that
753 all the files are loaded before any of them can be compiled ]
754
755 End side note
756
757 In asdf, the dependency information for a given component and
758 operation can be queried using @code{(component-depends-on operation
759 component)}, which returns a list
760
761 @lisp
762 ((load-op "a") (load-op "b") (compile-op "c") ...)
763 @end lisp
764
765 @code{component-depends-on} can be subclassed for more specific
766 component/operation types: these need to @code{(call-next-method)} and
767 append the answer to their dependency, unless they have a good reason
768 for completely overriding the default dependencies
769
770 (If it weren't for CLISP, we'd be using a @code{LIST} method
771 combination to do this transparently.  But, we need to support CLISP.
772 If you have the time for some CLISP hacking, I'm sure they'd welcome
773 your fixes)
774
775 @subsubsection pathname
776
777 This attribute is optional and if absent will be inferred from the
778 component's name, type (the subclass of source-file), and the location
779 of its parent.
780
781 The rules for this inference are:
782
783 (for source-files)
784 @itemize
785 @item the host is taken from the parent
786 @item pathname type is @code{(source-file-type component system)}
787 @item the pathname case option is @code{:local}
788 @item the pathname is merged against the parent
789 @end itemize
790
791 (for modules)
792 @itemize
793 @item the host is taken from the parent
794 @item the name and type are @code{NIL}
795 @item the directory is @code{(:relative component-name)}
796 @item the pathname case option is @code{:local}
797 @item the pathname is merged against the parent
798 @end itemize
799
800 Note that the DEFSYSTEM operator (used to create a ``top-level''
801 system) does additional processing to set the filesystem location of
802 the top component in that system.  This is detailed
803 elsewhere, @xref{Defining systems with defsystem}.
804
805 The answer to the frequently asked question "how do I create a system 
806 definition where all the source files have a .cl extension" is thus
807
808 @lisp
809 (defmethod source-file-type ((c cl-source-file) (s (eql (find-system 'my-sys))))
810    "cl")
811 @end lisp
812
813 @subsubsection properties
814
815 This attribute is optional.
816
817 Packaging systems often require information about files or systems in
818 addition to that specified by asdf's pre-defined component attributes.
819 Programs that create vendor packages out of asdf systems therefore
820 have to create ``placeholder'' information to satisfy these systems.
821 Sometimes the creator of an asdf system may know the additional
822 information and wish to provide it directly.
823
824 (component-property component property-name) and associated setf
825 method will allow the programmatic update of this information.
826 Property names are compared as if by @code{EQL}, so use symbols or
827 keywords or something.
828
829 @menu
830 * Pre-defined subclasses of component::  
831 * Creating new component types::  
832 @end menu
833
834 @node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
835 @comment  node-name,  next,  previous,  up
836 @subsection Pre-defined subclasses of component
837
838 @deffn Component source-file
839
840 A source file is any file that the system does not know how to
841 generate from other components of the system. 
842
843 Note that this is not necessarily the same thing as ``a file
844 containing data that is typically fed to a compiler''.  If a file is
845 generated by some pre-processor stage (e.g. a @file{.h} file from
846 @file{.h.in} by autoconf) then it is not, by this definition, a source
847 file.  Conversely, we might have a graphic file that cannot be
848 automatically regenerated, or a proprietary shared library that we
849 received as a binary: these do count as source files for our purposes.
850
851 Subclasses of source-file exist for various languages.  @emph{FIXME:
852 describe these.}
853 @end deffn
854
855 @deffn Component module
856
857 A module is a collection of sub-components.
858
859 A module component has the following extra initargs:
860
861 @itemize
862 @item
863 @code{:components} the components contained in this module
864
865 @item
866 @code{:default-component-class} All child components which don't
867 specify their class explicitly are inferred to be of this type.
868
869 @item
870 @code{:if-component-dep-fails} This attribute takes one of the values
871 @code{:fail}, @code{:try-next}, @code{:ignore}, its default value is
872 @code{:fail}.  The other values can be used for implementing
873 conditional compilation based on implementation @code{*features*}, for
874 the case where it is not necessary for all files in a module to be
875 compiled.
876
877 @item
878 @code{:serial} When this attribute is set, each subcomponent of this
879 component is assumed to depend on all subcomponents before it in the
880 list given to @code{:components}, i.e. all of them are loaded before
881 a compile or load operation is performed on it.
882
883 @end itemize
884
885 The default operation knows how to traverse a module, so most
886 operations will not need to provide methods specialised on modules.
887
888 @code{module} may be subclassed to represent components such as
889 foreign-language linked libraries or archive files.
890 @end deffn
891
892 @deffn Component system
893
894 @code{system} is a subclass of @code{module}.
895
896 A system is a module with a few extra attributes for documentation
897 purposes; these are given elsewhere.  @xref{The defsystem grammar}.
898
899 Users can create new classes for their systems: the default
900 @code{defsystem} macro takes a @code{:classs} keyword
901 argument.
902 @end deffn
903
904 @node  Creating new component types,  , Pre-defined subclasses of component, Components
905 @comment  node-name,  next,  previous,  up
906 @subsection Creating new component types
907
908 New component types are defined by subclassing one of the existing
909 component classes and specializing methods on the new component class.
910
911 @emph{FIXME: this should perhaps be explained more throughly, not only by
912 example ...}
913
914 As an example, suppose we have some implementation-dependent
915 functionality that we want to isolate in one subdirectory per Lisp
916 implementation our system supports.  We create a subclass of
917 @code{cl-source-file}:
918
919 @lisp
920 (defclass unportable-cl-source-file (cl-source-file)
921     ())
922 @end lisp
923
924 A hypothetical function @code{system-dependent-dirname} gives us the
925 name of the subdirectory.  All that's left is to define how to
926 calculate the pathname of an @code{unportable-cl-source-file}.
927
928 @lisp
929 (defmethod component-pathname ((component unportable-cl-source-file))
930   (let ((pathname (call-next-method))
931         (name (string-downcase (system-dependent-dirname))))
932     (merge-pathnames
933      (make-pathname :directory (list :relative name))
934      pathname)))
935 @end lisp
936
937 The new component type is used in a @code{defsystem} form in this way:
938
939 @lisp
940 (defsystem :foo
941     :components
942     ((:file "packages")
943      ...
944      (:unportable-cl-source-file "threads"
945       :depends-on ("packages" ...))
946      ...
947     )
948 @end lisp
949
950 @node  Error handling, Compilation error and warning handling, The object model of asdf, Top
951 @comment  node-name,  next,  previous,  up
952 @chapter Error handling
953 @findex SYSTEM-DEFINITION-ERROR
954 @findex OPERATION-ERROR
955
956 It is an error to define a system incorrectly: an implementation may
957 detect this and signal a generalised instance of
958 @code{SYSTEM-DEFINITION-ERROR}.
959
960 Operations may go wrong (for example when source files contain
961 errors).  These are signalled using generalised instances of
962 @code{OPERATION-ERROR}.
963
964 @node  Compilation error and warning handling, Getting the latest version, Error handling, Top
965 @comment  node-name,  next,  previous,  up
966 @chapter Compilation error and warning handling
967 @vindex *compile-file-warnings-behaviour*
968 @vindex *compile-file-errors-behavior*
969
970 ASDF checks for warnings and errors when a file is compiled. The
971 variables @code{*compile-file-warnings-behaviour*} and
972 @code{*compile-file-errors-behavior*} controls the handling of any
973 such events. The valid values for these variables are @code{:error},
974 @code{:warn}, and @code{:ignore}.
975
976 @node Getting the latest version, TODO list, Compilation error and warning handling, Top
977 @comment  node-name,  next,  previous,  up
978 @chapter Getting the latest version
979
980 @enumerate
981 @item
982 Decide which version you want.  HEAD is the newest version and
983 usually OK, whereas RELEASE is for cautious people (e.g. who already
984 have systems using asdf that they don't want broken), a slightly older
985 version about which none of the HEAD users have complained.
986
987 @item
988 Check it out from sourceforge cCLan CVS:
989
990 @kbd{cvs -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan login}
991
992 (no password: just press @key{Enter})
993  
994 @kbd{cvs -z3 -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan co -r RELEASE asdf}
995
996 or for the bleeding edge, instead
997
998 @kbd{cvs -z3 -d:pserver:anonymous@@cvs.cclan.sourceforge.net:/cvsroot/cclan co -A asdf}
999
1000 @end enumerate
1001
1002 If you are tracking the bleeding edge, you may want to subscribe to
1003 the cclan-commits mailing list (see
1004 @url{http://sourceforge.net/mail/?group_id=28536}) to receive commit
1005 messages and diffs whenever changes are made.
1006
1007 For more CVS information, look at
1008 @url{http://sourceforge.net/cvs/?group_id=28536}.
1009
1010
1011
1012
1013 @node  TODO list, missing bits in implementation, Getting the latest version, Top
1014 @comment  node-name,  next,  previous,  up
1015 @chapter TODO list
1016
1017 * Outstanding spec questions, things to add
1018
1019 ** packaging systems
1020
1021 *** manual page component?
1022
1023 ** style guide for .asd files
1024
1025 You should either use keywords or be careful with the package that you
1026 evaluate defsystem forms in.  Otherwise (defsystem partition ...)
1027 being read in the cl-user package will intern a cl-user:partition
1028 symbol, which will then collide with the partition:partition symbol.
1029
1030 Actually there's a hairier packages problem to think about too.
1031 in-order-to is not a keyword: if you read defsystem forms in a package
1032 that doesn't use ASDF, odd things might happen
1033
1034 ** extending defsystem with new options
1035
1036 You might not want to write a whole parser, but just to add options to
1037 the existing syntax.  Reinstate parse-option or something akin
1038
1039 ** document all the error classes
1040
1041 ** what to do with compile-file failure
1042
1043 Should check the primary return value from compile-file and see if
1044 that gets us any closer to a sensible error handling strategy
1045
1046 ** foreign files
1047
1048 lift unix-dso stuff from db-sockets
1049
1050 ** Diagnostics
1051
1052 A ``dry run'' of an operation can be made with the following form:
1053
1054 @lisp
1055 (traverse (make-instance '<operation-name>)
1056           (find-system <system-name>)
1057           'explain)
1058 @end lisp
1059
1060 This uses unexported symbols.  What would be a nice interface for this
1061 functionality?
1062
1063 @node  missing bits in implementation, Inspiration, TODO list, Top
1064 @comment  node-name,  next,  previous,  up
1065 @chapter missing bits in implementation
1066
1067 ** all of the above
1068
1069 ** reuse the same scratch package whenever a system is reloaded from disk
1070
1071 ** rules for system pathname defaulting are not yet implemented properly
1072
1073 ** proclamations probably aren't
1074
1075 ** when a system is reloaded with fewer components than it previously
1076    had, odd things happen
1077
1078 we should do something inventive when processing a defsystem form,
1079 like take the list of kids and setf the slot to nil, then transfer
1080 children from old to new list as they're found
1081
1082 **  traverse may become a normal function
1083
1084 If you're defining methods on traverse,  speak up.
1085
1086
1087 ** a lot of load-op methods can be rewritten to use input-files
1088
1089 so should be.
1090
1091
1092 ** (stuff that might happen later)
1093
1094 *** david lichteblau's patch for symlink resolution?
1095
1096 *** Propagation of the :force option.  ``I notice that
1097
1098         (oos 'compile-op :araneida :force t)
1099
1100 also forces compilation of every other system the :araneida system
1101 depends on.  This is rarely useful to me; usually, when I want to force
1102 recompilation of something more than a single source file, I want to
1103 recompile only one system.  So it would be more useful to have
1104 make-sub-operation refuse to propagate @code{:force t} to other systems, and
1105 propagate only something like @code{:force :recursively}.
1106
1107 Ideally what we actually want is some kind of criterion that says to
1108 which systems (and which operations) a @code{:force} switch will
1109 propagate.
1110
1111 The problem is perhaps that `force' is a pretty meaningless concept.
1112 How obvious is it that @code{load :force t} should force
1113 @emph{compilation}?  But we don't really have the right dependency
1114 setup for the user to compile @code{:force t} and expect it to work
1115 (files will not be loaded after compilation, so the compile
1116 environment for subsequent files will be emptier than it needs to be)
1117
1118 What does the user actually want to do when he forces?  Usually, for
1119 me, update for use with a new version of the lisp compiler.  Perhaps
1120 for recovery when he suspects that something has gone wrong.  Or else
1121 when he's changed compilation options or configuration in some way
1122 that's not reflected in the dependency graph.
1123
1124 Other possible interface: have a 'revert' function akin to 'make clean'
1125
1126 @lisp
1127 (asdf:revert 'asdf:compile-op 'araneida) 
1128 @end lisp
1129
1130 would delete any files produced by 'compile-op 'araneida.  Of course, it
1131 wouldn't be able to do much about stuff in the image itself.
1132
1133 How would this work?
1134
1135 traverse
1136
1137 There's a difference between a module's dependencies (peers) and its
1138 components (children).  Perhaps there's a similar difference in
1139 operations?  For example, @code{(load "use") depends-on (load "macros")} is a
1140 peer, whereas @code{(load "use") depends-on (compile "use")} is more of a
1141 `subservient' relationship.
1142
1143 @node  Inspiration, Concept Index, missing bits in implementation, Top
1144 @comment  node-name,  next,  previous,  up
1145 @chapter Inspiration
1146
1147 @section mk-defsystem (defsystem-3.x)
1148
1149 We aim to solve basically the same problems as mk-defsystem does.
1150 However, our architecture for extensibility better exploits CL
1151 language features (and is documented), and we intend to be portable
1152 rather than just widely-ported.  No slight on the mk-defsystem authors
1153 and maintainers is intended here; that implementation has the
1154 unenviable task of supporting pre-ANSI implementations, which is 
1155 no longer necessary.
1156
1157 The surface defsystem syntax of asdf is more-or-less compatible with
1158 mk-defsystem, except that we do not support the @code{source-foo} and
1159 @code{binary-foo} prefixes for separating source and binary files, and 
1160 we advise the removal of all options to specify pathnames.
1161
1162 The mk-defsystem code for topologically sorting a module's dependency
1163 list was very useful.
1164
1165 @section defsystem-4 proposal
1166
1167 Marco and Peter's proposal for defsystem 4 served as the driver for
1168 many of the features in here.  Notable differences are:
1169
1170 @itemize
1171 @item
1172 We don't specify output files or output file extensions as part of the
1173 system.  
1174
1175 If you want to find out what files an operation would create, ask the
1176 operation.
1177
1178 @item
1179 We don't deal with CL packages
1180
1181 If you want to compile in a particular package, use an in-package form
1182 in that file (ilisp / SLIME will like you more if you do this anyway)
1183
1184 @item
1185 There is no proposal here that defsystem does version control.  
1186
1187 A system has a given version which can be used to check dependencies,
1188 but that's all.
1189 @end itemize
1190
1191 The defsystem 4 proposal tends to look more at the external features,
1192 whereas this one centres on a protocol for system introspection.
1193
1194 @section kmp's ``The Description of Large Systems'', MIT AI Memu 801
1195
1196 Available in updated-for-CL form on the web at 
1197 @url{http://world.std.com/~pitman/Papers/Large-Systems.html}
1198
1199 In our implementation we borrow kmp's overall PROCESS-OPTIONS and
1200 concept to deal with creating component trees from defsystem surface
1201 syntax.  [ this is not true right now, though it used to be and
1202 probably will be again soon ]
1203
1204
1205 @c -------------------
1206
1207
1208 @node Concept Index, Function and Class Index, Inspiration, Top
1209 @unnumbered Concept Index
1210      
1211 @printindex cp
1212
1213 @node Function and Class Index, Variable Index, Concept Index, Top
1214 @unnumbered Function and Class Index
1215      
1216 @printindex fn
1217
1218 @node Variable Index,  , Function and Class Index, Top
1219 @unnumbered Variable Index
1220      
1221 @printindex vr
1222
1223
1224
1225
1226 @bye
1227