index.html 19 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
35
36
37
38
39
        <a id="ASDF 3"></a>
        <h3>ASDF 3</h3>
        <p>ASDF 3, released on January 31st 2013,
          is the current successor to Daniel Barlow's ASDF.
          It was improved for portability, robustness, usability,
          extensibility, configurability, internal consistency,
          the ability to create standalone executables.
40
        </p>
41
42
        <a id="what_it_is"></a>
        <h3>What it is</h3>
43
44
45
46
47
48
        <p>ASDF 3 contains two parts: ASDF/DEFSYSTEM and ASDF/DRIVER.
        </p>
        <p>ASDF/DEFSYSTEM,
          is a tool to describe how source code are organized,
          and how to build the system with
          what action depends on what previous actions.
49
        </p>
50
        <p>It is roughly what Common Lisp hackers use to build software
51
          where C hackers might use GNU Make.
52
53
54
55
        </p>
        <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 DEFSYSTEM of yore.
        </p>
56
57
58
59
60
61
62
63
64
65
66
        <p>ASDF/DRIVER 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.
        </p>
67
68
        <a id="what_it_is_not"></a>
        <h3>What it is not</h3>
69
        <p>ASDF will <em>not</em> download missing software components for you.
70
          For that, you want <a href="http://quicklisp.org/">Quicklisp</a>,
71
72
73
74
75
          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/">clbuild</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.
76
77
78
79
80
81
82
83
84
85
86
          We recommend you should <em>not</em> use ASDF-Install anymore,
          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&ccedil;ois-Ren&eacute; Rideau's
          <a href="http://common-lisp.net/project/xcvb/">XCVB</a>
          (trying to build object and image files deterministically and in parallel),
          or its polar opposite,
          Drew McDermott's
          <a href="http://cs-www.cs.yale.edu/homes/dvm/">YTools</a>
87
          (trying to maintain coherence of the current Lisp image at a fine grain),
88
          or the newcomer
89
90
          <a href="http://lisp.ystok.ru/asdlite/">ASDlite</a>
          (a somewhat improved incompatible variant of ASDF 1).
91
92
93
94
95
          Older systems that are not maintained anymore include
          Mark Kantrowitz's <a href="http://www.cliki.net/mk-defsystem">mk-defsystem</a>
          (free software successor of the old proprietary DEFSYSTEM's and predecessor of ASDF),
          Sean Ross's <a href="http://sean-ross.blogspot.com/search/label/mudballs">mudballs</a>
          (aborted attempt at making things cleaner than in ASDF),
96
          Peter Etter's <a href="http://www.cliki.net/faslpath">faslpath</a>
97
          (a much simpler system establishing a mapping between packages and files),
98
99
100
101
          Alexander Kahl's <a href="http://www.cliki.net/evol">evol</a>
          (a reimplementation of the GNU autotools stack in Lisp),
          and probably more.
          However, none of these systems seems to ever have had the traction of ASDF.
102
        </p>
103
        <a id="implementations"></a>
104
        <h3>Supported Implementations</h3>
105
        <p>ASDF 3 now supports all CL implementations
106
107
108
          that seem to have any current user base.
        </p><p>
          Most implementations provide ASDF 2 as a module,
109
110
111
          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.)
112
113
114
115
116
117
        </p><p>
          They will hopefully soon all provide ASDF 3,
          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,
          which you should before you use ASDF for anything else.
118
119
120
121
        </p><p>
          A few implementations don't provide ASDF yet,
          but have announced they will in their next release.
          As for remaining implementations,
122
          they are obsolete and/or mostly unmaintained;
123
          still ASDF 3 supports them if you load it manually,
124
125
126
127
128
129
130
131
132
          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>
133
            <td align="left">abcl ccl clisp cmucl ecl mkcl sbcl xcl</td>
134
135
136
            <td> </td>
            <td align="left">gcl mcl</td></tr>
          <tr><th align="left">Proprietary</th>
137
138
            <td align="left">allegro lispworks</td>
            <td align="left">scl</td>
139
140
141
142
143
144
145
146
147
            <td align="left">cormanlisp genera</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:
148
             abcl ccl cmucl gcl lispworks sbcl mkcl scl xcl
149
150
151
152
153
154
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>,
155
Jean-Claude Beaudoin <jean.claude.beaudoin@gmail.com>,
156
157
Douglas Crosher <dtc3@scieneer.com>,
Peter Graves <gnooth@gmail.com>
158
        -->
159
160
        <p>
          If there is an old or new implementation that we are missing,
161
          it shouldn't be hard to adapt ASDF to support it.
162
          Ask us!
163
        </p>
164

165
166
167
168
169
170
        <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>

171
172
173
174
175
176
177
        <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>
178
          <li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=doc/asdf.texinfo">as texinfo source</a></li>
179
        </ul>
180
181
        <p>Regarding the internal design of ASDF in general,
          and the work we did on ASDF 2,
182
183
184
185
          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>
186
187
188
189
190
        <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>
191
192
193
194
        <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>
195

196
        <a id="downloads"></a>
197
198
199
200
201
        <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>
202
          <li>download just the latest <em>release</em> source for
203
            <!--<a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob_plain;tag=RELEASE;f=asdf.lisp">asdf.lisp</a>,-->
204
            <a href="http://common-lisp.net/project/asdf/asdf.lisp">asdf.lisp</a>;
205
          </li>
206
          <li>download the latest <em>release</em>
207
208
            <!--<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>
209
            to get all bells and whistles;
210
          </li>
211
212
213
214
          <li>download just the latest <em>development</em> source from our git repository:
            <a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob_plain;f=asdf.lisp;hb=HEAD">asdf.lisp</a>
          </li>
          <li>pull the latest <em>development</em> tree from our git repository
215
            <pre>git clone git://common-lisp.net/projects/asdf/asdf.git</pre>
216
217
218
219
220
221
222
223
            (note that our "master" branch is for current development;
            get our "release" branch for the latest stable release.);
          </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>
224
225
        </li></ul>

226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
        <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"
		 >asdf-contrib</a>,
	    a collection of most of the below.</li>
	  <li><a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git"
		 >asdf-encodings</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"
		 >asdf-finalizers</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"
		 >asdf-dependency-grovel</a>,
	    to compute the actual dependencies in a big ASDF system.</li>
	  <li><a href="http://common-lisp.net/project/qitab/"
		 >poiu</a>,
	    to compile a system in parallel.</li>
246
247
248
	  <li><a href="http://www.lrde.epita.fr/~didier/software/lisp/misc.php#asdf-flv"
		 >asdf-flv</a>,
	    to bind file-local variables around the compilation of some files.</li>
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
        </ul>
        <p>Former extensions, now superseded, include:</p>
        <ul>
	  <li>ASDF-BINARY-LOCATIONS 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 ASDF/DEFSYSTEM's builtin ASDF-OUTPUT-TRANSLATIONS mechanism;
            a limited compatibility mode is available to easily convert
            your former ABL configuration into an AOT configuration.
            COMMON-LISP-CONTROLLER and CL-LAUNCH used to provide similar mechanisms,
            and have also been superseded by ASDF-OUTPUT-TRANSLATIONS.
          </li>
	  <li>ASDF-BUNDLE, née ASDF-ECL,
            allowed you to create single-file bundled outputs for your systems,
            for easier delivery.
            It is now a builtin part of ASDF/DEFSYSTEM.
          </li>
	  <li>ASDF-UTILS was a colletion of utilities that originated with ASDF.
            It is now superseded by ASDF/DRIVER, which is part of ASDF,
            and exports its functionality in its own package ASDF/DRIVER.
          </li>
	  <li>ASDF-CONDITION-CONTROL, initially part of XCVB's XCVB-DRIVER,
            allowed you to muffle uninteresting conditions during compilation.
            Is now superseded by equivalent functionality in ASDF/DRIVER.
          </li>
273
274
275
276
277
278
279
	</ul>

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

280
281
        <a id="bugs">
        <h3>Reporting Bugs</h3>
282
        <p>To report bugs, you can use our
283
284
285
286
287
          <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
288
289
        <a id="mailing-lists"></a>
        <h3>Mailing Lists</h3>
290
291
        <ul>
          <li><a href="http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel">asdf-devel</a>:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
292
293
294
295
296
297
298
299
300
            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.
301
302
303
304
305
306
307
308
309
310
        </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>
311
312
313
314
315
316
317
318
319
          <dt>In January 2013</dt>
          <dd>
            ASDF 3 now includes both the traditional ASDF/DEFSYSTEM
            and a formalized portability library ASDF/DRIVER.
            ASDF/DEFSYSTEM 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, and more.
            ASDF/DRIVER provides many abstractions to write portable Common Lisp programs.
          </dd>
320
321
          <dt>In April 2012</dt>
          <dd>
322
323
324
            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>,
325
            if you <kbd>:defsystem-depends-on (:asdf-encodings)</kbd>.
326
327
328
329
330
331
332
            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.
333
          </dd>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
334
          <dt>Since December 2009</dt>
335
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau is de facto maintainer,
336
            with notable contributions from Robert P. Goldman, but also
337
            Juanjo Garcia-Ripoll and James Anderson.
338
            ASDF 2 released
339
            with many clean-ups, better configurability, some new features,
340
341
342
343
344
            and updated documentation.
          </dd>
          <dt>May 2006 to November 2009</dt>
          <dd>Gary King is de facto maintainer,
            with notable contributions from
345
            Robert P. Goldman, Nikodemus Siivola, Christophe Rhodes, Daniel Herring.
346
            Many small features and bug fixes,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
347
            making the project more maintainable,
348
            moving to using git and common-lisp.net.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
349
            Last version: 1.369.
350
351
352
353
354
          </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.
355
            The system made more robust, a few more features.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
356
            Last version: 1.97.
357
          <dt>August 2001 to May 2004</dt>
358
          <dd>Developed by Daniel Barlow, with notable contributions from
359
            Christophe Rhodes, Kevin Rosenberg, Edi Weitz, Rahul Jain.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
360
            Last version: 1.37.
361
362
          <dt>August 2001</dt>
          <dd>Created by Daniel Barlow</dd>
363
364
      </dl>
          </div>
365
366
367
368
369
      <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>
370
        <p><span class="copyright"Copyright &copy; 2001-2012 Daniel Barlow and contributors</span></p>
371
        <p>ASDF has an <a href="http://www.opensource.org/licenses/mit-license.php">MIT style</a> license</p>
372
        <div id="timestamp">Last updated 2012-07-28</div>
373
    </div>
374
375
  </body>
</html>