Commit fe31090f authored by Francois-Rene Rideau's avatar Francois-Rene Rideau

Merge some documentation and tools tweaks from the minimakefile branch.

Move load-asdf.lisp to tools, as in the minimakefile branch.
parent 68e6693b
...@@ -26,6 +26,7 @@ doc/asdf.dvi ...@@ -26,6 +26,7 @@ doc/asdf.dvi
*.tmp *.tmp
LICENSE LICENSE
README.html
tmp/ tmp/
man/ man/
lib/ lib/
......
...@@ -42,7 +42,7 @@ More information and additional links can be found on ASDF's home page at: ...@@ -42,7 +42,7 @@ More information and additional links can be found on ASDF's home page at:
Quick Start Quick Start
------------- -----------
Just use `(require "asdf")` to load your implementation-provided ASDF. Just use `(require "asdf")` to load your implementation-provided ASDF.
...@@ -137,6 +137,7 @@ How do I navigate this source directory? ...@@ -137,6 +137,7 @@ How do I navigate this source directory?
* `tools/` * `tools/`
* Some scripts to help ASDF users * Some scripts to help ASDF users
* `load-asdf.lisp` -- a build script to load, configure and use ASDF
* `install-asdf.lisp` -- replace and update an implementation's ASDF * `install-asdf.lisp` -- replace and update an implementation's ASDF
* `cl-source-registry-cache.lisp` -- update a cache for the source-registry * `cl-source-registry-cache.lisp` -- update a cache for the source-registry
......
...@@ -18,8 +18,10 @@ ...@@ -18,8 +18,10 @@
;; Do everything in eval-when, so this works ;; Do everything in eval-when, so this works
;; whether this file is being loaded directly or compiled first. ;; whether this file is being loaded directly or compiled first.
(eval-when (:compile-toplevel :load-toplevel :execute) (eval-when (:compile-toplevel :load-toplevel :execute)
(load (make-pathname :name "load-asdf" :type "lisp" (let* ((this (or *load-pathname* *compile-file-pathname*)))
:defaults (or *load-pathname* *compile-file-pathname*)))) (load (merge-pathnames (make-pathname :name "load-asdf" :type "lisp"
:directory '(:relative :back "tools")
:defaults this) this))))
(in-package :asdf) (in-package :asdf)
......
...@@ -48,7 +48,7 @@ It notably doesn't work on: ...@@ -48,7 +48,7 @@ It notably doesn't work on:
#+clozure #p"ccl:tools;" #+clozure #p"ccl:tools;"
#+cmu #p"modules:asdf/" #+cmu #p"modules:asdf/"
#+(or ecl mkcl) #p"sys:" #+(or ecl mkcl) #p"sys:"
#+gcl system:*system-directory* #+gcl (subpathname system:*system-directory* "../modules/")
#+lispworks (system:lispworks-dir "load-on-demand/utilities/") #+lispworks (system:lispworks-dir "load-on-demand/utilities/")
#+sbcl (subpathname (sb-int:sbcl-homedir-pathname) "contrib/") #+sbcl (subpathname (sb-int:sbcl-homedir-pathname) "contrib/")
#+scl #p"file://modules/" #+scl #p"file://modules/"
......
...@@ -13,69 +13,64 @@ All exported symbols are reexported in a convenience package `UIOP`. ...@@ -13,69 +13,64 @@ All exported symbols are reexported in a convenience package `UIOP`.
The files that constitute UIOP are, in loading order: The files that constitute UIOP are, in loading order:
* [`package`](package.lisp): deals with packages and their symbols, most * `package`: deals with packages and their symbols, most notably including
notably including `define-package`, a variant of `defpackage` capable of `define-package`, a variant of `defpackage` capable of hot-upgrade, or
hot-upgrade, or `symbol-call` and `find-symbol*` that are also useful `symbol-call` and `find-symbol*` that are also useful for use in `.asd` files
for use in `.asd` files before packages have been defined. before packages have been defined.
* [`common-lisp`](common-lisp.lisp): lets you paper over various * `common-lisp`: lets you paper over various sub-standard implementations.
sub-standard implementations. Big offenders are Big offenders are Corman, GCL, Genera, MCL, all of them unmaintained.
Corman, GCL, Genera, MCL, all of them unmaintained.
Supported without serious issues are: Supported without serious issues are:
ABCL, Allegro, CCL, CMUCL, CLISP, ECL, LispWorks, MKCL, SBCL, SCL, XCL. ABCL, Allegro, CCL, CMUCL, CLISP, ECL, LispWorks, MKCL, SBCL, SCL, XCL.
* [`utility`](utility.lisp): provides macros and functions not involving I/O; * `utility`: provides macros and functions that do not involve I/O; it handles
it handles control-flow, (p)lists, characters, strings, functions, classes, control-flow, (p)lists, characters, strings, functions, classes, conditions,
conditions, "stamps" (real number or boolean for +/- infinity), versions, "stamps" (real number or boolean for +/- infinity), versions, etc.
etc. It also sports `uiop-debug`, a useful tool to help you debug programs. It also sports `uiop-debug`, a useful tool to help you debug programs.
* [`os`](os.lisp): extracts information from your environment, including * `os`: extracts information from your environment, including
an ABI identifier, features that distinguish Unix vs Windows, an ABI identifier, features that distinguish Unix vs Windows,
`getenv`, `hostname`, `getcwd` and `chdir`, etc. `getenv`, `hostname`, `getcwd` and `chdir`, etc.
* [`pathname`](pathname.lisp): overcomes the gruesome non-portability trap * `pathname`: overcomes the gruesome non-portability trap that are CL pathnames
that are CL pathnames (and their lovecraftian "logical" variant), (and their lovecraftian "logical" variant), offering a vast array of
offering a vast array of functions and a sensible, usable abstraction functions and a sensible, usable abstraction to specify relative pathnames.
to specify relative pathnames. It has a function `merge-pathnames*` to use It has a function `merge-pathnames*` to use instead of `merge-pathnames`, or
instead of `merge-pathnames`, or ven better, `subpathname` and its variant even better, `subpathname` and its variant `subpathname*`; it has also plenty
`subpathname*`; it has also plenty of functions for dealing with pathnames of functions for dealing with pathnames being directory vs file,
being directory vs file, physical vs logical, absolute vs relative, and more. physical vs logical, absolute vs relative, and more.
* [`filesystem`](filesystem.lisp): provides portable access to the filesystem, * `filesystem`: provides portable access to the filesystem, inspecting it,
inspecting it, only using `truename` when desired, using native OS namestrings, only using truename when desired, using native OS namestrings,
atomic file renaming, creating or deleting directories, etc. atomic file renaming, creating or deleting directories, etc.
* [`stream`](stream.lisp): portably deals with `*stderr*` vs `*error-output*`, * `stream`: portably deals with `*stderr*` vs `*error-output*`, character encodings
character encodings (external formats), element types, safe `read`ing and (external formats), element types, safe `read`ing and `write`ing, opening files
`write`ing, opening files or temporary files, providing `format`-like or temporary files, providing `format`-like designators for streams,
designators for streams, flushing output buffers, consuming or copying flushing output buffers, consuming or copying streams, concatenating streams
streams, concatenating streams or files, copying files, etc. or files, copying files, etc.
* [`image`](image.lisp): portably deals with images, dumping them, restoring * `image`: portably deals with images, dumping them, restoring from them,
from them, registering hooks to run at suitable events in the image lifetime, registering hooks to run at suitable events in the image lifetime,
printing backtraces, handling fatal conditions, using or avoiding debug modes, printing backtraces, handling fatal conditions, using or avoiding debug modes,
accessing command line arguments or quitting the process. accessing command line arguments or quitting the process.
* [`run-program`](run-program.lisp): portably spawns external processes and * `run-program`: portably spawns external processes and captures their output.
captures their output. Can also capture error-output, inject input, Can also capture error-output, inject input, or let it all be interactive.
or let it all be interactive.
* [`lisp-build`](lisp-build.lisp): portably compiles Common Lisp code, * `lisp-build`: portably compiles Common Lisp code, handles compilation results,
handles compilation results, muffles uninteresting conditions, muffles uninteresting conditions, saves and restores deferred warnings,
saves and restores deferred warnings, runs hooks around compilation runs hooks around compilation (to e.g. control optimizations or syntax),
(to e.g. control optimizations or syntax), identifies the pathname identifies the pathname of the current file, combines FASLs, etc.
of the current file, combines FASLs, etc.
* [`configuration`](configuration.lisp): helps you define portable * `configuration`: helps you define portable configuration files, using best
configuration files, using best practices to define and validate syntax, practices to define and validate syntax, search standard paths,
search standard paths, let users specify pathnames or pathname patterns, etc. let users specify pathnames or pathname patterns, etc.
* [`backward-driver`](backward-driver.lisp): provides backward-compatibility * `backward-driver`: provides backward-compatibility with earlier incarnations
with earlier incarnations of this library (i.e. ASDF internals that have of this library (i.e. ASDF internals that have leaked, or ASDF-UTILS)
leaked, or ASDF-UTILS). Do not use in new code.
* [`driver`](driver.lisp): reexports all the above utilities * `driver`: reexports all the above utilities in a single package `UIOP`.
in a single package `UIOP`.
Documentation Documentation
...@@ -93,12 +88,12 @@ One tool with which you can extract all the documentation is HEΛP. ...@@ -93,12 +88,12 @@ One tool with which you can extract all the documentation is HEΛP.
At this time, the interface is not great, but if you use the scrollbar on the right At this time, the interface is not great, but if you use the scrollbar on the right
of the left side panel, you can see many packages and from there the defined symbols: of the left side panel, you can see many packages and from there the defined symbols:
> [http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html](http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html) http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html
Another automated documentation tool is quickdocs, but unhappily, at the time of this writing, Another automated documentation tool is quickdocs, but unhappily, at the time of this writing,
it only extracts information from the first package: it only extracts information from the first package:
> [http://quickdocs.org/uiop/api](http://quickdocs.org/uiop/api) http://quickdocs.org/uiop/api
Using UIOP Using UIOP
...@@ -126,14 +121,12 @@ Some history ...@@ -126,14 +121,12 @@ Some history
UIOP, formerly known as ASDF-DRIVER (the package and system nicknames live on), UIOP, formerly known as ASDF-DRIVER (the package and system nicknames live on),
evolved from ASDF 2's internal utilities and portability layer. evolved from ASDF 2's internal utilities and portability layer.
It has since fully superseded functionality from the following libraries: It has since fully superseded functionality from the following libraries:
ASDF-UTILS (UIOP carries on the ASDF 2 utilities that this exported),
* ASDF-UTILS (UIOP carries on the ASDF 2 utilities that ASDF-UTILS exported), CL-FAD (UIOP's pathname and filesystem functions are much more portable),
* CL-FAD (UIOP's pathname and filesystem functions are much more portable), CL-LAUNCH (UIOP took its image and command-line argument handling from it),
* CL-LAUNCH (UIOP took its image and command-line argument handling from it), EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER (UIOP's run-program is better),
* EXECUTOR, EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER SLIME's swank-loader (UIOP has better compilation and API identification),
(UIOP improved on their `run-program` facilities), TRIVIAL-BACKTRACE (UIOP/IMAGE has all of it and more), etc.
* SLIME's `swank-loader` (UIOP has better compilation and API identification),
* TRIVIAL-BACKTRACE (UIOP/IMAGE has all of it and more), etc.
UIOP also captures a large subset of the functionality from TRIVIAL-FEATURES, UIOP also captures a large subset of the functionality from TRIVIAL-FEATURES,
and a small subset of the functionality from ALEXANDRIA or FARE-UTILS. and a small subset of the functionality from ALEXANDRIA or FARE-UTILS.
......
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