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 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.
86 The following options are accepted on the command line.
89 .BR "\-h" ", " "\-\-help"
91 .BR dump-runlisp-image 's
93 and a description of the command-line options
95 and immediately exit with status 0.
98 .BR "\-V" ", " "\-\-version"
100 .BR dump-runlisp-image 's
103 and immediately exit with status 0.
106 .BI "\-O" "\fR, " "\-\-output=" output
110 then write images to that directory
111 with their default names as specified in the configuration file.
113 exactly one Lisp implementation must be explicitly named,
118 options must not be set,
120 the image is written to a file named
123 images are written to the directory in which
125 will look in when checking for custom images:
127 .B query-runlisp-config \-x@image-dir
128 to see the default setting.
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.
138 .BR \-\-no-remove-other .
141 .BR "\-U" ", " "\-\-remove-unknown"
142 After processing the selected Lisp implementations,
143 delete all of the files in the image directory which
145 image files of a configured Lisp implementation.
149 .BR \-\-no-remove-unknown .
152 .BR "\-a" ", " "\-\-all-configured"
153 Select all configured Lisp implementations.
154 You must either list Lisp implementations explicitly on the command line
161 .BI "\-c" "\fR, " "\-\-config-file=" conf
162 Read configuration from
166 is a directory, then all of the files within
169 are loaded, in ascending lexicographical order;
173 All of the files are expected to be as described in
174 .BR runlisp.conf (5).
177 .BR "\-f" ", " "\-\-force"
178 Create fresh Lisp images
179 even if a file with the appropriate name
187 .BR "\-i" ", " "\-\-check-installed"
188 Only select those Lisp implementations
189 which are actually installed
191 To count as `installed',
194 must exist and be executable in one of the directories listed in the
196 environment variable,
197 as must the command named in the first word of the
200 Note that a Lisp implementation which fails this check
201 is not counted as `selected' for the purposes of the
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.
211 .BR \-\-no-check-installed .
214 .BI "\-j" "\fR, " "\-\-jobs=" njobs
217 Lisp implementations in parallel.
218 The default is to run the jobs sequentially.
221 .BR "\-n" ", " "\-\-dry-run"
222 Don't actually run any commands to dump images.
223 This may be helpful for the curious,
226 to increase the verbosity.
230 .BR "\-\-no-dry-run" .
233 .BR "\-q" ", " "\-\-quiet"
234 Don't print warning messages.
235 This option may be repeated:
236 each use reduces verbosity by one step,
240 The default verbosity level is 1,
241 which prints only warning measages.
244 .BR "\-r" ", " "\-\-remove-image"
245 Delete image files for the selected Lisp implementations,
246 rather than dumping them.
250 .BR \-\-no-remove-image .
253 .BR "\-v" ", " "\-\-verbose"
254 Be more verbose about the process of creating images.
255 Lisp implementations can be rather noisy:
257 .B dump-runlisp-image
258 runs silently unless something goes wrong,
259 in which case it prints the failed Lisp command line
264 .B dump-runlisp-image
265 will show Lisp implementation's noise immediately,
266 without waiting to see whether it succeeds or fails.
270 .B dump-runlisp-image
271 program first determines a collection of
273 Lisp implementations.
277 then the selected Lisps are those named on the command line.
281 and the configuration contains a setting for
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;
294 configured Lisp implementations which claim support for custom images
295 \(en i.e., configuration sections with settings for
299 \(en are selected, and the
305 then only those Lisp implementations which are actually installed
308 Having established the selected Lisps,
309 .B dump-runlisp-image
310 proceeds to act on them:
311 in the absence of the
314 it attempts to dump a custom image
315 for each selected Lisp implementation,
316 unless an image file already exists
322 is an optimization of image dumping,
323 and does not affect selection.)
324 On the other hand, if
327 then the custom image files of the selected Lisp implementations
333 then all the images for Lisp implementations
334 which are defined in the configuration
343 then all files in the image directory
344 which aren't recognized as being
345 the custom image of some Lisp implementation
348 If all of these operations are successfully performed
350 .B dump-runlisp-image
352 if there was a problem with the command line,
354 then it exits with status 127.
356 .\"--------------------------------------------------------------------------
359 .BR query-runlisp-config (1),
361 .BR runlisp.conf (5).
364 Mark Wooding, <mdw@distorted.org.uk>
366 .\"----- That's all, folks --------------------------------------------------