Bump version to 3.1.0.116
[projects/asdf/asdf.git] / uiop / README
1 UIOP the Utilities for Implementation- and OS- Portability
2 ==========================================================
3
4 UIOP is the portability layer of ASDF.
5 It provides utilities that abstract over discrepancies between implementations,
6 between operating systems, and between what the standard provides and
7 what programmers actually need, to write portable Common Lisp programs.
8
9 It is organized by topic in many files, each of which defines its own package
10 according to its topic: e.g pathname.lisp will define package UIOP/PATHNAME
11 and contain utilities related to the handling of pathname objects.
12 All exported symbols are reexported in a convenience package UIOP.
13
14 The files that constitute UIOP are, in loading order:
15
16 * package: to deal with packages and their symbols, most notably including
17   DEFINE-PACKAGE, a variant of defpackage capable of hot-upgrade.
18
19 * common-lisp: to let you paper over various sub-standard implementations.
20   Big offenders are Corman, GCL, Genera, MCL, all of them unmaintained.
21   Supported without serious issues are:
22   ABCL, Allegro, CCL, CMUCL, CLISP, ECL, LispWorks, MKCL, SBCL, XCL.
23
24 * utility: to provide macros and functions that do not involve I/O, handling
25   control-flow, (p)lists, characters, strings, functions, classes, conditions,
26   "stamps" (real number or boolean for +/- infinity), versions, etc.
27   It also sports uiop-debug, a useful tool to help you debug programs.
28
29 * os: to extract information from your environment, including
30   an API identifier, unix vs windows, getenv, hostname, getcwd and chdir, etc.
31
32 * pathname: to survive the gruesome non-portability trap that are CL pathnames
33   (and their lovecraftian "logical" variant), offering a vast array of functions
34   and a sensible, usable abstraction to specify relative pathnames.
35
36 * filesystem: to provide portable access to the filesystem, inspecting it,
37   only using truename when desired, using native OS namestrings,
38   atomic file renaming, creating or deleting directories, etc.
39
40 * stream: to portably deal with character encodings (external formats),
41   element types, safe READing and WRITEing, opening files or temporary files,
42   providing FORMAT-like designators for streams, flushing output buffers,
43   consuming or copying streams, concatenating files, copying files, etc.
44
45 * image: to portably deal with images, dumping them, restoring from them,
46   registering hooks to run at suitable events in the image lifetime,
47   printing backtraces, handling fatal conditions, using or avoiding debug modes,
48   accessing command line arguments or quitting the process.
49
50 * run-program: to portably spawn external processes and capture their output.
51   Can also capture error-output, inject input, or let it all be interactive.
52
53 * lisp-build: to portably compile common-lisp code, handle compilation results,
54   muffle uninteresting conditions, save and restore deferred warnings,
55   run hooks around compilation (to e.g. control optimizations or syntax),
56   identify the pathname of the current file, combine FASLs, etc.
57
58 * configuration: to write portable configuration files, using best practices
59   to define and validate syntax, search standard paths,
60   let users specify pathnames or pathname patterns, etc.
61
62 * backward-driver: to provide backward-compatibility with earlier incarnations
63   of this library (i.e. ASDF internals that have leaked, or ASDF-UTILS)
64
65 * driver: to reexport all the above utilities in a single package UIOP.
66
67
68 Documentation
69 -------------
70
71 Each file starts with a package definition form that lists the exported symbols.
72
73 All the exported functions, macros and variables ought to have proper docstrings.
74 If not, then it's a legitimate bug that we invite you to report.
75
76 Maybe some automated tool will extract all that information and
77 make a webpage from it, at which point it would be nice to insert a link here.
78
79 One tool with which you can extract all the documentation is HEΛP.
80 At this time, the interface is not great, but if you use the scrollbar on the right
81 of the left side panel, you can see many packages and from there the defined symbols::
82
83         http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html
84
85 Another automated documentation tool is quickdocs, but unhappily, at the time of this writing,
86 it only extracts information from the first package::
87
88         http://quickdocs.org/uiop/api
89
90
91 Using UIOP
92 ----------
93
94 UIOP is part of ASDF 3, and any modern Common Lisp implementation
95 will have all of UIOP available when you (require "asdf").
96 NB: (require :asdf) also works on all implementations but CLISP.
97
98 If you need some functionality only available in a recent version of UIOP,
99 but cannot or will not upgrade ASDF, UIOP is also distributed separately;
100 see e.g. in Quicklisp. You may then have to load it like any other library::
101         (asdf:load-system :uiop)
102
103 If you want to use UIOP while preserving compatibility with ASDF 2,
104 we recommend that in your ASDF system definition you may use the like of::
105         :depends-on (#-asdf3 :uiop)
106
107
108 Some history
109 ------------
110
111 UIOP, formerly known as ASDF-DRIVER (the package and system nicknames live on),
112 evolved from ASDF 2's internal utilities and portability layer.
113 It has since fully superseded functionality from the following libraries:
114 ASDF-UTILS (UIOP carries on the ASDF 2 utilities that this exported),
115 CL-FAD (UIOP's pathname and filesystem functions are much more portable),
116 CL-LAUNCH (UIOP took its image and command-line argument handling from it),
117 EXTERNAL-PROGRAM, TRIVIAL-SHELL and XCVB-DRIVER (UIOP's run-program is better),
118 SLIME's swank-loader (UIOP has better compilation and API identification),
119 TRIVIAL-BACKTRACE (UIOP/IMAGE has all of it and more), etc.
120
121 UIOP also captures a large subset of the functionality from TRIVIAL-FEATURES,
122 and a small subset of the functionality from ALEXANDRIA or FARE-UTILS.
123