/usr/share/doc/cl-asdf/asdf/Miscellaneous-Functions.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
https://common-lisp.net/project/asdf/asdf.html.

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

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

This manual revised (C) 2009-2015 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 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>ASDF Manual: Miscellaneous Functions</title>

<meta name="description" content="ASDF Manual: Miscellaneous Functions">
<meta name="keywords" content="ASDF Manual: Miscellaneous Functions">
<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="Miscellaneous-additional-functionality.html#Miscellaneous-additional-functionality" rel="up" title="Miscellaneous additional functionality">
<link href="Some-Utility-Functions.html#Some-Utility-Functions" rel="next" title="Some Utility Functions">
<link href="Controlling-source-file-character-encoding.html#Controlling-source-file-character-encoding" rel="prev" title="Controlling source file character encoding">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
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.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Miscellaneous-Functions"></a>
<div class="header">
<p>
Next: <a href="Some-Utility-Functions.html#Some-Utility-Functions" accesskey="n" rel="next">Some Utility Functions</a>, Previous: <a href="Controlling-source-file-character-encoding.html#Controlling-source-file-character-encoding" accesskey="p" rel="prev">Controlling source file character encoding</a>, Up: <a href="Miscellaneous-additional-functionality.html#Miscellaneous-additional-functionality" accesskey="u" rel="up">Miscellaneous additional functionality</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="Miscellaneous-Functions-1"></a>
<h3 class="section">11.3 Miscellaneous Functions</h3>

<p>These functions are exported by ASDF for your convenience.
</p>
<a name="system_002drelative_002dpathname"></a><dl>
<dt><a name="index-system_002drelative_002dpathname"></a>Function: <strong>system-relative-pathname</strong> <em>system name &amp;key type</em></dt>
<dd>
<p>It&rsquo;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#The-defsystem-grammar">Pathname specifiers</a>.
</p>
<p>It returns a pathname built from the location of the system&rsquo;s
source directory and the relative pathname. For example:
</p>
<div class="lisp">
<pre class="lisp">&gt; (asdf:system-relative-pathname 'cl-ppcre &quot;regex.data&quot;)
#P&quot;/repository/other/cl-ppcre/regex.data&quot;
</pre></div>

</dd></dl>

<dl>
<dt><a name="index-system_002dsource_002ddirectory"></a>Function: <strong>system-source-directory</strong> <em>system-designator</em></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>
<dt><a name="index-clear_002dsystem"></a>Function: <strong>clear-system</strong> <em>system-designator</em></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 name="DOCF16" href="#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>
<dt><a name="index-register_002dpreloaded_002dsystem"></a>Function: <strong>register-preloaded-system</strong> <em>name &amp;rest keys</em></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>.
That is, its code has 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&rsquo;re using your software from source or from fasl.
</p></dd></dl>

<dl>
<dt><a name="index-register_002dimmutable_002dsystem-1"></a>Function: <strong>register-immutable-system</strong> <em>name &amp;rest keys</em></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>immutable</em>.
That is, its code has already been loaded into the current image,
and if at some point some other system <code>:depends-on</code> it,
it is considered as already provided, and
no attempt will be made to search for an updated version from the source-registry
or any other method.
There will be no search for an <samp>.asd</samp> file, and no <code>missing-component</code> error.
</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&rsquo;t
distributed as source code to regular users.
<a name="index-immutable-systems-1"></a>
</p></dd></dl>

<dl>
<dt><a name="index-run_002dshell_002dcommand"></a>Function: <strong>run-shell-command</strong> <em>control-string &amp;rest args</em></dt>
<dd>
<p>This function is obsolete and present only for the sake of backwards-compatibility:
&ldquo;If it&rsquo;s not backwards, it&rsquo;s not compatible&rdquo;. 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 class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h3><a name="FOOT16" href="#DOCF16">(16)</a></h3>
<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" accesskey="n" rel="next">Some Utility Functions</a>, Previous: <a href="Controlling-source-file-character-encoding.html#Controlling-source-file-character-encoding" accesskey="p" rel="prev">Controlling source file character encoding</a>, Up: <a href="Miscellaneous-additional-functionality.html#Miscellaneous-additional-functionality" accesskey="u" rel="up">Miscellaneous additional functionality</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.1.6-1 / usr / share / doc / cl-asdf / asdf / Miscellaneous-Functions.html
