From c7af83cd7374d95469252f4ee18dd4d157ab5b95 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 15 May 2021 10:58:50 +0100
Subject: [PATCH] dump-runlisp-image.1.in, runlisp.conf.5.in: Document the
 versioning system.

---
 dump-runlisp-image.1.in | 49 ++++++++++++++++++++++++++++++++++++++++++++++++-
 runlisp.conf.5.in       | 28 ++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/dump-runlisp-image.1.in b/dump-runlisp-image.1.in
index 8f2bcc8..b6c4c33 100644
--- 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
diff --git a/runlisp.conf.5.in b/runlisp.conf.5.in
index 2e06f57..f225eb9 100644
--- a/runlisp.conf.5.in
+++ b/runlisp.conf.5.in
@@ -549,6 +549,19 @@ section,
 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
@@ -566,6 +579,13 @@ section,
 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)
@@ -577,6 +597,14 @@ will rename the image into place itself,
 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)
-- 
2.11.0