/usr/share/doc/cl-asdf/asdf/Loading-ASDF.html

<html lang="en">
<head>
<title>Loading ASDF - ASDF Manual</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="ASDF Manual">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="prev" href="Introduction.html#Introduction" title="Introduction">
<link rel="next" href="Configuring-ASDF.html#Configuring-ASDF" title="Configuring ASDF">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This manual describes ASDF, a system definition facility
for Common Lisp programs and libraries.

You can find the latest version of this manual at
`http://common-lisp.net/project/asdf/asdf.html'.

ASDF Copyright (C) 2001-2011 Daniel Barlow and contributors.

This manual Copyright (C) 2001-2011 Daniel Barlow and contributors.

This manual revised (C) 2009-2011 Robert P. Goldman and Francois-Rene Rideau.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Loading-ASDF"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Configuring-ASDF.html#Configuring-ASDF">Configuring ASDF</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Introduction.html#Introduction">Introduction</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
</div>

<!-- node-name,  next,  previous,  up -->
<h2 class="chapter">2 Loading ASDF</h2>

<p><a name="index-g_t_002acentral_002dregistry_002a-7"></a><a name="index-link-farm-8"></a><a name="index-load_002dsystem-9"></a><a name="index-compile_002dsystem-10"></a><a name="index-test_002dsystem-11"></a><a name="index-system-directory-designator-12"></a><a name="index-operate-13"></a><a name="index-oos-14"></a>
<!-- @menu -->
<!-- * Installing ASDF:: -->
<!-- @end menu -->

<h3 class="section">2.1 Loading a pre-installed ASDF</h3>

<p>Many Lisp implementations include a copy of ASDF. 
You can usually load this copy using Common Lisp's <code>require</code> function:

<pre class="lisp">     (require "asdf")
</pre>
   <p>As of the writing of this manual,
the following implementations provide ASDF 2 this way:
abcl allegro ccl clisp cmucl ecl sbcl xcl. 
The following implementations don't provide it yet but will in a future release:
lispworks scl. 
The following implementations are obsolete and most probably will never bundle it:
cormancl gcl genera mcl.

   <p>If the implementation you are using doesn't provide ASDF 2,
see see <a href="Loading-ASDF.html#Loading-ASDF">Loading an otherwise installed ASDF</a> below. 
If that implementation is still actively maintained,
you may also send a bug report to your Lisp vendor and complain
about their failing to provide ASDF.

   <p>NB: all implementations except clisp also accept
<code>(require "ASDF")</code>, <code>(require 'asdf)</code> and <code>(require :asdf)</code>. 
For portability's sake, you probably want to use <code>(require "asdf")</code>.

<h3 class="section">2.2 Checking whether ASDF is loaded</h3>

<p>To check whether ASDF is properly loaded in your current Lisp image,
you can run this form:

<pre class="lisp">     (asdf:asdf-version)
</pre>
   <p>If it returns a string,
that is the version of ASDF that is currently installed.

   <p>If it raises an error,
then either ASDF is not loaded, or
you are using an old version of ASDF.

   <p>You can check whether an old version is loaded
by checking if the ASDF package is present. 
The form below will allow you to programmatically determine
whether a recent version is loaded, an old version is loaded,
or none at all:

<pre class="lisp">     (or #+asdf2 (asdf:asdf-version) #+asdf :old)
</pre>
   <p>If it returns a version number, that's the version of ASDF installed. 
If it returns the keyword <code>:OLD</code>,
then you're using an old version of ASDF (from before 1.635). 
If it returns <code>NIL</code> then ASDF is not installed.

   <p>If you are experiencing problems with ASDF,
please try upgrading to the latest released version,
using the method below,
before you contact us and raise an issue.

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

<p>If your implementation does provide ASDF 2 or later,
and you want to upgrade to a more recent version,
just install ASDF like any other package
(see see <a href="Loading-ASDF.html#Loading-ASDF">Loading an otherwise installed ASDF</a> below),
configure ASDF as usual (see see <a href="Configuring-ASDF.html#Configuring-ASDF">Configuring ASDF</a> below),
and upgrade with:

<pre class="lisp">     (require "asdf")
     (asdf:load-system :asdf)
</pre>
   <p>If on the other hand, your implementation only provides an old ASDF,
you will require a special configuration step and an old-style loading:

<pre class="lisp">     (require "asdf")
     (push #p"<var>/path/to/new/asdf/</var>" asdf:*central-registry*)
     (asdf:oos 'asdf:load-op :asdf)
</pre>
   <p>Don't forget the trailing <code>/</code> at the end of your pathname.

   <p>Also, note that older versions of ASDF won't redirect their output,
or at least won't do it according to your usual ASDF 2 configuration. 
You therefore need write access on the directory
where you install the new ASDF,
and make sure you're not using it
for multiple mutually incompatible implementations. 
At worst, you may have to have multiple copies of the new ASDF,
e.g. one per implementation installation, to avoid clashes. 
Note that to our knowledge all implementations that provide ASDF
provide ASDF 2 in their latest release, so
you may want to upgrade your implementation rather than go through that hoop.

   <p>Finally, note that there are some limitations to upgrading ASDF:
     <ul>
<li>Any ASDF extension becomes invalid, and will need to be reloaded. 
This applies to e.g. CFFI-Grovel, or to hacks used by ironclad, etc. 
Starting with ASDF 2.014.8, ASDF will actually invalidate
all previously loaded systems when it is loaded on top of
a different ASDF version. 
<li>Until all implementations provide ASDF 2.015 or later,
it is safer if you upgrade ASDF and its extensions as a special step
at the very beginning of whatever script you are running,
before you start using ASDF to load anything else. 
<li>Until all implementations provide ASDF 2.015 or later,
it is unsafe to upgrade ASDF as part of loading a system
that depends on a more recent version of ASDF,
since the new one might shadow the old one while the old one is running,
and the running old one will be confused
when extensions are loaded into the new one. 
In the meantime, we recommend that your systems should <em>not</em> specify
<code>:depends-on (:asdf)</code>, or <code>:depends-on ((:version :asdf "2.010"))</code>,
but instead that they check that a recent enough ASDF is installed,
with such code as:
     <pre class="example">          (unless (or #+asdf2 (asdf:version-satisfies
                               (asdf:asdf-version) *required-asdf-version*))
            (error "FOO requires ASDF ~A or later." *required-asdf-version*))
</pre>
     </ul>

<h3 class="section">2.4 Loading an otherwise installed ASDF</h3>

<p>If your implementation doesn't include ASDF,
if for some reason the upgrade somehow fails,
does not or cannot apply to your case,
you will have to install the file <samp><span class="file">asdf.lisp</span></samp>
somewhere and load it with:

<pre class="lisp">     (load "/path/to/your/installed/asdf.lisp")
</pre>
   <p>The single file <samp><span class="file">asdf.lisp</span></samp> is all you normally need to use ASDF.

   <p>You can extract this file from latest release tarball on the
<a href="http://common-lisp.net/project/asdf/">ASDF website</a>. 
If you are daring and willing to report bugs, you can get
the latest and greatest version of ASDF from its git repository. 
See <a href="Getting-the-latest-version.html#Getting-the-latest-version">Getting the latest version</a>.

   <p>For maximum convenience you might want to have ASDF loaded
whenever you start your Lisp implementation,
for example by loading it from the startup script or dumping a custom core
&mdash; check your Lisp implementation's manual for details.

   </body></html>
cl-asdf 2:2.20-1 / usr / share / doc / cl-asdf / asdf / Loading-ASDF.html
