contrib/asdf/README.md

   1 ASDF: Another System Definition Facility
   2 ========================================
   3
   4 What is ASDF?
   5 -------------
   6
   7 ASDF is the de facto standard build facility for Common Lisp.
   8 Your Lisp implementation probably contains a copy of ASDF,
   9 which you can load using `(require "asdf")`.
  10
  11 If you come from the C/C++ world, ASDF covers a bit of what each of
  12 make, autoconf, dlopen and libc do for C programs:
  13 it orchestrates the compilation and dependency management,
  14 handles some of the portability issues, dynamically finds and loads code,
  15 and offers some portable system access library.
  16 Except everything is different in Common Lisp, and ultimately much simpler,
  17 though it requires acquiring some basic concepts.
  18 Importantly, ASDF builds all software in the current Lisp image,
  19 as opposed to building software into separate processes.
  20
  21 To use ASDF, read our manual:
  22     <http://common-lisp.net/project/asdf/asdf.html>
  23
  24 The first few sections, Loading ASDF, Configuring ASDF and Using ASDF,
  25 will get you started as a simple user.
  26 If you want to define your own systems, further read the section
  27 Defining systems with defsystem.
  28
  29 The manual is also in the [doc/](doc/) subdirectory, and can be prepared with:
  30
  31     make doc
  32
  33
  34 ASDF 3 now includes an extensive runtime support library:
  35 [UIOP, the Utilities for Implementation- and OS- Portability](uiop/).
  36 Its documentation unhappily lies mainly in the source code and docstrings.
  37 See [uiop/README.md](uiop/README.md) for an introduction.
  38
  39 More information and additional links can be found on ASDF's home page at:
  40     <http://common-lisp.net/project/asdf/>
  41
  42
  43 Quick Start
  44 -----------
  45
  46 Just use `(require "asdf")` to load your implementation-provided ASDF.
  47
  48 If it is recent enough (3.0 or later, check its `(asdf:asdf-version)`),
  49 then it will automatically upgrade to the ASDF provided as source code,
  50 assuming the source code in under a path registered by the source-registry.
  51 If it isn't present or isn't recent enough, we recommend you install a recent
  52 ASDF release using [tools/install-asdf.lisp](tools/install-asdf.lisp)
  53
  54
  55 Building and testing it
  56 -----------------------
  57
  58 First, make sure ASDF is checked out under a path registered by the source-registry,
  59 if that isn't the case yet (see the manual). One place would be:
  60
  61     ~/.local/share/common-lisp/source/asdf/
  62
  63 or, assuming your implementation provides ASDF 3.1 or later:
  64
  65     ~/common-lisp/asdf/
  66
  67
  68 If you cloned our git repository, bootstrap a copy of `build/asdf.lisp` with:
  69
  70     make
  71
  72 Before you may run tests, you need a few CL libraries.
  73 The simplest way to get them is as follows, but read below:
  74
  75     make ext
  76
  77 The above make target uses `git submodule update --init` to download
  78 all these libraries using git. If you don't otherwise maintain your
  79 own set of carefully controlled CL libraries, that's what you want to use.
  80 However, if you do maintain your own set of carefully controlled CL libraries
  81 then you will want to use whichever tools you use (e.g. `quicklisp`, `clbuild`,
  82 or 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
  86 If you are a CL developer, you may already have them, or may want
  87 to use your own tools to download a version of them you control.
  88 If you use [Quicklisp](https://www.quicklisp.org/), you may let
  89 Quicklisp download those you don't have.
  90 In these cases, you do NOT want to use the git submodules from `make ext`.
  91 Otherwise, if you want to let ASDF download known-working versions
  92 of its dependencies, you can do it with:
  93
  94     make ext
  95
  96 To run all the tests on your favorite Lisp implementation `$L`,
  97 choose your most elaborate installed system `$S`, and try:
  98
  99     make t u l=$L s=$S
 100
 101
 102 Debugging tip
 103 -------------
 104
 105 To interactively debug ASDF, you may load it in such a way that `M-.` will work,
 106 by 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
 113 Note that the above can be adapted in a general recipe to get all the files in a system, in order.
 114 To also have the files in systems it transitively depends on, add the `:other-systems t` keyword
 115 argument to the call to `asdf::required-components`.
 116
 117
 118 What has changed?
 119 -----------------
 120
 121 You can consult the [debian/changelog](debian/changelog) for an overview of the
 122 significant changes in each release, and
 123 the `git log` for a detailed description of each commit.
 124
 125
 126 How 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
 198 Last updated Tuesday, June 9th, 2015.