index.html 39.5 KB
Newer Older
1
2
3
4
5
6
<!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"/>
7
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
8
9
10
11
  </head>
  <body>
    <div class="header">
      <span class="logo">
12
        <a href="https://common-lisp.net/project/asdf/" title="ASDF Homepage">
13
14
15
16
17
          <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>
18
19
20
    <div class="system-links">
      <ul>
        <li><a href="#what_it_is">What it is</a></li>
21
22
        <li><a href="#what_it_is_not">What it is not</a></li>
        <li><a href="#implementations">Supported Implementations</a></li>
23
        <li><a href="#examples">Examples</a></li>
24
25
        <li><a href="#documentation">Documentation</a></li>
        <li><a href="#downloads">Getting it</a></li>
26
        <li><a href="#extensions">Extensions</a></li>
27
        <li><a href="#bugs">Reporting Bugs</a></li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
28
        <li><a href="#mailing-lists">Mailing Lists</a></li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
29
        <li><a href="#news">What is happening</a></li>
30
31
      </ul>
    </div>
32
    <div class="contents">
33
34
        <a id="ASDF 3"></a>
        <h3>ASDF 3</h3>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
35
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
36
37
38
39
40
          ASDF is the <i>de facto</i> standard build facility for Common Lisp.
          Your Lisp implementation probably contains a copy of ASDF,
          which you can load using <kbd>(require "asdf")</kbd>.
        </p><p>
          ASDF 3 is the current successor to Daniel Barlow's ASDF.
41
          It was rewritten for improved portability, robustness, usability,
42
          extensibility, configurability, internal consistency,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
43
          and the ability to deliver standalone executables.
44
          Its notable versions include pre-release 2.27 on February 1st 2013,
45
          first stable release 3.0.1 on May 16th 2013,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
46
47
          major releases 3.1.2 on May 6th 2014 and 3.2.0 on January 10th 2017,
          and latest release 3.2.1 on April 3rd 2017.
48
        </p>
49
50
        <a id="what_it_is"></a>
        <h3>What it is</h3>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
51
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
52
53
54
          ASDF is what Common Lisp hackers use to build and load software.
          It is the successor of the Lisp <tt>DEFSYSTEM</tt> of yore.
          ASDF stands for <em>A</em>nother <em>S</em>ystem <em>D</em>efinition <em>F</em>acility.
55
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
56
        <p>ASDF 3 contains two parts: <tt>asdf/defsystem</tt> and <tt>uiop</tt>.
57
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
58
59
60
        <dl>
          <dt><tt>asdf/defsystem</tt></dt>
          <dd>
61
62
63
            <p>is a tool to describe
              how Lisp source code is organized in systems,
              and how to build and load these systems.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
64
              The build happens based on a plan in term of
65
              actions that depend on previous actions;
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
66
              the plan is computed from the structure of the systems.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
67
68
            </p>
            <p>
69
70
71
72
73
74
              Typical actions consist in compiling a Lisp source file
              (unless already up to date)
              and loading the resulting compilation output
              (unless both already loaded and up to date).
              And you must typically compile and load
              files that define packages, macros, variables,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
75
76
              before you may compile and load other files that use them.
            </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
77
            <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
78
              If you come from the C/C++ world, ASDF covers a bit of what
79
80
              each of <tt>make</tt>, <tt>autoconf</tt>, <tt>dlopen</tt> and
              <tt>libc</tt> do for C programs:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
81
82
              it orchestrates the compilation and dependency management,
              handles some of the portability issues,
83
              dynamically finds and loads code,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
84
              and offers some portable system access library
85
              (see <tt>uiop</tt> below for the latter).
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
86
              Except everything is different in Common Lisp,
87
              and ultimately much simpler overall,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
88
89
90
91
              though it does require acquiring some basic concepts
              that do not exactly match those of the C and Unix world.
              Importantly, ASDF builds all software in the current Lisp image,
              as opposed to building software into separate processes.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
92
            </p>
93
94
            <p><tt>asdf/defsystem</tt> is the part that people usually refer to
              as <tt>ASDF</tt>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
95
96
97
98
99
100
              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>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
101
            <p>
102
103
              the <em>U</em>tilities for <em>I</em>mplementation- and
              <em>O</em>S- <em>P</em>ortability,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
104
              formerly known as <tt>asdf/driver</tt>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
105
106
107
              is a Common Lisp portability library and runtime support system
              that helps you write Common Lisp software in a portable way.
            </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
108
            <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
109
              In addition to many general-purpose Lisp utilities,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
110
111
112
113
114
115
116
              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
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
117
              <a href="https://gitlab.common-lisp.net/asdf/asdf/blob/master/uiop/README.md">README.md</a>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
118
119
              for an overview,
              and the documentation as extracted from its docstrings by
120
              <a href="http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html">HEΛP</a>
121
122
123
124
125
              (NB: you can, though it's not obvious,
              scroll the list of packages with a scrollbar
              on the right of the top-left pane,
              and then click on the package you're interested in
              to browse its symbols).
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
126
            </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
127
            <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
128
              <tt>uiop</tt> is distributed as part of <tt>ASDF</tt>:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
129
              its source code is <em>transcluded</em> in
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
130
              the single-file <tt>asdf.lisp</tt> being distributed
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
131
              and the precompiled fasls provided by Lisp implementations.
132
133
              <tt>ASDF</tt> relies heavily on it
              for its portability layer and runtime support,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
134
              particularly so as to handle pathnames and filesystem access.
135
136
              <tt>uiop</tt> is useful on its own
              and can also be compiled and distributed separately.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
137
138
139
            </p>
          </dd>
        </dl>
140
141
        <a id="what_it_is_not"></a>
        <h3>What it is not</h3>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
142
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
143
          ASDF will <em>not</em> download missing software components for you.
144
145
          For that, you want
          <a href="http://quicklisp.org/"><tt>Quicklisp</tt></a>,
146
          that builds upon ASDF, and is great for pulling and installing
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
147
          tarballs of packages you may depend upon.
148
149
150
151
          We also recommend
          <a href="https://common-lisp.net/project/clbuild/"><tt>clbuild</tt></a>,
          that now builds upon Quicklisp,
          as a great tool for pulling from version control
152
          packages you need to modify or want to contribute to.
153
154
155
          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.
156
        </p><p>
157
158
          ASDF is also not a tool to build or run Common Lisp software
          from the Unix command-line.
159
          For that, you want <a href="http://cliki.net/cl-launch">cl-launch</a>,
160
161
          <a href="http://www.xach.com/lisp/buildapp/">buildapp</a>, or
          <a href="https://github.com/roswell/roswell">roswell</a>.
162
        </p><p>
163
          If you're unsatisfied with ASDF,
164
          beside helping with our
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
165
          <a href="https://gitlab.common-lisp.net/asdf/asdf/blob/master/TODO">TODO list</a>,
166
167
          you might be interested in other build systems for Common-Lisp:
          <ul>
168
169
170
171
172
            <li>Google's deterministic and scalable build system
              <a href="https://bazel.build/">Bazel</a>,
              for which Lisp support is available:
              <a href="https://github.com/qitab/bazelisp"><tt>bazelisp</tt></a>.
            </li>
173
            <li>Alastair Bridgewater's small and simple one-package-per-file
174
              <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a>
175
              (also reimplemented as the ASDF extension
176
              <a href="https://gitlab.common-lisp.net/asdf/asdf-package-system"
177
178
                 ><tt>asdf-package-system</tt></a>, now part of ASDF 3;
              similar to <tt>faslpath</tt> below).
179
180
            </li>
            <li>Fran&ccedil;ois-Ren&eacute; Rideau's
181
              <a href="https://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a>
182
183
184
185
186
187
              (building object and image files deterministically
              and in parallel, but
              not actively maintained and bitrotten since 2012;
              a hypothetical ASDF 4 could conceivably be evolved to support
              these features thanks to the groundwork laid by ASDF 3;
              or you could use Bazel).
188
189
190
            </li>
            <li>Drew McDermott's
              <a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a>
191
              (the polar opposite of XCVB, trying to maintain coherence
192
193
194
195
              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>
196
197
              (a somewhat improved incompatible variant of ASDF 1,
              much less featureful, robust or portable than ASDF 3),
198
199
200
201
202
203
204
205
206
207
208
209
            </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>
210
211
212
              (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),
213
214
215
            </li>
            <li>Alexander Kahl's
              <a href="http://www.cliki.net/evol"><tt>evol</tt></a>
216
217
              (a reimplementation in Lisp of the GNU autotools stack,
              abandoned).
218
            </li>
219
          </ul>
220
221
222
          There are probably more. However, none of these systems seems
          to ever have had the traction of ASDF, probably because
          none was technically superior and/or portable enough (if at all)
223
          to compensate for the first mover advantage.
224
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
225
        <a id="implementations"></a>
226
        <h3>Supported Implementations</h3>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
227
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
228
          ASDF 3 now supports all CL implementations
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
229
          that seem to have any current user base, and then some.
230
231
          But ASDF does not magically turn
          broken implementations into working ones,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
232
          and some ASDF or UIOP features may not work
233
234
          on less-maintained implementations that do not support them
          (see below).
235
        </p><p>
236
          Most implementations provide ASDF as a module,
237
238
239
          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's avatar
Francois-Rene Rideau committed
240
          All these implementations provide ASDF 3.1 or later in their latest version,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
241
          but your software distribution might have an older version.
242
        </p><p>
243
          As for remaining implementations,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
244
          they are obsolete and/or mostly unmaintained;
245
          ASDF was made to run with each of them at some point,
246
247
          but some hacking is probably required
          to make the latest ASDF work well
248
249
          with the latest release of these implementations:
          <ul><li>
250
251
252
253
254
255
256
257
              CLISP is generally well-tested with ASDF,
              though it has a few minor bugs.
              The implementation has received only
              minimal maintenance since 2010,
              and the last official release doesn't ship with ASDF,
              or often has antique version of ASDF tucked on it.
              However, ASDF has been recently updated
              in its source control system,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
258
              and there is hope of a new release some day soon.
259
260
              If needs be, you can replace CLISP's provided ASDF
              with a newer one, or use an upgrade on top of that.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
261
262
263
            </li><li>
              CormanLisp was recently open-sourced.
              Its bundled ASDF has not yet been updated from 1.x;
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
264
              ASDF 3 should work fine with it, but
265
              several features were disabled
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
266
267
268
269
270
271
272
              because CormanLisp was insufficiently compliant with the CLHS,
              and requires some work in this regard.
              Ask the new CormanLisp maintainers for updates.
            </li><li>
              ECL is generally well-tested with ASDF, but
              its bytecode compiler doesn't support the bundle operations, and
              support for Windows seems to be less stable.
273
274
275
              For instance, as of January 2017,
              <code>cl:require</code> and <code>ext:system</code>
              (and thus <code>uiop:run-program</code>)
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
276
277
              seem not to be working correctly on Windows.
            </li><li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
278
              GCL is somewhat maintained but
279
              its maintainer doesn't seem to care about ASDF,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
280
              and hasn't replied for years to requests for bug fixes or
281
282
              for providing ASDF via <tt>(require "asdf")</tt>
            </li><li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
283
              Genera was never open-source and never bundled ASDF,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
284
              but should otherwise just work with a recent ASDF 3,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
285
286
287
              if you somehow have a license and a working version.
              There are rumors of people doing active development with it
              and having minor patches to improve ASDF on it.
288
289
            </li><li>
              MCL similarly was open-sourced, but never bundled ASDF;
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
290
              ASDF 3 should work just fine with it,
291
292
293
294
              but Rosetta is not supported in the latest versions of MacOS X,
              so a lot of work is required to make something out of it
              — at which point, you might just use CCL.
            </li><li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
295
296
297
298
              Mocl has its own heavily modified variant of ASDF2, and
              is the only implementation not currently supported by ASDF3.
              To make it work with ASDF 3 would require ASDF to be taught about
              natively supporting cross-compilation.
299
            </li><li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
300
              SCL was seemingly abandoned and never open-sourced.
301
              It never bundled ASDF, but otherwise
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
302
              should just work with a recent ASDF 3,
303
304
              if you somehow have a license and a working version.
            </li><li>
305
306
              XCL is now an abandoned experiment.
              It provides some old ASDF 2;
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
307
              but you can replace it with ASDF 3, which works well with it,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
308
              inasmuch as anything works at all with XCL.
309
          </li></ul>
310
        </p>
311
        <table border="1">
312
          <tr><th></th>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
313
            <th align="left">Provide ASDF 3.1 or later</th>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
314
            <th align="left">No ASDF</th>
315
            <th align="left">Unmaintained</th></tr>
316
          <tr><th align="left">Free</th>
317
318
319
320
321
322
323
324
325
326
327
328
            <td align="left">
              <a href="http://abcl.org/" title="Armed Bear Common Lisp">ABCL</a>,
              <a href="http://ccl.clozure.com/" title="Clozure Common Lisp">CCL</a>,
              <a href="https://github.com/drmeister/clasp">Clasp</a>,
              <a href="http://clisp.org/">CLISP</a>,
              <a href="http://cmucl.org/">CMUCL</a>,
              <a href="https://common-lisp.net/project/ecl/" title="Embeddable Common Lisp">ECL</a>,
              <a href="https://common-lisp.net/project/mkcl/" title="ManKai Common Lisp">MKCL</a>,
              <a href="http://www.sbcl.org/" title="Steel Bank Common Lisp">SBCL</a>
            </td>
            <td align="left">
              <a href="https://github.com/sharplispers/cormanlisp">CormanLisp</a>,
329
330
              <a title="GNU Common Lisp" href="https://www.gnu.org/software/gcl/">GCL</a>,
              <a title="Macintosh Common Lisp" href="https://en.wikipedia.org/wiki/Macintosh_Common_Lisp">MCL</a>
331
            </td>
332
            <td align="left">XCL</td></tr>
333
          <tr><th align="left">Proprietary</th>
334
335
336
337
            <td align="left">
              <a href="http://franz.com/products/allegro-common-lisp/">Allegro</a>,
              <a href="http://www.lispworks.com/">LispWorks</a>
            </td>
338
            <td align="left"></td>
339
            <td align="left">Genera, mocl, SCL</td></tr>
340
        </table>
341
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
342
          To deal with an implementation that does not yet provide ASDF 3.1 or later,
343
          we provide
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
344
          <a href="https://common-lisp.net/asdf/asdf/blob/master/tools/install-asdf.lisp">a script</a>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
345
346
347
          that will install the ASDF from your git checkout
          to where your implementation goes looking for it
          when you <tt>(require "asdf")</tt>.
348
        </p><p>
349
350
351
352
353
354
355
          Note that upgrading from an old version of ASDF 2 or earlier
          is possible, but quite complex to do right in a robust way,
          and we do not recommend it.
          Also note that <tt>mocl</tt> only supports
          a heavily modified variant of ASDF 2,
          and will require robust cross-compilation support
          to be added to ASDF
356
          before it is actually supported.
357
        </p>
358
359
        <!-- Note to self:
             The maintainers of the following implementations require direct notification:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
360
             abcl allegro ccl clisp cmucl ecl gcl lispworks mkcl sbcl scl xcl
361
Armed Bear <armedbear-devel@common-lisp.net>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
362
363
Allegro <bugs@franz.com>,
Clozure CL <openmcl-devel@clozure.com>,
364
GNU CLISP <clisp-list@lists.sourceforge.net> (sds),
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
365
CMU CL <cmucl-imp@cmucl.cons.org>,
366
ECL <ecl-devel@common-lisp.net>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
367
368
369
370
371
372
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>
373
374
CLASP <clasp-devel@common-lisp.net>
Corman Common Lisp <admin@cormanlisp.com>
375
        -->
376
377
        <p>
          If there is an old or new implementation that we are missing,
378
          it shouldn't be hard to adapt ASDF to support it.
379
          Ask us!
380
        </p>
381

382
383
384
385
386
387
        <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>

388
389
390
391
392
393
394
        <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>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
395
          <li><a href="https://gitlab.common-lisp.net/asdf/asdf/blob/master/doc/asdf.texinfo">as texinfo source</a></li>
396
        </ul>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
397
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
398
399
400
401
402
403
404
405
          The first few sections,
          <a href="https://common-lisp.net/project/asdf/asdf/Loading-ASDF.html">Loading ASDF</a>,
          <a href="https://common-lisp.net/project/asdf/asdf/Configuring-ASDF.html">Configuring ASDF</a>
          and <a href="https://common-lisp.net/project/asdf/asdf/Using-ASDF.html">Using ASDF</a>
          will get you started as a simple user.
        </p><p>
          If you want to define your own systems, further read the section
          <a href="https://common-lisp.net/project/asdf/asdf/Defining-systems-with-defsystem.html">Defining systems with defsystem</a>.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
406
        </p><p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
407
408
409
410
          There is now also a
          <a href="https://gitlab.common-lisp.net/asdf/asdf/blob/master/doc/best_practices.md">Best Practices</a>
          document explaining recommended usage patterns when writing <tt>.asd</tt> files,
          and detailing common pitfalls or deprecated practices to avoid.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
411
        </p><p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
412
413
414
415
416
417
418
          About the latest developments in ASDF 3.2 and ASDF 3.3, see our demo
          <cite><a href="http://fare.tunes.org/files/asdf2017/asdf2017.html"
                   >Delivering Common Lisp Applications with ASDF 3.3</a></cite>
          (<a href="http://fare.tunes.org/files/asdf2017/asdf2017.pdf">PDF</a>,
          <a href="http://fare.tunes.org/files/asdf2017/els2017-slides.pdf">slides</a>,
          <a href="https://github.com/fare/asdf2017">git</a>).
          Regarding the internal design of ASDF in general,
419
          and the work we did on ASDF 3,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
420
          see the extended version (26 pages) of our paper
421
          <cite><a href="http://fare.tunes.org/files/asdf3/asdf3-2014.html"
422
                   >ASDF 3, or Why Lisp is Now an Acceptable Scripting Language</a></cite>
423
          (<a href="http://fare.tunes.org/files/asdf3/asdf3-2014.pdf">PDF</a>,
424
          <a href="https://github.com/fare/asdf3-2013">git</a>).
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
425
          The shorter version (8 pages), presented at
426
427
428
429
430
431
          <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"
432
             >ASDF 3 tutorial</a> presented at ELS 2013,
433
434
          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>.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
435
436
          For details about our previous work on ASDF 2,
          see our paper presented at
437
438
          <a href="http://www.international-lisp-conference.org/2010/index">ILC 2010</a>,
          <cite><a href="ilc2010draft.pdf"
439
                   >Evolving ASDF: More Cooperation, Less Coordination</a></cite>
440
          (<a href="https://gitlab.common-lisp.net/asdf/ilc2010">git</a>).
441
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
442
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
443
          Finally, while the manual covers all the basics,
444
445
          some advanced or new features remain underdocumented.
          Please contact our mailing-list (see below)
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
446
          regarding any feature that isn't well-documented enough.
447
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
448
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
449
          Until we write more documentation on the further innovations of ASDF,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
450
          the documentation strings,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
451
452
453
          the <a href="https://gitlab.common-lisp.net/asdf/asdf">source code</a>,
          the <a href="changelog">changelog</a>
          and the <a href="https://gitlab.common-lisp.net/asdf/asdf/commits/master">git log</a>
454
455
          are unfortunately your best chances
          for discovering the available functionality.
456
        </p>
457

458
        <a id="downloads"></a>
459
        <h3>Getting it</h3>
460
461
        <p>Though they may lag behind the version here,
          ASDF comes bundled with most Lisps.
462
463
464
          To get the greatest and latest, you can:
        </p>
        <ul>
465
          <li>download just the latest <em>release</em> source for
466
            <a href="https://common-lisp.net/project/asdf/archives/asdf.lisp">asdf.lisp</a>;
467
          </li>
468
          <li>download the latest <em>release</em>
469
            <a href="https://common-lisp.net/project/asdf/archives/asdf.tar.gz">tarball</a>
470
            to get all bells and whistles;
471
          </li>
472
          <li>pull the latest <em>development</em> tree from our git repository
473
            <pre>git clone https://gitlab.common-lisp.net/asdf/asdf.git</pre>
474
            (note that our "master" branch is for current development;
475
476
            get our "release" branch for the latest stable release.
            Run <tt>make</tt> to create <tt>build/asdf.lisp</tt>);
477
          </li>
Robert P. Goldman's avatar
Robert P. Goldman committed
478
479
          <li>browse the latest <em>development</em> tree from our git
        repository:
480
          <a href="https://gitlab.common-lisp.net/asdf/asdf">gitlab</a>
481
482
          </li>
          <li>download the tarball of a past release:
483
            <a href="https://common-lisp.net/project/asdf/archives/">archives</a>
484
485
        </li></ul>

486
487
488
        <a id="extensions"></a>
        <h3>Extensions</h3>
        <p>Known extensions to ASDF include:</p>
489
        <ul>
490
491
492
493
          <li>
            <a href="https://gitlab.common-lisp.net/xcvb/asdf-dependency-grovel">
            <tt>asdf-dependency-grovel</tt></a>,
            to compute the actual dependencies in a big ASDF system.</li>
494
          <li><a href="https://gitlab.common-lisp.net/asdf/asdf-encodings"
495
496
                 ><tt>asdf-encodings</tt></a>,
            to compile Lisp source files with character encodings other than UTF-8.</li>
497
          <li><a href="https://gitlab.common-lisp.net/asdf/asdf-finalizers"
498
499
500
                 ><tt>asdf-finalizers</tt></a>,
            to allow macros to include code to be evaluated
            at the end of a file being compiled.</li>
501
502
503
          <li><a href="http://www.lrde.epita.fr/~didier/software/lisp/misc.php#asdf-flv"
                 ><tt>asdf-flv</tt></a>,
            to bind file-local variables around the compilation of some files.</li>
504
          <li><a href="https://common-lisp.net/project/asdf-system-connections/"
505
506
                 ><tt>asdf-system-connections</tt></a>,
            lets you specify systems that are automatically loaded when
507
            two other systems are loaded, to connect them.</li>
508
509
          <li><a href="https://common-lisp.net/project/cffi/"
                 ><tt>cffi</tt></a>,
510
            lets you interface between functions and datastructures written in C
511
            and functions written in Lisp,
512
513
514
515
            including support for
            automatically detecting constants from C macros,
            linking to dynamic (and now also static) libraries, and
            writing your own wrapper code in C.</li>
516
517
518
          <li><a href="https://common-lisp.net/project/qitab/"
                 ><tt>poiu</tt></a>,
            to compile a system in parallel on a multiprocessor machine.</li>
519
520
521
        </ul>
        <p>Former extensions, now superseded, include:</p>
        <ul>
522
523
          <li><tt>asdf-binary-locations</tt>
            used to allow one to redirect where ASDF 1 created its output files,
524
525
            so they don't clash between implementations
            and don't pollute source directories.
526
527
            It is superseded by <tt>asdf/defsystem</tt>'s builtin
            <tt>asdf-output-translations</tt> mechanism;
528
529
            a limited compatibility mode is available to easily convert
            your former ABL configuration into an AOT configuration.
530
531
532
533
            <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>
            (built into ASDF 2 and later).
534
          </li>
535
          <li><tt>asdf-bundle</tt>, n&eacute;e <tt>asdf-ecl</tt>,
536
            allowed you to create a single-file bundle out of a system,
537
            for easier delivery.
538
            It is now a builtin part of <tt>asdf/defsystem</tt>,
539
540
541
            and allows users to deliver a single FASL for a system,
            a standalone executable program (on supported implementations),
            or an image containing your system precompiled.
542
          </li>
543
544
          <li><tt>asdf-condition-control</tt>,
            initially part of XCVB's <tt>xcvb-driver</tt>,
545
546
547
            allowed you to muffle uninteresting conditions during compilation.
            Is now superseded by equivalent functionality in <tt>uiop</tt>.
          </li>
548
549
550
551
          <li><a href="https://gitlab.common-lisp.net/asdf/asdf-contrib"
                 ><tt>asdf-contrib</tt></a>,
            an empty package that used to collect dependencies on other systems
            in the list above and below.</li>
552
553
554
555
556
557
          <li><a href="http://gitlab.common-lisp.net/asdf/asdf-package-system"
                 ><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>
558
559
560
561
            (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;
562
563
            search the manual for <tt>package-inferred-system</tt>).
          </li>
564
565
          <li><tt>asdf-utils</tt> was a collection of utilities
            that originated with ASDF.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
566
            It is now superseded by <tt>uiop</tt>, aka <tt>asdf/driver</tt>,
567
568
569
            which is part of ASDF,
            and exports its functionality
            in its own package <tt>uiop</tt>.
570
          </li>
571
        </ul>
572
573
574
575
576
577

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

578
579
        <a id="bugs">
        <h3>Reporting Bugs</h3>
580
        <p>To report bugs, you can use our
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
581
          <a href="https://bugs.launchpad.net/asdf/">launchpad project</a>.
582
583
584
          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>
585
        <p>
586
587
588
589
          Note that the most valuable thing you can send this way
          are test cases,
          if possible as <tt>.script</tt> files
          readily runnable by our test system.
590
591
592
593
          If you're courageous, send us merge requests on
          <a href="https://gitlab.common-lisp.net/asdf/asdf/">gitlab</a>.
        </p>
        <p>
594
595
          While bug fixes are useful,
          they are not usually as valuable as test cases:
596
          small easy fixes will be obvious from the test case,
597
598
          and large fixes written by someone who isn't
          either a maintainer or working tightly with one
599
600
601
602
603
          will probably not be correct and not fit the codebase:
          any modification at one point is likely to have repercussions
          at other unobvious places in the codebase,
          for the code to be correct in a wider variety of scenarios
          than casual developers usually think about.
604
605
          Now, if you're willing to become a maintainer,
          you're welcome to join the team!
606
        </p>
607

Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
608
609
        <a id="mailing-lists"></a>
        <h3>Mailing Lists</h3>
610
        <ul>
611
          <li><b>asdf-devel</b>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
612
            A list for questions, suggestions, bug reports, patches, and so on.
613
            It's for everyone and everything. Please join the conversation!
614
615
616
          <a
        href="http://mailman.common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel">asdf-devel
        mailman site to subscribe</a>
617
          </li>
618
          <li><b>asdf-announce</b>
619
620
621
622
623
624
            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,
625
626
            who needs to know when to upgrade the ASDF you distribute,
            but are otherwise not interested in day to day design and
627
628
            development.
            <a href="http://mailman.common-lisp.net/cgi-bin/mailman/listinfo/asdf-announce">asdf-announce mailman site to subscribe</a>
629
630
631
632
633
634
635
636
637
        </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>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
638
639
        <p>For a detailed description of changes see our <a href="Changelog">Changelog</a>
        </p>
640
        <dl>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
641
642
643
644
          <dt>April 2017</dt>
          <dd>Release of 3.2.1, with many small bugfixes and cleanups.
            Presentation at ELS 2017 about ASDF 3.3.
          </dd>
645
          <dt>January 2017</dt>
646
647
648
649
650
651
652
          <dd>Release of 3.2.0, a release containing many notable improvements,
            such as a new portable <tt>uiop:launch-program</tt> facility for
            spawning asynchronous subprocesses
            (with many thanks to Elias Pipping),
            a <tt>uiop:with-deprecation</tt> facility to handle
            progressive deprecation of functions,
            a cleanup and tightening of the internal dependency model
653
            (you are now required to use <tt>make-operation</tt>
654
655
656
657
658
659
660
            to instantiate an operation class; also you'll be WARNed if your
            <tt>.asd</tt> file contains improperly named secondary systems),
            a systematic pass of adding documentation to all functions,
            many fixes to small bugs and portability issues
            across all underlying platforms and operating systems,
            an improved test suite,
            and the removal of some long deprecated functionality.</dd>
Robert Goldman's avatar
Robert Goldman committed
661
662
          <dt>March 2016</dt>
          <dd>Release of 3.1.7, another bug fix release for the 3.1.x series.</dd>
Robert Goldman's avatar
Robert Goldman committed
663
664
665
666
667
668
          <dt>October 2015</dt>
          <dd>Although we had hoped that ASDF 3.1.5 would be the final release
        in the ASDF 3.1 series, a number of bug reports led us to prepare
        release 3.1.6.  Support for Windows continues to improve, and we wished
        to release a number of bug fixes, and support the recent Allegro Common
        Lisp 10.0 release.</dd>
Robert Goldman's avatar
Robert Goldman committed
669
670
671
672
673
          <dt>July 2015</dt>
          <dd>An extensive bout of bug-fixing, notably on Windows, leads to
        release of ASDF 3.1.5 on 21 July 2015. XDG handling has been improved to
        be more compliant with the standard. <em>Preliminary</em> support for
        immutable systems has been added.</dd>
674
675
          <dt>May 2015</dt>
          <dd>With the LispWorks 7.0 release, all actively maintained CL implementations
Robert Goldman's avatar
Robert Goldman committed
676
        are now providing ASDF 3.0 or later, and
677
        support for older variants is now officially dropped.</dd>
678
679
          <dt>October 2014</dt>
          <dd>More bug fixing leads to release of 3.1.4 on 10 October 2014.
680
681
          There should be no incompatibilities.
          See the <a href="changelog">Changelog</a> for more details.</dd>
682
683
684
685
          <dt>August 2014</dt>
          <dd>The ASDF mailing lists have been reestablished, in particular
        asdf-announce, which should allow CL implementers better access to only
        the information they want about ASDF development.</dd>
Robert P. Goldman's avatar
Robert P. Goldman committed
686
687
688
689
690
          <dt>May 2014 to July 2014</dt>
          <dd>ASDF bug fixing from 3.1.2 leads to release of 3.1.3, a major bug
        fix release.  We strongly urge implementors that have shipped with 3.1.2
        to upgrade to 3.1.3. There should be no incompatibilities, and some
        very important bug fixes are provided. See the Changelog for more details.</dd>
691
          <dt>July 2013 to May 2014</dt>
692
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau has resigned as maintainer
693
            but remained an active developer.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
694
695
            Robert P. Goldman is interim maintainer until someone more gifted,
            charming, dedicated, and better-looking can be secured to fill the role.
696
697
698
699
            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.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
700
701
          </dd>
          <dt>November 2012 to June 2013</dt>
702
          <dd>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
703
            Fran&ccedil;ois-Ren&eacute; Rideau completely rewrites ASDF
704
            and publishes ASDF 3, pre-released as 2.27 in February 2013,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
705
706
            and released as 3.0.1 in May 2013.
            It now includes both the traditional <tt>asdf/defsystem</tt>
707
            and a formalized portability library <tt>uiop</tt> (n&eacute;e <tt>asdf/driver</tt>).
708
            <tt>asdf/defsystem</tt> is a backward-compatible reimplementation of ASDF
709
            with correct timestamp propagation based on a consistent dependency model,
710
            and featuring support for bundle output, deferred warnings check, and more.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
711
712
            <tt>uiop</tt> provides many abstractions to write portable Common Lisp programs.
            Last version: 3.0.1.
713
          </dd>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
714
          <dt>December 2009 to October 2012</dt>
715
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau is de facto maintainer,
716
            with notable contributions from Robert P. Goldman, but also
717
            Juanjo Garcia-Ripoll and James Anderson.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
718
            ASDF 2.000 is released in May 2010
719
            with many clean-ups, better configurability, some new features,
720
            and updated documentation.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
721
722
723
724
            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.
725
726
727
728
          </dd>
          <dt>May 2006 to November 2009</dt>
          <dd>Gary King is de facto maintainer,
            with notable contributions from
729
            Robert P. Goldman, Nikodemus Siivola, Christophe Rhodes, Daniel Herring.
730
            Many small features and bug fixes,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
731
            making the project more maintainable,
732
            moving to using git and common-lisp.net.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
733
            Last version: 1.369.
734
735
736
737
738
          </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.
739
            The system made slightly more robust, a few more features.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
740
            Last version: 1.97.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
741
          </dd>
742
          <dt>August 2001 to May 2004</dt>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
743
          <dd>Created then developed by Daniel Barlow, with notable contributions from
744
            Christophe Rhodes, Kevin Rosenberg, Edi Weitz, Rahul Jain.
745
            Last version: 1.85.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
746
          </dd>
747
748
      </dl>
          </div>
749
750
751
752
753
      <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>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
754
        <p><span class="copyright"Copyright &copy; 2001-2016 Daniel Barlow and contributors</span></p>
755
        <p>ASDF has an <a href="http://www.opensource.org/licenses/mit-license.php">MIT style</a> license</p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
756
        <div id="timestamp">Last updated 2017-04-30</div>
757
    </div>
758
759
  </body>
</html>