217 lines
11 KiB
HTML
217 lines
11 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<!-- This manual describes ASDF, a system definition facility
|
|
for Common Lisp programs and libraries.
|
|
|
|
You can find the latest version of this manual at
|
|
https://common-lisp.net/project/asdf/asdf.html.
|
|
|
|
ASDF Copyright (C) 2001-2019 Daniel Barlow and contributors.
|
|
|
|
This manual Copyright (C) 2001-2019 Daniel Barlow and contributors.
|
|
|
|
This manual revised (C) 2009-2019 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.
|
|
-->
|
|
<title>Convenience Functions (ASDF Manual)</title>
|
|
|
|
<meta name="description" content="Convenience Functions (ASDF Manual)">
|
|
<meta name="keywords" content="Convenience Functions (ASDF Manual)">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<link href="index.html" rel="start" title="Top">
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="Using-ASDF.html" rel="up" title="Using ASDF">
|
|
<link href="Moving-on.html" rel="next" title="Moving on">
|
|
<link href="Loading-a-system.html" rel="prev" title="Loading a system">
|
|
<style type="text/css">
|
|
<!--
|
|
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {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}
|
|
span.nolinebreak {white-space: nowrap}
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
span:hover a.copiable-anchor {visibility: visible}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<div class="section" id="Convenience-Functions">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Moving-on.html" accesskey="n" rel="next">Moving on</a>, Previous: <a href="Loading-a-system.html" accesskey="p" rel="prev">Loading a system</a>, Up: <a href="Using-ASDF.html" accesskey="u" rel="up">Using ASDF</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<span id="Convenience-Functions-1"></span><h3 class="section">5.2 Convenience Functions</h3>
|
|
|
|
|
|
<p>ASDF provides three commands for the most common system operations:
|
|
<code>load-system</code>, <code>compile-system</code>, and <code>test-system</code>.
|
|
</p>
|
|
<p>ASDF also provides <code>require-system</code>, a variant of <code>load-system</code>
|
|
that skips loading systems that are already loaded. This is sometimes
|
|
useful, for example, in order to avoid re-loading libraries that come
|
|
pre-loaded into your lisp implementation.
|
|
</p>
|
|
<p>ASDF also provides <code>make</code>, a way of allowing system developers to
|
|
choose a default operation for their systems. For example, a developer
|
|
who has created a system intended to format a specific document, might
|
|
make document-formatting the default operation invoked by <code>make</code>,
|
|
instead of loading. If the system developer doesn’t specify in the
|
|
system definition, the default operation will be loading.
|
|
</p>
|
|
|
|
|
|
<span id="index-operate"></span>
|
|
<span id="index-oos"></span>
|
|
|
|
<p>Because ASDF is an extensible system
|
|
for defining <em>operations</em> on <em>components</em>,
|
|
it also provides a generic function <code>operate</code>,
|
|
so you may arbitrarily operate on your systems beyond the default operations.
|
|
(At the interactive REPL, users often use its shorter alias <code>oos</code>,
|
|
which stands for <code>operate-on-system</code>, a name inherited from <code>mk-defsystem</code>.)
|
|
You’ll use <code>operate</code> whenever you want to do something beyond
|
|
compiling, loading and testing.
|
|
</p>
|
|
|
|
|
|
<dl class="def">
|
|
<dt id="index-load_002dsystem"><span class="category">Function: </span><span><strong>load-system</strong> <em>system &rest keys &key force force-not verbose version &allow-other-keys</em><a href='Convenience-Functions.html#index-load_002dsystem' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p>Apply <code>operate</code> with the operation <code>load-op</code>, the
|
|
<var>system</var>, and any provided keyword arguments. Calling
|
|
<code>load-system</code> is the regular, recommended way to load a system
|
|
into the current image.
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-compile_002dsystem"><span class="category">Function: </span><span><strong>compile-system</strong> <em>system &rest keys &key force force-not verbose version &allow-other-keys</em><a href='Convenience-Functions.html#index-compile_002dsystem' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p>Apply <code>operate</code> with the operation <code>compile-op</code>,
|
|
the <var>system</var>, and any provided keyword arguments.
|
|
This will make sure all the files in the system are compiled,
|
|
but not necessarily load any of them in the current image;
|
|
on most systems, it will <em>not</em> load all compiled files in the current image.
|
|
This function exists for symmetry with <code>load-system</code> but is not recommended
|
|
unless you are writing build scripts and know what you’re doing.
|
|
But then, you might be interested in <code>program-op</code> rather than <code>compile-op</code>.
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-test_002dsystem"><span class="category">Function: </span><span><strong>test-system</strong> <em>system &rest keys &key force force-not verbose version &allow-other-keys</em><a href='Convenience-Functions.html#index-test_002dsystem' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p>Apply <code>operate</code> with the operation <code>test-op</code>,
|
|
the <var>system</var>, and any provided keyword arguments.
|
|
See <a href="Predefined-operations-of-ASDF.html#test_002dop">test-op</a>.
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-make"><span class="category">Function: </span><span><strong>make</strong> <em>system &rest keys &key &allow-other-keys</em><a href='Convenience-Functions.html#index-make' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p>Do “The Right Thing” with your system.
|
|
Starting with ASDF 3.1, this function <code>make</code> is also available.
|
|
The default behaviour is to load the system as if by <code>load-system</code>;
|
|
but system authors can override this default in their system definition
|
|
they may specify an alternate operation as the intended use of their system,
|
|
with a <code>:build-operation</code> option in the <code>defsystem</code> form
|
|
(see <a href="The-defsystem-grammar.html#Build_002doperation">Build-operation</a>),
|
|
and an intended output pathname for that operation with
|
|
<code>:build-pathname</code>.
|
|
This function is experimental and largely untested. Use at your own risk.
|
|
</p></dd></dl>
|
|
<span id="index-build_002doperation"></span>
|
|
|
|
<dl class="def">
|
|
<dt id="index-require_002dsystem"><span class="category">Function: </span><span><strong>require-system</strong> <em>system &rest keys &key &allow-other-keys</em><a href='Convenience-Functions.html#index-require_002dsystem' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p><code>require-system</code> skips any update to systems that have already been loaded,
|
|
in the spirit of <code>cl:require</code>.
|
|
It does it by calling <code>load-system</code> with a keyword option
|
|
excluding already loaded systems.<a id="DOCF8" href="Convenience-Functions.html#FOOT8"><sup>8</sup></a>.
|
|
On actively maintained free software implementations
|
|
(namely recent versions of ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL),
|
|
once ASDF itself is loaded, <code>cl:require</code> too can load ASDF systems,
|
|
by falling back on <code>require-system</code>
|
|
for module names not recognized by the implementation.
|
|
(Note however that <code>require-system</code> does <em>not</em> fall back on <code>cl:require</code>;
|
|
that would introduce an “interesting” potential infinite loop to break somehow.)
|
|
</p>
|
|
<p><code>cl:require</code> and <code>require-system</code> are appropriate to load code
|
|
that is not being modified during the current programming session.
|
|
<code>cl:require</code> will notably load the implementation-provided extension modules;
|
|
<code>require-system</code> won’t, unless they are also defined as systems somehow,
|
|
which SBCL and MKCL do.
|
|
<code>require-system</code> may also be used to load any number of ASDF systems
|
|
that the user isn’t either developing or debugging,
|
|
for which a previously installed version is deemed to be satisfactory;
|
|
<code>cl:require</code> on the above-mentioned implementations will delegate to <code>require-system</code>
|
|
and may load them as well.
|
|
But for code that you are actively developing, debugging, or otherwise modifying,
|
|
you should use <code>load-system</code>, so ASDF will pick on your modifications
|
|
and transitively re-build the modified files and everything that depends on them
|
|
(that the requested <var>system</var> itself depends on —
|
|
ASDF itself never builds anything unless
|
|
it’s an explicitly requested system or the dependencies thereof).
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-already_002dloaded_002dsystems"><span class="category">Function: </span><span><strong>already-loaded-systems</strong><a href='Convenience-Functions.html#index-already_002dloaded_002dsystems' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p>Returns a list of names of the systems that have been successfully
|
|
loaded so far.
|
|
</p></dd></dl>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
<div class="footnote">
|
|
<hr>
|
|
<h4 class="footnotes-heading">Footnotes</h4>
|
|
|
|
<h5><a id="FOOT8" href="Convenience-Functions.html#DOCF8">(8)</a></h5>
|
|
<p>For the curious, the option is <code>:force-not (already-loaded-systems)</code>.
|
|
</p>
|
|
</div>
|
|
<hr>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Moving-on.html">Moving on</a>, Previous: <a href="Loading-a-system.html">Loading a system</a>, Up: <a href="Using-ASDF.html">Using ASDF</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|