Commit 3e579958 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

Fix and update the webpage

parent 9bedd81b
......@@ -44,7 +44,7 @@
Its notable versions include pre-release 2.27 on February 1st 2013,
first stable release 3.0.1 on May 16th 2013,
major release 3.1.2 on May 6th 2014,
and latest release 3.1.7 on March 23rd 2016.
and latest release 3.2.0 on January 10th 2017.
</p>
<a id="what_it_is"></a>
<h3>What it is</h3>
......@@ -58,30 +58,40 @@
<dl>
<dt><tt>asdf/defsystem</tt></dt>
<dd>
<p>is a tool to describe how Lisp source code is organized in systems,
and to build and load these systems.
The build happens based on a plan in term of actions that depend on previous actions;
<p>is a tool to describe
how Lisp source code is organized in systems,
and how to build and load these systems.
The build happens based on a plan in term of
actions that depend on previous actions;
the plan is computed from the structure of the systems.
</p>
<p>
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,
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,
before you may compile and load other files that use them.
</p>
<p>
If you come from the C/C++ world, ASDF covers a bit of what each of
<tt>make</tt>, <tt>autoconf</tt>, <tt>dlopen</tt> and <tt>libc</tt> do for C programs:
If you come from the C/C++ world, ASDF covers a bit of what
each of <tt>make</tt>, <tt>autoconf</tt>, <tt>dlopen</tt> and
<tt>libc</tt> do for C programs:
it orchestrates the compilation and dependency management,
handles some of the portability issues, dynamically finds and loads code,
and offers some portable system access library.
Except everything is different in Common Lisp, and ultimately much simpler overall,
handles some of the portability issues,
dynamically finds and loads code,
and offers some portable system access library
(see <tt>uiop</tt> below for the latter).
Except everything is different in Common Lisp,
and ultimately much simpler overall,
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.
</p>
<p><tt>asdf/defsystem</tt> is the part that people usually refer to as <tt>ASDF</tt>,
<p><tt>asdf/defsystem</tt> is the part that people usually refer to
as <tt>ASDF</tt>,
with <tt>uiop</tt> being only a supporting library,
that happens to be distributed at the same time, by necessity.
</p>
......@@ -89,7 +99,8 @@
<dt><tt>uiop</tt></dt>
<dd>
<p>
the <em>U</em>tilities for <em>I</em>mplementation- and <em>O</em>S- <em>P</em>ortability,
the <em>U</em>tilities for <em>I</em>mplementation- and
<em>O</em>S- <em>P</em>ortability,
formerly known as <tt>asdf/driver</tt>,
is a Common Lisp portability library and runtime support system
that helps you write Common Lisp software in a portable way.
......@@ -107,18 +118,22 @@
for an overview,
and the documentation as extracted from its docstrings by
<a href="http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html">HEΛP</a>
(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).
(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).
</p>
<p>
<tt>uiop</tt> is distributed as part of <tt>ASDF</tt>:
its source code is <em>transcluded</em> in
the single-file <tt>asdf.lisp</tt> being distributed
and the precompiled fasls provided by Lisp implementations.
<tt>ASDF</tt> relies heavily on it for its portability layer and runtime support,
<tt>ASDF</tt> relies heavily on it
for its portability layer and runtime support,
particularly so as to handle pathnames and filesystem access.
<tt>uiop</tt> is useful on its own and can also be compiled and distributed separately.
<tt>uiop</tt> is useful on its own
and can also be compiled and distributed separately.
</p>
</dd>
</dl>
......@@ -126,16 +141,21 @@
<h3>What it is not</h3>
<p>
ASDF will <em>not</em> download missing software components for you.
For that, you want <a href="http://quicklisp.org/"><tt>Quicklisp</tt></a>,
For that, you want
<a href="http://quicklisp.org/"><tt>Quicklisp</tt></a>,
that builds upon ASDF, and is great for pulling and installing
tarballs of packages you may depend upon.
We also recommend <a href="https://common-lisp.net/project/clbuild/"><tt>clbuild</tt></a>,
that now builds upon Quicklisp, as a great tool for pulling from version control
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
packages you need to modify or want to contribute to.
We recommend you should <em>not</em> use <tt>asdf-install</tt> anymore,
as it is an older similar piece of software that is both unmaintained and obsolete.
We recommend you should <em>not</em> use <tt>asdf-install</tt>
anymore, as it is an older similar piece of software
that is both unmaintained and obsolete.
</p><p>
ASDF is also not a tool to build or run Common Lisp software from the Unix command-line.
ASDF is also not a tool to build or run Common Lisp software
from the Unix command-line.
For that, you want <a href="http://cliki.net/cl-launch">cl-launch</a>,
<a href="http://www.xach.com/lisp/buildapp/">buildapp</a>, or
<a href="https://github.com/roswell/roswell">roswell</a>.
......@@ -145,6 +165,11 @@
<a href="https://gitlab.common-lisp.net/asdf/asdf/blob/master/TODO">TODO list</a>,
you might be interested in other build systems for Common-Lisp:
<ul>
<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>
<li>Alastair Bridgewater's small and simple one-package-per-file
<a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a>
(also reimplemented as the ASDF extension
......@@ -154,10 +179,12 @@
</li>
<li>Fran&ccedil;ois-Ren&eacute; Rideau's
<a href="https://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a>
(building object and image files deterministically and in parallel,
but not actively maintained since 2012;
a hypothetical ASDF 4 could conceivably be evolved to support these features
thanks to the groundwork laid by ASDF 3).
(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).
</li>
<li>Drew McDermott's
<a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a>
......@@ -166,7 +193,8 @@
</li>
<li>Dmitriy Ivanov's
<a href="http://lisp.ystok.ru/asdlite/"><tt>ASDlite</tt></a>
(a somewhat improved incompatible variant of ASDF 1, less featureful than ASDF 3),
(a somewhat improved incompatible variant of ASDF 1,
much less featureful, robust or portable than ASDF 3),
</li>
<li>Mark Kantrowitz's
<a href="http://www.cliki.net/mk-defsystem"><tt>mk-defsystem</tt></a>
......@@ -179,31 +207,30 @@
</li>
<li>Peter von Etter's
<a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a>
(a much simpler system establishing a mapping between packages and files,
abandoned but see <tt>asdf-package-system</tt> and <tt>quick-build</tt> above),
(a much simpler system establishing a mapping
between packages and files, abandoned but
see <tt>asdf-package-system</tt> and <tt>quick-build</tt> above),
</li>
<li>Alexander Kahl's
<a href="http://www.cliki.net/evol"><tt>evol</tt></a>
(a reimplementation in Lisp of the GNU autotools stack, abandoned),
</li>
<li>Google's
<a href="https://github.com/qitab/bazelisp"><tt>bazelisp</tt></a>
(building Lisp applications deterministically with
<a href="https://bazel.io/">Bazel</a>).
(a reimplementation in Lisp of the GNU autotools stack,
abandoned).
</li>
</ul>
There are probably more.
However, none of these systems seems to ever have had the traction of ASDF,
probably because none was technically superior enough (if at all)
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)
to compensate for the first mover advantage.
</p>
<h3>Supported Implementations</h3>
<p>
ASDF 3 now supports all CL implementations
that seem to have any current user base, and then some.
But ASDF does not magically turn broken implementations into working ones,
But ASDF does not magically turn
broken implementations into working ones,
and some ASDF or UIOP features may not work
on less-maintained implementations that do not support them (see below).
on less-maintained implementations that do not support them
(see below).
</p><p>
Most implementations provide ASDF as a module,
and you can simply <tt>(require "asdf")</tt>.
......@@ -215,20 +242,26 @@
As for remaining implementations,
they are obsolete and/or mostly unmaintained;
ASDF was made to run with each of them at some point,
but some hacking is probably required to make the latest ASDF work well
but some hacking is probably required
to make the latest ASDF work well
with the latest release of these implementations:
<ul><li>
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 ships with an antique version of ASDF;
however ASDF has been recently updated in its source control system,
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,
and there is hope of a new release some day soon.
If needs be, you can replace CLISP's provided ASDF with a newer one,
or use an upgrade on top of that.
If needs be, you can replace CLISP's provided ASDF
with a newer one, or use an upgrade on top of that.
</li><li>
CormanLisp was recently open-sourced.
Its bundled ASDF has not yet been updated from 1.x;
ASDF 3.1 should work fine with it, but several features were disabled
ASDF 3.1 should work fine with it, but
several features were disabled
because CormanLisp was insufficiently compliant with the CLHS,
and requires some work in this regard.
Ask the new CormanLisp maintainers for updates.
......@@ -236,11 +269,13 @@
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.
For instance, as of November 2016,
<code>cl:require</code> and <code>ext:system</code> (and thus <code>uiop:run-program</code>)
For instance, as of January 2017,
<code>cl:require</code> and <code>ext:system</code>
(and thus <code>uiop:run-program</code>)
seem not to be working correctly on Windows.
</li><li>
GCL is somewhat maintained but its maintainer doesn't seem to care about ASDF,
GCL is somewhat maintained but
its maintainer doesn't seem to care about ASDF,
and hasn't replied for years to requests for bug fixes or
for providing ASDF via <tt>(require "asdf")</tt>
</li><li>
......@@ -262,10 +297,12 @@
natively supporting cross-compilation.
</li><li>
SCL was seemingly abandoned and never open-sourced.
It never bundled ASDF, but should otherwise just work with a recent ASDF 3.1,
It never bundled ASDF, but otherwise
should just work with a recent ASDF 3.1,
if you somehow have a license and a working version.
</li><li>
XCL is now an abandoned experiment. It provides some old ASDF 2;
XCL is now an abandoned experiment.
It provides some old ASDF 2;
but you can replace it with ASDF 3.1, which works well with it,
inasmuch as anything works at all with XCL.
</li></ul>
......@@ -301,15 +338,20 @@
<td align="left">Genera, mocl, SCL</td></tr>
</table>
<p>
To deal with an implementation that does not yet provide ASDF 3.1, we provide
To deal with an implementation that does not yet provide ASDF 3.1,
we provide
<a href="https://common-lisp.net/asdf/asdf/blob/master/tools/install-asdf.lisp">a script</a>
that can install ASDF 3.1 where your implementation goes looking for it
that will install ASDF 3.1
where your implementation goes looking for it
when you <tt>(require "asdf")</tt> .
</p><p>
Note that upgrading from an old version of ASDF 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 3
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
before it is actually supported.
</p>
<!-- Note to self:
......@@ -392,17 +434,19 @@ Corman Common Lisp <admin@cormanlisp.com>
regarding any feature that isn't well-documented enough.
</p>
<p>
Until we write more documentation on the further innovations of ASDF 3,
Until we write more documentation on the further innovations of ASDF,
the documentation strings,
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>
are unfortunately your best chances for discovering the available functionality.
are unfortunately your best chances
for discovering the available functionality.
</p>
<a id="downloads"></a>
<h3>Getting it</h3>
<p>Though they may lag behind the version here, ASDF comes bundled with most Lisps.
<p>Though they may lag behind the version here,
ASDF comes bundled with most Lisps.
To get the greatest and latest, you can:
</p>
<ul>
......@@ -451,10 +495,12 @@ Corman Common Lisp <admin@cormanlisp.com>
two other systems are loaded, to connect them.</li>
<li><a href="https://common-lisp.net/project/cffi/"
><tt>cffi</tt></a>,
lets you interface between with functions and datastructures written in C
lets you interface between functions and datastructures written in C
and functions written in Lisp,
including support for automatically detecting constants from C macros,
linking to dynamic libraries, and writing your own wrapper code in C.</li>
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>
<li><a href="https://common-lisp.net/project/qitab/"
><tt>poiu</tt></a>,
to compile a system in parallel on a multiprocessor machine.</li>
......@@ -463,7 +509,8 @@ Corman Common Lisp <admin@cormanlisp.com>
<ul>
<li><tt>asdf-binary-locations</tt>
used to allow one to redirect where ASDF 1 created its output files,
so they don't clash between implementations and don't pollute source directories.
so they don't clash between implementations
and don't pollute source directories.
It is superseded by <tt>asdf/defsystem</tt>'s builtin
<tt>asdf-output-translations</tt> mechanism;
a limited compatibility mode is available to easily convert
......@@ -481,7 +528,8 @@ Corman Common Lisp <admin@cormanlisp.com>
a standalone executable program (on supported implementations),
or an image containing your system precompiled.
</li>
<li><tt>asdf-condition-control</tt>, initially part of XCVB's <tt>xcvb-driver</tt>,
<li><tt>asdf-condition-control</tt>,
initially part of XCVB's <tt>xcvb-driver</tt>,
allowed you to muffle uninteresting conditions during compilation.
Is now superseded by equivalent functionality in <tt>uiop</tt>.
</li>
......@@ -495,11 +543,14 @@ Corman Common Lisp <admin@cormanlisp.com>
that also determines dependencies, in the style of
<a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a> or
<a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a>
(this functionality is built into recent versions of ASDF 3.1 and later,
but this package exists for backward compatibility with earlier versions of ASDF 3;
(this functionality is built into recent versions
of ASDF 3.1 and later,
but this package exists for backward compatibility
with earlier versions of ASDF 3;
search the manual for <tt>package-inferred-system</tt>).
</li>
<li><tt>asdf-utils</tt> was a collection of utilities that originated with ASDF.
<li><tt>asdf-utils</tt> was a collection of utilities
that originated with ASDF.
It is now superseded by <tt>uiop</tt>, aka <tt>asdf/driver</tt>,
which is part of ASDF,
and exports its functionality
......@@ -520,13 +571,16 @@ Corman Common Lisp <admin@cormanlisp.com>
you can send email to the project mailing-list below.
</p>
<p>
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.
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.
If you're courageous, send us merge requests on
<a href="https://gitlab.common-lisp.net/asdf/asdf/">gitlab</a>.
</p>
<p>
While bug fixes are useful, they are not usually as valuable as test cases:
While bug fixes are useful,
they are not usually as valuable as test cases:
small easy fixes will be obvious from the test case,
and large fixes written by someone who isn't
either a maintainer or working tightly with one
......@@ -535,7 +589,8 @@ Corman Common Lisp <admin@cormanlisp.com>
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.
Now, if you're willing to become a maintainer, you're welcome to join the team!
Now, if you're willing to become a maintainer,
you're welcome to join the team!
</p>
<a id="mailing-lists"></a>
......@@ -549,15 +604,16 @@ Corman Common Lisp <admin@cormanlisp.com>
mailman site to subscribe</a>
</li>
<li><b>asdf-announce</b>
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,
A low-volume mailing-list for announcements only,
mostly regarding new releases.
Posting is restricted to project administrators
and to important notices.
Please subscribe to it
if you're a Lisp implementation or distribution vendor,
who needs to know when to upgrade the ASDF you distribute,
but are otherwise not interested in day to day design and
development.
<a
href="http://mailman.common-lisp.net/cgi-bin/mailman/listinfo/asdf-announce">asdf-announce
mailman site to subscribe</a>
development.
<a href="http://mailman.common-lisp.net/cgi-bin/mailman/listinfo/asdf-announce">asdf-announce mailman site to subscribe</a>
</li></ul>
<h3>Contributing</h3>
......@@ -568,7 +624,7 @@ Corman Common Lisp <admin@cormanlisp.com>
<a id="news"></a>
<h3>What is happening</h3>
<dl>
<dt>December 2016</dt>
<dt>January 2017</dt>
<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
......@@ -576,7 +632,7 @@ Corman Common Lisp <admin@cormanlisp.com>
a <tt>uiop:with-deprecation</tt> facility to handle
progressive deprecation of functions,
a cleanup and tightening of the internal dependency model
(you are now required to use <tt>make-operation<tt>
(you are now required to use <tt>make-operation</tt>
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,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment