index.html 21.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<!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>
17 18 19
    <div class="system-links">
      <ul>
        <li><a href="#what_it_is">What it is</a></li>
20 21
        <li><a href="#what_it_is_not">What it is not</a></li>
        <li><a href="#implementations">Supported Implementations</a></li>
22
        <li><a href="#examples">Examples</a></li>
23 24
        <li><a href="#documentation">Documentation</a></li>
        <li><a href="#downloads">Getting it</a></li>
25
        <li><a href="#extensions">Extensions</a></li>
26
        <li><a href="#bugs">Reporting Bugs</a></li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
27
        <li><a href="#mailing-lists">Mailing Lists</a></li>
28 29 30 31
        <li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=log"
               >Changelog</a></li>
      </ul>
    </div>
32
    <div class="contents">
33 34
        <a id="ASDF 3"></a>
        <h3>ASDF 3</h3>
35 36
        <p>ASDF 3, pre-released as 2.28 on February 1st 2013, and
          released as 3.0.0 on May 15th 2013,
37
          is the current successor to Daniel Barlow's ASDF.
38
          It was rewritten for improved portability, robustness, usability,
39
          extensibility, configurability, internal consistency,
40
          and the ability to create standalone executables.
41
        </p>
42 43
        <a id="what_it_is"></a>
        <h3>What it is</h3>
44
        <p>ASDF 3 contains two parts: <tt>asdf/defsystem</tt> and <tt>asdf/driver</tt>.
45
        </p>
46
        <p><tt>asdf/defsystem</tt>,
47 48
          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.
49
        </p>
50
        <p>It is roughly what Common Lisp hackers use to build software
51
          where C hackers might use GNU <tt>Make</tt>.
52 53
        </p>
        <p>ASDF stands for <em>A</em>nother <em>S</em>ystem <em>D</em>efinition <em>F</em>acility,
54
          in the continuity of the Lisp <tt>DEFSYSTEM</tt> of yore.
55
        </p>
56 57 58 59
        <p><tt>asdf/driver</tt>,
          also known as <tt>uiop</tt>,
          the Utilities for Implementation- and OS- Portability,
          is a Common Lisp portability library and runtime support system
60 61 62 63 64 65 66 67 68 69
          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>
70 71
        <a id="what_it_is_not"></a>
        <h3>What it is not</h3>
72
        <p>ASDF will <em>not</em> download missing software components for you.
73
          For that, you want <a href="http://quicklisp.org/"><tt>Quicklisp</tt></a>,
74 75
          that builds upon ASDF, and is great for pulling and installing
          tarballs of packages you may depend upon;
76
          we also recommend <a href="http://common-lisp.net/project/clbuild/"><tt>clbuild</tt></a>,
77 78
          that now builds upon Quicklisp, as a great tool for pulling from version control
          packages you need to modify or want to contribute to.
79
          We recommend you should <em>not</em> use <tt>asdf-install</tt> anymore,
80 81
          as it is an older similar piece of software that is both unmaintained and obsolete.
        </p><p>
82 83
          If you're unsatisfied with ASDF,
          other somewhat actively maintained build systems for Common-Lisp
84 85
          that may or may not satisfy you include:
          Fran&ccedil;ois-Ren&eacute; Rideau's
86
          <a href="http://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a>
87 88
          (trying to build object and image files deterministically and in parallel,
          has fallen behind ASDF since 2012),
89 90
          or its polar opposite,
          Drew McDermott's
91
          <a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a>
92
          (trying to maintain coherence of the current Lisp image at a fine grain),
93
          Dmitriy Ivanov's
94
          <a href="http://lisp.ystok.ru/asdlite/"><tt>ASDlite</tt></a>
95
          (a somewhat improved incompatible variant of ASDF 1, less featureful than ASDF 3),
96 97 98
          or Alastair Bridgewater's one-package-per-file
          <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a>
          (similar to <tt>faslpath</tt> below).
99
          Older systems that are not maintained anymore include
100 101 102 103 104 105
          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),
          Sean Ross's
          <a href="http://sean-ross.blogspot.com/search/label/mudballs"><tt>mudballs</tt></a>
106
          (an attempt at making things cleaner than in ASDF, aborted),
107 108
          Peter Etter's
          <a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a>
109
          (a much simpler system establishing a mapping between packages and files)
110 111
          Alexander Kahl's
          <a href="http://www.cliki.net/evol"><tt>evol</tt></a>
112
          (a reimplementation of the GNU autotools stack in Lisp, abandoned),
113 114
          and probably more.
          However, none of these systems seems to ever have had the traction of ASDF.
115
        </p>
116
        <a id="implementations"></a>
117
        <h3>Supported Implementations</h3>
118
        <p>ASDF 3 now supports all CL implementations
119
          that seem to have any current user base, and then some.
120
        </p><p>
121
          Most implementations provide ASDF as a module,
122 123 124
          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.)
125
          All of these implementations provide at least ASDF 2,
126
          and a few of them aready provide ASDF 3
127
          (<tt>abcl</tt>, <tt>allegro</tt>, <tt>ccl</tt>, <tt>clisp</tt>, <tt>cmucl</tt>,
128
          <tt>ecl</tt>, <tt>sbcl</tt>).
129
          Hopefully soon all will follow suit;
130 131
          but in the meantime, you can download ASDF 3,
          and use <tt>(asdf:load-system :asdf)</tt>
132
          to upgrade to the latest ASDF from a properly configured ASDF 2,
133
          which you should do before you use ASDF for anything else.
134 135 136 137
        </p><p>
          A few implementations don't provide ASDF yet,
          but have announced they will in their next release.
          As for remaining implementations,
138
          they are obsolete and/or mostly unmaintained;
139
          still ASDF 3 supports them if you load it manually,
140 141 142 143 144
          though there might never be a next release
          to provide it through <tt>require</tt>.
        </p>
        <table>
          <tr><th></th>
145 146
            <th align="left">Provide "asdf" 3</th>
            <th align="left">Provide "asdf" 2</th>
147 148 149
            <th align="left">Will provide it</th>
            <th align="left">Obsolete</th></tr>
          <tr><th align="left">Free</th>
150 151
            <td align="left"><tt>abcl ccl clisp cmucl ecl sbcl</tt></td>
            <td align="left"><tt>mkcl xcl</tt></td>
152
            <td> </td>
153
            <td align="left"><tt>gcl mcl</tt></td></tr>
154
          <tr><th align="left">Proprietary</th>
155 156
            <td align="left"><tt>allegro</tt></td>
            <td align="left"><tt>lispworks</tt></td>
157 158
            <td align="left"><tt>scl</tt></td>
            <td align="left"><tt>cormanlisp genera</tt></td></tr>
159 160 161 162 163 164 165 166
        </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:
167
             abcl ccl cmucl gcl lispworks sbcl mkcl scl xcl
168 169 170 171 172 173
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>,
174
Jean-Claude Beaudoin <jean.claude.beaudoin@gmail.com>,
175 176
Douglas Crosher <dtc3@scieneer.com>,
Peter Graves <gnooth@gmail.com>
177
        -->
178 179
        <p>
          If there is an old or new implementation that we are missing,
180
          it shouldn't be hard to adapt ASDF to support it.
181
          Ask us!
182
        </p>
183

184 185 186 187 188 189
        <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>

190 191 192 193 194 195 196
        <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>
197
          <li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=doc/asdf.texinfo">as texinfo source</a></li>
198
        </ul>
199 200
        <p>Regarding the internal design of ASDF in general,
          and the work we did on ASDF 2,
201 202 203
          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"
204 205 206 207
                   >Evolving ASDF: More Cooperation, Less Coordination</a></cite>,
          or 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.
208 209 210 211 212
        <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>
213 214 215 216
        <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>
217

218
        <a id="downloads"></a>
219 220 221 222 223
        <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>
224
          <li>download just the latest <em>release</em> source for
225
            <!--<a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob_plain;tag=RELEASE;f=asdf.lisp">asdf.lisp</a>,-->
226
            <a href="http://common-lisp.net/project/asdf/asdf.lisp">asdf.lisp</a>;
227
          </li>
228
          <li>download the latest <em>release</em>
229 230
            <!--<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>
231
            to get all bells and whistles;
232
          </li>
233
          <li>pull the latest <em>development</em> tree from our git repository
234
            <pre>git clone git://common-lisp.net/projects/asdf/asdf.git</pre>
235
            (note that our "master" branch is for current development;
236 237
            get our "release" branch for the latest stable release.
            Run <tt>make</tt> to create <tt>build/asdf.lisp</tt>);
238 239 240 241 242 243
          </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>
244 245
        </li></ul>

246 247 248 249 250
        <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"
251
		 ><tt>asdf-contrib</tt></a>,
252 253
	    a collection of most of the below.</li>
	  <li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git"
254
		 ><tt>asdf-encodings</tt></a>,
255 256
	    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"
257
		 ><tt>asdf-finalizers</tt></a>,
258 259 260
	    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"
261
		 ><tt>asdf-dependency-grovel</tt></a>,
262 263
	    to compute the actual dependencies in a big ASDF system.</li>
	  <li><a href="http://common-lisp.net/project/qitab/"
264
		 ><tt>poiu</tt></a>,
265
	    to compile a system in parallel.</li>
266
	  <li><a href="http://common-lisp.net/project/asdf-system-connections/"
267
		 ><tt>asdf-system-connections</tt></a>,
268 269
	    lets you specify systems that are automatically loaded when
            two other systems are loaded, to connect them.</li>
270
	  <li><a href="http://www.lrde.epita.fr/~didier/software/lisp/misc.php#asdf-flv"
271
		 ><tt>asdf-flv</tt></a>,
272
	    to bind file-local variables around the compilation of some files.</li>
273 274 275
        </ul>
        <p>Former extensions, now superseded, include:</p>
        <ul>
276
	  <li><tt>asdf-binary-locations</tt> allowed one to redirect where ASDF creates its output files,
277
            so they don't clash between implementations and don't pollute source directories.
278
            It is superseded by <tt>asdf/defsystem</tt> builtin <tt>asdf-output-translations</tt> mechanism;
279 280
            a limited compatibility mode is available to easily convert
            your former ABL configuration into an AOT configuration.
281 282
            <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>.
283
          </li>
284
	  <li><tt>asdf-bundle</tt>, n&eacute;e <tt>asdf-ecl</tt>,
285
            allowed you to create a single-file bundle out of a system,
286
            for easier delivery.
287
            It is now a builtin part of <tt>asdf/defsystem</tt>,
288 289
            and allows to deliver a single FASL for a system,
            or (on supported implementations), a standalone executable program.
290
          </li>
291
	  <li><tt>asdf-utils</tt> was a collection of utilities that originated with ASDF.
292 293 294 295
            It is now superseded by <tt>asdf/driver</tt>, aka <tt>uiop</tt>,
            which is part of ASDF,
            and exports its functionality
            in its own package <tt>uiop</tt>.
296
          </li>
297
	  <li><tt>asdf-condition-control</tt>, initially part of XCVB's <tt>xcvb-driver</tt>,
298
            allowed you to muffle uninteresting conditions during compilation.
299
            Is now superseded by equivalent functionality in <tt>uiop</tt>.
300
          </li>
301 302 303 304 305 306 307
	</ul>

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

308 309
        <a id="bugs">
        <h3>Reporting Bugs</h3>
310
        <p>To report bugs, you can use our
311 312 313 314 315
          <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
316 317
        <a id="mailing-lists"></a>
        <h3>Mailing Lists</h3>
318
        <ul>
Robert P. Goldman's avatar
Robert P. Goldman committed
319
          <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
320 321 322
            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
323
          <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
324 325 326 327 328
            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.
329
        </li></ul>
Robert P. Goldman's avatar
Robert P. Goldman committed
330 331 332
        <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>
333 334 335 336 337 338 339 340 341

        <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>
Robert P. Goldman's avatar
Robert P. Goldman committed
342
          <dt>Summer 2013</dt>
343 344
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau has resigned as maintainer
            after releasing ASDF 3.0.1.
Robert P. Goldman's avatar
Robert P. Goldman committed
345 346
        Robert P. Goldman is interim maintainer until someone more gifted,
        charming, dedicated, and better-looking can be secured to fill the role.</dd>
347
          <dt>In February 2013</dt>
348
          <dd>
349 350 351
            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
352
            with correct timestamp propagation based on a consistent dependency model,
353 354
            and featuring support for bundle output, deferred warnings check, and more.
            <tt>asdf/driver</tt> provides many abstractions to write portable Common Lisp programs.
355
          </dd>
356 357
          <dt>In April 2012</dt>
          <dd>
358 359 360
            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>,
361
            if you <kbd>:defsystem-depends-on (:asdf-encodings)</kbd>.
362 363 364 365 366 367 368
            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.
369
          </dd>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
370
          <dt>Since December 2009</dt>
371
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau is de facto maintainer,
372
            with notable contributions from Robert P. Goldman, but also
373
            Juanjo Garcia-Ripoll and James Anderson.
374
            ASDF 2 released
375
            with many clean-ups, better configurability, some new features,
376 377 378 379 380
            and updated documentation.
          </dd>
          <dt>May 2006 to November 2009</dt>
          <dd>Gary King is de facto maintainer,
            with notable contributions from
381
            Robert P. Goldman, Nikodemus Siivola, Christophe Rhodes, Daniel Herring.
382
            Many small features and bug fixes,
383
            making the project more maintainable,
384
            moving to using git and common-lisp.net.
385
            Last version: 1.369.
386 387 388 389 390
          </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.
391
            The system made more robust, a few more features.
392
            Last version: 1.97.
393
          <dt>August 2001 to May 2004</dt>
394
          <dd>Developed by Daniel Barlow, with notable contributions from
395
            Christophe Rhodes, Kevin Rosenberg, Edi Weitz, Rahul Jain.
396
            Last version: 1.85.
397 398
          <dt>August 2001</dt>
          <dd>Created by Daniel Barlow</dd>
399 400
      </dl>
          </div>
401 402 403 404 405
      <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>
406
        <p><span class="copyright"Copyright &copy; 2001-2013 Daniel Barlow and contributors</span></p>
407
        <p>ASDF has an <a href="http://www.opensource.org/licenses/mit-license.php">MIT style</a> license</p>
408
        <div id="timestamp">Last updated 2013-03-03</div>
409
    </div>
410 411
  </body>
</html>