/usr/share/doc/cl-asdf/asdf/The-defsystem-grammar.html

<html lang="en">
<head>
<title>The defsystem grammar - 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="up" href="Defining-systems-with-defsystem.html#Defining-systems-with-defsystem" title="Defining systems with defsystem">
<link rel="prev" href="A-more-involved-example.html#A-more-involved-example" title="A more involved example">
<link rel="next" href="Other-code-in-_002easd-files.html#Other-code-in-_002easd-files" title="Other code in .asd files">
<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="The-defsystem-grammar"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Other-code-in-_002easd-files.html#Other-code-in-_002easd-files">Other code in .asd files</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="A-more-involved-example.html#A-more-involved-example">A more involved example</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Defining-systems-with-defsystem.html#Defining-systems-with-defsystem">Defining systems with defsystem</a>
<hr>
</div>

<!-- node-name,  next,  previous,  up -->
<h3 class="section">5.3 The defsystem grammar</h3>

<!-- FIXME: @var typesetting not consistently used here.  We should either expand -->
<!-- its use to everywhere, or we should kill it everywhere. -->
<pre class="example">     system-definition := ( defsystem system-designator <var>system-option</var>* )
     
     system-option := :defsystem-depends-on system-list
                      | :class class-name (see discussion below)
                      | module-option
                      | option
     
     module-option := :components component-list
                      | :serial [ t | nil ]
                      | :if-component-dep-fails component-dep-fail-option
     
     option :=
             | :pathname pathname-specifier
             | :default-component-class class-name
             | :perform method-form
             | :explain method-form
             | :output-files method-form
             | :operation-done-p method-form
             | :depends-on ( <var>dependency-def</var>* )
             | :in-order-to ( <var>dependency</var>+ )
     
     
     system-list := ( <var>simple-component-name</var>* )
     
     component-list := ( <var>component-def</var>* )
     
     component-def  := ( component-type simple-component-name <var>option</var>* )
     
     component-type := :system | :module | :file | :static-file | other-component-type
     
     other-component-type := symbol-by-name (see <a href="The-defsystem-grammar.html#The-defsystem-grammar">Component types</a>)
     
     dependency-def := simple-component-name
                    | ( :feature name )
                    | ( :version simple-component-name version-specifier)
     
     dependency := (dependent-op <var>requirement</var>+)
     requirement := (required-op <var>required-component</var>+)
                  | (feature feature-name)
     dependent-op := operation-name
     required-op := operation-name | feature
     
     simple-component-name := string
                           |  symbol
     
     pathname-specifier := pathname | string | symbol
     
     method-form := (operation-name qual lambda-list &amp;rest body)
     qual := method qualifier
     
     component-dep-fail-option := :fail | :try-next | :ignore
</pre>
<h4 class="subsection">5.3.1 Component names</h4>

<p>Component names (<code>simple-component-name</code>)
may be either strings or symbols.

<h4 class="subsection">5.3.2 Component types</h4>

<p>Component type names, even if expressed as keywords, will be looked up
by name in the current package and in the asdf package, if not found in
the current package.  So a component type <code>my-component-type</code>, in
the current package <code>my-system-asd</code> can be specified as
<code>:my-component-type</code>, or <code>my-component-type</code>.

<h4 class="subsection">5.3.3 System class names</h4>

<p>A system class name will be looked up in the same way as a Component
type (see above).  Typically, one will not need to specify a system
class name, unless using a non-standard system class defined in some
ASDF extension, typically loaded through <code>DEFSYSTEM-DEPENDS-ON</code>,
see below.  For such class names in the ASDF package, we recommend that
the <code>:class</code> option be specified using a keyword symbol, such as

<pre class="example">     :class :MY-NEW-SYSTEM-SUBCLASS
</pre>
   <p>This practice will ensure that package name conflicts are avoided. 
Otherwise, the symbol <code>MY-NEW-SYSTEM-SUBCLASS</code> will be read into
the current package <em>before</em> it has been exported from the ASDF
extension loaded by <code>:defsystem-depends-on</code>, causing a name
conflict in the current package.

<h4 class="subsection">5.3.4 Defsystem depends on</h4>

<p>The <code>:defsystem-depends-on</code> option to <code>defsystem</code> allows the
programmer to specify another ASDF-defined system or set of systems that
must be loaded <em>before</em> the system definition is processed. 
Typically this is used to load an ASDF extension that is used in the
system definition.

<h4 class="subsection">5.3.5 Pathname specifiers</h4>

<p><a name="index-pathname-specifiers-19"></a>
A pathname specifier (<code>pathname-specifier</code>)
may be a pathname, a string or a symbol. 
When no pathname specifier is given for a component,
which is the usual case, the component name itself is used.

   <p>If a string is given, which is the usual case,
the string will be interpreted as a Unix-style pathname
where <code>/</code> characters will be interpreted as directory separators. 
Usually, Unix-style relative pathnames are used
(i.e. not starting with <code>/</code>, as opposed to absolute pathnames);
they are relative to the path of the parent component. 
Finally, depending on the <code>component-type</code>,
the pathname may be interpreted as either a file or a directory,
and if it's a file,
a file type may be added corresponding to the <code>component-type</code>,
or else it will be extracted from the string itself (if applicable).

   <p>For instance, the <code>component-type</code> <code>:module</code>
wants a directory pathname, and so a string <code>"foo/bar"</code>
will be interpreted as the pathname <samp><span class="file">#p"foo/bar/"</span></samp>. 
On the other hand, the <code>component-type</code> <code>:file</code>
wants a file of type <code>lisp</code>, and so a string <code>"foo/bar"</code>
will be interpreted as the pathname <samp><span class="file">#p"foo/bar.lisp"</span></samp>,
and a string <code>"foo/bar.quux"</code>
will be interpreted as the pathname <samp><span class="file">#p"foo/bar.quux.lisp"</span></samp>. 
Finally, the <code>component-type</code> <code>:static-file</code>
wants a file without specifying a type, and so a string <code>"foo/bar"</code>
will be interpreted as the pathname <samp><span class="file">#p"foo/bar"</span></samp>,
and a string <code>"foo/bar.quux"</code>
will be interpreted as the pathname <samp><span class="file">#p"foo/bar.quux"</span></samp>.

   <p>ASDF does not interpret the string <code>".."</code> to designate the parent
directory.  This string will be passed through to the underlying
operating system for interpretation.  We <em>believe</em> that this will
work on all platforms where ASDF is deployed, but do not guarantee this
behavior.  A pathname object with a relative directory component of
<code>:up</code> or <code>:back</code> is the only guaranteed way to specify a
parent directory.

   <p>If a symbol is given, it will be translated into a string,
and downcased in the process. 
The downcasing of symbols is unconventional,
but was selected after some consideration. 
Observations suggest that the type of systems we want to support
either have lowercase as customary case (Unix, Mac, windows)
or silently convert lowercase to uppercase (lpns),
so this makes more sense than attempting to use <code>:case :common</code>
as argument to <code>make-pathname</code>,
which is reported not to work on some implementations.

   <p>Pathname objects may be given to override the path for a component. 
Such objects are typically specified using reader macros such as <code>#p</code>
or <code>#.(make-pathname ...)</code>. 
Note however, that <code>#p...</code> is a shorthand for <code>#.(parse-namestring ...)</code>
and that the behavior of <code>parse-namestring</code> is completely non-portable,
unless you are using Common Lisp <code>logical-pathname</code>s
(see <a href="The-defsystem-grammar.html#The-defsystem-grammar">Using logical pathnames</a>, below). 
Pathnames made with <code>#.(make-pathname ...)</code>
can usually be done more easily with the string syntax above. 
The only case that you really need a pathname object is to override
the component-type default file type for a given component. 
Therefore, pathname objects should only rarely be used. 
Unhappily, ASDF 1 didn't properly support
parsing component names as strings specifying paths with directories,
and the cumbersome <code>#.(make-pathname ...)</code> syntax had to be used.

   <p>Note that when specifying pathname objects,
ASDF does not do any special interpretation of the pathname
influenced by the component type, unlike the procedure for
pathname-specifying strings. 
On the one hand, you have to be careful to provide a pathname that correctly
fulfills whatever constraints are required from that component type
(e.g. naming a directory or a file with appropriate type);
on the other hand, you can circumvent the file type that would otherwise
be forced upon you if you were specifying a string.

<h4 class="subsection">5.3.6 Version specifiers</h4>

<p><a name="index-version-specifiers-20"></a><a name="index-g_t_003aversion-21"></a>
Version specifiers are parsed as period-separated lists of integers.  I.e., in the example,
<code>0.2.1</code> is to be interpreted, roughly speaking, as <code>(0 2 1)</code>. 
In particular, version <code>0.2.1</code> is interpreted the same as
<code>0.0002.1</code> and is strictly version-less-than version <code>0.20.1</code>,
even though the two are the same when interpreted as decimal fractions.

   <p>System definers are encouraged to use version identifiers of the form
<var>x</var>.<var>y</var>.<var>z</var> for major version, minor version (compatible
API) and patch level.

   <p>See <a href="Common-attributes-of-components.html#Common-attributes-of-components">Common attributes of components</a>.

<h4 class="subsection">5.3.7 Using logical pathnames</h4>

<p><a name="index-logical-pathnames-22"></a>
We do not generally recommend the use of logical pathnames,
especially not so to newcomers to Common Lisp. 
However, we do support the use of logical pathnames by old timers,
when such is their preference.

   <p>To use logical pathnames,
you will have to provide a pathname object as a <code>:pathname</code> specifier
to components that use it, using such syntax as
<code>#p"LOGICAL-HOST:absolute;path;to;component.lisp"</code>.

   <p>You only have to specify such logical pathname
for your system or some top-level component. 
Sub-components' relative pathnames,
specified using the string syntax for names,
will be properly merged with the pathnames of their parents. 
The specification of a logical pathname host however is <em>not</em>
otherwise directly supported in the ASDF syntax
for pathname specifiers as strings.

   <p>The <code>asdf-output-translation</code> layer will
avoid trying to resolve and translate logical pathnames. 
The advantage of this is that
you can define yourself what translations you want to use
with the logical pathname facility. 
The disadvantage is that if you do not define such translations,
any system that uses logical pathnames will behave differently under
asdf-output-translations than other systems you use.

   <p>If you wish to use logical pathnames you will have to configure the
translations yourself before they may be used. 
ASDF currently provides no specific support
for defining logical pathname translations.

   <p>Note that the reasons we do not recommend logical pathnames are that
(1) there is no portable way to set up logical pathnames before they are used,
(2) logical pathnames are limited to only portably use
a single character case, digits and hyphens. 
While you can solve the first issue on your own,
describing how to do it on each of fifteen implementations supported by ASDF
is more than we can document. 
As for the second issue, mind that the limitation is notably enforced on SBCL,
and that you therefore can't portably violate the limitations
but must instead define some encoding of your own and add individual mappings
to name physical pathnames that do not fit the restrictions. 
This can notably be a problem when your Lisp files are part of a larger project
in which it is common to name files or directories in a way that
includes the version numbers of supported protocols,
or in which files are shared with software written
in different programming languages where conventions include the use of
underscores, dots or CamelCase in pathnames.

<h4 class="subsection">5.3.8 Serial dependencies</h4>

<p><a name="index-serial-dependencies-23"></a>
If the <code>:serial t</code> option is specified for a module,
ASDF will add dependencies for each child component,
on all the children textually preceding it. 
This is done as if by <code>:depends-on</code>.

<pre class="lisp">     :serial t
     :components ((:file "a") (:file "b") (:file "c"))
</pre>
   <p>is equivalent to

<pre class="lisp">     :components ((:file "a")
                  (:file "b" :depends-on ("a"))
                  (:file "c" :depends-on ("a" "b")))
</pre>
   <h4 class="subsection">5.3.9 Source location</h4>

<p>The <code>:pathname</code> option is optional in all cases for systems
defined via <code>defsystem</code>,
and in the usual case the user is recommended not to supply it.

   <p>Instead, ASDF follows a hairy set of rules that are designed so that
     <ol type=1 start=1>
<li><code>find-system</code>
will load a system from disk
and have its pathname default to the right place. 
<li>This pathname information will not be overwritten with
<code>*default-pathname-defaults*</code>
(which could be somewhere else altogether)
if the user loads up the <samp><span class="file">.asd</span></samp> file into his editor
and interactively re-evaluates that form.
        </ol>

   <p>If a system is being loaded for the first time,
its top-level pathname will be set to:

     <ul>
<li>The host/device/directory parts of <code>*load-truename*</code>,
if it is bound. 
<li><code>*default-pathname-defaults*</code>, otherwise. 
</ul>

   <p>If a system is being redefined, the top-level pathname will be

     <ul>
<li>changed, if explicitly supplied or obtained from <code>*load-truename*</code>
(so that an updated source location is reflected in the system definition)
<li>changed if it had previously been set from <code>*default-pathname-defaults*</code>
<li>left as before, if it had previously been set from <code>*load-truename*</code>
and <code>*load-truename*</code> is currently unbound
(so that a developer can evaluate a <code>defsystem</code> form
from within an editor without clobbering its source location)
</ul>

<h4 class="subsection">5.3.10 if-component-dep-fails option</h4>

<p>This option is only appropriate for module components (including
systems), not individual source files.

   <p>For more information about this option, see <a href="Pre_002ddefined-subclasses-of-component.html#Pre_002ddefined-subclasses-of-component">Pre-defined subclasses of component</a>.

   </body></html>
cl-asdf 2:2.20-1 / usr / share / doc / cl-asdf / asdf / The-defsystem-grammar.html
