asdf.texinfo 50.8 KB
Newer Older
1
2
\input texinfo          @c -*- texinfo -*-
@c %**start of header
3
@setfilename asdf.info
4
5
6
@settitle asdf Manual
@c %**end of header

7
8
9
10
11
12
@c for install-info
@dircategory Software development
@direntry
* asdf: (asdf).           another system definition facility
@end direntry

13
14
15
16
@copying
This manual describes asdf, a system definition facility for Common
Lisp programs and libraries.
     
17
asdf Copyright @copyright{} 2001-2007 Daniel Barlow and contributors
18

19
This manual Copyright @copyright{} 2001-2007 Daniel Barlow and
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
contributors

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

@end copying



@titlepage
@title asdf: another system definition facility
     
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
     
@c Output the table of contents at the beginning.
@contents

@c -------------------

@ifnottex

61
@node Top, Introduction, (dir), (dir)
62
63
64
65
66
@top asdf: another system definition facility
     
@insertcopying

@menu
67
* Introduction::
68
69
70
* Using asdf to load systems::  
* Defining systems with defsystem::  
* The object model of asdf::    
71
72
* Controlling where ASDF saves compiled files::
* Special variables::
73
* Error handling::              
74
* Compilation error and warning handling::  
75
* Miscellaneous additional functionality::
76
77
78
79
80
81
82
83
84
85
86
* Getting the latest version::  
* TODO list::                   
* missing bits in implementation::  
* Inspiration::                 
* Concept Index::               
* Function and Class Index::    
* Variable Index::              

@detailmenu
 --- The Detailed Node Listing ---

87
88
89
90
Using ASDF

@c * Installing ASDF::

91
92
93
94
95
Defining systems with defsystem

* The defsystem form::          
* A more involved example::     
* The defsystem grammar::       
96
* Other code in .asd files::
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

The object model of asdf

* Operations::                  
* Components::                  

Operations

* Predefined operations of asdf::  
* Creating new operations::     

Components

* Common attributes of components::  
* Pre-defined subclasses of component::  
* Creating new component types::  

properties

* Pre-defined subclasses of component::  
* Creating new component types::  

@end detailmenu
@end menu

@end ifnottex

@c -------------------

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
@node Introduction, Using asdf to load systems, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

ASDF is Another System Definition Facility: a tool for describing the
sub-systems and files that comprise a system and for operating on these
components in the right order so that they can be compiled, loaded,
tested, etc.

ASDF presents two faces: one for system implementors who need to be able
to describe their systems and one for Lisp programmers who want to use
those systems. @xref{Using asdf to load systems,the getting started guide}, to learn how to use ASDF to
load a system. @xref{Defining systems with defsystem}, to learn how to
define a system of your own.  Later chapters describe the ASDF internals
and how to extend ASDF.

142

143
@node  Using asdf to load systems, Defining systems with defsystem, Introduction, Top
144
@comment  node-name,  next,  previous,  up
145
@chapter Using ASDF
146
@vindex *central-registry*
147
@cindex link farm
148
149
150
151
152
153
@findex load-system
@findex compile-system
@findex test-system
@cindex system directory designator
@findex operate
@findex oos
154

155
156
157
@c @menu
@c * Installing ASDF::
@c @end menu
158

159
@section Installing ASDF
160

161
162
163
Many Lisp implementations include a copy of ASDF. You can
usually load this copy using Common-Lisp's @code{require}
function:
164

165
166
167
168
169
@kbd{(require 'asdf)}

Consult your Lisp implementation's documentation for details. If ASDF
doesn't come bundled with your Lisp or if you want to make
sure that you have the most recent version, then you'll want
170
171
172
173
174
175
to download it from the
@url{http://common-lisp.net/project/asdf/,asdf-home} website.

Note to SBCL users:  you are cautioned that installing ASDF yourself may
break some SBCL contribs.  We are working to provide instructions for
doing this safely.
176
177
178
179
180
181

@section Loading ASDF

If your CL implementation does @emph{not} provide ASDF through the
@code{require} feature, then you need to download ASDF and load it
yourself.
182
183
184
185
186
187
188
189

The single file @file{asdf.lisp} is all you need to use asdf normally.
Once you load it in a running Lisp, you're ready to use asdf.  For
maximum convenience you might want to have asdf loaded whenever you
start your Lisp implementation, for example by loading it from the
startup script or dumping a custom core -- check your Lisp
implementation's manual for details.

190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
@section Setting up a system to be loaded

To compile and load a system, you need to ensure that its
system definition can be found in one of the directories in
@code{*central-registry*}@footnote{It is possible to customize the
system definition file search.  That's considered advanced use, and
covered later: search forward for
@code{*system-definition-search-functions*}.  @xref{Defining systems
with defsystem}.}.

There are two ways that you can make a system definition findable
through @code{*central-registry*}.  One is to simply insert into
@code{*central-registry*} an entry that specifies the pathname of for
the directory containing the system definition file (a file whose name
is of the form @code{*.asd}).
For example, if we had a
system @var{foo} that is stored in a directory
@file{/home/me/src/foo/}, containing  @file{/home/me/src/foo/}, we could
make the foo system asdf-operable by doing @kbd{(push
"/home/me/src/foo/" asdf:*central-registry*)}.

ASDF will also properly handle the case where the
@code{*central-registry*} points to a directory containing a
@emph{symbolic link} to the system definition file.

For example, if @code{#p"/home/me/cl/systems/"} (note the trailing
slash) is a member of @code{*central-registry*}, you could set up the
system @var{foo} for loading with asdf with the following
commands at the shell:

@example
$ cd /home/me/cl/systems/
$ ln -s ~/src/foo/foo.asd .
@end example

225
226
227
228
229
Previous versions of the ASDF manual suggested that users create a
directory in their @code{*central-registry*} that would act as a ``link
farm.''  However, this method may cause problems if you work on multiple
lisp projects that contain different mixes of ASDF libraries.

230
The variable @code{asdf:*central-registry*} is a list of ``system
231
232
233
234
235
236
directory designators''@footnote{When we say ``directory'' here, we
mean ``designator for a pathname with a supplied DIRECTORY
component''.}.  A @dfn{system directory designator} is a form which
will be evaluated whenever a system is to be found, and must evaluate
to a directory to look in.  You might want to set or augment
@code{*central-registry*} in your Lisp init file, for example:
237
238
239

@lisp
(setf asdf:*central-registry*
240
241
242
243
  (list* '*default-pathname-defaults*
         #p"/home/me/cl/systems/"
         #p"/usr/share/common-lisp/systems/"
         asdf:*central-registry*))
244
245
246
247
@end lisp

@section Loading a system

248
249
250
@c{FIXME:  Add Gary's material about loading system definitions by hand.}
@c{FIXME:  Introduce ASDF-binary-locations.}

251
252
253
254
The system @var{foo} is loaded (and compiled, if necessary) by
evaluating the following form in your Lisp implementation:

@example
255
(asdf:load-system '@var{foo})
256
257
@end example

258
259
(In older versions of ASDF, you may need to use @code{(asdf:oos
'asdf:load-op 'foo)}, instead.)
260

261
262
263
264
265
Output from asdf and asdf extensions are supposed to be sent to the CL
stream @code{*standard-output*}, and so rebinding that stream around
calls to @code{asdf:operate} should redirect all output from asdf
operations.

266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
ASDF provides three commands for the most common system
operations: @code{load-system}, @code{compile-system} or @code{test-system}.

Because ASDF is an extensible system for defining
@emph{operations} on @emph{components} also provides a generic
function: @code{operate} (which is usually abbreviated by
@code{oos}). You'll use @code{oos} whenever you want to do something
beyond compiling, loading and testing.

Reminder: before ASDF can operate on a system, however, it must be able
to find and load that system's definition.

@section Summary

To use ASDF:

@itemize
@item
load @file{asdf.lisp} into your Lisp image, either through
@code{require} or @code{load}.

@item
make sure ASDF can find system definitions by loading them
yourself or setting up @code{*central-registry*}.

@item
use @code{operate} (or shorthand @code{oos})
to tell ASDF what you'd like to do to what systems.
For simple operations, you can use @code{load-system}, @code{compile-system} or @code{test-system}
instead.

@end itemize

@section Moving on

301
302
That's all you need to know to use asdf to load systems written by
others.  The rest of this manual deals with writing system
303
304
definitions for Lisp software you write yourself, including how to
extend ASDF to define new operation and component types.
305
306
307
308
309
310
311
312
313
314
315
316
317

@node   Defining systems with defsystem, The object model of asdf, Using asdf to load systems, Top
@comment  node-name,  next,  previous,  up
@chapter Defining systems with defsystem

This chapter describes how to use asdf to define systems and develop
software.


@menu
* The defsystem form::          
* A more involved example::     
* The defsystem grammar::       
318
* Other code in .asd files::
319
320
321
322
323
324
325
326
327
328
329
330
@end menu

@node  The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
@comment  node-name,  next,  previous,  up
@section The defsystem form

Systems can be constructed programmatically by instantiating
components using make-instance.  Most of the time, however, it is much
more practical to use a static @code{defsystem} form.  This section
begins with an example of a system definition, then gives the full
grammar of @code{defsystem}.

331
332
Let's look at a simple system.  This is a complete file that would
usually be saved as @file{hello-lisp.asd}:
333
334

@lisp
335
336
337
338
339
(defpackage hello-lisp-system
  (:use :common-lisp :asdf))

(in-package :hello-lisp-system)

340
341
342
343
344
345
346
347
348
349
350
351
352
(defsystem "hello-lisp"
    :description "hello-lisp: a sample Lisp system."
    :version "0.2"
    :author "Joe User <joe@@example.com>"
    :licence "Public Domain"
    :components ((:file "packages")
                 (:file "macros" :depends-on ("packages"))
                 (:file "hello" :depends-on ("macros"))))
@end lisp

Some notes about this example:

@itemize
353
354
355
356
357
358
359
360
361
362
363

@item
The file starts with @code{defpackage} and @code{in-package} forms to
make and use a package expressly for defining this system in.  This
package is named by taking the system name and suffixing
@code{-system} - note that it is @emph{not} the same package as you
will use for the application code.

This is not absolutely required by asdf, but helps avoid namespace
pollution and so is considered good form. 

364
@item
365
366
The defsystem form defines a system named "hello-lisp" that contains
three source files: @file{packages}, @file{macros} and @file{hello}.
367
368
369
370
371
372
373
374
375
376
377
378

@item
The file @file{macros} depends on @file{packages} (presumably because
the package it's in is defined in @file{packages}), and the file
@file{hello} depends on @file{macros} (and hence, transitively on
@file{packages}).  This means that asdf will compile and load
@file{packages} and @file{macros} before starting the compilation of
file @file{hello}.


@item
The files are located in the same directory as the file with the
379
system definition.  asdf resolves symbolic links before loading the system
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
definition file and stores its location in the resulting
system@footnote{It is possible, though almost never necessary, to
override this behaviour.}.  This is a good thing because the user can
move the system sources without having to edit the system definition.

@end itemize

@node  A more involved example, The defsystem grammar, The defsystem form, Defining systems with defsystem
@comment  node-name,  next,  previous,  up
@section A more involved example

Let's illustrate some more involved uses of @code{defsystem} via a
slightly convoluted example:

@lisp
(defsystem "foo"
  :version "1.0"
  :components ((:module "foo" :components ((:file "bar") (:file"baz") 
                                           (:file "quux"))
Robert P. Goldman's avatar
Nits.    
Robert P. Goldman committed
399
400
401
402
                :perform (compile-op :after (op c)
                          (do-something c))
                :explain (compile-op :after (op c)
                          (explain-something c)))
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
               (:file "blah")))
@end lisp

The method-form tokens need explaining: essentially, this part:

@lisp
	        :perform (compile-op :after (op c)
			  (do-something c))
		:explain (compile-op :after (op c)
			  (explain-something c))
@end lisp

has the effect of

@lisp
(defmethod perform :after ((op compile-op) (c (eql ...)))
	   (do-something c))
(defmethod explain :after ((op compile-op) (c (eql ...)))
	   (explain-something c))
@end lisp

where @code{...} is the component in question; note that although this
also supports @code{:before} methods, they may not do what you want
them to -- a @code{:before} method on perform @code{((op compile-op) (c
(eql ...)))}  will run after all the dependencies and sub-components
have been processed, but before the component in question has been
compiled.

431
@node  The defsystem grammar, Other code in .asd files, A more involved example, Defining systems with defsystem
432
433
434
435
436
437
438
439
440
441
442
443
444
@comment  node-name,  next,  previous,  up
@section The defsystem grammar

@verbatim
system-definition := ( defsystem system-designator {option}* )

option := :components component-list
        | :pathname pathname
        | :default-component-class
        | :perform method-form 
        | :explain method-form
	| :output-files  method-form
        | :operation-done-p method-form
Gary King's avatar
Gary King committed
445
        | :depends-on ( {dependency-def}* ) 
446
447
448
449
450
451
452
453
454
455
	| :serial [ t | nil ]
        | :in-order-to ( {dependency}+ )

component-list := ( {component-def}* )
                
component-def  := simple-component-name
                | ( component-type name {option}* )

component-type := :module | :file | :system | other-component-type

Gary King's avatar
Gary King committed
456
457
458
459
dependency-def := simple-component-name
               | ( :feature name )
               | ( :version simple-component-name version-specifier)

460
461
462
463
464
dependency := (dependent-op {requirement}+)
requirement := (required-op {required-component}+)
             | (feature feature-name)
dependent-op := operation-name
required-op := operation-name | feature
Gary King's avatar
Gary King committed
465
466
467

simple-component-name := string
                      |  symbol
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
@end verbatim

@subsection Serial dependencies

If the @code{:serial t} option is specified for a module, asdf will add
dependencies for each each child component, on all the children
textually preceding it.  This is done as if by @code{:depends-on}.

@lisp
:components ((:file "a") (:file "b") (:file "c"))
:serial t
@end lisp

is equivalent to

@lisp
:components ((:file "a") 
	     (:file "b" :depends-on ("a"))
	     (:file "c" :depends-on ("a" "b")))
@end lisp


@subsection Source location

The @code{:pathname} option is optional in all cases for systems
defined via @code{defsystem}, and in the usual case the user is
recommended not to supply it.

Instead, asdf follows a hairy set of rules that are designed so that
@enumerate
@item @code{find-system} will load a system from disk and have its pathname
default to the right place
@item this pathname information will not be
overwritten with @code{*default-pathname-defaults*} (which could be
somewhere else altogether) if the user loads up the @file{.asd} file
into his editor and interactively re-evaluates that form.
@end enumerate

If a system is being loaded for the first time, its top-level pathname
will be set to:

@itemize
@item The host/device/directory parts of @code{*load-truename*}, if it is bound
@item @code{*default-pathname-defaults*}, otherwise
@end itemize

If a system is being redefined, the top-level pathname will be

@itemize
@item
changed, if explicitly supplied or obtained from
@code{*load-truename*} (so that an updated source location is
reflected in the system definition)
@item
changed if it had previously been set from
@code{*default-pathname-defaults*}
@item
left as before, if it had previously been set from
@code{*load-truename*} and @code{*load-truename*} is currently
unbound (so that a developer can evaluate a @code{defsystem} form from
within an editor without clobbering its source location)
@end itemize

531
@node Other code in .asd files,  , The defsystem grammar, Defining systems with defsystem
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
@section Other code in .asd files

Files containing defsystem forms are regular Lisp files that are
executed by @code{load}.  Consequently, you can put whatever Lisp code
you like into these files (e.g., code that examines the compile-time
environment and adds appropriate features to @code{*features*}).
However, some conventions should be followed, so that users can
control certain details of execution of the Lisp in .asd files:

@itemize
@item
Any informative output (other than warnings and errors, which are the
condition system's to dispose of) should be sent to the standard CL
stream @code{*standard-output*}, so that users can easily control the
disposition of output from asdf operations.
@end itemize
548
549


550
@node The object model of asdf, Controlling where ASDF saves compiled files, Defining systems with defsystem, Top
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
@comment  node-name,  next,  previous,  up
@chapter The object model of asdf

asdf is designed in an object-oriented way from the ground up.  Both a
system's structure and the operations that can be performed on systems
follow a protocol.  asdf is extensible to new operations and to new
component types.  This allows the addition of behaviours: for example,
a new component could be added for Java JAR archives, and methods
specialised on @code{compile-op} added for it that would accomplish the
relevant actions.

This chapter deals with @emph{components}, the building blocks of a
system, and @emph{operations}, the actions that can be performed on a
system.



@menu
* Operations::                  
* Components::                  
@end menu

@node  Operations, Components, The object model of asdf, The object model of asdf
@comment  node-name,  next,  previous,  up
@section Operations
@cindex operation

An @dfn{operation} object of the appropriate type is instantiated
whenever the user wants to do something with a system like

@itemize
@item compile all its files
@item load the files into a running lisp environment
@item copy its source files somewhere else
@end itemize

Operations can be invoked directly, or examined to see what their
effects would be without performing them.  @emph{FIXME: document how!}  There
are a bunch of methods specialised on operation and component type
that actually do the grunt work.

The operation object contains whatever state is relevant for this
purpose (perhaps a list of visited nodes, for example) but primarily
is a nice thing to specialise operation methods on and easier than
having them all be EQL methods.

Operations are invoked on systems via @code{operate}.

@deffn {Generic function} operate operation system &rest initargs
@deffnx {Generic function} oos operation system &rest initargs
@code{operate} invokes @var{operation} on @var{system}.  @code{oos}
is a synonym for @code{operate}.

@var{operation} is a symbol that is passed, along with the supplied
@var{initargs}, to @code{make-instance} to create the operation object.
@var{system} is a system designator.

The initargs are passed to the @code{make-instance} call when creating
the operation object.  Note that dependencies may cause the operation
to invoke other operations on the system or its components: the new
operations will be created with the same initargs as the original one.

@end deffn

@menu
* Predefined operations of asdf::  
* Creating new operations::     
@end menu

@node Predefined operations of asdf, Creating new operations, Operations, Operations
@comment  node-name,  next,  previous,  up
@subsection Predefined operations of asdf

All the operations described in this section are in the @code{asdf}
package.  They are invoked via the @code{operate} generic function.

@lisp
(asdf:operate 'asdf:@var{operation-name} '@var{system-name} @{@var{operation-options ...}@})
@end lisp

@deffn Operation compile-op &key proclamations

This operation compiles the specified component.  If proclamations are
supplied, they will be proclaimed.  This is a good place to specify
optimization settings.

When creating a new component type, you should provide methods for
@code{compile-op}.

When @code{compile-op} is invoked, component dependencies often cause
some parts of the system to be loaded as well as compiled.  Invoking
@code{compile-op} does not necessarily load all the parts of the
system, though; use @code{load-op} to load a system.
@end deffn

@deffn Operation load-op &key proclamations

This operation loads a system.

The default methods for @code{load-op} compile files before loading them.
For parity, your own methods on new component types should probably do
so too.
@end deffn

@deffn Operation load-source-op

This operation will load the source for the files in a module even if
the source files have been compiled. Systems sometimes have knotty
dependencies which require that sources are loaded before they can be
compiled.  This is how you do that.

If you are creating a component type, you need to implement this
operation - at least, where meaningful.
@end deffn

@deffn Operation test-system-version &key minimum

Asks the system whether it satisfies a version requirement.

The default method accepts a string, which is expected to contain of a
number of integers separated by #\. characters.  The method is not
recursive.  The component satisfies the version dependency if it has
the same major number as required and each of its sub-versions is
greater than or equal to the sub-version number required.

@lisp
(defun version-satisfies (x y)
  (labels ((bigger (x y)
	     (cond ((not y) t)
		   ((not x) nil)
		   ((> (car x) (car y)) t)
		   ((= (car x) (car y))
		    (bigger (cdr x) (cdr y))))))
    (and (= (car x) (car y))
	 (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
@end lisp

If that doesn't work for your system, you can override it.  I hope
you have as much fun writing the new method as @verb{|#lisp|} did
reimplementing this one.
@end deffn

@deffn Operation feature-dependent-op

An instance of @code{feature-dependent-op} will ignore any components
which have a @code{features} attribute, unless the feature combination
it designates is satisfied by @code{*features*}.  This operation is
not intended to be instantiated directly, but other operations may
inherit from it.

@end deffn

@node  Creating new operations,  , Predefined operations of asdf, Operations
@comment  node-name,  next,  previous,  up
@subsection Creating new operations

asdf was designed to be extensible in an object-oriented fashion.  To
teach asdf new tricks, a programmer can implement the behaviour he
wants by creating a subclass of @code{operation}.


asdf's pre-defined operations are in no way ``privileged'', but it is
requested that developers never use the @code{asdf} package for
operations they develop themselves.  The rationale for this rule is
that we don't want to establish a ``global asdf operation name
registry'', but also want to avoid name clashes.

An operation must provide methods for the following generic functions
when invoked with an object of type @code{source-file}:  @emph{FIXME describe
this better}

@itemize

@item @code{output-files}
@item @code{perform}
The @code{perform} method must call @code{output-files} to find out
where to put its files, because the user is allowed to override
@item @code{output-files} for local policy @code{explain}
@item @code{operation-done-p}, if you don't like the default one

@end itemize

733
734
735
Operations that print output should send that output to the standard
CL stream @code{*standard-output*}, as the Lisp compiler and loader do.

736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
@node Components,  , Operations, The object model of asdf
@comment  node-name,  next,  previous,  up
@section Components
@cindex component
@cindex system
@cindex system designator
@vindex *system-definition-search-functions*

A @dfn{component} represents a source file or (recursively) a
collection of components.  A @dfn{system} is (roughly speaking) a
top-level component that can be found via @code{find-system}.

A @dfn{system designator} is a string or symbol and behaves just like
any other component name (including with regard to the case conversion
rules for component names).


@defun find-system system-designator &optional (error-p t)

Given a system designator, @code{find-system} finds and returns a
system.  If no system is found, an error of type
@code{missing-component} is thrown, or @code{nil} is returned if
@code{error-p} is false.

To find and update systems, @code{find-system} funcalls each element
in the @code{*system-definition-search-functions*} list, expecting a
pathname to be returned.  The resulting pathname is loaded if either
of the following conditions is true:

@itemize
@item there is no system of that name in memory
@item the file's last-modified time exceeds the last-modified time of the
  system in memory
@end itemize

When system definitions are loaded from @file{.asd} files, a new
scratch package is created for them to load into, so that different
systems do not overwrite each others operations.  The user may also
wish to (and is recommended to) include @code{defpackage} and
@code{in-package} forms in his system definition files, however, so
that they can be loaded manually if need be.

The default value of @code{*system-definition-search-functions*} is a
function that looks in each of the directories given by evaluating
members of @code{*central-registry*} for a file whose name is the
name of the system and whose type is @file{asd}.  The first such file
is returned, whether or not it turns out to actually define the
appropriate system.  Hence, it is strongly advised to define a system
@var{foo} in the corresponding file @var{foo.asd}.
@end defun


@menu
* Common attributes of components::  
* Pre-defined subclasses of component::  
* Creating new component types::  
@end menu

@node  Common attributes of components, Pre-defined subclasses of component, Components, Components
@comment  node-name,  next,  previous,  up
@subsection Common attributes of components

All components, regardless of type, have the following attributes.
All attributes except @code{name} are optional.

@subsubsection Name

A component name is a string or a symbol.  If a symbol, its name is
taken and lowercased.  The name must be a suitable value for the
@code{:name} initarg to @code{make-pathname} in whatever filesystem
the system is to be found.

The lower-casing-symbols behaviour is unconventional, but was selected
after some consideration.  Observations suggest that the type of
systems we want to support either have lowercase as customary case
(Unix, Mac, windows) or silently convert lowercase to uppercase
(lpns), so this makes more sense than attempting to use @code{:case
:common} as argument to @code{make-pathname}, which is reported not to
Robert P. Goldman's avatar
Nits.    
Robert P. Goldman committed
814
work on some implementations.
815
816
817
818
819
820
821
822
823
824

@subsubsection Version identifier

This optional attribute is used by the test-system-version
operation. @xref{Predefined operations of asdf}.  For the default method of
test-system-version, the version should be a string of intergers
separated by dots, for example @samp{1.0.11}.

@subsubsection Required features

Robert P. Goldman's avatar
Nits.    
Robert P. Goldman committed
825
826
827
828
829
@emph{FIXME:  This subsection seems to contradict the defsystem grammar
subsection; which doesn't provide any obvious way to specify required
features.  Furthermore, recent discussion on the asdf-devel mailing list
suggests that the specification of required features may be broken.}

830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
Traditionally defsystem users have used reader conditionals to include
or exclude specific per-implementation files.  This means that any
single implementation cannot read the entire system, which becomes a
problem if it doesn't wish to compile it, but instead for example to
create an archive file containing all the sources, as it will omit to
process the system-dependent sources for other systems.

Each component in an asdf system may therefore specify features using
the same syntax as #+ does, and it will (somehow) be ignored for
certain operations unless the feature conditional is a member of
@code{*features*}.


@subsubsection Dependencies

This attribute specifies dependencies of the component on its
siblings.  It is optional but often necessary.

There is an excitingly complicated relationship between the initarg
and the method that you use to ask about dependencies

Dependencies are between (operation component) pairs.  In your
initargs for the component, you can say

@lisp
:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
	      (load-op (load-op "foo")))
@end lisp

This means the following things:
@itemize
@item
before performing compile-op on this component, we must perform
load-op on @var{a} and @var{b}, and compile-op on @var{c},
@item
before performing @code{load-op}, we have to load @var{foo}
@end itemize

The syntax is approximately

@verbatim
(this-op {(other-op required-components)}+)

required-components := component-name
                     | (required-components required-components)

component-name := string
                | (:version string minimum-version-object)
@end verbatim

Side note:

This is on a par with what ACL defsystem does.  mk-defsystem is less
general: it has an implied dependency

@verbatim
  for all x, (load x) depends on (compile x)
@end verbatim

and using a @code{:depends-on} argument to say that @var{b} depends on
@var{a} @emph{actually} means that

@verbatim
  (compile b) depends on (load a) 
@end verbatim

This is insufficient for e.g. the McCLIM system, which requires that
all the files are loaded before any of them can be compiled ]

End side note

In asdf, the dependency information for a given component and
operation can be queried using @code{(component-depends-on operation
component)}, which returns a list

@lisp
((load-op "a") (load-op "b") (compile-op "c") ...)
@end lisp

@code{component-depends-on} can be subclassed for more specific
component/operation types: these need to @code{(call-next-method)} and
append the answer to their dependency, unless they have a good reason
Robert P. Goldman's avatar
Nits.    
Robert P. Goldman committed
912
for completely overriding the default dependencies.
913

Robert P. Goldman's avatar
Nits.    
Robert P. Goldman committed
914
If it weren't for CLISP, we'd be using @code{LIST} method
915
916
combination to do this transparently.  But, we need to support CLISP.
If you have the time for some CLISP hacking, I'm sure they'd welcome
Robert P. Goldman's avatar
Nits.    
Robert P. Goldman committed
917
your fixes.
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000

@subsubsection pathname

This attribute is optional and if absent will be inferred from the
component's name, type (the subclass of source-file), and the location
of its parent.

The rules for this inference are:

(for source-files)
@itemize
@item the host is taken from the parent
@item pathname type is @code{(source-file-type component system)}
@item the pathname case option is @code{:local}
@item the pathname is merged against the parent
@end itemize

(for modules)
@itemize
@item the host is taken from the parent
@item the name and type are @code{NIL}
@item the directory is @code{(:relative component-name)}
@item the pathname case option is @code{:local}
@item the pathname is merged against the parent
@end itemize

Note that the DEFSYSTEM operator (used to create a ``top-level''
system) does additional processing to set the filesystem location of
the top component in that system.  This is detailed
elsewhere, @xref{Defining systems with defsystem}.

The answer to the frequently asked question "how do I create a system 
definition where all the source files have a .cl extension" is thus

@lisp
(defmethod source-file-type ((c cl-source-file) (s (eql (find-system 'my-sys))))
   "cl")
@end lisp

@subsubsection properties

This attribute is optional.

Packaging systems often require information about files or systems in
addition to that specified by asdf's pre-defined component attributes.
Programs that create vendor packages out of asdf systems therefore
have to create ``placeholder'' information to satisfy these systems.
Sometimes the creator of an asdf system may know the additional
information and wish to provide it directly.

(component-property component property-name) and associated setf
method will allow the programmatic update of this information.
Property names are compared as if by @code{EQL}, so use symbols or
keywords or something.

@menu
* Pre-defined subclasses of component::  
* Creating new component types::  
@end menu

@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
@comment  node-name,  next,  previous,  up
@subsection Pre-defined subclasses of component

@deffn Component source-file

A source file is any file that the system does not know how to
generate from other components of the system. 

Note that this is not necessarily the same thing as ``a file
containing data that is typically fed to a compiler''.  If a file is
generated by some pre-processor stage (e.g. a @file{.h} file from
@file{.h.in} by autoconf) then it is not, by this definition, a source
file.  Conversely, we might have a graphic file that cannot be
automatically regenerated, or a proprietary shared library that we
received as a binary: these do count as source files for our purposes.

Subclasses of source-file exist for various languages.  @emph{FIXME:
describe these.}
@end deffn

@deffn Component module