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
43 .\"--------------------------------------------------------------------------
44 .TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"
46 dump-runlisp-image \- dump Lisp images for faster script execution
48 .\"--------------------------------------------------------------------------
70 .\"--------------------------------------------------------------------------
75 program builds and manages custom images for use by
77 For many Lisp implementation,
79 with ASDF already loaded,
80 can start scripts much more quickly
81 than the `vanilla' images installed by default.
82 The downside is that custom images may be rather large.
86 filenames for each Lisp image:
87 the well-known one that
89 uses to run scripts is a symbolic link to the other,
90 the actual image file,
91 whose name contains an ugly hexadecimal lump
92 which identifies the versions of the Lisp code dumped in the image file.
95 program uses this hash to determine whether
96 the current image is up-to-date or needs replacing.
99 The following options are accepted on the command line.
102 .BR "\-h" ", " "\-\-help"
104 .BR dump-runlisp-image 's
106 and a description of the command-line options
108 and immediately exit with status 0.
111 .BR "\-V" ", " "\-\-version"
113 .BR dump-runlisp-image 's
116 and immediately exit with status 0.
119 .BI "\-O" "\fR, " "\-\-output=" output
123 then write images to that directory
124 with their default names as specified in the configuration file.
126 exactly one Lisp implementation must be explicitly named,
131 options must not be set,
133 the image is written to a file named
136 images are written to the directory in which
138 will look in when checking for custom images:
140 .B query-runlisp-config \-x@image-dir
141 to see the default setting.
144 .BR "\-R" ", " "\-\-remove-other"
145 After processing the selected Lisp implementations,
146 delete all of the image files corresponding to other Lisps
147 defined in the configuration.
151 .BR \-\-no-remove-other .
154 .BR "\-U" ", " "\-\-remove-unknown"
155 After processing the selected Lisp implementations,
156 delete all of the files in the image directory which
158 image files of a configured Lisp implementation.
162 .BR \-\-no-remove-unknown .
165 .BR "\-a" ", " "\-\-all-configured"
166 Select all configured Lisp implementations.
167 You must either list Lisp implementations explicitly on the command line
174 .BI "\-c" "\fR, " "\-\-config-file=" conf
175 Read configuration from
179 is a directory, then all of the files within
182 are loaded, in ascending lexicographical order;
186 All of the files are expected to be as described in
187 .BR runlisp.conf (5).
190 .BR "\-f" ", " "\-\-force"
191 Create fresh Lisp images
192 even if a file with the appropriate name
200 .BR "\-i" ", " "\-\-check-installed"
201 Only select those Lisp implementations
202 which are actually installed
204 To count as `installed',
207 must exist and be executable in one of the directories listed in the
209 environment variable,
210 as must the command named in the first word of the
213 Note that a Lisp implementation which fails this check
214 is not counted as `selected' for the purposes of the
217 For example, the command
218 .B "dump-runlisp-image \-Rai"
219 will dump images for Lisps which have been installed since the last run,
220 and delete images for Lisps which have been uninstalled since then.
224 .BR \-\-no-check-installed .
227 .BI "\-j" "\fR, " "\-\-jobs=" njobs
230 Lisp implementations in parallel.
231 The default is to run the jobs sequentially.
234 .BR "\-n" ", " "\-\-dry-run"
235 Don't actually run any commands to dump images.
236 This may be helpful for the curious,
239 to increase the verbosity.
243 .BR "\-\-no-dry-run" .
246 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect "\fR]\fB:" var = value
251 in configuration section
255 if no section is specified.
256 The value is unexpandable,
257 and overrides any similarly named setting
258 from the configuration file(s).
261 .BR "\-q" ", " "\-\-quiet"
262 Don't print warning messages.
263 This option may be repeated:
264 each use reduces verbosity by one step,
268 The default verbosity level is 1,
269 which prints only warning measages.
272 .BR "\-r" ", " "\-\-remove-image"
273 Delete image files for the selected Lisp implementations,
274 rather than dumping them.
278 .BR \-\-no-remove-image .
281 .BR "\-v" ", " "\-\-verbose"
282 Be more verbose about the process of creating images.
283 Lisp implementations can be rather noisy:
285 .B dump-runlisp-image
286 runs silently unless something goes wrong,
287 in which case it prints the failed Lisp command line
292 .B dump-runlisp-image
293 will show Lisp implementation's noise immediately,
294 without waiting to see whether it succeeds or fails.
298 .B dump-runlisp-image
299 program first determines a collection of
301 Lisp implementations.
305 then the selected Lisps are those named on the command line.
309 and the configuration contains a setting for
314 then its (expanded) value is taken to be
315 a list of Lisp implementation names
316 separated by commas and/or one or more whitespace characters,
317 and these named Lisp implementations are selected;
322 configured Lisp implementations which claim support for custom images
323 \(en i.e., configuration sections with settings for
327 \(en are selected, and the
333 then only those Lisp implementations which are actually installed
338 .B dump-runlisp-image
339 invokes each selected Lisp in order to determine a
341 For each selected Lisp system,
342 it constructs a command line,
345 to evaluate the expression resulting from expanding the
347 setting in the Lisp system's configuration section.
348 It hashes the result,
349 using a collision-resistant hash function
351 to produce a string of hexadecimal digits which represents
352 the versions of the various pieces of Lisp code which
354 be in the dumped image.
355 The standard setting for
357 includes the Lisp implementation version string
358 and the version of ASDF currently installed.
359 (This step is skipped
360 if it's not necessary to determine the Lisp system versions.
361 In practice, this happens when the
366 options are all set.)
368 Having established the selected Lisps,
369 and their version hashes,
370 .B dump-runlisp-image
371 proceeds to act on them:
372 in the absence of the
375 it attempts to dump a custom image
376 for each selected Lisp implementation,
377 unless an image file already exists
383 is an optimization of image dumping,
384 and does not affect selection.)
385 On the other hand, if
388 then the custom image files of the selected Lisp implementations
394 then all the images for Lisp implementations
395 which are defined in the configuration
404 then all files in the image directory
405 which aren't recognized as being
406 the custom image of some Lisp implementation
409 If all of these operations are successfully performed
411 .B dump-runlisp-image
413 if there was a problem with the command line,
415 then it exits with status 127.
417 .\"--------------------------------------------------------------------------
420 .BR query-runlisp-config (1),
422 .BR runlisp.conf (5).
425 Mark Wooding, <mdw@distorted.org.uk>
427 .\"----- That's all, folks --------------------------------------------------