*.[1-9].in: Delete apparently pointless definitions of `\*,'.

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

.\" -*-nroff-*-
.\"
.\" Manual for `dump-runlisp-image'
.\"
.\" (c) 2020 Mark Wooding
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
.\"
.\" Runlisp is free software: you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" Runlisp is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Runlisp.  If not, see <https://www.gnu.org/licenses/>.
.
.ie t \{\
.  ds o \(bu
.  if \n(.g \{\
.    fam P
.    ev an-1
.    fam P
.    ev
.  \}
.\}
.el \{\
.  ds o o
.\}
.
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.
.\"--------------------------------------------------------------------------
.TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"
.SH NAME
dump-runlisp-image \- dump Lisp images for faster script execution
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.B dump-runlisp-image
.RB [ \-RUafinqrv ]
.RB [ +RUfinr ]
.RB [ \-O
.IR output ]
.br
	\c
.RB [ \-c
.IR conf ]
.RB [ \-o
.RI [ sect \c
.BR : ] \c
.IB var = \c
.IR value ]
.RB [ \-j
.IR njobs ]
.RI [ lisp
\&...]
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B dump-runlisp-image
program builds and manages custom images for use by
.BR runlisp (1).
For many Lisp implementation,
a custom image,
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.
.
.TP
.BR "\-h" ", " "\-\-help"
Write a synopsis of
.BR dump-runlisp-image 's
command-line syntax
and a description of the command-line options
to standard output
and immediately exit with status 0.
.
.TP
.BR "\-V" ", " "\-\-version"
Write
.BR dump-runlisp-image 's
version number
to standard output
and immediately exit with status 0.
.
.TP
.BI "\-O" "\fR, " "\-\-output=" output
If
.I output
names a directory,
then write images to that directory
with their default names as specified in the configuration file.
Otherwise,
exactly one Lisp implementation must be explicitly named,
the
.RB ` \-R '
and
.RB `\-U '
options must not be set,
and
the image is written to a file named
.IR output .
By default,
images are written to the directory in which
.BR runlisp (1)
will look in when checking for custom images:
run
.B query-runlisp-config \-x@image-dir
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
or set the
.RB ` \- a'
option,
but not both.
.
.TP
.BI "\-c" "\fR, " "\-\-config-file=" conf
Read configuration from
.IR conf .
If
.I conf
is a directory, then all of the files within
whose names end with
.RB ` .conf ',
are loaded, in ascending lexicographical order;
otherwise,
.I conf
is opened as a file.
All of the files are expected to be as described in
.BR runlisp.conf (5).
.
.TP
.BR "\-f" ", " "\-\-force"
Create fresh Lisp images
even if a file with the appropriate name
already exists.
Negate with
.B +f
or
.BR \-\-no-force .
.
.TP
.BR "\-i" ", " "\-\-check-installed"
Only select those Lisp implementations
which are actually installed
(and can be found).
To count as `installed',
the program named by
.B command
must exist and be executable in one of the directories listed in the
.B PATH
environment variable,
as must the command named in the first word of the
.B dump-image
command line.
Note that a Lisp implementation which fails this check
is not counted as `selected' for the purposes of the
.RB ` \-R '
option above.
For example, the command
.B "dump-runlisp-image \-Rai"
will dump images for Lisps which have been installed since the last run,
and delete images for Lisps which have been uninstalled since then.
Negate with
.B +i
or
.BR \-\-no-check-installed .
.
.TP
.BI "\-j" "\fR, " "\-\-jobs=" njobs
Dump image for up to
.I njobs
Lisp implementations in parallel.
The default is to run the jobs sequentially.
.
.TP
.BR "\-n" ", " "\-\-dry-run"
Don't actually run any commands to dump images.
This may be helpful for the curious,
in conjunction with
.RB ` \-v '
to increase the verbosity.
Negate with
.B +n
or
.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:
each use reduces verbosity by one step,
counteracting one
.RB ` \-v '
option.
The default verbosity level is 1,
which prints only warning measages.
.
.TP
.BR "\-r" ", " "\-\-remove-image"
Delete image files for the selected Lisp implementations,
rather than dumping them.
Negate with
.B +r
or
.BR \-\-no-remove-image .
.
.TP
.BR "\-v" ", " "\-\-verbose"
Be more verbose about the process of creating images.
Lisp implementations can be rather noisy:
by default,
.B dump-runlisp-image
runs silently unless something goes wrong,
in which case it prints the failed Lisp command line
and its output.
If you set
.B \-v
then
.B dump-runlisp-image
will show Lisp implementation's noise immediately,
without waiting to see whether it succeeds or fails.
.
.SS "Operation"
The
.B dump-runlisp-image
program first determines a collection of
.I selected
Lisp implementations.
If the
.RB ` \-a '
option is not set,
then the selected Lisps are those named on the command line.
If
.RB ` \-a '
is set,
and the configuration contains a setting for
.B dump
in the
.B @CONFIG
section,
then its (expanded) value is taken to be
a list of Lisp implementation names
separated by commas and/or one or more whitespace characters,
and these named Lisp implementations are selected;
if there is no
.B dump
setting, then
.I all
configured Lisp implementations which claim support for custom images
\(en i.e., configuration sections with settings for
.B run-script
and
.B image-file
\(en are selected, and the
.RB ` \-i '
option is forced on.
If the
.RB ` \-i '
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
.RB ` \-r '
option,
it attempts to dump a custom image
for each selected Lisp implementation,
unless an image file already exists
or the
.RB ` \-f '
option is set.
(Note that
.RB ` \-f '
is an optimization of image dumping,
and does not affect selection.)
On the other hand, if
.RB ` \-r '
is set,
then the custom image files of the selected Lisp implementations
are deleted.
.PP
Next, if the
.RB ` \-R '
option is set,
then all the images for Lisp implementations
which are defined in the configuration
but were
.I not
selected
are deleted.
.PP
Finally, if the
.RB ` \-U '
option is set,
then all files in the image directory
which aren't recognized as being
the custom image of some Lisp implementation
are deleted.
.PP
If all of these operations are successfully performed
then
.B dump-runlisp-image
exits with status 0;
if there was a problem with the command line,
or if any jobs fail,
then it exits with status 127.
.
.\"--------------------------------------------------------------------------
.
.SH SEE ALSO
.BR query-runlisp-config (1),
.BR runlisp (1),
.BR runlisp.conf (5).
.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------