.
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.
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
or a value determined at compile time.
.
.TP
+.B @hash
+Set by
+.BR dump-runlisp-image (1)
+to the hash
+(a string of hexadecimal digits)
+identifying the versions of the Lisp code included
+\(en or to be included \(en
+in a custom image.
+This is constructed by hashing the result of evaluating the
+.B lisp-version
+expression in the system definition.
+.
+.TP
.B @image-dir
The directory in which
.B runlisp
or a value determined at compile time.
.
.TP
+.B @image-link
+The well-known name of the image;
+actually a symbolic link to the `real' image file,
+whose name includes a hash
+which identifies the versions of the Lisp code included in the image.
+.
+.TP
.B @image-new
Set by
.BR dump-runlisp-image (1)
if the command completes successfully.)
.
.TP
+.B @image-newlink
+Set by
+.BR dump-runlisp-image (1)
+to the name to use for the updated symbolic link to the image file.
+This is used internally,
+and is not expected to be useful in Lisp system definitions.
+.
+.TP
.B @image-out
Set by
.BR dump-runlisp-image (1)