Skip to content
Snippets Groups Projects
index.html 26.4 KiB
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"/>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  </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>
        <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>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
        <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>
        <p>ASDF 3 is the current successor to Daniel Barlow's ASDF.
          It was rewritten for improved portability, robustness, usability,
          extensibility, configurability, internal consistency,
          and the ability to deliver standalone executables.
          It was pre-released as 2.27 on February 1st 2013,
          released as 3.0.0 on May 15th 2013,
          and again as 3.1.2 on May 6th 2014.
        <a id="what_it_is"></a>
        <h3>What it is</h3>
        <p>ASDF stands for <em>A</em>nother <em>S</em>ystem <em>D</em>efinition <em>F</em>acility,
          in the continuity of the Lisp <tt>DEFSYSTEM</tt> of yore.
        <p>ASDF 3 contains two parts: <tt>asdf/defsystem</tt> and <tt>uiop</tt>.
        <dl>
          <dt><tt>asdf/defsystem</tt></dt>
          <dd>
            <p>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>
              Typical actions consist in compiling a Lisp source file (if not up to date)
              and loading the resulting compilation output (if not both loaded and up to date).
              And you must typically compile and load files that define packages, macros, variables,
              before you may compile and load other files that use them.
            </p>
            <p>It is roughly what Common Lisp hackers use to build and load software
              where C hackers might use GNU <tt>Make</tt> to build software and
              <tt>ld.so</tt> to load it.
            </p>
            <p><tt>asdf/defsystem</tt> is the part that people usually refer to as <tt>ASDF</tt>,
              with <tt>uiop</tt> being only a supporting library,
              that happens to be distributed at the same time, by necessity.
            </p>
          </dd>
          <dt><tt>uiop</tt></dt>
          <dd>
            <p>also known as <tt>asdf/driver</tt>,
              the Utilities for Implementation- and OS- Portability,
              is a Common Lisp portability library and runtime support system
              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.
              See its
              <a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=uiop/README;hb=HEAD;js=1">README</a>.
            </p>
            <p><tt>uiop</tt> is distributed as part of the <tt>ASDF</tt>,
              its source code is transcluded in the single-file <tt>asdf.lisp</tt> being distributed
              and the precompiled fasls provided by Lisp implementations.
              <tt>ASDF</tt> relies heavily on it for its portability layer and runtime support,
              particularly so as to handle pathnames and filesystem access.
              <tt>uiop</tt> is useful on its own and can also be compiled and distributed separately.
            </p>
          </dd>
        </dl>
        <a id="what_it_is_not"></a>
        <h3>What it is not</h3>
        <p>ASDF will <em>not</em> download missing software components for you.
          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;
          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.
          We recommend you should <em>not</em> use <tt>asdf-install</tt> anymore,
          as it is an older similar piece of software that is both unmaintained and obsolete.
        </p><p>
          ASDF is also not a tool to build or run Common Lisp software from the Unix command-line.
          For that, you want <a href="http://cliki.net/cl-launch">cl-launch</a>,
          or perhaps <a href="http://www.xach.com/lisp/buildapp/">buildapp</a>.
          beside helping with our
          <a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=TODO">TODO list</a>,
          you might be interested in other build systems for Common-Lisp:
          <ul>
            <li>Alastair Bridgewater's small and simple one-package-per-file
              <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a>
              (also reimplemented as the ASDF extension
              <a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-package-system.git"
                 ><tt>asdf-package-system</tt></a>; similar to <tt>faslpath</tt> below).
            </li>
            <li>Fran&ccedil;ois-Ren&eacute; Rideau's
              <a href="http://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a>
              (building object and image files deterministically and in parallel,
              but not actively maintained since 2012;
              thanks to its new build model, ASDF 3 could conceivably be modified
              to support these features).
            </li>
            <li>Drew McDermott's
              <a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a>
              (the polar opposite, trying to maintain coherence
              of the current Lisp image at a fine grain).
            </li>
            <li>Dmitriy Ivanov's
              <a href="http://lisp.ystok.ru/asdlite/"><tt>ASDlite</tt></a>
              (a somewhat improved incompatible variant of ASDF 1, less featureful than ASDF 3),
            </li>
            <li>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),
            </li>
            <li>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 2, aborted),
            </li>
            <li>Peter von Etter's
              <a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a>
              (a much simpler system establishing a mapping between packages and files,
              abandoned but see <tt>asdf-package-system</tt> and <tt>quick-build</tt> above).
            </li>
            <li>Alexander Kahl's
              <a href="http://www.cliki.net/evol"><tt>evol</tt></a>
              (a reimplementation in Lisp of the GNU autotools stack, abandoned),
            </li>
          </ul>
          There are probably more.
          However, none of these systems seems to ever have had the traction of ASDF,
          probably because none was technically superior enough (when at all)
          to compensate for the first mover advantage.
        </p>
        <h3>Supported Implementations</h3>
        <p>ASDF 3 now supports all CL implementations
          that seem to have any current user base, and then some.
          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.)
          Most of these implementations provide ASDF 3,
          a few only provide ASDF 2.
          Some 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;
          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>
            <th align="left">Provide ASDF 3</th>
            <th align="left">Provide ASDF 2</th>
            <th align="left">Will provide ASDF(?)</th>
            <th align="left">Obsolete</th></tr>
          <tr><th align="left">Free</th>
            <td align="left"><tt>abcl ccl clisp cmucl ecl mkcl sbcl</tt></td>
            <td align="left"><tt>xcl</tt></td>
          <tr><th align="left">Proprietary</th>
            <td align="left"><tt>lispworks mocl</tt></td>
            <td align="left"><tt>scl</tt></td>
            <td align="left"><tt>cormanlisp genera</tt></td></tr>
        <p>
          To deal with an implementation that doesn't yet provide ASDF 3,
          we provide <a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=bin/install-asdf-as-module">a script</a> that can install ASDF 3
          where your implementation goes looking for it
          when you <tt>require</tt> it.
          Alternatively, if the implementation provides ASDF 2 or an older ASDF 3,
          you can download, install and configure a more recent ASDF 3,
          and use <tt>(asdf:load-system :asdf)</tt> to upgrade it.
          Beware: when upgrading from ASDF 2, you should always do it
          immediately after the <tt>require</tt>,
          and before you use ASDF for anything else
          (ASDF 3 does that automatically).
        </p>
             asdf-announce may have been a casualty of some recent mailing-list reorganization. Check.
sds, maintainer of CLISP, used to listen to it.

             The maintainers of the following implementations require direct notification:
             abcl allegro ccl clisp cmucl ecl gcl lispworks mkcl sbcl scl xcl
Armed Bear <armedbear-devel@common-lisp.net>,
Allegro <bugs@franz.com>,
Clozure CL <openmcl-devel@clozure.com>,
GNU CLISP <clisp-list@lists.sourceforge.net> (sds)
CMU CL <cmucl-imp@cmucl.cons.org>,
ECL <ecls-list@lists.sourceforge.net>,
GCL <gcl-devel@gnu.org>,
LispWorks <lisp-support@lispworks.com>,
MKCL <jean.claude.beaudoin@gmail.com>,
SBCL <sbcl-devel@lists.sourceforge.net>,
Scieneer CL (Douglas Crosher) <dtc3@scieneer.com>,
XCL (Peter Graves) <gnooth@gmail.com>
        <p>
          If there is an old or new implementation that we are missing,
          it shouldn't be hard to adapt ASDF to support it.
        <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>
        <p>Regarding the internal design of ASDF in general,
          and the work we did on ASDF 3,
          see the extended version (26 pages) of our paper
          <cite><a href="http://fare.tunes.org/files/asdf3/asdf3-2014.html"
                   >ASDF 3, or Why Lisp is Now an Acceptable Scripting Language</a></cite>
          (<a href="http://fare.tunes.org/files/asdf3/asdf3-2014.pdf">PDF</a>,
          <a href="http://github.com/fare/asdf3-2013">git</a>).
          The shorter version (8 pages), submitted to
          <a href="http://www.european-lisp-symposium.org/">ELS 2014</a>,
          focuses on ASDF 3 and misses historical and technical information
          (<a href="http://fare.tunes.org/files/asdf3/asdf3-els2014.pdf">PDF</a>,
          <a href="http://fare.tunes.org/files/asdf3/asdf3-2014.html">HTML</a>).
          Regarding ASDF 3, see also the slides of the
          <a href="https://github.com/fare/asdf3-2013/blob/master/els-slides.org"
             >ASDF 3 tutorial</a> presented at ELS 2013,
          and for an introduction to the source code, this video:
          <a href="https://www.youtube.com/watch?v=Qqqbc31ZZ-U">ASDF 3.1 walkthrough</a>.
          For more details about our work 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>
          (<a href="http://common-lisp.net/gitweb?p=projects/asdf/ilc2010.git">git</a>).
        <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>
        <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>
        <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>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>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;
            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>
        <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"
	    a collection of most of the below.</li>
	  <li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git"
	    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"
	    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"
	    to compute the actual dependencies in a big ASDF system.</li>
	  <li><a href="http://common-lisp.net/project/qitab/"
	    to compile a system in parallel.</li>
	  <li><a href="http://common-lisp.net/project/asdf-system-connections/"
	    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"
	    to bind file-local variables around the compilation of some files.</li>
          <li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-package-system.git"
                 ><tt>asdf-package-system</tt></a>,
            to compile Lisp source files with one package per file
            that also determines dependencies, in the style of
            <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a> or
            <a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a>
            (this functionality is built into recent versions of ASDF 3.1 and later,
            but this package exists for backward compatibility with earlier versions of ASDF 3;
            search the manual for <tt>package-inferred-system</tt>).
        </ul>
        <p>Former extensions, now superseded, include:</p>
        <ul>
	  <li><tt>asdf-binary-locations</tt> allowed one to redirect where ASDF creates its output files,
            so they don't clash between implementations and don't pollute source directories.
            It is superseded by <tt>asdf/defsystem</tt>'s builtin
            <tt>asdf-output-translations</tt> mechanism;
            a limited compatibility mode is available to easily convert
            your former ABL configuration into an AOT configuration.
            <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>.
	  <li><tt>asdf-bundle</tt>, n&eacute;e <tt>asdf-ecl</tt>,
            allowed you to create a single-file bundle out of a system,
            and allows to deliver a single FASL for a system,
            or (on supported implementations), a standalone executable program,
            or an image containing part of your software precompiled.
	  <li><tt>asdf-utils</tt> was a collection of utilities that originated with ASDF.
            It is now superseded by <tt>uiop</tt>, aka <tt>asdf/driver</tt>,
            which is part of ASDF,
            and exports its functionality
            in its own package <tt>uiop</tt>.
	  <li><tt>asdf-condition-control</tt>, initially part of XCVB's <tt>xcvb-driver</tt>,
            allowed you to muffle uninteresting conditions during compilation.
            Is now superseded by equivalent functionality in <tt>uiop</tt>.
	</ul>

        <h3>Contributing</h3>
        <p>Join our mailing list, check the code out from git,
          send questions, ideas and patches!
        </p>

        <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>

Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
        <a id="mailing-lists"></a>
        <h3>Mailing Lists</h3>
Robert P. Goldman's avatar
Robert P. Goldman committed
          <li><b>asdf-devel</b><!-- <a href="http://lists.common-lisp.net/mailman/listinfo/asdf-devel">asdf-devel</a> -->:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
            A list for questions, suggestions, bug reports, patches, and so on.
	    It's for everyone and everything. Please join the conversation!
	  </li>
Robert P. Goldman's avatar
Robert P. Goldman committed
          <li><b>asdf-announce</b><!-- <a href="http://lists.common-lisp.net/mailman/listinfo/asdf-announce">asdf-announce</a> -->:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
            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.
Robert P. Goldman's avatar
Robert P. Goldman committed
        <p>To subscribe to these mailing lists, send an email to, e.g.,
        asdf-devel+subscribe at common-lisp.net.  For more information about
        mailing lists at common-lisp.net, see <a href="http://common-lisp.net/listinfo.html">here</a>.</p>

        <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>
          <dt>July 2013 to May 2014</dt>
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau has resigned as maintainer
            but remained an active developer.
            Robert P. Goldman is interim maintainer until someone more gifted,
            charming, dedicated, and better-looking can be secured to fill the role.
            ASDF 3.0.2 was released in July 2013, 3.0.3 in October 2013, and 3.1.2 in May 2014.
            In addition to significant improvements and bug fixes,
            notably better Windows support,
            ASDF 3.1.2 notably sports the <tt>package-inferred-system</tt> extension.
          </dd>
          <dt>November 2012 to June 2013</dt>
            Fran&ccedil;ois-Ren&eacute; Rideau completely rewrites ASDF
            and publishes ASDF 3, pre-released as 2.27 in February 2013,
            and released as 3.0.1 in May 2013.
            It now includes both the traditional <tt>asdf/defsystem</tt>
            and a formalized portability library <tt>uiop</tt> (n&eacute;e <tt>asdf/driver</tt>).
            <tt>asdf/defsystem</tt> is a backward-compatible reimplementation of ASDF
            with correct timestamp propagation based on a consistent dependency model,
            and featuring support for bundle output, deferred warnings check, and more.
            <tt>uiop</tt> provides many abstractions to write portable Common Lisp programs.
            Last version: 3.0.1.
          <dt>December 2009 to October 2012</dt>
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau is de facto maintainer,
            with notable contributions from Robert P. Goldman, but also
            ASDF 2.000 is released in May 2010
            with many clean-ups, better configurability, some new features,
            The ASDF 2 series culminates with ASDF 2.26 in October 2012,
            which in addition to many bug fixes and small features
            includes support for file encodings, around-compile and compile-check hooks.
            Last version: 2.26.
          </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,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
            making the project more maintainable,
            moving to using git and common-lisp.net.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
            Last version: 1.369.
          </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 slightly more robust, a few more features.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
            Last version: 1.97.
          </dd>
          <dd>Created then developed by Daniel Barlow, with notable contributions from
            Christophe Rhodes, Kevin Rosenberg, Edi Weitz, Rahul Jain.
          </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 &copy; 2001-2014 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>
        <div id="timestamp">Last updated 2014-05-09</div>