Newer
Older
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
debugging.
@item
Record that testing is implemented by @var{foo-test}. For example:
@example
(defsystem @var{foo}
:in-order-to ((test-op (test-op @var{foo-test})))
....)
(defsystem @var{foo-test}
:depends-on (@var{foo} @var{my-test-library} ...)
....)
@end example
@end itemize
This procedure will allow you to support users who do not wish to
install your test framework.
One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
does not return a value. So in current versions of ASDF there is no
reliable programmatic means of determining whether or not a set of tests
has passed, or which tests have failed. The user must simply read the
console output. This limitation has been the subject of much
discussion.
@subsection ``How can I cater for documentation generation in my system?''
The ASDF developers are currently working to add a @code{doc-op}
to the set of predefined ASDF operations.
@xref{Predefined operations of ASDF}.
See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
@subsection ``How can I maintain non-Lisp (e.g. C) source files?''
@subsection ``I want to put my module's files at the top level. How do I do this?''
By default, the files contained in an asdf module go
in a subdirectory with the same name as the module.
However, this can be overridden by adding a @code{:pathname ""} argument
to the module description.
For example, here is how it could be done
in the spatial-trees ASDF system definition for ASDF 2:
@example
(asdf:defsystem :spatial-trees
:components
((:module base
:pathname ""
:components
((:file "package")
(:file "basedefs" :depends-on ("package"))
(:file "rectangles" :depends-on ("package"))))
(:module tree-impls
:depends-on (base)
:pathname ""
:components
((:file "r-trees")
(:file "greene-trees" :depends-on ("r-trees"))
(:file "rstar-trees" :depends-on ("r-trees"))
(:file "rplus-trees" :depends-on ("r-trees"))
(:file "x-trees" :depends-on ("r-trees" "rstar-trees"))))
(:module viz
:depends-on (base)
:pathname ""
((:static-file "spatial-tree-viz.lisp")))
:pathname ""
((:static-file "spatial-tree-test.lisp")))
(:static-file "LICENCE")
(:static-file "TODO")))
@end example
Francois-Rene Rideau
committed
All of the files in the @code{tree-impls} module are at the top level,
instead of in a @file{tree-impls/} subdirectory.
Francois-Rene Rideau
committed
Note that the argument to @code{:pathname} can be either a pathname object or a string.
A pathname object can be constructed with the @file{#p"foo/bar/"} syntax,
Francois-Rene Rideau
committed
but this is discouraged because the results of parsing a namestring are not portable.
A pathname can only be portably constructed with such syntax as
@code{#.(make-pathname :directory '(:relative "foo" "bar"))},
and similarly the current directory can only be portably specified as
Francois-Rene Rideau
committed
@code{#.(make-pathname :directory '(:relative))}.
However, as of ASDF 2, you can portably use a string to denote a pathname.
Francois-Rene Rideau
committed
The string will be parsed as a @code{/}-separated path from the current directory,
such that the empty string @code{""} denotes the current directory, and
@code{"foo/bar"} (no trailing @code{/} required in the case of modules)
portably denotes the same subdirectory as above.
Francois-Rene Rideau
committed
When files are specified, the last @code{/}-separated component is interpreted
either as the name component of a pathname
(if the component class specifies a pathname type),
or as a name component plus optional dot-separated type component
(if the component class doesn't specifies a pathname type).
Francois-Rene Rideau
committed
@subsection How do I create a system definition where all the source files have a .cl extension?
Francois-Rene Rideau
committed
Starting with ASDF 2.014.14, you may just pass
the builtin class @code{cl-source-file.cl} as
the @code{:default-component-class} argument to @code{defsystem}:
Francois-Rene Rideau
committed
(defsystem my-cl-system
:default-component-class cl-source-file.cl
...)
Francois-Rene Rideau
committed
Another builtin class @code{cl-source-file.lsp} is offered
for files ending in @file{.lsp}.
If you want to use a different extension
for which ASDF doesn't provide builtin support,
or want to support versions of ASDF
earlier than 2.014.14 (but later than 2.000),
you can define a class as follows:
Francois-Rene Rideau
committed
;; Prologue: make sure we're using a sane package.
(defpackage :my-asdf-extension
(:use :asdf :common-lisp)
(:export #:cl-source-file.lis))
(in-package :my-asdf-extension)
(defclass cl-source-file.lis (cl-source-file)
Francois-Rene Rideau
committed
((type :initform "lis")))
Francois-Rene Rideau
committed
@end lisp
Then you can use it as follows:
@lisp
(defsystem my-cl-system
:default-component-class my-asdf-extension:cl-source-file.lis
...)
Francois-Rene Rideau
committed
Of course, if you're in the same package, e.g. in the same file,
you won't need to use the package qualifier before @code{cl-source-file.lis}.
Actually, if all you're doing is defining this class
and using it in the same file without other fancy definitions,
you might skip package complications:
Francois-Rene Rideau
committed
(in-package :asdf)
(defclass cl-source-file.lis (cl-source-file)
((type :initform "lis")))
(defsystem my-cl-system
Francois-Rene Rideau
committed
:default-component-class cl-source-file.lis
...)
Francois-Rene Rideau
committed
It is possible to achieve the same effect
in a way that supports both ASDF 1 and ASDF 2,
but really, friends don't let friends use ASDF 1.
Please upgrade to ASDF 2.
In short, though: do same as above, but
@emph{before} you use the class in a @code{defsystem},
you also define the following method:
@lisp
Francois-Rene Rideau
committed
(defmethod source-file-type ((f cl-source-file.lis) (s system))
(declare (ignorable f s))
Francois-Rene Rideau
committed
"lis")
@end lisp
@comment FIXME: Add a FAQ about how to use a new system class...
@node TODO list, Inspiration, FAQ, Top
Here is an old list of things to do,
in addition to the bugs that are now tracked on launchpad:
@url{https://launchpad.net/asdf}.
@section Outstanding spec questions, things to add
** packaging systems
*** manual page component?
** style guide for .asd files
You should either use keywords or be careful
with the package that you evaluate defsystem forms in.
Otherwise @code{(defsystem partition ...)}
being read in the @code{cl-user} package
will intern a @code{cl-user:partition} symbol,
which will then collide with the @code{partition:partition} symbol.
Actually there's a hairier packages problem to think about too.
@code{in-order-to} is not a keyword:
if you read @code{defsystem} forms in a package that doesn't use ASDF,
odd things might happen.
** extending defsystem with new options
You might not want to write a whole parser,
but just to add options to the existing syntax.
Reinstate @code{parse-option} or something akin.
** Diagnostics
A ``dry run'' of an operation can be made with the following form:
@lisp
(let ((asdf::*verbose-out* *standard-output*))
(loop :for (op . comp) :in
(asdf::traverse (make-instance '<operation-name> :force t)
(asdf:find-system <system-name>))
:do (asdf:explain op comp)))
This uses unexported symbols.
What would be a nice interface for this functionality?
@section Missing bits in implementation
** reuse the same scratch package whenever a system is reloaded from disk
Have a package ASDF-USER instead of all these temporary packages?
** proclamations probably aren't
** A revert function
Other possible interface: have a ``revert'' function akin to @code{make clean}.
(asdf:revert 'asdf:compile-op 'araneida)
would delete any files produced by @code{(compile-system :araneida)}.
Of course, it wouldn't be able to do much about stuff in the image itself.
How would this work?
There's a difference between a module's dependencies (peers)
and its components (children).
Perhaps there's a similar difference in operations?
For example, @code{(load "use") depends-on (load "macros")} is a peer,
whereas @code{(load "use") depends-on (compile "use")}
is more of a ``subservient'' relationship.
@node Inspiration, Concept Index, TODO list, Top
@comment node-name, next, previous, up
@chapter Inspiration
@section mk-defsystem (defsystem-3.x)
We aim to solve basically the same problems as @code{mk-defsystem} does.
However, our architecture for extensibility
better exploits CL language features (and is documented),
and we intend to be portable rather than just widely-ported.
No slight on the @code{mk-defsystem} authors and maintainers is intended here;
that implementation has the unenviable task
of supporting pre-ANSI implementations, which is no longer necessary.
The surface defsystem syntax of asdf is more-or-less compatible with
@code{mk-defsystem}, except that we do not support
the @code{source-foo} and @code{binary-foo} prefixes
for separating source and binary files, and
we advise the removal of all options to specify pathnames.
The @code{mk-defsystem} code for topologically sorting
a module's dependency list was very useful.
@section defsystem-4 proposal
Marco and Peter's proposal for defsystem 4 served as the driver for
many of the features in here. Notable differences are:
@itemize
@item
We don't specify output files or output file extensions
as part of the system.
If you want to find out what files an operation would create,
ask the operation.
@item
We don't deal with CL packages
If you want to compile in a particular package, use an @code{in-package} form
in that file (ilisp / SLIME will like you more if you do this anyway)
@item
There is no proposal here that @code{defsystem} does version control.
A system has a given version which can be used to check dependencies,
but that's all.
@end itemize
The defsystem 4 proposal tends to look more at the external features,
whereas this one centres on a protocol for system introspection.
Francois-Rene Rideau
committed
@section kmp's ``The Description of Large Systems'', MIT AI Memo 801
Available in updated-for-CL form on the web at
@url{http://nhplace.com/kent/Papers/Large-Systems.html}
In our implementation we borrow kmp's overall @code{PROCESS-OPTIONS}
and concept to deal with creating component trees
from @code{defsystem} surface syntax.
[ this is not true right now, though it used to be and
probably will be again soon ]
@c -------------------
@node Concept Index, Function and Class Index, Inspiration, Top
@unnumbered Concept Index
@printindex cp
@node Function and Class Index, Variable Index, Concept Index, Top
@unnumbered Function and Class Index
@printindex fn
@node Variable Index, , Function and Class Index, Top
@unnumbered Variable Index
@printindex vr
@bye