README.md 7.23 KB
Newer Older
1 2
UIOP, the Utilities for Implementation- and OS- Portability
===========================================================
3 4 5 6 7 8 9

UIOP is the portability layer of ASDF.
It provides utilities that abstract over discrepancies between implementations,
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
10
according to its topic: e.g `[pathname.lisp](pathname.lisp)`
11 12
will define package `UIOP/PATHNAME` and contain utilities related to
the handling of pathname objects.
13 14 15
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.
16

17
The files that constitute UIOP are, in dependency loading order:
18

19
* `[package](package.lisp)`: deals with packages and their symbols, most notably including
20 21 22 23
  `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.

24
* `[common-lisp](common-lisp.lisp)`: lets you paper over various sub-standard implementations.
25
  Big offenders are Corman, GCL, Genera, MCL, all of them unmaintained.
26
  Supported without serious issues are:
27
  ABCL, Allegro, CCL, CMUCL, CLASP, CLISP, ECL, LispWorks, MKCL, SBCL, SCL, XCL.
28

29
* `[utility](utility.lisp)`: provides macros and functions that do not involve I/O; it handles
30 31 32
  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.
33

34
* `[os](os.lisp)`: extracts information from your environment, including
35
  an ABI identifier, features that distinguish Unix vs Windows,
36
  `getenv`, `hostname`, `getcwd` and `chdir`, etc.
37

38
* `[pathname](pathname.lisp)`: overcomes the gruesome non-portability trap that are CL pathnames
39 40 41 42 43 44
  (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.
45

46
* `[filesystem](filesystem.lisp)`: provides portable access to the filesystem, inspecting it,
47
  only using truename when desired, using native OS namestrings,
48 49
  atomic file renaming, creating or deleting directories, etc.

50
* `[stream](stream.lisp)`: portably deals with `*stderr*` vs `*error-output*`, character encodings
51 52 53 54
  (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.
55

56
* `[image](image.lisp)`: portably deals with images, dumping them, restoring from them,
57
  registering hooks to run at suitable events in the image lifetime,
58 59 60
  printing backtraces, handling fatal conditions, using or avoiding debug modes,
  accessing command line arguments or quitting the process.

61
* `[run-program](program.lisp)`: portably spawns external processes and captures their output.
62
  Can also capture error-output, inject input, or let it all be interactive.
63

64
* `[lisp-build](lisp-build.lisp)`: portably compiles Common Lisp code, handles compilation results,
65 66 67
  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.
68

69
* `[configuration](configuration.lisp)`: portably locate and parse configuration files,
70
  using best practices to define and validate syntax, search standard paths,
71
  let users specify pathnames or pathname patterns, etc.
72

73
* `[backward-driver](backward-driver.lisp)`: provides backward-compatibility
74 75
  with earlier incarnations of this library
  (i.e. ASDF internals that have leaked, ASDF-UTILS, or older versions of UIOP).
76

77
* `[driver](driver.lisp)`: reexports all the above utilities in a single package `UIOP`.
78 79 80 81 82 83 84 85 86 87 88 89


Documentation
-------------

Each file starts with a package definition form that lists the exported symbols.

All the exported functions, macros and variables ought to have proper docstrings.
If not, then it's a legitimate bug that we invite you to report.

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.
90 91

One tool with which you can extract all the documentation is HEΛP.
92 93 94
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:
95

96
* [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)
97 98

Another automated documentation tool is quickdocs, but unhappily, at the time of this writing,
99 100
it only extracts information from the first package
(see [bug #24](https://github.com/fukamachi/quickdocs/issues/24)):
101

102
* [http://quickdocs.org/uiop/api](http://quickdocs.org/uiop/api)
103

104

105
Help wanted extracting working documentation from UIOP's docstrings.
106

107 108 109 110 111

Using UIOP
----------

UIOP is part of ASDF 3, and any modern Common Lisp implementation
112 113
will have all of UIOP available when you `(require "asdf")`.
NB: `(require :asdf)` also works on all implementations but CLISP.
114 115 116

If you need some functionality only available in a recent version of UIOP,
but cannot or will not upgrade ASDF, UIOP is also distributed separately;
117 118
see e.g. in Quicklisp. You may then have to load it like any other library:

119 120 121
	(asdf:load-system :uiop)

If you want to use UIOP while preserving compatibility with ASDF 2,
122 123
we recommend that in your ASDF system definition you may use the like of:

124 125 126 127 128 129 130 131 132
	:depends-on (#-asdf3 :uiop)


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:
133 134
ASDF-UTILS (UIOP carries on the ASDF 2 utilities that this exported),
CL-FAD (UIOP's pathname and filesystem functions are much more portable),
135 136 137 138
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),
139
TRIVIAL-BACKTRACE (UIOP/IMAGE has all of it and more), etc.
140 141

UIOP also captures a large subset of the functionality from TRIVIAL-FEATURES,
142
and a small subset of the functionality from ALEXANDRIA or FARE-UTILS.
143

144 145 146
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.