Smaller safepoint sequence: Now use a static offset from the thread
[sbcl/pkhuong.git] / contrib / asdf / README
blob53f88f1167a51d11bee7c6f5dc470cd119f979da
1 README,v 1.39 2006/08/21 10:52:32 crhodes Exp         -*- Text -*-
3 The canonical documentation for asdf is in the file asdf.texinfo.  
4 The significant overlap between this file and that will one day be
5 resolved by deleting text from this file; in the meantime, please look
6 there before here.
10 asdf: another system definition facility          
11 ========================================
13 * Getting the latest version
15 0) Decide which version you want.  HEAD is the newest version and
16 usually OK, whereas RELEASE is for cautious people (e.g. who already
17 have systems using asdf that they don't want broken), a slightly older
18 version about which none of the HEAD users have complained.
20 1) Check it out from sourceforge cCLan CVS:
22 1a) cvs -d:pserver:anonymous@cvs.cclan.sourceforge.net:/cvsroot/cclan login
23      (no password: just press Enter)
25 1a.1) cvs -z3 -d:pserver:anonymous@cvs.cclan.sourceforge.net:/cvsroot/cclan
26          co -r RELEASE asdf
28 or for the bleeding edge, instead
30 1a.2) cvs -z3 -d:pserver:anonymous@cvs.cclan.sourceforge.net:/cvsroot/cclan
31           co -A asdf
33 If you are tracking the bleeding edge, you may want to subscribe to
34 the cclan-commits mailing list (see
35 <URL:http://sourceforge.net/mail/?group_id=28536>) to receive commit
36 messages and diffs whenever changes are made.
38 For more CVS information, look at http://sourceforge.net/cvs/?group_id=28536
41 * Getting started
43 - The single file asdf.lisp is all you need to use asdf normally.  For
44 maximum convenience you want to have it loaded whenever you start your
45 Lisp implementation, by loading it from the startup script, or dumping
46 a custom core, or something.
48 - The variable asdf:*central-registry* is a list of system directory
49   designators.  A system directory designator is a form which will be
50   evaluated whenever a system is to be found, and must evaluate to a
51   directory to look in.  For example, you might have
53      (*default-pathname-defaults* "/home/me/cl/systems/"
54       "/usr/share/common-lisp/systems/")
56   (When we say "directory" here, we mean "designator for a pathname
57   with a supplied DIRECTORY component")
59   It is possible to customize the system definition file search.
60   That's considered advanced use, and covered later: search forward
61   for *system-definition-search-functions*
63 - To compile and load a system 'foo', you need to (1) ensure that
64   foo.asd is in one of the directories in *central-registry* (a
65   symlink to the real location of foo.asd is preferred), (2) execute
66   ``(asdf:operate 'asdf:load-op 'foo)''
68     $ cd /home/me/cl/systems/
69     $ ln -s ~/src/foo/foo.asd .
70     $ lisp
71     * (asdf:operate 'asdf:load-op 'foo)
73 - To write your own system definitions, look at the test systems in
74   test/ , and read the rest of this.  Ignore systems/ which is old
75   and may go away when next I clean up
77 - Syntax is similar to mk-defsystem 3 for straightforward systems, you
78   may only need to remove the :source-pathname option (and replace it
79   with :pathname if the asd file is not in the same place as the
80   system sources)
82 - Join cclan-list@lists.sf.net for discussion, bug reports, questions, etc
84 - cclan.asd and the source files listed therein contain useful extensions 
85   for maintainers of systems in the cCLan.  If this isn't you, you
86   don't need them - although you may want to look at them anyway
88 - For systems that do complicated things (e.g. compiling C files to
89   load as foreign code), the packages in vn-cclan may provide some
90   guidance.  db-sockets, for example, is known to do outlandish things
91   with preprocessors
93    http://ww.telent.net/cliki/vn-cclan 
97 * Concepts
99 This system definition utility talks in terms of 'components' and
100 'operations'.
102 Components form systems: a component represents a source file, or a
103 collection of components.  A system is therefore a component,
104 recursively formed of a tree of subcomponents.
106 Operations are instantiated then performed on the nodes of a tree to
107 do things like
109  - compile all its files
110  - load the files into a running lisp environment
111  - copy its source files somewhere else
113 Operations can be invoked directly, or examined to see what their
114 effects would be without performing them.  There are a bunch of 
115 methods specialised on operation and component type which actually do
116 the grunt work.
118 asdf is extensible to new operations and to new component types.  This
119 allows the addition of behaviours: for example, a new component could
120 be added for Java JAR archives, and methods specialised on compile-op
121 added for it that would accomplish the relevant actions.  Users
122 defining their own operations and component types should inherit from
123 the asdf base classes asdf:operation and asdf:component respectively.
125 * Inspiration
127 ** mk-defsystem (defsystem-3.x)
129 We aim to solve basically the same problems as mk-defsystem does.
130 However, our architecture for extensibility better exploits CL
131 language features (and is documented), and we intend to be portable
132 rather than just widely-ported.  No slight on the mk-defsystem authors
133 and maintainers is intended here; that implementation has the
134 unenviable task of supporting non-ANSI implementations, which I
135 propose to ignore.
137 The surface defsystem syntax of asdf is more-or-less compatible with
138 mk-defsystem
140 The mk-defsystem code for topologically sorting a module's dependency
141 list was very useful.
143 ** defsystem-4 proposal
145 Marco and Peter's proposal for defsystem 4 served as the driver for
146 many of the features in here.  Notable differences are
148 - we don't specify output files or output file extensions as part of
149   the system
151   If you want to find out what files an operation would create, ask
152   the operation
154 - we don't deal with CL packages
156   If you want to compile in a particular package, use an in-package
157   form in that file (ilisp will like you more if you do this anyway)
159 - there is no proposal here that defsystem does version control.  
161   A system has a given version which can be used to check
162   dependencies, but that's all.
164 The defsystem 4 proposal tends to look more at the external features,
165 whereas this one centres on a protocol for system introspection.
167 ** kmp's "The Description of Large Systems", MIT AI Memu 801
169 Available in updated-for-CL form on the web at 
170 http://world.std.com/~pitman/Papers/Large-Systems.html
172 In our implementation we borrow kmp's overall PROCESS-OPTIONS and
173 concept to deal with creating component trees from defsystem surface
174 syntax.  [ this is not true right now, though it used to be and
175 probably will be again soon ]
178 * The Objects
180 ** component
182 *** Component Attributes
184 **** A name (required)
186 This is a string or a symbol.  If a symbol, its name is taken and
187 lowercased.  The name must be a suitable value for the :name initarg
188 to make-pathname in whatever filesystem the system is to be found.
190 The lower-casing-symbols behaviour is unconventional, but was selected
191 after some consideration.  Observations suggest that the type of
192 systems we want to support either have lowercase as customary case
193 (Unix, Mac, windows) or silently convert lowercase to uppercase
194 (lpns), so this makes more sense than attempting to use :case :common,
195 which is reported not to work on some implementations
197 **** a version identifier (optional)
199 This is used by the test-system-version operation (see later).
201 **** *features* required
203 Traditionally defsystem users have used reader conditionals to include
204 or exclude specific per-implementation files.  This means that any
205 single implementation cannot read the entire system, which becomes a
206 problem if it doesn't wish to compile it, but instead for example to
207 create an archive file containing all the sources, as it will omit to
208 process the system-dependent sources for other systems.
210 Each component in an asdf system may therefore specify features using
211 the same syntax as #+ does, and it will (somehow) be ignored for
212 certain operations unless the feature conditional matches
214 **** dependencies on its siblings  (optional but often necessary)
216 There is an excitingly complicated relationship between the initarg
217 and the method that you use to ask about dependencies
219 Dependencies are between (operation component) pairs.  In your
220 initargs, you can say
222 :in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
223               (load-op (load-op "foo")))
225 - before performing compile-op on this component, we must perform
226 load-op on "a" and "b", and compile-op on c, - before performing
227 load-op, we have to load "foo"
229 The syntax is approximately
231 (this-op {(other-op required-components)}+)
233 required-components := component-name
234                      | (required-components required-components)
236 component-name := string
237                 | (:version string minimum-version-object)
239 [ This is on a par with what ACL defsystem does.  mk-defsystem is less
240 general: it has an implied dependency
242   for all x, (load x) depends on (compile x)
244 and using a :depends-on argument to say that b depends on a _actually_
245 means that
247   (compile b) depends on (load a) 
249 This is insufficient for e.g. the McCLIM system, which requires that
250 all the files are loaded before any of them can be compiled ]
252 In asdf, the dependency information for a given component and
253 operation can be queried using (component-depends-on operation
254 component), which returns a list
256 ((load-op "a") (load-op "b") (compile-op "c") ...)
258 component-depends-on can be subclassed for more specific
259 component/operation types: these need to (call-next-method) and append
260 the answer to their dependency, unless they have a good reason for
261 completely overriding the default dependencies
263 (If it weren't for CLISP, we'd be using a LIST method combination to
264 do this transparently.  But, we need to support CLISP.  If you have
265 the time for some CLISP hacking, I'm sure they'd welcome your fixes)
267 **** a pathname
269 This is optional and if absent will be inferred from name, type (the
270 subclass of source-file), and the location of parent.
272 The rules for this inference are:
274 (for source-files)
275 - the host is taken from the parent
276 - pathname type is (source-file-type component system)
277 - the pathname case option is :local
278 - the pathname is merged against the parent
280 (for modules)
281 - the host is taken from the parent
282 - the name and type are NIL
283 - the directory is (:relative component-name)
284 - the pathname case option is :local
285 - the pathname is merged against the parent
287 Note that the DEFSYSTEM operator (used to create a "top-level" system)
288 does additional processing to set the filesystem location of the
289 top component in that system.  This is detailed elsewhere
291 The answer to the frequently asked question "how do I create a system 
292 definition where all the source files have a .cl extension" is thus
294 (defmethod source-file-type ((c cl-source-file) (s (eql (find-system 'my-sys))))
295    "cl")
297 **** properties (optional)
299 Packaging systems often require information about files or systems
300 additional to that specified here.  Programs that create vendor
301 packages out of asdf systems therefore have to create "placeholder"
302 information to satisfy these systems.  Sometimes the creator of an
303 asdf system may know the additional information and wish to provide it
304 directly.
306 (component-property component property-name) and associated setf method 
307 will allow the programmatic update of this information.  Property
308 names are compared as if by EQL, so use symbols or keywords or something
310 ** Subclasses of component
312 *** 'source-file'
314 A source file is any file that the system does not know how to
315 generate from other components of the system. 
317 (Note that this is not necessarily the same thing as "a file
318 containing data that is typically fed to a compiler".  If a file is
319 generated by some pre-processor stage (e.g. a ".h" file from ".h.in"
320 by autoconf) then it is not, by this definition, a source file.
321 Conversely, we might have a graphic file that cannot be automatically
322 regenerated, or a proprietary shared library that we received as a
323 binary: these do count as source files for our purposes.  All
324 suggestions for better terminology gratefully received)
326 Subclasses of source-file exist for various languages.  
328 *** 'module', a collection of sub-components
330 This has extra slots for
332  :components - the components contained in this module
334  :default-component-class - for child components which don't specify
335    their class explicitly
337  :if-component-dep-fails takes one of the values :fail, :try-next, :ignore 
338    (default value is :fail).  The other values can be used for implementing
339    conditional compilation based on implementation *features*, where
340    it is not necessary for all files in a module to be compiled
342 The default operation knows how to traverse a module, so most
343 operations will not need to provide methods specialised on modules.
345 The module may be subclassed to represent components such as
346 foreign-language linked libraries or archive files.
348 *** system, subclasses module
350 A system is a module with a few extra attributes for documentation
351 purposes.  In behaviour, it's usually identical.
353 Users can create new classes for their systems: the default defsystem
354 macro takes a :classs keyword argument.
357 ** operation
359 An operation is instantiated whenever the user asks that an operation
360 be performed, inspected, or etc.  The operation object contains
361 whatever state is relevant to this purpose (perhaps a list of visited
362 nodes, for example) but primarily is a nice thing to specialise
363 operation methods on and easier than having them all be EQL methods.
365 There are no differences between standard operations and user-defined
366 operations, except that the user is respectfully requested to keep his
367 (or more importantly, our) package namespace clean
369 *** invoking operations
371 (operate operation system &rest keywords-args)
373 keyword-args are passed to the make-instance call when creating the
374 operation: valid keywords depend on the initargs that the operation is
375 defined to accept.  Note that dependencies may cause the operation to
376 invoke other operations on the system or its components: the new
377 operation will be created with the same initargs as the original one.
379 oos is accepted as a synonym for operate
381 *** standard operations
383 **** feature-dependent-op
385 This is not intended to be instantiated directly, but other operations
386 may inherit from it.  An instance of feature-dependent-op will ignore
387 any components which have a `features' attribute, unless the feature
388 combination it designates is satisfied by *features*
390 See the earlier explanation about the component features attribute for
391 more information
393 **** compile-op &key proclamations
395 If proclamations are supplied, they will be proclaimed.  This is a
396 good place to specify optimization settings
398 When creating a new component, you should provide methods for this.  
400 If you invoke compile-op as a user, component dependencies often mean
401 you may get some parts of the system loaded.  This may not necessarily
402 be the whole thing, though; for your own sanity it is recommended that
403 you use load-op if you want to load a system.
405 **** load-op &key proclamations
407 The default methods for load-op compile files before loading them.
408 For parity, your own methods on new component types should probably do
409 so too
411 **** load-source-op
413 This method will load the source for the files in a module even if the
414 source files have been compiled. Systems sometimes have knotty
415 dependencies which require that sources are loaded before they can be
416 compiled.  This is how you do that.
418 If you are creating a component type, you need to implement this
419 operation - at least, where meaningful.
421 **** test-system-version &key minimum
423 Asks the system whether it satisfies a version requirement.
425 The default method accepts a string, which is expected to contain of a
426 number of integers separated by #\. characters.  The method is not
427 recursive.  The component satisfies the version dependency if it has
428 the same major number as required and each of its sub-versions is
429 greater than or equal to the sub-version number required.
431 (defun version-satisfies (x y)
432   (labels ((bigger (x y)
433              (cond ((not y) t)
434                    ((not x) nil)
435                    ((> (car x) (car y)) t)
436                    ((= (car x) (car y))
437                     (bigger (cdr x) (cdr y))))))
438     (and (= (car x) (car y))
439          (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
441 If that doesn't work for your system, you can override it.  I hope
442 yoyu have as much fun writing the new method as #lisp did
443 reimplementing this one. 
445 *** Creating new operations
447 subclass operation, provide methods for source-file for 
449 - output-files
450 - perform
451    The perform method must call output-files to find out where to
452    put its files, because the user is allowed to override output-files
453    for local policy
454 - explain
455 - operation-done-p, if you don't like the default one
457 * Writing system definitions
459 ** System designators
461 System designators are strings or symbols and behave just like
462 any other component names (including case conversion)
464 ** find-system
466 Given a system designator, find-system finds an actual system - either
467 in memory, or in a file on the disk.  It funcalls each element in the
468 *system-definition-search-functions* list, expecting a pathname to be
469 returned.
471 If a suitable file exists, it is loaded if
473 - there is no system of that name in memory, 
474 - the file's last-modified time exceeds the last-modified time of the
475   system in memory
477 When system definitions are loaded from .asd files, a new scratch
478 package is created for them to load into, so that different systems do
479 not overwrite each others operations.  The user may also wish to (and
480 is recommended to) include defpackage and in-package forms in his
481 system definition files, however, so that they can be loaded manually
482 if need be.  It is not recommended to use the CL-USER package for this
483 purpose, as definitions made in this package will affect the parsing
484 of asdf systems.
486 For convenience in the normal case, and for backward compatibility
487 with the spirit of mk-defsystem, the default contents of
488 *system-definition-search-functions* is a function called
489 sysdef-central-registry-search.  This looks in each of the directories
490 given by evaluating members of *central-registry*, for a file whose
491 name is the name of the system and whose type is "asd".  The first
492 such file is returned, whether or not it turns out to actually define
493 the appropriate system
497 ** Syntax
499 Systems can always be constructed programmatically by instantiating
500 components using make-instance.  For most purposes, however, it is
501 likely that people will want a static defystem form. 
503 asdf is based around the principle that components should not have to
504 know defsystem syntax.  That is, the initargs that a component accepts
505 are not necessarily related to the defsystem form which creates it.
507 A defsystem parser must implement a `defsystem' macro, which can
508 be named for compatibility with whatever other system definition
509 utility is being emulated.  It should instantiate components in
510 accordance with whatever language it accepts, and register the topmost
511 component using REGISTER-SYSTEM
513 *** Native syntax
515 The native syntax is inspired by mk-defsystem, to the extent that it
516 should be possible to take most straightforward mk- system definitions
517 and run them with only light editing.  For my convenience, this turns
518 out to be basically the same as the initargs to the various
519 components, with a few extensions for convenience
520                
521 system-definition := ( defsystem system-designator {option}* )
523 option := :components component-list
524         | :pathname pathname
525         | :default-component-class
526         | :perform method-form 
527         | :explain method-form
528         | :output-files  method-form
529         | :operation-done-p method-form
530         | :depends-on ( {simple-component-name}* ) 
531         | :serial [ t | nil ]
532         | :in-order-to ( {dependency}+ )
534 component-list := ( {component-def}* )
535                 
536 component-def  := simple-component-name
537                 | ( component-type name {option}* )
539 component-type := :module | :file | :system | other-component-type
541 dependency := (dependent-op {requirement}+)
542 requirement := (required-op {required-component}+)
543              | (feature feature-name)
544 dependent-op := operation-name
545 required-op := operation-name | feature
547 For example
549 (defsystem "foo"
550   :version "1.0"
551   :components ((:module "foo" :components ((:file "bar") (:file"baz") 
552                                            (:file "quux"))
553                 :perform (compile-op :after (op c)
554                           (do-something c))
555                 :explain (compile-op :after (op c)
556                           (explain-something c)))
557                (:file "blah")))
560 The method-form tokens need explaining: esentially, 
562                 :perform (compile-op :after (op c)
563                           (do-something c))
564                 :explain (compile-op :after (op c)
565                           (explain-something c)))
566 has the effect of
568 (defmethod perform :after ((op compile-op) (c (eql ...)))
569            (do-something c))
570 (defmethod explain :after ((op compile-op) (c (eql ...)))
571            (explain-something c))
573 where ... is the component in question; note that although this also
574 supports :before methods, they may not do what you want them to - a
575 :before method on perform ((op compile-op) (c (eql ...)))  will run
576 after all the dependencies and sub-components have been processed, but
577 before the component in question has been compiled.
579 **** Serial dependencies
581 If the `:serial t' option is specified for a module, asdf will add
582 dependencies for each each child component, on all the children
583 textually preceding it.  This is done as if by :depends-on
585 :components ((:file "a") (:file "b") (:file "c"))
586 :serial t
588 is equivalent to
589 :components ((:file "a") 
590              (:file "b" :depends-on ("a"))
591              (:file "c" :depends-on ("a" "b")))
595 have all the 
597 **** Source location
599 The :pathname option is optional in all cases for native-syntax
600 systems, and in the usual case the user is recommended not to supply
601 it.  If it is not supplied for the top-level form, defsystem will set
602 it from
604 - The host/device/directory parts of *load-truename*, if it is bound
605 - *default-pathname-defaults*, otherwise
607 If a system is being redefined, the top-level pathname will be 
609 - changed, if explicitly supplied or obtained from *load-truename*
610 - changed if it had previously been set from *default-pathname-defaults*
611 - left as before, if it had previously been set from *load-truename*
612   and *load-truename* is not now bound
614 These rules are designed so that (i) find-system will load a system
615 from disk and have its pathname default to the right place, (ii)
616 this pathname information will not be overwritten with
617 *default-pathname-defaults* (which could be somewhere else altogether)
618 if the user loads up the .asd file into his editor and
619 interactively re-evaluates that form
621  * Error handling
623 It is an error to define a system incorrectly: an implementation may
624 detect this and signal a generalised instance of
625 SYSTEM-DEFINITION-ERROR.
627 Operations may go wrong (for example when source files contain
628 errors).  These are signalled using generalised instances of
629 OPERATION-ERROR, with condition readers ERROR-COMPONENT and
630 ERROR-OPERATION for the component and operation which erred.
632 * Compilation error and warning handling
634 ASDF checks for warnings and errors when a file is compiled. The
635 variables *compile-file-warnings-behaviour* and
636 *compile-file-errors-behavior* controls the handling of any such
637 events. The valid values for these variables are :error, :warn, and
638 :ignore.
640 ----------------------------------------------------------
641                       TODO List
642 ----------------------------------------------------------
644 * Outstanding spec questions, things to add
646 ** packaging systems
648 *** manual page component?
650 ** style guide for .asd files
652 You should either use keywords or be careful with the package that you
653 evaluate defsystem forms in.  Otherwise (defsystem partition ...)
654 being read in the cl-user package will intern a cl-user:partition
655 symbol, which will then collide with the partition:partition symbol.
657 Actually there's a hairier packages problem to think about too.
658 in-order-to is not a keyword: if you read defsystem forms in a package
659 that doesn't use ASDF, odd things might happen
661 ** extending defsystem with new options
663 You might not want to write a whole parser, but just to add options to
664 the existing syntax.  Reinstate parse-option or something akin
666 ** document all the error classes
668 ** what to do with compile-file failure
670 Should check the primary return value from compile-file and see if
671 that gets us any closer to a sensible error handling strategy
673 ** foreign files
675 lift unix-dso stuff from db-sockets
677 ** Diagnostics
679 A "dry run" of an operation can be made with the following form:
681 (traverse (make-instance '<operation-name>)
682           (find-system <system-name>)
683           'explain)
685 This uses unexported symbols.  What would be a nice interface for this
686 functionality?
688 ** patches
690 Sometimes one wants to 
693 * missing bits in implementation
695 ** all of the above
696 ** reuse the same scratch package whenever a system is reloaded from disk
697 ** rules for system pathname defaulting are not yet implemented properly
698 ** proclamations probably aren't
699 ** when a system is reloaded with fewer components than it previously
700    had, odd things happen
702 we should do something inventive when processing a defsystem form,
703 like take the list of kids and setf the slot to nil, then transfer
704 children from old to new list as they're found
706 **  traverse may become a normal function
708 If you're defining methods on traverse,  speak up.
711 ** a lot of load-op methods can be rewritten to use input-files
713 so should be.
716 ** (stuff that might happen later)
718 *** david lichteblau's patch for symlink resolution?
720 *** Propagation of the :force option.  ``I notice that
722         (oos 'compile-op :araneida :force t)
724 also forces compilation of every other system the :araneida system
725 depends on.  This is rarely useful to me; usually, when I want to force
726 recompilation of something more than a single source file, I want to
727 recompile only one system.  So it would be more useful to have
728 make-sub-operation refuse to propagate ":force t" to other systems, and
729 propagate only something like ":force :recursively". ''
731 Ideally what we actually want is some kind of criterion that says
732 to which systems (and which operations) a :force switch will propagate.
734 The problem is perhaps that 'force' is a pretty meaningless concept.
735 How obvious is it that "load :force t" should force _compilation_?
736 But we don't really have the right dependency setup for the user to
737 compile :force t and expect it to work (files will not be loaded after
738 compilation, so the compile environment for subsequent files will be
739 emptier than it needs to be)
741 What does the user actually want to do when he forces?  Usually, for
742 me, update for use with a new version of the lisp compiler.  Perhaps
743 for recovery when he suspects that something has gone wrong.  Or else
744 when he's changed compilation options or configuration in some way
745 that's not reflected in the dependency graph.
747 Other possible interface: have a 'revert' function akin to 'make clean'
749   (asdf:revert 'asdf:compile-op 'araneida) 
751 would delete any files produced by 'compile-op 'araneida.  Of course, it
752 wouldn't be able to do much about stuff in the image itself.
754 How would this work?
756 traverse
758 There's a difference between a module's dependencies (peers) and its
759 components (children).  Perhaps there's a similar difference in
760 operations?  For example, (load "use") depends-on (load "macros") is a
761 peer, whereas (load "use") depends-on (compile "use") is more of a
762 `subservient' relationship.