dump-runlisp-image.1.in, runlisp.conf.5.in: Document the versioning system.

[runlisp] / dump-runlisp-image.1.in

diff --git a/dump-runlisp-image.1.in b/dump-runlisp-image.1.in
index 8f2bcc8..b6c4c33 100644 (file)
--- a/dump-runlisp-image.1.in
+++ b/dump-runlisp-image.1.in
@@ -73,7 +73,7 @@ dump-runlisp-image \- dump Lisp images for faster script execution
 .
 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,
@@ -81,6 +81,20 @@ with ASDF already loaded,
 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.
@@ -320,7 +334,40 @@ option is set,
 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