Commit 20b36a4e authored by Francois-Rene Rideau's avatar Francois-Rene Rideau

Backport some changes from the minimakefile branch.

* README updated, converted to markdown
* Some documentation updates
* bin/install-asdf-as-module renamed to tools/install-asdf.lisp and improved.
* Update test scripts to be work even when the initial getcwd isn't in test/
parent 6c052bf0
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/
What is ASDF?
-------------
ASDF is the de facto standard build facility for Common Lisp.
If you come from the C/C++ world, the function ASDF covers a bit of what
each of make, autoconf, dlopen and libc do for C programs:
it orchestrates the compilation and dependency management,
handles some of the portability issues, dynamically finds and loads code,
and offers some portable system access.
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::
http://common-lisp.net/project/asdf/asdf.html
The first few sections, Loading ASDF, Configuring ASDF and Using ASDF,
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::
make doc
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.
More information and additional links can be found on ASDF's home page at::
http://common-lisp.net/project/asdf/
Building and testing it
-----------------------
If you cloned our git repository, bootstrap a copy of build/asdf.lisp with::
make
To run all the tests on your favorite Lisp implementation $L,
choose your most elaborate installed system $S, and try::
make t u l=$L s=$S
Debugging tip
-------------
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)))
What has changed?
-----------------
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.
Last updated Wednesday, March 13th, 2014.
ASDF: Another System Definition Facility
========================================
What is ASDF?
-------------
ASDF is the de facto standard build facility for Common Lisp.
If you come from the C/C++ world, the function ASDF covers a bit of what
each of make, autoconf, dlopen and libc do for C programs:
it orchestrates the compilation and dependency management,
handles some of the portability issues, dynamically finds and loads code,
and offers some portable system access.
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:
http://common-lisp.net/project/asdf/asdf.html
The first few sections, Loading ASDF, Configuring ASDF and Using ASDF,
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:
make doc
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`](uiop/README) for an introduction.
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
-----------------------
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:
make ext
The above make target uses `git submodule update` to download
all these libraries using git. If you don't otherwise maintain your
own set of carefully controlled CL libraries, that's what you want to use.
However, if you do maintain your own set of carefully controlled CL libraries
then you will want to use whichever tools you use (e.g. quicklisp, clbuild,
or your own scripts around git) to download these libraries:
alexandria, closer-mop, cl-ppcre, fare-mop, fare-quasiquote, fare-utils,
inferior-shell, lisp-invocation, named-readtables, optima.
If you are a CL developer, you may already have them, or may want
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:
make ext
To run all the tests on your favorite Lisp implementation $L,
choose your most elaborate installed system $S, and try:
make t u l=$L s=$S
Debugging tip
-------------
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)))
What has changed?
-----------------
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.
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/`
* Some scripts to help ASDF users
* `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.
* `ext/`
* external dependencies, that can be populated with `make ext`
or equivalently with `git submodule update`.
* `README`
* this file
* `TODO`
* plenty of ideas for how to further improve ASDF.
Last updated Thursday, September 11th, 2014.
......@@ -498,25 +498,19 @@ as explained below.
If all fails, we recommend you load ASDF from source
@pxref{Loading ASDF,,Loading ASDF from source}.
The ASDF source repository contains a script
@file{bin/install-asdf-as-module} that can help you upgrade your implementation's ASDF.
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.
It works on
Allegro CL, Clozure CL, CMU CL, ECL, GNU CLISP, LispWorks, MKCL, SBCL, SCL, XCL.
That's all known implementations except ABCL, Corman CL, GCL, Genera, MCL, MOCL.
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.
Happily, ABCL is usually pretty up to date and shouldn't need that script.
GCL would be supported, except that so far is still lacking usable support for @code{require}.
GCL requires a very recent version, and hasn't been tested for lack of success compiling it.
Corman CL, Genera, MCL are obsolete anyway.
MOCL is under development.
On an old version of an implementation that does not provide ASDF,
you may have to load ASDF 3 from source before you load that script.
The script relies on @code{cl-launch} 4 for command-line invocation,
which may depend on ASDF being checked out in @file{~/common-lisp/asdf/}
(which we recommend anyway)
if your implementation doesn't even have an ASDF 2.
If you don't have @code{cl-launch},
you can instead @code{(load "bin/install-asdf-as-module")}
from your implementation's REPL after loading ASDF from source.
Finally, if your implementation only provides ASDF 2,
and you can't or won't upgrade it or override its ASDF module,
......@@ -1757,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
......@@ -1815,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
......@@ -3459,7 +3451,7 @@ The list can also be empty, allowing to stop a costly recursion in a huge direct
To update such a cache after you install, update or remove source repositories,
you can run a script distributed with ASDF:
@code{./tools/cl-source-registry-cache.lisp @emph{/path/to/directory}}.
@code{tools/cl-source-registry-cache.lisp @emph{/path/to/directory}}.
To wholly invalidate the cache, you can
delete the file @file{.cl-source-registry.cache} in that directory.
In either case, for an existing Lisp process to see this change,
......@@ -3475,10 +3467,19 @@ a software source repository or installation package.
Finally, advanced developers who juggle with a lot of code
in their @code{source-registry} may manually manage such a cache,
to allow for faster startup of Lisp programs.
This persistence cache can help you reduce startup latency.
For instance, on one machine with hundreds of source repositories,
such a cache shaves half a second at the startup
of every @code{#!/usr/bin/cl} script,
which makes a difference as to their subjective interactivity and usability.
of every @code{#!/usr/bin/cl} script using SBCL, more on other implementations;
this makes a notable difference as to
their subjective interactivity and usability.
The speedup will only happen if the implementation-provided ASDF is recent enough
(3.1.3.7 or later); it is not enough for a recent ASDF upgrade to be present,
since the upgrade will itself be found but
after the old version has scanned the directories without heeding such a cache.
To upgrade the implementation-provided ASDF,
use our script @code{tools/install-asdf.lisp}.
@node Configuration API, Introspection, Caching Results, Controlling where ASDF searches for systems
......
......@@ -199,7 +199,7 @@
</table>
<p>
To deal with an implementation that doesn't yet provide ASDF 3,
we provide <a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=bin/install-asdf-as-module">a script</a> that can install ASDF 3
we provide <a href="http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=blob;f=tools/install-asdf.lisp">a script</a> that can install ASDF 3
where your implementation goes looking for it
when you <tt>require</tt> it.
Alternatively, if the implementation provides ASDF 2 or an older ASDF 3,
......@@ -497,7 +497,7 @@ XCL (Peter Graves) <gnooth@gmail.com>
<a class="nav" href="http://common-lisp.net/" title="Common-Lisp.net"> <img src="http://common-lisp.net/project/cl-containers/shared/buttons/lisp-lizard.png" width="80" height="15" title="Common-Lisp.net" alt="Common-Lisp.net button" /></a>
<p><span class="copyright"Copyright &copy; 2001-2014 Daniel Barlow and contributors</span></p>
<p>ASDF has an <a href="http://www.opensource.org/licenses/mit-license.php">MIT style</a> license</p>
<div id="timestamp">Last updated 2014-05-09</div>
<div id="timestamp">Last updated 2014-05-19</div>
</div>
</body>
</html>
......@@ -630,7 +630,6 @@ is bound, write a message and exit on an error. If
(defun test-upgrade (old-method new-method tag) ;; called by run-test
(with-test ()
(verbose t nil)
(setf tag (string tag))
(when old-method
(cond
((string-equal tag "REQUIRE")
......@@ -641,7 +640,7 @@ is bound, write a message and exit on an error. If
(leave-test "Your Lisp implementation does not provide ASDF. Skipping test.~%" 0)))
(t
(format t "Loading old asdf ~A via ~A~%" tag old-method)
(funcall old-method tag))))
(acall (list old-method :asdf-test) tag))))
(when (find-package :asdf)
(configure-asdf))
(when (and (null old-method) (eq 'load-asdf-fasl new-method) (not (probe-file (asdf-fasl))))
......@@ -649,7 +648,7 @@ is bound, write a message and exit on an error. If
(leave-test "Your failed to compile ASDF before your run (test-upgrade ()'load-asdf-fasl ...)" 1)
(leave-test "Your Lisp doesn't provide ASDF. Skipping (test-upgrade ()'load-asdf-fasl ...)" 0)))
(format t "Now loading new asdf via method ~A~%" new-method)
(funcall new-method)
(acall (list new-method :asdf-test))
(format t "Testing it~%")
(register-directory *test-directory*)
(load-test-system :test-asdf/all)
......
......@@ -2,8 +2,7 @@
;;; test to check that the cache doesn't upset error signaling from FIND-SYSTEM
(in-package asdf-test)
(in-package :asdf-test)
(defparameter *all-systems*
(list
......
;;; -*- Lisp -*-
;;; Testing that defclass module doesn't interfere with use of :module in defsystem.
(in-package :cl-user)
(asdf-test::with-test ()
(defun module () 1)
(load "test-package.asd")
(defclass module () ())
(load "test-package.asd"))
(defun module () 1)
(asdf::load-asd (asdf-test:test-source "test-package.asd"))
(defclass module () ())
(asdf::load-asd (asdf-test:test-source "test-package.asd"))
;;; -*- Lisp -*-
;; NB: this test does some evil side-effects in the test source directory itself. UGH!
;;; test asdf:try-recompiling restart
(defvar *caught-error* nil)
(delete-file-if-exists "try-reloading-dependency.asd")
(delete-file-if-exists (test-source "try-reloading-dependency.asd"))
(with-asdf-cache (:override t)
(handler-bind
((error #'(lambda (c)
(format t "~&Caught error ~s" c)
(assert (not *caught-error*) () "Déjà vu")
(setf *caught-error* t)
(concatenate-files '("try-reloading-dependency.hidden") "try-reloading-dependency.asd")
;; Evil side-effect: create a .asd file from .hidden file.
(concatenate-files (list (test-source "try-reloading-dependency.hidden"))
(test-source "try-reloading-dependency.asd"))
(DBG "trlc1 5")
(multiple-value-bind (name mode) (find-symbol* :retry :asdf)
(assert (eq mode :external) () "Mode of ~s was not external" name)
......
......@@ -37,9 +37,10 @@
#+os-unix
(progn
(chdir *test-directory*)
(DBG "Testing good shell command in current directory via run-shell-command")
(unless (equal 0 (run-shell-command "./good-shell-command"))
(error "Failed to capture exit status indicating shell command success."))
(assert-equal 0 (run-shell-command "./good-shell-command"))
;; this test checks for a problem there was in allegro -- :output :interactive
;; would try to open T as a stream for INPUT.
......@@ -263,4 +264,3 @@ Testing run-program
(test/run-program)
;;; -*- Lisp -*-
(chdir *asdf-directory*)
(assert (pathname-equal *asdf-directory* (getcwd)))
(chdir *test-directory*)
(assert (pathname-equal *test-directory* (getcwd)))
(assert
(every #'directory-pathname-p
(list
......
......@@ -37,7 +37,7 @@
(def-test-system :versioned-system-file-line
:defsystem-depends-on ((:version :test-asdf/2 "2.1"))
:pathname #.*test-directory*
:version (:read-file-line "version.lisp-expr" :at 1))
:version (:read-file-line #.(test-source "version.lisp-expr") :at 1))
(defun vtest (name v &optional (true t))
(or (eq true (version-satisfies (find-system name) v))
......
File mode changed from 100644 to 100755
":" ; exec cl-launch "$0" "$@" # -*- Lisp -*-
#|
Usage: make && cl-launch -l lispworks bin/install-asdf-as-module
Or make
Usage: make && ./tools/asdf-tools install-asdf lispworks
or make && l=lispworks ./tools/asdf-tools install-asdf
or make && cl-launch -l lispworks bin/install-asdf-as-module
or make
sbcl # or otherwise start your Lisp
(load "bin/install-asdf-as-module")
......@@ -20,7 +22,7 @@ It notably doesn't work on:
Also, MKCL now delivers UIOP separately from ASDF, which is great,
but requires support. Happily, both ECL and MKCL tend to sport
a recent ASDF 3, too.
* SBCL since 1.2.2 now like MKCL delivers UIOP separately from ASDF.
* SBCL since 1.2.3 now like MKCL delivers UIOP separately from ASDF.
* mocl, that doesn't support ASDF 3 yet.
* Corman Lisp, RMCL, Genera, that are obsolete anyway.
......
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