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         \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 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 .BI "\-O" "\fR, " "\-\-output=" output
 107 If
 108 .I output
 109 names a directory,
 110 then write images to that directory
 111 with their default names as specified in the configuration file.
 112 Otherwise,
 113 exactly one Lisp implementation must be explicitly named,
 114 the
 115 .RB ` \-R '
 116 and
 117 .RB `\-U '
 118 options must not be set,
 119 and
 120 the image is written to a file named
 121 .IR output .
 122 By default,
 123 images are written to the directory in which
 124 .BR runlisp (1)
 125 will look in when checking for custom images:
 126 run
 127 .B query-runlisp-config \-x@image-dir
 128 to see the default setting.
 129 .
 130 .TP
 131 .BR "\-R" ", " "\-\-remove-other"
 132 After processing the selected Lisp implementations,
 133 delete all of the image files corresponding to other Lisps
 134 defined in the configuration.
 135 Negate with
 136 .B +R
 137 or
 138 .BR \-\-no-remove-other .
 139 .
 140 .TP
 141 .BR "\-U" ", " "\-\-remove-unknown"
 142 After processing the selected Lisp implementations,
 143 delete all of the files in the image directory which
 144 .I aren't
 145 image files of a configured Lisp implementation.
 146 Negate with
 147 .B +U
 148 or
 149 .BR \-\-no-remove-unknown .
 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 be 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 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect "\fR]\fB:" var = value
 234 Assign
 235 .I value
 236 to the variable
 237 .I var
 238 in configuration section
 239 .IR sect ,
 240 or
 241 .B @CONFIG
 242 if no section is specified.
 243 The value is unexpandable,
 244 and overrides any similarly named setting
 245 from the configuration file(s).
 246 .
 247 .TP
 248 .BR "\-q" ", " "\-\-quiet"
 249 Don't print warning messages.
 250 This option may be repeated:
 251 each use reduces verbosity by one step,
 252 counteracting one
 253 .RB ` \-v '
 254 option.
 255 The default verbosity level is 1,
 256 which prints only warning measages.
 257 .
 258 .TP
 259 .BR "\-r" ", " "\-\-remove-image"
 260 Delete image files for the selected Lisp implementations,
 261 rather than dumping them.
 262 Negate with
 263 .B +r
 264 or
 265 .BR \-\-no-remove-image .
 266 .
 267 .TP
 268 .BR "\-v" ", " "\-\-verbose"
 269 Be more verbose about the process of creating images.
 270 Lisp implementations can be rather noisy:
 271 by default,
 272 .B dump-runlisp-image
 273 runs silently unless something goes wrong,
 274 in which case it prints the failed Lisp command line
 275 and its output.
 276 If you set
 277 .B \-v
 278 then
 279 .B dump-runlisp-image
 280 will show Lisp implementation's noise immediately,
 281 without waiting to see whether it succeeds or fails.
 282 .
 283 .SS "Operation"
 284 The
 285 .B dump-runlisp-image
 286 program first determines a collection of
 287 .I selected
 288 Lisp implementations.
 289 If the
 290 .RB ` \-a '
 291 option is not set,
 292 then the selected Lisps are those named on the command line.
 293 If
 294 .RB ` \-a '
 295 is set,
 296 and the configuration contains a setting for
 297 .B dump
 298 in the
 299 .B @CONFIG
 300 section,
 301 then its (expanded) value is taken to be
 302 a list of Lisp implementation names
 303 separated by commas and/or one or more whitespace characters,
 304 and these named Lisp implementations are selected;
 305 if there is no
 306 .B dump
 307 setting, then
 308 .I all
 309 configured Lisp implementations which claim support for custom images
 310 \(en i.e., configuration sections with settings for
 311 .B run-script
 312 and
 313 .B image-file
 314 \(en are selected, and the
 315 .RB ` \-i '
 316 option is forced on.
 317 If the
 318 .RB ` \-i '
 319 option is set,
 320 then only those Lisp implementations which are actually installed
 321 are selected.
 322 .PP
 323 Having established the selected Lisps,
 324 .B dump-runlisp-image
 325 proceeds to act on them:
 326 in the absence of the
 327 .RB ` \-r '
 328 option,
 329 it attempts to dump a custom image
 330 for each selected Lisp implementation,
 331 unless an image file already exists
 332 or the
 333 .RB ` \-f '
 334 option is set.
 335 (Note that
 336 .RB ` \-f '
 337 is an optimization of image dumping,
 338 and does not affect selection.)
 339 On the other hand, if
 340 .RB ` \-r '
 341 is set,
 342 then the custom image files of the selected Lisp implementations
 343 are deleted.
 344 .PP
 345 Next, if the
 346 .RB ` \-R '
 347 option is set,
 348 then all the images for Lisp implementations
 349 which are defined in the configuration
 350 but were
 351 .I not
 352 selected
 353 are deleted.
 354 .PP
 355 Finally, if the
 356 .RB ` \-U '
 357 option is set,
 358 then all files in the image directory
 359 which aren't recognized as being
 360 the custom image of some Lisp implementation
 361 are deleted.
 362 .PP
 363 If all of these operations are successfully performed
 364 then
 365 .B dump-runlisp-image
 366 exits with status 0;
 367 if there was a problem with the command line,
 368 or if any jobs fail,
 369 then it exits with status 127.
 370 .
 371 .\"--------------------------------------------------------------------------
 372 .
 373 .SH SEE ALSO
 374 .BR query-runlisp-config (1),
 375 .BR runlisp (1),
 376 .BR runlisp.conf (5).
 377 .
 378 .SH AUTHOR
 379 Mark Wooding, <mdw@distorted.org.uk>
 380 .
 381 .\"----- That's all, folks --------------------------------------------------