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