Newer
Older
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<title>ASDF - Another System Definition Facility</title>
<link type='text/css' href='style.css' rel='stylesheet' />
<meta name="author" content="the ASDF group"/>
</head>
<body>
<div class="header">
<span class="logo">
<a href="http://common-lisp.net/project/asdf/" title="ASDF Homepage">
<img src="lisp-logo120x80.png" title="ASDF homepage" width="100" alt="Lisp Lizzard" />
</a>
</span>
<h2>ASDF</h2><h4>Another System Definition Facility</h4>
</div>
<div class="system-links">
<ul>
<li><a href="#what_it_is">What it is</a></li>
<li><a href="#what_it_is_not">What it is not</a></li>
<li><a href="#implementations">Supported Implementations</a></li>
Francois-Rene Rideau
committed
<li><a href="#examples">Examples</a></li>
<li><a href="#documentation">Documentation</a></li>
<li><a href="#downloads">Getting it</a></li>
<li><a href="#extensions">Extensions</a></li>
<li><a href="#bugs">Reporting Bugs</a></li>
<li><a href="#mailing-lists">Mailing Lists</a></li>
<li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=log"
>Changelog</a></li>
</ul>
</div>
<div class="contents">
Francois-Rene Rideau
committed
<a id="ASDF 3"></a>
<h3>ASDF 3</h3>
<p>ASDF 3, pre-released as 2.28 on February 1st 2013,
Francois-Rene Rideau
committed
is the current successor to Daniel Barlow's ASDF.
It was rewritten for improved portability, robustness, usability,
Francois-Rene Rideau
committed
extensibility, configurability, internal consistency,
and the ability to create standalone executables.
<a id="what_it_is"></a>
<h3>What it is</h3>
Francois-Rene Rideau
committed
<p>ASDF 3 contains two parts: <tt>asdf/defsystem</tt> and <tt>asdf/driver</tt>.
Francois-Rene Rideau
committed
</p>
Francois-Rene Rideau
committed
<p><tt>asdf/defsystem</tt>,
is a tool to describe how Lisp source code is organized in systems,
and how to build a system in term of actions that depend on previous actions.
</p>
<p>It is roughly what Common Lisp hackers use to build software
Francois-Rene Rideau
committed
where C hackers might use GNU <tt>Make</tt>.
</p>
<p>ASDF stands for <em>A</em>nother <em>S</em>ystem <em>D</em>efinition <em>F</em>acility,
Francois-Rene Rideau
committed
in the continuity of the Lisp <tt>DEFSYSTEM</tt> of yore.
</p>
Francois-Rene Rideau
committed
<p><tt>asdf/driver</tt> is a Common Lisp portability library and runtime support system
Francois-Rene Rideau
committed
that helps you write Common Lisp software in a portable way.
</p>
<p>In addition to many general-purpose Lisp utilities,
it notably provides portable abstractions to
gloss over implementation quirks, support hot-upgrade of code,
manipulate pathnames, create programs, use command-line arguments,
access the environment, use the filesystem,
call other programs and parse their output,
compile Lisp code, muffle conditions, or configure Lisp software.
</p>
<a id="what_it_is_not"></a>
<h3>What it is not</h3>
Francois-Rene Rideau
committed
<p>ASDF will <em>not</em> download missing software components for you.
Francois-Rene Rideau
committed
For that, you want <a href="http://quicklisp.org/"><tt>Quicklisp</tt></a>,
that builds upon ASDF, and is great for pulling and installing
tarballs of packages you may depend upon;
Francois-Rene Rideau
committed
we also recommend <a href="http://common-lisp.net/project/clbuild/"><tt>clbuild</tt></a>,
that now builds upon Quicklisp, as a great tool for pulling from version control
packages you need to modify or want to contribute to.
Francois-Rene Rideau
committed
We recommend you should <em>not</em> use <tt>asdf-install</tt> anymore,
Francois-Rene Rideau
committed
as it is an older similar piece of software that is both unmaintained and obsolete.
</p><p>
If you're unsatisfied with ASDF, other actively maintained build systems for Common-Lisp
that may or may not satisfy you include:
François-René Rideau's
Francois-Rene Rideau
committed
<a href="http://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a>
Francois-Rene Rideau
committed
(trying to build object and image files deterministically and in parallel),
or its polar opposite,
Drew McDermott's
Francois-Rene Rideau
committed
<a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a>
Francois-Rene Rideau
committed
(trying to maintain coherence of the current Lisp image at a fine grain),
Francois-Rene Rideau
committed
<a href="http://lisp.ystok.ru/asdlite/"><tt>ASDlite</tt></a>
(a somewhat improved incompatible variant of ASDF 1, less featureful than ASDF 3),
Francois-Rene Rideau
committed
or Alastair Bridgewater's interesting <tt>quick-build</tt> (unreleased, similar to <tt>faslpath</tt> below).
Francois-Rene Rideau
committed
Older systems that are not maintained anymore include
Francois-Rene Rideau
committed
Mark Kantrowitz's <a href="http://www.cliki.net/mk-defsystem"><tt>mk-defsystem</tt></a>
(free software successor of the old proprietary DEFSYSTEM's and predecessor of ASDF, obsolete),
Francois-Rene Rideau
committed
Sean Ross's <a href="http://sean-ross.blogspot.com/search/label/mudballs"><tt>mudballs</tt></a>
(an attempt at making things cleaner than in ASDF, aborted),
Francois-Rene Rideau
committed
Peter Etter's <a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a>
(a much simpler system establishing a mapping between packages and files)
Francois-Rene Rideau
committed
Alexander Kahl's <a href="http://www.cliki.net/evol"><tt>evol</tt></a>
(a reimplementation of the GNU autotools stack in Lisp, abandoned),
Francois-Rene Rideau
committed
and probably more.
However, none of these systems seems to ever have had the traction of ASDF.
<a id="implementations"></a>
<h3>Supported Implementations</h3>
Francois-Rene Rideau
committed
<p>ASDF 3 now supports all CL implementations
that seem to have any current user base, and then some.
</p><p>
Francois-Rene Rideau
committed
Most implementations provide ASDF as a module,
Francois-Rene Rideau
committed
and you can simply <tt>(require "asdf")</tt>.
(All of them but CLISP also accept
<tt>:asdf</tt>, <tt>"ASDF"</tt> or <tt>'asdf</tt> as an argument.)
Francois-Rene Rideau
committed
All of these implementations provide at least ASDF 2,
and a few of them aready provide ASDF 3 (<tt>allegro</tt>, <tt>ccl</tt>, <tt>cmucl</tt>, <tt>ecl</tt>).
Hopefully soon all will follow suit;
Francois-Rene Rideau
committed
but in the meantime, you can download ASDF 3,
and use <tt>(asdf:load-system :asdf)</tt>
from a properly configured ASDF 2 to upgrade to the latest,
Francois-Rene Rideau
committed
which you should do before you use ASDF for anything else.
</p><p>
A few implementations don't provide ASDF yet,
but have announced they will in their next release.
As for remaining implementations,
they are obsolete and/or mostly unmaintained;
Francois-Rene Rideau
committed
still ASDF 3 supports them if you load it manually,
though there might never be a next release
to provide it through <tt>require</tt>.
</p>
<table>
<tr><th></th>
<th align="left">Provide "asdf"</th>
<th align="left">Will provide it</th>
<th align="left">Obsolete</th></tr>
<tr><th align="left">Free</th>
Francois-Rene Rideau
committed
<td align="left"><tt>abcl ccl clisp cmucl ecl mkcl sbcl xcl</tt></td>
<td> </td>
Francois-Rene Rideau
committed
<td align="left"><tt>gcl mcl</tt></td></tr>
<tr><th align="left">Proprietary</th>
Francois-Rene Rideau
committed
<td align="left"><tt>allegro lispworks</tt></td>
<td align="left"><tt>scl</tt></td>
<td align="left"><tt>cormanlisp genera</tt></td></tr>
</table>
<!-- Note to self:
The maintainers of the following implementations follow asdf-announce:
allegro Gary King <gwking@franz.com>
clisp (sds)
ecl (juanjo)
The maintainers of the following implementations require direct notification:
abcl ccl cmucl gcl lispworks sbcl mkcl scl xcl
Armed Bear <armedbear-devel@common-lisp.net>,
openmcl-devel@clozure.com,
cmucl-imp@cons.org,
gcl-devel@gnu.org,
lisp-support@lispworks.com,
SBCL Devel-list <sbcl-devel@lists.sourceforge.net>,
Jean-Claude Beaudoin <jean.claude.beaudoin@gmail.com>,
Douglas Crosher <dtc3@scieneer.com>,
Peter Graves <gnooth@gmail.com>
Francois-Rene Rideau
committed
-->
<p>
If there is an old or new implementation that we are missing,
Francois-Rene Rideau
committed
it shouldn't be hard to adapt ASDF to support it.
Ask us!
</p>
Francois-Rene Rideau
committed
<a id="examples"></a>
<h3>Examples</h3>
<p>Download any of the many packages available through
<a href="http://quicklisp.org/">Quicklisp</a>
to see as many examples.</p>
<a id="documentation"></a>
<h3>Documentation</h3>
<p>You can read our manual:</p>
<ul>
<li><a href="asdf.html">as one HTML file</a></li>
<li><a href="asdf/">split into one HTML file per section</a></li>
<li><a href="asdf.pdf">as a PDF document</a></li>
<li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=doc/asdf.texinfo">as texinfo source</a></li>
</ul>
Francois-Rene Rideau
committed
<p>Regarding the internal design of ASDF in general,
and the work we did on ASDF 2,
see the last draft version of our paper for
<a href="http://www.international-lisp-conference.org/2010/index">ILC 2010</a>,
<cite><a href="ilc2010draft.pdf"
>Evolving ASDF: More Cooperation, Less Coordination</a></cite></p>
<p>Finally, while the manual covers all the basics,
some advanced or new features remain underdocumented.
Please contact our mailing-list (see below)
for any issue that isn't well-documented enough.
</p>
Francois-Rene Rideau
committed
<p>Until we write more documentation on the further innovations of ASDF 3,
the documentation strings, the source code, the changelog and the git log
are unfortunately your best chances for discovering the available functionality.
</p>
Francois-Rene Rideau
committed
<a id="downloads"></a>
<h3>Getting it</h3>
<p>Though they may lag behind the version here, ASDF comes bundled with most Lisps.
To get the greatest and latest, you can:
</p>
<ul>
<li>download just the latest <em>release</em> source for
<!--<a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob_plain;tag=RELEASE;f=asdf.lisp">asdf.lisp</a>,-->
<a href="http://common-lisp.net/project/asdf/asdf.lisp">asdf.lisp</a>;
</li>
<li>download the latest <em>release</em>
<!--<a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;tag=RELEASE;a=snapshot;sf=tgz">tarball</a>,-->
<a href="http://common-lisp.net/project/asdf/asdf.tar.gz">tarball</a>
to get all bells and whistles;
</li>
<li>pull the latest <em>development</em> tree from our git repository
<pre>git clone git://common-lisp.net/projects/asdf/asdf.git</pre>
(note that our "master" branch is for current development;
Francois-Rene Rideau
committed
get our "release" branch for the latest stable release.
Run <tt>make</tt> to create <tt>build/asdf.lisp</tt>);
</li>
<li>browse the latest <em>development</em> tree from our git repository:
<a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git">gitweb</a>
</li>
<li>download the tarball of a past release:
<a href="http://common-lisp.net/project/asdf/archives/">archives</a>
</li></ul>
<a id="extensions"></a>
<h3>Extensions</h3>
<p>Known extensions to ASDF include:</p>
<ul>
<li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-contrib.git"
Francois-Rene Rideau
committed
><tt>asdf-contrib</tt></a>,
a collection of most of the below.</li>
<li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git"
Francois-Rene Rideau
committed
><tt>asdf-encodings</tt></a>,
to compile Lisp source files with character encodings other than UTF-8.</li>
<li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-finalizers.git"
Francois-Rene Rideau
committed
><tt>asdf-finalizers</tt></a>,
to allow macros to include code to be evaluated
at the end of a file being compiled.</li>
<li><a href="http://common-lisp.net/gitweb?p=projects/xcvb/asdf-dependency-grovel.git"
Francois-Rene Rideau
committed
><tt>asdf-dependency-grovel</tt></a>,
to compute the actual dependencies in a big ASDF system.</li>
<li><a href="http://common-lisp.net/project/qitab/"
Francois-Rene Rideau
committed
><tt>poiu</tt></a>,
to compile a system in parallel.</li>
<li><a href="http://common-lisp.net/project/asdf-system-connections/"
Francois-Rene Rideau
committed
><tt>asdf-system-connections</tt></a>,
lets you specify systems that are automatically loaded when
two other systems are loaded, to connect them.</li>
<li><a href="http://www.lrde.epita.fr/~didier/software/lisp/misc.php#asdf-flv"
Francois-Rene Rideau
committed
><tt>asdf-flv</tt></a>,
to bind file-local variables around the compilation of some files.</li>
Francois-Rene Rideau
committed
</ul>
<p>Former extensions, now superseded, include:</p>
<ul>
Francois-Rene Rideau
committed
<li><tt>asdf-binary-locations</tt> allowed one to redirect where ASDF creates its output files,
Francois-Rene Rideau
committed
so they don't clash between implementations and don't pollute source directories.
Francois-Rene Rideau
committed
It is superseded by <tt>asdf/defsystem</tt> builtin <tt>asdf-output-translations</tt> mechanism;
Francois-Rene Rideau
committed
a limited compatibility mode is available to easily convert
your former ABL configuration into an AOT configuration.
Francois-Rene Rideau
committed
<tt>common-lisp-controller</tt> and <tt>cl-launch</tt> used to provide similar mechanisms,
and have also been superseded by <tt>asdf-output-translations</tt>.
Francois-Rene Rideau
committed
</li>
Francois-Rene Rideau
committed
<li><tt>asdf-bundle</tt>, née <tt>asdf-ecl</tt>,
allowed you to create a single-file bundle out of a system,
Francois-Rene Rideau
committed
for easier delivery.
Francois-Rene Rideau
committed
It is now a builtin part of <tt>asdf/defsystem</tt>,
and allows to deliver a single FASL for a system,
or (on supported implementations), a standalone executable program.
Francois-Rene Rideau
committed
</li>
Francois-Rene Rideau
committed
<li><tt>asdf-utils</tt> was a collection of utilities that originated with ASDF.
It is now superseded by <tt>asdf/driver</tt>, which is part of ASDF,
and exports its functionality in its own package <tt>asdf/driver</tt>.
Francois-Rene Rideau
committed
</li>
Francois-Rene Rideau
committed
<li><tt>asdf-condition-control</tt>, initially part of XCVB's <tt>xcvb-driver</tt>,
Francois-Rene Rideau
committed
allowed you to muffle uninteresting conditions during compilation.
Francois-Rene Rideau
committed
Is now superseded by equivalent functionality in <tt>asdf/driver</tt>.
Francois-Rene Rideau
committed
</li>
</ul>
<h3>Contributing</h3>
<p>Join our mailing list, check the code out from git,
send questions, ideas and patches!
</p>
<a id="bugs">
<h3>Reporting Bugs</h3>
<p>To report bugs, you can use our
<a href="https://launchpad.net/asdf/">launchpad project</a>.
If you're unsure about the bug or want to discuss how to fix it,
you can send email to the project mailing-list below.
</p>
<a id="mailing-lists"></a>
<h3>Mailing Lists</h3>
<ul>
<li><a href="http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel">asdf-devel</a>:
A list for questions, suggestions, bug reports, patches, and so on.
It's for everyone and everything. Please join the conversation!
</li>
<li><a href="http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-announce">asdf-announce</a>:
A low-volume mailing-list for announcements only, mostly regarding new releases.
Posting is restricted to project administrators and to important notices.
Please subscribe to it if you're a Lisp implementation or distribution vendor,
who needs to know when to upgrade the ASDF you distribute,
but are otherwise not interested in day to day design and development.
</li></ul>
<h3>Contributing</h3>
<p>Join our mailing list, check the code out from git,
send questions, ideas and patches!
</p>
<a id="news"></a>
<h3>What is happening</h3>
<dl>
Francois-Rene Rideau
committed
<dd>
Francois-Rene Rideau
committed
ASDF 3 now includes both the traditional <tt>asdf/defsystem</tt>
and a formalized portability library <tt>asdf/driver</tt>.
<tt>asdf/defsystem</tt> is a backward-compatible reimplementation of ASDF
Francois-Rene Rideau
committed
with correct timestamp propagation based on a consistent dependency model,
Francois-Rene Rideau
committed
and featuring support for bundle output, deferred warnings check, and more.
<tt>asdf/driver</tt> provides many abstractions to write portable Common Lisp programs.
Francois-Rene Rideau
committed
</dd>
<dt>In April 2012</dt>
<dd>
ASDF 2.21 now controls the character encoding used by Lisp source files.
You can specify different encodings in your defsystem,
e.g. <kbd>:encoding :latin1</kbd>,
if you <kbd>:defsystem-depends-on (:asdf-encodings)</kbd>.
While the default will remain to load and compile file
with the <kbd>:default</kbd> external-format,
we encourage all library authors to adopt
the <i>de facto</i> standard, UTF-8,
for all their source files (.lisp and .asd).
Our intent is to bless and enforce this standard encoding
on all these files by default in a not-to-faraway future.
<dd>François-René Rideau is de facto maintainer,
with notable contributions from Robert P. Goldman, but also
Francois-Rene Rideau
committed
Juanjo Garcia-Ripoll and James Anderson.
ASDF 2 released
with many clean-ups, better configurability, some new features,
and updated documentation.
</dd>
<dt>May 2006 to November 2009</dt>
<dd>Gary King is de facto maintainer,
with notable contributions from
Robert P. Goldman, Nikodemus Siivola, Christophe Rhodes, Daniel Herring.
Many small features and bug fixes,
moving to using git and common-lisp.net.
</dd>
<dt>May 2004 to April 2006</dt>
<dd>Christophe Rhodes is de facto maintainer,
with notable contributions from
Nikodemus Siivola, Peter Van Eynde, Edi Weitz, Kevin Rosenberg.
The system made more robust, a few more features.
<dt>August 2001 to May 2004</dt>
<dd>Developed by Daniel Barlow, with notable contributions from
Christophe Rhodes, Kevin Rosenberg, Edi Weitz, Rahul Jain.
Francois-Rene Rideau
committed
Last version: 1.85.
<dt>August 2001</dt>
<dd>Created by Daniel Barlow</dd>
<div id="footer">
<a class="nav" href="http://validator.w3.org/check/referer" title="xhtml1.1"><img src="http://common-lisp.net/project/cl-containers/shared/buttons/xhtml.gif" width="80" height="15" title="valid xhtml button" alt="valid xhtml" /></a>
<a class="nav" href="http://www.catb.org/hacker-emblem/" title="hacker"> <img src="http://common-lisp.net/project/cl-containers/shared/buttons/hacker.png" width="80" height="15" title="hacker emblem" alt="hacker button" /></a>
<a class="nav" href="http://www.lisp.org/" title="Association of Lisp Users"> <img src="http://common-lisp.net/project/cl-containers/shared/buttons/lambda-lisp.png" width="80" height="15" title="ALU emblem" alt="ALU button" /></a>
<a class="nav" href="http://common-lisp.net/" title="Common-Lisp.net"> <img src="http://common-lisp.net/project/cl-containers/shared/buttons/lisp-lizard.png" width="80" height="15" title="Common-Lisp.net" alt="Common-Lisp.net button" /></a>
<p><span class="copyright"Copyright © 2001-2013 Daniel Barlow and contributors</span></p>
<p>ASDF has an <a href="http://www.opensource.org/licenses/mit-license.php">MIT style</a> license</p>
Francois-Rene Rideau
committed
<div id="timestamp">Last updated 2013-03-02</div>
</body>
</html>