diff --git a/README b/README deleted file mode 100644 index 4eda55a4073d0232d7d5adba59a97281d101d9a6..0000000000000000000000000000000000000000 --- a/README +++ /dev/null @@ -1,88 +0,0 @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..ea6acc0eea76f52fcaaa7089fc02463d3db780c9 --- /dev/null +++ b/README.md @@ -0,0 +1,187 @@ +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. diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 57be62543c8445808fe41795ea94811094394c11..61e2e04e81d173faa6038750836f5e4d1c9e9611 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -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 diff --git a/doc/index.html b/doc/index.html index dbd416d944dfef2f45df3d2db518b91ba5619485..b00580aab69a3396a97409f173f4c578346998a5 100644 --- a/doc/index.html +++ b/doc/index.html @@ -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 © 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> diff --git a/test/script-support.lisp b/test/script-support.lisp index c85f209a1c03262f07f6e55f1362840de5ce5519..d4c83b3afa4e0b388e5eb83fda3ac7e246bbd741 100644 --- a/test/script-support.lisp +++ b/test/script-support.lisp @@ -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) diff --git a/test/test-cache.script b/test/test-cache.script index 81e8ff7278ac9c7f1ac304b3e2afc5bae17acd54..4ac015f71397d8cff9cb309629fd91b8b44325d5 100644 --- a/test/test-cache.script +++ b/test/test-cache.script @@ -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 diff --git a/test/test-package.script b/test/test-package.script index b8c1b686b0d6d87704e6a2009926331dc0fb0d38..136c87b2af5615b9b26f7ac82611fe4ec3b05d81 100644 --- a/test/test-package.script +++ b/test/test-package.script @@ -1,9 +1,9 @@ ;;; -*- 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")) diff --git a/test/test-retry-loading-component-1.script b/test/test-retry-loading-component-1.script index 2097ce06e1bb84ca25dcc1e1176b69f16baeebf2..35a8c13bad612dd156522c171d9d2a1f6c8f2a9f 100644 --- a/test/test-retry-loading-component-1.script +++ b/test/test-retry-loading-component-1.script @@ -1,16 +1,20 @@ ;;; -*- 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) diff --git a/test/test-run-program.script b/test/test-run-program.script index 39abbe4931120c450cab77556d29a23a3d981450..227b1f536c46ff2eaa4a7921af4cefb2176e71a4 100644 --- a/test/test-run-program.script +++ b/test/test-run-program.script @@ -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) - diff --git a/test/test-utilities.script b/test/test-utilities.script index ec02a68fd54411ff6690d82cbb8bc89ca65bf3cd..d4a70dc301c8ae64c263186d8bdf868599daece2 100644 --- a/test/test-utilities.script +++ b/test/test-utilities.script @@ -1,5 +1,10 @@ ;;; -*- 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 diff --git a/test/test-version.script b/test/test-version.script index 092387caf5f3c6f51c210b977254a8236f4d263e..295e108a72ec1c599b591cb58742ab1739747b3a 100644 --- a/test/test-version.script +++ b/test/test-version.script @@ -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)) diff --git a/tools/cl-source-registry-cache.lisp b/tools/cl-source-registry-cache.lisp old mode 100644 new mode 100755 diff --git a/bin/install-asdf-as-module b/tools/install-asdf.lisp old mode 100644 new mode 100755 similarity index 95% rename from bin/install-asdf-as-module rename to tools/install-asdf.lisp index 5361dad7ecf340ff7b52c09af83e1236936ca6bd..3097207b5680a749da0aaa5ef621a8d87c351a9e --- a/bin/install-asdf-as-module +++ b/tools/install-asdf.lisp @@ -1,7 +1,9 @@ ":" ; 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.