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 | |
58 | \& | |
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 | |
106 | .BR "\-R" ", " "\-\-remove-other" | |
107 | After processing the selected Lisp implementations, | |
108 | delete all of the image files corresponding to other Lisps | |
109 | defined in the configuration. | |
110 | Negate with | |
111 | .B +R | |
112 | or | |
113 | .BR \-\-no-remove-other . | |
114 | . | |
115 | .TP | |
116 | .BR "\-U" ", " "\-\-remove-unknown" | |
117 | After processing the selected Lisp implementations, | |
118 | delete all of the files in the image directory which | |
119 | .I aren't | |
120 | image files of a configured Lisp implementation. | |
121 | Negate with | |
122 | .B +U | |
123 | or | |
124 | .BR \-\-no-remove-unknown . | |
125 | . | |
126 | .TP | |
127 | .BI "\-O" "\fR, " "\-\-output=" output | |
128 | If | |
129 | .I output | |
130 | names a directory, | |
131 | then write images to that directory | |
132 | with their default names as specified in the configuration file. | |
133 | Otherwise, | |
134 | exactly one Lisp implementation must be explicitly named, | |
135 | the | |
136 | .RB ` \-R ' | |
137 | and | |
138 | .RB `\-U ' | |
139 | options must not be set, | |
140 | and | |
141 | the image is written to a file named | |
142 | .IR output . | |
143 | By default, | |
144 | images are written to the directory in which | |
145 | .BR runlisp (1) | |
146 | will look in when checking for custom images: | |
147 | run | |
148 | .B query-runlisp-config -x@image-dir | |
149 | to see the default setting. | |
150 | . | |
151 | .TP | |
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. | |
173 | All of the files are expected to as described in | |
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 | |
221 | .BR "\-n" ", " "-\-dry-run" | |
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 | |
233 | .BR "\-q" ", " "\-\-quiet" | |
234 | Don't print warning messages. | |
235 | This option may be repeated: | |
236 | each use reduces verbosity by one step, | |
237 | counteracting one | |
238 | .RB ` \-v ' | |
239 | option. | |
240 | The default verbosity level is 1, | |
241 | which prints only warning measages. | |
242 | . | |
243 | .TP | |
244 | .BR "\-r" ", " "\-\-remove-image" | |
245 | Delete image files for the selected Lisp implementations, | |
246 | rather than dumping them. | |
247 | Negate with | |
248 | .B +r | |
249 | or | |
250 | .BR \-\-no-remove-image . | |
251 | . | |
252 | .TP | |
253 | .BR "\-v" ", " "\-\-verbose" | |
254 | Be more verbose about the process of creating images. | |
255 | Lisp implementations can be rather noisy: | |
256 | by default, | |
257 | .B dump-runlisp-image | |
258 | runs silently unless something goes wrong, | |
259 | in which case it prints the failed Lisp command line | |
260 | and its output. | |
261 | If you set | |
262 | .B \-v | |
263 | then | |
264 | .B dump-runlisp-image | |
265 | will show Lisp implementation's noise immediately, | |
266 | without waiting to see whether it succeeds or fails. | |
267 | . | |
268 | .SS "Operation" | |
269 | The | |
270 | .B dump-runlisp-image | |
271 | program first determines a collection of | |
272 | .I selected | |
273 | Lisp implementations. | |
274 | If the | |
275 | .RB ` \-a ' | |
276 | option is not set, | |
277 | then the selected Lisps are those named on the command line. | |
278 | If | |
279 | .RB ` \-a ' | |
280 | is set, | |
281 | and the configuration contains a setting for | |
282 | .B dump | |
283 | in the | |
284 | .B @CONFIG | |
285 | section, | |
286 | then its (expanded) value is taken to be | |
287 | a list of Lisp implementation names | |
288 | separated by commas and/or one or more whitespace characters, | |
289 | and these named Lisp implementations are selected; | |
290 | if there is no | |
291 | .B dump | |
292 | setting, then | |
293 | .I all | |
294 | configured Lisp implementations which claim support for custom images | |
295 | \(en i.e., configuration sections with settings for | |
296 | .B run-script | |
297 | and | |
298 | .B image-file | |
299 | \(en are selected, and the | |
300 | .RB ` \-i ' | |
301 | option is forced on. | |
302 | If the | |
303 | .RB ` \-i ' | |
304 | option is set, | |
305 | then only those Lisp implementations which are actually installed | |
306 | are selected. | |
307 | .PP | |
308 | Having established the selected Lisps, | |
309 | .B dump-runlisp-image | |
310 | proceeds to act on them: | |
311 | in the absence of the | |
312 | .RB ` \-r ' | |
313 | option, | |
314 | it attempts to dump a custom image | |
315 | for each selected Lisp implementation, | |
316 | unless an image file already exists | |
317 | or the | |
318 | .RB ` \-f ' | |
319 | option is set. | |
320 | (Note that | |
321 | .RB ` \-f ' | |
322 | is an optimization of image dumping, | |
323 | and does not affect selection.) | |
324 | On the other hand, if | |
325 | .RB ` \-r ' | |
326 | is set, | |
327 | then the custom image files of the selected Lisp implementations | |
328 | are deleted. | |
329 | .PP | |
330 | Next, if the | |
331 | .RB ` \-R ' | |
332 | option is set, | |
333 | then all the images for Lisp implementations | |
334 | which are defined in the configuration | |
335 | but were | |
336 | .I not | |
337 | selected | |
338 | are deleted. | |
339 | .PP | |
340 | Finally, if the | |
341 | .RB ` \-U ' | |
342 | option is set, | |
343 | then all files in the image directory | |
344 | which aren't recognized as being | |
345 | the custom image of some Lisp implementation | |
346 | are deleted. | |
347 | .PP | |
348 | If all of these operations are successfully performed | |
349 | then | |
350 | .B dump-runlisp-image | |
351 | exits with status 0; | |
352 | if there was a problem with the command line, | |
353 | or if any jobs fail, | |
354 | then it exits with status 127. | |
355 | . | |
356 | .\"-------------------------------------------------------------------------- | |
357 | . | |
358 | .SH SEE ALSO | |
359 | .BR query-runlisp-config (1), | |
360 | .BR runlisp (1), | |
361 | .BR runlisp.conf (5). | |
362 | . | |
363 | .SH AUTHOR | |
364 | Mark Wooding, <mdw@distorted.org.uk> | |
365 | . | |
366 | .\"----- That's all, folks -------------------------------------------------- |