@@@ more wip

[runlisp] / dump-runlisp-image.1

.\" -*-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
..
.ds , \h'.16667m'
.
.\"--------------------------------------------------------------------------
.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 [ \-acluv ]
.RB [ \-o
.IR output ]
.RI [ lisp
\&...]
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B dump-runlisp-image
program builds 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 deafult.
The downside is that custom images may be rather large.
.
.SS "Supperted Common Lisp implementations"
The following Lisp implementations are currently supported.
.TP
.B "ccl"
Clozure Common Lisp.
The default image name is
.BR ccl+asdf.image ;
a typical image can be 20\(en30\*,MB in size.
.TP
.B "clisp"
GNU CLisp.
The default image name is
.BR clisp+asdf.mem ;
a typical image is about 10\*,MB in size.
.TP
.B "cmucl"
Carnegie\(enMellon University Common Lisp.
The default image name is
.BR cmucl+asdf.core ;
a typical image is about 35\*,MB in size.
.TP
.B "ecl"
Embeddable Common Lisp.
The default image name is
.BR ecl+asdf ;
images comparatively very small
\(en about 4\*,MB \(en
but, sadly, not very effective.
.TP
.B "sbcl"
Steel Bank Common Lisp.
The default image name is
.BR sbcl+asdf.core ;
a typical image is nearly 45\*,MB in size.
.PP
(Although
.BR runlisp (3)
also supports Armed Bear Common Lisp,
.B dump-runlisp-image
currently doesn't.)
.
.SS "Options"
The following options are accepted on the command line.
.
.TP
.B "\-h"
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
.B "\-v"
Write
.BR dump-runlisp-image 's
version number
to standard output
and immediately exit with status 0.
.
.TP
.B "\-a"
Dump images for all Lisp supported implementations
which are installed .
This implies
.BR \-c ,
described below.
You can't set
.B \-a
and also list implementations explicitly on the command line.
.
.TP
.B "\-c"
Only dump images for Lisp implementations
which are actually installed
(and can be found).
.
.TP
.B "\-l"
List the supported implementations
and the names of the image files for each
to standard output,
and immediately exit with status 0.
.
.TP
.BI "\-o " output
If
.I output
names a directory,
then write images to that directory
with their default names
(as listed above).
Otherwise,
exactly one Lisp implementation may be named, and
the image is written to a file named
.IR output .
By default,
images are written to the directory which
.BR runlisp (1)
will look in when checking for custom images
(shown in
.B "runlisp \-\-help"
or
.BR "dump-runlisp-image \-h" ),
unless overridden by the
.B RUNLISP_IMAGEDIR
environment variable.
.
.TP
.BI "\-u"
Don't create Lisp images
if a file with the appropriate name
already exists.
.
.TP
.BI "\-v"
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.
.PP
The
.B dump-runlisp-image
program will dump an image for each of the named
.I lisp
implementations in turn,
or all Lisp implementations, if
.B \-a
is set.
.PP
This involves invoking the Lisp implementations.
The
.B dump-runlisp-image
program expects, by default,
to be able to run a Lisp system
as a program with the same name,
found by searching as directed by the
.B PATH
environment variable.
This can be overridden by setting an environment variable,
with the same name but in
.IR "upper case" ,
to the actual name \(en
either a bare filename to be searched for on the
.BR PATH ,
or a pathname containing a
.RB ` / ',
relative to the working directory or absolute,
to the program.
Note that the entire variable value is used as the program name:
it's not possible to provide custom arguments to a Lisp system
using this mechanism.
If you want to do that,
you must write a shell script to do the necessary work,
and point the environment variable
(or the
.BR PATH )
at your script.
(This is the same convention as
.BR runlisp (1).)
.PP
If
.B \-a
or
.B \-c
is set,
then
.B dump-runlisp-image
will skip Lisp implementations
which can't actually be found
(by searching the
.B PATH
for its command name).
.
.\"--------------------------------------------------------------------------
.
.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 --------------------------------------------------