Commit 1b0a0fd9 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau

Documentation tweak

Following a discussion on asdf-devel with jmll.
parent 3cf77735
......@@ -307,16 +307,19 @@ ASDF is @emph{not} a tool for library and system @emph{installation};
it plays a role like @code{make} or @code{ant}, not like a package manager.
In particular, ASDF should not to be confused with Quicklisp or ASDF-Install,
that attempt to find and download ASDF systems for you.
Despite what the name might suggest, ASDF-Install is not part of ASDF, but a separate piece of software.
Despite what the name might suggest,
ASDF-Install was never a part of ASDF, it was a separate piece of software.
ASDF-Install is also unmaintained and obsolete.
We recommend you use Quicklisp
(@uref{http://www.quicklisp.org/}) instead,
a Common Lisp package manager which works well and is being actively maintained.
If you want to download software from version control instead of tarballs,
so you may more easily modify it, we recommend clbuild (@uref{http://common-lisp.net/project/clbuild/}).
We recommend @file{~/common-lisp/}
as a place into which to install Common Lisp software;
starting with ASDF 3.1.2, it is included in the default source-registry configuration.
so you may more easily modify it,
we recommend clbuild (@uref{http://common-lisp.net/project/clbuild/}).
As for where on your filesystem to install Common Lisp software,
we recommend subdirectories of @file{~/common-lisp/}:
starting with ASDF 3.1.2 (2014), this hierarchy is included
in the default source-registry configuration.
Finally, note that this manual is incomplete.
All the bases are covered,
......@@ -480,8 +483,9 @@ before you contact us and raise an issue.
@c versions of ASDF down, or encapsulate it.
If your implementation already provides ASDF 3 or later (and it should),
but you want a more recent ASDF version than your implementation provides,
then you just need to ensure the more recent ASDF is installed in a configured path, like any other system.
but you want a more recent ASDF version than your implementation provides, then
you just need to ensure the more recent ASDF is installed in a configured path,
like any other system.
We recommend you download an official tarball or checkout a release from git into
@file{~/common-lisp/asdf/}.
(@pxref{Configuring ASDF to find your systems}).
......@@ -499,15 +503,18 @@ If your implementation fails to provide ASDF 3 or later,
@section Replacing your implementation's ASDF
All maintained implementations now provide ASDF 3 in their latest release.
If your doesn't, we recommend you upgrade it.
If yours doesn't, we recommend you upgrade it.
Now, if you insist on using an old implementation that didn't provide ASDF or provided an old version,
Now, if you insist on using an old implementation
that didn't provide ASDF or provided an old version,
we recommend installing a recent ASDF, as explained below,
into your implementation's installation directory.
Thus your modified implementation will now provide ASDF 3.
This requires proper write permissions and may necessitate execution as a system administrator.
This requires proper write permissions and
may necessitate execution as a system administrator.
The ASDF source repository contains a tool to help you upgrade your implementation's ASDF.
The ASDF source repository contains a tool to
help you upgrade your implementation's ASDF.
You can invoke it from the shell command-line as
@code{tools/asdf-tools install-asdf lispworks}
(where you can replace @code{lispworks} by the name of the relevant implementation),
......@@ -681,6 +688,8 @@ may already have configured system-managed libraries for you.
@c should not be burdened with it. [2014/02/27:rpg]
Novices may skip this section.
Please @emph{do not} use the central-registry if you are a novice,
and @emph{do not} instruct novices to use the central-registry.
@c ``Experts may read it then proceed to ...''
@c some better section explaining
@c *central-registry* vs source-registry vs *system-definition-search-functions*,
......@@ -690,12 +699,27 @@ The old way to configure ASDF to find your systems is by
@code{push}ing directory pathnames onto the variable
@code{asdf:*central-registry*}.
You must configure this variable between the time you load ASDF
and the time you first try to use it.
Loading and configuring ASDF presumably happen
as part of some initialization script that builds or starts
your Common Lisp software system.
(For instance, some SBCL users used to put it in their @file{~/.sbclrc}.)
You @emph{must} configure this variable @emph{after} you load ASDF 3 or later,
yet @emph{before} the first time you try to use it.
This loading and configuring of ASDF must happen
as part of some initialization script:
typically, either a script you maintain that builds your project,
or your implementation's initialization script
(e.g. @file{~/.sbclrc} for SBCL).
Also, if you are using an ancient ASDF 2 or earlier to load ASDF 3 or later,
then after it loads the ancient ASDF, your script @emph{must} configure
the central-registry a first time to tell ASDF 1 or 2 where to find ASDF 3,
then load ASDF 3 with e.g. @code{(asdf:operate 'asdf:load-op "asdf")},
then configure the central-registry again, because
ASDF 3 will not preserve the central-registry from ASDF 2 when upgrading.
You should probably be using the source-registry instead, which will be preserved
(unless you manually called @code{asdf:initialize-source-registry} with an argument,
in which case you will have to do it again indeed).
However, if you are using an ancient ASDF 2 or earlier,
we @emph{strongly} recommend that you should instead upgrade your implementation,
or overwrite the ancient ASDF installation with a more recent one:
@xref{Replacing your implementation's ASDF}.
The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
but is still supported for compatibility with ASDF 1.
......@@ -742,6 +766,8 @@ is necessary to tell Lisp that you're discussing a directory
rather than a file. If you leave it out, ASDF is likely to look in
@code{/home/me/src/} instead of @code{/home/me/src/foo/} as you
intended, and fail to find your system definition.
Modern versions of ASDF will issue an error and offer you to
remove such entries from the central-registry.
Typically there are a lot of @file{.asd} files, and
a common idiom was to put
......@@ -3723,7 +3749,7 @@ The speedup will only happen if the implementation-provided ASDF is recent enoug
since the upgrade will itself be found but
after the old version has scanned the directories without heeding such a cache.
To upgrade the implementation-provided ASDF,
use our script @code{tools/install-asdf.lisp}.
@pxref{Replacing your implementation's ASDF}.
@node Configuration API, Introspection, Caching Results, Controlling where ASDF searches for systems
......@@ -5569,18 +5595,22 @@ and XCL is more of a working demo than something you'd use seriously anyway.
@item
For the above reasons, your build and startup scripts
should load, configure and upgrade ASDF among the very first things they do,
and ensure that ASDF 3 or later is present indeed,
before they start using ASDF to load anything else.
should load ASDF 3, configure it, and upgrade it,
among the very first things they do.
They should ensure that only ASDF 3 or later is used indeed,
and error out if ASDF 2 or earlier was used.
@item
Now that all implementations provide ASDF 3.1 or later (since May 2016),
Now that (since May 2016) all maintained implementations
(i.e. having had at least one release since 2014,
or a commit on their public source code repository)
provide ASDF 3.1 or later,
the simple solution is just to use code as below in your setup,
and when it fails, upgrade your implementation or replace its ASDF.
(@pxref{Replacing your implementation's ASDF}):
@example
(require "asdf")
#-asdf3 (error "ASDF 3 or bust")
#-asdf3.1 (error "ASDF 3.1 or bust")
@end example
@item
......@@ -5593,10 +5623,11 @@ or the code of @url{https://cliki.net/cl-launch,@code{cl-launch}}.
Note that in addition to the pitfalls and constraints above,
these heroic scripts (should you wish to write or modify one),
must take care to configure ASDF @emph{twice}.
A first time, right after you load the old ASDF 2 and before you upgrade to the new ASDF 3,
A first time, right after you load the old ASDF 2 (or 1!)
and before you upgrade to the new ASDF 3,
so it may find where you put ASDF 3.
A second time, because some implementations can't handle a smooth upgrade to ASDF 3,
and lose configuration as they do.
A second time, because most implementations can't handle a smooth upgrade from ASDF 2 to ASDF 3,
so ASDF 3 doesn't try (anymore) and loses any configuration from ASDF 2.
@lisp
(ignore-errors (funcall 'require "asdf")) ;; <--- try real hard
;; <--- insert heroics here, if that failed to provide ASDF 2 or 3
......@@ -5765,17 +5796,31 @@ when they upgrade to the upstream version.
@vindex *central-registry*
@cindex Quicklisp
If you upgrade ASDF on-line, loading a new version on top of an old one
(e.g., loading an updated version of ASDF to support systems that use
newer features), then you must reconfigure it. Notably,
@var{*central-registry*} is not maintained across upgrades.
When you upgrade the ASDF running in your Lisp image
from an ancient ASDF 2 or older to ASDF 3 or newer,
then you may have to re-configure ASDF.
If your configuration only consists in
using the source-registry and output-translations (as it should),
and if you are not explicitly calling @code{asdf:initialize-source-registry}
or @code{asdf:initialize-output-translations} with a non-nil argument,
then ASDF will reconfigure itself.
Otherwise, you will have to configure ASDF 2 (or older) to find ASDF 3,
then configure ASDF 3.
Notably, @var{*central-registry*} is not maintained across upgrades from ASDF 2.
@xref{reinitializeASDFAfterUpgrade,note about ASDF reconfiguration after upgrade}
Problems like this may be experienced if one loads Quicklisp (which as
of this writing bundles a quite old version of ASDF), upgrades
ASDF, and then tries to load new systems. It is better always to load
the most up-to-date ASDF you want, then load its configuration, for
reasons discussed in detail at the above cross-reference.
Problems like this may be experienced if one loads Quicklisp
(which as of this writing bundles an obsolete ASDF version 2.26),
upgrades ASDF, and then tries to load new systems.
The correct solution is to load the most up-to-date ASDF you can,
@emph{then} configure it, @emph{then} load Quicklisp and any other extension.
Do @emph{not} try to upgrade from ASDF 2 @emph{after} loading Quicklisp,
for it will leave both ASDF and Quicklisp badly misconfigured.
For details see the discussion at the above cross-reference.
Also, if you are experiencing such failures due to Quicklisp shipping an ancient ASDF,
please complain to Zach Beane about it.
@node Issues with configuring ASDF, Issues with using and extending ASDF to define systems, Issues with installing the proper version of ASDF, FAQ
@section Issues with configuring ASDF
......
......@@ -237,7 +237,7 @@
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.)
All these implementations provide ASDF 3.1 in their latest version,
All these implementations provide ASDF 3.1 or later in their latest version,
but your software distribution might have an older version.
</p><p>
As for remaining implementations,
......@@ -261,7 +261,7 @@
</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
ASDF 3 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.
......@@ -281,13 +281,13 @@
for providing ASDF via <tt>(require "asdf")</tt>
</li><li>
Genera was never open-source and never bundled ASDF,
but should otherwise just work with a recent ASDF 3.1,
but should otherwise just work with a recent ASDF 3,
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.
</li><li>
MCL similarly was open-sourced, but never bundled ASDF;
ASDF 3.1 should work just fine with it,
ASDF 3 should work just fine with it,
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.
......@@ -299,18 +299,18 @@
</li><li>
SCL was seemingly abandoned and never open-sourced.
It never bundled ASDF, but otherwise
should just work with a recent ASDF 3.1,
should just work with a recent ASDF 3,
if you somehow have a license and a working version.
</li><li>
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,
but you can replace it with ASDF 3, which works well with it,
inasmuch as anything works at all with XCL.
</li></ul>
</p>
<table border="1">
<tr><th></th>
<th align="left">Provide ASDF 3.1</th>
<th align="left">Provide ASDF 3.1 or later</th>
<th align="left">No ASDF</th>
<th align="left">Unmaintained</th></tr>
<tr><th align="left">Free</th>
......@@ -339,12 +339,12 @@
<td align="left">Genera, mocl, SCL</td></tr>
</table>
<p>
To deal with an implementation that does not yet provide ASDF 3.1,
To deal with an implementation that does not yet provide ASDF 3.1 or later,
we provide
<a href="https://common-lisp.net/asdf/asdf/blob/master/tools/install-asdf.lisp">a script</a>
that will install ASDF 3.1
where your implementation goes looking for it
when you <tt>(require "asdf")</tt> .
that will install the ASDF from your git checkout
to where your implementation goes looking for it
when you <tt>(require "asdf")</tt>.
</p><p>
Note that upgrading from an old version of ASDF 2 or earlier
is possible, but quite complex to do right in a robust way,
......
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