From 0eb96ddad7fe50262fb08bed7ef2c1f5fe610de8 Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <tunes@google.com>
Date: Tue, 8 Apr 2014 21:25:23 -0400
Subject: [PATCH] doc: upgrading an implementation's ASDF; more on
 asdf/package-system.

---
 doc/asdf.texinfo | 106 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 68 insertions(+), 38 deletions(-)

diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo
index 41db5919..468ad44f 100644
--- a/doc/asdf.texinfo
+++ b/doc/asdf.texinfo
@@ -118,7 +118,7 @@ Loading ASDF
 
 Upgrading ASDF
 
-* Notes about ASDF 1 and ASDF 2::
+* Upgrading your implementation's ASDF::
 * Issues with upgrading ASDF::
 
 Configuring ASDF
@@ -480,33 +480,40 @@ ASDF will automatically look whether an updated version of itself is available
 amongst the regularly configured systems, before it compiles anything else.
 
 @menu
-* Notes about ASDF 1 and ASDF 2::
+* Upgrading your implementation's ASDF::
 * Issues with upgrading ASDF::
 @end menu
 
-@node Notes about ASDF 1 and ASDF 2, Issues with upgrading ASDF, Upgrading ASDF, Upgrading ASDF
-@subsection Notes about ASDF 1 and ASDF 2
-
-Most implementations provide ASDF 3 in their latest release,
-and we recommend upgrading your implementation rather than using ASDF 1 or 2.
-A few implementations only provide ASDF 2,
-that can be overridden by installing a fasl (see below).
-A few implementations don't provide ASDF,
-but a fasl can be installed to provide it.
-GCL so far is still lacking a usable @code{require} interface.
-
-If your implementation has no suitable upgrade available (yet),
-or somehow upgrading is not an option,
-we assume you're an expert deliberately using a legacy implementation,
-and are proficient enough to install this fasl.
-Still, the ASDF source repository contains a script
-@file{bin/install-asdf-as-module} that can help you do that.
-It relies on @code{cl-launch} 4 for command-line invocation,
-which may depend on ASDF being checked out in @file{~/cl/asdf/}
-if your implementation doesn't even have an ASDF 2;
-but if you don't have @code{cl-launch},
+@node Upgrading your implementation's ASDF, Issues with upgrading ASDF, Upgrading ASDF, Upgrading ASDF
+@subsection Upgrading your implementation's ASDF
+
+Most implementations provide a recent ASDF 3 in their latest release.
+If yours doesn't, we recommend upgrading your implementation.
+If the latest version of your implementation still doesn't provide ASDF,
+or provides an old version, we recommend installing a recent ASDF so your implementation provides it,
+as explained below.
+If all fails, we recommend you load ASDF from source
+@pxref{Loading ASDF,,Loading ASDF from source}.
+
+The ASDF source repository contains a script
+@file{bin/install-asdf-as-module} that can help you upgrade your implementation's ASDF.
+It works on
+Allegro CL, Clozure CL, CMU CL, ECL, GNU CLISP, LispWorks, MKCL, SBCL, SCL, XCL.
+That's all known implementations except ABCL, Corman CL, GCL, Genera, MCL, MOCL.
+Happily, ABCL is usually pretty up to date and shouldn't need that script.
+GCL would be supported, except that so far is still lacking usable support for @code{require}.
+Corman CL, Genera, MCL are obsolete anyway.
+MOCL is under development.
+On an old version of an implementation that does not provide ASDF,
+you may have to load ASDF 3 from source before you load that script.
+
+The script relies on @code{cl-launch} 4 for command-line invocation,
+which may depend on ASDF being checked out in @file{~/common-lisp/asdf/}
+(which we recommend anyway)
+if your implementation doesn't even have an ASDF 2.
+If you don't have @code{cl-launch},
 you can instead @code{(load "bin/install-asdf-as-module")}
-from your implementation's REPL.
+from your implementation's REPL after loading ASDF from source.
 
 Finally, if your implementation only provides ASDF 2,
 and you can't or won't upgrade it or override its ASDF module,
@@ -521,7 +528,7 @@ after requiring the builtin ASDF 2:
 (asdf:load-system :asdf)
 @end lisp
 
-@node Issues with upgrading ASDF,  , Notes about ASDF 1 and ASDF 2, Upgrading ASDF
+@node Issues with upgrading ASDF,  , Upgrading your implementation's ASDF, Upgrading ASDF
 @subsection Issues with upgrading ASDF
 
 Note that there are some limitations to upgrading ASDF:
@@ -1705,24 +1712,35 @@ of output from ASDF operations.
 @node The package-system extension,  , Other code in .asd files, Defining systems with defsystem
 @section The package-system extension
 
-Starting with ASDF 3.1.1,
+Starting with release 3.1.1,
 ASDF supports a one-package-per-file style of programming,
 whereby each file is its own system,
 and dependencies are deduced from the @code{defpackage} form.
 
-In this style, packages referring to a same-named system (downcased);
-and if a system is defined with @code{:class package-system},
+In this style, packages refer to a same-named system (downcased),
+unless specially registered.
+If a system is defined with @code{:class :package-system},
 then system names that start with that name
 (using the slash @code{/} separator)
 refer to files under the filesystem hierarchy where the system is defined.
 For instance, if system @code{my-lib} is defined in
-@file{/foo/bar/my-lib/my-lib.asd}, then system @code{my-lib/src/utility}
+@file{/foo/bar/my-lib/my-lib.asd}, then package @code{my-lib/src/utility}
 will be found in file @file{/foo/bar/my-lib/src/utility.lisp}.
 
-This style was made popular by @code{faslpath} and @code{quick-build} before,
-and at the cost of a stricter package discipline,
-seems to make for more maintainable code.
-It is used by ASDF itself (starting with ASDF 3) and by @code{lisp-interface-library}.
+This style was made popular
+by @code{faslpath} and @code{quick-build} before (@pxref{Bibliography}).
+It seems to make for more maintainable code,
+at the cost of a stricter package discipline:
+by imposing upon programmers a discipline of smaller namespaces,
+with explicit dependencies and especially explicit forward dependencies,
+the style encourages good factoring of the code into coherent units;
+by contrast, the traditional style of "everything in one package"
+has low overhead but doesn't scale very well.
+
+It is used by ASDF itself (starting with ASDF 3, aka 2.27)
+and by @code{lisp-interface-library},
+to the great satisfaction of the author (FRR).
+Others who have tried it before also expressed similar results.
 
 To use this style, choose a toplevel system name, e.g. @code{my-lib},
 and create a file @file{my-lib.asd}
@@ -1745,7 +1763,8 @@ In the code above, the
 @code{:defsystem-depends-on (:asdf-package-system)} is
 for compatibility with older versions of ASDF 3 (ASDF 2 not supported),
 and requires the @code{asdf-package-system} library to be present
-(it is implicitly provided by ASDF starting with ASDF 3.0.3).
+(it is implicitly provided by ASDF starting with release 3.1.1,
+which can be detected with the feature @code{:asdf3.1}).
 
 The function @code{register-system-packages} has to be called to register
 packages used or provided by your system and its components
@@ -3358,7 +3377,7 @@ that everyone uses implicitly.
 @node Rejected ideas, TODO, Status, Controlling where ASDF searches for systems
 @section Rejected ideas
 
-Alternatives I (Faré) considered and rejected while developing ASDF 2 included:
+Alternatives I (FRR) considered and rejected while developing ASDF 2 included:
 
 @enumerate
 @item Keep @code{asdf:*central-registry*} as the master with its current semantics,
@@ -5386,9 +5405,15 @@ Also, bugs that are now tracked on launchpad:
   ``ASDF 3, or Why Lisp is Now an Acceptable Scripting Language'', 2014.
   This article describes the innovations in ASDF 3 and 3.1,
   as well as historical information on previous versions.
-  @url{http://fare.tunes.org/files/asdf3/asdf3-2014.html}
   @url{http://github.com/fare/asdf3-2013}
-
+@item Alastair Bridgewater:
+  ``Quick-build'' (private communication), 2012.
+  @code{quick-build} is a simple and robust one file, one package build system,
+  similar to @code{faslpath}, in 182 lines of code
+  (117 of which are not blank, not comments, not docstrings).
+  Unhappily, it remains unpublished and its IP status is unclear as of April 2014.
+  @code{asdf/package-system} is mostly compatible with it,
+  modulo a different setup for toplevel hierarchies.
 @item Zach Beane:
   ``Quicklisp'', 2011.
   The Quicklisp blog and Xach's livejournal contain information on Quicklisp.
@@ -5405,7 +5430,12 @@ Also, bugs that are now tracked on launchpad:
   many ideas of which have been incorporated into ASDF 2 and 3,
   though many other of which still haven't.
   @url{http://common-lisp.net/projects/xcvb/}
-@item Dan Barlow: ``ASDF Manual'', 2004
+@item Peter von Etter: ``faslpath'', 2009.
+  @code{faslpath} is similar to the latter @code{quick-build}
+  and our letter @code{asdf/package-system} extension,
+  except that it uses the dot @code{.} rather than the slash @code{/} as a separator.
+  @url{https://code.google.com/p/faslpath/}
+@item Dan Barlow: ``ASDF Manual'', 2004.
   Older versions of this document from the days of ASDF 1;
   they include ideas laid down by Dan Barlow,
   and comparisons with older defsystems (@code{mk-defsystem})
-- 
GitLab