asdf.texinfo 236 KB
Newer Older
1 2
\input texinfo          @c -*- texinfo -*-
@c %**start of header
3
@setfilename asdf.info
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
4
@settitle ASDF Manual
5
@syncodeindex tp fn
6 7
@c %**end of header

8 9
@c We use @&key, etc to escape & from TeX in lambda lists --
@c so we need to define them for info as well.
10
@macro AallowOtherKeys
11 12
&allow-other-keys
@end macro
13
@macro Aoptional
14 15
&optional
@end macro
16
@macro Arest
17 18
&rest
@end macro
19
@macro Akey
20 21
&key
@end macro
22
@macro Abody
23 24 25
&body
@end macro

26 27 28
@c for install-info
@dircategory Software development
@direntry
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
29
* asdf: (asdf).           Another System Definition Facility (for Common Lisp)
30 31
@end direntry

32
@copying
33 34
This manual describes ASDF, a system definition facility
for Common Lisp programs and libraries.
35

36 37 38
You can find the latest version of this manual at
@url{http://common-lisp.net/project/asdf/asdf.html}.

39
ASDF Copyright @copyright{} 2001-2015 Daniel Barlow and contributors.
40

41
This manual Copyright @copyright{} 2001-2015 Daniel Barlow and contributors.
42

43
This manual revised @copyright{} 2009-2015 Robert P. Goldman and Francois-Rene Rideau.
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

@end copying

66
@include version.texinfo
67 68

@titlepage
69
@title ASDF: Another System Definition Facility
70
@subtitle Manual for Version @value{VERSION}
71 72 73 74 75
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
76

77 78 79 80 81 82 83
@c Output the table of contents at the beginning.
@contents

@c -------------------

@ifnottex

84
@node Top, Introduction, (dir), (dir)
85
@top ASDF: Another System Definition Facility
86 87 88 89
@ifnottex
Manual for Version @value{VERSION}
@end ifnottex

90

91 92 93
@insertcopying

@menu
94
* Introduction::
95
* Quick start summary::
96
* Loading ASDF::
97 98
* Configuring ASDF::
* Using ASDF::
99 100
* Defining systems with defsystem::
* The object model of ASDF::
101
* Controlling where ASDF searches for systems::
102 103 104 105 106
* Controlling where ASDF saves compiled files::
* Error handling::
* Miscellaneous additional functionality::
* Getting the latest version::
* FAQ::
107 108
* Ongoing Work::
* Bibliography::
109 110
* Concept Index::
* Function and Class Index::
111
* Variable Index::              @c @detailmenu
112
@c
113 114 115 116 117 118 119 120 121

@detailmenu
 --- The Detailed Node Listing ---

Loading ASDF

* Loading a pre-installed ASDF::
* Checking whether ASDF is loaded::
* Upgrading ASDF::
122
* Loading ASDF from source::
123

124 125
Upgrading ASDF

126
* Upgrading your implementation's ASDF::
127 128
* Issues with upgrading ASDF::

129 130 131
Configuring ASDF

* Configuring ASDF to find your systems::
Robert P. Goldman's avatar
Robert P. Goldman committed
132
* Configuring ASDF to find your systems --- old style::
133
* Configuring where ASDF stores object files::
Robert P. Goldman's avatar
Robert P. Goldman committed
134
* Resetting the ASDF configuration::
135

136 137 138 139 140 141
Using ASDF

* Loading a system::
* Other Operations::
* Moving on::

142 143 144 145 146 147
Defining systems with defsystem

* The defsystem form::
* A more involved example::
* The defsystem grammar::
* Other code in .asd files::
148
* The package-inferred-system extension::
149

150
The Object model of ASDF
151

152 153
* Operations::
* Components::
154
* Dependencies::
155
* Functions::
156

157
Operations
158

159 160
* Predefined operations of ASDF::
* Creating new operations::
161

162
Components
163

164 165 166
* Common attributes of components::
* Pre-defined subclasses of component::
* Creating new component types::
167

168
properties
169

170 171
* Pre-defined subclasses of component::
* Creating new component types::
172

173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
Controlling where ASDF searches for systems

* Configurations::
* Truenames and other dangers::
* XDG base directory::
* Backward Compatibility::
* Configuration DSL::
* Configuration Directories::
* Shell-friendly syntax for configuration::
* Search Algorithm::
* Caching Results::
* Configuration API::
* Introspection::
* Status::
* Rejected ideas::
* TODO::
* Credits for the source-registry::

Configuration Directories

Robert P. Goldman's avatar
Robert P. Goldman committed
193
* The here directive::
194 195 196 197 198 199 200 201

Introspection

* *source-registry-parameter* variable::
* Information about system dependencies::

Controlling where ASDF saves compiled files

202 203 204 205 206
* Output Configurations::
* Output Backward Compatibility::
* Output Configuration DSL::
* Output Configuration Directories::
* Output Shell-friendly syntax for configuration::
207
* Semantics of Output Translations::
208
* Output Caching Results::
209 210 211 212 213 214
* Output location API::
* Credits for output translations::

Miscellaneous additional functionality

* Controlling file compilation::
215
* Controlling source file character encoding::
216 217
* Some Utility Functions::

218
FAQ
219

220
* Where do I report a bug?::
221
* What has changed between ASDF 1 ASDF 2 and ASDF 3?::
222 223 224 225
* Issues with installing the proper version of ASDF::
* Issues with configuring ASDF::
* Issues with using and extending ASDF to define systems::
* ASDF development FAQs::
226

227
``What has changed between ASDF 1, ASDF 2, and ASDF 3?''
228

229
* What are ASDF 1 2 3?::
230
* How do I detect the ASDF version?::
231 232 233 234 235 236 237 238 239
* ASDF can portably name files in subdirectories::
* Output translations::
* Source Registry Configuration::
* Usual operations are made easier to the user::
* Many bugs have been fixed::
* ASDF itself is versioned::
* ASDF can be upgraded::
* Decoupled release cycle::
* Pitfalls of the transition to ASDF 2::
240
* What happened to the bundle operations::
241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258

Issues with installing the proper version of ASDF

* My Common Lisp implementation comes with an outdated version of ASDF. What to do?::
* I'm a Common Lisp implementation vendor. When and how should I upgrade ASDF?::

Issues with configuring ASDF

* How can I customize where fasl files are stored?::
* How can I wholly disable the compiler output cache?::

Issues with using and extending ASDF to define systems

* How can I cater for unit-testing in my system?::
* How can I cater for documentation generation in my system?::
* How can I maintain non-Lisp (e.g. C) source files?::
* I want to put my module's files at the top level.  How do I do this?::
* How do I create a system definition where all the source files have a .cl extension?::
259
* How do I mark a source file to be loaded only and not compiled?::
260
* How do I work with readtables?::
261 262 263 264 265 266

ASDF development FAQs

* How do run the tests interactively in a REPL?::

@end detailmenu
267 268 269 270 271 272
@end menu

@end ifnottex

@c -------------------

273
@node Introduction, Quick start summary, Top, Top
274 275
@comment  node-name,  next,  previous,  up
@chapter Introduction
Robert P. Goldman's avatar
Robert P. Goldman committed
276 277 278 279 280 281
@cindex ASDF-related features
@vindex *features*
@cindex Testing for ASDF
@cindex ASDF versions
@cindex :asdf
@cindex :asdf2
282
@cindex :asdf3
283

284 285
ASDF is Another System Definition Facility:
a tool for specifying how systems of Common Lisp software
286
are made up of components (sub-systems and files),
287 288
and how to operate on these components in the right order
so that they can be compiled, loaded, tested, etc.
289
If you are new to ASDF, @pxref{Quick start summary,,the quick start
290
guide}.
291 292 293 294

ASDF presents three faces:
one for users of Common Lisp software who want to reuse other people's code,
one for writers of Common Lisp software who want to specify how to build their systems,
295 296
and one for implementers of Common Lisp extensions who want to extend
the build system.
297
For more specifics,
298
@pxref{Using ASDF,,Loading a system},
299
to learn how to use ASDF to load a system.
Robert P. Goldman's avatar
Robert P. Goldman committed
300
@xref{Defining systems with defsystem},
301
to learn how to define a system of your own.
302
@xref{The object model of ASDF}, for a description of
Robert P. Goldman's avatar
Robert P. Goldman committed
303
the ASDF internals and how to extend ASDF.
304

305
Note that
306 307 308 309 310
ASDF is @emph{not} a tool for library and system @emph{installation}; it
plays a role like @t{make} or @t{ant}, not like a package manager.
In particular, ASDF should not to be confused with ASDF-Install, which attempts to find and
download ASDF systems for you.
Despite the name, ASDF-Install is not part of ASDF, but a separate piece of software.
311
ASDF-Install is also unmaintained and obsolete.
312 313 314
We recommend you use Quicklisp
(@uref{http://www.quicklisp.org}) instead,
a Common Lisp package manager which works well and is being actively maintained.
315
If you want to download software from version control instead of tarballs,
316
so you may more easily modify it, we recommend clbuild (@uref{http://common-lisp.net/project/clbuild/}).
317 318
We recommend @file{~/common-lisp/}
as a place into which to install Common Lisp software;
319
starting with ASDF 3.1.2, it is included in the default source-registry configuration.
320

321 322
@node  Quick start summary, Loading ASDF, Introduction, Top
@chapter Quick start summary
323

324
@itemize
325 326 327 328 329 330

@item To load an ASDF system:

@itemize
@item
Load ASDF itself into your Lisp image, either through
331
@code{(require "asdf")} (if it's supplied by your lisp implementation)
332
or else through
333
@code{(load "/path/to/asdf.lisp")}.  For more details, @ref{Loading ASDF}.
334 335 336

@item
Make sure ASDF can find system definitions
337 338
through proper source-registry configuration.
For more details, @xref{Configuring ASDF to find your systems}.
339
The simplest way is simply to put all your lisp code in subdirectories of
340
@file{~/common-lisp/} (starting with ASDF 3.1.2),
341 342
or @file{~/.local/share/common-lisp/source/}
(for ASDF 2 and later, or if you want to keep source in a hidden directory).
343
Such code will automatically be found.
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358

@item
Load a system with @code{(asdf:load-system :system)}. @xref{Using ASDF}.

@end itemize

@item To make your own ASDF system:

@itemize
@item
As above, load and configure ASDF.

@item
Make a new directory for your system, @code{my-system/} in a location
where ASDF can find it (@pxref{Configuring ASDF to find your systems}).
359 360 361
All else being equal, the easiest location is probably
@file{~/common-lisp/my-system/}.

362 363

@item
364 365 366 367 368
Create an ASDF system definition listing the dependencies of
your system, its components, and their interdependencies,
and put it in @file{my-system.asd}.
This file must have the same name as your system.
@xref{Defining systems with defsystem}.
369 370

@item
371 372
Use @code{(asdf:load-system :my-system)}
to make sure it's all working properly. @xref{Using ASDF}.
373 374 375 376

@end itemize
@end itemize

Robert P. Goldman's avatar
Robert P. Goldman committed
377 378
@c FIXME: (1) add a sample project that the user can cut and paste to
@c get started.  (2) discuss the option of starting with Quicklisp.
379 380 381 382 383 384





@node Loading ASDF, Configuring ASDF, Quick start summary, Top
385
@comment  node-name,  next,  previous,  up
386
@chapter Loading ASDF
387

388 389 390 391
@menu
* Loading a pre-installed ASDF::
* Checking whether ASDF is loaded::
* Upgrading ASDF::
392
* Loading ASDF from source::
393
@end menu
394

395
@node  Loading a pre-installed ASDF, Checking whether ASDF is loaded, Loading ASDF, Loading ASDF
396 397
@section Loading a pre-installed ASDF

398
All actively maintained Lisp implementations now include a copy of ASDF 3.
399
You can usually load this copy using Common Lisp's @code{require} function.@footnote{
400 401
NB: all implementations except GNU CLISP also accept
@code{(require "ASDF")}, @code{(require 'asdf)} and @code{(require :asdf)}.
402
For portability's sake, you should use @code{(require "asdf")}.
403
}
404 405

@lisp
406
(require "asdf")
407 408
@end lisp

Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
409
As of the writing of this manual,
410
the following implementations provide ASDF 3 this way:
411
ABCL, Allegro CL, CLASP, Clozure CL, CMUCL, ECL, GNU CLISP, LispWorks, MKCL, SBCL.
412
The following implementations only provide ASDF 2:
413
mocl, XCL.
414 415
The following implementations don't provide ASDF:
Corman CL, GCL, Genera, MCL, SCL.
416
The latter implementations are not actively maintained (except maybe GCL);
417
if some of them are ever released again, they probably will include ASDF 3.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
418

419
If the implementation you are using doesn't provide a recent ASDF 3,
420
see @pxref{Loading ASDF,,Loading ASDF from source} below.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
421 422
If that implementation is still actively maintained,
you may also send a bug report to your Lisp vendor and complain
423
about their failing to provide an up-to-date ASDF.
424

425
@node Checking whether ASDF is loaded, Upgrading ASDF, Loading a pre-installed ASDF, Loading ASDF
426 427 428 429 430 431 432 433 434 435 436 437 438 439
@section Checking whether ASDF is loaded

To check whether ASDF is properly loaded in your current Lisp image,
you can run this form:

@lisp
(asdf:asdf-version)
@end lisp

If it returns a string,
that is the version of ASDF that is currently installed.

If it raises an error,
then either ASDF is not loaded, or
440 441
you are using a very old version of ASDF,
and need to install ASDF 3.
442 443 444 445 446 447 448 449

You can check whether an old version is loaded
by checking if the ASDF package is present.
The form below will allow you to programmatically determine
whether a recent version is loaded, an old version is loaded,
or none at all:

@lisp
450
(when (find-package :asdf)
Robert P. Goldman's avatar
Robert P. Goldman committed
451 452 453
  (let ((ver (symbol-value
                   (or (find-symbol (string :*asdf-version*) :asdf)
                       (find-symbol (string :*asdf-revision*) :asdf)))))
454 455
    (etypecase ver
      (string ver)
456
      (cons (with-output-to-string (s)
Robert P. Goldman's avatar
Robert P. Goldman committed
457 458 459
              (loop for (n . m) on ver
                    do (princ n s)
                       (when m (princ "." s)))))
460
      (null "1.0"))))
461 462
@end lisp

463
If it returns @code{nil} then ASDF is not installed.
464 465 466
Otherwise it should return a string.
If it returns @code{"1.0"}, then it can actually be
any version before 1.77 or so, or some buggy variant of 1.x.
467

Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
468 469 470 471
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.
472

473
@node  Upgrading ASDF, Loading ASDF from source, Checking whether ASDF is loaded, Loading ASDF
474
@section Upgrading ASDF
475 476 477
@c FIXME: tighten this up a bit -- there's a lot of stuff here that
@c doesn't matter to almost anyone.  Move discussion of updating antique
@c versions of ASDF down, or encapsulate it.
478

479 480 481 482
If you want to upgrade to a more recent ASDF version,
you need to install and configure your ASDF just like any other system
(@pxref{Configuring ASDF to find your systems}).

483
If your implementation provides ASDF 3 or later,
484 485 486 487
you only need to @code{(require "asdf")}:
ASDF will automatically look whether an updated version of itself is available
amongst the regularly configured systems, before it compiles anything else.

488
@menu
489
* Upgrading your implementation's ASDF::
490 491 492
* Issues with upgrading ASDF::
@end menu

493 494 495
@node Upgrading your implementation's ASDF, Issues with upgrading ASDF, Upgrading ASDF, Upgrading ASDF
@subsection Upgrading your implementation's ASDF

496 497 498 499 500 501
@c Now that all implementations provide ASDF 3, most issues become trivial,
@c except on CMUCL where upgrade doesn't work.
@c Most of the upgrading section might be moved to an advanced chapter
@c rather than being in an early section that will trouble the novice.

All maintained implementations now provide ASDF 3 in their latest release.
502
If yours doesn't, we recommend upgrading your implementation.
503 504 505 506
If you want to stick to an old implementation that didn't provide ASDF or provided an old version,
we recommend installing a recent ASDF, as explained below,
into your implementation's installation directory;
thus your modified implementation will now provide ASDF 3.
507 508 509
If all fails, we recommend you load ASDF from source
@pxref{Loading ASDF,,Loading ASDF from source}.

510 511 512 513 514 515
The ASDF source repository contains a tool to help you upgrade your implementation's ASDF.
You can invoke it from the shell command-line as
@code{tools/asdf-tools install-asdf lispworks}
(where you can replace @code{lispworks} by the name of the relevant implementation),
or you can @code{(load "tools/install-asdf.lisp")} from your Lisp REPL.

516
It works on
517 518
Allegro CL, Clozure CL, CMU CL, ECL, GCL, GNU CLISP, LispWorks, MKCL, SBCL, SCL, XCL.
It doesn't work on ABCL, Corman CL, Genera, MCL, MOCL.
519
Happily, ABCL is usually pretty up to date and shouldn't need that script.
520
GCL requires a very recent version, and hasn't been tested for lack of success compiling it.
521 522
Corman CL, Genera, MCL are obsolete anyway.
MOCL is under development.
523 524 525 526 527 528 529

Finally, if your implementation only provides ASDF 2,
and you can't or won't upgrade it or override its ASDF module,
you may simply configure ASDF to find a proper upgrade;
however, to avoid issues with a self-upgrade in mid-build,
you @emph{must} make sure to upgrade ASDF immediately
after requiring the builtin ASDF 2:
530 531

@lisp
532
(require "asdf")
533
;; <--- insert programmatic configuration here if needed
534 535 536
(asdf:load-system :asdf)
@end lisp

537
@node Issues with upgrading ASDF,  , Upgrading your implementation's ASDF, Upgrading ASDF
538 539
@subsection Issues with upgrading ASDF

540
Note that there are some limitations to upgrading ASDF:
541 542
@itemize
@item
543
Previously loaded ASDF extensions become invalid, and will need to be reloaded.
544
Examples include CFFI-Grovel, hacks used by ironclad, etc.
545
Since it isn't possible to automatically detect what extensions
546 547 548 549 550 551 552 553 554 555
need to be invalidated,
ASDF will invalidate @emph{all} previously loaded systems
when it is loaded on top of a forward-incompatible ASDF version.
@footnote{
@vindex *oldest-forward-compatible-asdf-version*
Forward incompatibility can be determined using the variable
@code{asdf/upgrade::*oldest-forward-compatible-asdf-version*},
which is 2.33 at the time of this writing.}

Starting with ASDF 3 (2.27 or later),
556 557
this self-upgrade will be automatically attempted as the first step
to any system operation, to avoid any possibility of
558
a catastrophic attempt to self-upgrade in mid-build.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
559

560
@c FIXME: Fix grammar below.
561
@item
562
For this and many other reasons,
563
you should load, configure and upgrade ASDF
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
564
as one of the very first things done by your build and startup scripts.
565
It is safer if you upgrade ASDF and its extensions as a special step
566
at the very beginning of whatever script you are running,
567
before you start using ASDF to load anything else.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
568

569
@item
570
Until all implementations provide ASDF 3 or later (now the case in May 2015),
571
it is unsafe to upgrade ASDF as part of loading a system
572 573 574 575
that depends on a more recent version of ASDF,
since the new one might shadow the old one while the old one is running,
and the running old one will be confused
when extensions are loaded into the new one.
576
In the meantime, we recommend that your systems should @emph{not} specify
577
@code{:depends-on (:asdf)}, or @code{:depends-on ((:version :asdf "3.0.1"))},
578 579 580 581 582 583 584
but instead that they check that a recent enough ASDF is installed,
with such code as:
@example
(unless (or #+asdf2 (asdf:version-satisfies
                     (asdf:asdf-version) *required-asdf-version*))
  (error "FOO requires ASDF ~A or later." *required-asdf-version*))
@end example
585
@item
586
Until all implementations provide ASDF 3 or later (now the case in May 2015),
587 588 589 590 591
it is unsafe for a system to transitively depend on ASDF
and not directly depend on ASDF;
if any of the system you use either depends-on asdf,
system-depends-on asdf, or transitively does,
you should also do as well.
592 593
@end itemize

594 595 596 597 598
Note that bugs in CMUCL and XCL prevent upgrade of ASDF.
Happily, CMUCL comes with a recent ASDF,
and XCL is more of a working demo than something you'd use seriously anyway.


599 600
@node Loading ASDF from source,  , Upgrading ASDF, Loading ASDF
@section Loading ASDF from source
601 602

If your implementation doesn't include ASDF,
603 604
if for some reason the upgrade somehow fails,
does not or cannot apply to your case,
605 606 607 608 609 610
you will have to install the file @file{asdf.lisp}
somewhere and load it with:

@lisp
(load "/path/to/your/installed/asdf.lisp")
@end lisp
611

612
The single file @file{asdf.lisp} is all you normally need to use ASDF.
613

614
You can extract this file from latest release tarball on the
615
@url{http://common-lisp.net/project/asdf/,ASDF website}.
616
If you are daring and willing to report bugs, you can get
617
the latest and greatest version of ASDF from its git repository.
618 619 620 621 622 623 624
@xref{Getting the latest version}.

For maximum convenience you might want to have ASDF loaded
whenever you start your Lisp implementation,
for example by loading it from the startup script or dumping a custom core
--- check your Lisp implementation's manual for details.

625

626 627
@node Configuring ASDF, Using ASDF, Loading ASDF, Top
@comment  node-name,  next,  previous,  up
628 629
@chapter Configuring ASDF

630 631 632 633 634 635
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 @xref{Using ASDF}. 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.
Robert P. Goldman's avatar
Robert P. Goldman committed
636 637 638


@menu
639
* Configuring ASDF to find your systems::
Robert P. Goldman's avatar
Robert P. Goldman committed
640
* Configuring ASDF to find your systems --- old style::
641
* Configuring where ASDF stores object files::
Robert P. Goldman's avatar
Robert P. Goldman committed
642
* Resetting the ASDF configuration::
Robert P. Goldman's avatar
Robert P. Goldman committed
643 644
@end menu

Robert P. Goldman's avatar
Robert P. Goldman committed
645
@node Configuring ASDF to find your systems, Configuring ASDF to find your systems --- old style, Configuring ASDF, Configuring ASDF
646 647
@section Configuring ASDF to find your systems

Robert P. Goldman's avatar
Robert P. Goldman committed
648
In order to compile and load your systems, ASDF must be configured to find
649 650
the @file{.asd} files that contain system definitions.

Robert P. Goldman's avatar
Robert P. Goldman committed
651 652 653 654
There are a number of different techniques for setting yourself up with
ASDF, starting from easiest to the most complex:

@itemize @bullet
655

656
@item
657 658 659
Put all of your systems in one of the standard locations, subdirectories
of
@itemize
660
@item
661
@file{~/common-lisp/} or
662
@item
663
@file{~/.local/share/common-lisp/source/}.
664
@end itemize
665 666
If you install software there, you don't need further
configuration.@footnote{@file{~/common-lisp/} is only included in
667
the default configuration
668
starting with ASDF 3.1.2 or later.}
Robert P. Goldman's avatar
Robert P. Goldman committed
669

670
@item
671
If you're using some tool to install software (e.g. Quicklisp),
672 673
the authors of that tool should already have configured ASDF.

674
@item
Robert P. Goldman's avatar
Robert P. Goldman committed
675 676 677 678 679 680 681
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} facility,
fully described in its own chapter of this manual.
@xref{Controlling where ASDF searches for systems}.  Here is a quick
recipe for getting started:

682
The simplest way to add a path to your search path,
683
say @file{/home/luser/.asd-link-farm/}
684 685
is to create the directory
@file{~/.config/common-lisp/source-registry.conf.d/}
686
and there create a file with any name of your choice,
Robert P. Goldman's avatar
Robert P. Goldman committed
687 688 689 690 691 692 693 694 695 696 697
and with the type @file{conf}@footnote{By requiring the @file{.conf}
extension, and ignoring other files, ASDF allows you to have disabled files,
editor backups, etc. in the same directory with your active
configuration files.

ASDF will also ignore files whose names start with a @file{.} character.

It is customary to start the filename with two digits, to control the
sorting of the @code{conf} files in the source registry directory, and
thus the order in which the directories will be scanned.},
for instance @file{42-asd-link-farm.conf},
698 699
containing the line:

700
@kbd{(:directory "/home/luser/.asd-link-farm/")}
701

702
If you want all the subdirectories under @file{/home/luser/lisp/}
703 704
to be recursively scanned for @file{.asd} files, instead use:

705
@kbd{(:tree "/home/luser/lisp/")}
706 707 708

ASDF will automatically read your configuration
the first time you try to find a system.
Robert P. Goldman's avatar
Robert P. Goldman committed
709
If necessary, you can reset the source-registry configuration with:
710

711 712 713 714
@lisp
(asdf:clear-source-registry)
@end lisp

Robert P. Goldman's avatar
Robert P. Goldman committed
715 716
@item
In earlier versions of ASDF, the system source registry was configured
717 718 719 720
using a global variable, @code{asdf:*central-registry*}.
For more details about this, see the following section,
@ref{Configuring ASDF to find your systems --- old style}.
Unless you need to understand this,
Robert P. Goldman's avatar
Robert P. Goldman committed
721
skip directly to @ref{Configuring where ASDF stores object files}.
722

Robert P. Goldman's avatar
Robert P. Goldman committed
723 724 725 726 727 728 729
@end itemize

Note that your Operating System distribution or your system administrator
may already have configured system-managed libraries for you.



730
@node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Configuring ASDF
Robert P. Goldman's avatar
Robert P. Goldman committed
731 732
@section Configuring ASDF to find your systems --- old style

733 734 735

@c FIXME: this section should be moved elsewhere.  The novice user
@c should not be burdened with it. [2014/02/27:rpg]
Robert P. Goldman's avatar
Robert P. Goldman committed
736

737 738 739 740 741 742 743 744 745 746 747 748

The old way to configure ASDF to find your systems is by
@code{push}ing directory pathnames onto the variable
@code{asdf:*central-registry*}.

You must configure this variable between the time you load ASDF
and the time you first try to use it.
Loading and configuring ASDF presumably happen
as part of some initialization script that builds or starts
your Common Lisp software system.
(For instance, some SBCL users used to put it in their @file{~/.sbclrc}.)

749
The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
750
but is still supported for compatibility with ASDF 1.
751
When used, it takes precedence over the above source-registry.@footnote{
752 753 754 755 756
It is possible to further customize
the system definition file search.
That's considered advanced use, and covered later:
search forward for
@code{*system-definition-search-functions*}.
757
@xref{Defining systems with defsystem}.}
758

759 760 761
For example, let's say you want ASDF to find the @file{.asd} file
@file{/home/me/src/foo/foo.asd}.
In your lisp initialization file, you could have the following:
762 763

@lisp
764
(require "asdf")
765 766 767 768 769
(push "/home/me/src/foo/" asdf:*central-registry*)
@end lisp

Note the trailing slash: when searching for a system,
ASDF will evaluate each entry of the central registry
770
and coerce the result to a pathname.@footnote{
771
ASDF will indeed call @code{eval} on each entry.
772
It will skip entries that evaluate to @code{nil}.
773 774

Strings and pathname objects are self-evaluating,
775
in which case the @code{eval} step does nothing;
776 777 778
but you may push arbitrary s-expressions onto the central registry.
These s-expressions may be evaluated to compute context-dependent
entries, e.g. things that depend
779 780 781 782 783 784
on the value of shell variables or the identity of the user.

The variable @code{asdf:*central-registry*} is thus a list of
``system directory designators''.
A @dfn{system directory designator} is a form
which will be evaluated whenever a system is to be found,
785 786 787
and must evaluate to a directory to look in (or @code{NIL}).
By ``directory'', we mean
``designator for a pathname with a non-empty DIRECTORY component''.
788
}
789
The trailing directory name separator
790
is necessary to tell Lisp that you're discussing a directory
791 792 793
rather than a file.  If you leave it out, ASDF is likely to look in
@code{/home/me/src/} instead of @code{/home/me/src/foo/} as you
intended, and fail to find your system definition.
794

795 796 797
Typically there are a lot of @file{.asd} files, and
a common idiom was to put
@emph{symbolic links} to all of one's @file{.asd} files
798 799
in a common directory
and push @emph{that} directory (the ``link farm'')
800 801 802 803 804 805 806 807 808
onto
@code{asdf:*central-registry*},
instead of pushing each individual system directory.

ASDF knows to follow @emph{symlinks}
to the actual location of the systems.@footnote{
On Windows, you can use Windows shortcuts instead of POSIX symlinks.
if you try aliases under MacOS, we are curious to hear about your experience.}

809
For example, if @code{#p"/home/me/cl/systems/"}
810 811
is an element of @code{*central-registry*}, you could set up the
system @var{foo} as follows:
812 813 814 815 816 817

@example
$ cd /home/me/cl/systems/
$ ln -s ~/src/foo/foo.asd .
@end example

818 819 820 821
This old style for configuring ASDF is not recommended for new users,
but it is supported for old users, and for users who want to programmatically
control what directories are added to the ASDF search path.

822

Robert P. Goldman's avatar
Robert P. Goldman committed
823
@node Configuring where ASDF stores object files, Resetting the ASDF configuration, Configuring ASDF to find your systems --- old style, Configuring ASDF
824
@section Configuring where ASDF stores object files
825
@findex clear-output-translations
826 827 828 829 830

ASDF lets you configure where object files will be stored.
Sensible defaults are provided and
you shouldn't normally have to worry about it.

831
This allows the same source code repository to be shared
832
between several versions of several Common Lisp implementations,
833 834 835 836
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.
837

838
Starting with ASDF 2, the @code{asdf-output-translations} facility
839
was added to ASDF itself.  This facility controls where object files will be stored.
840
This facility is fully described in a chapter of this manual,
841
@ref{Controlling where ASDF saves compiled files}.
842

843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889
@c FIXME: possibly this should be moved elsewhere.  It's redundant here,
@c and makes this section of the manual too long and daunting for the
@c new user. [2014/02/27:rpg]
@c The simplest way to add a translation to your search path,
@c say from @file{/foo/bar/baz/quux/}
@c to @file{/where/i/want/my/fasls/}
@c is to create the directory
@c @file{~/.config/common-lisp/asdf-output-translations.conf.d/}
@c and there create a file with any name of your choice and the type @file{conf},
@c for instance @file{42-bazquux.conf}
@c containing the line:

@c @kbd{("/foo/bar/baz/quux/" "/where/i/want/my/fasls/")}

@c To disable output translations for source under a given directory,
@c say @file{/toto/tata/}
@c you can create a file @file{40-disable-toto.conf}
@c with the line:

@c @kbd{("/toto/tata/")}

@c To wholly disable output translations for all directories,
@c you can create a file @file{00-disable.conf}
@c with the line:

@c @kbd{(t t)}

@c Note that your Operating System distribution or your system administrator
@c may already have configured translations for you.
@c In absence of any configuration, the default is to redirect everything
@c under an implementation-dependent subdirectory of @file{~/.cache/common-lisp/}.
@c @xref{Controlling where ASDF searches for systems}, for full details.

@c The required @file{.conf} extension allows you to have disabled files
@c or editor backups (ending in @file{~}), and works portably
@c (for instance, it is a pain to allow both empty and non-empty extension on CLISP).
@c Excluded are files the name of which start with a @file{.} character.
@c It is customary to start the filename with two digits
@c that specify the order in which the directories will be scanned.

@c ASDF will automatically read your configuration
@c the first time you try to find a system.
@c You can reset the source-registry configuration with:

@c @lisp
@c (asdf:clear-output-translations)
@c @end lisp
890

891 892 893 894 895 896
@c And you probably should do so before you dump your Lisp image,
@c if the configuration may change
@c between the machine where you save it at the time you save it
@c and the machine you resume it at the time you resume it.
@c (Once again, you should use @code{(asdf:clear-configuration)}
@c before you dump your Lisp image, which includes the above.)
897

898
Note that before ASDF 2,
899 900 901 902
other ASDF add-ons offered the same functionality,
each in subtly different and incompatible ways:
ASDF-Binary-Locations, cl-launch, common-lisp-controller.
ASDF-Binary-Locations is now not needed anymore and should not be used.
903
cl-launch 3.000 and common-lisp-controller 7.2 have been updated
904
to delegate object file placement to ASDF.
905

906
@node Resetting the ASDF configuration,  , Configuring where ASDF stores object files, Configuring ASDF
Robert P. Goldman's avatar
Robert P. Goldman committed
907 908
@section Resetting the ASDF configuration

909 910
@c FIXME: this should probably be moved out of the "quickstart" part of
@c the manual. [2014/02/27:rpg]
Robert P. Goldman's avatar
Robert P. Goldman committed
911

912 913 914 915 916 917

When you dump and restore an image, or when you tweak your configuration,
you may want to reset the ASDF configuration.
For that you may use the following function:

@defun clear-configuration
918
   Undoes any ASDF configuration
919 920 921
   regarding source-registry or output-translations.
@end defun

922
@vindex *image-dump-hook*
923 924 925 926 927 928 929 930 931
This function is pushed onto the @code{uiop:*image-dump-hook*} by default,
which means that if you save an image using @code{uiop:dump-image},
or via @code{asdf:image-op} and @code{asdf:program-op},
it will be automatically called to clear your configuration.
If for some reason you prefer to call your implementation's underlying functionality,
be sure to call @code{clear-configuration} manually,
or push it into your implementation's equivalent of @code{uiop:*image-dump-hook*},
e.g. @code{sb-ext:*save-hooks*} on SBCL, or @code{ext:*before-save-initializations*}
on CMUCL and SCL, etc.
932

933
@node  Using ASDF, Defining systems with defsystem, Configuring ASDF, Top
934 935
@chapter Using ASDF

Robert P. Goldman's avatar
Robert P. Goldman committed
936 937 938 939 940 941 942
@menu
* Loading a system::
* Other Operations::
* Moving on::
@end menu

@node Loading a system, Other Operations, Using ASDF, Using ASDF
943 944 945 946
@section Loading a system

The system @var{foo} is loaded (and compiled, if necessary)
by evaluating the following Lisp form:
947 948

@example
949
(asdf:load-system :@var{foo})
950 951
@end example

952
On some implementations (namely recent versions of
953
ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL),
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
954 955 956 957 958 959 960
ASDF hooks into the @code{CL:REQUIRE} facility
and you can just use:

@example
(require :@var{foo})
@end example

961 962
In older versions of ASDF, you needed to use
@code{(asdf:oos 'asdf:load-op :@var{foo})}.
Francois-Rene Rideau's avatar
Francois-Rene Rideau committed
963
If your ASDF is too old to provide @code{asdf:load-system} though
964
we recommend that you upgrade to ASDF 3.
965
@xref{Loading ASDF,,Loading ASDF from source}.
966

967
Note the name of a system is specified as a string or a symbol.
968 969
If a symbol (including a keyword), its name is taken and lowercased.
The name must be a suitable value for the @code{:name} initarg
970 971 972
to @code{make-pathname} in whatever filesystem the system is to be
found.

973 974
The lower-casing-symbols behaviour is unconventional,
but was selected after some consideration.
975 976 977 978 979
The type of systems we want to support
either have lowercase as customary case (Unix, Mac, Windows)
or silently convert lowercase to uppercase (lpns).
@c so this makes more sense than attempting to use @code{:case :common},
@c which is reported not to work on some implementations
980

Robert P. Goldman's avatar
Robert P. Goldman committed
981
@node Other Operations, Moving on, Loading a system, Using ASDF
982
@section Other Operations
983

Robert Goldman's avatar
Robert Goldman committed
984 985 986 987
@c FIXME: this isn't a great name for this node -- these are not, in
@c fact, other OPERATIONS.  OPERATIONS are objects.  These are other
@c "convenience functions," or something like that. [2015/06/29:rpg]

988 989 990
@findex load-system
@findex compile-system
@findex test-system
Robert Goldman's avatar
Robert Goldman committed
991
@findex require-system
992

993
ASDF provides three commands for the most common system operations:
994
@code{load-system}, @code{compile-system}, and @code{test-system}.
995 996
It also provides @code{require-system}, a version of @code{load-system}
that skips trying to update systems that are already loaded.
997

998 999 1000 1001 1002
@c FIXME: We seem to export @findex bundle-system also.

@findex operate
@findex oos

1003 1004 1005
Because ASDF is an extensible system
for defining @emph{operations} on @emph{components},
it also provides a generic function @code{operate}
1006 1007
(which is usually abbreviated by @code{oos},
which stands for operate-on-system).
1008 1009
You'll use @code{oos} whenever you want to do something beyond
compiling, loading and testing.
1010

1011
Output from ASDF and ASDF extensions are sent
1012
to the CL stream @code{*standard-output*},
1013
so rebinding that stream around calls to @code{asdf:operate}
1014
should redirect all output from ASDF operations.
1015

1016 1017 1018
@c Reminder: before ASDF can operate on a system, however,
@c it must be able to find and load that system's definition.
@c @xref{Configuring ASDF,,Configuring ASDF to find your systems}.
1019

1020 1021
@c FIXME: the following is too complicated for here, especially since
@c :force hasn't been defined yet.  Move it. [2014/02/27:rpg]
1022

1023 1024 1025 1026
@findex already-loaded-systems
@findex require-system
@findex load-system
@vindex *load-system-operation*
1027
For advanced users, note that