diff --git a/README.md b/README.md index a58ea31a7226c555fe50cdf947eb850d018784ab..32a001cc9ded7e164b9ef7ee7c477a9a2e6e4b5a 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ ASDF is the de facto standard build facility for Common Lisp. Your Lisp implementation probably contains a copy of ASDF, which you can load using `(require "asdf")`. -If you come from the C/C++ world, the ASDF covers a bit of what each of +If you come from the C/C++ world, 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, @@ -25,15 +25,15 @@ 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: +The manual is also in the [doc/](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. +[UIOP, the Utilities for Implementation- and OS- Portability](uiop/). Its documentation unhappily lies mainly in the source code and docstrings. -See [`uiop/README.md`](uiop/README.md) for an introduction. +See [uiop/README.md](uiop/README.md) for an introduction. More information and additional links can be found on ASDF's home page at: <http://common-lisp.net/project/asdf/> @@ -62,7 +62,7 @@ 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: +If you cloned our git repository, bootstrap a copy of `build/asdf.lisp` with: make @@ -98,7 +98,7 @@ choose your most elaborate installed system $S, and try: Debugging tip ------------- -To load ASDF in such a way that M-. will work, install the source code, and run: +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 @@ -113,7 +113,7 @@ to the call to `asdf::required-components`. What has changed? ----------------- -You can consult the `debian/changelog` for an overview of the +You can consult the [debian/changelog](debian/changelog) for an overview of the significant changes in each release, and the `git log` for a detailed description of each commit. @@ -121,77 +121,78 @@ the `git log` for a detailed description of each commit. How do I navigate this source directory? ---------------------------------------- -* `asdf.asd` +* [asdf.asd](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. + * The source code files for `asdf/defsystem`. + See [asdf.asd](asdf.asd) for the order in which they are loaded. -* `uiop/` +* [uiop/](uiop/) * Utilities of Implementation- and OS- Portability, - the portability layer of ASDF. It has its own `README`, + the portability layer of ASDF. It has its own [README](uiop/README.md), and functions all have docstrings. -* `Makefile` - * a minimal Makefile for bootstrapping purposes. - Most of the logic is in the asdf-tools system +* [Makefile](Makefile) + * a minimal `Makefile` for bootstrapping purposes. + Most of the logic is in the [asdf-tools](tools/asdf-tools.asd) system below. -* `tools/` +* [tools/](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 + * [asdf-tools](tools/asdf-tools) -- a shell script to run it as a shell command. + * [load-asdf.lisp](tools/load-asdf.lisp) -- how to load ASDF in a self-contained project + * [asdf-tools.asd](tools/asdf-tools.asd) -- system definition for asdf-tools + * `*.lisp` -- the source code for `asdf-tools` * also a couple 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 + * [load-asdf.lisp](tools/load-asdf.lisp) -- a build script to load, configure and use ASDF + * [install-asdf.lisp](install-asdf.lisp) -- replace and update an implementation's ASDF + * [cl-source-registry-cache.lisp](cl-source-registry-cache.lisp) -- update a cache for the source-registry -* `build.xcvb` +* [build.xcvb](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` +* [version.lisp-expr](version.lisp-expr) * The current version. Bumped up every time the code changes, using: - ./tools/asdf-builder bump + ./tools/asdf-builder bump -* `doc/` +* [doc/](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/` + * [index.html](doc/index.html) -- the web page for <http://common-lisp.net/project/asdf/> + * [asdf.texinfo](doc/asdf.texinfo) -- our manual + * [Makefile](doc/Makefile) -- how to build the manual + * [cclan.png](doc/cclan.png) [lisp-logo120x80.png](doc/lisp-logo120x80.png) + [style.css](doc/style.css) [favicon.ico](doc/favicon.ico) + -- auxiliaries of [index.html](doc/index.html) + +* [test/](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/` +* [contrib/](contrib/) * a few contributed files that show case how to use ASDF. -* `debian/` - files for packaging on debian, ubuntu, etc. +* [debian/](debian/) + * files for packaging on Debian, Ubuntu, etc. -* `build/` - * where the Makefile and asdf-tools store their output files, including +* [build/](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/` +* [ext/](ext/) * external dependencies, that can be populated with `make ext` or equivalently with `git submodule update --init`. -* `README` +* [README.md](README.md) * this file -* `TODO` +* [TODO](TODO) * plenty of ideas for how to further improve ASDF. -Last updated Sunday, March 22nd, 2015. +Last updated Wednesday, May 6th, 2015. diff --git a/doc/index.html b/doc/index.html index a430cc9b917159f5d209739088dee20f95053baa..65f595c10d0ebf69a4925a27d76d3b196981a658 100644 --- a/doc/index.html +++ b/doc/index.html @@ -84,7 +84,12 @@ call other programs and parse their output, compile Lisp code, muffle conditions, or configure Lisp software. See its - <a href="https://gitlab.common-lisp.net/asdf/asdf/tree/master/uiop/README.md">README.md</a>. + <a href="https://gitlab.common-lisp.net/asdf/asdf/tree/master/uiop/README.md">README.md</a> for an overview, + and the documentation as extracted from its docstrings by + <a href="http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html">HEΛP</a> + (beware: you can, though it's not obvious, scroll the list of packages + with a scroll the right of the top-left pane, and then click on the one + you're interested in to browse its symbols). </p> <p><tt>uiop</tt> is distributed as part of the <tt>ASDF</tt>, its source code is transcluded in the single-file <tt>asdf.lisp</tt> being distributed @@ -120,14 +125,15 @@ <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a> (also reimplemented as the ASDF extension <a href="https://gitlab.common-lisp.net/asdf/asdf-package-system" - ><tt>asdf-package-system</tt></a>; similar to <tt>faslpath</tt> below). + ><tt>asdf-package-system</tt></a>, now part of ASDF 3; + similar to <tt>faslpath</tt> below). </li> <li>François-René Rideau's <a href="https://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a> (building object and image files deterministically and in parallel, but not actively maintained since 2012; - thanks to its new build model, ASDF 3 could conceivably be modified - to support these features). + a hypothetical ASDF 4 could conceivably be evolved to support these features + thanks to the groundwork laid by ASDF 3). </li> <li>Drew McDermott's <a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a> @@ -187,16 +193,16 @@ <td align="left"><tt>mcl xcl</tt></td></tr> <tr><th align="left">Proprietary</th> <td align="left"><tt>allegro</tt></td> - <td align="left"><tt>lispworks mocl</tt></td> - <td align="left"><tt>cormanlisp genera scl</tt></td></tr> + <td align="left"><tt>lispworks</tt></td> + <td align="left"><tt>cormanlisp genera mocl scl</tt></td></tr> </table> <p> To deal with an implementation that doesn't yet provide ASDF 3, - we provide <a href="https://common-lisp.net/asdf/asdf/tree/master/tools/install-asdf.lisp">a script</a> that can install ASDF 3 - where your implementation goes looking for it + we provide <a href="https://common-lisp.net/asdf/asdf/tree/master/tools/install-asdf.lisp">a script</a> + that can install ASDF 3 where your implementation goes looking for it when you <tt>(require "asdf")</tt> . </p><p> - Alternatively, if the implementation provides ASDF 2 + Alternatively, though we don't recommend it, if the implementation provides ASDF 2 (as do <tt>lispworks mocl xcl</tt> or older versions of some implementations) or an overly old version of ASDF 3, you can download, install and configure a more recent ASDF 3, @@ -329,7 +335,7 @@ XCL (Peter Graves) <gnooth@gmail.com> to compute the actual dependencies in a big ASDF system.</li> <li><a href="https://common-lisp.net/project/qitab/" ><tt>poiu</tt></a>, - to compile a system in parallel.</li> + to compile a system in parallel on a multiprocessor machine.</li> <li><a href="https://common-lisp.net/project/asdf-system-connections/" ><tt>asdf-system-connections</tt></a>, lets you specify systems that are automatically loaded when @@ -337,19 +343,10 @@ XCL (Peter Graves) <gnooth@gmail.com> <li><a href="http://www.lrde.epita.fr/~didier/software/lisp/misc.php#asdf-flv" ><tt>asdf-flv</tt></a>, to bind file-local variables around the compilation of some files.</li> - <li><a href="http://gitlab.common-lisp.net/asdf/asdf-package-system" - ><tt>asdf-package-system</tt></a>, - to compile Lisp source files with one package per file - that also determines dependencies, in the style of - <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a> or - <a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a> - (this functionality is built into recent versions of ASDF 3.1 and later, - but this package exists for backward compatibility with earlier versions of ASDF 3; - search the manual for <tt>package-inferred-system</tt>). </ul> <p>Former extensions, now superseded, include:</p> <ul> - <li><tt>asdf-binary-locations</tt> allowed one to redirect where ASDF creates its output files, + <li><tt>asdf-binary-locations</tt> used to allow one to redirect where ASDF 1 created its output files, so they don't clash between implementations and don't pollute source directories. It is superseded by <tt>asdf/defsystem</tt>'s builtin <tt>asdf-output-translations</tt> mechanism; @@ -366,16 +363,26 @@ XCL (Peter Graves) <gnooth@gmail.com> a standalone executable program (on supported implementations), or an image containing your system precompiled. </li> + <li><tt>asdf-condition-control</tt>, initially part of XCVB's <tt>xcvb-driver</tt>, + allowed you to muffle uninteresting conditions during compilation. + Is now superseded by equivalent functionality in <tt>uiop</tt>. + </li> + <li><a href="http://gitlab.common-lisp.net/asdf/asdf-package-system" + ><tt>asdf-package-system</tt></a>, + to compile Lisp source files with one package per file + that also determines dependencies, in the style of + <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a> or + <a href="http://www.cliki.net/faslpath"><tt>faslpath</tt></a> + (this functionality is built into recent versions of ASDF 3.1 and later, + but this package exists for backward compatibility with earlier versions of ASDF 3; + search the manual for <tt>package-inferred-system</tt>). + </li> <li><tt>asdf-utils</tt> was a collection of utilities that originated with ASDF. It is now superseded by <tt>uiop</tt>, aka <tt>asdf/driver</tt>, which is part of ASDF, and exports its functionality in its own package <tt>uiop</tt>. </li> - <li><tt>asdf-condition-control</tt>, initially part of XCVB's <tt>xcvb-driver</tt>, - allowed you to muffle uninteresting conditions during compilation. - Is now superseded by equivalent functionality in <tt>uiop</tt>. - </li> </ul> <h3>Contributing</h3> @@ -497,9 +504,9 @@ XCL (Peter Graves) <gnooth@gmail.com> <a class="nav" href="http://www.catb.org/hacker-emblem/" title="hacker"> <img src="http://common-lisp.net/project/cl-containers/shared/buttons/hacker.png" width="80" height="15" title="hacker emblem" alt="hacker button" /></a> <a class="nav" href="http://www.lisp.org/" title="Association of Lisp Users"> <img src="http://common-lisp.net/project/cl-containers/shared/buttons/lambda-lisp.png" width="80" height="15" title="ALU emblem" alt="ALU button" /></a> <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><span class="copyright"Copyright © 2001-2015 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 2015-03-28</div> + <div id="timestamp">Last updated 2015-05-05</div> </div> </body> </html> diff --git a/uiop/README.md b/uiop/README.md index b3a23b1ebb699fc315cddaccc29a08548c9b8b60..8c79bf9cd4555f4e3eb358abd83df0b87597ad5d 100644 --- a/uiop/README.md +++ b/uiop/README.md @@ -1,5 +1,5 @@ -UIOP the Utilities for Implementation- and OS- Portability -========================================================== +UIOP, the Utilities for Implementation- and OS- Portability +=========================================================== UIOP is the portability layer of ASDF. It provides utilities that abstract over discrepancies between implementations, @@ -7,32 +7,35 @@ between operating systems, and between what the standard provides and what programmers actually need, to write portable Common Lisp programs. It is organized by topic in many files, each of which defines its own package -according to its topic: e.g `pathname.lisp` will define package `UIOP/PATHNAME` -and contain utilities related to the handling of pathname objects. -All exported symbols are reexported in a convenience package `UIOP`. +according to its topic: e.g [pathname.lisp](pathname.lisp) +will define package `UIOP/PATHNAME` and contain utilities related to +the handling of pathname objects. +All exported symbols are reexported in a convenience package `UIOP`, +except for those from `UIOP/COMMON-LISP`. +We recommend package `UIOP` be used to access all the symbols. -The files that constitute UIOP are, in loading order: +The files that constitute UIOP are, in dependency loading order: -* `package`: deals with packages and their symbols, most notably including +* [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`: lets you paper over various sub-standard implementations. +* [common-lisp](common-lisp.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. + ABCL, Allegro, CCL, CMUCL, CLASP, CLISP, ECL, LispWorks, MKCL, SBCL, SCL, XCL. -* `utility`: provides macros and functions that do not involve I/O; it handles +* [utility](utility.lisp): 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`: extracts information from your environment, including +* [os](os.lisp): extracts information from your environment, including an ABI identifier, features that distinguish Unix vs Windows, `getenv`, `hostname`, `getcwd` and `chdir`, etc. -* `pathname`: overcomes the gruesome non-portability trap that are CL pathnames +* [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 @@ -40,37 +43,38 @@ The files that constitute UIOP are, in loading order: of functions for dealing with pathnames being directory vs file, physical vs logical, absolute vs relative, and more. -* `filesystem`: provides portable access to the filesystem, inspecting it, +* [filesystem](filesystem.lisp): 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`: portably deals with `*stderr*` vs `*error-output*`, character encodings +* [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. -* `image`: portably deals with images, dumping them, restoring from them, +* [image](image.lisp): 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`: portably spawns external processes and captures their output. +* [run-program](program.lisp): portably spawns external processes and captures their output. Can also capture error-output, inject input, or let it all be interactive. -* `lisp-build`: portably compiles Common Lisp code, handles compilation results, +* [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. -* `configuration`: helps you define portable configuration files, using best - practices to define and validate syntax, search standard paths, +* [configuration](configuration.lisp): portably locate and parse configuration files, + using best practices to define and validate syntax, search standard paths, let users specify pathnames or pathname patterns, etc. -* `backward-driver`: provides backward-compatibility with earlier incarnations - of this library (i.e. ASDF internals that have leaked, or ASDF-UTILS) +* [backward-driver](backward-driver.lisp): provides backward-compatibility + with earlier incarnations of this library + (i.e. ASDF internals that have leaked, ASDF-UTILS, or older versions of UIOP). -* `driver`: reexports all the above utilities in a single package `UIOP`. +* [driver](driver.lisp): reexports all the above utilities in a single package `UIOP`. Documentation @@ -85,15 +89,20 @@ Maybe some automated tool will extract all that information and make a webpage from it, at which point it would be nice to insert a link here. 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: +At this time, the interface is not great: it isn't obvious at all that you can indeed +use a scrollbar on the right of the top left side panel to navigate the many packages; +once you click on the package you're interested in, you can see its 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> 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 +(see [bug #24](https://github.com/fukamachi/quickdocs/issues/24)): - http://quickdocs.org/uiop/api +* <http://quickdocs.org/uiop/api> + + +Help wanted extracting working documentation from UIOP's docstrings. Using UIOP @@ -123,11 +132,16 @@ 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 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), +CL-LAUNCH (UIOP took its image and command-line argument handling), +EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER (UIOP's run-program evolved +from XCVB-DRIVER's, and so did its condition muffling), +SLIME's swank-loader (UIOP has better compilation and ABI 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. +We recommend you use UIOP instead of any of the above, where applicable, +since UIOP is more portable, more robust, more ubiquitous, better designed, +better documented, etc. If you see any way in which UIOP isn't superior, +we're interested in improving it so it become so.