dump-ecl: Defeat ASDF's magic internal knowledge of itself.

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

diff --git a/dump-runlisp-image.1.in b/dump-runlisp-image.1.in
index 6c433f4..46c58c1 100644 (file)
--- a/dump-runlisp-image.1.in
+++ b/dump-runlisp-image.1.in
@@ -39,7 +39,7 @@
 .IP
 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
 ..
 .IP
 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
 ..

-.ds , \h'.16667m'
+.ds .. \&.\|.\|.

 .
 .\"--------------------------------------------------------------------------
 .TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"
 .
 .\"--------------------------------------------------------------------------
 .TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"


@@ -55,7 +55,7 @@ dump-runlisp-image \- dump Lisp images for faster script execution
 .RB [ \-O
 .IR output ]
 .br
 .RB [ \-O
 .IR output ]
 .br

-       \&
+       \c

 .RB [ \-c
 .IR conf ]
 .RB [ \-o
 .RB [ \-c
 .IR conf ]
 .RB [ \-o


@@ -66,14 +66,14 @@ dump-runlisp-image \- dump Lisp images for faster script execution
 .RB [ \-j
 .IR njobs ]
 .RI [ lisp
 .RB [ \-j
 .IR njobs ]
 .RI [ lisp

-\&...]
+\*(..]

 .
 .\"--------------------------------------------------------------------------
 .SH DESCRIPTION
 .
 The
 .B dump-runlisp-image
 .
 .\"--------------------------------------------------------------------------
 .SH DESCRIPTION
 .
 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,
 .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.
 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.
 .
 .SS "Options"
 The following options are accepted on the command line.


@@ -103,27 +117,6 @@ to standard output
 and immediately exit with status 0.
 .
 .TP
 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
 .BI "\-O" "\fR, " "\-\-output=" output
 If
 .I output


@@ -145,10 +138,31 @@ images are written to the directory in which
 .BR runlisp (1)
 will look in when checking for custom images:
 run
 .BR runlisp (1)
 will look in when checking for custom images:
 run

-.B query-runlisp-config -x@image-dir
+.B query-runlisp-config \-x@image-dir

 to see the default setting.
 .
 .TP
 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 "\-a" ", " "\-\-all-configured"
 Select all configured Lisp implementations.
 You must either list Lisp implementations explicitly on the command line


@@ -170,7 +184,7 @@ are loaded, in ascending lexicographical order;
 otherwise,
 .I conf
 is opened as a file.
 otherwise,
 .I conf
 is opened as a file.

-All of the files are expected to as described in
+All of the files are expected to be as described in

 .BR runlisp.conf (5).
 .
 .TP
 .BR runlisp.conf (5).
 .
 .TP


@@ -218,7 +232,7 @@ Lisp implementations in parallel.
 The default is to run the jobs sequentially.
 .
 .TP
 The default is to run the jobs sequentially.
 .
 .TP

-.BR "\-n" ", " "-\-dry-run"
+.BR "\-n" ", " "\-\-dry-run"

 Don't actually run any commands to dump images.
 This may be helpful for the curious,
 in conjunction with
 Don't actually run any commands to dump images.
 This may be helpful for the curious,
 in conjunction with


@@ -230,6 +244,21 @@ or
 .BR "\-\-no-dry-run" .
 .
 .TP
 .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:
 .BR "\-q" ", " "\-\-quiet"
 Don't print warning messages.
 This option may be repeated:


@@ -305,7 +334,40 @@ option is set,
 then only those Lisp implementations which are actually installed
 are selected.
 .PP
 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,
 Having established the selected Lisps,

+and their version hashes,

 .B dump-runlisp-image
 proceeds to act on them:
 in the absence of the
 .B dump-runlisp-image
 proceeds to act on them:
 in the absence of the