Skip to content
Snippets Groups Projects
Commit 95d2bdee authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

Merge branch 'master' into minimakefile

parents 410dabd7 e261d413
No related branches found
No related tags found
No related merge requests found
...@@ -8,7 +8,7 @@ ASDF is the de facto standard build facility for Common Lisp. ...@@ -8,7 +8,7 @@ ASDF is the de facto standard build facility for Common Lisp.
Your Lisp implementation probably contains a copy of ASDF, Your Lisp implementation probably contains a copy of ASDF,
which you can load using `(require "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: make, autoconf, dlopen and libc do for C programs:
it orchestrates the compilation and dependency management, it orchestrates the compilation and dependency management,
handles some of the portability issues, dynamically finds and loads code, handles some of the portability issues, dynamically finds and loads code,
...@@ -25,15 +25,15 @@ will get you started as a simple user. ...@@ -25,15 +25,15 @@ will get you started as a simple user.
If you want to define your own systems, further read the section If you want to define your own systems, further read the section
Defining systems with defsystem. 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 make doc
ASDF 3 now includes an extensive runtime support library: 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. 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: More information and additional links can be found on ASDF's home page at:
<http://common-lisp.net/project/asdf/> <http://common-lisp.net/project/asdf/>
...@@ -62,7 +62,7 @@ or, assuming your implementation provides ASDF 3.1 or later: ...@@ -62,7 +62,7 @@ or, assuming your implementation provides ASDF 3.1 or later:
~/common-lisp/asdf/ ~/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 make
...@@ -98,7 +98,7 @@ choose your most elaborate installed system $S, and try: ...@@ -98,7 +98,7 @@ choose your most elaborate installed system $S, and try:
Debugging tip 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 (asdf:load-system :uiop) ;; loading uiop is simple
(map () 'load ;; loading asdf/defsystem is tricky (map () 'load ;; loading asdf/defsystem is tricky
...@@ -113,7 +113,7 @@ to the call to `asdf::required-components`. ...@@ -113,7 +113,7 @@ to the call to `asdf::required-components`.
What has changed? 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 significant changes in each release, and
the `git log` for a detailed description of each commit. the `git log` for a detailed description of each commit.
...@@ -121,77 +121,78 @@ 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? How do I navigate this source directory?
---------------------------------------- ----------------------------------------
* `asdf.asd` * [asdf.asd](asdf.asd)
* The system definition for building ASDF with ASDF. * The system definition for building ASDF with ASDF.
* `*.lisp` * `*.lisp`
* The source code files for asdf/defsystem. * The source code files for `asdf/defsystem`.
See asdf.asd for the order in which they are loaded. See [asdf.asd](asdf.asd) for the order in which they are loaded.
* `uiop/` * [uiop/](uiop/)
* Utilities of Implementation- and OS- Portability, * 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. and functions all have docstrings.
* `Makefile` * [Makefile](Makefile)
* a minimal Makefile for bootstrapping purposes. * a minimal `Makefile` for bootstrapping purposes.
Most of the logic is in the asdf-tools system 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 system to build, test and release ASDF. It includes:
* `asdf-tools` -- a shell script to run it as a shell command. * [asdf-tools](tools/asdf-tools) -- a shell script to run it as a shell command.
* `load-asdf.lisp` -- how to load ASDF in a self-contained project * [load-asdf.lisp](tools/load-asdf.lisp) -- how to load ASDF in a self-contained project
* `asdf-tools.asd` -- system definition for asdf-tools * [asdf-tools.asd](tools/asdf-tools.asd) -- system definition for asdf-tools
* `*.lisp` -- the source code for asdf-tools * `*.lisp` -- the source code for `asdf-tools`
* also a couple scripts to help ASDF users: * also a couple scripts to help ASDF users:
* `load-asdf.lisp` -- a build script to load, configure and use ASDF * [load-asdf.lisp](tools/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](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](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. * The system definition for building ASDF with XCVB.
It hasn't been tested or maintained for years and has bitrotten. 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: * 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: * documentation for ASDF, including:
* `index.html` -- the web page for <http://common-lisp.net/project/asdf/> * [index.html](doc/index.html) -- the web page for <http://common-lisp.net/project/asdf/>
* `asdf.texinfo` -- our manual * [asdf.texinfo](doc/asdf.texinfo) -- our manual
* `Makefile` -- how to build the manual * [Makefile](doc/Makefile) -- how to build the manual
* `cclan.png` `lisp-logo120x80.png` `style.css` `favicon.ico` * [cclan.png](doc/cclan.png) [lisp-logo120x80.png](doc/lisp-logo120x80.png)
-- auxiliaries of `index.html` [style.css](doc/style.css) [favicon.ico](doc/favicon.ico)
-- auxiliaries of [index.html](doc/index.html)
* `test/`
* [test/](test/)
* regression test scripts (and ancillary files) for developers to check * regression test scripts (and ancillary files) for developers to check
that they don't unintentionally break any of the functionality of ASDF. that they don't unintentionally break any of the functionality of ASDF.
Far from covering all of ASDF. Far from covering all of ASDF.
* `contrib/` * [contrib/](contrib/)
* a few contributed files that show case how to use ASDF. * a few contributed files that show case how to use ASDF.
* `debian/` * [debian/](debian/)
files for packaging on debian, ubuntu, etc. * files for packaging on Debian, Ubuntu, etc.
* `build/` * [build/](build/)
* where the Makefile and asdf-tools store their output files, including * where the `Makefile` and `asdf-tools` store their output files, including
* `asdf.lisp` -- the current one-file deliverable of ASDF * `asdf.lisp` -- the current one-file deliverable of ASDF
* `asdf-XXX.lisp` -- for upgrade test purposes, old versions * `asdf-XXX.lisp` -- for upgrade test purposes, old versions
* `results/` -- logs of tests that have been run * `results/` -- logs of tests that have been run
* `fasls/` -- output files while running tests. * `fasls/` -- output files while running tests.
* `ext/` * [ext/](ext/)
* external dependencies, that can be populated with `make ext` * external dependencies, that can be populated with `make ext`
or equivalently with `git submodule update --init`. or equivalently with `git submodule update --init`.
* `README` * [README.md](README.md)
* this file * this file
* `TODO` * [TODO](TODO)
* plenty of ideas for how to further improve ASDF. * plenty of ideas for how to further improve ASDF.
Last updated Sunday, March 22nd, 2015. Last updated Wednesday, May 6th, 2015.
...@@ -84,7 +84,12 @@ ...@@ -84,7 +84,12 @@
call other programs and parse their output, call other programs and parse their output,
compile Lisp code, muffle conditions, or configure Lisp software. compile Lisp code, muffle conditions, or configure Lisp software.
See its 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>
<p><tt>uiop</tt> is distributed as part of the <tt>ASDF</tt>, <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 its source code is transcluded in the single-file <tt>asdf.lisp</tt> being distributed
...@@ -120,14 +125,15 @@ ...@@ -120,14 +125,15 @@
<a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a> <a href="https://bugs.launchpad.net/asdf/+bug/1230368"><tt>quick-build</tt></a>
(also reimplemented as the ASDF extension (also reimplemented as the ASDF extension
<a href="https://gitlab.common-lisp.net/asdf/asdf-package-system" <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>
<li>Fran&ccedil;ois-Ren&eacute; Rideau's <li>Fran&ccedil;ois-Ren&eacute; Rideau's
<a href="https://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a> <a href="https://common-lisp.net/project/xcvb/"><tt>XCVB</tt></a>
(building object and image files deterministically and in parallel, (building object and image files deterministically and in parallel,
but not actively maintained since 2012; but not actively maintained since 2012;
thanks to its new build model, ASDF 3 could conceivably be modified a hypothetical ASDF 4 could conceivably be evolved to support these features
to support these features). thanks to the groundwork laid by ASDF 3).
</li> </li>
<li>Drew McDermott's <li>Drew McDermott's
<a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a> <a href="http://cs-www.cs.yale.edu/homes/dvm/"><tt>YTools</tt></a>
...@@ -187,16 +193,16 @@ ...@@ -187,16 +193,16 @@
<td align="left"><tt>mcl xcl</tt></td></tr> <td align="left"><tt>mcl xcl</tt></td></tr>
<tr><th align="left">Proprietary</th> <tr><th align="left">Proprietary</th>
<td align="left"><tt>allegro</tt></td> <td align="left"><tt>allegro</tt></td>
<td align="left"><tt>lispworks mocl</tt></td> <td align="left"><tt>lispworks</tt></td>
<td align="left"><tt>cormanlisp genera scl</tt></td></tr> <td align="left"><tt>cormanlisp genera mocl scl</tt></td></tr>
</table> </table>
<p> <p>
To deal with an implementation that doesn't yet provide ASDF 3, 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 we provide <a href="https://common-lisp.net/asdf/asdf/tree/master/tools/install-asdf.lisp">a script</a>
where your implementation goes looking for it that can install ASDF 3 where your implementation goes looking for it
when you <tt>(require "asdf")</tt> . when you <tt>(require "asdf")</tt> .
</p><p> </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) (as do <tt>lispworks mocl xcl</tt> or older versions of some implementations)
or an overly old version of ASDF 3, or an overly old version of ASDF 3,
you can download, install and configure a more recent ASDF 3, you can download, install and configure a more recent ASDF 3,
...@@ -329,7 +335,7 @@ XCL (Peter Graves) <gnooth@gmail.com> ...@@ -329,7 +335,7 @@ XCL (Peter Graves) <gnooth@gmail.com>
to compute the actual dependencies in a big ASDF system.</li> to compute the actual dependencies in a big ASDF system.</li>
<li><a href="https://common-lisp.net/project/qitab/" <li><a href="https://common-lisp.net/project/qitab/"
><tt>poiu</tt></a>, ><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/" <li><a href="https://common-lisp.net/project/asdf-system-connections/"
><tt>asdf-system-connections</tt></a>, ><tt>asdf-system-connections</tt></a>,
lets you specify systems that are automatically loaded when lets you specify systems that are automatically loaded when
...@@ -337,19 +343,10 @@ XCL (Peter Graves) <gnooth@gmail.com> ...@@ -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" <li><a href="http://www.lrde.epita.fr/~didier/software/lisp/misc.php#asdf-flv"
><tt>asdf-flv</tt></a>, ><tt>asdf-flv</tt></a>,
to bind file-local variables around the compilation of some files.</li> 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> </ul>
<p>Former extensions, now superseded, include:</p> <p>Former extensions, now superseded, include:</p>
<ul> <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. so they don't clash between implementations and don't pollute source directories.
It is superseded by <tt>asdf/defsystem</tt>'s builtin It is superseded by <tt>asdf/defsystem</tt>'s builtin
<tt>asdf-output-translations</tt> mechanism; <tt>asdf-output-translations</tt> mechanism;
...@@ -366,16 +363,26 @@ XCL (Peter Graves) <gnooth@gmail.com> ...@@ -366,16 +363,26 @@ XCL (Peter Graves) <gnooth@gmail.com>
a standalone executable program (on supported implementations), a standalone executable program (on supported implementations),
or an image containing your system precompiled. or an image containing your system precompiled.
</li> </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. <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>, It is now superseded by <tt>uiop</tt>, aka <tt>asdf/driver</tt>,
which is part of ASDF, which is part of ASDF,
and exports its functionality and exports its functionality
in its own package <tt>uiop</tt>. in its own package <tt>uiop</tt>.
</li> </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> </ul>
<h3>Contributing</h3> <h3>Contributing</h3>
...@@ -497,9 +504,9 @@ XCL (Peter Graves) <gnooth@gmail.com> ...@@ -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.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://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> <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 &copy; 2001-2014 Daniel Barlow and contributors</span></p> <p><span class="copyright"Copyright &copy; 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> <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> </div>
</body> </body>
</html> </html>
UIOP the Utilities for Implementation- and OS- Portability UIOP, the Utilities for Implementation- and OS- Portability
========================================================== ===========================================================
UIOP is the portability layer of ASDF. UIOP is the portability layer of ASDF.
It provides utilities that abstract over discrepancies between implementations, It provides utilities that abstract over discrepancies between implementations,
...@@ -7,32 +7,35 @@ between operating systems, and between what the standard provides and ...@@ -7,32 +7,35 @@ between operating systems, and between what the standard provides and
what programmers actually need, to write portable Common Lisp programs. 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 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` according to its topic: e.g [pathname.lisp](pathname.lisp)
and contain utilities related to the handling of pathname objects. will define package `UIOP/PATHNAME` and contain utilities related to
All exported symbols are reexported in a convenience package `UIOP`. 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 `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 `symbol-call` and `find-symbol*` that are also useful for use in `.asd` files
before packages have been defined. 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. Big offenders are 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, 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, control-flow, (p)lists, characters, strings, functions, classes, conditions,
"stamps" (real number or boolean for +/- infinity), versions, etc. "stamps" (real number or boolean for +/- infinity), versions, 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`: extracts information from your environment, including * [os](os.lisp): 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`: 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 (and their lovecraftian "logical" variant), offering a vast array of
functions and a sensible, usable abstraction to specify relative pathnames. functions and a sensible, usable abstraction to specify relative pathnames.
It has a function `merge-pathnames*` to use instead of `merge-pathnames`, or 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: ...@@ -40,37 +43,38 @@ The files that constitute UIOP are, in loading order:
of functions for dealing with pathnames being directory vs file, of functions for dealing with pathnames being directory vs file,
physical vs logical, absolute vs relative, and more. 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, 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`: 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 (external formats), element types, safe `read`ing and `write`ing, opening files
or temporary files, providing `format`-like designators for streams, or temporary files, providing `format`-like designators for streams,
flushing output buffers, consuming or copying streams, concatenating streams flushing output buffers, consuming or copying streams, concatenating streams
or files, copying files, etc. 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, 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`: 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. 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, muffles uninteresting conditions, saves and restores deferred warnings,
runs hooks around compilation (to e.g. control optimizations or syntax), runs hooks around compilation (to e.g. control optimizations or syntax),
identifies the pathname of the current file, combines FASLs, etc. identifies the pathname of the current file, combines FASLs, etc.
* `configuration`: helps you define portable configuration files, using best * [configuration](configuration.lisp): portably locate and parse configuration files,
practices to define and validate syntax, search standard paths, using best practices to define and validate syntax, search standard paths,
let users specify pathnames or pathname patterns, etc. let users specify pathnames or pathname patterns, etc.
* `backward-driver`: provides backward-compatibility with earlier incarnations * [backward-driver](backward-driver.lisp): provides backward-compatibility
of this library (i.e. ASDF internals that have leaked, or ASDF-UTILS) 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 Documentation
...@@ -85,15 +89,20 @@ Maybe some automated tool will extract all that information and ...@@ -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. 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. 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: it isn't obvious at all that you can indeed
of the left side panel, you can see many packages and from there the defined symbols: 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, 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 Using UIOP
...@@ -123,11 +132,16 @@ evolved from ASDF 2's internal utilities and portability layer. ...@@ -123,11 +132,16 @@ 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 this 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),
EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER (UIOP's run-program is better), EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER (UIOP's run-program evolved
SLIME's swank-loader (UIOP has better compilation and API identification), 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. 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.
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.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment