chiark - git - mdw - runlisp/blob - runlisp.conf.5.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for `runlisp' configuration files
   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 runlisp.conf 5 "27 August 2020" "Mark Wooding"
  46 .SH NAME
  47 runlisp.conf \- configuration files for runlisp
  48 .
  49 .\"--------------------------------------------------------------------------
  50 .SH DESCRIPTION
  51 .
  52 .SS "Default configuration files"
  53 By default, the
  54 .B runlisp
  55 programs read configuration from the following files.
  56 (Note that if a
  57 .RB ` \-c '
  58 command-line option is given, then
  59 these default files are
  60 .I not
  61 read.)
  62 .TP
  63 .B @etcdir@/runlisp.d/*.conf
  64 If a directory named
  65 .B @etcdir@/runlisp.d
  66 exists,
  67 then all of the files within
  68 whose names end in
  69 .RB ` .conf '
  70 are read,
  71 in ascending lexicographical order by name.
  72 This directory name can be overridden by setting the
  73 .B RUNLISP_SYSCONFIG_DIR
  74 environment variable.
  75 .TP
  76 .B @etcdir@/runlisp.conf
  77 The file named
  78 .B @etcdir@/runlisp.conf
  79 is read; the file must exist.
  80 This filename can be overridden by setting the
  81 .B RUNLISP_SYSCONFIG
  82 environment variable.
  83 .TP
  84 .B ~/.runlisp.conf
  85 If there is a file named
  86 .B .runlisp.conf
  87 in the user's home directory,
  88 then it is read.
  89 The home directory is determined to be
  90 the value of the
  91 .B HOME
  92 environment variable, or, if that is not set,
  93 the home directory associated with the process's real uid
  94 in the system password database.
  95 This filename can be overridden by setting the
  96 .B RUNLISP_USERCONFIG
  97 environment variable.
  98 .TP
  99 .B ~/.config/runlisp.conf
 100 If there is a file named
 101 .B runlisp.conf
 102 in the user's XDG configuration directory,
 103 then it is read.
 104 The XDG configuration directory is determined to be the value of the
 105 .B XDG_CONFIG_HOME
 106 environment variable, or the
 107 .B .config
 108 directory in the user's home directory
 109 (as determined above).
 110 This filename can be overridden by setting the
 111 .B RUNLISP_USERCONFIG
 112 environment variable.
 113 (Note, therefore, that this variable overrides
 114 .I both
 115 of the user configuration files.)
 116 .
 117 .SS "General syntax"
 118 In summary,
 119 a configuration file is structured as a collection of assignments
 120 .I variable
 121 .B =
 122 .IR value ,
 123 gathered into named sections by header lines
 124 .BI [ section ]\fR.
 125 .PP
 126 Comments are indicated by a semicolon
 127 .RB ` ; '
 128 in the leftmost column,
 129 and extend to the end of the line;
 130 comments and lines consisting only of whiteapace are ignored
 131 and have no effect whatever.
 132 Semicolons not in the first column do
 133 .I not
 134 introduce comments,
 135 and have no special meaning.
 136 .PP
 137 A
 138 .I name
 139 is a non-empty sequence of ASCII alphanumeric characters,
 140 or the special constituent characters
 141 .RB ` \- ',
 142 .RB ` _ ',
 143 .RB ` . ',
 144 .RB ` / ',
 145 .RB ` * ',
 146 .RB ` + ',
 147 .RB ` *% ',
 148 or
 149 .RB ` @ '.
 150 For example,
 151 .RB ` foo ',
 152 .RB ` 12345 ',
 153 .RB ` \-2.718 ',
 154 .RB ` 113/355 ',
 155 .RB ` image-dir ',
 156 .RB ` @%IMAGEDIR ',
 157 and
 158 .RB ` *organa-solo* '
 159 are all names, but
 160 .RB ` foo:bar '
 161 .RB ` happy? '
 162 and
 163 .RB ` $3.95 '
 164 are not.
 165 Names beginning with
 166 .RB ` @ '
 167 are reserved for use by the
 168 .B runlisp
 169 programs;
 170 names beginning with
 171 .RB ` % '
 172 or
 173 .RB ` @% '
 174 are by convention private.
 175 .PP
 176 A
 177 .I section header
 178 is a line of the form
 179 .IP
 180 .BI [ section ]
 181 .PP
 182 where
 183 .I section
 184 is a name, as defined above.
 185 There may be whitespace before and after the
 186 .I name
 187 or after the
 188 .RB  ` ] '.
 189 Section headers need not have distinct names.
 190 Subsequent assignments are applied to the section called
 191 .IR name ,
 192 up until the next section header, or the end of the file.
 193 Assignments prior to the first section header in a file
 194 are applied to the
 195 .B @CONFIG
 196 section.
 197 .PP
 198 An
 199 .I assignment
 200 begins with a line of the form
 201 .IP
 202 .I variable
 203 .B =
 204 .I rest
 205 .PP
 206 where
 207 .I variable
 208 is a name, as defined above,
 209 and it includes all subsequent
 210 (non-empty, non-comment)
 211 lines up to, but not including,
 212 the next line which does
 213 .I not
 214 begin with whitespace or a semicolon,
 215 or the end of the input file.
 216 There may be space before or after the
 217 .RB ` = '.
 218 The
 219 .I value
 220 assigned consists of the text of the initial line following the
 221 .RB ` = '
 222 character
 223 (shown as
 224 .I rest
 225 above),
 226 together with the contents of the subsequent lines;
 227 initial and trailing whitespace is removed from each piece,
 228 and the (nonempty) pieces are joined,
 229 separated by single spaces.
 230 We say that an assignment
 231 assigns a value to the variable
 232 in some section \(en
 233 namely, the section in which the assignment is applied.
 234 .PP
 235 For example,
 236 consider the following file.
 237 .IP
 238 .ft B
 239 .nf
 240 long =
 241         one
 242
 243         two
 244 ; this line is a comment
 245         ; not a comment
 246         three
 247
 248 short = just a quick note
 249 .fi
 250 .ft P
 251 .PP
 252 Then
 253 .B long
 254 is assigned the value
 255 .RB ` "one two ; not a comment three" ',
 256 and
 257 .B short
 258 is assigned
 259 .RB ` "just a quick note" '.
 260 .PP
 261 The assignments applied to a section
 262 need not have distinct variable names.
 263 Only the last assignment to a particular variable name in a section is
 264 .IR effective ;
 265 the earlier assignments are simply ignored.
 266 If an effective assignment assigns a value to a variable in a section,
 267 we say that the variable is
 268 .I set
 269 to that value in the section.
 270 .
 271 .SS "Lookup and inheritance"
 272 A section may have zero or more
 273 .I parent
 274 sections.
 275 .PP
 276 The
 277 .B @BUILTIN
 278 and
 279 .B @ENV
 280 sections have no parents.
 281 The
 282 .B @COMMON
 283 section has one parent, namely
 284 .BR @BUILTIN .
 285 .PP
 286 If the variable
 287 .B @parents
 288 is set in a section other than one of those named above,
 289 then it must consist of a space- and/or comma-separated list
 290 of names,
 291 which name the section's parents.
 292 Currently, the parents need not be distinct,
 293 though duplicates have no effect other than slowing down lookup.
 294 The order in which parents are listed is not significant.
 295 If
 296 .B @parents
 297 is not set in a section other than one of those named above,
 298 then by default it has one parent, namely
 299 .BR @COMMON .
 300 .PP
 301 It is currently possible to build a cyclic structure of parent links.
 302 This is not recommended.
 303 If lookup (explained below) detects a cycle
 304 then it will report a fatal error,
 305 but cycles may exist without being detected.
 306 .PP
 307 A variable is
 308 .I "looked up"
 309 in a section as follows.
 310 .hP 1.
 311 If there is an effective assignment
 312 of a value to that variable in the section
 313 then lookup finds that assignment.
 314 .hP 2.
 315 If the section has no parents,
 316 then lookup fails.
 317 .hP 3.
 318 Otherwise, the variable is looked up in each of the section's parents.
 319 If none of these lookups succeeds, then the lookup fails.
 320 If all of the successful lookups found the
 321 .I "same assignment"
 322 (not just the same value!)\&
 323 then lookup finds that assignment.
 324 Otherwise, the lookup reports an error.
 325 .
 326 .SS "Expansion and word-splitting"
 327 A value can be
 328 .I expanded
 329 relative to some home section,
 330 and optionally split into words.
 331 .PP
 332 Not all values are
 333 .IR expandable .
 334 Values set by assignments in a configuration file are always expandable.
 335 Values set on the command line \(en in
 336 .B \-o
 337 options \(en are not expandable.
 338 Values in the
 339 .B @ENV
 340 section from environment variables (see below) are not expandable.
 341 Some values set in the
 342 .B @BUILTIN
 343 section are expandable and some are not.
 344 Applying expansion to a value that is not expandable
 345 simply results in that same value, unchanged.
 346 .PP
 347 Applying expansion to an expandable value
 348 produces a result string as follows.
 349 The value is scanned from start to end.
 350 .hP \*o
 351 A backslash
 352 .RB ` \e '
 353 is discarded, but the immediately following character
 354 is copied to the output without further inspection.
 355 .hP \*o
 356 A
 357 .I variable substitution
 358 takes the form
 359 .BR ${ [ \c
 360 .IB sect : \c
 361 .RI ] var \c
 362 .RB [ | \c
 363 .IR filter ]\*(.. \c
 364 .RB [ ? \c
 365 .IR alt ] \c
 366 .BR } .
 367 A variable named
 368 .I var
 369 is looked up in the section named
 370 .IR sect ,
 371 or, if omitted, in the home section.
 372 If the lookup succeeds,
 373 then the value is expanded,
 374 processed by the
 375 .IR filter s
 376 (explained below),
 377 and appended to the output.
 378 If the lookup failed,
 379 and
 380 .BI ? alt
 381 is present,
 382 then
 383 .I alt
 384 is expanded and appended to the output.
 385 Otherwise,
 386 if the lookup fails and there is no
 387 .I alt
 388 text, then an error is reported.
 389 .IP
 390 A filter
 391 .B u
 392 causes the expanded value to be converted to uppercase;
 393 similarly,
 394 .B l
 395 causes the expanded value to be converted to lowercase.
 396 A filter
 397 .B q
 398 causes a backslash to be inserted before each
 399 backslash or double-quote character in the expanded value,
 400 so that this can be used as part of a quoted Common Lisp string.
 401 .hP \*o
 402 A
 403 .I conditional
 404 takes the form
 405 .BR $? [ \c
 406 .IB sect : \c
 407 .RI ] var \c
 408 .BI { conseq \c
 409 .RB [ | \c
 410 .IR alt ] \c
 411 .BR } .
 412 A variable named
 413 .I var
 414 is looked up in the section named
 415 .IR sect ,
 416 or, if omitted, in the home section.
 417 If the lookup succeeds, then
 418 .I conseq
 419 is expanded and appended to the output;
 420 otherwise, if
 421 .I alt
 422 is present, then it is expanded and appended to the output;
 423 otherwise, nothing happens.
 424 .hP \*o
 425 A dollar sign which doesn't introduce one of the forms above
 426 is invalid, and a fatal error is reported.
 427 .hP \*o
 428 Any other characters are simply appended to the output.
 429 .PP
 430 Word-splitting is similar but more complex.
 431 The result is not a string, but a sequence of strings.
 432 At any given point in this procedure,
 433 there may be a partially constructed word,
 434 or there might not.
 435 .hP \*o
 436 Outside of quotes (see below),
 437 whitespace serves to separate words.
 438 When a whitespace character is encountered,
 439 if there is a word under construction,
 440 then it is finished and added to the output list;
 441 otherwise it is simply ignored.
 442 .hP \*o
 443 If a backslash is encountered,
 444 then a word is started if there is none currently under construction,
 445 and the character following the backslash is added to the current word.
 446 .hP \*o
 447 If a single-quote character
 448 .RB ` ' '
 449 is encountered,
 450 then a word is started if there is none currently under construction,
 451 and
 452 .I all
 453 characters up to the next single quote
 454 are added to the current word.
 455 This includes double quotes, dollar signs, and backslashes.
 456 (Neither of the two single quotes is appended to the current word.)
 457 .hP \*o
 458 If a double-quote character
 459 .RB ` """" '
 460 is encountered,
 461 then a word is started if there is none currently under construction.
 462 Until the next double quote is encountered,
 463 whitespace and single quotes are treated literally,
 464 and simply added to the current word;
 465 backslashes can be used to escape characters,
 466 such as double quotes,
 467 as usual.
 468 .hP \*o
 469 If a
 470 .BR $ -expansion
 471 \(en a variable substitution or conditional (as described above) \(en
 472 is encountered
 473 and there is a current word under construction,
 474 then the result of the
 475 .BR $ -expansion
 476 is appended to the current word.
 477 If there is no current word,
 478 then the variable value, or consequent or alternative text,
 479 is subjected to word splitting in addition to expansion,
 480 and the resulting words appended to the output sequence.
 481 .hP \*o
 482 If any other character is encountered,
 483 then a word is started if there is none currently under construction,
 484 and the character is appended to the current word.
 485 .PP
 486 One case which deserves attention:
 487 if a
 488 .BR $ -expansion
 489 is encountered outside of a word,
 490 so that the result is subject to word splitting,
 491 then an error is reported if a new word is started
 492 without there being whitespace between the closing brace of the
 493 .BR $ -expansion
 494 and the character which started the new word.
 495 For example,
 496 .IP
 497 .B "bad = one ${x}two"
 498 .PP
 499 would be invalid in a word-splitting context.
 500 .
 501 .SS "Other special variables"
 502 In every section, the section's name
 503 is automatically assigned to the variable
 504 .BR @name .
 505 This variable
 506 .I can
 507 be overridden by an explicit assignment,
 508 but this is not recommended.
 509 .
 510 .SS "Predefined variables in @BUILTIN"
 511 The
 512 .B @BUILTIN
 513 section has no parents.
 514 You should not override its settings in configuration files.
 515 It holds a number of variables set by the
 516 .B runlisp
 517 programs.
 518 .
 519 .TP
 520 .B @data-dir
 521 The directory in which
 522 .BR runlisp 's
 523 auxiliary data files and scripts are located.
 524 This is determined by the
 525 .B RUNLISP_DATADIR
 526 environment variable,
 527 the
 528 .B data-dir
 529 variable in the
 530 .B @CONFIG
 531 section,
 532 or a value determined at compile time.
 533 .
 534 .TP
 535 .B @ecl-opt
 536 The preferred option prefix for ECL, either
 537 .RB ` \- '
 538 or
 539 .RB ` \-\- '.
 540 (For some reason,
 541 the ECL developers are changing
 542 the way ECL recognizes command-line options,
 543 because they think that the minor \(aesthetic improvement
 544 is worth breaking everyone's scripts.)
 545 This is determined by the
 546 .B ecl-opt
 547 variable in the
 548 .B @CONFIG
 549 section,
 550 or a value determined at compile time.
 551 .
 552 .TP
 553 .B @hash
 554 Set by
 555 .BR dump-runlisp-image (1)
 556 to the hash
 557 (a string of hexadecimal digits)
 558 identifying the versions of the Lisp code included
 559 \(en or to be included \(en
 560 in a custom image.
 561 This is constructed by hashing the result of evaluating the
 562 .B lisp-version
 563 expression in the system definition.
 564 .
 565 .TP
 566 .B @image-dir
 567 The directory in which
 568 .B runlisp
 569 looks for, and
 570 .B dump-runlisp-image
 571 stores, custom Lisp images.
 572 This is determined by the
 573 .B RUNLISP_IMAGEDIR
 574 environment variable,
 575 the
 576 .B image-dir
 577 variable in the
 578 .B @CONFIG
 579 section,
 580 or a value determined at compile time.
 581 .
 582 .TP
 583 .B @image-link
 584 The well-known name of the image;
 585 actually a symbolic link to the `real' image file,
 586 whose name includes a hash
 587 which identifies the versions of the Lisp code included in the image.
 588 .
 589 .TP
 590 .B @image-new
 591 Set by
 592 .BR dump-runlisp-image (1)
 593 to the filename that a
 594 .B dump-image
 595 command should create.
 596 .RB ( dump-runlisp-image
 597 will rename the image into place itself,
 598 if the command completes successfully.)
 599 .
 600 .TP
 601 .B @image-newlink
 602 Set by
 603 .BR dump-runlisp-image (1)
 604 to the name to use for the updated symbolic link to the image file.
 605 This is used internally,
 606 and is not expected to be useful in Lisp system definitions.
 607 .
 608 .TP
 609 .B @image-out
 610 Set by
 611 .BR dump-runlisp-image (1)
 612 to the filename of the intended output image.
 613 (Don't use this in
 614 .B dump-image
 615 commands: use
 616 .B @image-new
 617 instread.)
 618 .
 619 .TP
 620 .B @script
 621 Set by
 622 .BR runlisp (1)
 623 to the name of the script being invoked.
 624 .
 625 .TP
 626 .B @tmp-dir
 627 Set by
 628 .BR dump-runlisp-image (1)
 629 to be the name of a directory in which a
 630 .B dump-image
 631 command can put temporary files.
 632 .
 633 .SS "Environment variables in @ENV"
 634 The
 635 .B @ENV
 636 section is special,
 637 and is used to hold a copy of the system environment.
 638 At startup,
 639 it contains an assignment for every environment variable.
 640 The
 641 .B @ENV
 642 section has no parents.
 643 The values are not expandable.
 644 It is possible to override
 645 .B @ENV
 646 settings in configuration files
 647 or on the command line,
 648 but this is not recommended.
 649 .
 650 .SS "The @COMMON section"
 651 The
 652 .B @COMMON section
 653 is the default parent for nearly all other configuration sections
 654 (the exceptions being
 655 .B @BUILTIN
 656 and
 657 .BR @ENV ,
 658 which have no parents, and
 659 .B @COMMON
 660 itself, whose parent is
 661 .BR @BUILTIN ).
 662 It is used in the provided configuration
 663 to hold various common snippets of Lisp code and other settings,
 664 but the
 665 .B runlisp
 666 programs themselves make no direct use of it.
 667 .
 668 .SS "Overall configuration in @CONFIG"
 669 Variable settings in
 670 .B @CONFIG
 671 are consulted for various administrative reasons.
 672 .PP
 673 Because of the open-ended nature of this configuration mechanism,
 674 users can easily invent new configuration variables
 675 for any purpose they can imagine.
 676 The following variables are used by the
 677 .B runlisp
 678 programs directly, or its default configuration.
 679 All values are expanded before use;
 680 the
 681 .B @CONFIG
 682 section's parent is
 683 .BR @COMMON ,
 684 as usual.
 685 .
 686 .TP
 687 .B data-dir
 688 The directory in which
 689 .BR runlisp 's
 690 auxiliary data files and scripts are located.
 691 There is a hardcoded default
 692 determined at compile-time,
 693 which is probably correct.
 694 Overridden by the
 695 .B RUNLISP_DATADIR
 696 environment variable.
 697 Don't refer to this setting directly:
 698 expand
 699 .B @data-dir
 700 from the
 701 .B @BUILTIN
 702 section instead.
 703 .
 704 .TP
 705 .B dump
 706 A comma-separated list of Lisp implementation names
 707 which should have custom images dumped by
 708 .BR "dump-runlisp-image \-a" .
 709 The order is not especially significant.
 710 The default is all of the configured implementations
 711 which define a
 712 .B dump-image
 713 variable
 714 and whose command can be found.
 715 .
 716 .TP
 717 .B ecl-opt
 718 The preferred option prefix for ECL, either
 719 .RB ` \- '
 720 or
 721 .RB ` \-\- '.
 722 There is a hardcoded default
 723 determined at compile-time,
 724 which was correct for the system on which
 725 .B runlisp
 726 was built.
 727 Don't refer to this setting directly:
 728 expand
 729 .B @ecl-opt
 730 from the
 731 .B @BUILTIN
 732 section instead.
 733 .
 734 .TP
 735 .B image-dir
 736 The directory in which
 737 .B runlisp
 738 looks for, and
 739 .B dump-runlisp-image
 740 stores, custom Lisp images.
 741 Overridden by the
 742 .B RUNLISP_IMAGEDIR
 743 environment variable.
 744 Don't refer to this setting directly:
 745 expand
 746 .B @image-dir
 747 from the
 748 .B @BUILTIN
 749 section instead.
 750 .
 751 .TP
 752 .B prefer
 753 A comma-separated list of names of
 754 .I preferred
 755 Lisp implementations.
 756 Overridden by the
 757 .B RUNLISP_PREFER
 758 environment variable.
 759 .
 760 .SS "Lisp implementation definitions"
 761 A Lisp implementation is described to
 762 .B runlisp
 763 by a configuration section.
 764 The section's name is used to refer to the implementation,
 765 e.g., in
 766 .BR runlisp 's
 767 .B \-L
 768 option,
 769 or in the
 770 .B dump
 771 and
 772 .B prefer
 773 lists described above.
 774 .PP
 775 The following variable settings are used directly;
 776 of course, a Lisp implementation definition may contain other settings
 777 for internal purposes.
 778 .
 779 .TP
 780 .B command
 781 The name of the program used to invoke the Lisp implementation.
 782 .BR dump-runlisp-image
 783 looks to see whether this program is installed when invoked with the
 784 .B \-i
 785 option:
 786 it will fail if there is no
 787 .B command
 788 setting.
 789 It is also commonly
 790 (but not universally)
 791 used in the
 792 .B run-script
 793 and
 794 .B dump-image
 795 variables.
 796 It's conventional to set this to
 797 .B ${@ENV:FOO?foo}
 798 so that the command name can be overridden from the environment.
 799 .
 800 .TP
 801 .B dump-image
 802 The complete command to use to dump a custom image
 803 for this Lisp implementation.
 804 The value is subjected to expansion and word-splitting before use.
 805 It should write the newly created image to the file named by the
 806 .B @image-new
 807 setting in the
 808 .B @BUILTIN
 809 section.
 810 .
 811 .TP
 812 .B image-file
 813 The basename of the custom image file
 814 (i.e., not containing any
 815 .BR ` / '
 816 characters)
 817 to use when invoking this Lisp implementation.
 818 .BR runlisp (1)
 819 and
 820 .BR dump-runlisp-image (1)
 821 use the presence of this setting to decide
 822 whether the implementation supports custom images.
 823 .
 824 .TP
 825 .B image-path
 826 The complete (but not necessarily absolute) pathname
 827 of the custom image file for this Lisp implementation.
 828 It is the (expanded) value of this variable
 829 which is used by
 830 .BR runlisp (1)
 831 when it checks whether a custom image exists.
 832 It's set to
 833 .B ${@image-dir}/${image-file}
 834 in the standard configuration file's
 835 .B @COMMON
 836 section,
 837 and there is probably no need to override it;
 838 .B @image-dir
 839 is set in the
 840 .B @BUILTIN
 841 section \(en see above \(en and
 842 .B image-file
 843 must be set in this section
 844 (or one of its ancestors)
 845 before
 846 .BR runlisp (1)
 847 would not attempt to check for an image file.
 848 .
 849 .TP
 850 .B run-script
 851 The complete command to use
 852 to get this Lisp implementation to execute a script.
 853 The value is subjected to expansion and word-splitting before use.
 854 The script name is available as
 855 .B @script
 856 in the
 857 .B @BUILTIN
 858 section \(en see above.
 859 If a custom image is available, then
 860 .B @image
 861 is defined
 862 (to the value
 863 .BR t )
 864 .I "in this section"
 865 (not in
 866 .BR @BUILTIN );
 867 the full path to the image file to use is given by
 868 .B ${image-path}
 869 \(en see above.
 870 .
 871 .\"--------------------------------------------------------------------------
 872 .
 873 .SH SEE ALSO
 874 .BR dump-runlisp-image (1),
 875 .BR query-runlisp-config (1),
 876 .BR runlisp (1).
 877 .
 878 .SH AUTHOR
 879 Mark Wooding, <mdw@distorted.org.uk>
 880 .
 881 .\"----- That's all, folks --------------------------------------------------