GitLab

at 2017-10-07T09:00:19-07:00

Update to ASDF version 3.3.0

 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

  -->

-<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->

+<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->

 <head>

 <title>ASDF Manual</title>

     <ul class="no-bullet">

       <li><a name="toc-_0060_0060My-Common-Lisp-implementation-comes-with-an-outdated-version-of-ASDF_002e-What-to-do_003f_0027_0027" href="#My-Common-Lisp-implementation-comes-with-an-outdated-version-of-ASDF_002e-What-to-do_003f">13.4.1 &ldquo;My Common Lisp implementation comes with an outdated version of ASDF. What to do?&rdquo;</a></li>

       <li><a name="toc-_0060_0060I_0027m-a-Common-Lisp-implementation-vendor_002e-When-and-how-should-I-upgrade-ASDF_003f_0027_0027" href="#I_0027m-a-Common-Lisp-implementation-vendor_002e-When-and-how-should-I-upgrade-ASDF_003f">13.4.2 &ldquo;I&rsquo;m a Common Lisp implementation vendor. When and how should I upgrade ASDF?&rdquo;</a></li>

+      <li><a name="toc-After-upgrading-ASDF_002c-ASDF-_0028and-Quicklisp_0029-can_0027t-find-my-systems" href="#After-upgrading-ASDF">13.4.3 After upgrading ASDF, ASDF (and Quicklisp) can&rsquo;t find my systems</a></li>

     </ul></li>

     <li><a name="toc-Issues-with-configuring-ASDF-1" href="#Issues-with-configuring-ASDF">13.5 Issues with configuring ASDF</a>

     <ul class="no-bullet">

 <a name="Top"></a>

 <a name="ASDF_003a-Another-System-Definition-Facility"></a>

 <h1 class="top">ASDF: Another System Definition Facility</h1>

-<p>Manual for Version 3.2.1

+<p>Manual for Version 3.3.0

 </p>

 <p>This manual describes ASDF, a system definition facility

it plays a role like <code>make</code> or <code>ant</code>, 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

 (<a href="http://www.quicklisp.org/">http://www.quicklisp.org/</a>) 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 (<a href="http://common-lisp.net/project/clbuild/">http://common-lisp.net/project/clbuild/</a>).

-We recommend <samp>~/common-lisp/</samp>

-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 (<a href="http://common-lisp.net/project/clbuild/">http://common-lisp.net/project/clbuild/</a>).

+As for where on your filesystem to install Common Lisp software,

+we recommend subdirectories of <samp>~/common-lisp/</samp>:

+starting with ASDF 3.1.2 (2014), this hierarchy is included

+in the default source-registry configuration.

 </p>

Finally, note that this manual is incomplete.

 All the bases are covered,

 <h3 class="section">3.3 Upgrading ASDF</h3>

 <p>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

<samp>~/common-lisp/asdf/</samp>.

(see <a href="#Configuring-ASDF-to-find-your-systems">Configuring ASDF to find your systems</a>).

 <h3 class="section">3.4 Replacing your implementation&rsquo;s ASDF</h3>

All maintained implementations now provide ASDF 3 in their latest release.

-If your doesn&rsquo;t, we recommend you upgrade it.

+If yours doesn&rsquo;t, we recommend you upgrade it.

 </p>

-<p>Now, if you insist on using an old implementation that didn&rsquo;t provide ASDF or provided an old version,

+<p>Now, if you insist on using an old implementation

+that didn&rsquo;t provide ASDF or provided an old version,

 we recommend installing a recent ASDF, as explained below,

 into your implementation&rsquo;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.

 </p>

-<p>The ASDF source repository contains a tool to help you upgrade your implementation&rsquo;s ASDF.

+<p>The ASDF source repository contains a tool to

+help you upgrade your implementation&rsquo;s ASDF.

 You can invoke it from the shell command-line as

 <code>tools/asdf-tools install-asdf lispworks</code>

 (where you can replace <code>lispworks</code> by the name of the relevant implementation),

Novices may skip this section.

+Please <em>do not</em> use the central-registry if you are a novice,

+and <em>do not</em> instruct novices to use the central-registry.

 </p>

 <p>The old way to configure ASDF to find your systems is by

 <code>push</code>ing directory pathnames onto the variable

<code>asdf:*central-registry*</code>.

 </p>

-<p>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 <samp>~/.sbclrc</samp>.)

+<p>You <em>must</em> configure this variable <em>after</em> you load ASDF 3 or later,

+yet <em>before</em> 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&rsquo;s initialization script

+(e.g. <samp>~/.sbclrc</samp> for SBCL).

+</p>

+<p>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 <em>must</em> 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 &quot;asdf&quot;)</code>,

+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</code> 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 <em>strongly</em> recommend that you should instead upgrade your implementation,

+or overwrite the ancient ASDF installation with a more recent one:

+See <a href="#Replacing-your-implementation_0027s-ASDF">Replacing your implementation's ASDF</a>.

 </p>

 <p>The <code>asdf:*central-registry*</code> is empty by default in ASDF 2 or ASDF 3,

 but is still supported for compatibility with ASDF 1.

 rather than a file.  If you leave it out, ASDF is likely to look in

 <code>/home/me/src/</code> instead of <code>/home/me/src/foo/</code> 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.

 </p>

 <p>Typically there are a lot of <samp>.asd</samp> files, and

 a common idiom was to put

 pathname-specifier := pathname | string | symbol

+version-specifier := string

+                     | (:read-file-form &lt;pathname-specifier&gt; &lt;form-specifier&gt;?)

+                     | (:read-file-line &lt;pathname-specifier&gt; &lt;line-specifier&gt;?)

+line-specifier := :at integer # base zero

+form-specifier := :at [ integer | ( integer+ )]

+

 method-form := (operation-name qual lambda-list &amp;rest body)

 qual := method qualifier?

 the <code>:version</code> argument can be an expression that is resolved to

 such a string using the following trivial domain-specific language:

 in addition to being a literal string, it can be an expression of the form

-<code>(:read-file-form &lt;pathname-or-string&gt; :at &lt;access-at-specifier&gt;)</code>,

-which will be resolved by reading a form in the specified pathname

-(read as a subpathname of the current system if relative or a unix-namestring).

+<code>(:read-file-form &lt;pathname-or-string&gt; [:at &lt;access-at-specifier]&gt;)</code>,

+or <code>(:read-file-line &lt;pathname-or-string&gt; [:at

+&lt;access-at-specifier]?&gt;)</code>.

+As the name suggests, the former will be resolved by reading a form in the specified pathname

+(read as a subpathname of the current system if relative or a

+unix-namestring), and the latter by reading a line.

 You may use a <code>uiop:access-at</code> specifier

-with the (optional) <code>:at</code> keyword,

-by default the specifier is <code>0</code>, meaning the first form is returned;

+with the <code>:at</code> keyword,

+by default the specifier is <code>0</code>, meaning the first form/line is

+returned.

+For <code>:read-file-form</code>,

 subforms can also be specified, with e.g. <code>(1 2 2)</code> specifying

 &ldquo;the third subform (index 2) of the third subform (index 2) of the second form (index 1)&rdquo;

 in the file (mind the off-by-one error in the English language).

 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</code>.

+see <a href="#Replacing-your-implementation_0027s-ASDF">Replacing your implementation's ASDF</a>.

 </p>

 <hr>

 and XCL is more of a working demo than something you&rsquo;d use seriously anyway.

 </li><li> 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.

-

-</li><li> Now that all implementations provide ASDF 3.1 or later (since May 2016),

+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.

+

+</li><li> 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.

 (see <a href="#Replacing-your-implementation_0027s-ASDF">Replacing your implementation's ASDF</a>):

 <div class="example">

 <pre class="example">(require &quot;asdf&quot;)

-#-asdf3 (error &quot;ASDF 3 or bust&quot;)

+#-asdf3.1 (error &quot;ASDF 3.1 or bust&quot;)

 </pre></div>

 </li><li> For scripts that try to use ASDF simply via <code>require</code> at first, and

 see <samp>tools/load-asdf.lisp</samp> distributed with the ASDF source repository,

or the code of <a href="https://cliki.net/cl-launch"><code>cl-launch</code></a>.

-</li><li> Note that in addition to the pitfalls and constraints above,

+</li><li> <a name="reinitializeASDFAfterUpgrade"></a>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 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&rsquo;t handle a smooth upgrade to ASDF 3,

-and lose configuration as they do.

+A second time, because most implementations can&rsquo;t handle a smooth upgrade from ASDF 2 to ASDF 3,

+so ASDF 3 doesn&rsquo;t try (anymore) and loses any configuration from ASDF 2.

 <div class="lisp">

 <pre class="lisp">(ignore-errors (funcall 'require &quot;asdf&quot;)) ;; &lt;--- try real hard

 ;; &lt;--- insert heroics here, if that failed to provide ASDF 2 or 3

 </li></ul>

-

+<hr>

+<a name="After-upgrading-ASDF"></a>

+<a name="After-upgrading-ASDF_002c-ASDF-_0028and-Quicklisp_0029-can_0027t-find-my-systems"></a>

+<h4 class="subsection">13.4.3 After upgrading ASDF, ASDF (and Quicklisp) can&rsquo;t find my systems</h4>

+<a name="index-_002acentral_002dregistry_002a"></a>

+<a name="index-Quicklisp"></a>

+

+<p>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</code>

+or <code>asdf:initialize-output-translations</code> 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*</var> is not maintained across upgrades from ASDF 2.

+See <a href="#reinitializeASDFAfterUpgrade">note about ASDF reconfiguration after upgrade</a>.

+</p>

+<p>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,

+<em>then</em> configure it, <em>then</em> load Quicklisp and any other extension.

+Do <em>not</em> try to upgrade from ASDF 2 <em>after</em> loading Quicklisp,

+for it will leave both ASDF and Quicklisp badly misconfigured.

+For details see the discussion at the above cross-reference.

+</p>

+<p>Also, if you are experiencing such failures due to Quicklisp shipping an ancient ASDF,

+please complain to Zach Beane about it.

+</p>

 <hr>

 <a name="Issues-with-configuring-ASDF"></a>

 ;; Load the test script support.

 (load &quot;script-support.lisp&quot;)

-;; Initialize the script support.

-;; This will also change your *package* to asdf-test.

+;; Initialize the script support for interaction.

+;; This will also change your *package* to asdf-test

+;; after frobbing the asdf-test package to make it usable.

 ;; NB: this function is also available from package cl-user,

 ;; and also available with the shorter name da in both packages.

-(asdf-test::debug-asdf)

-

-;; In case you modified ASDF since you last tested it,

-;; you need to update asdf.lisp itself by evaluating 'make' in a shell,

-;; or (require &quot;asdf&quot;) (asdf:load-system :asdf) in another CL REPL,

-;; if not done in this REPL above.

-;; *Then*, in this REPL, you need to evaluate:

-;(asdf-test::compile-load-asdf)

+(asdf-test:debug-asdf)

 ;; Now, you may experiment with test code from a .script file.

 ;; See the instructions given at the end of your failing test

 ;; to identify which form is needed, e.g.

-(frob-packages)

-(asdf::with-asdf-cache () (load &quot;test-utilities.script&quot;))

+(run-test-script &quot;test-utilities.script&quot;)

 </pre></div>

  &nbsp; 

 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>

  &nbsp; 

+<a class="summary-letter" href="#Concept-Index_cp_letter-Q"><b>Q</b></a>

+ &nbsp; 

 <a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>

  &nbsp; 

 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>

 <tr><td></td><td valign="top"><a href="#index-pathname-specifiers">pathname specifiers</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-defsystem-grammar">The defsystem grammar</a></td></tr>

 <tr><td></td><td valign="top"><a href="#index-Primary-system-name">Primary system name</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Components">Components</a></td></tr>

 <tr><td colspan="4"> <hr></td></tr>

+<tr><th><a name="Concept-Index_cp_letter-Q">Q</a></th><td></td><td></td></tr>

+<tr><td></td><td valign="top"><a href="#index-Quicklisp">Quicklisp</a>:</td><td>&nbsp;</td><td valign="top"><a href="#After-upgrading-ASDF">After upgrading ASDF</a></td></tr>

+<tr><td colspan="4"> <hr></td></tr>

 <tr><th><a name="Concept-Index_cp_letter-R">R</a></th><td></td><td></td></tr>

 <tr><td></td><td valign="top"><a href="#index-readtables">readtables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#How-do-I-work-with-readtables_003f">How do I work with readtables?</a></td></tr>

 <tr><td colspan="4"> <hr></td></tr>

  &nbsp; 

 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>

  &nbsp; 

+<a class="summary-letter" href="#Concept-Index_cp_letter-Q"><b>Q</b></a>

+ &nbsp; 

 <a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>

  &nbsp; 

 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>

 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>

 <tr><td colspan="4"> <hr></td></tr>

 <tr><th><a name="Variable-Index_vr_symbol-1">*</a></th><td></td><td></td></tr>

+<tr><td></td><td valign="top"><a href="#index-_002acentral_002dregistry_002a"><code>*central-registry*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#After-upgrading-ASDF">After upgrading ASDF</a></td></tr>

 <tr><td></td><td valign="top"><a href="#index-_002acompile_002dfile_002dfailure_002dbehaviour_002a"><code>*compile-file-failure-behaviour*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-handling">Error handling</a></td></tr>

 <tr><td></td><td valign="top"><a href="#index-_002acompile_002dfile_002dwarnings_002dbehaviour_002a"><code>*compile-file-warnings-behaviour*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-handling">Error handling</a></td></tr>

 <tr><td></td><td valign="top"><a href="#index-_002adefault_002dsource_002dregistry_002dexclusions_002a"><code>*default-source-registry-exclusions*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Search-Algorithm">Search Algorithm</a></td></tr>

-This is asdf.info, produced by makeinfo version 6.3 from asdf.texinfo.

+This is asdf.info, produced by makeinfo version 6.1 from asdf.texinfo.

 This manual describes ASDF, a system definition facility for Common Lisp

 programs and libraries.

 ASDF: Another System Definition Facility

 ****************************************

-Manual for Version 3.2.1

+Manual for Version 3.3.0

    This manual describes ASDF, a system definition facility for Common

 Lisp programs and libraries.

 * My Common Lisp implementation comes with an outdated version of ASDF. What to do?::

 * I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::

+* After upgrading ASDF, ASDF (and Quicklisp) can't find my systems: After upgrading ASDF.

 Issues with configuring ASDF

 it plays a role like 'make' or '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.  ASDF-Install is also unmaintained and

-obsolete.  We recommend you use Quicklisp (<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 (<http://common-lisp.net/project/clbuild/>).  We

-recommend '~/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.

+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

+(<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

+(<http://common-lisp.net/project/clbuild/>).  As for where on your

+filesystem to install Common Lisp software, we recommend subdirectories

+of '~/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, but many advanced topics are only barely alluded to, and there

 ========================================

 All maintained implementations now provide ASDF 3 in their latest

-release.  If your doesn't, we recommend you upgrade it.

+release.  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, we recommend installing a recent ASDF,

 4.2 Configuring ASDF to find your systems -- old style

 ======================================================

-Novices may skip this section.

+Novices may skip this section.  Please _do not_ use the central-registry

+if you are a novice, and _do not_ instruct novices to use the

+central-registry.

    The old way to configure ASDF to find your systems is by 'push'ing

 directory pathnames onto the variable '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 '~/.sbclrc'.)

+   You _must_ configure this variable _after_ you load ASDF 3 or later,

+yet _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.  '~/.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 _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.  '(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 '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 _strongly_

+recommend that you should instead upgrade your implementation, or

+overwrite the ancient ASDF installation with a more recent one: *Note

+Replacing your implementation's ASDF::.

    The 'asdf:*central-registry*' is empty by default in ASDF 2 or ASDF

 3, but is still supported for compatibility with ASDF 1.  When used, it

 Lisp that you're discussing a directory rather than a file.  If you

 leave it out, ASDF is likely to look in '/home/me/src/' instead of

 '/home/me/src/foo/' as you intended, and fail to find your system

-definition.

+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 '.asd' files, and a common idiom was to

 put _symbolic links_ to all of one's '.asd' files in a common directory

      pathname-specifier := pathname | string | symbol

+     version-specifier := string

+                          | (:read-file-form <pathname-specifier> <form-specifier>?)

+                          | (:read-file-line <pathname-specifier> <line-specifier>?)

+     line-specifier := :at integer # base zero

+     form-specifier := :at [ integer | ( integer+ )]

+

      method-form := (operation-name qual lambda-list &rest body)

      qual := method qualifier?

 can be an expression that is resolved to such a string using the

 following trivial domain-specific language: in addition to being a

 literal string, it can be an expression of the form '(:read-file-form

-<pathname-or-string> :at <access-at-specifier>)', which will be resolved

-by reading a form in the specified pathname (read as a subpathname of

-the current system if relative or a unix-namestring).  You may use a

-'uiop:access-at' specifier with the (optional) ':at' keyword, by default

-the specifier is '0', meaning the first form is returned; subforms can

-also be specified, with e.g.  '(1 2 2)' specifying "the third subform

-(index 2) of the third subform (index 2) of the second form (index 1)"

-in the file (mind the off-by-one error in the English language).

+<pathname-or-string> [:at <access-at-specifier]>)', or '(:read-file-line

+<pathname-or-string> [:at <access-at-specifier]?>)'.  As the name

+suggests, the former will be resolved by reading a form in the specified

+pathname (read as a subpathname of the current system if relative or a

+unix-namestring), and the latter by reading a line.  You may use a

+'uiop:access-at' specifier with the ':at' keyword, by default the

+specifier is '0', meaning the first form/line is returned.  For

+':read-file-form', subforms can also be specified, with e.g.  '(1 2 2)'

+specifying "the third subform (index 2) of the third subform (index 2)

+of the second form (index 1)" in the file (mind the off-by-one error in

+the English language).

    System definers are encouraged to use version identifiers of the form

 X.Y.Z for major version, minor version and patch level, where

 enough (3.1.3.7 or later); it is not enough for a recent ASDF upgrade to

 be present, 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

-'tools/install-asdf.lisp'.

+upgrade the implementation-provided ASDF, *note Replacing your

+implementation's ASDF::.

 File: asdf.info,  Node: Configuration API,  Next: Introspection,  Prev: Caching Results,  Up: Controlling where ASDF searches for systems

      ASDF, and XCL is more of a working demo than something you'd use

      seriously anyway.

-   * 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.

-

-   * Now that all implementations provide ASDF 3.1 or later (since May

-     2016), the simple solution is just to use code as below in your

-     setup, and when it fails, upgrade your implementation or replace

-     its ASDF. (*note Replacing your implementation's ASDF::):

+   * For the above reasons, your build and startup scripts 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.

+

+   * 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.

+     (*note Replacing your implementation's ASDF::):

           (require "asdf")

-          #-asdf3 (error "ASDF 3 or bust")

+          #-asdf3.1 (error "ASDF 3.1 or bust")

    * For scripts that try to use ASDF simply via 'require' at first, and

      make heroic attempts to load it the hard way if at first they don't

    * 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 _twice_.  A first time, right after you load

-     the old ASDF 2 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.

+     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 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.

           (ignore-errors (funcall 'require "asdf")) ;; <--- try real hard

           ;; <--- insert heroics here, if that failed to provide ASDF 2 or 3

           ;; <--- insert configuration here, if that succeeded

 * My Common Lisp implementation comes with an outdated version of ASDF. What to do?::

 * I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::

+* After upgrading ASDF, ASDF (and Quicklisp) can't find my systems: After upgrading ASDF.

 File: asdf.info,  Node: My Common Lisp implementation comes with an outdated version of ASDF. What to do?,  Next: I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?,  Prev: Issues with installing the proper version of ASDF,  Up: Issues with installing the proper version of ASDF

 implementation's ASDF::.

-File: asdf.info,  Node: I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?,  Prev: My Common Lisp implementation comes with an outdated version of ASDF. What to do?,  Up: Issues with installing the proper version of ASDF

+File: asdf.info,  Node: I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?,  Next: After upgrading ASDF,  Prev: My Common Lisp implementation comes with an outdated version of ASDF. What to do?,  Up: Issues with installing the proper version of ASDF

 13.4.2 "I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?"

 -------------------------------------------------------------------------------------

      upgrade to the upstream version.

+File: asdf.info,  Node: After upgrading ASDF,  Prev: I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?,  Up: Issues with installing the proper version of ASDF

+

+13.4.3 After upgrading ASDF, ASDF (and Quicklisp) can't find my systems

+-----------------------------------------------------------------------

+

+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 'asdf:initialize-source-registry' or

+'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,

+*CENTRAL-REGISTRY* is not maintained across upgrades from ASDF 2.  *Note

+note about ASDF reconfiguration after upgrade:

+reinitializeASDFAfterUpgrade.

+

+   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, _then_ configure it, _then_ load

+Quicklisp and any other extension.  Do _not_ try to upgrade from ASDF 2

+_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.

+

+

 File: asdf.info,  Node: Issues with configuring ASDF,  Next: Issues with using and extending ASDF to define systems,  Prev: Issues with installing the proper version of ASDF,  Up: FAQ

 13.5 Issues with configuring ASDF

      ;; Load the test script support.

      (load "script-support.lisp")

-     ;; Initialize the script support.

-     ;; This will also change your *package* to asdf-test.

+     ;; Initialize the script support for interaction.

+     ;; This will also change your *package* to asdf-test

+     ;; after frobbing the asdf-test package to make it usable.

      ;; NB: this function is also available from package cl-user,

      ;; and also available with the shorter name da in both packages.

-     (asdf-test::debug-asdf)

-

-     ;; In case you modified ASDF since you last tested it,

-     ;; you need to update asdf.lisp itself by evaluating 'make' in a shell,

-     ;; or (require "asdf") (asdf:load-system :asdf) in another CL REPL,

-     ;; if not done in this REPL above.

-     ;; *Then*, in this REPL, you need to evaluate:

-     ;(asdf-test::compile-load-asdf)

+     (asdf-test:debug-asdf)

      ;; Now, you may experiment with test code from a .script file.

      ;; See the instructions given at the end of your failing test

      ;; to identify which form is needed, e.g.

-     (frob-packages)

-     (asdf::with-asdf-cache () (load "test-utilities.script"))

+     (run-test-script "test-utilities.script")

 File: asdf.info,  Node: Ongoing Work,  Next: Bibliography,  Prev: FAQ,  Up: Top

 * :asdf2:                                Introduction.        (line   6)

 * :asdf3:                                Introduction.        (line   6)

 * :build-operation:                      The defsystem grammar.

-                                                              (line 128)

+                                                              (line 134)

 * :compile-check:                        Controlling file compilation.

                                                               (line   6)

 * :default-registry source config directive: Configuration DSL.

                                                               (line   6)

 * :defsystem-depends-on:                 The defsystem grammar.

-                                                              (line 120)

+                                                              (line 126)

 * :directory source config directive:    Configuration DSL.   (line   6)

 * :exclude source config directive:      Configuration DSL.   (line   6)

 * :feature dependencies:                 The defsystem grammar.

-                                                              (line 270)

+                                                              (line 279)

 * :if-feature component option:          The defsystem grammar.

-                                                              (line 390)

+                                                              (line 399)

 * :ignore-invalid-entries source config directive: Configuration DSL.

                                                               (line   6)

 * :include source config directive:      Configuration DSL.   (line   6)

 * :inherit-configuration source config directive: Configuration DSL.

                                                               (line   6)

 * :require dependencies:                 The defsystem grammar.

-                                                              (line 260)

+                                                              (line 269)

 * :tree source config directive:         Configuration DSL.   (line   6)

 * :version:                              The defsystem form.  (line  68)

 * :version <1>:                          The defsystem grammar.

-                                                              (line 229)

+                                                              (line 235)

* :version <2>: Common attributes of components.

                                                               (line  23)

 * :weakly-depends-on:                    The defsystem grammar.

-                                                              (line 140)

+                                                              (line 146)

 * also-exclude source config directive:  Configuration DSL.   (line   6)

 * around-compile keyword:                Controlling file compilation.

                                                               (line   6)

 * launchpad:                             Where do I report a bug?.

                                                               (line   6)

 * logical pathnames:                     The defsystem grammar.

-                                                              (line 289)

+                                                              (line 298)

 * mailing list:                          Mailing list.        (line   6)

 * operation:                             Operations.          (line   6)

 * pathname specifiers:                   The defsystem grammar.

-                                                              (line 162)

+                                                              (line 168)

 * Primary system name:                   Components.          (line  70)

+* Quicklisp:                             After upgrading ASDF.

+                                                              (line   6)

 * readtables:                            How do I work with readtables?.

                                                               (line   6)

 * serial dependencies:                   The defsystem grammar.

-                                                              (line 335)

+                                                              (line 344)

 * system:                                Components.          (line   6)

 * system designator:                     Components.          (line   6)

 * System names:                          Components.          (line  70)

 * Testing for ASDF:                      Introduction.        (line   6)

 * tree source config directive:          Configuration DSL.   (line   6)

 * version specifiers:                    The defsystem grammar.

-                                                              (line 229)

+                                                              (line 235)

 File: asdf.info,  Node: Function and Class Index,  Next: Variable Index,  Prev: Concept Index,  Up: Top

Raymond Toy pushed to branch master at cmucl / cmucl

Commits:

4 changed files:

Changes: