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}; ...@@ -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. 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, In particular, ASDF should not to be confused with Quicklisp or ASDF-Install,
that attempt to find and download ASDF systems for you. 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. ASDF-Install is also unmaintained and obsolete.
We recommend you use Quicklisp We recommend you use Quicklisp
(@uref{http://www.quicklisp.org/}) instead, (@uref{http://www.quicklisp.org/}) instead,
a Common Lisp package manager which works well and is being actively maintained. 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, 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/}). so you may more easily modify it,
We recommend @file{~/common-lisp/} we recommend clbuild (@uref{http://common-lisp.net/project/clbuild/}).
as a place into which to install Common Lisp software; As for where on your filesystem to install Common Lisp software,
starting with ASDF 3.1.2, it is included in the default source-registry configuration. 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. Finally, note that this manual is incomplete.
All the bases are covered, All the bases are covered,
...@@ -480,8 +483,9 @@ before you contact us and raise an issue. ...@@ -480,8 +483,9 @@ before you contact us and raise an issue.
@c versions of ASDF down, or encapsulate it. @c versions of ASDF down, or encapsulate it.
If your implementation already provides ASDF 3 or later (and it should), If your implementation already provides ASDF 3 or later (and it should),
but you want a more recent ASDF version than your implementation provides, but you want a more recent ASDF version than your implementation provides, then
then you just need to ensure the more recent ASDF is installed in a configured path, like any other system. 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 We recommend you download an official tarball or checkout a release from git into
@file{~/common-lisp/asdf/}. @file{~/common-lisp/asdf/}.
(@pxref{Configuring ASDF to find your systems}). (@pxref{Configuring ASDF to find your systems}).
...@@ -499,15 +503,18 @@ If your implementation fails to provide ASDF 3 or later, ...@@ -499,15 +503,18 @@ If your implementation fails to provide ASDF 3 or later,
@section Replacing your implementation's ASDF @section Replacing your implementation's ASDF
All maintained implementations now provide ASDF 3 in their latest release. 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, we recommend installing a recent ASDF, as explained below,
into your implementation's installation directory. into your implementation's installation directory.
Thus your modified implementation will now provide ASDF 3. 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 You can invoke it from the shell command-line as
@code{tools/asdf-tools install-asdf lispworks} @code{tools/asdf-tools install-asdf lispworks}
(where you can replace @code{lispworks} by the name of the relevant implementation), (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. ...@@ -681,6 +688,8 @@ may already have configured system-managed libraries for you.
@c should not be burdened with it. [2014/02/27:rpg] @c should not be burdened with it. [2014/02/27:rpg]
Novices may skip this section. 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 ``Experts may read it then proceed to ...''
@c some better section explaining @c some better section explaining
@c *central-registry* vs source-registry vs *system-definition-search-functions*, @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 ...@@ -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{push}ing directory pathnames onto the variable
@code{asdf:*central-registry*}. @code{asdf:*central-registry*}.
You must configure this variable between the time you load ASDF You @emph{must} configure this variable @emph{after} you load ASDF 3 or later,
and the time you first try to use it. yet @emph{before} the first time you try to use it.
Loading and configuring ASDF presumably happen This loading and configuring of ASDF must happen
as part of some initialization script that builds or starts as part of some initialization script:
your Common Lisp software system. typically, either a script you maintain that builds your project,
(For instance, some SBCL users used to put it in their @file{~/.sbclrc}.) 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, The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
but is still supported for compatibility with ASDF 1. but is still supported for compatibility with ASDF 1.
...@@ -742,6 +766,8 @@ is necessary to tell Lisp that you're discussing a directory ...@@ -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 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 @code{/home/me/src/} instead of @code{/home/me/src/foo/} as you
intended, and fail to find your system definition. 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 Typically there are a lot of @file{.asd} files, and
a common idiom was to put a common idiom was to put
...@@ -3723,7 +3749,7 @@ The speedup will only happen if the implementation-provided ASDF is recent enoug ...@@ -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 since the upgrade will itself be found but
after the old version has scanned the directories without heeding such a cache. after the old version has scanned the directories without heeding such a cache.
To upgrade the implementation-provided ASDF, 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 @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. ...@@ -5569,18 +5595,22 @@ and XCL is more of a working demo than something you'd use seriously anyway.
@item @item
For the above reasons, your build and startup scripts For the above reasons, your build and startup scripts
should load, configure and upgrade ASDF among the very first things they do, should load ASDF 3, configure it, and upgrade it,
and ensure that ASDF 3 or later is present indeed, among the very first things they do.
before they start using ASDF to load anything else. They should ensure that only ASDF 3 or later is used indeed,
and error out if ASDF 2 or earlier was used.
@item @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, the simple solution is just to use code as below in your setup,
and when it fails, upgrade your implementation or replace its ASDF. and when it fails, upgrade your implementation or replace its ASDF.
(@pxref{Replacing your implementation's ASDF}): (@pxref{Replacing your implementation's ASDF}):
@example @example
(require "asdf") (require "asdf")
#-asdf3 (error "ASDF 3 or bust") #-asdf3.1 (error "ASDF 3.1 or bust")
@end example @end example
@item @item
...@@ -5593,10 +5623,11 @@ or the code of @url{https://cliki.net/cl-launch,@code{cl-launch}}. ...@@ -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, Note that in addition to the pitfalls and constraints above,
these heroic scripts (should you wish to write or modify one), these heroic scripts (should you wish to write or modify one),
must take care to configure ASDF @emph{twice}. 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. so it may find where you put ASDF 3.
A second time, because some implementations can't handle a smooth upgrade to ASDF 3, A second time, because most implementations can't handle a smooth upgrade from ASDF 2 to ASDF 3,
and lose configuration as they do. so ASDF 3 doesn't try (anymore) and loses any configuration from ASDF 2.
@lisp @lisp
(ignore-errors (funcall 'require "asdf")) ;; <--- try real hard (ignore-errors (funcall 'require "asdf")) ;; <--- try real hard
;; <--- insert heroics here, if that failed to provide ASDF 2 or 3 ;; <--- insert heroics here, if that failed to provide ASDF 2 or 3
...@@ -5765,17 +5796,31 @@ when they upgrade to the upstream version. ...@@ -5765,17 +5796,31 @@ when they upgrade to the upstream version.
@vindex *central-registry* @vindex *central-registry*
@cindex Quicklisp @cindex Quicklisp
If you upgrade ASDF on-line, loading a new version on top of an old one When you upgrade the ASDF running in your Lisp image
(e.g., loading an updated version of ASDF to support systems that use from an ancient ASDF 2 or older to ASDF 3 or newer,
newer features), then you must reconfigure it. Notably, then you may have to re-configure ASDF.
@var{*central-registry*} is not maintained across upgrades. 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} @xref{reinitializeASDFAfterUpgrade,note about ASDF reconfiguration after upgrade}
Problems like this may be experienced if one loads Quicklisp (which as Problems like this may be experienced if one loads Quicklisp
of this writing bundles a quite old version of ASDF), upgrades (which as of this writing bundles an obsolete ASDF version 2.26),
ASDF, and then tries to load new systems. It is better always to load upgrades ASDF, and then tries to load new systems.
the most up-to-date ASDF you want, then load its configuration, for The correct solution is to load the most up-to-date ASDF you can,
reasons discussed in detail at the above cross-reference. @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 @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 @section Issues with configuring ASDF
......
...@@ -237,7 +237,7 @@ ...@@ -237,7 +237,7 @@
and you can simply <tt>(require "asdf")</tt>. and you can simply <tt>(require "asdf")</tt>.
(All of them but CLISP also accept (All of them but CLISP also accept
<tt>:asdf</tt>, <tt>"ASDF"</tt> or <tt>'asdf</tt> as an argument.) <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. but your software distribution might have an older version.
</p><p> </p><p>
As for remaining implementations, As for remaining implementations,
...@@ -261,7 +261,7 @@ ...@@ -261,7 +261,7 @@
</li><li> </li><li>
CormanLisp was recently open-sourced. CormanLisp was recently open-sourced.
Its bundled ASDF has not yet been updated from 1.x; 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 several features were disabled
because CormanLisp was insufficiently compliant with the CLHS, because CormanLisp was insufficiently compliant with the CLHS,
and requires some work in this regard. and requires some work in this regard.
...@@ -281,13 +281,13 @@ ...@@ -281,13 +281,13 @@
for providing ASDF via <tt>(require "asdf")</tt> for providing ASDF via <tt>(require "asdf")</tt>
</li><li> </li><li>
Genera was never open-source and never bundled ASDF, 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. if you somehow have a license and a working version.
There are rumors of people doing active development with it There are rumors of people doing active development with it
and having minor patches to improve ASDF on it. and having minor patches to improve ASDF on it.
</li><li> </li><li>
MCL similarly was open-sourced, but never bundled ASDF; 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, 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 so a lot of work is required to make something out of it
— at which point, you might just use CCL. — at which point, you might just use CCL.
...@@ -299,18 +299,18 @@ ...@@ -299,18 +299,18 @@
</li><li> </li><li>
SCL was seemingly abandoned and never open-sourced. SCL was seemingly abandoned and never open-sourced.
It never bundled ASDF, but otherwise 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. if you somehow have a license and a working version.
</li><li> </li><li>
XCL is now an abandoned experiment. XCL is now an abandoned experiment.
It provides some old ASDF 2; 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. inasmuch as anything works at all with XCL.
</li></ul> </li></ul>
</p> </p>
<table border="1"> <table border="1">
<tr><th></th> <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">No ASDF</th>
<th align="left">Unmaintained</th></tr> <th align="left">Unmaintained</th></tr>
<tr><th align="left">Free</th> <tr><th align="left">Free</th>
...@@ -339,12 +339,12 @@ ...@@ -339,12 +339,12 @@
<td align="left">Genera, mocl, SCL</td></tr> <td align="left">Genera, mocl, SCL</td></tr>
</table> </table>
<p> <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 we provide
<a href="https://common-lisp.net/asdf/asdf/blob/master/tools/install-asdf.lisp">a script</a> <a href="https://common-lisp.net/asdf/asdf/blob/master/tools/install-asdf.lisp">a script</a>
that will install ASDF 3.1 that will install the ASDF from your git checkout
where your implementation goes looking for it to where your implementation goes looking for it
when you <tt>(require "asdf")</tt> . when you <tt>(require "asdf")</tt>.
</p><p> </p><p>
Note that upgrading from an old version of ASDF 2 or earlier Note that upgrading from an old version of ASDF 2 or earlier
is possible, but quite complex to do right in a robust way, 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