/usr/share/doc/cl-asdf/asdf/Creating-new-operations.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: Creating new operations</title>

<meta name="description" content="ASDF Manual: Creating new operations">
<meta name="keywords" content="ASDF Manual: Creating new operations">
<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="Operations.html#Operations" rel="up" title="Operations">
<link href="Components.html#Components" rel="next" title="Components">
<link href="Predefined-operations-of-ASDF.html#Predefined-operations-of-ASDF" rel="previous" title="Predefined operations of ASDF">
<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="Creating-new-operations"></a>
<div class="header">
<p>
Previous: <a href="Predefined-operations-of-ASDF.html#Predefined-operations-of-ASDF" accesskey="p" rel="previous">Predefined operations of ASDF</a>, Up: <a href="Operations.html#Operations" accesskey="u" rel="up">Operations</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="Creating-new-operations-1"></a>
<h4 class="subsection">6.1.2 Creating new operations</h4>

<p>ASDF was designed to be extensible in an object-oriented fashion.
To teach ASDF new tricks, a programmer can implement the behaviour he wants
by creating a subclass of <code>operation</code>.
</p>
<p>ASDF&rsquo;s pre-defined operations are in no way &ldquo;privileged&rdquo;,
but it is requested that developers never use the <code>asdf</code> package
for operations they develop themselves.
The rationale for this rule is that we don&rsquo;t want to establish a
&ldquo;global asdf operation name registry&rdquo;,
but also want to avoid name clashes.
</p>
<p>Your operation <em>must</em> usually provide methods
for one or more of the following generic functions:
</p>
<ul>
<li> <code>perform</code>
Unless your operation, like <code>prepare-op</code>,
is for dependency propagation only,
the most important function for which to define a method
is usually <code>perform</code>,
which will be called to perform the operation on a specified component,
after all dependencies have been performed.

<p>The <code>perform</code> method must call <code>output-files</code> (see below)
to find out where to put its files,
because the user is allowed to override the method
or tweak the output-translation mechanism.
Perform should only use the primary value returned by <code>output-files</code>.
If one and only one output file is expected,
it can call <code>output-file</code> that checks that this is the case
and returns the first and only list element.
</p>
</li><li> <code>output-files</code>
If your perform method has any output,
you must define a method for this function.
for ASDF to determine where the outputs of performing operation lie.

<p>Your method may return two values, a list of pathnames, and a boolean.
If the boolean is <code>nil</code> (or you fail to return multiple values),
then enclosing <code>:around</code> methods may translate these pathnames,
e.g. to ensure object files are somehow stored
in some implementation-dependent cache.
If the boolean is <code>t</code> then the pathnames are marked
not be translated by the enclosing <code>:around</code> method.
</p>
</li><li> <code>component-depends-on</code>
If the action of performing the operation on a component has dependencies,
you must define a method on <code>component-depends-on</code>.

<p>Your method will take as specialized arguments
an operation and a component which together identify an action,
and return a list of entries describing actions that this action depends on.
The format of entries is described below.
</p>
<p>It is <em>strongly</em> advised that
you should always append the results of <code>(call-next-method)</code>
to the results of your method,
or &ldquo;interesting&rdquo; failures will likely occur,
unless you&rsquo;re a true specialist of ASDF internals.
It is unhappily too late to compatibly use the <code>append</code> method combination,
but conceptually that&rsquo;s the protocol that is being manually implemented.
</p>
<p>Each entry returned by <code>component-depends-on</code> is itself a list.
</p>
<p>The first element of an entry is an operation designator:
either an operation object designating itself, or
a symbol that names an operation class
(that ASDF will instantiate using <code>make-operation</code>).
For instance, <code>load-op</code>, <code>compile-op</code> and <code>prepare-op</code>
are common such names, denoting the respective operations.
</p>
<p>The rest of each entry is a list of component designators:
either a component object designating itself,
or an identifier to be used with <code>find-component</code>.
<code>find-component</code> will be called with the current component&rsquo;s parent as parent,
and the identifier as second argument.
The identifier is typically a string,
a symbol (to be downcased as per <code>coerce-name</code>),
or a list of strings or symbols.
In particular, the empty list <code>nil</code> denotes the parent itself.
</p>
</li></ul>

<p>An operation <em>may</em> provide methods for the following generic functions:
</p>
<ul>
<li> <code>input-files</code>
A method for this function is often not needed,
since ASDF has a pretty clever default <code>input-files</code> mechanism.
You only need create a method if there are multiple ultimate input files,
and/or the bottom one doesn&rsquo;t depend
on the <code>component-pathname</code> of the component.

</li><li> <code>operation-done-p</code>
You only need to define a method on that function
if you can detect conditions that invalidate previous runs of the operation,
even though no filesystem timestamp has changed,
in which case you return <code>nil</code> (the default is <code>t</code>).

<p>For instance, the method for <code>test-op</code> always returns <code>nil</code>,
so that tests are always run afresh.
Of course, the <code>test-op</code> for your system could depend
on a deterministically repeatable <code>test-report-op</code>,
and just read the results from the report files,
in which case you could have this method return <code>t</code>.
</p>
</li></ul>

<p>Operations that print output should send that output to the standard
CL stream <code>*standard-output*</code>, as the Lisp compiler and loader do.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="Predefined-operations-of-ASDF.html#Predefined-operations-of-ASDF" accesskey="p" rel="previous">Predefined operations of ASDF</a>, Up: <a href="Operations.html#Operations" accesskey="u" rel="up">Operations</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 / Creating-new-operations.html
