.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
-.ds , \h'.16667m'
.
.\"--------------------------------------------------------------------------
.TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"
.RB [ \-O
.IR output ]
.br
- \&
+ \c
.RB [ \-c
.IR conf ]
.RB [ \-o
.
The
.B dump-runlisp-image
-program builds custom images for use by
+program builds and manages custom images for use by
.BR runlisp (1).
For many Lisp implementation,
a custom image,
can start scripts much more quickly
than the `vanilla' images installed by default.
The downside is that custom images may be rather large.
+.PP
+There are actually
+.I two
+filenames for each Lisp image:
+the well-known one that
+.BR runlisp (1)
+uses to run scripts is a symbolic link to the other,
+the actual image file,
+whose name contains an ugly hexadecimal lump
+which identifies the versions of the Lisp code dumped in the image file.
+The
+.B dump-runlisp-image
+program uses this hash to determine whether
+the current image is up-to-date or needs replacing.
.
.SS "Options"
The following options are accepted on the command line.
and immediately exit with status 0.
.
.TP
-.BR "\-R" ", " "\-\-remove-other"
-After processing the selected Lisp implementations,
-delete all of the image files corresponding to other Lisps
-defined in the configuration.
-Negate with
-.B +R
-or
-.BR \-\-no-remove-other .
-.
-.TP
-.BR "\-U" ", " "\-\-remove-unknown"
-After processing the selected Lisp implementations,
-delete all of the files in the image directory which
-.I aren't
-image files of a configured Lisp implementation.
-Negate with
-.B +U
-or
-.BR \-\-no-remove-unknown .
-.
-.TP
.BI "\-O" "\fR, " "\-\-output=" output
If
.I output
to see the default setting.
.
.TP
+.BR "\-R" ", " "\-\-remove-other"
+After processing the selected Lisp implementations,
+delete all of the image files corresponding to other Lisps
+defined in the configuration.
+Negate with
+.B +R
+or
+.BR \-\-no-remove-other .
+.
+.TP
+.BR "\-U" ", " "\-\-remove-unknown"
+After processing the selected Lisp implementations,
+delete all of the files in the image directory which
+.I aren't
+image files of a configured Lisp implementation.
+Negate with
+.B +U
+or
+.BR \-\-no-remove-unknown .
+.
+.TP
.BR "\-a" ", " "\-\-all-configured"
Select all configured Lisp implementations.
You must either list Lisp implementations explicitly on the command line
.BR "\-\-no-dry-run" .
.
.TP
+.BI "\-o" "\fR, " "\-\-set-option=\fR[" sect "\fR]\fB:" var = value
+Assign
+.I value
+to the variable
+.I var
+in configuration section
+.IR sect ,
+or
+.B @CONFIG
+if no section is specified.
+The value is unexpandable,
+and overrides any similarly named setting
+from the configuration file(s).
+.
+.TP
.BR "\-q" ", " "\-\-quiet"
Don't print warning messages.
This option may be repeated:
then only those Lisp implementations which are actually installed
are selected.
.PP
+If necessary
+(see below),
+.B dump-runlisp-image
+invokes each selected Lisp in order to determine a
+.IR "version hash" .
+For each selected Lisp system,
+it constructs a command line,
+in the manner of
+.BR runlisp (1),
+to evaluate the expression resulting from expanding the
+.B lisp-version
+setting in the Lisp system's configuration section.
+It hashes the result,
+using a collision-resistant hash function
+(currently SHA256),
+to produce a string of hexadecimal digits which represents
+the versions of the various pieces of Lisp code which
+.I should
+be in the dumped image.
+The standard setting for
+.B lisp-version
+includes the Lisp implementation version string
+and the version of ASDF currently installed.
+(This step is skipped
+if it's not necessary to determine the Lisp system versions.
+In practice, this happens when the
+.RB ` \-r ',
+.RB ` \-R '
+and
+.RB ` \-U '
+options are all set.)
+.PP
Having established the selected Lisps,
+and their version hashes,
.B dump-runlisp-image
proceeds to act on them:
in the absence of the
~mdw / runlisp / blobdiff