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