index.html 40.4 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,
46
          major releases 3.1.2 on May 6th 2014,
Robert Goldman's avatar
Robert Goldman committed
47 48
          3.2.0 on January 10th 2017 and 3.3.0 on October 6th 2017.
          The latest release is 3.3.1, published on November 4th 2017.
49
        </p>
50 51
        <a id="what_it_is"></a>
        <h3>What it is</h3>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
52
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
53 54 55
          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.
56
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
57
        <p>ASDF 3 contains two parts: <tt>asdf/defsystem</tt> and <tt>uiop</tt>.
58
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
59 60 61
        <dl>
          <dt><tt>asdf/defsystem</tt></dt>
          <dd>
62 63 64
            <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
65
              The build happens based on a plan in term of
66
              actions that depend on previous actions;
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
67
              the plan is computed from the structure of the systems.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
68 69
            </p>
            <p>
70 71 72 73 74 75
              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
76 77
              before you may compile and load other files that use them.
            </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
78
            <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
79
              If you come from the C/C++ world, ASDF covers a bit of what
80 81
              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
82 83
              it orchestrates the compilation and dependency management,
              handles some of the portability issues,
84
              dynamically finds and loads code,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
85
              and offers some portable system access library
86
              (see <tt>uiop</tt> below for the latter).
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
87
              Except everything is different in Common Lisp,
88
              and ultimately much simpler overall,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
89 90 91 92
              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
93
            </p>
94 95
            <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
96 97 98 99 100 101
              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
102
            <p>
103 104
              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
105
              formerly known as <tt>asdf/driver</tt>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
106 107 108
              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
109
            <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
110
              In addition to many general-purpose Lisp utilities,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
111 112 113 114 115 116 117
              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
118
              <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
119 120
              for an overview,
              and the documentation as extracted from its docstrings by
121
              <a href="http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html">HEΛP</a>
122 123 124 125 126
              (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
127
            </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
128
            <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
129
              <tt>uiop</tt> is distributed as part of <tt>ASDF</tt>:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
130
              its source code is <em>transcluded</em> in
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
131
              the single-file <tt>asdf.lisp</tt> being distributed
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
132
              and the precompiled fasls provided by Lisp implementations.
133 134
              <tt>ASDF</tt> relies heavily on it
              for its portability layer and runtime support,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
135
              particularly so as to handle pathnames and filesystem access.
136 137
              <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
138 139 140
            </p>
          </dd>
        </dl>
141 142
        <a id="what_it_is_not"></a>
        <h3>What it is not</h3>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
143
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
144
          ASDF will <em>not</em> download missing software components for you.
145 146
          For that, you want
          <a href="http://quicklisp.org/"><tt>Quicklisp</tt></a>,
147
          that builds upon ASDF, and is great for pulling and installing
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
148
          tarballs of packages you may depend upon.
149 150 151 152
          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
153
          packages you need to modify or want to contribute to.
154 155 156
          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.
157
        </p><p>
158 159
          ASDF is also not a tool to build or run Common Lisp software
          from the Unix command-line.
160
          For that, you want <a href="http://cliki.net/cl-launch">cl-launch</a>,
161 162
          <a href="http://www.xach.com/lisp/buildapp/">buildapp</a>, or
          <a href="https://github.com/roswell/roswell">roswell</a>.
163
        </p><p>
164
          If you're unsatisfied with ASDF,
165
          beside helping with our
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
166
          <a href="https://gitlab.common-lisp.net/asdf/asdf/blob/master/TODO">TODO list</a>,
167 168
          you might be interested in other build systems for Common-Lisp:
          <ul>
169 170 171 172 173
            <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>
174
            <li>Alastair Bridgewater's small and simple one-package-per-file
175
              <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a>
176
              (also reimplemented as the ASDF extension
177
              <a href="https://gitlab.common-lisp.net/asdf/asdf-package-system"
178 179
                 ><tt>asdf-package-system</tt></a>, now part of ASDF 3;
              similar to <tt>faslpath</tt> below).
180 181
            </li>
            <li>Fran&ccedil;ois-Ren&eacute; Rideau's
182
              <a href="https://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a>
183 184 185 186 187 188
              (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).
189 190 191
            </li>
            <li>Drew McDermott's
              <a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a>
192
              (the polar opposite of XCVB, trying to maintain coherence
193 194 195 196
              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>
197 198
              (a somewhat improved incompatible variant of ASDF 1,
              much less featureful, robust or portable than ASDF 3),
199 200 201 202 203 204 205 206 207 208 209 210
            </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>
211 212 213
              (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),
214 215 216
            </li>
            <li>Alexander Kahl's
              <a href="http://www.cliki.net/evol"><tt>evol</tt></a>
217 218
              (a reimplementation in Lisp of the GNU autotools stack,
              abandoned).
219
            </li>
220
          </ul>
221 222 223
          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)
224
          to compensate for the first mover advantage.
225
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
226
        <a id="implementations"></a>
227
        <h3>Supported Implementations</h3>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
228
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
229
          ASDF 3 now supports all CL implementations
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
230
          that seem to have any current user base, and then some.
231 232
          But ASDF does not magically turn
          broken implementations into working ones,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
233
          and some ASDF or UIOP features may not work
234 235
          on less-maintained implementations that do not support them
          (see below).
236
        </p><p>
237
          Most implementations provide ASDF as a module,
238 239 240
          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
241
          All these implementations provide ASDF 3.1 or later in their latest version,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
242
          but your software distribution might have an older version.
243
        </p><p>
244
          As for remaining implementations,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
245
          they are obsolete and/or mostly unmaintained;
246
          ASDF was made to run with each of them at some point,
247 248
          but some hacking is probably required
          to make the latest ASDF work well
249 250
          with the latest release of these implementations:
          <ul><li>
251 252 253 254 255 256 257 258
              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
259
              and there is hope of a new release some day soon.
260 261
              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
262 263 264
            </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
265
              ASDF 3 should work fine with it, but
266
              several features were disabled
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
267 268 269 270 271 272 273
              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.
274 275 276
              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
277 278
              seem not to be working correctly on Windows.
            </li><li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
279
              GCL is somewhat maintained but
280
              its maintainer doesn't seem to care about ASDF,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
281
              and hasn't replied for years to requests for bug fixes or
282 283
              for providing ASDF via <tt>(require "asdf")</tt>
            </li><li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
284
              Genera was never open-source and never bundled ASDF,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
285
              but should otherwise just work with a recent ASDF 3,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
286 287 288
              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.
289 290
            </li><li>
              MCL similarly was open-sourced, but never bundled ASDF;
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
291
              ASDF 3 should work just fine with it,
292 293 294 295
              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
296 297 298 299
              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.
300
            </li><li>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
301
              SCL was seemingly abandoned and never open-sourced.
302
              It never bundled ASDF, but otherwise
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
303
              should just work with a recent ASDF 3,
304 305
              if you somehow have a license and a working version.
            </li><li>
306 307
              XCL is now an abandoned experiment.
              It provides some old ASDF 2;
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
308
              but you can replace it with ASDF 3, which works well with it,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
309
              inasmuch as anything works at all with XCL.
310
          </li></ul>
311
        </p>
312
        <table border="1">
313
          <tr><th></th>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
314
            <th align="left">Provide ASDF 3.1 or later</th>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
315
            <th align="left">No ASDF</th>
316
            <th align="left">Unmaintained</th></tr>
317
          <tr><th align="left">Free</th>
318 319 320 321 322 323 324
            <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>,
325
              <a href="https://github.com/froggey/Mezzano/" title="Mezzano">Mezzano</a>,
326 327 328 329 330
              <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>,
331 332
              <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>
333
            </td>
334
            <td align="left"><a href="https://github.com/gnooth/xcl">XCL</a></td></tr>
335
          <tr><th align="left">Proprietary</th>
336 337 338 339
            <td align="left">
              <a href="http://franz.com/products/allegro-common-lisp/">Allegro</a>,
              <a href="http://www.lispworks.com/">LispWorks</a>
            </td>
340
            <td align="left"></td>
341 342 343 344
            <td align="left">
              <a href="https://en.wikipedia.org/wiki/Genera_(operating_system)">Genera</a>,
              <a href="https://wukix.com/mocl">mocl</a>,
              <a title="Scieneer Common Lisp" href="http://www.scieneer.com/scl/">SCL</a></td></tr>
345
        </table>
346
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
347
          To deal with an implementation that does not yet provide ASDF 3.1 or later,
348
          we provide
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
349
          <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
350 351 352
          that will install the ASDF from your git checkout
          to where your implementation goes looking for it
          when you <tt>(require "asdf")</tt>.
353
        </p><p>
354 355 356 357 358 359 360
          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
361
          before it is actually supported.
362
        </p>
363 364
        <!-- Note to self:
             The maintainers of the following implementations require direct notification:
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
365
             abcl allegro ccl clisp cmucl ecl gcl lispworks mkcl sbcl scl xcl
366
Armed Bear <armedbear-devel@common-lisp.net>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
367 368
Allegro <bugs@franz.com>,
Clozure CL <openmcl-devel@clozure.com>,
369
GNU CLISP <clisp-list@lists.sourceforge.net> (sds),
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
370
CMU CL <cmucl-imp@cmucl.cons.org>,
371
ECL <ecl-devel@common-lisp.net>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
372 373 374 375 376 377
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>
378 379
CLASP <clasp-devel@common-lisp.net>
Corman Common Lisp <admin@cormanlisp.com>
380
        -->
381 382
        <p>
          If there is an old or new implementation that we are missing,
383
          it shouldn't be hard to adapt ASDF to support it.
384
          Ask us!
385
        </p>
386

387 388 389 390 391 392
        <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>

393 394 395 396 397 398 399
        <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
400
          <li><a href="https://gitlab.common-lisp.net/asdf/asdf/blob/master/doc/asdf.texinfo">as texinfo source</a></li>
401
        </ul>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
402
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
403 404 405 406 407 408 409 410
          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
411
        </p><p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
412 413 414 415
          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
416
        </p><p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
417 418 419
          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>
420
          (2-page <a href="http://fare.tunes.org/files/asdf2017/asdf2017.pdf">PDF</a>,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
421 422 423
          <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,
424
          and the work we did on ASDF 3,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
425
          see the extended version (26 pages) of our paper
426
          <cite><a href="http://fare.tunes.org/files/asdf3/asdf3-2014.html"
427
                   >ASDF 3, or Why Lisp is Now an Acceptable Scripting Language</a></cite>
428
          (<a href="http://fare.tunes.org/files/asdf3/asdf3-2014.pdf">PDF</a>,
429
          <a href="https://github.com/fare/asdf3-2013">git</a>).
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
430
          The shorter version (8 pages), presented at
431 432 433 434 435 436
          <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"
437
             >ASDF 3 tutorial</a> presented at ELS 2013,
438 439
          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
440 441
          For details about our previous work on ASDF 2,
          see our paper presented at
442 443
          <a href="http://www.international-lisp-conference.org/2010/index">ILC 2010</a>,
          <cite><a href="ilc2010draft.pdf"
444
                   >Evolving ASDF: More Cooperation, Less Coordination</a></cite>
445
          (<a href="https://gitlab.common-lisp.net/asdf/ilc2010">git</a>).
446
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
447
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
448
          Finally, while the manual covers all the basics,
449 450
          some advanced or new features remain underdocumented.
          Please contact our mailing-list (see below)
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
451
          regarding any feature that isn't well-documented enough.
452
        </p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
453
        <p>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
454
          Until we write more documentation on the further innovations of ASDF,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
455
          the documentation strings,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
456 457 458
          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>
459 460
          are unfortunately your best chances
          for discovering the available functionality.
461
        </p>
462

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

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

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

583 584
        <a id="bugs">
        <h3>Reporting Bugs</h3>
585
        <p>To report bugs, you can use our
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
586
          <a href="https://bugs.launchpad.net/asdf/">launchpad project</a>.
587 588 589
          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>
590
        <p>
591 592 593 594
          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.
595 596 597 598
          If you're courageous, send us merge requests on
          <a href="https://gitlab.common-lisp.net/asdf/asdf/">gitlab</a>.
        </p>
        <p>
599 600
          While bug fixes are useful,
          they are not usually as valuable as test cases:
601
          small easy fixes will be obvious from the test case,
602 603
          and large fixes written by someone who isn't
          either a maintainer or working tightly with one
604 605 606 607 608
          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.
609 610
          Now, if you're willing to become a maintainer,
          you're welcome to join the team!
611
        </p>
612

Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
613 614
        <a id="mailing-lists"></a>
        <h3>Mailing Lists</h3>
615
        <ul>
616
          <li><b>asdf-devel</b>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
617
            A list for questions, suggestions, bug reports, patches, and so on.
618
            It's for everyone and everything. Please join the conversation!
619 620 621
          <a
        href="http://mailman.common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel">asdf-devel
        mailman site to subscribe</a>
622
          </li>
623
          <li><b>asdf-announce</b>
624 625 626 627 628 629
            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,
630 631
            who needs to know when to upgrade the ASDF you distribute,
            but are otherwise not interested in day to day design and
632 633
            development.
            <a href="http://mailman.common-lisp.net/cgi-bin/mailman/listinfo/asdf-announce">asdf-announce mailman site to subscribe</a>
634 635 636 637 638 639 640 641 642
        </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
643 644
        <p>For a detailed description of changes see our <a href="Changelog">Changelog</a>
        </p>
Robert Goldman's avatar
Robert Goldman committed
645 646 647
        <dl>
          <dt>November 2017</dt>
          <dd>Release of 3.3.1: bugfix release for 3.3.0 addressing
648 649
            a backwards-incompatibility issue with timestamp computations,
            and other minor breakage.</dd>
650
          <dt>October 2017</dt>
651 652 653
          <dd>Release of 3.3.0, with substantial revision to the build plan
            to correct handle multiple phases of loading, due to e.g.
            <code>DEFSYSTEM-DEPENDS-ON</code> dependencies.</dd>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
654 655 656 657
          <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>
658
          <dt>January 2017</dt>
659 660 661 662 663 664 665
          <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
666
            (you are now required to use <tt>make-operation</tt>
667 668 669 670 671 672 673
            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
674 675
          <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
676 677 678 679 680 681
          <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
682 683 684 685 686
          <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>
687 688
          <dt>May 2015</dt>
          <dd>With the LispWorks 7.0 release, all actively maintained CL implementations
Robert Goldman's avatar
Robert Goldman committed
689
        are now providing ASDF 3.0 or later, and
690
        support for older variants is now officially dropped.</dd>
691 692
          <dt>October 2014</dt>
          <dd>More bug fixing leads to release of 3.1.4 on 10 October 2014.
693 694
          There should be no incompatibilities.
          See the <a href="changelog">Changelog</a> for more details.</dd>
695 696 697 698
          <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
699 700 701 702 703
          <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>
704
          <dt>July 2013 to May 2014</dt>
705
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau has resigned as maintainer
706
            but remained an active developer.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
707 708
            Robert P. Goldman is interim maintainer until someone more gifted,
            charming, dedicated, and better-looking can be secured to fill the role.
709 710 711 712
            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
713 714
          </dd>
          <dt>November 2012 to June 2013</dt>
715
          <dd>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
716
            Fran&ccedil;ois-Ren&eacute; Rideau completely rewrites ASDF
717
            and publishes ASDF 3, pre-released as 2.27 in February 2013,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
718 719
            and released as 3.0.1 in May 2013.
            It now includes both the traditional <tt>asdf/defsystem</tt>
720
            and a formalized portability library <tt>uiop</tt> (n&eacute;e <tt>asdf/driver</tt>).
721
            <tt>asdf/defsystem</tt> is a backward-compatible reimplementation of ASDF
722
            with correct timestamp propagation based on a consistent dependency model,
723
            and featuring support for bundle output, deferred warnings check, and more.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
724 725
            <tt>uiop</tt> provides many abstractions to write portable Common Lisp programs.
            Last version: 3.0.1.
726
          </dd>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
727
          <dt>December 2009 to October 2012</dt>
728
          <dd>Fran&ccedil;ois-Ren&eacute; Rideau is de facto maintainer,
729
            with notable contributions from Robert P. Goldman, but also
730
            Juanjo Garcia-Ripoll and James Anderson.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
731
            ASDF 2.000 is released in May 2010
732
            with many clean-ups, better configurability, some new features,
733
            and updated documentation.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
734 735 736 737
            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.
738 739 740 741
          </dd>
          <dt>May 2006 to November 2009</dt>
          <dd>Gary King is de facto maintainer,
            with notable contributions from
742
            Robert P. Goldman, Nikodemus Siivola, Christophe Rhodes, Daniel Herring.
743
            Many small features and bug fixes,
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
744
            making the project more maintainable,
745
            moving to using git and common-lisp.net.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
746
            Last version: 1.369.
747 748 749 750 751
          </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.
752
            The system made slightly more robust, a few more features.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
753
            Last version: 1.97.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
754
          </dd>
755
          <dt>August 2001 to May 2004</dt>
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
756
          <dd>Created then developed by Daniel Barlow, with notable contributions from
757
            Christophe Rhodes, Kevin Rosenberg, Edi Weitz, Rahul Jain.
758
            Last version: 1.85.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
759
          </dd>
760 761
      </dl>
          </div>
762 763 764 765 766
      <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>
767
        <p><span class="copyright"Copyright &copy; 2001-2017 Daniel Barlow and contributors</span></p>
768
        <p>ASDF has an <a href="http://www.opensource.org/licenses/mit-license.php">MIT style</a> license</p>
769
        <div id="timestamp">Last updated 2017-12-01</div>
770
    </div>
771 772
  </body>
</html>