/usr/share/doc/cl-asdf/asdf/Miscellaneous-additional-functionality.html

<html lang="en">
<head>
<title>Miscellaneous additional functionality - 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="Error-handling.html#Error-handling" title="Error handling">
<link rel="next" href="Getting-the-latest-version.html#Getting-the-latest-version" title="Getting the latest version">
<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="Miscellaneous-additional-functionality"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Getting-the-latest-version.html#Getting-the-latest-version">Getting the latest version</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Error-handling.html#Error-handling">Error handling</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
</div>

<!-- node-name,  next,  previous,  up -->
<h2 class="chapter">10 Miscellaneous additional functionality</h2>

<p>ASDF includes several additional features that are generally
useful for system definition and development.

<h3 class="section">10.1 Controlling file compilation</h3>

<p>When declaring a component (system, module, file),
you can specify a keyword argument <code>:around-compile function</code>. 
If left unspecified,
the value will be inherited from the parent component if any,
or with a default of <code>nil</code>
if no value is specified in any transitive parent.

   <p>The argument must be a either <code>nil</code>, a fbound symbol,
a lambda-expression (e.g. <code>(lambda (thunk) ...(funcall thunk) ...)</code>)
a function object (e.g. using <code>#.#'</code> but that's discouraged
because it prevents the introspection done by e.g. asdf-dependency-grovel),
or a string that when read yields a symbol or a lambda-expression. 
<code>nil</code> means the normal compile-file function will be called. 
A non-nil value designates a function of one argument
that will be called with a thunk for calling
the compile-file function with proper arguments.

   <p>Note that by using a string, you may reference
a function, symbol and/or package
that will only be created later during the build, but
isn't yet present at the time the defsystem form is evaluated. 
However, if your entire system is using such a hook, you may have to
explicitly override the hook with <code>nil</code> for all the modules and files
that are compiled before the hook is defined.

   <p>Using this hook, you may achieve such effects as:
locally renaming packages,
binding <var>*readtables*</var> and other syntax-controlling variables,
handling warnings and other conditions,
proclaiming consistent optimization settings,
saving code coverage information,
maintaining meta-data about compilation timings,
setting gensym counters and PRNG seeds and other sources of non-determinism,
overriding the source-location and/or timestamping systems,
checking that some compile-time side-effects were properly balanced,
etc.

<h3 class="section">10.2 Miscellaneous Exported Functions</h3>

<div class="defun">
&mdash; Function: <b>coerce-pathname</b><var> name &amp;key type defaults<a name="index-coerce_002dpathname-60"></a></var><br>
<blockquote>
        <p>This function (available starting with ASDF 2.012.11)
takes an argument, and portably interprets it as a pathname. 
If the argument <var>name</var> is a pathname or <code>nil</code>, it is passed through;
if it's a symbol, it's interpreted as a string by downcasing it;
if it's a string, it is first separated using <code>/</code> into substrings;
the leading substrings denote subdirectories of a relative pathname. 
If <var>type</var> is <code>:directory</code> or the string ends with <code>/</code>,
the last substring is also a subdirectory;
if <var>type</var> is a string, it is used as the type of the pathname, and
the last substring is the name component of the pathname;
if <var>type</var> is <code>nil</code>, the last substring specifies both name and type components
of the pathname, with the last <code>.</code> separating them, or only the name component
if there's no last <code>.</code> or if there is only one dot and it's the first character. 
The host, device and version components come from <var>defaults</var>, which defaults to
<var>*default-pathname-defaults*</var>; but that shouldn't matter if you use <code>merge-pathnames*</code>.

     </blockquote></div>

<div class="defun">
&mdash; Function: <b>merge-pathnames*</b><var> &amp;key specified defaults<a name="index-merge_002dpathnames_002a-61"></a></var><br>
<blockquote>
        <p>This function is a replacement for <code>merge-pathnames</code> that uses the host and device
from the <var>defaults</var> rather than the <var>specified</var> pathname when the latter
is a relative pathname. This allows ASDF and its users to create and use relative pathnames
without having to know beforehand what are the host and device
of the absolute pathnames they are relative to.

        </blockquote></div>

<div class="defun">
&mdash; Function: <b>system-relative-pathname</b><var> system name &amp;key type<a name="index-system_002drelative_002dpathname-62"></a></var><br>
<blockquote>
        <p>It's often handy to locate a file relative to some system. 
The <code>system-relative-pathname</code> function meets this need.

        <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>It returns a pathname built from the location of the system's
source directory and the relative pathname. For example:

     <pre class="lisp">          &gt; (asdf:system-relative-pathname 'cl-ppcre "regex.data")
          #P"/repository/other/cl-ppcre/regex.data"
</pre>
        </blockquote></div>

<div class="defun">
&mdash; Function: <b>system-source-directory</b><var> system-designator<a name="index-system_002dsource_002ddirectory-63"></a></var><br>
<blockquote>
        <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></blockquote></div>

<div class="defun">
&mdash; Function: <b>clear-system</b><var> system-designator<a name="index-clear_002dsystem-64"></a></var><br>
<blockquote>
        <p>It is sometimes useful to force recompilation of a previously loaded system. 
In these cases, it may be useful to <code>(asdf:clear-system :foo)</code>
to 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 then be loaded again. 
Alternatively, you could touch <code>foo.asd</code> or
remove the corresponding fasls from the output file cache. 
(It was once conceived that one should provide
a list of systems the recompilation of which to force
as the <code>:force</code> keyword argument to <code>load-system</code>;
but this has never worked, and though the feature was fixed in ASDF 2.000,
it remains <code>cerror</code>'ed out as nobody ever used it.)

        <p>Note that this does not and cannot by itself 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 datastructures
makes such a thing impossible in the general case. 
If the software being re-loaded is not conceived with hot upgrade in mind,
this 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 through notable pains to make such a hot upgrade possible
with respect to its own code, and what it does is ridiculously complex;
look at the beginning of <samp><span class="file">asdf.lisp</span></samp> to see what it does. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: <b>run-shell-command</b><var><a name="index-run_002dshell_002dcommand-65"></a></var><br>
<blockquote>
        <p>This function is obsolete and present only for the sake of backwards-compatibility:
&ldquo;If it's not backwards, it's not compatible&rdquo;. We strongly discourage its use. 
Its current behavior is only well-defined on Unix platforms
(which includes MacOS X and cygwin). On Windows, anything goes.

        <p>Instead we recommend the use of such a function as
<code>xcvb-driver:run-program/process-output-stream</code>
from the <code>xcvb-driver</code> system that is distributed with XCVB:
<a href="http://common-lisp.net/project/xcvb">http://common-lisp.net/project/xcvb</a>. 
It's only alternative that supports
as many implementations and operating systems as ASDF does,
and provides well-defined behavior outside Unix (i.e. on Windows). 
(The only unsupported exception is Genera, since on it
<code>run-shell-command</code> doesn't make sense anyway on that platform).

        <p>This function takes as arguments a <code>format</code> control-string
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></blockquote></div>

   </body></html>
cl-asdf 2:2.20-1 / usr / share / doc / cl-asdf / asdf / Miscellaneous-additional-functionality.html
