mdw@git.distorted.org.uk Git - runlisp/blob - dump-runlisp-image.1

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for `dump-runlisp-image'
   4 .\"
   5 .\" (c) 2020 Mark Wooding
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
  11 .\"
  12 .\" Runlisp is free software: you can redistribute it and/or modify it
  13 .\" under the terms of the GNU General Public License as published by the
  14 .\" Free Software Foundation; either version 3 of the License, or (at your
  15 .\" option) any later version.
  16 .\"
  17 .\" Runlisp is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20 .\" for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with Runlisp.  If not, see <https://www.gnu.org/licenses/>.
  24 .
  25 .ie t \{\
  26 .  ds o \(bu
  27 .  if \n(.g \{\
  28 .    fam P
  29 .    ev an-1
  30 .    fam P
  31 .    ev
  32 .  \}
  33 .\}
  34 .el \{\
  35 .  ds o o
  36 .\}
  37 .
  38 .de hP
  39 .IP
  40 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
  41 ..
  42 .ds , \h'.16667m'
  43 .
  44 .\"--------------------------------------------------------------------------
  45 .TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"
  46 .SH NAME
  47 dump-runlisp-image \- dump Lisp images for faster script execution
  48 .
  49 .\"--------------------------------------------------------------------------
  50 .SH SYNOPSIS
  51 .
  52 .B dump-runlisp-image
  53 .RB [ \-acluv ]
  54 .RB [ \-o
  55 .IR output ]
  56 .RI [ lisp
  57 \&...]
  58 .
  59 .\"--------------------------------------------------------------------------
  60 .SH DESCRIPTION
  61 .
  62 The
  63 .B dump-runlisp-image
  64 program builds custom images for use by
  65 .BR runlisp (1).
  66 For many Lisp implementation,
  67 a custom image,
  68 with ASDF already loaded,
  69 can start scripts much more quickly
  70 than the `vanilla' images installed by deafult.
  71 The downside is that custom images may be rather large.
  72 .
  73 .SS "Supperted Common Lisp implementations"
  74 The following Lisp implementations are currently supported.
  75 .TP
  76 .B "ccl"
  77 Clozure Common Lisp.
  78 The default image name is
  79 .BR ccl+asdf.image ;
  80 a typical image can be 20\(en30\*,MB in size.
  81 .TP
  82 .B "clisp"
  83 GNU CLisp.
  84 The default image name is
  85 .BR clisp+asdf.mem ;
  86 a typical image is about 10\*,MB in size.
  87 .TP
  88 .B "cmucl"
  89 Carnegie\(enMellon University Common Lisp.
  90 The default image name is
  91 .BR cmucl+asdf.core ;
  92 a typical image is about 35\*,MB in size.
  93 .TP
  94 .B "ecl"
  95 Embeddable Common Lisp.
  96 The default image name is
  97 .BR ecl+asdf ;
  98 images comparatively very small
  99 \(en about 4\*,MB \(en
 100 but, sadly, not very effective.
 101 .TP
 102 .B "sbcl"
 103 Steel Bank Common Lisp.
 104 The default image name is
 105 .BR sbcl+asdf.core ;
 106 a typical image is nearly 45\*,MB in size.
 107 .PP
 108 (Although
 109 .BR runlisp (3)
 110 also supports Armed Bear Common Lisp,
 111 .B dump-runlisp-image
 112 currently doesn't.)
 113 .
 114 .SS "Options"
 115 The following options are accepted on the command line.
 116 .
 117 .TP
 118 .B "\-h"
 119 Write a synopsis of
 120 .BR dump-runlisp-image 's
 121 command-line syntax
 122 and a description of the command-line options
 123 to standard output
 124 and immediately exit with status 0.
 125 .
 126 .TP
 127 .B "\-v"
 128 Write
 129 .BR dump-runlisp-image 's
 130 version number
 131 to standard output
 132 and immediately exit with status 0.
 133 .
 134 .TP
 135 .B "\-a"
 136 Dump images for all Lisp supported implementations
 137 which are installed .
 138 This implies
 139 .BR \-c ,
 140 described below.
 141 You can't set
 142 .B \-a
 143 and also list implementations explicitly on the command line.
 144 .
 145 .TP
 146 .B "\-c"
 147 Only dump images for Lisp implementations
 148 which are actually installed
 149 (and can be found).
 150 .
 151 .TP
 152 .B "\-l"
 153 List the supported implementations
 154 and the names of the image files for each
 155 to standard output,
 156 and immediately exit with status 0.
 157 .
 158 .TP
 159 .BI "\-o " output
 160 If
 161 .I output
 162 names a directory,
 163 then write images to that directory
 164 with their default names
 165 (as listed above).
 166 Otherwise,
 167 exactly one Lisp implementation may be named, and
 168 the image is written to a file named
 169 .IR output .
 170 By default,
 171 images are written to the directory which
 172 .BR runlisp (1)
 173 will look in when checking for custom images
 174 (shown in
 175 .B "runlisp \-\-help"
 176 or
 177 .BR "dump-runlisp-image \-h" ),
 178 unless overridden by the
 179 .B RUNLISP_IMAGEDIR
 180 environment variable.
 181 .
 182 .TP
 183 .BI "\-u"
 184 Don't create Lisp images
 185 if a file with the appropriate name
 186 already exists.
 187 .
 188 .TP
 189 .BI "\-v"
 190 Be more verbose about the process of creating images.
 191 Lisp implementations can be rather noisy:
 192 by default,
 193 .B dump-runlisp-image
 194 runs silently unless something goes wrong,
 195 in which case it prints the failed Lisp command line
 196 and its output.
 197 If you set
 198 .B \-v
 199 then
 200 .B dump-runlisp-image
 201 will show Lisp implementation's noise immediately,
 202 without waiting to see whether it succeeds or fails.
 203 .PP
 204 The
 205 .B dump-runlisp-image
 206 program will dump an image for each of the named
 207 .I lisp
 208 implementations in turn,
 209 or all Lisp implementations, if
 210 .B \-a
 211 is set.
 212 .PP
 213 This involves invoking the Lisp implementations.
 214 The
 215 .B dump-runlisp-image
 216 program expects, by default,
 217 to be able to run a Lisp system
 218 as a program with the same name,
 219 found by searching as directed by the
 220 .B PATH
 221 environment variable.
 222 This can be overridden by setting an environment variable,
 223 with the same name but in
 224 .IR "upper case" ,
 225 to the actual name \(en
 226 either a bare filename to be searched for on the
 227 .BR PATH ,
 228 or a pathname containing a
 229 .RB ` / ',
 230 relative to the working directory or absolute,
 231 to the program.
 232 Note that the entire variable value is used as the program name:
 233 it's not possible to provide custom arguments to a Lisp system
 234 using this mechanism.
 235 If you want to do that,
 236 you must write a shell script to do the necessary work,
 237 and point the environment variable
 238 (or the
 239 .BR PATH )
 240 at your script.
 241 (This is the same convention as
 242 .BR runlisp (1).)
 243 .PP
 244 If
 245 .B \-a
 246 or
 247 .B \-c
 248 is set,
 249 then
 250 .B dump-runlisp-image
 251 will skip Lisp implementations
 252 which can't actually be found
 253 (by searching the
 254 .B PATH
 255 for its command name).
 256 .
 257 .\"--------------------------------------------------------------------------
 258 .
 259 .SH SEE ALSO
 260 .BR query-runlisp-config (1),
 261 .BR runlisp (1),
 262 .BR runlisp.conf (5).
 263 .
 264 .SH AUTHOR
 265 Mark Wooding, <mdw@distorted.org.uk>
 266 .
 267 .\"----- That's all, folks --------------------------------------------------