242 lines
13 KiB
HTML
242 lines
13 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>Miscellaneous Functions (ASDF Manual)</title>
|
|
|
|
<meta name="description" content="Miscellaneous Functions (ASDF Manual)">
|
|
<meta name="keywords" content="Miscellaneous 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="Miscellaneous-additional-functionality.html" rel="up" title="Miscellaneous additional functionality">
|
|
<link href="Some-Utility-Functions.html" rel="next" title="Some Utility Functions">
|
|
<link href="Controlling-source-file-character-encoding.html" rel="prev" title="Controlling source file character encoding">
|
|
<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="Miscellaneous-Functions">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Some-Utility-Functions.html" accesskey="n" rel="next">Some Utility Functions</a>, Previous: <a href="Controlling-source-file-character-encoding.html" accesskey="p" rel="prev">Controlling source file character encoding</a>, Up: <a href="Miscellaneous-additional-functionality.html" accesskey="u" rel="up">Miscellaneous additional functionality</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="Miscellaneous-Functions-1"></span><h3 class="section">11.3 Miscellaneous Functions</h3>
|
|
|
|
<p>These functions are exported by ASDF for your convenience.
|
|
</p>
|
|
<span id="system_002drelative_002dpathname"></span><dl class="def">
|
|
<dt id="index-system_002drelative_002dpathname"><span class="category">Function: </span><span><strong>system-relative-pathname</strong> <em>system name &key type</em><a href='Miscellaneous-Functions.html#index-system_002drelative_002dpathname' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd>
|
|
<p>It’s often handy to locate a file relative to some system.
|
|
The <code>system-relative-pathname</code> function meets this need.
|
|
</p>
|
|
<p>It takes two mandatory arguments <var>system</var> and <var>name</var>
|
|
and a keyword argument <var>type</var>:
|
|
<var>system</var> is name of a system, whereas <var>name</var> and optionally <var>type</var>
|
|
specify a relative pathname, interpreted like a component pathname specifier
|
|
by <code>coerce-pathname</code>. See <a href="The-defsystem-grammar.html#Pathname-specifiers">Pathname specifiers</a>.
|
|
</p>
|
|
<p>It returns a pathname built from the location of the system’s
|
|
source directory and the relative pathname. For example:
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp">> (asdf:system-relative-pathname 'cl-ppcre "regex.data")
|
|
#P"/repository/other/cl-ppcre/regex.data"
|
|
</pre></div>
|
|
|
|
</dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-system_002dsource_002ddirectory"><span class="category">Function: </span><span><strong>system-source-directory</strong> <em>system-designator</em><a href='Miscellaneous-Functions.html#index-system_002dsource_002ddirectory' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd>
|
|
<p>ASDF does not provide a turnkey solution for locating
|
|
data (or other miscellaneous) files
|
|
that are distributed together with the source code of a system.
|
|
Programmers can use <code>system-source-directory</code> to find such files.
|
|
Returns a pathname object.
|
|
The <var>system-designator</var> may be a string, symbol, or ASDF system object.
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-clear_002dsystem"><span class="category">Function: </span><span><strong>clear-system</strong> <em>system-designator</em><a href='Miscellaneous-Functions.html#index-clear_002dsystem' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd>
|
|
<p>It is sometimes useful to force recompilation of a previously loaded system.
|
|
For these cases, <code>(asdf:clear-system :foo)</code>
|
|
will remove the system from the table of currently loaded systems:
|
|
the next time the system <code>foo</code> or one that depends on it is re-loaded,
|
|
<code>foo</code> will be loaded again.<a id="DOCF16" href="Miscellaneous-Functions.html#FOOT16"><sup>16</sup></a>
|
|
</p>
|
|
<p>Note that this does not and cannot undo
|
|
the previous loading of the system.
|
|
Common Lisp has no provision for such an operation,
|
|
and its reliance on irreversible side-effects to global data structures
|
|
makes such a thing impossible in the general case.
|
|
If the software being re-loaded is not conceived with hot upgrade in mind,
|
|
re-loading may cause many errors, warnings or subtle silent problems,
|
|
as packages, generic function signatures, structures, types, macros, constants, etc.
|
|
are being redefined incompatibly.
|
|
It is up to the user to make sure that reloading is possible and has the desired effect.
|
|
In some cases, extreme measures such as recursively deleting packages,
|
|
unregistering symbols, defining methods on <code>update-instance-for-redefined-class</code>
|
|
and much more are necessary for reloading to happen smoothly.
|
|
ASDF itself goes to extensive effort to make a hot upgrade possible
|
|
with respect to its own code.
|
|
If you want, you can reuse some of its utilities such as
|
|
<code>uiop:define-package</code> and <code>uiop:with-upgradability</code>,
|
|
and get inspiration (or disinspiration)
|
|
from what it does in <samp>header.lisp</samp> and <samp>upgrade.lisp</samp>.
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-register_002dpreloaded_002dsystem"><span class="category">Function: </span><span><strong>register-preloaded-system</strong> <em>name &rest keys &key version &allow-other-keys</em><a href='Miscellaneous-Functions.html#index-register_002dpreloaded_002dsystem' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p>A system with name <var>name</var>,
|
|
created by <code>make-instance</code> with extra keys <var>keys</var>
|
|
(e.g. <code>:version</code>),
|
|
is registered as <em>preloaded</em>.
|
|
If <var>version</var> is <code>t</code> (default), then the version is copied from the defined system
|
|
of the same name (if registered) or else is <code>nil</code>
|
|
(this automatic copy of version is only available starting since ASDF 3.1.8).
|
|
</p>
|
|
<p>A preloaded system is considered as having already been loaded into the current image,
|
|
and if at some point some other system <code>:depends-on</code> it yet no source code is found,
|
|
it is considered as already provided,
|
|
and ASDF will not raise a <code>missing-component</code> error.
|
|
</p>
|
|
<p>This function is particularly useful if you distribute your code
|
|
as fasls with either <code>compile-bundle-op</code> or <code>monolithic-compile-bundle-op</code>,
|
|
and want to register systems so that dependencies will work uniformly
|
|
whether you’re using your software from source or from fasl.
|
|
</p>
|
|
<p>Note that if the system was already defined or loaded from source code,
|
|
its build information will remain active until you call <code>clear-system</code> on it,
|
|
at which point a system without build information will be registered in its place.
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-register_002dimmutable_002dsystem-1"><span class="category">Function: </span><span><strong>register-immutable-system</strong> <em>name &rest keys</em><a href='Miscellaneous-Functions.html#index-register_002dimmutable_002dsystem-1' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd><p>A system with name <var>name</var> is registered as preloaded,
|
|
and additionally is marked as <em>immutable</em>:
|
|
that is, attempts to compile or load it will be succeed
|
|
without actually reading, creating or loading any file,
|
|
as if the system was passed as a <code>force-not</code> argument
|
|
to all calls to <code>plan</code> or <code>operate</code>.
|
|
There will be no search for an updated <samp>.asd</samp> file
|
|
to override the loaded version,
|
|
whether from the source-register or any other method.
|
|
</p>
|
|
<p>If a <var>version</var> keyword argument is specified as <code>t</code> or left unspecified,
|
|
then the version is copied from the defined system
|
|
of the same name (if registered) or else is <code>nil</code>.
|
|
This automatic copy of version is available starting
|
|
since immutable systems have been available in ASDF 3.1.5.
|
|
</p>
|
|
<p>This function, available since ASDF 3.1.5, is particularly useful
|
|
if you distribute a large body of code as a precompiled image,
|
|
and want to allow users to extend the image with further extension systems,
|
|
but without making thousands of filesystem requests looking for inexistent
|
|
(or worse, out of date) source code
|
|
for all the systems that came bundled with the image but aren’t
|
|
distributed as source code to regular users.
|
|
<span id="index-immutable-systems-1"></span>
|
|
</p></dd></dl>
|
|
|
|
<dl class="def">
|
|
<dt id="index-run_002dshell_002dcommand"><span class="category">Function: </span><span><strong>run-shell-command</strong> <em>control-string &rest args</em><a href='Miscellaneous-Functions.html#index-run_002dshell_002dcommand' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dd>
|
|
<p>This function is obsolete and present only for the sake of backwards-compatibility:
|
|
“If it’s not backwards, it’s not compatible”. We <em>strongly</em> discourage its use.
|
|
Its current behaviour is only well-defined on Unix platforms
|
|
(which include MacOS X and cygwin). On Windows, anything goes.
|
|
The following documentation is only for the purpose of your migrating away from it
|
|
in a way that preserves semantics.
|
|
</p>
|
|
<p>Instead we recommend the use <code>run-program</code>, described in the next section, and
|
|
available as part of ASDF since ASDF 3.
|
|
</p>
|
|
<p><code>run-shell-command</code> takes as arguments a format <code>control-string</code>
|
|
and arguments to be passed to <code>format</code> after this control-string
|
|
to produce a string.
|
|
This string is a command that will be evaluated with a POSIX shell if possible;
|
|
yet, on Windows, some implementations will use CMD.EXE,
|
|
while others (like SBCL) will make an attempt at invoking a POSIX shell
|
|
(and fail if it is not present).
|
|
</p></dd></dl>
|
|
|
|
</div>
|
|
<div class="footnote">
|
|
<hr>
|
|
<h4 class="footnotes-heading">Footnotes</h4>
|
|
|
|
<h5><a id="FOOT16" href="Miscellaneous-Functions.html#DOCF16">(16)</a></h5>
|
|
<p>Alternatively, you could touch <code>foo.asd</code> or
|
|
remove the corresponding fasls from the output file cache.</p>
|
|
</div>
|
|
<hr>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Some-Utility-Functions.html">Some Utility Functions</a>, Previous: <a href="Controlling-source-file-character-encoding.html">Controlling source file character encoding</a>, Up: <a href="Miscellaneous-additional-functionality.html">Miscellaneous additional functionality</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>
|