/usr/share/doc/cl-asdf/asdf/The-object-model-of-ASDF.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: The object model of ASDF</title>

<meta name="description" content="ASDF Manual: The object model of ASDF">
<meta name="keywords" content="ASDF Manual: The object model of ASDF">
<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="index.html#Top" rel="up" title="Top">
<link href="Operations.html#Operations" rel="next" title="Operations">
<link href="Other-code-in-_002easd-files.html#Other-code-in-_002easd-files" rel="previous" title="Other code in .asd files">
<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="The-object-model-of-ASDF"></a>
<div class="header">
<p>
Next: <a href="Controlling-where-ASDF-searches-for-systems.html#Controlling-where-ASDF-searches-for-systems" accesskey="n" rel="next">Controlling where ASDF searches for systems</a>, Previous: <a href="Defining-systems-with-defsystem.html#Defining-systems-with-defsystem" accesskey="p" rel="previous">Defining systems with defsystem</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</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="The-object-model-of-ASDF-1"></a>
<h2 class="chapter">6 The object model of ASDF</h2>

<p>ASDF is designed in an object-oriented way from the ground up.
Both a system&rsquo;s structure and the operations that can be performed on systems
follow a extensible protocol.
</p>
<p>This allows the addition of behaviours:
for example, <code>cffi</code> adds support of special FFI description files
to interface with C libraries and of wrapper files to embed C code in Lisp;
<code>abcl-jar</code> supports creating Java JAR archives in ABCL;
and <code>poiu</code> supports for compiling code in parallel using background processes.
</p>
<p>This chapter deals with <code>component</code>s and <code>operation</code>s.
</p>
<p>A <code>component</code> represents an individual source file or a group of source files,
and the things that get transformed into.
A <code>system</code> is a component at the top level of the component hierarchy.
A <code>source-file</code> is a component representing a single source-file
and the successive output files into which it is transformed.
A <code>module</code> is an intermediate component itself grouping several other components,
themselves source-files or further modules.
</p>
<p>An <code>Operation</code> represents a transformation that can be performed on a component,
turning them from source files to intermediate results to final outputs.
</p>
<p>A pair of an <code>operation</code> and a <code>component</code> is called an <code>action</code>.
An <code>action</code> represents a particular build step to be <code>perform</code>ed,
after all its dependencies have been fulfilled.
In the ASDF model, actions depend on other actions.
The term <em>action</em> itself was used by Kent Pitman in his old article,
but was only used by ASDF hackers starting with the ASDF 2;
but the concept is ubiquitous since the very beginning of ASDF 1,
though previously implicit.
</p>
<p>Then, there are many <em>functions</em> available
to users, extenders and implementers of ASDF
to use, define or implement the activities
that are part of building your software.
Though they manipulate <code>action</code>s,
most of these functions do not take as an argument
a reified pair (a <code>cons</code> cell) of an operation and a component;
instead, they usually take two separate arguments,
which allows to take advantage of the power CLOS-style multiple dispatch
for fun and profit.
</p>
<p>There are many <em>hooks</em> in which to add functionality,
by customizing the behavior of existing <em>functions</em>.
</p>
<p>Last but not least is the notion of <em>dependency</em> between two actions.
The structure of dependencies between actions is
a directed <em>dependency graph</em>.
ASDF is invoked by being told to <em>operate</em>
with some <em>operation</em> on some toplevel <em>system</em>;
it will then <em>traverse</em> the graph and build a <em>plan</em>
that follows its structure.
To be successfully buildable, this graph of actions but be acyclic.
If, as a user, extender or implementer of ASDF, you fail
to keep the dependency graph without cycles,
ASDF will fail loudly as it eventually finds one.
To clearly distinguish the direction of dependencies,
ASDF 3 uses the words <em>requiring</em> and <em>required</em>
as applied to an action depending on the other:
the requiring action <code>depends-on</code> the completion of all required actions
before it may itself be <code>perform</code>ed.
</p>
<p>Using the <code>defsystem</code> syntax, users may easily express
direct dependencies along the graph of the object hierarchy:
between a component and its parent, its children, and its siblings.
By defining custom CLOS methods, you can express more elaborate dependencies as you wish.
Most common operations, such as <code>load-op</code>, <code>compile-op</code> or <code>load-source-op</code>
are automatically propagate &ldquo;downward&rdquo; the component hierarchy and are &ldquo;covariant&rdquo; with it:
to act the operation on the parent module, you must first act it on all the children components,
with the action on the parent being parent of the action on each child.
Other operations, such as <code>prepare-op</code> and <code>prepare-source-op</code>
(introduced in ASDF 3) are automatically propagated &ldquo;upward&rdquo; the component hierarchy
and are &ldquo;contravariant&rdquo; with it:
to perform the operation of preparing for compilation of a child component,
you must perform the operation of preparing for compilation of its parent component, and so on,
ensuring that all the parent&rsquo;s dependencies are (compiled and) loaded
before the child component may be compiled and loaded.
Yet other operations, such as <code>test-op</code> or <code>load-fasl-op</code>
remain at the system level, and are not propagated along the hierarchy,
but instead do something global on the system.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="Operations.html#Operations" accesskey="1">Operations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="Components.html#Components" accesskey="2">Components</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="Functions.html#Functions" accesskey="3">Functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<div class="header">
<p>
Next: <a href="Controlling-where-ASDF-searches-for-systems.html#Controlling-where-ASDF-searches-for-systems" accesskey="n" rel="next">Controlling where ASDF searches for systems</a>, Previous: <a href="Defining-systems-with-defsystem.html#Defining-systems-with-defsystem" accesskey="p" rel="previous">Defining systems with defsystem</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</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 / The-object-model-of-ASDF.html
