/usr/share/doc/cl-asdf/asdf/FAQ.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- 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-2013 Daniel Barlow and contributors.

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

This manual revised (C) 2009-2013 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.
 -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>ASDF Manual: FAQ</title>

<meta name="description" content="ASDF Manual: FAQ">
<meta name="keywords" content="ASDF Manual: FAQ">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="TODO-list.html#TODO-list" rel="next" title="TODO list">
<link href="Getting-the-latest-version.html#Getting-the-latest-version" rel="previous" title="Getting the latest version">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="FAQ"></a>
<div class="header">
<p>
Next: <a href="TODO-list.html#TODO-list" accesskey="n" rel="next">TODO list</a>, Previous: <a href="Getting-the-latest-version.html#Getting-the-latest-version" accesskey="p" rel="previous">Getting the latest version</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="FAQ-1"></a>
<h2 class="chapter">12 FAQ</h2>

<a name="g_t_0060_0060Where-do-I-report-a-bug_003f_0027_0027"></a>
<h3 class="section">12.1 &ldquo;Where do I report a bug?&rdquo;</h3>

<p>ASDF bugs are tracked on launchpad: <a href="https://launchpad.net/asdf">https://launchpad.net/asdf</a>.
</p>
<p>If you&rsquo;re unsure about whether something is a bug, or for general discussion,
use the <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel">asdf-devel mailing list</a>
</p>

<a name="g_t_0060_0060What-has-changed-between-ASDF-1-and-ASDF-2_003f_0027_0027"></a>
<h3 class="section">12.2 &ldquo;What has changed between ASDF 1 and ASDF 2?&rdquo;</h3>

<a name="What-are-ASDF-1-and-ASDF-2_003f"></a>
<h4 class="subsection">12.2.1 What are ASDF 1 and ASDF 2?</h4>

<p>On May 31st 2010, we have released ASDF 2.
ASDF 2 refers to release 2.000 and later.
(Releases between 1.656 and 1.728 were development releases for ASDF 2.)
ASDF 1 to any release earlier than 1.369 or so.
If your ASDF doesn&rsquo;t sport a version, it&rsquo;s an old ASDF 1.
</p>
<p>ASDF 2 and its release candidates push
<code>:asdf2</code> onto <code>*features*</code> so that if you are writing
ASDF-dependent code you may check for this feature
to see if the new API is present.
<em>All</em> versions of ASDF should have the <code>:asdf</code> feature.
</p>
<p>Additionally, all versions of ASDF 2
define a function <code>(asdf:asdf-version)</code> you may use to query the version;
and the source code of recent versions of ASDF 2 features the version number
prominently on the second line of its source code.
</p>
<p>If you are experiencing problems or limitations of any sort with ASDF 1,
we recommend that you should upgrade to ASDF 2,
or whatever is the latest release.
</p>

<a name="ASDF-can-portably-name-files-in-subdirectories"></a>
<h4 class="subsection">12.2.2 ASDF can portably name files in subdirectories</h4>

<p>Common Lisp namestrings are not portable,
except maybe for logical pathnamestrings,
that themselves have various limitations and require a lot of setup
that is itself ultimately non-portable.
</p>
<p>In ASDF 1, the only portable ways to refer to pathnames inside systems and components
were very awkward, using <code>#.(make-pathname ...)</code> and
<code>#.(merge-pathnames ...)</code>.
Even the above were themselves were inadequate in the general case
due to host and device issues, unless horribly complex patterns were used.
Plenty of simple cases that looked portable actually weren&rsquo;t,
leading to much confusion and greavance.
</p>
<p>ASDF 2 implements its own portable syntax for strings as pathname specifiers.
Naming files within a system definition becomes easy and portable again.
See <a href="Miscellaneous-additional-functionality.html#Miscellaneous-additional-functionality">asdf:system-relative-pathname</a>,
<code>merge-pathnames*</code>,
<code>coerce-pathname</code>.
</p>
<p>On the other hand, there are places where systems used to accept namestrings
where you must now use an explicit pathname object:
<code>(defsystem ... :pathname &quot;LOGICAL-HOST:PATH;TO;SYSTEM;&quot; ...)</code>
must now be written with the <code>#p</code> syntax:
<code>(defsystem ... :pathname #p&quot;LOGICAL-HOST:PATH;TO;SYSTEM;&quot; ...)</code>
</p>
<p>See <a href="The-defsystem-grammar.html#The-defsystem-grammar">Pathname specifiers</a>.
</p>

<a name="Output-translations"></a>
<h4 class="subsection">12.2.3 Output translations</h4>

<p>A popular feature added to ASDF was output pathname translation:
<code>asdf-binary-locations</code>, <code>common-lisp-controller</code>,
<code>cl-launch</code> and other hacks were all implementing it in ways
both mutually incompatible and difficult to configure.
</p>
<p>Output pathname translation is essential to share
source directories of portable systems across multiple implementations
or variants thereof,
or source directories of shared installations of systems across multiple users,
or combinations of the above.
</p>
<p>In ASDF 2, a standard mechanism is provided for that,
<code>asdf-output-translations</code>,
with sensible defaults, adequate configuration languages,
a coherent set of configuration files and hooks,
and support for non-Unix platforms.
</p>
<p>See <a href="Controlling-where-ASDF-saves-compiled-files.html#Controlling-where-ASDF-saves-compiled-files">Controlling where ASDF saves compiled files</a>.
</p>
<a name="Source-Registry-Configuration"></a>
<h4 class="subsection">12.2.4 Source Registry Configuration</h4>

<p>Configuring ASDF used to require special magic
to be applied just at the right moment,
between the moment ASDF is loaded and the moment it is used,
in a way that is specific to the user,
the implementation he is using and the application he is building.
</p>
<p>This made for awkward configuration files and startup scripts
that could not be shared between users, managed by administrators
or packaged by distributions.
</p>
<p>ASDF 2 provides a well-documented way to configure ASDF,
with sensible defaults, adequate configuration languages,
and a coherent set of configuration files and hooks.
</p>
<p>We believe it&rsquo;s a vast improvement because it decouples
application distribution from library distribution.
The application writer can avoid thinking where the libraries are,
and the library distributor (dpkg, clbuild, advanced user, etc.)
can configure them once and for every application.
Yet settings can be easily overridden where needed,
so whoever needs control has exactly as much as required.
</p>
<p>At the same time, ASDF 2 remains compatible
with the old magic you may have in your build scripts
(using <code>*central-registry*</code> and
<code>*system-definition-search-functions*</code>)
to tailor the ASDF configuration to your build automation needs,
and also allows for new magic, simpler and more powerful magic.
</p>
<p>See <a href="Controlling-where-ASDF-searches-for-systems.html#Controlling-where-ASDF-searches-for-systems">Controlling where ASDF searches for systems</a>.
</p>

<a name="Usual-operations-are-made-easier-to-the-user"></a>
<h4 class="subsection">12.2.5 Usual operations are made easier to the user</h4>

<p>In ASDF 1, you had to use the awkward syntax
<code>(asdf:oos 'asdf:load-op :foo)</code>
to load a system,
and similarly for <code>compile-op</code>, <code>test-op</code>.
</p>
<p>In ASDF 2, you can use shortcuts for the usual operations:
<code>(asdf:load-system :foo)</code>, and
similarly for <code>compile-system</code>, <code>test-system</code>.
</p>

<a name="Many-bugs-have-been-fixed"></a>
<h4 class="subsection">12.2.6 Many bugs have been fixed</h4>

<p>The following issues and many others have been fixed:
</p>
<ul>
<li> The infamous TRAVERSE function has been revamped completely
between ASDF 1 and ASDF 2, with many bugs squashed.
In particular, dependencies were not correctly propagated
across modules but now are.
It has been completely rewritten many times over
between ASDF 2.000 and ASDF 3,
with fundamental issues in the original model being fixed.
Timestamps were not propagated at all, and now are.
The internal model of how actions depend on each other
is now both consistent and complete.
The :version and
the :force (system1 .. systemN) feature have been fixed.

</li><li> Performance has been notably improved for large systems
(say with thousands of components) by using
hash-tables instead of linear search,
and linear-time list accumulation
instead of quadratic-time recursive appends.

</li><li> Many features used to not be portable,
especially where pathnames were involved.
Windows support was notably quirky because of such non-portability.

</li><li> The internal test suite used to massively fail on many implementations.
While still incomplete, it now fully passes
on all implementations supported by the test suite,
except for GCL (due to GCL bugs).

</li><li> Support was lacking for some implementations.
ABCL and GCL were notably wholly broken.
ECL extensions were not integrated with ASDF release.

</li><li> The documentation was grossly out of date.

</li></ul>


<a name="ASDF-itself-is-versioned"></a>
<h4 class="subsection">12.2.7 ASDF itself is versioned</h4>

<p>Between new features, old bugs fixed, and new bugs introduced,
there were various releases of ASDF in the wild,
and no simple way to check which release had which feature set.
People using or writing systems had to either make worst-case assumptions
as to what features were available and worked,
or take great pains to have the correct version of ASDF installed.
</p>
<p>With ASDF 2, we provide a new stable set of working features
that everyone can rely on from now on.
Use <code>#+asdf2</code> to detect presence of ASDF 2,
<code>(asdf:version-satisfies (asdf:asdf-version) &quot;2.345.67&quot;)</code>
to check the availability of a version no earlier than required.
</p>

<a name="ASDF-can-be-upgraded"></a>
<h4 class="subsection">12.2.8 ASDF can be upgraded</h4>

<p>When an old version of ASDF was loaded,
it was very hard to upgrade ASDF in your current image
without breaking everything.
Instead you had to exit the Lisp process and
somehow arrange to start a new one from a simpler image.
Something that can&rsquo;t be done from within Lisp,
making automation of it difficult,
which compounded with difficulty in configuration,
made the task quite hard.
Yet as we saw before, the task would have been required
to not have to live with the worst case or non-portable
subset of ASDF features.
</p>
<p>With ASDF 2, it is easy to upgrade
from ASDF 2 to later versions from within Lisp,
and not too hard to upgrade from ASDF 1 to ASDF 2 from within Lisp.
We support hot upgrade of ASDF and any breakage is a bug
that we will do our best to fix.
There are still limitations on upgrade, though,
most notably the fact that after you upgrade ASDF,
you must also reload or upgrade all ASDF extensions.
</p>
<a name="Decoupled-release-cycle"></a>
<h4 class="subsection">12.2.9 Decoupled release cycle</h4>

<p>When vendors were releasing their Lisp implementations with ASDF,
they had to basically never change version
because neither upgrade nor downgrade was possible
without breaking something for someone,
and no obvious upgrade path was visible and recommendable.
</p>
<p>With ASDF 2, upgrade is possible, easy and can be recommended.
This means that vendors can safely ship a recent version of ASDF,
confident that if a user isn&rsquo;t fully satisfied,
he can easily upgrade ASDF and deal
with a supported recent version of it.
This means that release cycles will be causally decoupled,
the practical consequence of which will mean faster convergence
towards the latest version for everyone.
</p>

<a name="Pitfalls-of-the-transition-to-ASDF-2"></a>
<h4 class="subsection">12.2.10 Pitfalls of the transition to ASDF 2</h4>

<p>The main pitfalls in upgrading to ASDF 2 seem to be related
to the output translation mechanism.
</p>
<ul>
<li> Output translations is enabled by default. This may surprise some users,
most of them in pleasant way (we hope), a few of them in an unpleasant way.
It is trivial to disable output translations.
See <a href="#FAQ">&ldquo;How can I wholly disable the compiler output cache?&rdquo;</a>.

</li><li> Some systems in the large have been known
not to play well with output translations.
They were relatively easy to fix.
Once again, it is also easy to disable output translations,
or to override its configuration.

</li><li> The new ASDF output translations are incompatible with ASDF-Binary-Locations.
They replace A-B-L, and there is compatibility mode to emulate
your previous A-B-L configuration.
See <code>enable-asdf-binary-locations-compatibility</code> in
see <a href="Controlling-where-ASDF-saves-compiled-files.html#Controlling-where-ASDF-saves-compiled-files">Backward Compatibility</a>.
But thou shalt not load ABL on top of ASDF 2.

</li></ul>

<p>Other issues include the following:
</p>
<ul>
<li> ASDF pathname designators are now specified
in places where they were unspecified,
and a few small adjustments have to be made to some non-portable defsystems.
Notably, in the <code>:pathname</code> argument
to a <code>defsystem</code> and its components,
a logical pathname (or implementation-dependent hierarchical pathname)
must now be specified with <code>#p</code> syntax
where the namestring might have previously sufficed;
moreover when evaluation is desired <code>#.</code> must be used,
where it wasn&rsquo;t necessary in the toplevel <code>:pathname</code> argument
(but necessary in other <code>:pathname</code> arguments).

</li><li> There is a slight performance bug, notably on SBCL,
when initially searching for <samp>asd</samp> files,
the implicit <code>(directory &quot;/configured/path/**/*.asd&quot;)</code>
for every configured path <code>(:tree &quot;/configured/path/&quot;)</code>
in your <code>source-registry</code> configuration can cause a slight pause.
Try to <code>(time (asdf:initialize-source-registry))</code>
to see how bad it is or isn&rsquo;t on your system.
If you insist on not having this pause,
you can avoid the pause by overriding the default source-registry configuration
and not use any deep <code>:tree</code> entry but only <code>:directory</code> entries
or shallow <code>:tree</code> entries.
Or you can fix your implementation to not be quite that slow
when recursing through directories.
<em>Update</em>: This performance bug fixed the hard way in 2.010.

</li><li> On Windows, only LispWorks supports proper default configuration pathnames
based on the Windows registry.
Other implementations make do with environment variables,
that you may have to define yourself
if you&rsquo;re using an older version of Windows.
Windows support is somewhat less tested than Unix support.
Please help report and fix bugs.
<em>Update</em>: As of ASDF 2.21, all implementations
should now use the same proper default configuration pathnames
and they should actually work, though they haven&rsquo;t all been tested.

</li><li> The mechanism by which one customizes a system so that Lisp files
may use a different extension from the default <samp>.lisp</samp> has changed.
Previously, the pathname for a component
was lazily computed when operating on a system,
and you would
<code>(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
  (declare (ignorable component system)) &quot;lis&quot;)</code>.
Now, the pathname for a component is eagerly computed when defining the system,
and instead you will <code>(defclass cl-source-file.lis (cl-source-file) ((type :initform &quot;lis&quot;)))</code>
and use <code>:default-component-class cl-source-file.lis</code>
as argument to <code>defsystem</code>,
as detailed in a see <a href="#FAQ">How do I create a system definition where all the source files have a .cl extension?</a> below.

<a name="index-source_002dfile_002dtype"></a>


</li></ul>


<a name="Issues-with-installing-the-proper-version-of-ASDF"></a>
<h3 class="section">12.3 Issues with installing the proper version of ASDF</h3>

<a name="g_t_0060_0060My-Common-Lisp-implementation-comes-with-an-outdated-version-of-ASDF_002e-What-to-do_003f_0027_0027"></a>
<h4 class="subsection">12.3.1 &ldquo;My Common Lisp implementation comes with an outdated version of ASDF. What to do?&rdquo;</h4>

<p>We recommend you upgrade ASDF.
See <a href="Loading-ASDF.html#Loading-ASDF">Upgrading ASDF</a>.
</p>
<p>If this does not work, it is a bug, and you should report it.
See <a href="#FAQ">Where do I report a bug</a>.
In the meantime, you can load <samp>asdf.lisp</samp> directly.
See <a href="Loading-ASDF.html#Loading-ASDF">Loading an otherwise installed ASDF</a>.
</p>

<a name="g_t_0060_0060I_0027m-a-Common-Lisp-implementation-vendor_002e-When-and-how-should-I-upgrade-ASDF_003f_0027_0027"></a>
<h4 class="subsection">12.3.2 &ldquo;I&rsquo;m a Common Lisp implementation vendor. When and how should I upgrade ASDF?&rdquo;</h4>

<p>Since ASDF 2,
it should always be a good time to upgrade to a recent version of ASDF.
You may consult with the maintainer for which specific version they recommend,
but the latest <code>release</code> should be correct.
We trust you to thoroughly test it with your implementation
before you release it.
If there are any issues with the current release,
it&rsquo;s a bug that you should report upstream and that we will fix ASAP.
</p>
<p>As to how to include ASDF, we recommend the following:
</p>
<ul>
<li> If ASDF isn&rsquo;t loaded yet, then <code>(require &quot;asdf&quot;)</code>
should load the version of ASDF that is bundled with your system.
If possible so should <code>(require &quot;ASDF&quot;)</code>.
You may have it load some other version configured by the user,
if you allow such configuration.

</li><li> If your system provides a mechanism to hook into <code>CL:REQUIRE</code>,
then it would be nice to add ASDF to this hook the same way that
ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it.
Please send us appropriate code to this end.

</li><li> You may, like SBCL, have ASDF be implicitly used to require systems
that are bundled with your Lisp distribution.
If you do have a few magic systems that come with your implementation
in a precompiled way such that one should only use the binary version
that goes with your distribution, like SBCL does,
then you should add them in the beginning of <code>wrapping-source-registry</code>.

</li><li> If you have magic systems as above, like SBCL does,
then we explicitly ask you to <em>NOT</em> distribute
<samp>asdf.asd</samp> as part of those magic systems.
You should still include the file <samp>asdf.lisp</samp> in your source distribution
and precompile it in your binary distribution,
but <samp>asdf.asd</samp> if included at all,
should be secluded from the magic systems,
in a separate file hierarchy.
Alternatively, you may provide the system
after renaming it and its <samp>.asd</samp> file to e.g.
<code>asdf-ecl</code> and <samp>asdf-ecl.asd</samp>, or
<code>sb-asdf</code> and <samp>sb-asdf.asd</samp>.
Indeed, if you made <samp>asdf.asd</samp> a magic system,
then users would no longer be able to upgrade ASDF using ASDF itself
to some version of their preference that
they maintain independently from your Lisp distribution.

</li><li> If you do not have any such magic systems, or have other non-magic systems
that you want to bundle with your implementation,
then you may add them to the <code>wrapping-source-registry</code>,
and you are welcome to include <samp>asdf.asd</samp> amongst them.
Non-magic systems should be at the back of the <code>wrapping-source-registry</code>
while magic systems are at the front.

</li><li> Please send us upstream any patches you make to ASDF itself,
so we can merge them back in for the benefit of your users
when they upgrade to the upstream version.

</li></ul>



<a name="Issues-with-configuring-ASDF"></a>
<h3 class="section">12.4 Issues with configuring ASDF</h3>

<a name="g_t_0060_0060How-can-I-customize-where-fasl-files-are-stored_003f_0027_0027"></a>
<h4 class="subsection">12.4.1 &ldquo;How can I customize where fasl files are stored?&rdquo;</h4>

<p>See <a href="Controlling-where-ASDF-saves-compiled-files.html#Controlling-where-ASDF-saves-compiled-files">Controlling where ASDF saves compiled files</a>.
</p>
<p>Note that in the past there was an add-on to ASDF called
<code>ASDF-binary-locations</code>, developed by Gary King.
That add-on has been merged into ASDF proper,
then superseded by the <code>asdf-output-translations</code> facility.
</p>
<p>Note that use of <code>asdf-output-translations</code>
can interfere with one aspect of your systems
&mdash; if your system uses <code>*load-truename*</code> to find files
(e.g., if you have some data files stored with your program),
then the relocation that this ASDF customization performs
is likely to interfere.
Use <code>asdf:system-relative-pathname</code> to locate a file
in the source directory of some system, and
use <code>asdf:apply-output-translations</code> to locate a file
whose pathname has been translated by the facility.
</p>
<a name="g_t_0060_0060How-can-I-wholly-disable-the-compiler-output-cache_003f_0027_0027"></a>
<h4 class="subsection">12.4.2 &ldquo;How can I wholly disable the compiler output cache?&rdquo;</h4>

<p>To permanently disable the compiler output cache
for all future runs of ASDF, you can:
</p>
<div class="example">
<pre class="example">mkdir -p ~/.config/common-lisp/asdf-output-translations.conf.d/
echo ':disable-cache' &gt; ~/.config/common-lisp/asdf-output-translations.conf.d/99-disable-cache.conf
</pre></div>

<p>This assumes that you didn&rsquo;t otherwise configure the ASDF files
(if you did, edit them again),
and don&rsquo;t somehow override the configuration at runtime
with a shell variable (see below) or some other runtime command
(e.g. some call to <code>asdf:initialize-output-translations</code>).
</p>
<p>To disable the compiler output cache in Lisp processes
run by your current shell, try (assuming <code>bash</code> or <code>zsh</code>)
(on Unix and cygwin only):
</p>
<div class="example">
<pre class="example">export ASDF_OUTPUT_TRANSLATIONS=/:
</pre></div>

<p>To disable the compiler output cache just in the current Lisp process,
use (after loading ASDF but before using it):
</p>
<div class="example">
<pre class="example">(asdf:disable-output-translations)
</pre></div>

<a name="Issues-with-using-and-extending-ASDF-to-define-systems"></a>
<h3 class="section">12.5 Issues with using and extending ASDF to define systems</h3>

<a name="g_t_0060_0060How-can-I-cater-for-unit_002dtesting-in-my-system_003f_0027_0027"></a>
<h4 class="subsection">12.5.1 &ldquo;How can I cater for unit-testing in my system?&rdquo;</h4>

<p>ASDF provides a predefined test operation, <code>test-op</code>.
See <a href="Predefined-operations-of-ASDF.html#Predefined-operations-of-ASDF">test-op</a>.
The test operation, however, is largely left to the system definer to specify.
<code>test-op</code> has been
a topic of considerable discussion on the
<a href="http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel">asdf-devel mailing list</a>,
and on the
<a href="https://launchpad.net/asdf">launchpad bug-tracker</a>.
</p>
<p>Here are some guidelines:
</p>
<ul>
<li> For a given system, <var>foo</var>, you will want to define a corresponding
test system, such as <var>foo-test</var>.  The reason that you will want this
separate system is that ASDF does not out of the box supply components
that are conditionally loaded.  So if you want to have source files
(with the test definitions) that will not be loaded except when testing,
they should be put elsewhere.

</li><li> The <var>foo-test</var> system can be defined in an asd file of its own or
together with <var>foo</var>.  An aesthetic preference against cluttering up
the filesystem with extra asd files should be balanced against the
question of whether one might want to directly load <var>foo-test</var>.
Typically one would not want to do this except in early stages of
debugging.

</li><li> Record that testing is implemented by <var>foo-test</var>.  For example:
<div class="example">
<pre class="example">(defsystem <var>foo</var>
   :in-order-to ((test-op (test-op <var>foo-test</var>)))
   ....)

(defsystem <var>foo-test</var>
   :depends-on (<var>foo</var> <var>my-test-library</var> ...)
   ....)
</pre></div>
</li></ul>

<p>This procedure will allow you to support users who do not wish to
install your test framework.
</p>
<p>One oddity of ASDF is that <code>operate</code> (see <a href="Operations.html#Operations">operate</a>)
does not return a value.  So in current versions of ASDF there is no
reliable programmatic means of determining whether or not a set of tests
has passed, or which tests have failed.  The user must simply read the
console output.  This limitation has been the subject of much
discussion.
</p>
<a name="g_t_0060_0060How-can-I-cater-for-documentation-generation-in-my-system_003f_0027_0027"></a>
<h4 class="subsection">12.5.2 &ldquo;How can I cater for documentation generation in my system?&rdquo;</h4>

<p>The ASDF developers are currently working to add a <code>doc-op</code>
to the set of predefined ASDF operations.
See <a href="Predefined-operations-of-ASDF.html#Predefined-operations-of-ASDF">Predefined operations of ASDF</a>.
See also <a href="https://bugs.launchpad.net/asdf/+bug/479470">https://bugs.launchpad.net/asdf/+bug/479470</a>.
</p>


<a name="g_t_0060_0060How-can-I-maintain-non_002dLisp-_0028e_002eg_002e-C_0029-source-files_003f_0027_0027"></a>
<h4 class="subsection">12.5.3 &ldquo;How can I maintain non-Lisp (e.g. C) source files?&rdquo;</h4>

<p>See <code>cffi</code>&rsquo;s <code>cffi-grovel</code>.
</p>
<a name="report_002dbugs"></a>

<a name="g_t_0060_0060I-want-to-put-my-module_0027s-files-at-the-top-level_002e-How-do-I-do-this_003f_0027_0027"></a>
<h4 class="subsection">12.5.4 &ldquo;I want to put my module&rsquo;s files at the top level.  How do I do this?&rdquo;</h4>

<p>By default, the files contained in an asdf module go
in a subdirectory with the same name as the module.
However, this can be overridden by adding a <code>:pathname &quot;&quot;</code> argument
to the module description.
For example, here is how it could be done
in the spatial-trees ASDF system definition for ASDF 2:
</p>
<div class="example">
<pre class="example">(asdf:defsystem :spatial-trees
  :components
  ((:module base
            :pathname &quot;&quot;
            :components
            ((:file &quot;package&quot;)
             (:file &quot;basedefs&quot; :depends-on (&quot;package&quot;))
             (:file &quot;rectangles&quot; :depends-on (&quot;package&quot;))))
   (:module tree-impls
            :depends-on (base)
            :pathname &quot;&quot;
            :components
            ((:file &quot;r-trees&quot;)
             (:file &quot;greene-trees&quot; :depends-on (&quot;r-trees&quot;))
             (:file &quot;rstar-trees&quot; :depends-on (&quot;r-trees&quot;))
             (:file &quot;rplus-trees&quot; :depends-on (&quot;r-trees&quot;))
             (:file &quot;x-trees&quot; :depends-on (&quot;r-trees&quot; &quot;rstar-trees&quot;))))
   (:module viz
            :depends-on (base)
            :pathname &quot;&quot;
            :components
            ((:static-file &quot;spatial-tree-viz.lisp&quot;)))
   (:module tests
            :depends-on (base)
            :pathname &quot;&quot;
            :components
            ((:static-file &quot;spatial-tree-test.lisp&quot;)))
   (:static-file &quot;LICENCE&quot;)
   (:static-file &quot;TODO&quot;)))
</pre></div>

<p>All of the files in the <code>tree-impls</code> module are at the top level,
instead of in a <samp>tree-impls/</samp> subdirectory.
</p>
<p>Note that the argument to <code>:pathname</code> can be either a pathname object or a string.
A pathname object can be constructed with the <samp>#p&quot;foo/bar/&quot;</samp> syntax,
but this is discouraged because the results of parsing a namestring are not portable.
A pathname can only be portably constructed with such syntax as
<code>#.(make-pathname :directory '(:relative &quot;foo&quot; &quot;bar&quot;))</code>,
and similarly the current directory can only be portably specified as
<code>#.(make-pathname :directory '(:relative))</code>.
However, as of ASDF 2, you can portably use a string to denote a pathname.
The string will be parsed as a <code>/</code>-separated path from the current directory,
such that the empty string <code>&quot;&quot;</code> denotes the current directory, and
<code>&quot;foo/bar&quot;</code> (no trailing <code>/</code> required in the case of modules)
portably denotes the same subdirectory as above.
When files are specified, the last <code>/</code>-separated component is interpreted
either as the name component of a pathname
(if the component class specifies a pathname type),
or as a name component plus optional dot-separated type component
(if the component class doesn&rsquo;t specifies a pathname type).
</p>
<a name="How-do-I-create-a-system-definition-where-all-the-source-files-have-a-_002ecl-extension_003f"></a>
<h4 class="subsection">12.5.5 How do I create a system definition where all the source files have a .cl extension?</h4>

<p>Starting with ASDF 2.014.14, you may just pass
the builtin class <code>cl-source-file.cl</code> as
the <code>:default-component-class</code> argument to <code>defsystem</code>:
</p>
<div class="lisp">
<pre class="lisp">(defsystem my-cl-system
  :default-component-class cl-source-file.cl
  ...)
</pre></div>

<p>Another builtin class <code>cl-source-file.lsp</code> is offered
for files ending in <samp>.lsp</samp>.
</p>
<p>If you want to use a different extension
for which ASDF doesn&rsquo;t provide builtin support,
or want to support versions of ASDF
earlier than 2.014.14 (but later than 2.000),
you can define a class as follows:
</p>
<div class="lisp">
<pre class="lisp">;; Prologue: make sure we're using a sane package.
(defpackage :my-asdf-extension
   (:use :asdf :common-lisp)
   (:export #:cl-source-file.lis))
(in-package :my-asdf-extension)

(defclass cl-source-file.lis (cl-source-file)
  ((type :initform &quot;lis&quot;)))
</pre></div>

<p>Then you can use it as follows:
</p><div class="lisp">
<pre class="lisp">(defsystem my-cl-system
  :default-component-class my-asdf-extension:cl-source-file.lis
  ...)
</pre></div>

<p>Of course, if you&rsquo;re in the same package, e.g. in the same file,
you won&rsquo;t need to use the package qualifier before <code>cl-source-file.lis</code>.
Actually, if all you&rsquo;re doing is defining this class
and using it in the same file without other fancy definitions,
you might skip package complications:
</p>
<div class="lisp">
<pre class="lisp">(in-package :asdf)
(defclass cl-source-file.lis (cl-source-file)
   ((type :initform &quot;lis&quot;)))
(defsystem my-cl-system
  :default-component-class cl-source-file.lis
  ...)
</pre></div>

<p>It is possible to achieve the same effect
in a way that supports both ASDF 1 and ASDF 2,
but really, friends don&rsquo;t let friends use ASDF 1.
Please upgrade to ASDF 3.
In short, though: do same as above, but
<em>before</em> you use the class in a <code>defsystem</code>,
you also define the following method:
</p>
<div class="lisp">
<pre class="lisp">(defmethod source-file-type ((f cl-source-file.lis) (s system))
  (declare (ignorable f s))
  &quot;lis&quot;)
</pre></div>



<hr>
<div class="header">
<p>
Next: <a href="TODO-list.html#TODO-list" accesskey="n" rel="next">TODO list</a>, Previous: <a href="Getting-the-latest-version.html#Getting-the-latest-version" accesskey="p" rel="previous">Getting the latest version</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
cl-asdf 2:3.0.3-1 / usr / share / doc / cl-asdf / asdf / FAQ.html
