Newer
Older
Note that in the past there was an add-on to ASDF called
@code{ASDF-binary-locations}, developed by Gary King.
That add-on has been merged into ASDF proper,
Francois-Rene Rideau
committed
then superseded by the @code{asdf-output-translations} facility.
Note that use of @code{asdf-output-translations}
can interfere with one aspect of your systems
--- if your system uses @code{*load-truename*} to find files
(e.g., if you have some data files stored with your program),
then the relocation that this ASDF customization performs
is likely to interfere.
Use @code{asdf:system-relative-pathname} to locate a file
in the source directory of some system, and
use @code{asdf:apply-output-translations} to locate a file
whose pathname has been translated by the facility.
@node How can I wholly disable the compiler output cache?, , How can I customize where fasl files are stored?, Issues with configuring ASDF
@subsection ``How can I wholly disable the compiler output cache?''
To permanently disable the compiler output cache
for all future runs of ASDF, you can:
@example
mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/
echo ':disable-cache' > ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
@end example
This assumes that you didn't otherwise configure the ASDF files
(if you did, edit them again),
and don't somehow override the configuration at runtime
with a shell variable (see below) or some other runtime command
(e.g. some call to @code{asdf:initialize-output-translations}).
To disable the compiler output cache in Lisp processes
Francois-Rene Rideau
committed
run by your current shell, try (assuming @code{bash} or @code{zsh})
(on Unix and cygwin only):
@example
export ASDF_OUTPUT_TRANSLATIONS=/:
@end example
To disable the compiler output cache just in the current Lisp process,
use (after loading ASDF but before using it):
@example
Francois-Rene Rideau
committed
(asdf:disable-output-translations)
@node Issues with using and extending ASDF to define systems, ASDF development FAQs, Issues with configuring ASDF, FAQ
@section Issues with using and extending ASDF to define systems
@menu
* How can I cater for unit-testing in my system?::
* How can I cater for documentation generation in my system?::
* How can I maintain non-Lisp (e.g. C) source files?::
* I want to put my module's files at the top level. How do I do this?::
* How do I create a system definition where all the source files have a .cl extension?::
* How do I mark a source file to be loaded only and not compiled?::
@end menu
@node How can I cater for unit-testing in my system?, How can I cater for documentation generation in my system?, Issues with using and extending ASDF to define systems, Issues with using and extending ASDF to define systems
@subsection ``How can I cater for unit-testing in my system?''
ASDF provides a predefined test operation, @code{test-op}.
@xref{Predefined operations of ASDF, test-op}.
The test operation, however, is largely left to the system definer to specify.
@code{test-op} has been
a topic of considerable discussion on the
@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list},
@url{https://launchpad.net/asdf,launchpad bug-tracker}.
We provide some guidelines in the discussion of @code{test-op}.
@c cut the following because it's discussed in the discussion of test-op.
@c Here are some guidelines:
@c @itemize
@c @item
@c For a given system, @var{foo}, you will want to define a corresponding
@c test system, such as @var{foo-test}. The reason that you will want this
@c separate system is that ASDF does not out of the box supply components
@c that are conditionally loaded. So if you want to have source files
@c (with the test definitions) that will not be loaded except when testing,
@c they should be put elsewhere.
@c @item
@c The @var{foo-test} system can be defined in an asd file of its own or
@c together with @var{foo}. An aesthetic preference against cluttering up
@c the filesystem with extra asd files should be balanced against the
@c question of whether one might want to directly load @var{foo-test}.
@c Typically one would not want to do this except in early stages of
@c debugging.
@c @item
@c Record that testing is implemented by @var{foo-test}. For example:
@c @example
@c (defsystem @var{foo}
@c :in-order-to ((test-op (test-op @var{foo-test})))
@c ....)
@c (defsystem @var{foo-test}
@c :depends-on (@var{foo} @var{my-test-library} ...)
@c ....)
@c @end example
@c @end itemize
@c This procedure will allow you to support users who do not wish to
@c install your test framework.
@c One oddity of ASDF is that @code{operate} (@pxref{Operations,operate})
@c does not return a value. So in current versions of ASDF there is no
@c reliable programmatic means of determining whether or not a set of tests
@c has passed, or which tests have failed. The user must simply read the
@c console output. This limitation has been the subject of much
@c discussion.
@node How can I cater for documentation generation in my system?, How can I maintain non-Lisp (e.g. C) source files?, How can I cater for unit-testing in my system?, Issues with using and extending ASDF to define systems
@subsection ``How can I cater for documentation generation in my system?''
Francois-Rene Rideau
committed
Various ASDF extensions provide some kind of @code{doc-op} operation.
See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
@node How can I maintain non-Lisp (e.g. C) source files?, I want to put my module's files at the top level. How do I do this?, How can I cater for documentation generation in my system?, Issues with using and extending ASDF to define systems
@subsection ``How can I maintain non-Lisp (e.g. C) source files?''
@node I want to put my module's files at the top level. How do I do this?, How do I create a system definition where all the source files have a .cl extension?, How can I maintain non-Lisp (e.g. C) source files?, Issues with using and extending ASDF to define systems
@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).
@node How do I create a system definition where all the source files have a .cl extension?, How do I mark a source file to be loaded only and not compiled?, I want to put my module's files at the top level. How do I do this?, Issues with using and extending ASDF to define systems
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.
Francois-Rene Rideau
committed
Please upgrade to ASDF 3.
Francois-Rene Rideau
committed
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
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
@node How do I mark a source file to be loaded only and not compiled?, , How do I create a system definition where all the source files have a .cl extension?, Issues with using and extending ASDF to define systems
@subsection How do I mark a source file to be loaded only and not compiled?
There is no provision in ASDF for ensuring that
some components are always loaded as source, while others are always
compiled.
There is @code{load-source-op} (@pxref{Predefined operations of
ASDF,load-source-op}), but that is an operation to be applied to a
system as a whole, not to one or another specific source files.
While this idea often comes up in discussions,
it doesn't play well with either the linking model of ECL
or with various bundle operations.
In addition, the dependency model of ASDF would have to be modified incompatibly
to allow for such a trick.
@c If your code doesn't compile cleanly, fix it.
@c If compilation makes it slow, use @code{declaim} or @code{eval-when}
@c to adjust your compiler settings,
@c or eschew compilation by @code{eval}uating a quoted source form at load-time.
@node ASDF development FAQs, , Issues with using and extending ASDF to define systems, FAQ
@section ASDF development FAQs
@menu
* How do run the tests interactively in a REPL?::
@end menu
@node How do run the tests interactively in a REPL?, , ASDF development FAQs, ASDF development FAQs
@subsection How do run the tests interactively in a REPL?
This not-so-frequently asked question is primarily for ASDF developers,
but those who encounter an unexpected error in some test may be
interested, too.
Here's the procedure for experimenting with tests in a REPL:
@example
(load "script-support.lisp")
(in-package :asdf-test)
(compile-load-asdf) ; there are a number of other functions to load ASDF
;; experiment with test code from a .script file...
@end example
@comment FIXME: Add a FAQ about how to use a new system class...
Francois-Rene Rideau
committed
@node Ongoing Work, Bibliography, FAQ, Top
@unnumbered Ongoing Work
For an active list of things to be done,
see the @file{TODO} file in the source repository.
Francois-Rene Rideau
committed
Also, bugs that are now tracked on launchpad:
@url{https://launchpad.net/asdf}.
Francois-Rene Rideau
committed
@node Bibliography, Concept Index, Ongoing Work, Top
@unnumbered Bibliography
@item Francois-Rene Rideau:
``ASDF 3, or Why Lisp is Now an Acceptable Scripting Language'', 2014.
This article describes the innovations in ASDF 3 and 3.1,
as well as historical information on previous versions.
@url{http://fare.tunes.org/files/asdf3/asdf3-2014.html}
@url{http://github.com/fare/asdf3-2013}
Francois-Rene Rideau
committed
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
@item Zach Beane:
``Quicklisp'', 2011.
The Quicklisp blog and Xach's livejournal contain information on Quicklisp.
@url{http://blog.quicklisp.org/}
@url{http://xach.livejournal.com/}
@item Francois-Rene Rideau and Robert Goldman:
``Evolving ASDF: More Cooperation, Less Coordination'', 2010.
This article describes the main issues solved by ASDF 2.
@url{http://common-lisp.net/project/asdf/doc/ilc2010draft.pdf}
@url{http://www.common-lisp.org/gitweb?p=projects/asdf/ilc2010.git}
@item Francois-Rene Rideau and Spencer Brody:
``XCVB: an eXtensible Component Verifier and Builder for Common Lisp'', 2009.
This article describes XCVB, a proposed competitor for ASDF,
many ideas of which have been incorporated into ASDF 2 and 3,
though many other of which still haven't.
@url{http://common-lisp.net/projects/xcvb/}
@item Dan Barlow: ``ASDF Manual'', 2004
Older versions of this document from the days of ASDF 1;
they include ideas laid down by Dan Barlow,
and comparisons with older defsystems (@code{mk-defsystem})
and defsystem (@code{defsystem-4}, kmp's Memo 801).
@item Marco Antoniotti and Peter Van Eynde:
``@code{DEFSYSTEM}: A @code{make} for Common Lisp, A Thoughtful Re-Implementation of an Old Idea'', 2002.
The @file{defsystem-4} proposal available in the CLOCC repository.
@item Mark Kantrovitz: ``Defsystem: A Portable Make Facility for Common Lisp'', 1990.
The classic @file{mk-defsystem}, later variants of which
are available in the CLOCC repository as @code{defsystem-3.x}.
@item Richard Elliot Robbins:
``BUILD: A Tool for Maintaining Consistency in Modular Systems'', MIT AI TR 874, 1985.
@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AITR-874.pdf}
@item Kent M. Pitman (kmp): ``The Description of Large Systems'', MIT AI Memo 801, 1984.
Available in updated-for-CL form on the web at
@url{http://nhplace.com/kent/Papers/Large-Systems.html}
@item Dan Weinreb and David Moon:
``Lisp Machine Manual'', MIT, 1981.
The famous CHINE NUAL describes one of the earliest variants of DEFSYSTEM.
@url{https://bitsavers.trailing-edge.com/pdf/mit/cadr/chinual_4thEd_Jul81.pdf}
@item Drew McDermott: ``A Framework for Maintaining the Coherence of a
Running Lisp,'' International Lisp Conference, 2005, available in
pre-print form at @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf}.
Francois-Rene Rideau
committed
@node Concept Index, Function and Class Index, Bibliography, 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