asdf.html 336 KB
Newer Older
1
2
3
<!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
Raymond Toy's avatar
Raymond Toy committed
4
5
6
for Common Lisp programs and libraries.

You can find the latest version of this manual at
7
https://common-lisp.net/project/asdf/asdf.html.
Raymond Toy's avatar
Raymond Toy committed
8

Raymond Toy's avatar
Raymond Toy committed
9
ASDF Copyright (C) 2001-2016 Daniel Barlow and contributors.
Raymond Toy's avatar
Raymond Toy committed
10

Raymond Toy's avatar
Raymond Toy committed
11
This manual Copyright (C) 2001-2016 Daniel Barlow and contributors.
Raymond Toy's avatar
Raymond Toy committed
12

Raymond Toy's avatar
Raymond Toy committed
13
This manual revised (C) 2009-2016 Robert P. Goldman and Francois-Rene Rideau.
Raymond Toy's avatar
Raymond Toy committed
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

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
32
33
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 -->
34
<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
35
36
<head>
<title>ASDF Manual</title>
Raymond Toy's avatar
Raymond Toy committed
37

38
39
40
41
42
43
44
45
46
47
48
49
50
<meta name="description" content="ASDF Manual">
<meta name="keywords" content="ASDF Manual">
<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="#Top" rel="start" title="Top">
<link href="#Concept-Index" rel="index" title="Concept Index">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<link href="dir.html#Top" rel="up" title="(dir)">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
Raymond Toy's avatar
Raymond Toy committed
51
52
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
53
54
55
56
57
58
59
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}
Raymond Toy's avatar
Raymond Toy committed
60
kbd {font-style: oblique}
61
62
63
64
65
66
67
68
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}
Raymond Toy's avatar
Raymond Toy committed
69
70
71
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
72
73
74
ul.no-bullet {list-style: none}
-->
</style>
Raymond Toy's avatar
Raymond Toy committed
75
76


77
</head>
Raymond Toy's avatar
Raymond Toy committed
78

Raymond Toy's avatar
Raymond Toy committed
79
<body lang="en">
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
<h1 class="settitle" align="center">ASDF Manual</h1>





<a name="SEC_Contents"></a>
<h2 class="contents-heading">Table of Contents</h2>

<div class="contents">

<ul class="no-bullet">
  <li><a name="toc-Introduction-1" href="#Introduction">1 Introduction</a></li>
  <li><a name="toc-Quick-start-summary-1" href="#Quick-start-summary">2 Quick start summary</a></li>
  <li><a name="toc-Loading-ASDF-1" href="#Loading-ASDF">3 Loading ASDF</a>
  <ul class="no-bullet">
    <li><a name="toc-Loading-a-pre_002dinstalled-ASDF-1" href="#Loading-a-pre_002dinstalled-ASDF">3.1 Loading a pre-installed ASDF</a></li>
    <li><a name="toc-Checking-whether-ASDF-is-loaded-1" href="#Checking-whether-ASDF-is-loaded">3.2 Checking whether ASDF is loaded</a></li>
    <li><a name="toc-Upgrading-ASDF-1" href="#Upgrading-ASDF">3.3 Upgrading ASDF</a></li>
    <li><a name="toc-Replacing-your-implementation_0027s-ASDF-1" href="#Replacing-your-implementation_0027s-ASDF">3.4 Replacing your implementation&rsquo;s ASDF</a></li>
    <li><a name="toc-Loading-ASDF-from-source-1" href="#Loading-ASDF-from-source">3.5 Loading ASDF from source</a></li>
  </ul></li>
  <li><a name="toc-Configuring-ASDF-1" href="#Configuring-ASDF">4 Configuring ASDF</a>
  <ul class="no-bullet">
    <li><a name="toc-Configuring-ASDF-to-find-your-systems-1" href="#Configuring-ASDF-to-find-your-systems">4.1 Configuring ASDF to find your systems</a></li>
    <li><a name="toc-Configuring-ASDF-to-find-your-systems-_002d_002d_002d-old-style-1" href="#Configuring-ASDF-to-find-your-systems-_002d_002d_002d-old-style">4.2 Configuring ASDF to find your systems &mdash; old style</a></li>
    <li><a name="toc-Configuring-where-ASDF-stores-object-files-1" href="#Configuring-where-ASDF-stores-object-files">4.3 Configuring where ASDF stores object files</a></li>
    <li><a name="toc-Resetting-the-ASDF-configuration-1" href="#Resetting-the-ASDF-configuration">4.4 Resetting the ASDF configuration</a></li>
  </ul></li>
  <li><a name="toc-Using-ASDF-1" href="#Using-ASDF">5 Using ASDF</a>
  <ul class="no-bullet">
    <li><a name="toc-Loading-a-system-1" href="#Loading-a-system">5.1 Loading a system</a></li>
    <li><a name="toc-Convenience-Functions-1" href="#Convenience-Functions">5.2 Convenience Functions</a></li>
    <li><a name="toc-Moving-on-1" href="#Moving-on">5.3 Moving on</a></li>
  </ul></li>
  <li><a name="toc-Defining-systems-with-defsystem-1" href="#Defining-systems-with-defsystem">6 Defining systems with defsystem</a>
  <ul class="no-bullet">
    <li><a name="toc-The-defsystem-form-1" href="#The-defsystem-form">6.1 The defsystem form</a></li>
    <li><a name="toc-A-more-involved-example-1" href="#A-more-involved-example">6.2 A more involved example</a></li>
    <li><a name="toc-The-defsystem-grammar-1" href="#The-defsystem-grammar">6.3 The defsystem grammar</a>
    <ul class="no-bullet">
      <li><a name="toc-Component-names" href="#Component-names">6.3.1 Component names</a></li>
      <li><a name="toc-Component-types" href="#Component-types">6.3.2 Component types</a></li>
      <li><a name="toc-System-class-names" href="#System-class-names">6.3.3 System class names</a></li>
      <li><a name="toc-Defsystem-depends-on" href="#Defsystem-depends-on">6.3.4 Defsystem depends on</a></li>
Raymond Toy's avatar
Raymond Toy committed
125
126
127
128
129
      <li><a name="toc-Build_002doperation" href="#Build_002doperation">6.3.5 Build-operation</a></li>
      <li><a name="toc-Weakly-depends-on" href="#Weakly-depends-on">6.3.6 Weakly depends on</a></li>
      <li><a name="toc-Pathname-specifiers" href="#Pathname-specifiers">6.3.7 Pathname specifiers</a></li>
      <li><a name="toc-Version-specifiers" href="#Version-specifiers">6.3.8 Version specifiers</a></li>
      <li><a name="toc-Require" href="#Require">6.3.9 Require</a></li>
Raymond Toy's avatar
Raymond Toy committed
130
131
132
133
134
      <li><a name="toc-Feature-dependencies" href="#Feature-dependencies">6.3.10 Feature dependencies</a></li>
      <li><a name="toc-Using-logical-pathnames" href="#Using-logical-pathnames">6.3.11 Using logical pathnames</a></li>
      <li><a name="toc-Serial-dependencies" href="#Serial-dependencies">6.3.12 Serial dependencies</a></li>
      <li><a name="toc-Source-location-_0028_003apathname_0029" href="#Source-location-_0028_003apathname_0029">6.3.13 Source location (<code>:pathname</code>)</a></li>
      <li><a name="toc-if_002dfeature-option" href="#if_002dfeature-option">6.3.14 if-feature option</a></li>
Raymond Toy's avatar
Raymond Toy committed
135
      <li><a name="toc-feature-requirement" href="#feature-requirement">6.3.15 feature requirement</a></li>
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
    </ul></li>
    <li><a name="toc-Other-code-in-_002easd-files-1" href="#Other-code-in-_002easd-files">6.4 Other code in .asd files</a></li>
    <li><a name="toc-The-package_002dinferred_002dsystem-extension-1" href="#The-package_002dinferred_002dsystem-extension">6.5 The package-inferred-system extension</a></li>
  </ul></li>
  <li><a name="toc-The-Object-model-of-ASDF" href="#The-object-model-of-ASDF">7 The Object model of ASDF</a>
  <ul class="no-bullet">
    <li><a name="toc-Operations-1" href="#Operations">7.1 Operations</a>
    <ul class="no-bullet">
      <li><a name="toc-Predefined-operations-of-ASDF-1" href="#Predefined-operations-of-ASDF">7.1.1 Predefined operations of ASDF</a></li>
      <li><a name="toc-Creating-new-operations-1" href="#Creating-new-operations">7.1.2 Creating new operations</a></li>
    </ul></li>
    <li><a name="toc-Components-1" href="#Components">7.2 Components</a>
    <ul class="no-bullet">
      <li><a name="toc-Common-attributes-of-components-1" href="#Common-attributes-of-components">7.2.1 Common attributes of components</a>
      <ul class="no-bullet">
        <li><a name="toc-Name" href="#Name">7.2.1.1 Name</a></li>
        <li><a name="toc-Version-identifier" href="#Version-identifier">7.2.1.2 Version identifier</a></li>
        <li><a name="toc-Required-features" href="#Required-features">7.2.1.3 Required features</a></li>
        <li><a name="toc-Dependencies-1" href="#Dependencies-1">7.2.1.4 Dependencies</a></li>
        <li><a name="toc-pathname" href="#pathname">7.2.1.5 pathname</a></li>
        <li><a name="toc-properties" href="#properties">7.2.1.6 properties</a></li>
      </ul></li>
      <li><a name="toc-Pre_002ddefined-subclasses-of-component-1" href="#Pre_002ddefined-subclasses-of-component">7.2.2 Pre-defined subclasses of component</a></li>
      <li><a name="toc-Creating-new-component-types-1" href="#Creating-new-component-types">7.2.3 Creating new component types</a></li>
    </ul></li>
    <li><a name="toc-Dependencies-2" href="#Dependencies">7.3 Dependencies</a></li>
    <li><a name="toc-Functions-1" href="#Functions">7.4 Functions</a></li>
  </ul></li>
  <li><a name="toc-Controlling-where-ASDF-searches-for-systems-1" href="#Controlling-where-ASDF-searches-for-systems">8 Controlling where ASDF searches for systems</a>
  <ul class="no-bullet">
    <li><a name="toc-Configurations-1" href="#Configurations">8.1 Configurations</a></li>
    <li><a name="toc-Truenames-and-other-dangers-1" href="#Truenames-and-other-dangers">8.2 Truenames and other dangers</a></li>
    <li><a name="toc-XDG-base-directory-1" href="#XDG-base-directory">8.3 XDG base directory</a></li>
    <li><a name="toc-Backward-Compatibility-1" href="#Backward-Compatibility">8.4 Backward Compatibility</a></li>
    <li><a name="toc-Configuration-DSL-1" href="#Configuration-DSL">8.5 Configuration DSL</a></li>
    <li><a name="toc-Configuration-Directories-1" href="#Configuration-Directories">8.6 Configuration Directories</a>
    <ul class="no-bullet">
      <li><a name="toc-The-_003ahere-directive" href="#The-here-directive">8.6.1 The :here directive</a></li>
    </ul></li>
    <li><a name="toc-Shell_002dfriendly-syntax-for-configuration-1" href="#Shell_002dfriendly-syntax-for-configuration">8.7 Shell-friendly syntax for configuration</a></li>
    <li><a name="toc-Search-Algorithm-1" href="#Search-Algorithm">8.8 Search Algorithm</a></li>
    <li><a name="toc-Caching-Results-1" href="#Caching-Results">8.9 Caching Results</a></li>
    <li><a name="toc-Configuration-API-1" href="#Configuration-API">8.10 Configuration API</a></li>
    <li><a name="toc-Introspection-1" href="#Introspection">8.11 Introspection</a>
    <ul class="no-bullet">
      <li><a name="toc-_002asource_002dregistry_002dparameter_002a-variable-1" href="#g_t_002asource_002dregistry_002dparameter_002a-variable">8.11.1 *source-registry-parameter* variable</a></li>
      <li><a name="toc-Information-about-system-dependencies-1" href="#Information-about-system-dependencies">8.11.2 Information about system dependencies</a></li>
    </ul></li>
    <li><a name="toc-Status-1" href="#Status">8.12 Status</a></li>
    <li><a name="toc-Rejected-ideas-1" href="#Rejected-ideas">8.13 Rejected ideas</a></li>
    <li><a name="toc-TODO-1" href="#TODO">8.14 TODO</a></li>
    <li><a name="toc-Credits-for-the-source_002dregistry-1" href="#Credits-for-the-source_002dregistry">8.15 Credits for the source-registry</a></li>
  </ul></li>
  <li><a name="toc-Controlling-where-ASDF-saves-compiled-files-1" href="#Controlling-where-ASDF-saves-compiled-files">9 Controlling where ASDF saves compiled files</a>
  <ul class="no-bullet">
    <li><a name="toc-Configurations-2" href="#Output-Configurations">9.1 Configurations</a></li>
    <li><a name="toc-Backward-Compatibility-2" href="#Output-Backward-Compatibility">9.2 Backward Compatibility</a></li>
    <li><a name="toc-Configuration-DSL-2" href="#Output-Configuration-DSL">9.3 Configuration DSL</a></li>
    <li><a name="toc-Configuration-Directories-2" href="#Output-Configuration-Directories">9.4 Configuration Directories</a></li>
    <li><a name="toc-Shell_002dfriendly-syntax-for-configuration-2" href="#Output-Shell_002dfriendly-syntax-for-configuration">9.5 Shell-friendly syntax for configuration</a></li>
    <li><a name="toc-Semantics-of-Output-Translations-1" href="#Semantics-of-Output-Translations">9.6 Semantics of Output Translations</a></li>
    <li><a name="toc-Caching-Results-2" href="#Output-Caching-Results">9.7 Caching Results</a></li>
    <li><a name="toc-Output-location-API-1" href="#Output-location-API">9.8 Output location API</a></li>
    <li><a name="toc-Credits-for-output-translations-1" href="#Credits-for-output-translations">9.9 Credits for output translations</a></li>
  </ul></li>
  <li><a name="toc-Error-handling-1" href="#Error-handling">10 Error handling</a>
  <ul class="no-bullet">
    <li><a name="toc-ASDF-errors" href="#ASDF-errors">10.1 ASDF errors</a></li>
    <li><a name="toc-Compilation-error-and-warning-handling" href="#Compilation-error-and-warning-handling">10.2 Compilation error and warning handling</a></li>
  </ul></li>
  <li><a name="toc-Miscellaneous-additional-functionality-1" href="#Miscellaneous-additional-functionality">11 Miscellaneous additional functionality</a>
  <ul class="no-bullet">
    <li><a name="toc-Controlling-file-compilation-1" href="#Controlling-file-compilation">11.1 Controlling file compilation</a></li>
    <li><a name="toc-Controlling-source-file-character-encoding-1" href="#Controlling-source-file-character-encoding">11.2 Controlling source file character encoding</a></li>
    <li><a name="toc-Miscellaneous-Functions-1" href="#Miscellaneous-Functions">11.3 Miscellaneous Functions</a></li>
    <li><a name="toc-Some-Utility-Functions-1" href="#Some-Utility-Functions">11.4 Some Utility Functions</a></li>
  </ul></li>
  <li><a name="toc-Getting-the-latest-version-1" href="#Getting-the-latest-version">12 Getting the latest version</a></li>
  <li><a name="toc-FAQ-1" href="#FAQ">13 FAQ</a>
  <ul class="no-bullet">
    <li><a name="toc-_0060_0060Where-do-I-report-a-bug_003f_0027_0027" href="#Where-do-I-report-a-bug_003f">13.1 &ldquo;Where do I report a bug?&rdquo;</a></li>
    <li><a name="toc-Mailing-list-1" href="#Mailing-list">13.2 Mailing list</a></li>
    <li><a name="toc-_0060_0060What-has-changed-between-ASDF-1_002c-ASDF-2_002c-and-ASDF-3_003f_0027_0027" href="#What-has-changed-between-ASDF-1-ASDF-2-and-ASDF-3_003f">13.3 &ldquo;What has changed between ASDF 1, ASDF 2, and ASDF 3?&rdquo;</a>
    <ul class="no-bullet">
      <li><a name="toc-What-are-ASDF-1_002c-ASDF-2_002c-and-ASDF-3_003f" href="#What-are-ASDF-1-2-3_003f">13.3.1 What are ASDF 1, ASDF 2, and ASDF 3?</a></li>
      <li><a name="toc-How-do-I-detect-the-ASDF-version_003f-1" href="#How-do-I-detect-the-ASDF-version_003f">13.3.2 How do I detect the ASDF version?</a></li>
      <li><a name="toc-ASDF-can-portably-name-files-in-subdirectories-1" href="#ASDF-can-portably-name-files-in-subdirectories">13.3.3 ASDF can portably name files in subdirectories</a></li>
      <li><a name="toc-Output-translations-1" href="#Output-translations">13.3.4 Output translations</a></li>
      <li><a name="toc-Source-Registry-Configuration-1" href="#Source-Registry-Configuration">13.3.5 Source Registry Configuration</a></li>
      <li><a name="toc-Usual-operations-are-made-easier-to-the-user-1" href="#Usual-operations-are-made-easier-to-the-user">13.3.6 Usual operations are made easier to the user</a></li>
      <li><a name="toc-Many-bugs-have-been-fixed-1" href="#Many-bugs-have-been-fixed">13.3.7 Many bugs have been fixed</a></li>
      <li><a name="toc-ASDF-itself-is-versioned-1" href="#ASDF-itself-is-versioned">13.3.8 ASDF itself is versioned</a></li>
      <li><a name="toc-ASDF-can-be-upgraded-1" href="#ASDF-can-be-upgraded">13.3.9 ASDF can be upgraded</a></li>
      <li><a name="toc-Decoupled-release-cycle-1" href="#Decoupled-release-cycle">13.3.10 Decoupled release cycle</a></li>
      <li><a name="toc-Pitfalls-of-the-transition-to-ASDF-2-1" href="#Pitfalls-of-the-transition-to-ASDF-2">13.3.11 Pitfalls of the transition to ASDF 2</a></li>
      <li><a name="toc-Pitfalls-of-the-upgrade-to-ASDF-3-1" href="#Pitfalls-of-the-upgrade-to-ASDF-3">13.3.12 Pitfalls of the upgrade to ASDF 3</a></li>
      <li><a name="toc-What-happened-to-the-bundle-operations_003f" href="#What-happened-to-the-bundle-operations">13.3.13 What happened to the bundle operations?</a></li>
    </ul></li>
    <li><a name="toc-Issues-with-installing-the-proper-version-of-ASDF-1" href="#Issues-with-installing-the-proper-version-of-ASDF">13.4 Issues with installing the proper version of ASDF</a>
    <ul class="no-bullet">
      <li><a name="toc-_0060_0060My-Common-Lisp-implementation-comes-with-an-outdated-version-of-ASDF_002e-What-to-do_003f_0027_0027" href="#My-Common-Lisp-implementation-comes-with-an-outdated-version-of-ASDF_002e-What-to-do_003f">13.4.1 &ldquo;My Common Lisp implementation comes with an outdated version of ASDF. What to do?&rdquo;</a></li>
      <li><a name="toc-_0060_0060I_0027m-a-Common-Lisp-implementation-vendor_002e-When-and-how-should-I-upgrade-ASDF_003f_0027_0027" href="#I_0027m-a-Common-Lisp-implementation-vendor_002e-When-and-how-should-I-upgrade-ASDF_003f">13.4.2 &ldquo;I&rsquo;m a Common Lisp implementation vendor. When and how should I upgrade ASDF?&rdquo;</a></li>
    </ul></li>
    <li><a name="toc-Issues-with-configuring-ASDF-1" href="#Issues-with-configuring-ASDF">13.5 Issues with configuring ASDF</a>
    <ul class="no-bullet">
      <li><a name="toc-_0060_0060How-can-I-customize-where-fasl-files-are-stored_003f_0027_0027" href="#How-can-I-customize-where-fasl-files-are-stored_003f">13.5.1 &ldquo;How can I customize where fasl files are stored?&rdquo;</a></li>
      <li><a name="toc-_0060_0060How-can-I-wholly-disable-the-compiler-output-cache_003f_0027_0027" href="#How-can-I-wholly-disable-the-compiler-output-cache_003f">13.5.2 &ldquo;How can I wholly disable the compiler output cache?&rdquo;</a></li>
    </ul></li>
    <li><a name="toc-Issues-with-using-and-extending-ASDF-to-define-systems-1" href="#Issues-with-using-and-extending-ASDF-to-define-systems">13.6 Issues with using and extending ASDF to define systems</a>
    <ul class="no-bullet">
      <li><a name="toc-_0060_0060How-can-I-cater-for-unit_002dtesting-in-my-system_003f_0027_0027" href="#How-can-I-cater-for-unit_002dtesting-in-my-system_003f">13.6.1 &ldquo;How can I cater for unit-testing in my system?&rdquo;</a></li>
      <li><a name="toc-_0060_0060How-can-I-cater-for-documentation-generation-in-my-system_003f_0027_0027" href="#How-can-I-cater-for-documentation-generation-in-my-system_003f">13.6.2 &ldquo;How can I cater for documentation generation in my system?&rdquo;</a></li>
      <li><a name="toc-_0060_0060How-can-I-maintain-non_002dLisp-_0028e_002eg_002e-C_0029-source-files_003f_0027_0027" href="#How-can-I-maintain-non_002dLisp-_0028e_002eg_002e-C_0029-source-files_003f">13.6.3 &ldquo;How can I maintain non-Lisp (e.g. C) source files?&rdquo;</a></li>
      <li><a name="toc-_0060_0060I-want-to-put-my-module_0027s-files-at-the-top-level_002e-How-do-I-do-this_003f_0027_0027" href="#I-want-to-put-my-module_0027s-files-at-the-top-level_002e-How-do-I-do-this_003f">13.6.4 &ldquo;I want to put my module&rsquo;s files at the top level.  How do I do this?&rdquo;</a></li>
      <li><a name="toc-How-do-I-create-a-system-definition-where-all-the-source-files-have-a-_002ecl-extension_003f-1" href="#How-do-I-create-a-system-definition-where-all-the-source-files-have-a-_002ecl-extension_003f">13.6.5 How do I create a system definition where all the source files have a .cl extension?</a></li>
      <li><a name="toc-How-do-I-mark-a-source-file-to-be-loaded-only-and-not-compiled_003f-1" href="#How-do-I-mark-a-source-file-to-be-loaded-only-and-not-compiled_003f">13.6.6 How do I mark a source file to be loaded only and not compiled?</a></li>
      <li><a name="toc-How-do-I-work-with-readtables_003f-1" href="#How-do-I-work-with-readtables_003f">13.6.7 How do I work with readtables?</a>
      <ul class="no-bullet">
        <li><a name="toc-How-should-my-system-use-a-readtable-exported-by-another-system_003f" href="#How-should-my-system-use-a-readtable-exported-by-another-system_003f">13.6.7.1 How should my system use a readtable exported by another system?</a></li>
        <li><a name="toc-How-should-my-library-make-a-readtable-available-to-other-systems_003f" href="#How-should-my-library-make-a-readtable-available-to-other-systems_003f">13.6.7.2 How should my library make a readtable available to other systems?</a></li>
      </ul></li>
Raymond Toy's avatar
Raymond Toy committed
257
      <li><a name="toc-How-can-I-capture-ASDF_0027s-output_003f-1" href="#How-can-I-capture-ASDF_0027s-output_003f">13.6.8 How can I capture ASDF&rsquo;s output?</a></li>
Raymond Toy's avatar
Raymond Toy committed
258
      <li><a name="toc-_002aLOAD_002dPATHNAME_002a-and-_002aLOAD_002dTRUENAME_002a-have-weird-values_002c-help_0021" href="#LOAD_002dPATHNAME-has-a-weird-value">13.6.9 *LOAD-PATHNAME* and *LOAD-TRUENAME* have weird values, help!</a></li>
259
260
261
262
263
264
265
266
267
268
269
270
271
    </ul></li>
    <li><a name="toc-ASDF-development-FAQs-1" href="#ASDF-development-FAQs">13.7 ASDF development FAQs</a>
    <ul class="no-bullet">
      <li><a name="toc-How-do-I-run-the-tests-interactively-in-a-REPL_003f-1" href="#How-do-I-run-the-tests-interactively-in-a-REPL_003f">13.7.1 How do I run the tests interactively in a REPL?</a></li>
    </ul></li>
  </ul></li>
  <li><a name="toc-Ongoing-Work-1" href="#Ongoing-Work">Ongoing Work</a></li>
  <li><a name="toc-Bibliography-1" href="#Bibliography">Bibliography</a></li>
  <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li>
  <li><a name="toc-Function-and-Class-Index-1" href="#Function-and-Class-Index">Function and Class Index</a></li>
  <li><a name="toc-Variable-Index-1" href="#Variable-Index">Variable Index</a></li>
</ul>
</div>
Raymond Toy's avatar
Raymond Toy committed
272
273
274
275




276
277
278
<a name="Top"></a>
<a name="ASDF_003a-Another-System-Definition-Facility"></a>
<h1 class="top">ASDF: Another System Definition Facility</h1>
279
<p>Manual for Version 3.2.1
280
</p>
Raymond Toy's avatar
Raymond Toy committed
281

282
283
284
285
286
287
<p>This manual describes ASDF, a system definition facility
for Common Lisp programs and libraries.
</p>
<p>You can find the latest version of this manual at
<a href="https://common-lisp.net/project/asdf/asdf.html">https://common-lisp.net/project/asdf/asdf.html</a>.
</p>
Raymond Toy's avatar
Raymond Toy committed
288
<p>ASDF Copyright &copy; 2001-2016 Daniel Barlow and contributors.
289
</p>
Raymond Toy's avatar
Raymond Toy committed
290
<p>This manual Copyright &copy; 2001-2016 Daniel Barlow and contributors.
291
</p>
Raymond Toy's avatar
Raymond Toy committed
292
<p>This manual revised &copy; 2009-2016 Robert P. Goldman and Francois-Rene Rideau.
293
294
</p>
<p>Permission is hereby granted, free of charge, to any person obtaining
Raymond Toy's avatar
Raymond Toy committed
295
296
297
298
299
300
a copy of this software and associated documentation files (the
&ldquo;Software&rdquo;), 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:
301
302
</p>
<p>The above copyright notice and this permission notice shall be
Raymond Toy's avatar
Raymond Toy committed
303
included in all copies or substantial portions of the Software.
304
305
</p>
<p>THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND,
Raymond Toy's avatar
Raymond Toy committed
306
307
308
309
310
311
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.
312
313
</p>

Raymond Toy's avatar
Raymond Toy committed
314
315
316



317
318
319
320
321
322
323
324
325
326
327
328
329
330

<hr>
<a name="Introduction"></a>
<a name="Introduction-1"></a>
<h2 class="chapter">1 Introduction</h2>
<a name="index-ASDF_002drelated-features"></a>
<a name="index-_002afeatures_002a-1"></a>
<a name="index-Testing-for-ASDF"></a>
<a name="index-ASDF-versions"></a>
<a name="index-_003aasdf"></a>
<a name="index-_003aasdf2"></a>
<a name="index-_003aasdf3"></a>

<p>ASDF is Another System Definition Facility:
Raymond Toy's avatar
Raymond Toy committed
331
a tool for specifying how systems of Common Lisp software
332
are made up of components (sub-systems and files),
Raymond Toy's avatar
Raymond Toy committed
333
334
and how to operate on these components in the right order
so that they can be compiled, loaded, tested, etc.
335
336
337
338
339
If you are new to ASDF, see <a href="#Quick-start-summary">the quick start
guide</a>.
</p>
<p>ASDF presents three faces:
one for users of Common Lisp software who want to reuse other people&rsquo;s code,
Raymond Toy's avatar
Raymond Toy committed
340
one for writers of Common Lisp software who want to specify how to build their systems,
341
342
343
344
345
and one for implementers of Common Lisp extensions who want to extend
the build system.
For more specifics,
see <a href="#Using-ASDF">Using ASDF</a>,
to learn how to use ASDF to load a system.
Raymond Toy's avatar
Raymond Toy committed
346
See <a href="#Defining-systems-with-defsystem">Defining systems with defsystem</a>,
347
to learn how to define a system of your own.
Raymond Toy's avatar
Raymond Toy committed
348
349
See <a href="#The-object-model-of-ASDF">The object model of ASDF</a>, for a description of
the ASDF internals and how to extend ASDF.
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
</p>
<p>Note that
ASDF is <em>not</em> a tool for library and system <em>installation</em>;
it plays a role like <code>make</code> or <code>ant</code>, not like a package manager.
In particular, ASDF should not to be confused with Quicklisp or ASDF-Install,
that attempt to find and download ASDF systems for you.
Despite what the name might suggest, ASDF-Install is not part of ASDF, but a separate piece of software.
ASDF-Install is also unmaintained and obsolete.
We recommend you use Quicklisp
(<a href="http://www.quicklisp.org/">http://www.quicklisp.org/</a>) instead,
a Common Lisp package manager which works well and is being actively maintained.
If you want to download software from version control instead of tarballs,
so you may more easily modify it, we recommend clbuild (<a href="http://common-lisp.net/project/clbuild/">http://common-lisp.net/project/clbuild/</a>).
We recommend <samp>~/common-lisp/</samp>
as a place into which to install Common Lisp software;
starting with ASDF 3.1.2, it is included in the default source-registry configuration.
</p>
<p>Finally, note that this manual is incomplete.
All the bases are covered,
but many advanced topics are only barely alluded to,
and there is not much in terms of examples.
The source code remains the ultimate source of information,
free software systems in Quicklisp remain the best source of examples,
and the mailing-list the best place to ask for help.
</p>
Raymond Toy's avatar
Raymond Toy committed
375

376
377
378
379
<hr>
<a name="Quick-start-summary"></a>
<a name="Quick-start-summary-1"></a>
<h2 class="chapter">2 Quick start summary</h2>
Raymond Toy's avatar
Raymond Toy committed
380

381
382
<ul>
<li> To load an ASDF system:
Raymond Toy's avatar
Raymond Toy committed
383

384
385
386
387
388
<ul>
<li> Load ASDF itself into your Lisp image, using
<code>(require &quot;asdf&quot;)</code>.
Check that you have a recent version using <code>(asdf:asdf-version)</code>.
For more details, or if any of the above fails, see <a href="#Loading-ASDF">Loading ASDF</a>.
Raymond Toy's avatar
Raymond Toy committed
389

390
391
392
393
394
395
</li><li> Make sure software is installed where ASDF can find it.
The simplest way is to put all your Lisp code in subdirectories of
<samp>~/common-lisp/</samp> (starting with ASDF 3.1.2),
or <samp>~/.local/share/common-lisp/source/</samp>
(for ASDF 2 and later, or if you want to keep source in a hidden directory).
For more details, see <a href="#Configuring-ASDF-to-find-your-systems">Configuring ASDF to find your systems</a>.
Raymond Toy's avatar
Raymond Toy committed
396

397
398
</li><li> Load your system with <code>(asdf:load-system &quot;<var>my-system</var>&quot;)</code>.
See <a href="#Using-ASDF">Using ASDF</a>.
Raymond Toy's avatar
Raymond Toy committed
399

400
</li></ul>
Raymond Toy's avatar
Raymond Toy committed
401

402
</li><li> To make your own ASDF system:
Raymond Toy's avatar
Raymond Toy committed
403

404
405
<ul>
<li> As above, load and configure ASDF.
Raymond Toy's avatar
Raymond Toy committed
406

407
408
409
410
411
</li><li> Make a new directory for your system, <code><var>my-system</var>/</code>,
again in a location where ASDF can find it.
All else being equal, the easiest location is probably
<samp>~/common-lisp/my-system/</samp>.
See <a href="#Configuring-ASDF-to-find-your-systems">Configuring ASDF to find your systems</a>.
Raymond Toy's avatar
Raymond Toy committed
412
413


414
415
416
417
418
</li><li> Create an ASDF system definition listing the dependencies of
your system, its components, and their interdependencies,
and put it in <samp><var>my-system</var>.asd</samp>.
This file must have the same name as your system, all lowercase.
See <a href="#Defining-systems-with-defsystem">Defining systems with defsystem</a>.
Raymond Toy's avatar
Raymond Toy committed
419

420
421
</li><li> Use <code>(asdf:load-system &quot;<var>my-system</var>&quot;)</code>
to make sure it&rsquo;s all working properly. See <a href="#Using-ASDF">Using ASDF</a>.
Raymond Toy's avatar
Raymond Toy committed
422

423
424
</li></ul>
</li></ul>
Raymond Toy's avatar
Raymond Toy committed
425
426
427
428
429
430






431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
<hr>
<a name="Loading-ASDF"></a>
<a name="Loading-ASDF-1"></a>
<h2 class="chapter">3 Loading ASDF</h2>


<hr>
<a name="Loading-a-pre_002dinstalled-ASDF"></a>
<a name="Loading-a-pre_002dinstalled-ASDF-1"></a>
<h3 class="section">3.1 Loading a pre-installed ASDF</h3>

<p>The recommended way to load ASDF is via:
</p><div class="lisp">
<pre class="lisp">(require &quot;asdf&quot;)
</pre></div>

<p>All actively maintained Lisp implementations now include a copy of ASDF 3
that you can load this way using Common Lisp&rsquo;s <code>require</code> function.<a name="DOCF1" href="#FOOT1"><sup>1</sup></a>
</p>
<p>If the implementation you are using doesn&rsquo;t provide a recent ASDF 3,
we recommend you upgrade it.
If for some reason you would rather not upgrade it,
we recommend you replace your implementation&rsquo;s ASDF.
See <a href="#Replacing-your-implementation_0027s-ASDF">Replacing your implementation's ASDF</a>.
If all else fails, see see <a href="#Loading-ASDF-from-source">Loading ASDF from source</a> below.
</p>
<p>If you use an actively maintained implementation that fails to provide
an up-to-date enough stable release of ASDF,
you may also send a bug report to your Lisp vendor and complain about it
&mdash; or you may fix the issue yourself if it&rsquo;s free software.
</p>
<p>As of the writing of this manual,
the following implementations provide ASDF 3 this way:
ABCL, Allegro CL, CLASP, Clozure CL, CMUCL, ECL, GNU CLISP, LispWorks, MKCL, SBCL.
The following implementations only provide ASDF 2:
MOCL, XCL.
The following implementations don&rsquo;t provide ASDF:
Corman CL, GCL, Genera, MCL, SCL.
The latter implementations are not actively maintained (except maybe GCL);
if some of them are ever released again, they probably will include ASDF 3.
</p>
<p>For maximum convenience you might want to have ASDF loaded
Raymond Toy's avatar
Raymond Toy committed
473
474
whenever you start your Lisp implementation,
for example by loading it from the startup script or dumping a custom core
475
476
477
478
479
480
481
482
&mdash; check your Lisp implementation&rsquo;s manual for details.
SLIME notably sports a <code>slime-asdf</code> contrib that makes life easier with ASDF.
</p>

<hr>
<a name="Checking-whether-ASDF-is-loaded"></a>
<a name="Checking-whether-ASDF-is-loaded-1"></a>
<h3 class="section">3.2 Checking whether ASDF is loaded</h3>
Raymond Toy's avatar
Raymond Toy committed
483

484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
<p>To check that ASDF is properly loaded, you can run this form:
</p>
<div class="lisp">
<pre class="lisp">(asdf:asdf-version)
</pre></div>

<p>If it returns a string,
that is the version of ASDF that is currently installed.
If that version is suitably recent (say, 3.1.2 or later),
then you can skip directly to next chapter: See <a href="#Configuring-ASDF">Configuring ASDF</a>.
</p>
<p>If it raises an error,
then either ASDF is not loaded, or
you are using a very old version of ASDF,
and need to install ASDF 3.
</p>
<p>For more precision in detecting versions old and new,
see <a href="#How-do-I-detect-the-ASDF-version_003f">How do I detect the ASDF version?</a>.
</p>
<p>If you are experiencing problems with ASDF,
please try upgrading to the latest released version,
using the method below,
before you contact us and raise an issue.
</p>
<hr>
<a name="Upgrading-ASDF"></a>
<a name="Upgrading-ASDF-1"></a>
<h3 class="section">3.3 Upgrading ASDF</h3>

<p>If your implementation already provides ASDF 3 or later (and it should),
but you want a more recent ASDF version than your implementation provides,
then you just need to ensure the more recent ASDF is installed in a configured path, like any other system.
We recommend you download an official tarball or checkout a release from git into
<samp>~/common-lisp/asdf/</samp>.
(see <a href="#Configuring-ASDF-to-find-your-systems">Configuring ASDF to find your systems</a>).
</p>
<p>Once the source code for ASDF is installed,
you don&rsquo;t need any extra step to load it beyond the usual <code>(require &quot;asdf&quot;)</code>:
ASDF 3 will automatically look whether an updated version of itself is available
amongst the regularly configured systems, before it compiles anything else.
</p>
<p>If your implementation fails to provide ASDF 3 or later,
see <a href="#Replacing-your-implementation_0027s-ASDF">Replacing your implementation's ASDF</a>.
</p>
Raymond Toy's avatar
Raymond Toy committed
528

529
530
531
532
<hr>
<a name="Replacing-your-implementation_0027s-ASDF"></a>
<a name="Replacing-your-implementation_0027s-ASDF-1"></a>
<h3 class="section">3.4 Replacing your implementation&rsquo;s ASDF</h3>
Raymond Toy's avatar
Raymond Toy committed
533

534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
<p>All maintained implementations now provide ASDF 3 in their latest release.
If your doesn&rsquo;t, we recommend you upgrade it.
</p>
<p>Now, if you insist on using an old implementation that didn&rsquo;t provide ASDF or provided an old version,
we recommend installing a recent ASDF, as explained below,
into your implementation&rsquo;s installation directory.
Thus your modified implementation will now provide ASDF 3.
This requires proper write permissions and may necessitate execution as a system administrator.
</p>
<p>The ASDF source repository contains a tool to help you upgrade your implementation&rsquo;s ASDF.
You can invoke it from the shell command-line as
<code>tools/asdf-tools install-asdf lispworks</code>
(where you can replace <code>lispworks</code> by the name of the relevant implementation),
or you can <code>(load &quot;tools/install-asdf.lisp&quot;)</code> from your Lisp REPL.
</p>
<p>This script works on
Allegro CL, Clozure CL, CMU CL, ECL, GCL, GNU CLISP, LispWorks, MKCL, SBCL, SCL, XCL.
It doesn&rsquo;t work on ABCL, Corman CL, Genera, MCL, MOCL.
Happily, ABCL is usually pretty up to date and shouldn&rsquo;t need that script.
GCL requires a very recent version, and hasn&rsquo;t been tested much.
Corman CL, Genera, MCL are obsolete anyway.
MOCL is incomplete.
</p>
Raymond Toy's avatar
Raymond Toy committed
557

558
559
560
561
<hr>
<a name="Loading-ASDF-from-source"></a>
<a name="Loading-ASDF-from-source-1"></a>
<h3 class="section">3.5 Loading ASDF from source</h3>
Raymond Toy's avatar
Raymond Toy committed
562

563
564
565
566
567
568
569
570
<p>If you write build scripts that must remain portable to old machines with old implementations
that you cannot ensure have been upgraded or modified to provide a recent ASDF,
you may have to install the file <samp>asdf.lisp</samp>
somewhere and load it with:
</p>
<div class="lisp">
<pre class="lisp">(load &quot;/path/to/your/installed/asdf.lisp&quot;)
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
571

572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
<p>The single file <samp>asdf.lisp</samp> is all you normally need to use ASDF.
</p>
<p>You can extract this file from latest release tarball on the
<a href="https://common-lisp.net/project/asdf/">ASDF website</a>.
If you are daring and willing to report bugs, you can get
the latest and greatest version of ASDF from its git repository.
See <a href="#Getting-the-latest-version">Getting the latest version</a>.
</p>
<p>For scripts that try to use ASDF simply via <code>require</code> at first, and
make heroic attempts to load it the hard way if at first they don&rsquo;t succeed,
see <samp>tools/load-asdf.lisp</samp> distributed with the ASDF source repository,
or the code of <a href="https://cliki.net/cl-launch"><code>cl-launch</code></a>.
</p>

<hr>
<a name="Configuring-ASDF"></a>
<a name="Configuring-ASDF-1"></a>
<h2 class="chapter">4 Configuring ASDF</h2>

<p>For standard use cases, ASDF should work pretty much out of the box.
We recommend you skim the sections on configuring ASDF to find your systems
and choose the method of installing Lisp software that works best for you.
Then skip directly to See <a href="#Using-ASDF">Using ASDF</a>. That will probably be enough.
You are unlikely to have to worry about the way ASDF stores object files,
and resetting the ASDF configuration is usually only needed in corner cases.
</p>
Raymond Toy's avatar
Raymond Toy committed
598
599


600
601
602
603
<hr>
<a name="Configuring-ASDF-to-find-your-systems"></a>
<a name="Configuring-ASDF-to-find-your-systems-1"></a>
<h3 class="section">4.1 Configuring ASDF to find your systems</h3>
Raymond Toy's avatar
Raymond Toy committed
604

605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
<p>In order to compile and load your systems, ASDF must be configured to find
the <samp>.asd</samp> files that contain system definitions.
</p>
<p>There are a number of different techniques for setting yourself up with
ASDF, starting from easiest to the most complex:
</p>
<ul>
<li> Put all of your systems in one of the standard locations,
subdirectories of
<ul>
<li> <samp>~/common-lisp/</samp> or
</li><li> <samp>~/.local/share/common-lisp/source/</samp>.
</li></ul>
<p>If you install software there, you don&rsquo;t need further
configuration.<a name="DOCF2" href="#FOOT2"><sup>2</sup></a>
You can then skip to the next section. See <a href="#Loading-a-system">Loading a system</a>.
</p>
</li><li> If you&rsquo;re using some tool to install software (e.g. Quicklisp),
the authors of that tool should already have configured ASDF.
Raymond Toy's avatar
Raymond Toy committed
624

625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
</li><li> If you have more specific desires about how to lay out your software on
disk, the preferred way to configure where ASDF finds your systems is
the <code>source-registry</code> facility,
fully described in its own chapter of this manual.
See <a href="#Controlling-where-ASDF-searches-for-systems">Controlling where ASDF searches for systems</a>.
Here is a quick recipe for getting started.

<p>First create the directory
<samp>~/.config/common-lisp/source-registry.conf.d/</samp><a name="DOCF3" href="#FOOT3"><sup>3</sup></a>;
there create a file with any name of your choice
but with the type <samp>conf</samp><a name="DOCF4" href="#FOOT4"><sup>4</sup></a>,
for instance <samp>50-luser-lisp.conf</samp>;
in this file, add the following line
to tell ASDF to recursively scan all the subdirectories under <samp>/home/luser/lisp/</samp>
for <samp>.asd</samp> files:
<kbd>(:tree &quot;/home/luser/lisp/&quot;)</kbd>
</p>
<p>That&rsquo;s enough. You may replace <samp>/home/luser/lisp/</samp> by wherever you want to install your source code.
You don&rsquo;t actually need to specify anything if you use the default <samp>~/common-lisp/</samp> as above
and your implementation provides ASDF 3.1.2 or later.
If your implementation provides an earlier variant of ASDF 3,
you might want to specify <kbd>(:tree (:home &quot;common-lisp/&quot;))</kbd> for bootstrap purposes,
then install a recent source tree of ASDF under <samp>~/common-lisp/asdf/</samp>.
</p>
<p>If you prefer to use a &ldquo;link farm&rdquo;, which is faster to use but costlier to manage than a recursive traversal,
say at <samp>/home/luser/.asd-link-farm/</samp>, then
you may instead (or additionally) create a file <samp>42-asd-link-farm.conf</samp>, containing the line:
<kbd>(:directory &quot;/home/luser/.asd-link-farm/&quot;)</kbd>
</p>
<p>ASDF will automatically read your configuration
the first time you try to find a system.
If necessary, you can reset the source-registry configuration with:
</p>
<div class="lisp">
<pre class="lisp">(asdf:clear-source-registry)
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
661

662
663
664
665
666
667
668
669
670
671
</li><li> In earlier versions of ASDF, the system source registry was configured
using a global variable, <code>asdf:*central-registry*</code>.
For more details about this, see the following section,
<a href="#Configuring-ASDF-to-find-your-systems-_002d_002d_002d-old-style">Configuring ASDF to find your systems --- old style</a>.
Unless you need to understand this,
skip directly to <a href="#Configuring-where-ASDF-stores-object-files">Configuring where ASDF stores object files</a>.

</li></ul>

<p>Note that your Operating System distribution or your system administrator
Raymond Toy's avatar
Raymond Toy committed
672
may already have configured system-managed libraries for you.
673
674
</p>

Raymond Toy's avatar
Raymond Toy committed
675

676
677
678
679
<hr>
<a name="Configuring-ASDF-to-find-your-systems-_002d_002d_002d-old-style"></a>
<a name="Configuring-ASDF-to-find-your-systems-_002d_002d_002d-old-style-1"></a>
<h3 class="section">4.2 Configuring ASDF to find your systems &mdash; old style</h3>
Raymond Toy's avatar
Raymond Toy committed
680
681
682



Raymond Toy's avatar
Raymond Toy committed
683
684
<p>Novices may skip this section.
</p>
Raymond Toy's avatar
Raymond Toy committed
685
686
687
<p>The old way to configure ASDF to find your systems is by
<code>push</code>ing directory pathnames onto the variable
<code>asdf:*central-registry*</code>.
688
689
690
</p>
<p>You must configure this variable between the time you load ASDF
and the time you first try to use it.
Raymond Toy's avatar
Raymond Toy committed
691
692
Loading and configuring ASDF presumably happen
as part of some initialization script that builds or starts
693
694
695
696
697
698
699
700
701
your Common Lisp software system.
(For instance, some SBCL users used to put it in their <samp>~/.sbclrc</samp>.)
</p>
<p>The <code>asdf:*central-registry*</code> is empty by default in ASDF 2 or ASDF 3,
but is still supported for compatibility with ASDF 1.
When used, it takes precedence over the above source-registry.<a name="DOCF5" href="#FOOT5"><sup>5</sup></a>
</p>
<p>For example, let&rsquo;s say you want ASDF to find the <samp>.asd</samp> file
<samp>/home/me/src/foo/foo.asd</samp>.
Raymond Toy's avatar
Raymond Toy committed
702
In your Lisp initialization file, you could have the following:
703
704
705
706
707
</p>
<div class="lisp">
<pre class="lisp">(require &quot;asdf&quot;)
(push &quot;/home/me/src/foo/&quot; asdf:*central-registry*)
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
708

709
<p>Note the trailing slash: when searching for a system,
Raymond Toy's avatar
Raymond Toy committed
710
ASDF will evaluate each entry of the central registry
711
712
713
714
715
716
717
718
719
720
and coerce the result to a pathname.<a name="DOCF6" href="#FOOT6"><sup>6</sup></a>
The trailing directory name separator
is necessary to tell Lisp that you&rsquo;re discussing a directory
rather than a file.  If you leave it out, ASDF is likely to look in
<code>/home/me/src/</code> instead of <code>/home/me/src/foo/</code> as you
intended, and fail to find your system definition.
</p>
<p>Typically there are a lot of <samp>.asd</samp> files, and
a common idiom was to put
<em>symbolic links</em> to all of one&rsquo;s <samp>.asd</samp> files
Raymond Toy's avatar
Raymond Toy committed
721
722
in a common directory
and push <em>that</em> directory (the &ldquo;link farm&rdquo;)
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
onto
<code>asdf:*central-registry*</code>,
instead of pushing each individual system directory.
</p>
<p>ASDF knows to follow <em>symlinks</em>
to the actual location of the systems.<a name="DOCF7" href="#FOOT7"><sup>7</sup></a>
</p>
<p>For example, if <code>#p&quot;/home/me/cl/systems/&quot;</code>
is an element of <code>*central-registry*</code>, you could set up the
system <var>foo</var> as follows:
</p>
<div class="example">
<pre class="example">$ cd /home/me/cl/systems/
$ ln -s ~/src/foo/foo.asd .
</pre></div>

<p>This old style for configuring ASDF is not recommended for new users,
but it is supported for old users, and for users who want a simple way to
programmatically control what directories are added to the ASDF search path.
</p>
Raymond Toy's avatar
Raymond Toy committed
743

744
745
746
747
748
<hr>
<a name="Configuring-where-ASDF-stores-object-files"></a>
<a name="Configuring-where-ASDF-stores-object-files-1"></a>
<h3 class="section">4.3 Configuring where ASDF stores object files</h3>
<a name="index-clear_002doutput_002dtranslations"></a>
Raymond Toy's avatar
Raymond Toy committed
749

750
<p>ASDF lets you configure where object files will be stored.
Raymond Toy's avatar
Raymond Toy committed
751
Sensible defaults are provided and
752
753
754
you shouldn&rsquo;t normally have to worry about it.
</p>
<p>This allows the same source code repository to be shared
Raymond Toy's avatar
Raymond Toy committed
755
between several versions of several Common Lisp implementations,
756
757
758
759
760
761
762
between several users using different compilation options,
with users who lack write privileges on shared source directories, etc.
This also keeps source directories from being cluttered
with object/fasl files.
</p>
<p>Starting with ASDF 2, the <code>asdf-output-translations</code> facility
was added to ASDF itself.  This facility controls where object files will be stored.
Raymond Toy's avatar
Raymond Toy committed
763
764
This facility is fully described in a chapter of this manual,
<a href="#Controlling-where-ASDF-saves-compiled-files">Controlling where ASDF saves compiled files</a>.
765
</p>
Raymond Toy's avatar
Raymond Toy committed
766
767
768
769
770
771
772
773
774
775










776
777

<p>Note that before ASDF 2,
Raymond Toy's avatar
Raymond Toy committed
778
779
other ASDF add-ons offered the same functionality,
each in subtly different and incompatible ways:
780
781
ASDF-Binary-Locations, cl-launch, common-lisp-controller.
ASDF-Binary-Locations is now not needed anymore and should not be used.
Raymond Toy's avatar
Raymond Toy committed
782
cl-launch 3.000 and common-lisp-controller 7.2 have been updated
783
784
785
786
787
788
to delegate object file placement to ASDF.
</p>
<hr>
<a name="Resetting-the-ASDF-configuration"></a>
<a name="Resetting-the-ASDF-configuration-1"></a>
<h3 class="section">4.4 Resetting the ASDF configuration</h3>
Raymond Toy's avatar
Raymond Toy committed
789
790
791
792



<p>When you dump and restore an image, or when you tweak your configuration,
793
you may want to reset the ASDF configuration.
Raymond Toy's avatar
Raymond Toy committed
794
For that you may use the following function:
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
</p>
<dl>
<dt><a name="index-clear_002dconfiguration"></a>Function: <strong>clear-configuration</strong></dt>
<dd><p>Undoes any ASDF configuration
   regarding source-registry or output-translations.
</p></dd></dl>

<a name="index-_002aimage_002ddump_002dhook_002a"></a>
<p>This function is pushed onto the <code>uiop:*image-dump-hook*</code> by default,
which means that if you save an image using <code>uiop:dump-image</code>,
or via <code>asdf:image-op</code> and <code>asdf:program-op</code>,
it will be automatically called to clear your configuration.
If for some reason you prefer to call your implementation&rsquo;s underlying functionality,
be sure to call <code>clear-configuration</code> manually,
or push it into your implementation&rsquo;s equivalent of <code>uiop:*image-dump-hook*</code>,
e.g. <code>sb-ext:*save-hooks*</code> on SBCL, or <code>ext:*before-save-initializations*</code>
on CMUCL and SCL, etc.
</p>
<hr>
<a name="Using-ASDF"></a>
<a name="Using-ASDF-1"></a>
<h2 class="chapter">5 Using ASDF</h2>
Raymond Toy's avatar
Raymond Toy committed
817
818


819
820
821
822
<hr>
<a name="Loading-a-system"></a>
<a name="Loading-a-system-1"></a>
<h3 class="section">5.1 Loading a system</h3>
Raymond Toy's avatar
Raymond Toy committed
823
824
825

<p>The system <var>foo</var> is loaded (and compiled, if necessary)
by evaluating the following Lisp form:
826
827
828
829
</p>
<div class="example">
<pre class="example">(asdf:load-system :<var>foo</var>)
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
830

831
832
833
834
835
836
<p>On some implementations (see <a href="#Convenience-Functions">Convenience Functions</a>),
ASDF hooks into the <code>cl:require</code> facility and you can just use:
</p>
<div class="example">
<pre class="example">(require :<var>foo</var>)
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
837

838
839
840
<p>Note that the canonical name of a system is a string, conventionally lowercase.
A system name can also be specified as a symbol (including a keyword),
in which case its <code>symbol-name</code> is taken and lowercased.
Raymond Toy's avatar
Raymond Toy committed
841
The name must be a suitable value for the <code>:name</code> initarg
842
843
844
845
846
847
848
849
to <code>make-pathname</code> in whatever filesystem the system is to be found.
</p>
<p>The lower-casing-symbols behaviour is unconventional,
but was selected after some consideration.
The type of systems we want to support
either have lowercase as customary case (Unix, Mac, Windows)
or silently convert lowercase to uppercase (lpns).
</p>
Raymond Toy's avatar
Raymond Toy committed
850

851
852
853
854
855
<hr>
<a name="Convenience-Functions"></a>
<a name="Convenience-Functions-1"></a>
<h3 class="section">5.2 Convenience Functions</h3>

Raymond Toy's avatar
Raymond Toy committed
856
857

<p>ASDF provides three commands for the most common system operations:
858
859
<code>load-system</code>, <code>compile-system</code>, and <code>test-system</code>.
</p>
Raymond Toy's avatar
Raymond Toy committed
860
861
862
863
864
865
866
867
868
869
870
871
872
<p>ASDF also provides <code>require-system</code>, a variant of <code>load-system</code>
that skips loading systems that are already loaded.  This is sometimes
useful, for example, in order to avoid re-loading libraries that come
pre-loaded into your  lisp implementation.
</p>
<p>ASDF also provides <code>make</code>, a way of allowing system developers to
choose a default operation for their systems.  For example, a developer
who has created a system intended to format a specific document, might
make document-formatting the default operation invoked by <code>make</code>,
instead of loading.  If the system developer doesn&rsquo;t specify in the
system definition, the default operation will be loading.
</p>

873
874
875

<a name="index-operate"></a>
<a name="index-oos"></a>
Raymond Toy's avatar
Raymond Toy committed
876

877
<p>Because ASDF is an extensible system
Raymond Toy's avatar
Raymond Toy committed
878
for defining <em>operations</em> on <em>components</em>,
879
880
881
882
883
it also provides a generic function <code>operate</code>,
so you may arbitrarily operate on your systems beyond the default operations.
(At the interactive REPL, users often use its shorter alias <code>oos</code>,
which stands for operate-on-system, a name inherited from <code>mk-defsystem</code>.)
You&rsquo;ll use <code>operate</code> whenever you want to do something beyond
Raymond Toy's avatar
Raymond Toy committed
884
compiling, loading and testing.
885
</p>
Raymond Toy's avatar
Raymond Toy committed
886
887


888
889
<a name="index-_002aload_002dsystem_002doperation_002a"></a>
<a name="index-already_002dloaded_002dsystems"></a>
Raymond Toy's avatar
Raymond Toy committed
890
891
892
893

<dl>
<dt><a name="index-load_002dsystem"></a>Function: <strong>load-system</strong> <em>system &amp;rest keys &amp;key force force-not verbose version &amp;allow-other-keys</em></dt>
<dd><p>Apply <code>operate</code> with the operation from
894
<code>*load-system-operation*</code>
Raymond Toy's avatar
Raymond Toy committed
895
the <var>system</var>, and any provided keyword arguments.
896
<code>*load-system-operation*</code> by default is <code>load-op</code>;
Raymond Toy's avatar
Raymond Toy committed
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
it would be <code>load-bundle-op</code> by default on ECL,
if only an implementation bug were fixed.
Calling <code>load-system</code> is the regular, recommended way
to load a system into the current image.
</p></dd></dl>

<dl>
<dt><a name="index-compile_002dsystem"></a>Function: <strong>compile-system</strong> <em>system &amp;rest keys &amp;key force force-not verbose version &amp;allow-other-keys</em></dt>
<dd><p>Apply <code>operate</code> with the operation <code>compile-op</code>,
the <var>system</var>, and any provided keyword arguments.
This will make sure all the files in the system are compiled,
but not necessarily load any of them in the current image;
on most systems, it will <em>not</em> load all compiled files in the current image.
This function exists for symmetry with <code>load-system</code> but is not recommended
unless you are writing build scripts and know what you&rsquo;re doing.
But then, you might be interested in <code>program-op</code> rather than <code>compile-op</code>.
</p></dd></dl>

<dl>
<dt><a name="index-test_002dsystem"></a>Function: <strong>test-system</strong> <em>system &amp;rest keys &amp;key force force-not verbose version &amp;allow-other-keys</em></dt>
<dd><p>Apply <code>operate</code> with the operation <code>test-op</code>,
the <var>system</var>, and any provided keyword arguments.
See <a href="#test_002dop">test-op</a>.
</p></dd></dl>

<dl>
<dt><a name="index-make"></a>Function: <strong>make</strong> <em>system &amp;rest keys &amp;key &amp;allow-other-keys</em></dt>
<dd><p>Do &ldquo;The Right Thing&rdquo; with your system.
Starting with ASDF 3.1, this function <code>make</code> is also available.
The default behaviour is to load the system as if by <code>load-system</code>;
but system authors can override this default in their system definition
they may specify an alternate operation as the intended use of their system,
with a <code>:build-operation</code> option in the <code>defsystem</code> form
(see <a href="#The-defsystem-grammar">build-operation</a>),
and an intended output pathname for that operation with
<code>:build-pathname</code>.
This function is experimental and largely untested.  Use at your own risk.
</p></dd></dl>
<a name="index-build_002doperation"></a>

<dl>
<dt><a name="index-require_002dsystem"></a>Function: <strong>require-system</strong> <em>system &amp;rest keys &amp;key &amp;allow-other-keys</em></dt>
<dd><p><code>require-system</code> skips any update to systems that have already been loaded,
940
in the spirit of <code>cl:require</code>.
Raymond Toy's avatar
Raymond Toy committed
941
942
It does it by calling <code>load-system</code> with a keyword option
excluding already loaded systems.<a name="DOCF8" href="#FOOT8"><sup>8</sup></a>.
943
944
945
946
947
On actively maintained free software implementations
(namely recent versions of ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL),
once ASDF itself is loaded, <code>cl:require</code> too can load ASDF systems,
by falling back on <code>require-system</code>
for module names not recognized by the implementation.
Raymond Toy's avatar
Raymond Toy committed
948
949
(Note however that <code>require-system</code> does <em>not</em> fall back on <code>cl:require</code>;
that would introduce an &ldquo;interesting&rdquo; potential infinite loop to break somehow.)
950
</p>
Raymond Toy's avatar
Raymond Toy committed
951
<p><code>cl:require</code> and <code>require-system</code> are appropriate to load code
952
that is not being modified during the current programming session.
Raymond Toy's avatar
Raymond Toy committed
953
954
955
956
957
958
959
960
<code>cl:require</code> will notably load the implementation-provided extension modules;
<code>require-system</code> won&rsquo;t, unless they are also defined as systems somehow,
which SBCL and MKCL do.
<code>require-system</code> may also be used to load any number of ASDF systems
that the user isn&rsquo;t either developing or debugging,
for which a previously installed version is deemed to be satisfactory;
<code>cl:require</code> on the above-mentioned implementations will delegate to <code>require-system</code>
and may load them as well.
961
962
But for code that you are actively developing, debugging, or otherwise modifying,
you should use <code>load-system</code>, so ASDF will pick on your modifications
Raymond Toy's avatar
Raymond Toy committed
963
964
965
966
967
968
and transitively re-build the modified files and everything that depends on them
(that the requested <var>system</var> itself depends on &mdash;
ASDF itself never builds anything unless
it&rsquo;s an explicitly requested system or the dependencies thereof).
</p></dd></dl>

Raymond Toy's avatar
Raymond Toy committed
969

970
971
972
973
<hr>
<a name="Moving-on"></a>
<a name="Moving-on-1"></a>
<h3 class="section">5.3 Moving on</h3>
Raymond Toy's avatar
Raymond Toy committed
974

975
<p>That&rsquo;s all you need to know to use ASDF to load systems written by others.
Raymond Toy's avatar
Raymond Toy committed
976
977
978
The rest of this manual deals with writing system definitions
for Common Lisp software you write yourself,
including how to extend ASDF to define new operation and component types.
979
</p>
Raymond Toy's avatar
Raymond Toy committed
980

981
982
983
984
<hr>
<a name="Defining-systems-with-defsystem"></a>
<a name="Defining-systems-with-defsystem-1"></a>
<h2 class="chapter">6 Defining systems with defsystem</h2>
Raymond Toy's avatar
Raymond Toy committed
985

986
<p>This chapter describes how to use ASDF to define systems and develop
Raymond Toy's avatar
Raymond Toy committed
987
software.
988
</p>
Raymond Toy's avatar
Raymond Toy committed
989
990


991
992
993
994
995
996
997
998
999
<hr>
<a name="The-defsystem-form"></a>
<a name="The-defsystem-form-1"></a>
<h3 class="section">6.1 The defsystem form</h3>
<a name="index-defsystem"></a>
<a name="index-asdf_002duser"></a>
<a name="index-load_002dasd"></a>

<p>This section begins with an example of a system definition,
Raymond Toy's avatar
Raymond Toy committed
1000
then gives the full grammar of <code>defsystem</code>.
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
</p>
<p>Let&rsquo;s look at a simple system.
This is a complete file that should be saved as <samp>hello-lisp.asd</samp>
(in order that ASDF can find it
when ordered to operate on the system named <code>&quot;hello-lisp&quot;</code>).
</p>
<div class="lisp">
<pre class="lisp">;; Usual Lisp comments are allowed here

(defsystem &quot;hello-lisp&quot;
  :description &quot;hello-lisp: a sample Lisp system.&quot;
  :version &quot;0.0.1&quot;
  :author &quot;Joe User &lt;joe@example.com&gt;&quot;
  :licence &quot;Public Domain&quot;
  :depends-on (&quot;optima.ppcre&quot; &quot;command-line-arguments&quot;)
  :components ((:file &quot;packages&quot;)
               (:file &quot;macros&quot; :depends-on (&quot;packages&quot;))
               (:file &quot;hello&quot; :depends-on (&quot;macros&quot;))))
</pre></div>

<p>Some notes about this example:
</p>
<ul>
<li> The <code>defsystem</code> form defines a system named <code>hello-lisp</code>
Raymond Toy's avatar
Raymond Toy committed
1025
that contains three source files:
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
<samp>packages.lisp</samp>, <samp>macros.lisp</samp> and <samp>hello.lisp</samp>.

</li><li> The <samp>.lisp</samp> suffix is implicit for Lisp source files.
The source files are located in the same directory
as the <code>.asd</code> file with the system definition.

</li><li> The file <samp>macros</samp> depends on <samp>packages</samp>
(presumably because the package it&rsquo;s in is defined in <samp>packages</samp>),
and the file <samp>hello</samp> depends on <samp>macros</samp>
(and hence, transitively on <samp>packages</samp>).
This means that ASDF will compile and load <samp>packages</samp> then <samp>macros</samp>
before starting the compilation of file <samp>hello</samp>.

</li><li> This example system has external dependencies on two other systems,
<code>optima.ppcre</code> (that provides a friendly interface to matching regular expressions),
and <code>command-line-arguments</code> (that provides a way to parse arguments passed from the shell command line).
To use this system, ASDF must be configured to find installed copies of these systems;
it will load them before it tries to compile and load <code>hello-lisp</code>.

</li><li> This system also defines a bunch of metadata.
While it is optional to define these fields
(and other fields like <code>:bug-tracker</code>, <code>:mailto</code>, <code>:long-name</code>,
<code>:long-description</code>, <code>:source-control</code>),
it is strongly recommended to define the fields <code>:description</code>, <code>:version</code>, <code>:author</code>, and <code>:licence</code>,
especially if you intend your software to be eventually included in Quicklisp.

</li><li> Make sure you know how the <code>:version</code> numbers will be parsed!
Only period-separated non-negative integers are accepted at present.
See below Version specifiers in <a href="#The-defsystem-grammar">The defsystem grammar</a>.

</li><li> This file contains a single form, the <code>defsystem</code> declaration.
No <code>in-package</code> form, no <code>asdf:</code> package prefix, no nothing.
Just the one naked <code>defsystem</code> form.
This is what we recommend.
More complex system definition files are possible with arbitrary Lisp code,
but we recommend that you keep it simple if you can.
This will make your system definitions more robust and more future-proof.

<a name="index-_003aversion"></a>
Raymond Toy's avatar
Raymond Toy committed
1065

1066
</li></ul>
Raymond Toy's avatar
Raymond Toy committed
1067

1068
1069
1070
1071
<p>This is all you need to know to define simple systems.
The next example is much more involved, to give you a glimpse of how you can do more complex things.
However, since it&rsquo;s ultimately arbitrary Lisp code, there is no bottom to the rabbit hole.
</p>
Raymond Toy's avatar
Raymond Toy committed
1072

1073
1074
1075
1076
1077
<hr>
<a name="A-more-involved-example"></a>
<a name="A-more-involved-example-1"></a>
<h3 class="section">6.2 A more involved example</h3>
<a name="index-defsystem-1"></a>
Raymond Toy's avatar
Raymond Toy committed
1078

1079
<p>Let&rsquo;s illustrate some more involved uses of <code>defsystem</code> via a
Raymond Toy's avatar
Raymond Toy committed
1080
slightly convoluted example:
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
</p>
<div class="lisp">
<pre class="lisp">(in-package :asdf-user)

(defsystem &quot;foo&quot;
  :version (:read-file-form &quot;variables&quot; :at (3 2))
  :components
  ((:file &quot;package&quot;)
   (:file &quot;variables&quot; :depends-on (&quot;package&quot;))
   (:module &quot;mod&quot;
     :depends-on (&quot;package&quot;)
     :serial t
     :components ((:file &quot;utils&quot;)
                  (:file &quot;reader&quot;)
                  (:file &quot;cooker&quot;)
                  (:static-file &quot;data.raw&quot;))
     :output-files (compile-op (o c) (list &quot;data.cooked&quot;))
     :perform (compile-op :after (o c)
        (cook-data
         :in (component-pathname (find-component c &quot;data.raw&quot;))
         :out (first (output-files o c)))))
   (:file &quot;foo&quot; :depends-on (&quot;mod&quot;))))

(defmethod action-description
    ((o compile-op) (c (eql (find-component &quot;foo&quot; &quot;mod&quot;))))
  &quot;cooking data&quot;)
</pre></div>

<p>Here are some notes about this example:
</p>
<ul>
<li> The main thing this file does is define a system <code>foo</code>.
It also contains other Lisp forms, which we&rsquo;ll examine below.
Raymond Toy's avatar
Raymond Toy committed
1114

1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
</li><li> Besides Lisp source files, this system contains a <code>:module</code> component
named <code>&quot;mod&quot;</code>, which is a collection of three Lisp source files
<samp>utils.lisp</samp>, <samp>reader.lisp</samp>, <samp>cooker.lisp</samp> and <samp>data.raw</samp>

</li><li> Note that the <code>:static-file</code> does not have an implicit file type,
unlike the Lisp source files.

</li><li> This files will be located in a subdirectory of the main code directory named
<samp>mod/</samp> (this location could have been overridden to be
in the same directory, or in a different subdirectory;
see the discussion of the <code>:pathname</code> option in <a href="#The-defsystem-grammar">The defsystem grammar</a>).
Raymond Toy's avatar
Raymond Toy committed
1126

1127
1128
1129
1130
1131
1132
1133
</li><li> The <code>:serial t</code> says that each sub-component of <code>mod</code> depends on the previous components,
so that <samp>cooker.lisp</samp> depends-on <samp>utils.lisp</samp>, which depends-on <samp>reader.lisp</samp>.
Also <samp>data.raw</samp> depends on all of them, but that doesn&rsquo;t matter since it&rsquo;s a static file;
on the other hand, if it appeared first, then all the Lisp files would be recompiled
when the data is modified, which is probably not what is desired in this case.

</li><li> The method-form tokens provide a shorthand for defining methods on
Raymond Toy's avatar
Raymond Toy committed
1134
1135
particular components.  This part

1136
1137
1138
1139
1140
1141
1142
<div class="lisp">
<pre class="lisp">     :output-files (compile-op (o c) (list &quot;data.cooked&quot;))
     :perform (compile-op :after (o c)
        (cook-data
         :in (component-pathname (find-component c &quot;data.raw&quot;))
         :out (first (output-files o c))))
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
1143

1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
<p>has the effect of
</p>
<div class="lisp">
<pre class="lisp">(defmethod output-files ((o compile-op) (c (eql ...)))
  (list &quot;data.cooked&quot;))
(defmethod perform :after ((o compile-op) (c (eql ...)))
  (cook-data
   :in (component-pathname (find-component c &quot;data.raw&quot;))
   :out (first (output-files o c))))
</pre></div>

<p>where <code>...</code> is the component in question.
Raymond Toy's avatar
Raymond Toy committed
1156
In this case <code>...</code> would expand to something like
1157
1158
1159
1160
</p>
<div class="lisp">
<pre class="lisp">(find-component &quot;foo&quot; &quot;mod&quot;)
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
1161

1162
1163
<p>For more details on the syntax of such forms,
see <a href="#The-defsystem-grammar">The defsystem grammar</a>.
Raymond Toy's avatar
Raymond Toy committed
1164
1165
For more details on what these methods do, see <a href="#Operations">Operations</a> in
<a href="#The-object-model-of-ASDF">The object model of ASDF</a>.
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
</p>
</li><li> There is an additional <code>defmethod</code> with a similar effect,
because ASDF (as of ASDF 3.1.5)
fails to accept inline-methods as above for <code>action-description</code>,
instead only supporting the deprecated <code>explain</code> interface.


</li><li> In this case, these methods describe how this module defines code
that it then uses to cook some data.

</li><li> Importantly, ASDF is told about the input and output files
used by the data cooker,
and to make sure everyone agrees,
the cooking function explicitly uses ASDF to access pathnames
to the input and output data.


</li><li> The file starts with a form <code>(in-package :asdf-user)</code>,
but it is actually redundant, not necessary and not recommended.
But yet more complex cases (also not recommended) may usefully use an <code>in-package</code> form.

</li><li> Indeed, ASDF does not load <samp>.asd</samp> files simply with <code>cl:load</code>,
and neither should you.
You should let ASDF find and load them when you operate on systems.
If you somehow <em>must</em> load a <samp>.asd</samp> file,
use the same function <code>asdf:load-asd</code> that ASDF uses.
Among other things, it already binds the <code>*package*</code> to <code>asdf-user</code>.
Recent versions of SLIME (2013-02 and later) know to do that when you <kbd>C-c C-k</kbd>
when you use the <code>slime-asdf</code> contrib.

</li><li> You shouldn&rsquo;t use an <code>in-package</code> form
if you&rsquo;re keeping things simple.
You should only use <code>in-package</code> (and before it, a <code>defpackage</code>)
when you&rsquo;re going to define new classes, functions, variables, macros, etc.,
in the <code>.asd</code> file, and want to thereby avoid name clashes.
Manuals for old versions of ASDF recommended use of such an idiom in <samp>.asd</samp> files,
but as of ASDF 3, we recommend that you don&rsquo;t do that anymore,
and instead define any ASDF extensions in their own system,
on which you can then declare a dependency using <code>:defsystem-depends-on</code>.
See <a href="#The-defsystem-grammar">The defsystem grammar</a>.

</li><li> More generally, you can always rely on symbols
from packages <code>asdf</code>, <code>common-lisp</code> and <code>uiop</code>
being available in <code>.asd</code> files &mdash;
most importantly including <code>defsystem</code>.
It is therefore redundant and in bad taste to use a package-prefixed <code>asdf:defsystem</code> symbol
in a <samp>.asd</samp> file.
Just use <code>(defsystem ...)</code>.
Only package-prefix it when somehow dynamically generating system definitions
from a package that doesn&rsquo;t already use the ASDF package.

</li><li> <code>asdf-user</code> is actually only available starting since ASDF 3, but then again,
ASDF 1 and 2 did crazy things with packages that ASDF 3 has stopped doing<a name="DOCF9" href="#FOOT9"><sup>9</sup></a>,
and since all implementations provide ASDF 3, you shouldn&rsquo;t care about compatibility with ASDF 2.
We do not support ASDF 2 anymore, and we recommend that neither should you.

</li><li> Starting with ASDF 3.1, <code>asdf-user</code> uses <code>uiop</code>,
whereas in earlier variants of ASDF 3 it only used <code>uiop/package</code>.
We recommend you either prefix use of UIOP functions with the package prefix <code>uiop:</code>,
or make sure your system <code>:depends-on ((:version &quot;asdf&quot; &quot;3.1.2&quot;))</code>
or has a <code>#-asdf3.1 (error &quot;MY-SYSTEM requires ASDF 3.1.2&quot;)</code>.

</li><li> Finally, we elided most metadata, but showed how you can have ASDF automatically extract
the system&rsquo;s version from a source file. In this case, the 3rd subform of the 4th form
(note that Lisp uses 0-based indexing, English uses 1-based indexing).
Presumably, the 4th form looks like <code>(defparameter *foo-version* &quot;5.6.7&quot;)</code>.

</li></ul>


<hr>
<a name="The-defsystem-grammar"></a>
<a name="The-defsystem-grammar-1"></a>
<h3 class="section">6.3 The defsystem grammar</h3>
<a name="index-defsystem-2"></a>
<a name="index-DEFSYSTEM-grammar"></a>



<div class="example">
<pre class="example">system-definition := ( defsystem system-designator <var>system-option</var>* )

system-option := :defsystem-depends-on system-list
                 | :weakly-depends-on <var>system-list</var>
                 | :class class-name (see discussion below)
Raymond Toy's avatar
Raymond Toy committed
1251
                 | :build-operation <var>operation-name</var>
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
                 | system-option
                 | module-option
                 | option

# These are only available since ASDF 3 (actually its alpha release 2.27)
system-option := :homepage string
                 | :bug-tracker string
                 | :mailto string
                 | :long-name string
                 | :source-control source-control
                 | :version version-specifier

source-control := (keyword string)

module-option := :components component-list
                 | :serial [ t | nil ]

option :=
        | :pathname pathname-specifier
        | :default-component-class class-name
        | :perform method-form
        | :explain method-form
        | :output-files method-form
        | :operation-done-p method-form
        | :if-feature feature-expression
        | :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 := :module | :file | :static-file | other-component-type

other-component-type := symbol-by-name
                        (see <a href="#The-defsystem-grammar">Component types</a>)

# This is used in :depends-on, as opposed to ``dependency,''
# which is used in :in-order-to
dependency-def := simple-component-name
               | ( :feature <var>feature-expression</var> dependency-def )
Raymond Toy's avatar
Raymond Toy committed
1296
                 # (see <a href="#The-defsystem-grammar">Feature dependencies</a>)
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
               | ( :version simple-component-name version-specifier )
               | ( :require module-name )

# ``dependency'' is used in :in-order-to, as opposed to
# ``dependency-def''
dependency := (dependent-op <var>requirement</var>+)
requirement := (required-op <var>required-component</var>+)
dependent-op := operation-name
required-op := operation-name

simple-component-name := string
                      |  symbol

pathname-specifier := pathname | string | symbol

method-form := (operation-name qual lambda-list &amp;rest body)
1313
qual := method qualifier?
1314
1315
1316
1317
1318
1319
1320

feature-expression := keyword
                      | (:and <var>feature-expression</var>*)
                      | (:or <var>feature-expression</var>*)
                      | (:not <var>feature-expression</var>)
</pre></div>

Raymond Toy's avatar
Raymond Toy committed
1321

1322
1323
<a name="Component-names"></a>
<h4 class="subsection">6.3.1 Component names</h4>
Raymond Toy's avatar
Raymond Toy committed
1324
1325
1326

<p>Component names (<code>simple-component-name</code>)
may be either strings or symbols.
1327
1328
1329
</p>
<a name="Component-types"></a>
<h4 class="subsection">6.3.2 Component types</h4>
Raymond Toy's avatar
Raymond Toy committed
1330
1331
1332
1333
1334
1335

<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>.
1336
1337
</p>
<p><code>system</code> and its subclasses are <em>not</em>
Raymond Toy's avatar
Raymond Toy committed
1338
allowed as component types for such children components.
1339
1340
1341
</p>
<a name="System-class-names"></a>
<h4 class="subsection">6.3.3 System class names</h4>
Raymond Toy's avatar
Raymond Toy committed
1342
1343
1344

<p>A system class name will be looked up
in the same way as a Component type (see above),
1345
except that only <code>system</code> and its subclasses are allowed.
Raymond Toy's avatar
Raymond Toy committed
1346
1347
1348
1349
1350
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
1351
1352
1353
1354
</p>
<div class="example">
<pre class="example">:class :MY-NEW-SYSTEM-SUBCLASS
</pre></div>
Raymond Toy's avatar
Raymond Toy committed
1355

1356
<p>This practice will ensure that package name conflicts are avoided.
Raymond Toy's avatar
Raymond Toy committed
1357
1358
1359
1360
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.
1361
1362
1363
1364
</p>
<a name="Defsystem-depends-on"></a>
<h4 class="subsection">6.3.4 Defsystem depends on</h4>
<a name="index-_003adefsystem_002ddepends_002don"></a>
Raymond Toy's avatar
Raymond Toy committed
1365

1366
<p>The <code>:defsystem-depends-on</code> option to <code>defsystem</code> allows the
Raymond Toy's avatar
Raymond Toy committed
1367
programmer to specify another ASDF-defined system or set of systems that
1368
must be loaded <em>before</em> the system definition is processed.
Raymond Toy's avatar
Raymond Toy committed
1369
1370
Typically this is used to load an ASDF extension that is used in the
system definition.
1371
</p>
Raymond Toy's avatar
Raymond Toy committed
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
<a name="Build_002doperation"></a>
<h4 class="subsection">6.3.5 Build-operation</h4>
<a name="index-_003abuild_002doperation"></a>

<p>The <code>:build-operation</code> option to <code>defsystem</code> allows the
programmer to specify an operation that will be applied, in place of
<code>load-op</code> when <code>make</code> (see <a href="#Convenience-Functions">make</a>)
is run on the system.    The option
value should be the name of an operation.  E.g., <code>:build-operation doc-op</code>
</p>
<p>This feature is
experimental and largely untested.  Use at your own risk.
</p>
1385
<a name="Weakly-depends-on"></a>
Raymond Toy's avatar
Raymond Toy committed
1386
<h4 class="subsection">6.3.6 Weakly depends on</h4>
1387
<a name="index-_003aweakly_002ddepends_002don"></a>
Raymond Toy's avatar
Raymond Toy committed
1388

1389
<p>We do <em>NOT</em> recommend you use this feature.
Raymond Toy's avatar
Raymond Toy committed
1390
1391
1392
1393
If you are tempted to write a system <var>foo</var>
that weakly-depends-on a system <var>bar</var>,
we recommend that you should instead
write system <var>foo</var> in a parametric way,
1394
and offer some special variable and/or some hook to specialize its behaviour;
Raymond Toy's avatar
Raymond Toy committed
1395
1396
then you should write a system <var>foo+bar</var>
that does the hooking of things together.
1397
1398
</p>
<p>The (deprecated) <code>:weakly-depends-on</code> option to <code>defsystem</code>
Raymond Toy's avatar
Raymond Toy committed
1399
1400
allows the programmer to specify another ASDF-defined system or set of systems
that ASDF should <em>try</em> to load,
1401
but need not load in order to be successful.
Raymond Toy's avatar
Raymond Toy committed
1402
1403
1404
Typically this is used if there are a number of systems
that, if present, could provide additional functionality,
but which are not necessary for basic function.
1405
1406
</p>
<p>Currently, although it is specified to be an option only to <code>defsystem</code>,
Raymond Toy's avatar
Raymond Toy committed
1407
this option is accepted at any component, but it probably
1408
only makes sense at the <code>defsystem</code> level.
Raymond Toy's avatar
Raymond Toy committed
1409
1410
Programmers are cautioned not
to use this component option except at the <code>defsystem</code> level, as
1411
1412
this anomalous behaviour may be removed without warning.
</p>
Raymond Toy's avatar
Raymond Toy committed
1413
1414


1415
<a name="Pathname-specifiers"></a>
Raymond Toy's avatar
Raymond Toy committed
1416
<h4 class="subsection">6.3.7 Pathname specifiers</h4>
1417
<a name="index-pathname-specifiers"></a>
Raymond Toy's avatar
Raymond Toy committed
1418

1419
1420
<p>A pathname specifier (<code>pathname-specifier</code>)
may be a pathname, a string or a symbol.
Raymond Toy's avatar
Raymond Toy committed
1421
1422
When no pathname specifier is given for a component,
which is the usual case, the component name itself is used.
1423
1424
</p>
<p>If a string is given, which is the usual case,
Raymond Toy's avatar
Raymond Toy committed
1425
the string will be interpreted as a Unix-style pathname
1426
where <code>/</code> characters will be interpreted as directory separators.
Raymond Toy's avatar
Raymond Toy committed
1427
1428
Usually, Unix-style relative pathnames are used
(i.e. not starting with <code>/</code>, as opposed to absolute pathnames);
1429
they are relative to the path of the parent component.
Raymond Toy's avatar
Raymond Toy committed
1430
1431
Finally, depending on the <code>component-type</code>,
the pathname may be interpreted as either a file or a directory,
1432
and if it&rsquo;s a file,
Raymond Toy's avatar
Raymond Toy committed
1433
1434
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).
1435
1436
1437
1438
</p>
<p>For instance, the <code>component-type</code> <code>:module</code>
wants a directory pathname, and so a string <code>&quot;foo/bar&quot;</code>
will be interpreted as the pathname <samp>#p&quot;foo/bar/&quot;</samp>.
Raymond Toy's avatar
Raymond Toy committed
1439
On the other hand, the <code>component-type</code> <code>:file</code>
1440
1441
1442
1443
wants a file of type <code>lisp</code>, and so a string <code>&quot;foo/bar&quot;</code>
will be interpreted as the pathname <samp>#p&quot;foo/bar.lisp&quot;</samp>,
and a string <code>&quot;foo/bar.quux&quot;</code>
will be interpreted as the pathname <samp>#p&quot;foo/bar.quux.lisp&quot;</samp>.
Raymond Toy's avatar
Raymond Toy committed
1444
Finally, the <code>component-type</code> <code>:static-file</code>
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
wants a file without specifying a type, and so a string <code>&quot;foo/bar&quot;</code>
will be interpreted as the pathname <samp>#p&quot;foo/bar&quot;</samp>,
and a string <code>&quot;foo/bar.quux&quot;</code>
will be interpreted as the pathname <samp>#p&quot;foo/bar.quux&quot;</samp>.
</p>
<p>ASDF interprets the string <code>&quot;..&quot;</code>
as the pathname directory component word <code>:back</code>,
which when merged, goes back one level in the directory hierarchy.
</p>
<p>If a symbol is given, it will be translated into a string,
and downcased in the process.
Raymond Toy's avatar
Raymond Toy committed
1456
The downcasing of symbols is unconventional,
1457
but was selected after some consideration.
Raymond Toy's avatar
Raymond Toy committed
1458
1459
1460
1461
1462
1463
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.
1464
1465
</p>
<p>Pathname objects may be given to override the path for a component.
Raymond Toy's avatar
Raymond Toy committed
1466
Such objects are typically specified using reader macros such as <code>#p</code>
1467
or <code>#.(make-pathname ...)</code>.
Raymond Toy's avatar
Raymond Toy committed
1468
1469
Note however, that <code>#p...</code> is
a shorthand for <code>#.(parse-namestring ...)</code>
1470
and that the behaviour of <code>parse-namestring</code> is completely non-portable,
Raymond Toy's avatar
Raymond Toy committed
1471
unless you are using Common Lisp <code>logical-pathname</code>s,
1472
1473
which themselves involve other non-portable behaviour
(see <a href="#The-defsystem-grammar">Using logical pathnames</a>, below).
Raymond Toy's avatar
Raymond Toy committed
1474
Pathnames made with <code>#.(make-pathname ...)</code>
1475
can usually be done more easily with the string syntax above.
Raymond Toy's avatar
Raymond Toy committed
1476
The only case that you really need a pathname object is to override
1477
1478
1479
the component-type default file type for a given component.
Therefore, pathname objects should only rarely be used.
Unhappily, ASDF 1 used not to properly support
Raymond Toy's avatar
Raymond Toy committed
1480
parsing component names as strings specifying paths with directories,
1481
and the cumbersome <code>#.(make-pathname ...)</code> syntax had to be used.
Raymond Toy's avatar
Raymond Toy committed
1482
1483
An alternative to <code>#.</code> read-time evaluation is to use
<code>(eval `(defsystem ... ,pathname ...))</code>.
1484
1485
</p>
<p>Note that when specifying pathname objects,
Raymond Toy's avatar
Raymond Toy committed
1486
1487
ASDF does not do any special interpretation of the pathname
influenced by the component type, unlike the procedure for
1488
pathname-specifying strings.
Raymond Toy's avatar
Raymond Toy committed
1489
1490
1491
1492
1493
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.
1494
1495
</p>
<a name="Version-specifiers"></a>
Raymond Toy's avatar
Raymond Toy committed
1496
<h4 class="subsection">6.3.8 Version specifiers</h4>
1497
1498
1499
1500
1501
1502
1503
1504
1505
<a name="index-version-specifiers"></a>
<a name="index-_003aversion-1"></a>

<p>Version specifiers are strings to be parsed as period-separated lists of integers.
I.e., in the example, <code>&quot;0.2.1&quot;</code> is to be interpreted,
roughly speaking, as <code>(0 2 1)</code>.
In particular, version <code>&quot;0.2.1&quot;</code> is interpreted the same as <code>&quot;0.0002.1&quot;</code>,
though the latter is not canonical and may lead to a warning being issued.
Also, <code>&quot;1.3&quot;</code> and <code>&quot;1.4&quot;</code> are both strictly <code>uiop:version&lt;</code> to <code>&quot;1.30&quot;</code>,
Raymond Toy's avatar
Raymond Toy committed
1506
1507
quite unlike what would have happened
had the version strings been interpreted as decimal fractions.
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
</p>
<p>Instead of a string representing the version,
the <code>:version</code> argument can be an expression that is resolved to
such a string using the following trivial domain-specific language:
in addition to being a literal string, it can be an expression of the form
<code>(:read-file-form &lt;pathname-or-string&gt; :at &lt;access-at-specifier&gt;)</code>,
which will be resolved by reading a form in the specified pathname
(read as a subpathname of the current system if relative or a unix-namestring).
You may use a <code>uiop:access-at</code> specifier
with the (optional) <code>:at</code> keyword,
by default the specifier is <code>0</code>, meaning the first form is returned;
subforms can also be specified, with e.g. <code>(1 2 2)</code> specifying
&ldquo;the third subform (index 2) of the third subform (index 2) of the second form (index 1)&rdquo;
in the file (mind the off-by-one error in the English language).
</p>
<p>System definers are encouraged to use version identifiers of the form
Raymond Toy's avatar
Raymond Toy committed
1524
1525
1526
<var>x</var>.<var>y</var>.<var>z</var> for
major version, minor version and patch level,
where significant API incompatibilities are signaled by an increased major number.
1527
1528
1529
1530
</p>
<p>See <a href="#Common-attributes-of-components">Common attributes of components</a>.
</p>
<a name="Require"></a>
Raymond Toy's avatar
Raymond Toy committed
1531
<h4 class="subsection">6.3.9 Require</h4>
1532
<a name="index-_003arequire-dependencies"></a>
Raymond Toy's avatar
Raymond Toy committed
1533

1534
1535
1536
1537
1538
1539
1540
<p>Use the implementation&rsquo;s own <code>require</code> to load the <var>module-name</var>.
</p>
<p>It is good taste to use <code>:if-feature <em>:implementation-name</em></code>
rather than <code>#+<em>implementation-name</em></code>
to only depend on the specified module on the specific implementation that provides it.
See <a href="#if_002dfeature_002doption">if-feature-option</a>.
</p>
Raymond Toy's avatar
Raymond Toy committed
1541
1542
1543
<a