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 .. \&.\|.\|.
  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         \c
  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 and manages 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 .PP
  85 There are actually
  86 .I two
  87 filenames for each Lisp image:
  88 the well-known one that
  89 .BR runlisp (1)
  90 uses to run scripts is a symbolic link to the other,
  91 the actual image file,
  92 whose name contains an ugly hexadecimal lump
  93 which identifies the versions of the Lisp code dumped in the image file.
  94 The
  95 .B dump-runlisp-image
  96 program uses this hash to determine whether
  97 the current image is up-to-date or needs replacing.
  98 .
  99 .SS "Options"
 100 The following options are accepted on the command line.
 101 .
 102 .TP
 103 .BR "\-h" ", " "\-\-help"
 104 Write a synopsis of
 105 .BR dump-runlisp-image 's
 106 command-line syntax
 107 and a description of the command-line options
 108 to standard output
 109 and immediately exit with status 0.
 110 .
 111 .TP
 112 .BR "\-V" ", " "\-\-version"
 113 Write
 114 .BR dump-runlisp-image 's
 115 version number
 116 to standard output
 117 and immediately exit with status 0.
 118 .
 119 .TP
 120 .BI "\-O" "\fR, " "\-\-output=" output
 121 If
 122 .I output
 123 names a directory,
 124 then write images to that directory
 125 with their default names as specified in the configuration file.
 126 Otherwise,
 127 exactly one Lisp implementation must be explicitly named,
 128 the
 129 .RB ` \-R '
 130 and
 131 .RB `\-U '
 132 options must not be set,
 133 and
 134 the image is written to a file named
 135 .IR output .
 136 By default,
 137 images are written to the directory in which
 138 .BR runlisp (1)
 139 will look in when checking for custom images:
 140 run
 141 .B query-runlisp-config \-x@image-dir
 142 to see the default setting.
 143 .
 144 .TP
 145 .BR "\-R" ", " "\-\-remove-other"
 146 After processing the selected Lisp implementations,
 147 delete all of the image files corresponding to other Lisps
 148 defined in the configuration.
 149 Negate with
 150 .B +R
 151 or
 152 .BR \-\-no-remove-other .
 153 .
 154 .TP
 155 .BR "\-U" ", " "\-\-remove-unknown"
 156 After processing the selected Lisp implementations,
 157 delete all of the files in the image directory which
 158 .I aren't
 159 image files of a configured Lisp implementation.
 160 Negate with
 161 .B +U
 162 or
 163 .BR \-\-no-remove-unknown .
 164 .
 165 .TP
 166 .BR "\-a" ", " "\-\-all-configured"
 167 Select all configured Lisp implementations.
 168 You must either list Lisp implementations explicitly on the command line
 169 or set the
 170 .RB ` \- a'
 171 option,
 172 but not both.
 173 .
 174 .TP
 175 .BI "\-c" "\fR, " "\-\-config-file=" conf
 176 Read configuration from
 177 .IR conf .
 178 If
 179 .I conf
 180 is a directory, then all of the files within
 181 whose names end with
 182 .RB ` .conf ',
 183 are loaded, in ascending lexicographical order;
 184 otherwise,
 185 .I conf
 186 is opened as a file.
 187 All of the files are expected to be as described in
 188 .BR runlisp.conf (5).
 189 .
 190 .TP
 191 .BR "\-f" ", " "\-\-force"
 192 Create fresh Lisp images
 193 even if a file with the appropriate name
 194 already exists.
 195 Negate with
 196 .B +f
 197 or
 198 .BR \-\-no-force .
 199 .
 200 .TP
 201 .BR "\-i" ", " "\-\-check-installed"
 202 Only select those Lisp implementations
 203 which are actually installed
 204 (and can be found).
 205 To count as `installed',
 206 the program named by
 207 .B command
 208 must exist and be executable in one of the directories listed in the
 209 .B PATH
 210 environment variable,
 211 as must the command named in the first word of the
 212 .B dump-image
 213 command line.
 214 Note that a Lisp implementation which fails this check
 215 is not counted as `selected' for the purposes of the
 216 .RB ` \-R '
 217 option above.
 218 For example, the command
 219 .B "dump-runlisp-image \-Rai"
 220 will dump images for Lisps which have been installed since the last run,
 221 and delete images for Lisps which have been uninstalled since then.
 222 Negate with
 223 .B +i
 224 or
 225 .BR \-\-no-check-installed .
 226 .
 227 .TP
 228 .BI "\-j" "\fR, " "\-\-jobs=" njobs
 229 Dump image for up to
 230 .I njobs
 231 Lisp implementations in parallel.
 232 The default is to run the jobs sequentially.
 233 .
 234 .TP
 235 .BR "\-n" ", " "\-\-dry-run"
 236 Don't actually run any commands to dump images.
 237 This may be helpful for the curious,
 238 in conjunction with
 239 .RB ` \-v '
 240 to increase the verbosity.
 241 Negate with
 242 .B +n
 243 or
 244 .BR "\-\-no-dry-run" .
 245 .
 246 .TP
 247 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect "\fR]\fB:" var = value
 248 Assign
 249 .I value
 250 to the variable
 251 .I var
 252 in configuration section
 253 .IR sect ,
 254 or
 255 .B @CONFIG
 256 if no section is specified.
 257 The value is unexpandable,
 258 and overrides any similarly named setting
 259 from the configuration file(s).
 260 .
 261 .TP
 262 .BR "\-q" ", " "\-\-quiet"
 263 Don't print warning messages.
 264 This option may be repeated:
 265 each use reduces verbosity by one step,
 266 counteracting one
 267 .RB ` \-v '
 268 option.
 269 The default verbosity level is 1,
 270 which prints only warning measages.
 271 .
 272 .TP
 273 .BR "\-r" ", " "\-\-remove-image"
 274 Delete image files for the selected Lisp implementations,
 275 rather than dumping them.
 276 Negate with
 277 .B +r
 278 or
 279 .BR \-\-no-remove-image .
 280 .
 281 .TP
 282 .BR "\-v" ", " "\-\-verbose"
 283 Be more verbose about the process of creating images.
 284 Lisp implementations can be rather noisy:
 285 by default,
 286 .B dump-runlisp-image
 287 runs silently unless something goes wrong,
 288 in which case it prints the failed Lisp command line
 289 and its output.
 290 If you set
 291 .B \-v
 292 then
 293 .B dump-runlisp-image
 294 will show Lisp implementation's noise immediately,
 295 without waiting to see whether it succeeds or fails.
 296 .
 297 .SS "Operation"
 298 The
 299 .B dump-runlisp-image
 300 program first determines a collection of
 301 .I selected
 302 Lisp implementations.
 303 If the
 304 .RB ` \-a '
 305 option is not set,
 306 then the selected Lisps are those named on the command line.
 307 If
 308 .RB ` \-a '
 309 is set,
 310 and the configuration contains a setting for
 311 .B dump
 312 in the
 313 .B @CONFIG
 314 section,
 315 then its (expanded) value is taken to be
 316 a list of Lisp implementation names
 317 separated by commas and/or one or more whitespace characters,
 318 and these named Lisp implementations are selected;
 319 if there is no
 320 .B dump
 321 setting, then
 322 .I all
 323 configured Lisp implementations which claim support for custom images
 324 \(en i.e., configuration sections with settings for
 325 .B run-script
 326 and
 327 .B image-file
 328 \(en are selected, and the
 329 .RB ` \-i '
 330 option is forced on.
 331 If the
 332 .RB ` \-i '
 333 option is set,
 334 then only those Lisp implementations which are actually installed
 335 are selected.
 336 .PP
 337 If necessary
 338 (see below),
 339 .B dump-runlisp-image
 340 invokes each selected Lisp in order to determine a
 341 .IR "version hash" .
 342 For each selected Lisp system,
 343 it constructs a command line,
 344 in the manner of
 345 .BR runlisp (1),
 346 to evaluate the expression resulting from expanding the
 347 .B lisp-version
 348 setting in the Lisp system's configuration section.
 349 It hashes the result,
 350 using a collision-resistant hash function
 351 (currently SHA256),
 352 to produce a string of hexadecimal digits which represents
 353 the versions of the various pieces of Lisp code which
 354 .I should
 355 be in the dumped image.
 356 The standard setting for
 357 .B lisp-version
 358 includes the Lisp implementation version string
 359 and the version of ASDF currently installed.
 360 (This step is skipped
 361 if it's not necessary to determine the Lisp system versions.
 362 In practice, this happens when the
 363 .RB ` \-r ',
 364 .RB ` \-R '
 365 and
 366 .RB ` \-U '
 367 options are all set.)
 368 .PP
 369 Having established the selected Lisps,
 370 and their version hashes,
 371 .B dump-runlisp-image
 372 proceeds to act on them:
 373 in the absence of the
 374 .RB ` \-r '
 375 option,
 376 it attempts to dump a custom image
 377 for each selected Lisp implementation,
 378 unless an image file already exists
 379 or the
 380 .RB ` \-f '
 381 option is set.
 382 (Note that
 383 .RB ` \-f '
 384 is an optimization of image dumping,
 385 and does not affect selection.)
 386 On the other hand, if
 387 .RB ` \-r '
 388 is set,
 389 then the custom image files of the selected Lisp implementations
 390 are deleted.
 391 .PP
 392 Next, if the
 393 .RB ` \-R '
 394 option is set,
 395 then all the images for Lisp implementations
 396 which are defined in the configuration
 397 but were
 398 .I not
 399 selected
 400 are deleted.
 401 .PP
 402 Finally, if the
 403 .RB ` \-U '
 404 option is set,
 405 then all files in the image directory
 406 which aren't recognized as being
 407 the custom image of some Lisp implementation
 408 are deleted.
 409 .PP
 410 If all of these operations are successfully performed
 411 then
 412 .B dump-runlisp-image
 413 exits with status 0;
 414 if there was a problem with the command line,
 415 or if any jobs fail,
 416 then it exits with status 127.
 417 .
 418 .\"--------------------------------------------------------------------------
 419 .
 420 .SH SEE ALSO
 421 .BR query-runlisp-config (1),
 422 .BR runlisp (1),
 423 .BR runlisp.conf (5).
 424 .
 425 .SH AUTHOR
 426 Mark Wooding, <mdw@distorted.org.uk>
 427 .
 428 .\"----- That's all, folks --------------------------------------------------