+++ /dev/null
-.\" -*-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 --------------------------------------------------
~mdw / runlisp / blobdiff