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