Commit 66b7fec4 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau

Documentation tweak: more manual about package-inferred-system.

README update and conversion to markdown.
parent eb45d7cc
......@@ -26,6 +26,7 @@ doc/asdf.dvi
*.tmp
LICENSE
README.html
tmp/
man/
lib/
......
ASDF: Another System Definition Facility
========================================
Quick Summary
-------------
1- Build it with::
make
2- Make sure you put it under a path registered by the source-registry,
if that isn't the case yet (see the manual). One place would be::
~/.local/share/common-lisp/source/asdf/
or, assuming your implementation provides ASDF 3.1 or later::
~/common-lisp/asdf/
What is ASDF?
-------------
......@@ -34,7 +15,7 @@ Except everything is different in Common Lisp, and ultimately much simpler,
though it requires acquiring some basic concepts.
Importantly, ASDF builds all software in the current Lisp image.
To use ASDF, read our manual::
To use ASDF, read our manual:
http://common-lisp.net/project/asdf/asdf.html
......@@ -43,7 +24,7 @@ will get you started as a simple user.
If you want to define your own systems, further read the section
Defining systems with defsystem.
The manual is also in the doc/ subdirectory, and can be prepared with::
The manual is also in the doc/ subdirectory, and can be prepared with:
make doc
......@@ -51,22 +32,42 @@ The manual is also in the doc/ subdirectory, and can be prepared with::
ASDF 3 now includes an extensive runtime support library:
UIOP, the Utilities for Implementation- and OS- Portability.
Its documentation unhappily lies mainly in the source code and docstrings.
See uiop/README for an introduction.
See [`uiop/README`](uiop/README) for an introduction.
More information and additional links can be found on ASDF's home page at::
More information and additional links can be found on ASDF's home page at:
http://common-lisp.net/project/asdf/
Quick Summary
-------------
Just use `(require "asdf")` to load your implementation-provided ASDF.
If it is recent enough (3.0 or later, check its `(asdf:asdf-version)`),
then it will automatically upgrade to the ASDF provided as source code,
assuming the source code in under a path registered by the source-registry.
Building and testing it
-----------------------
If you cloned our git repository, bootstrap a copy of build/asdf.lisp with::
First, make sure ASDF is checked out under a path registered by the source-registry,
if that isn't the case yet (see the manual). One place would be:
~/.local/share/common-lisp/source/asdf/
or, assuming your implementation provides ASDF 3.1 or later:
~/common-lisp/asdf/
If you cloned our git repository, bootstrap a copy of build/asdf.lisp with:
make
Before you may run tests, you need a few CL libraries.
The simplest way to get them is as follows, but read below::
The simplest way to get them is as follows, but read below:
make ext
......@@ -84,10 +85,12 @@ to use your own tools to download a version of them you control.
If you use Quicklisp, you may let Quicklisp download those you don't have.
In these cases, you do NOT want to use
However, if you want to let ASDF download known-working versions
of its dependencies, you can do it with::
of its dependencies, you can do it with:
make ext
To run all the tests on your favorite Lisp implementation $L,
choose your most elaborate installed system $S, and try::
choose your most elaborate installed system $S, and try:
make t u l=$L s=$S
......@@ -95,92 +98,95 @@ choose your most elaborate installed system $S, and try::
Debugging tip
-------------
To load ASDF in such a way that M-. will work, install the source code, and run::
To load ASDF in such a way that M-. will work, install the source code, and run:
(asdf:load-system :uiop) ;; loading uiop is simple
(map () 'load ;; loading asdf/defsystem is tricky
(mapcar 'asdf:component-pathname
(asdf::required-components :asdf/defsystem :keep-component 'asdf:cl-source-file)))
(asdf:load-system :uiop) ;; loading uiop is simple
(map () 'load ;; loading asdf/defsystem is tricky
(mapcar 'asdf:component-pathname
(asdf::required-components :asdf/defsystem :keep-component 'asdf:cl-source-file)))
What has changed?
-----------------
You can consult the debian/changelog for an overview of the
You can consult the `debian/changelog` for an overview of the
significant changes in each release, and
the git log for a detailed description of each commit.
the `git log` for a detailed description of each commit.
How do I navigate this source directory?
----------------------------------------
asdf.asd
The system definition for building ASDF with ASDF.
*.lisp
The source code files for asdf/defsystem.
See asdf.asd for the order in which they are loaded.
uiop/
Utilities of Implementation- and OS- Portability,
the portability layer of ASDF. It has its own README,
and functions all have docstrings.
Makefile
a minimal Makefile for bootstrapping purposes.
Most of the logic is in the asdf-tools system
tools/
asdf-tools, a system to build, test and release ASDF. It includes:
asdf-tools -- a shell script to run it as a shell command.
load-asdf.lisp -- how to load ASDF in a self-contained project
asdf-tools.asd -- system definition for asdf-tools
*.lisp -- the source code for asdf-tools
install-asdf-as-module -- replace and update an implementation's ASDF
build.xcvb
The system definition for building ASDF with XCVB.
It hasn't been tested or maintained for years and has bitrotten.
version.lisp-expr
The current version. Bumped up every time the code changes, using
./tools/asdf-builder bump
doc/
documentation for ASDF, including:
index.html -- the web page for http://common-lisp.net/project/asdf/
asdf.texinfo -- our manual
Makefile -- how to build the manual
cclan.png lisp-logo120x80.png style.css favicon.ico
-- auxiliaries of index.html
test/
regression test scripts (and ancillary files) for developers to check
that they don't unintentionally break any of the functionality of ASDF.
Far from covering all of ASDF.
contrib/
a few contributed files that show case how to use ASDF.
debian/
* `asdf.asd`
* The system definition for building ASDF with ASDF.
* `*.lisp`
* The source code files for asdf/defsystem.
See asdf.asd for the order in which they are loaded.
* `uiop/`
* Utilities of Implementation- and OS- Portability,
the portability layer of ASDF. It has its own `README`,
and functions all have docstrings.
* `Makefile`
* a minimal Makefile for bootstrapping purposes.
Most of the logic is in the asdf-tools system
* `tools/`
* `asdf-tools`, a system to build, test and release ASDF. It includes:
* `asdf-tools` -- a shell script to run it as a shell command.
* `load-asdf.lisp` -- how to load ASDF in a self-contained project
* `asdf-tools.asd` -- system definition for asdf-tools
* `*.lisp` -- the source code for asdf-tools
* Also in this directory:
* `install-asdf.lisp` -- replace and update an implementation's ASDF
* `cl-source-registry-cache.lisp` -- update a cache for the source-registry
* `build.xcvb`
* The system definition for building ASDF with XCVB.
It hasn't been tested or maintained for years and has bitrotten.
* `version.lisp-expr`
* The current version. Bumped up every time the code changes, using:
./tools/asdf-builder bump
* `doc/`
* documentation for ASDF, including:
* `index.html` -- the web page for http://common-lisp.net/project/asdf/
* `asdf.texinfo` -- our manual
* `Makefile` -- how to build the manual
* `cclan.png` `lisp-logo120x80.png` `style.css` `favicon.ico`
-- auxiliaries of `index.html`
* `test/`
* regression test scripts (and ancillary files) for developers to check
that they don't unintentionally break any of the functionality of ASDF.
Far from covering all of ASDF.
* `contrib/`
* a few contributed files that show case how to use ASDF.
* `debian/`
files for packaging on debian, ubuntu, etc.
build/
where the Makefile and asdf-tools store their output files, including
asdf.lisp -- the current one-file deliverable of ASDF
asdf-XXX.lisp -- for upgrade test purposes, old versions
results/ -- logs of tests that have been run
fasls/ -- output files while running tests.
* `build/`
* where the Makefile and asdf-tools store their output files, including
* `asdf.lisp` -- the current one-file deliverable of ASDF
* `asdf-XXX.lisp` -- for upgrade test purposes, old versions
* `results/` -- logs of tests that have been run
* `fasls/` -- output files while running tests.
ext/
external dependencies, that can be populated with `make ext`
or equivalently with `git submodule update`.
* `ext/`
* external dependencies, that can be populated with `make ext`
or equivalently with `git submodule update`.
README
this file
* `README`
* this file
TODO
plenty of ideas for how to further improve ASDF.
* `TODO`
* plenty of ideas for how to further improve ASDF.
Last updated Tuesday, September 2nd, 2014.
Last updated Thursday, September 11th, 2014.
......@@ -1751,25 +1751,21 @@ and create a file @file{my-lib.asd}
with the @code{:class :package-inferred-system} option in its @code{defsystem}.
For instance:
@example
#-asdf (error "my-lib requires ASDF 3")
#-asdf3 (error "my-lib requires ASDF 3")
(defsystem my-lib
:class :package-inferred-system
:defsystem-depends-on (:asdf-package-system)
:depends-on (:lil/interface/all
:lil/pure/all
:lil/stateful/all
:lil/transform/all)
:in-order-to ((test-op (load-op :lil/test/all)))
:perform (test-op (o c) (symbol-call :lil/test/all :test-suite)))
(defsystem :lil/test :depends-on (:lil/test/all))
(register-system-packages :lil/interface/all '(:interface))
(register-system-packages :lil/pure/all '(:pure))
(register-system-packages :lil/stateful/all '(:stateful))
(register-system-packages :lil/transform/classy '(:classy))
(register-system-packages :lil/transform/posh '(:posh))
(register-system-packages :lil/test/all '(:lil/test))
:depends-on (:my-lib/interface/all
:my-lib/src/all
:my-lib/extras/all)
:in-order-to ((test-op (load-op :my-lib/test/all)))
:perform (test-op (o c) (symbol-call :my-lib/test/all :test-suite)))
(defsystem :my-lib/test :depends-on (:my-lib/test/all))
(register-system-packages :my-lib/interface/all '(:my-lib-interface))
(register-system-packages :my-lib/src/all '(:my-lib-implementation))
(register-system-packages :my-lib/test/all '(:my-lib-test))
(register-system-packages
:closer-mop
......@@ -1809,9 +1805,11 @@ ASDF can tell that this file depends on system @code{closer-mop} (registered abo
(package and system names match, and they will be looked up hierarchically).
ASDF also detects dependencies from @code{:import-from} clauses.
To depend on a system without using a package or importing any symbol from it
(because you'll fully qualify them when used),
you may thus use an @code{:import-from} clause with an empty list of symbols, as in:
You may thus import a well-defined set of symbols from an existing package
as loaded from suitably named system;
or if you prefer to use any such symbol fully qualified by a package prefix,
you may declare a dependency on such a package and its corresponding system
via an @code{:import-from} clause with an empty list of symbols, as in:
@example
(defpackage :foo/bar
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment