Commit | Line | Data |
---|---|---|
10427eb2 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 | .. | |
eea3b0c7 | 42 | .ds .. \&.\|.\|. |
10427eb2 MW |
43 | . |
44 | .\"-------------------------------------------------------------------------- | |
45 | .TH dump-runlisp-image 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 [ \-RUafinqrv ] | |
54 | .RB [ +RUfinr ] | |
55 | .RB [ \-O | |
56 | .IR output ] | |
57 | .br | |
8ed4c352 | 58 | \c |
10427eb2 MW |
59 | .RB [ \-c |
60 | .IR conf ] | |
61 | .RB [ \-o | |
62 | .RI [ sect \c | |
63 | .BR : ] \c | |
64 | .IB var = \c | |
65 | .IR value ] | |
66 | .RB [ \-j | |
67 | .IR njobs ] | |
68 | .RI [ lisp | |
eea3b0c7 | 69 | \*(..] |
10427eb2 MW |
70 | . |
71 | .\"-------------------------------------------------------------------------- | |
72 | .SH DESCRIPTION | |
73 | . | |
74 | The | |
75 | .B dump-runlisp-image | |
c7af83cd | 76 | program builds and manages custom images for use by |
10427eb2 MW |
77 | .BR runlisp (1). |
78 | For many Lisp implementation, | |
79 | a custom image, | |
80 | with ASDF already loaded, | |
81 | can start scripts much more quickly | |
82 | than the `vanilla' images installed by default. | |
83 | The downside is that custom images may be rather large. | |
c7af83cd MW |
84 | .PP |
85 | There are actually | |
86 | .I two | |
87 | filenames for each Lisp image: | |
88 | the well-known one that | |
89 | .BR runlisp (1) | |
90 | uses to run scripts is a symbolic link to the other, | |
91 | the actual image file, | |
92 | whose name contains an ugly hexadecimal lump | |
93 | which identifies the versions of the Lisp code dumped in the image file. | |
94 | The | |
95 | .B dump-runlisp-image | |
96 | program uses this hash to determine whether | |
97 | the current image is up-to-date or needs replacing. | |
10427eb2 MW |
98 | . |
99 | .SS "Options" | |
100 | The following options are accepted on the command line. | |
101 | . | |
102 | .TP | |
103 | .BR "\-h" ", " "\-\-help" | |
104 | Write a synopsis of | |
105 | .BR dump-runlisp-image 's | |
106 | command-line syntax | |
107 | and a description of the command-line options | |
108 | to standard output | |
109 | and immediately exit with status 0. | |
110 | . | |
111 | .TP | |
112 | .BR "\-V" ", " "\-\-version" | |
113 | Write | |
114 | .BR dump-runlisp-image 's | |
115 | version number | |
116 | to standard output | |
117 | and immediately exit with status 0. | |
118 | . | |
119 | .TP | |
10427eb2 MW |
120 | .BI "\-O" "\fR, " "\-\-output=" output |
121 | If | |
122 | .I output | |
123 | names a directory, | |
124 | then write images to that directory | |
125 | with their default names as specified in the configuration file. | |
126 | Otherwise, | |
127 | exactly one Lisp implementation must be explicitly named, | |
128 | the | |
129 | .RB ` \-R ' | |
130 | and | |
131 | .RB `\-U ' | |
132 | options must not be set, | |
133 | and | |
134 | the image is written to a file named | |
135 | .IR output . | |
136 | By default, | |
137 | images are written to the directory in which | |
138 | .BR runlisp (1) | |
139 | will look in when checking for custom images: | |
140 | run | |
bf52b6ca | 141 | .B query-runlisp-config \-x@image-dir |
10427eb2 MW |
142 | to see the default setting. |
143 | . | |
144 | .TP | |
c88b892c MW |
145 | .BR "\-R" ", " "\-\-remove-other" |
146 | After processing the selected Lisp implementations, | |
147 | delete all of the image files corresponding to other Lisps | |
148 | defined in the configuration. | |
149 | Negate with | |
150 | .B +R | |
151 | or | |
152 | .BR \-\-no-remove-other . | |
153 | . | |
154 | .TP | |
155 | .BR "\-U" ", " "\-\-remove-unknown" | |
156 | After processing the selected Lisp implementations, | |
157 | delete all of the files in the image directory which | |
158 | .I aren't | |
159 | image files of a configured Lisp implementation. | |
160 | Negate with | |
161 | .B +U | |
162 | or | |
163 | .BR \-\-no-remove-unknown . | |
164 | . | |
165 | .TP | |
10427eb2 MW |
166 | .BR "\-a" ", " "\-\-all-configured" |
167 | Select all configured Lisp implementations. | |
168 | You must either list Lisp implementations explicitly on the command line | |
169 | or set the | |
170 | .RB ` \- a' | |
171 | option, | |
172 | but not both. | |
173 | . | |
174 | .TP | |
175 | .BI "\-c" "\fR, " "\-\-config-file=" conf | |
176 | Read configuration from | |
177 | .IR conf . | |
178 | If | |
179 | .I conf | |
180 | is a directory, then all of the files within | |
181 | whose names end with | |
182 | .RB ` .conf ', | |
183 | are loaded, in ascending lexicographical order; | |
184 | otherwise, | |
185 | .I conf | |
186 | is opened as a file. | |
af677646 | 187 | All of the files are expected to be as described in |
10427eb2 MW |
188 | .BR runlisp.conf (5). |
189 | . | |
190 | .TP | |
191 | .BR "\-f" ", " "\-\-force" | |
192 | Create fresh Lisp images | |
193 | even if a file with the appropriate name | |
194 | already exists. | |
195 | Negate with | |
196 | .B +f | |
197 | or | |
198 | .BR \-\-no-force . | |
199 | . | |
200 | .TP | |
201 | .BR "\-i" ", " "\-\-check-installed" | |
202 | Only select those Lisp implementations | |
203 | which are actually installed | |
204 | (and can be found). | |
205 | To count as `installed', | |
206 | the program named by | |
207 | .B command | |
208 | must exist and be executable in one of the directories listed in the | |
209 | .B PATH | |
210 | environment variable, | |
211 | as must the command named in the first word of the | |
212 | .B dump-image | |
213 | command line. | |
214 | Note that a Lisp implementation which fails this check | |
215 | is not counted as `selected' for the purposes of the | |
216 | .RB ` \-R ' | |
217 | option above. | |
218 | For example, the command | |
219 | .B "dump-runlisp-image \-Rai" | |
220 | will dump images for Lisps which have been installed since the last run, | |
221 | and delete images for Lisps which have been uninstalled since then. | |
222 | Negate with | |
223 | .B +i | |
224 | or | |
225 | .BR \-\-no-check-installed . | |
226 | . | |
227 | .TP | |
228 | .BI "\-j" "\fR, " "\-\-jobs=" njobs | |
229 | Dump image for up to | |
230 | .I njobs | |
231 | Lisp implementations in parallel. | |
232 | The default is to run the jobs sequentially. | |
233 | . | |
234 | .TP | |
bf52b6ca | 235 | .BR "\-n" ", " "\-\-dry-run" |
10427eb2 MW |
236 | Don't actually run any commands to dump images. |
237 | This may be helpful for the curious, | |
238 | in conjunction with | |
239 | .RB ` \-v ' | |
240 | to increase the verbosity. | |
241 | Negate with | |
242 | .B +n | |
243 | or | |
244 | .BR "\-\-no-dry-run" . | |
245 | . | |
246 | .TP | |
497e5a4a MW |
247 | .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect "\fR]\fB:" var = value |
248 | Assign | |
249 | .I value | |
250 | to the variable | |
251 | .I var | |
252 | in configuration section | |
253 | .IR sect , | |
254 | or | |
255 | .B @CONFIG | |
256 | if no section is specified. | |
257 | The value is unexpandable, | |
258 | and overrides any similarly named setting | |
259 | from the configuration file(s). | |
260 | . | |
261 | .TP | |
10427eb2 MW |
262 | .BR "\-q" ", " "\-\-quiet" |
263 | Don't print warning messages. | |
264 | This option may be repeated: | |
265 | each use reduces verbosity by one step, | |
266 | counteracting one | |
267 | .RB ` \-v ' | |
268 | option. | |
269 | The default verbosity level is 1, | |
270 | which prints only warning measages. | |
271 | . | |
272 | .TP | |
273 | .BR "\-r" ", " "\-\-remove-image" | |
274 | Delete image files for the selected Lisp implementations, | |
275 | rather than dumping them. | |
276 | Negate with | |
277 | .B +r | |
278 | or | |
279 | .BR \-\-no-remove-image . | |
280 | . | |
281 | .TP | |
282 | .BR "\-v" ", " "\-\-verbose" | |
283 | Be more verbose about the process of creating images. | |
284 | Lisp implementations can be rather noisy: | |
285 | by default, | |
286 | .B dump-runlisp-image | |
287 | runs silently unless something goes wrong, | |
288 | in which case it prints the failed Lisp command line | |
289 | and its output. | |
290 | If you set | |
291 | .B \-v | |
292 | then | |
293 | .B dump-runlisp-image | |
294 | will show Lisp implementation's noise immediately, | |
295 | without waiting to see whether it succeeds or fails. | |
296 | . | |
297 | .SS "Operation" | |
298 | The | |
299 | .B dump-runlisp-image | |
300 | program first determines a collection of | |
301 | .I selected | |
302 | Lisp implementations. | |
303 | If the | |
304 | .RB ` \-a ' | |
305 | option is not set, | |
306 | then the selected Lisps are those named on the command line. | |
307 | If | |
308 | .RB ` \-a ' | |
309 | is set, | |
310 | and the configuration contains a setting for | |
311 | .B dump | |
312 | in the | |
313 | .B @CONFIG | |
314 | section, | |
315 | then its (expanded) value is taken to be | |
316 | a list of Lisp implementation names | |
317 | separated by commas and/or one or more whitespace characters, | |
318 | and these named Lisp implementations are selected; | |
319 | if there is no | |
320 | .B dump | |
321 | setting, then | |
322 | .I all | |
323 | configured Lisp implementations which claim support for custom images | |
324 | \(en i.e., configuration sections with settings for | |
325 | .B run-script | |
326 | and | |
327 | .B image-file | |
328 | \(en are selected, and the | |
329 | .RB ` \-i ' | |
330 | option is forced on. | |
331 | If the | |
332 | .RB ` \-i ' | |
333 | option is set, | |
334 | then only those Lisp implementations which are actually installed | |
335 | are selected. | |
336 | .PP | |
c7af83cd MW |
337 | If necessary |
338 | (see below), | |
339 | .B dump-runlisp-image | |
340 | invokes each selected Lisp in order to determine a | |
341 | .IR "version hash" . | |
342 | For each selected Lisp system, | |
343 | it constructs a command line, | |
344 | in the manner of | |
345 | .BR runlisp (1), | |
346 | to evaluate the expression resulting from expanding the | |
347 | .B lisp-version | |
348 | setting in the Lisp system's configuration section. | |
349 | It hashes the result, | |
350 | using a collision-resistant hash function | |
351 | (currently SHA256), | |
352 | to produce a string of hexadecimal digits which represents | |
353 | the versions of the various pieces of Lisp code which | |
354 | .I should | |
355 | be in the dumped image. | |
356 | The standard setting for | |
357 | .B lisp-version | |
358 | includes the Lisp implementation version string | |
359 | and the version of ASDF currently installed. | |
360 | (This step is skipped | |
361 | if it's not necessary to determine the Lisp system versions. | |
362 | In practice, this happens when the | |
363 | .RB ` \-r ', | |
364 | .RB ` \-R ' | |
365 | and | |
366 | .RB ` \-U ' | |
367 | options are all set.) | |
368 | .PP | |
10427eb2 | 369 | Having established the selected Lisps, |
c7af83cd | 370 | and their version hashes, |
10427eb2 MW |
371 | .B dump-runlisp-image |
372 | proceeds to act on them: | |
373 | in the absence of the | |
374 | .RB ` \-r ' | |
375 | option, | |
376 | it attempts to dump a custom image | |
377 | for each selected Lisp implementation, | |
378 | unless an image file already exists | |
379 | or the | |
380 | .RB ` \-f ' | |
381 | option is set. | |
382 | (Note that | |
383 | .RB ` \-f ' | |
384 | is an optimization of image dumping, | |
385 | and does not affect selection.) | |
386 | On the other hand, if | |
387 | .RB ` \-r ' | |
388 | is set, | |
389 | then the custom image files of the selected Lisp implementations | |
390 | are deleted. | |
391 | .PP | |
392 | Next, if the | |
393 | .RB ` \-R ' | |
394 | option is set, | |
395 | then all the images for Lisp implementations | |
396 | which are defined in the configuration | |
397 | but were | |
398 | .I not | |
399 | selected | |
400 | are deleted. | |
401 | .PP | |
402 | Finally, if the | |
403 | .RB ` \-U ' | |
404 | option is set, | |
405 | then all files in the image directory | |
406 | which aren't recognized as being | |
407 | the custom image of some Lisp implementation | |
408 | are deleted. | |
409 | .PP | |
410 | If all of these operations are successfully performed | |
411 | then | |
412 | .B dump-runlisp-image | |
413 | exits with status 0; | |
414 | if there was a problem with the command line, | |
415 | or if any jobs fail, | |
416 | then it exits with status 127. | |
417 | . | |
418 | .\"-------------------------------------------------------------------------- | |
419 | . | |
420 | .SH SEE ALSO | |
421 | .BR query-runlisp-config (1), | |
422 | .BR runlisp (1), | |
423 | .BR runlisp.conf (5). | |
424 | . | |
425 | .SH AUTHOR | |
426 | Mark Wooding, <mdw@distorted.org.uk> | |
427 | . | |
428 | .\"----- That's all, folks -------------------------------------------------- |