diff --git a/.gitignore b/.gitignore index 7b8606d1776f1706181acf0c05b4d5793b6231c6..bc7d4b2e9451544f9c202b7cad11802dbfb3b5b1 100644 --- a/.gitignore +++ b/.gitignore @@ -26,6 +26,7 @@ doc/asdf.dvi *.tmp LICENSE +README.html tmp/ man/ lib/ diff --git a/README b/README deleted file mode 100644 index e29063ccac7da5bdc24266a42e5234c4a655cb82..0000000000000000000000000000000000000000 --- a/README +++ /dev/null @@ -1,186 +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/ - - or, assuming your implementation provides ASDF 3.1 or later:: - - ~/common-lisp/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 - -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:: - -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/ - 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/ - 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 Tuesday, September 2nd, 2014. diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..6a97c87c63fa1c3b172ad8854afe6a4339fecede --- /dev/null +++ b/README.md @@ -0,0 +1,192 @@ +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/` + * `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. + +* `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 2f41dfd41366baf07991ca9554111bbd5bcea67c..61e2e04e81d173faa6038750836f5e4d1c9e9611 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -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