3 .\" Manual for `dump-runlisp-image'
5 .\" (c) 2020 Mark Wooding
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
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.
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
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/>.
40 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
44 .\"--------------------------------------------------------------------------
45 .TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"
47 dump-runlisp-image \- dump Lisp images for faster script execution
49 .\"--------------------------------------------------------------------------
71 .\"--------------------------------------------------------------------------
76 program builds and manages custom images for use by
78 For many Lisp implementation,
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.
87 filenames for each Lisp image:
88 the well-known one that
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.
96 program uses this hash to determine whether
97 the current image is up-to-date or needs replacing.
100 The following options are accepted on the command line.
103 .BR "\-h" ", " "\-\-help"
105 .BR dump-runlisp-image 's
107 and a description of the command-line options
109 and immediately exit with status 0.
112 .BR "\-V" ", " "\-\-version"
114 .BR dump-runlisp-image 's
117 and immediately exit with status 0.
120 .BI "\-O" "\fR, " "\-\-output=" output
124 then write images to that directory
125 with their default names as specified in the configuration file.
127 exactly one Lisp implementation must be explicitly named,
132 options must not be set,
134 the image is written to a file named
137 images are written to the directory in which
139 will look in when checking for custom images:
141 .B query-runlisp-config \-x@image-dir
142 to see the default setting.
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.
152 .BR \-\-no-remove-other .
155 .BR "\-U" ", " "\-\-remove-unknown"
156 After processing the selected Lisp implementations,
157 delete all of the files in the image directory which
159 image files of a configured Lisp implementation.
163 .BR \-\-no-remove-unknown .
166 .BR "\-a" ", " "\-\-all-configured"
167 Select all configured Lisp implementations.
168 You must either list Lisp implementations explicitly on the command line
175 .BI "\-c" "\fR, " "\-\-config-file=" conf
176 Read configuration from
180 is a directory, then all of the files within
183 are loaded, in ascending lexicographical order;
187 All of the files are expected to be as described in
188 .BR runlisp.conf (5).
191 .BR "\-f" ", " "\-\-force"
192 Create fresh Lisp images
193 even if a file with the appropriate name
201 .BR "\-i" ", " "\-\-check-installed"
202 Only select those Lisp implementations
203 which are actually installed
205 To count as `installed',
208 must exist and be executable in one of the directories listed in the
210 environment variable,
211 as must the command named in the first word of the
214 Note that a Lisp implementation which fails this check
215 is not counted as `selected' for the purposes of the
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.
225 .BR \-\-no-check-installed .
228 .BI "\-j" "\fR, " "\-\-jobs=" njobs
231 Lisp implementations in parallel.
232 The default is to run the jobs sequentially.
235 .BR "\-n" ", " "\-\-dry-run"
236 Don't actually run any commands to dump images.
237 This may be helpful for the curious,
240 to increase the verbosity.
244 .BR "\-\-no-dry-run" .
247 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect "\fR]\fB:" var = value
252 in configuration section
256 if no section is specified.
257 The value is unexpandable,
258 and overrides any similarly named setting
259 from the configuration file(s).
262 .BR "\-q" ", " "\-\-quiet"
263 Don't print warning messages.
264 This option may be repeated:
265 each use reduces verbosity by one step,
269 The default verbosity level is 1,
270 which prints only warning measages.
273 .BR "\-r" ", " "\-\-remove-image"
274 Delete image files for the selected Lisp implementations,
275 rather than dumping them.
279 .BR \-\-no-remove-image .
282 .BR "\-v" ", " "\-\-verbose"
283 Be more verbose about the process of creating images.
284 Lisp implementations can be rather noisy:
286 .B dump-runlisp-image
287 runs silently unless something goes wrong,
288 in which case it prints the failed Lisp command line
293 .B dump-runlisp-image
294 will show Lisp implementation's noise immediately,
295 without waiting to see whether it succeeds or fails.
299 .B dump-runlisp-image
300 program first determines a collection of
302 Lisp implementations.
306 then the selected Lisps are those named on the command line.
310 and the configuration contains a setting for
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;
323 configured Lisp implementations which claim support for custom images
324 \(en i.e., configuration sections with settings for
328 \(en are selected, and the
334 then only those Lisp implementations which are actually installed
339 .B dump-runlisp-image
340 invokes each selected Lisp in order to determine a
342 For each selected Lisp system,
343 it constructs a command line,
346 to evaluate the expression resulting from expanding the
348 setting in the Lisp system's configuration section.
349 It hashes the result,
350 using a collision-resistant hash function
352 to produce a string of hexadecimal digits which represents
353 the versions of the various pieces of Lisp code which
355 be in the dumped image.
356 The standard setting for
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
367 options are all set.)
369 Having established the selected Lisps,
370 and their version hashes,
371 .B dump-runlisp-image
372 proceeds to act on them:
373 in the absence of the
376 it attempts to dump a custom image
377 for each selected Lisp implementation,
378 unless an image file already exists
384 is an optimization of image dumping,
385 and does not affect selection.)
386 On the other hand, if
389 then the custom image files of the selected Lisp implementations
395 then all the images for Lisp implementations
396 which are defined in the configuration
405 then all files in the image directory
406 which aren't recognized as being
407 the custom image of some Lisp implementation
410 If all of these operations are successfully performed
412 .B dump-runlisp-image
414 if there was a problem with the command line,
416 then it exits with status 127.
418 .\"--------------------------------------------------------------------------
421 .BR query-runlisp-config (1),
423 .BR runlisp.conf (5).
426 Mark Wooding, <mdw@distorted.org.uk>
428 .\"----- That's all, folks --------------------------------------------------