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

   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 [ \-RUafinqrv ]
  54 .RB [ +RUfinr ]
  55 .RB [ \-O
  56 .IR output ]
  57 .br
  58         \&
  59 .RB [ \-c
  60 .IR conf ]
  61 .RB [ \-o
  62 .RI [ sect \c
  63 .BR : ] \c
  64 .IB var = \c
  65 .IR value ]
  66 .RB [ \-j
  67 .IR njobs ]
  68 .RI [ lisp
  69 \&...]
  70 .
  71 .\"--------------------------------------------------------------------------
  72 .SH DESCRIPTION
  73 .
  74 The
  75 .B dump-runlisp-image
  76 program builds custom images for use by
  77 .BR runlisp (1).
  78 For many Lisp implementation,
  79 a custom image,
  80 with ASDF already loaded,
  81 can start scripts much more quickly
  82 than the `vanilla' images installed by default.
  83 The downside is that custom images may be rather large.
  84 .
  85 .SS "Options"
  86 The following options are accepted on the command line.
  87 .
  88 .TP
  89 .BR "\-h" ", " "\-\-help"
  90 Write a synopsis of
  91 .BR dump-runlisp-image 's
  92 command-line syntax
  93 and a description of the command-line options
  94 to standard output
  95 and immediately exit with status 0.
  96 .
  97 .TP
  98 .BR "\-V" ", " "\-\-version"
  99 Write
 100 .BR dump-runlisp-image 's
 101 version number
 102 to standard output
 103 and immediately exit with status 0.
 104 .
 105 .TP
 106 .BR "\-R" ", " "\-\-remove-other"
 107 After processing the selected Lisp implementations,
 108 delete all of the image files corresponding to other Lisps
 109 defined in the configuration.
 110 Negate with
 111 .B +R
 112 or
 113 .BR \-\-no-remove-other .
 114 .
 115 .TP
 116 .BR "\-U" ", " "\-\-remove-unknown"
 117 After processing the selected Lisp implementations,
 118 delete all of the files in the image directory which
 119 .I aren't
 120 image files of a configured Lisp implementation.
 121 Negate with
 122 .B +U
 123 or
 124 .BR \-\-no-remove-unknown .
 125 .
 126 .TP
 127 .BI "\-O" "\fR, " "\-\-output=" output
 128 If
 129 .I output
 130 names a directory,
 131 then write images to that directory
 132 with their default names as specified in the configuration file.
 133 Otherwise,
 134 exactly one Lisp implementation must be explicitly named,
 135 the
 136 .RB ` \-R '
 137 and
 138 .RB `\-U '
 139 options must not be set,
 140 and
 141 the image is written to a file named
 142 .IR output .
 143 By default,
 144 images are written to the directory in which
 145 .BR runlisp (1)
 146 will look in when checking for custom images:
 147 run
 148 .B query-runlisp-config -x@image-dir
 149 to see the default setting.
 150 .
 151 .TP
 152 .BR "\-a" ", " "\-\-all-configured"
 153 Select all configured Lisp implementations.
 154 You must either list Lisp implementations explicitly on the command line
 155 or set the
 156 .RB ` \- a'
 157 option,
 158 but not both.
 159 .
 160 .TP
 161 .BI "\-c" "\fR, " "\-\-config-file=" conf
 162 Read configuration from
 163 .IR conf .
 164 If
 165 .I conf
 166 is a directory, then all of the files within
 167 whose names end with
 168 .RB ` .conf ',
 169 are loaded, in ascending lexicographical order;
 170 otherwise,
 171 .I conf
 172 is opened as a file.
 173 All of the files are expected to as described in
 174 .BR runlisp.conf (5).
 175 .
 176 .TP
 177 .BR "\-f" ", " "\-\-force"
 178 Create fresh Lisp images
 179 even if a file with the appropriate name
 180 already exists.
 181 Negate with
 182 .B +f
 183 or
 184 .BR \-\-no-force .
 185 .
 186 .TP
 187 .BR "\-i" ", " "\-\-check-installed"
 188 Only select those Lisp implementations
 189 which are actually installed
 190 (and can be found).
 191 To count as `installed',
 192 the program named by
 193 .B command
 194 must exist and be executable in one of the directories listed in the
 195 .B PATH
 196 environment variable,
 197 as must the command named in the first word of the
 198 .B dump-image
 199 command line.
 200 Note that a Lisp implementation which fails this check
 201 is not counted as `selected' for the purposes of the
 202 .RB ` \-R '
 203 option above.
 204 For example, the command
 205 .B "dump-runlisp-image \-Rai"
 206 will dump images for Lisps which have been installed since the last run,
 207 and delete images for Lisps which have been uninstalled since then.
 208 Negate with
 209 .B +i
 210 or
 211 .BR \-\-no-check-installed .
 212 .
 213 .TP
 214 .BI "\-j" "\fR, " "\-\-jobs=" njobs
 215 Dump image for up to
 216 .I njobs
 217 Lisp implementations in parallel.
 218 The default is to run the jobs sequentially.
 219 .
 220 .TP
 221 .BR "\-n" ", " "-\-dry-run"
 222 Don't actually run any commands to dump images.
 223 This may be helpful for the curious,
 224 in conjunction with
 225 .RB ` \-v '
 226 to increase the verbosity.
 227 Negate with
 228 .B +n
 229 or
 230 .BR "\-\-no-dry-run" .
 231 .
 232 .TP
 233 .BR "\-q" ", " "\-\-quiet"
 234 Don't print warning messages.
 235 This option may be repeated:
 236 each use reduces verbosity by one step,
 237 counteracting one
 238 .RB ` \-v '
 239 option.
 240 The default verbosity level is 1,
 241 which prints only warning measages.
 242 .
 243 .TP
 244 .BR "\-r" ", " "\-\-remove-image"
 245 Delete image files for the selected Lisp implementations,
 246 rather than dumping them.
 247 Negate with
 248 .B +r
 249 or
 250 .BR \-\-no-remove-image .
 251 .
 252 .TP
 253 .BR "\-v" ", " "\-\-verbose"
 254 Be more verbose about the process of creating images.
 255 Lisp implementations can be rather noisy:
 256 by default,
 257 .B dump-runlisp-image
 258 runs silently unless something goes wrong,
 259 in which case it prints the failed Lisp command line
 260 and its output.
 261 If you set
 262 .B \-v
 263 then
 264 .B dump-runlisp-image
 265 will show Lisp implementation's noise immediately,
 266 without waiting to see whether it succeeds or fails.
 267 .
 268 .SS "Operation"
 269 The
 270 .B dump-runlisp-image
 271 program first determines a collection of
 272 .I selected
 273 Lisp implementations.
 274 If the
 275 .RB ` \-a '
 276 option is not set,
 277 then the selected Lisps are those named on the command line.
 278 If
 279 .RB ` \-a '
 280 is set,
 281 and the configuration contains a setting for
 282 .B dump
 283 in the
 284 .B @CONFIG
 285 section,
 286 then its (expanded) value is taken to be
 287 a list of Lisp implementation names
 288 separated by commas and/or one or more whitespace characters,
 289 and these named Lisp implementations are selected;
 290 if there is no
 291 .B dump
 292 setting, then
 293 .I all
 294 configured Lisp implementations which claim support for custom images
 295 \(en i.e., configuration sections with settings for
 296 .B run-script
 297 and
 298 .B image-file
 299 \(en are selected, and the
 300 .RB ` \-i '
 301 option is forced on.
 302 If the
 303 .RB ` \-i '
 304 option is set,
 305 then only those Lisp implementations which are actually installed
 306 are selected.
 307 .PP
 308 Having established the selected Lisps,
 309 .B dump-runlisp-image
 310 proceeds to act on them:
 311 in the absence of the
 312 .RB ` \-r '
 313 option,
 314 it attempts to dump a custom image
 315 for each selected Lisp implementation,
 316 unless an image file already exists
 317 or the
 318 .RB ` \-f '
 319 option is set.
 320 (Note that
 321 .RB ` \-f '
 322 is an optimization of image dumping,
 323 and does not affect selection.)
 324 On the other hand, if
 325 .RB ` \-r '
 326 is set,
 327 then the custom image files of the selected Lisp implementations
 328 are deleted.
 329 .PP
 330 Next, if the
 331 .RB ` \-R '
 332 option is set,
 333 then all the images for Lisp implementations
 334 which are defined in the configuration
 335 but were
 336 .I not
 337 selected
 338 are deleted.
 339 .PP
 340 Finally, if the
 341 .RB ` \-U '
 342 option is set,
 343 then all files in the image directory
 344 which aren't recognized as being
 345 the custom image of some Lisp implementation
 346 are deleted.
 347 .PP
 348 If all of these operations are successfully performed
 349 then
 350 .B dump-runlisp-image
 351 exits with status 0;
 352 if there was a problem with the command line,
 353 or if any jobs fail,
 354 then it exits with status 127.
 355 .
 356 .\"--------------------------------------------------------------------------
 357 .
 358 .SH SEE ALSO
 359 .BR query-runlisp-config (1),
 360 .BR runlisp (1),
 361 .BR runlisp.conf (5).
 362 .
 363 .SH AUTHOR
 364 Mark Wooding, <mdw@distorted.org.uk>
 365 .
 366 .\"----- That's all, folks --------------------------------------------------