Commit | Line | Data |
---|---|---|
e29834b8 MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" Manual for `dump-runlisp-image' | |
4 | .\" | |
5 | .\" (c) 2020 Mark Wooding | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts. | |
11 | .\" | |
12 | .\" Runlisp is free software: you can redistribute it and/or modify it | |
13 | .\" under the terms of the GNU General Public License as published by the | |
14 | .\" Free Software Foundation; either version 3 of the License, or (at your | |
15 | .\" option) any later version. | |
16 | .\" | |
17 | .\" Runlisp is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
20 | .\" for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU General Public License | |
23 | .\" along with Runlisp. If not, see <https://www.gnu.org/licenses/>. | |
24 | . | |
25 | .ie t \{\ | |
26 | . ds o \(bu | |
27 | . if \n(.g \{\ | |
28 | . fam P | |
29 | . ev an-1 | |
30 | . fam P | |
31 | . ev | |
32 | . \} | |
33 | .\} | |
34 | .el \{\ | |
35 | . ds o o | |
36 | .\} | |
37 | . | |
38 | .de hP | |
39 | .IP | |
40 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
41 | .. | |
42 | .ds , \h'.16667m' | |
43 | . | |
44 | .\"-------------------------------------------------------------------------- | |
45 | .TH runlisp 1 "12 August 2020" "Mark Wooding" | |
46 | .SH NAME | |
47 | dump-runlisp-image \- dump Lisp images for faster script execution | |
48 | . | |
49 | .\"-------------------------------------------------------------------------- | |
50 | .SH SYNOPSIS | |
51 | . | |
52 | .B dump-runlisp-image | |
53 | .RB [ \-acluv ] | |
54 | .RB [ \-o | |
55 | .IR output ] | |
56 | .RI [ lisp | |
57 | \&...] | |
58 | . | |
59 | .\"-------------------------------------------------------------------------- | |
60 | .SH DESCRIPTION | |
61 | . | |
62 | The | |
63 | .B dump-runlisp-image | |
64 | program builds custom images for use by | |
65 | .BR runlisp (1). | |
66 | For many Lisp implementation, | |
67 | a custom image, | |
68 | with ASDF already loaded, | |
69 | can start scripts much more quickly | |
70 | than the `vanilla' images installed by deafult. | |
71 | The downside is that custom images may be rather large. | |
72 | . | |
73 | .SS "Supperted Common Lisp implementations" | |
74 | The following Lisp implementations are currently supported. | |
75 | .TP | |
76 | .B "ccl" | |
77 | Clozure Common Lisp. | |
78 | The default image name is | |
79 | .BR ccl+asdf.image ; | |
80 | a typical image can be 20\(en30\*,MB in size. | |
81 | .TP | |
82 | .B "clisp" | |
83 | GNU CLisp. | |
84 | The default image name is | |
85 | .BR clisp+asdf.mem ; | |
86 | a typical image is about 10\*,MB in size. | |
87 | .TP | |
88 | .B "cmucl" | |
89 | Carnegie\(enMellon University Common Lisp. | |
90 | The default image name is | |
91 | .BR cmucl+asdf.core ; | |
92 | a typical image is about 35\*,MB in size. | |
93 | .TP | |
94 | .B "ecl" | |
95 | Embeddable Common Lisp. | |
96 | The default image name is | |
97 | .BR ecl+asdf ; | |
98 | images comparatively very small | |
99 | \(en about 4\*,MB \(en | |
100 | but, sadly, not very effective. | |
101 | .TP | |
102 | .B "sbcl" | |
103 | Steel Bank Common Lisp. | |
104 | The default image name is | |
105 | .BR sbcl+asdf.core ; | |
106 | a typical image is nearly 45\*,MB in size. | |
107 | .PP | |
108 | (Although | |
109 | .BR runlisp (3) | |
110 | also supports Armed Bear Common Lisp, | |
111 | .B dump-runlisp-image | |
112 | currently doesn't.) | |
113 | . | |
114 | .SS "Options" | |
115 | The following options are accepted on the command line. | |
116 | . | |
117 | .TP | |
118 | .B "\-h" | |
119 | Write a synopsis of | |
120 | .BR dump-runlisp-image 's | |
121 | command-line syntax | |
122 | and a description of the command-line options | |
123 | to standard output | |
124 | and immediately exit with status 0. | |
125 | . | |
126 | .TP | |
127 | .B "\-v" | |
128 | Write | |
129 | .BR dump-runlisp-image 's | |
130 | version number | |
131 | to standard output | |
132 | and immediately exit with status 0. | |
133 | . | |
134 | .TP | |
135 | .B "\-a" | |
136 | Dump images for all Lisp supported implementations | |
137 | which are installed . | |
138 | This implies | |
139 | .BR \-c , | |
140 | described below. | |
141 | You can't set | |
142 | .B \-a | |
143 | and also list implementations explicitly on the command line. | |
144 | . | |
145 | .TP | |
146 | .B "\-c" | |
147 | Only dump images for Lisp implementations | |
148 | which are actually installed | |
149 | (and can be found). | |
150 | . | |
151 | .TP | |
152 | .B "\-l" | |
153 | List the supported implementations | |
154 | and the names of the image files for each | |
155 | to standard output, | |
156 | and immediately exit with status 0. | |
157 | . | |
158 | .TP | |
159 | .BI "\-o " output | |
160 | If | |
161 | .I output | |
162 | names a directory, | |
163 | then write images to that directory | |
164 | with their default names | |
165 | (as listed above). | |
166 | Otherwise, | |
167 | exactly one Lisp implementation may be named, and | |
168 | the image is written to a file named | |
169 | .IR output . | |
170 | By default, | |
171 | images are written to the directory which | |
172 | .BR runlisp (1) | |
173 | will look in when checking for custom images | |
174 | (shown in | |
175 | .B "runlisp \-\-help" | |
176 | or | |
177 | .BR "dump-runlisp-image \-h" ), | |
178 | unless overridden by the | |
179 | .B RUNLISP_IMAGEDIR | |
180 | environment variable. | |
181 | . | |
182 | .TP | |
183 | .BI "\-u" | |
184 | Don't create Lisp images | |
185 | if a file with the appropriate name | |
186 | already exists. | |
187 | . | |
188 | .TP | |
189 | .BI "\-v" | |
190 | Be more verbose about the process of creating images. | |
191 | Lisp implementations can be rather noisy: | |
192 | by default, | |
193 | .B dump-runlisp-image | |
194 | runs silently unless something goes wrong, | |
195 | in which case it prints the failed Lisp command line | |
196 | and its output. | |
197 | If you set | |
198 | .B \-v | |
199 | then | |
200 | .B dump-runlisp-image | |
201 | will show Lisp implementation's noise immediately, | |
202 | without waiting to see whether it succeeds or fails. | |
203 | .PP | |
204 | The | |
205 | .B dump-runlisp-image | |
206 | program will dump an image for each of the named | |
207 | .I lisp | |
208 | implementations in turn, | |
209 | or all Lisp implementations, if | |
210 | .B \-a | |
211 | is set. | |
212 | .PP | |
213 | This involves invoking the Lisp implementations. | |
214 | The | |
215 | .B dump-runlisp-image | |
216 | program expects, by default, | |
217 | to be able to run a Lisp system | |
218 | as a program with the same name, | |
219 | found by searching as directed by the | |
220 | .B PATH | |
221 | environment variable. | |
222 | This can be overridden by setting an environment variable, | |
223 | with the same name but in | |
224 | .IR "upper case" , | |
225 | to the actual name \(en | |
226 | either a bare filename to be searched for on the | |
227 | .BR PATH , | |
228 | or a pathname containing a | |
229 | .RB ` / ', | |
230 | relative to the working directory or absolute, | |
231 | to the program. | |
232 | Note that the entire variable value is used as the program name: | |
233 | it's not possible to provide custom arguments to a Lisp system | |
234 | using this mechanism. | |
235 | If you want to do that, | |
236 | you must write a shell script to do the necessary work, | |
237 | and point the environment variable | |
238 | (or the | |
239 | .BR PATH ) | |
240 | at your script. | |
241 | (This is the same convention as | |
242 | .BR runlisp (1).) | |
243 | .PP | |
244 | If | |
245 | .B \-a | |
246 | or | |
247 | .B \-c | |
248 | is set, | |
249 | then | |
250 | .B dump-runlisp-image | |
251 | will skip Lisp implementations | |
252 | which can't actually be found | |
253 | (by searching the | |
254 | .B PATH | |
255 | for its command name). | |
256 | . | |
257 | .\"-------------------------------------------------------------------------- | |
258 | . | |
259 | .SH "BUGS" | |
260 | .hP \*o | |
261 | There's no support for making images for ABCL. | |
262 | I don't really know what this would look like, | |
263 | but I suspect it wouldn't help very much. | |
264 | ABCL is terribly slow to start up anyway. | |
265 | . | |
266 | .SH "SEE ALSO" | |
267 | .BR runlisp (1). | |
268 | . | |
269 | .SH "AUTHOR" | |
270 | Mark Wooding, <mdw@distorted.org.uk> | |
271 | . | |
272 | .\"----- That's all, folks -------------------------------------------------- |