README.md
1ASDF: Another System Definition Facility
2========================================
3
4What is ASDF?
5-------------
6
7ASDF is the de facto standard build facility for Common Lisp.
8Your Lisp implementation probably contains a copy of ASDF,
9which you can load using `(require "asdf")`.
10
11If you come from the C/C++ world, ASDF covers a bit of what each of
12make, autoconf, dlopen and libc do for C programs:
13it orchestrates the compilation and dependency management,
14handles some of the portability issues, dynamically finds and loads code,
15and offers some portable system access library.
16Except everything is different in Common Lisp, and ultimately much simpler,
17though it requires acquiring some basic concepts.
18Importantly, ASDF builds all software in the current Lisp image,
19as opposed to building software into separate processes.
20
21To use ASDF, read our manual:
22 <http://common-lisp.net/project/asdf/asdf.html>
23
24The first few sections, Loading ASDF, Configuring ASDF and Using ASDF,
25will get you started as a simple user.
26If you want to define your own systems, further read the section
27Defining systems with defsystem.
28
29The manual is also in the [doc/](doc/) subdirectory, and can be prepared with:
30
31 make doc
32
33
34ASDF 3 now includes an extensive runtime support library:
35[UIOP, the Utilities for Implementation- and OS- Portability](uiop/).
36Its documentation unhappily lies mainly in the source code and docstrings.
37See [uiop/README.md](uiop/README.md) for an introduction.
38
39More information and additional links can be found on ASDF's home page at:
40 <http://common-lisp.net/project/asdf/>
41
42
43Quick Start
44-----------
45
46Just use `(require "asdf")` to load your implementation-provided ASDF.
47
48If it is recent enough (3.0 or later, check its `(asdf:asdf-version)`),
49then it will automatically upgrade to the ASDF provided as source code,
50assuming the source code in under a path registered by the source-registry.
51If it isn't present or isn't recent enough, we recommend you install a recent
52ASDF release using [tools/install-asdf.lisp](tools/install-asdf.lisp)
53
54
55Building and testing it
56-----------------------
57
58First, make sure ASDF is checked out under a path registered by the source-registry,
59if that isn't the case yet (see the manual). One place would be:
60
61 ~/.local/share/common-lisp/source/asdf/
62
63or, assuming your implementation provides ASDF 3.1 or later:
64
65 ~/common-lisp/asdf/
66
67
68If you cloned our git repository, bootstrap a copy of `build/asdf.lisp` with:
69
70 make
71
72Before you may run tests, you need a few CL libraries.
73The simplest way to get them is as follows, but read below:
74
75 make ext
76
77The above make target uses `git submodule update --init` to download
78all these libraries using git. If you don't otherwise maintain your
79own set of carefully controlled CL libraries, that's what you want to use.
80However, if you do maintain your own set of carefully controlled CL libraries
81then you will want to use whichever tools you use (e.g. `quicklisp`, `clbuild`,
82or your own scripts around `git`) to download these libraries:
83`alexandria`, `closer-mop`, `cl-ppcre`, `fare-mop`, `fare-quasiquote`,
84`fare-utils`, `inferior-shell`, `lisp-invocation`, `named-readtables`, `optima`.
85
86If you are a CL developer, you may already have them, or may want
87to use your own tools to download a version of them you control.
88If you use [Quicklisp](https://www.quicklisp.org/), you may let
89Quicklisp download those you don't have.
90In these cases, you do NOT want to use the git submodules from `make ext`.
91Otherwise, if you want to let ASDF download known-working versions
92of its dependencies, you can do it with:
93
94 make ext
95
96To run all the tests on your favorite Lisp implementation `$L`,
97choose your most elaborate installed system `$S`, and try:
98
99 make t u l=$L s=$S
100
101
102Debugging tip
103-------------
104
105To interactively debug ASDF, you may load it in such a way that `M-.` will work,
106by installing the source code, and running:
107
108 (asdf:load-system :uiop) ;; loading uiop is simple
109 (map () 'load ;; loading asdf/defsystem is tricky
110 (mapcar 'asdf:component-pathname
111 (asdf::required-components :asdf/defsystem :keep-component 'asdf:cl-source-file)))
112
113Note that the above can be adapted in a general recipe to get all the files in a system, in order.
114To also have the files in systems it transitively depends on, add the `:other-systems t` keyword
115argument to the call to `asdf::required-components`.
116
117
118What has changed?
119-----------------
120
121You can consult the [debian/changelog](debian/changelog) for an overview of the
122significant changes in each release, and
123the `git log` for a detailed description of each commit.
124
125
126How do I navigate this source tree?
127-----------------------------------
128
129* [asdf.asd](asdf.asd)
130 * The system definition for building ASDF with ASDF.
131
132* `*.lisp`
133 * The source code files for `asdf/defsystem`.
134 See [asdf.asd](asdf.asd) for the order in which they are loaded.
135
136* [uiop/](uiop/)
137 * Utilities of Implementation- and OS- Portability,
138 the portability layer of ASDF. It has its own [README](uiop/README.md),
139 and functions all have docstrings.
140
141* [Makefile](Makefile)
142 * a `Makefile` for bootstrap and development purposes.
143
144* [tools/](tools/)
145 * Some scripts to help ASDF users
146 * [load-asdf.lisp](tools/load-asdf.lisp) -- a build script to load, configure and use ASDF
147 * [install-asdf.lisp](install-asdf.lisp) -- replace and update an implementation's ASDF
148 * [cl-source-registry-cache.lisp](cl-source-registry-cache.lisp) -- update a cache for the source-registry
149
150* [build.xcvb](build.xcvb)
151 * The system definition for building ASDF with XCVB.
152 It hasn't been tested or maintained for years and has bitrotten.
153
154* [version.lisp-expr](version.lisp-expr)
155 * The current version. Bumped up every time the code changes, using:
156
157 ./tools/asdf-builder bump
158
159* [doc/](doc/)
160 * documentation for ASDF, including:
161 * [index.html](doc/index.html) -- the web page for <http://common-lisp.net/project/asdf/>
162 * [asdf.texinfo](doc/asdf.texinfo) -- our manual
163 * [Makefile](doc/Makefile) -- how to build the manual
164 * [cclan.png](doc/cclan.png) [lisp-logo120x80.png](doc/lisp-logo120x80.png)
165 [style.css](doc/style.css) [favicon.ico](doc/favicon.ico)
166 -- auxiliaries of [index.html](doc/index.html)
167
168* [test/](test/)
169 * regression test scripts (and ancillary files) for developers to check
170 that they don't unintentionally break any of the functionality of ASDF.
171 Far from covering all of ASDF.
172
173* [contrib/](contrib/)
174 * a few contributed files that show case how to use ASDF.
175
176* [debian/](debian/)
177 * files for packaging on Debian, Ubuntu, etc.
178
179* [build/](build/)
180 * where the `Makefile` and `asdf-tools` store their output files, including
181 * `asdf.lisp` -- the current one-file deliverable of ASDF
182 * `asdf-XXX.lisp` -- for upgrade test purposes, old versions
183 * `results/` -- logs of tests that have been run
184 * `fasls/` -- output files while running tests.
185
186* [ext/](ext/)
187 * external dependencies, that can be populated with `make ext`
188 or equivalently with `git submodule update --init`.
189 Depopulate it with `make noext`.
190
191* [README.md](README.md)
192 * this file
193
194* [TODO](TODO)
195 * plenty of ideas for how to further improve ASDF.
196
197
198Last updated Tuesday, June 9th, 2015.
199
