mdw@git.distorted.org.uk Git - 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 , \h'.16667m'
  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 a 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 is assigned
 258 .RB ` "just a quick note" '.
 259 .PP
 260 The assignments applied to a section
 261 need not have distinct variable names.
 262 Only the last assignment to a particular variable name in a section is
 263 .IR effective ;
 264 the earlier assignments are simply ignored.
 265 If an effective assignment assigns a value to a variable in a section,
 266 we say that the variable is
 267 .I set
 268 to that value in the section.
 269 .
 270 .SS "Lookup and inheritance"
 271 A section may have zero or more
 272 .I parent
 273 sections.
 274 .PP
 275 The
 276 .B @BUILTIN
 277 and
 278 .B @ENV
 279 sections have no parents.
 280 The
 281 .B @CONFIG
 282 section has one parent, namely
 283 .BR @BUILTIN .
 284 .PP
 285 If the variable
 286 .B @parents
 287 is set in a section other than one of those named above,
 288 then it must consist of a space- or comma-separated list
 289 of names,
 290 which name the section's parents.
 291 Currently, the parents need not be distinct,
 292 though duplicates have no effect other than slowing down lookup.
 293 The order in which parents are listed is not significant.
 294 If
 295 .B @parents
 296 is not set in a section other than one of those named above,
 297 then by default it has one parent, namely
 298 .BR @COMMON .
 299 .PP
 300 It is currently possible to build a cyclic structure of parent links.
 301 This is not recommended.
 302 If lookup (explained below) detects a cycle
 303 then it will report a fatal error,
 304 but cycles may exist without being detected.
 305 .PP
 306 A variable is
 307 .I "looked up"
 308 in a section as follows.
 309 .hP 1.
 310 If there is an effective assignment
 311 of a value to that variable in the section
 312 then lookup finds that assignment.
 313 .hP 2.
 314 If the section has no parents,
 315 then lookup fails.
 316 .hP 3.
 317 Otherwise, the variable is looked up in each of the section's parents.
 318 If none of these lookups succeeds, then the lookup fails.
 319 If all of the successful lookups found the
 320 .I "same assignment"
 321 (not just the same value!)
 322 then lookup finds that assignment.
 323 Otherwise, the lookup reports an error.
 324 .
 325 .SS "Expansion and word-splitting"
 326 A value can be
 327 .I expanded
 328 relative to some home section,
 329 and optionally split into words.
 330 .PP
 331 Not all values are
 332 .IR expandable .
 333 Values set by assignments in a configuration file are always expandable.
 334 Values set on the command line \(en in
 335 .B \-o
 336 options \(en are not expandable.
 337 Values in the
 338 .B @ENV
 339 section from environment variables (see below) are not expandable.
 340 Some values set in the
 341 .B @BUILTIN
 342 section are expandable and some are not.
 343 Applying expansion to a value that is not expandable
 344 simply results in that same value, unchanged.
 345 .PP
 346 Applying expansion to an expandable value
 347 produces a result string as follows.
 348 The value is scanned from start to end.
 349 .hP \*o
 350 A backslash
 351 .RB ` \e '
 352 is discarded, but the immediately following character
 353 is copied to the output without further inspection.
 354 .hP \*o
 355 A
 356 .I variable substitution
 357 takes the form
 358 .BR ${ [ \c
 359 .IB sect : \c
 360 .RI ] var \c
 361 .RB [ | \c
 362 .IR filter ]... \c
 363 .RB [ ? \c
 364 .IR alt ] \c
 365 .BR } .
 366 A variable named
 367 .I var
 368 is looked up in the section named
 369 .IR sect ,
 370 or, if omitted, in the home section.
 371 If the lookup succeeds,
 372 then the value is expanded,
 373 processed by the
 374 .IR filter s
 375 (explained below),
 376 and appended to the output.
 377 If the lookup failed,
 378 and
 379 .BI ? alt
 380 is present,
 381 then
 382 .I alt
 383 is expanded and appended to the output.
 384 Otherwise,
 385 if the lookup fails and there is no
 386 .I alt
 387 text, then an error is reported.
 388 .IP
 389 A filter
 390 .B u
 391 causes the expanded value to be converted to uppercase;
 392 similarly,
 393 .B l
 394 causes the expanded value to be converted to lowercase.
 395 A filter
 396 .B q
 397 causes a backslash to be inserted before each
 398 backslash or double-quote character in the expanded value,
 399 so that this can be used as part of a quoted Common Lisp string.
 400 .hP \*o
 401 A
 402 .I conditional
 403 takes the form
 404 .BR $? [ \c
 405 .IB sect : \c
 406 .RI ] var \c
 407 .BI { conseq \c
 408 .RB [ | \c
 409 .IR alt ] \c
 410 .BR } .
 411 A variable named
 412 .I var
 413 is looked up in the section named
 414 .IR sect ,
 415 or, if omitted, in the home section.
 416 If the lookup succeeds, then
 417 .I conseq
 418 is expanded and appended to the output;
 419 otherwise, if
 420 .I alt
 421 is present, then it is expanded and appended to the output;
 422 otherwise, nothing happens.
 423 .hP \*o
 424 A dollar sign which doesn't introduce one of the forms above
 425 is invalid, and a fatal error is reported.
 426 .hP \*o
 427 Any other characters are simply appended to the output.
 428 .PP
 429 Word-splitting is similar but more complex.
 430 The result is not a string, but a sequence of strings.
 431 At any given point in this procedure,
 432 there may be a partially constructed word,
 433 or there might not.
 434 .hP \*o
 435 Outside of quotes (see below),
 436 whitespace serves to separate words.
 437 When a whitespace character is encountered,
 438 if there is a word under construction,
 439 then it is finished and added to the output list;
 440 otherwise it is simply ignored.
 441 .hP \*o
 442 If a backslash is encountered,
 443 then a word is started if there is none currently under construction,
 444 and the character following the backslash is added to the current word.
 445 .hP \*o
 446 If a single-quote character
 447 .RB ` ' '
 448 is encountered,
 449 then a word is started if there is none currently under construction,
 450 and
 451 .I all
 452 characters up to the next single quote
 453 are added to the current word.
 454 This includes double quotes, dollar signs, and backslashes.
 455 (Neither of the two single quotes is appended to the current word.)
 456 .hP \*o
 457 If a double-quote character
 458 .RB ` """" '
 459 is encountered,
 460 then a word is started if there is none currently under construction.
 461 Until the next double quote is encountered,
 462 whitespace and single quotes treated literally,
 463 and simply added to the current word;
 464 backslashes can be used to escape characters,
 465 such as double quotes,
 466 as usual.
 467 .hP \*o
 468 If a
 469 .BR $ -expansion
 470 \(en a variable substitution or conditional (as described above) \(en
 471 is encountered
 472 and there is a current word under construction,
 473 then the result of the
 474 .BR $ -expansion
 475 is appended to the current word.
 476 If there is no current word,
 477 then the variable value, or consequent or alternative text,
 478 is subjected to word splitting in addition to expansion,
 479 and the resulting words appended to the output sequence.
 480 .hP \*o
 481 If any other character is encountered,
 482 then a word is started if there is none currently under construction,
 483 and the character is appended to the current word.
 484 .PP
 485 One case which deserves attention:
 486 if a
 487 .BR $ -expansion
 488 is encountered outside of a word,
 489 so that the result is subject to word splitting,
 490 then an error is reported if a new word is started
 491 without there being whitespace between the closing brace of the
 492 .B $ -expansion
 493 and the character which started the new word.
 494 For example,
 495 .IP
 496 .B "bad = one ${x}two"
 497 .PP
 498 would be invalid in a word-splitting context.
 499 .
 500 .SS "Other special variables"
 501 In every section, the section's name
 502 is automatically assigned to the variable
 503 .BR @name .
 504 This variable
 505 .I can
 506 be overridden by an explicit assignment,
 507 but this is not recommended.
 508 .
 509 .SS "Predefined variables in @BUILTIN"
 510 The
 511 .B @BULITIN
 512 Section has no parents.
 513 You should not override its settings in configuration files.
 514 it holds a number of variables set by the
 515 .B runlisp
 516 programs.
 517 .
 518 .TP
 519 .B @data-dir
 520 The directory in which
 521 .BR runlisp 's
 522 auxiliary data files and scripts are located.
 523 This is determined by the
 524 .B RUNLISP_DATADIR
 525 environment variable,
 526 the
 527 .B data-dir
 528 variable in the
 529 .B @CONFIG
 530 section,
 531 or a value determined at compile time.
 532 .
 533 .TP
 534 .B @ecl-opt
 535 The preferred option prefix for ECL, either
 536 .RB ` \- '
 537 or
 538 .RB ` \-\- '.
 539 (For some reason,
 540 the ECL developers are changing
 541 the way ECL recognizes command-line options,
 542 because they think that the minor aesthetic improvement
 543 is worth breaking everyone's scripts.)
 544 This is determined by the
 545 .B ecl-opt
 546 variable in the
 547 .B @CONFIG
 548 section,
 549 or a value determined at compile time.
 550 .
 551 .TP
 552 .B @image-dir
 553 The directory in which
 554 .B runlisp
 555 looks for, and
 556 .B dump-runlisp-image
 557 stores, custom Lisp images.
 558 This is determined by the
 559 .B RUNLISP_IMAGEDIR
 560 environment variable,
 561 the
 562 .B image-dir
 563 variable in the
 564 .B @CONFIG
 565 section,
 566 or a value determined at compile time.
 567 .
 568 .TP
 569 .B @image-new
 570 Set by
 571 .BR dump-runlisp-image (1)
 572 to the filename that a
 573 .B dump-image
 574 command should create.
 575 .RB ( dump-runlisp-image
 576 will rename the image into place itself,
 577 if the command completes successfully.)
 578 .
 579 .TP
 580 .B @image-out
 581 Set by
 582 .BR dump-runlisp-image (1)
 583 to the filename of the intended output image.
 584 (Don't use this in
 585 .B dump-image
 586 commands: use
 587 .B @image-new
 588 instread.)
 589 .
 590 .TP
 591 .B @script
 592 Set by
 593 .BR runlisp (1)
 594 to the name of the script being invoked.
 595 .
 596 .TP
 597 .B @tmp-dir
 598 Set by
 599 .BR dump-runlisp-image (1)
 600 to be the name of a directory in which a
 601 .B dump-image
 602 command can put temporary files.
 603 .
 604 .SS "Environment variables in @ENV"
 605 The
 606 .B @ENV
 607 section is special,
 608 and is used to hold a copy of the system environment.
 609 At startup,
 610 it contains an assignment for every environment variable.
 611 The
 612 .B @ENV
 613 section has no parents.
 614 The values are not expandable.
 615 It is possible to override
 616 .B @ENV
 617 settings in configuration files
 618 or on the command line,
 619 but this is not recommended.
 620 .
 621 .SS "The @COMMON section"
 622 The
 623 .B @COMMON section
 624 is the default parent for nearly all other configuration sections
 625 (the exceptions being
 626 .B @BUILTIN
 627 and
 628 .BR @ENV ,
 629 which have no parents, and
 630 .B @COMMON
 631 itself, whose parent is
 632 .BR @BUILTIN ).
 633 It is used in the provided configuration
 634 to hold various common snippets of Lisp code and other settings,
 635 but the
 636 .B runlisp
 637 programs themselves make no direct use of it.
 638 .
 639 .SS "Overall configuration in @CONFIG"
 640 Variable settings in
 641 .B @CONFIG
 642 are consulted for various administrative reasons.
 643 .PP
 644 Because of the open-ended nature of this configuration mechanism,
 645 users can easily invent new configuration variables
 646 for any purpose they can imagine.
 647 The following variables are used by the
 648 .B runlisp
 649 programs directly, or its default configuration.
 650 All values are expanded before use;
 651 the
 652 .B @CONFIG
 653 section's parent is
 654 .BR @COMMON ,
 655 as usual.
 656 .
 657 .TP
 658 .B data-dir
 659 The directory in which
 660 .BR runlisp 's
 661 auxiliary data files and scripts are located.
 662 There is a hardcoded default
 663 determined at compile-time,
 664 which is probably correct.
 665 Overridden by the
 666 .B RUNLISP_DATADIR
 667 environment variable.
 668 Don't refer to this setting directly:
 669 expand
 670 .B @data-dir
 671 from the
 672 .B @BUILTIN
 673 section instead.
 674 .
 675 .TP
 676 .B dump
 677 A comma-separated list of Lisp implementation names
 678 which should have custom images dumped by
 679 .BR "dump-runlisp-image \-a" .
 680 The order is not especially significant.
 681 The default is all of the configured implementations
 682 which define a
 683 .B dump-image
 684 variable
 685 and whose command can be found.
 686 .
 687 .TP
 688 .B ecl-opt
 689 The preferred option prefix for ECL, either
 690 .RB ` \- '
 691 or
 692 .RB ` \-\- '.
 693 There is a hardcoded default
 694 determined at compile-time,
 695 which was correct for the system on which
 696 .B runlisp
 697 was built.
 698 Don't refer to this setting directly:
 699 expand
 700 .B @ecl-opt
 701 from the
 702 .B @BUILTIN
 703 section instead.
 704 .
 705 .TP
 706 .B @image-dir
 707 The directory in which
 708 .B runlisp
 709 looks for, and
 710 .B dump-runlisp-image
 711 stores, custom Lisp images.
 712 Overridden by the
 713 .B RUNLISP_IMAGEDIR
 714 environment variable.
 715 Don't refer to this setting directly:
 716 expand
 717 .B @image-dir
 718 from the
 719 .B @BUILTIN
 720 section instead.
 721 .
 722 .TP
 723 .B prefer
 724 A comma-separated list of names of
 725 .I preferred
 726 Lisp implementations,
 727 Overridden by the
 728 .B RUNLISP_PREFER
 729 environment variable.
 730 .
 731 .SS "Lisp implementation definitions"
 732 A Lisp implementation is described to
 733 .B runlisp
 734 by a configuration section.
 735 The section's name is used to refer to the implementation,
 736 e.g., in
 737 .BR runlisp 's
 738 .B \-L
 739 option,
 740 or in the
 741 .B dump
 742 and
 743 .B prefer
 744 lists described above.
 745 .PP
 746 The following variable settings are used directly;
 747 of course, a Lisp implementation definition may contain other settings
 748 for internal purposes.
 749 .
 750 .TP
 751 .B command
 752 The name of the program used to invoke the Lisp implementation.
 753 .BR dump-runlisp-image
 754 looks to see whether this program is installed when invoked with the
 755 .B \-i
 756 option:
 757 it will fail if there is no
 758 .B command
 759 setting.
 760 It is also commonly
 761 (but not universally)
 762 used in the
 763 .B run-script
 764 and
 765 .B dump-image
 766 variables.
 767 It's conventional to set this to
 768 .B ${@ENV:FOO?foo}
 769 so that the command name can be overridden from the environment.
 770 .
 771 .TP
 772 .B dump-image
 773 The complete command to use to dump a custom image
 774 for this Lisp implementation.
 775 The value is subjected to expansion and word-splitting before use.
 776 It should write the newly created image to the file named by the
 777 .B @image-new
 778 setting in the
 779 .B @BUILTIN
 780 section.
 781 .
 782 .TP
 783 .B image-file
 784 The basename of the custom image file
 785 (i.e., not containing any
 786 .BR ` / '
 787 characters)
 788 to use when invoking this Lisp implementation.
 789 .BR runlisp (1)
 790 and
 791 .BR dump-runlisp-image (1)
 792 use the presence of this setting to decide
 793 whether the implementation supports custom images.
 794 .
 795 .TP
 796 .B image-path
 797 The complete (but not necessarily absolute) pathname
 798 of the custom image file for this Lisp implementation.
 799 It is the (expanded) value of this variable
 800 which is used by
 801 .BR runlisp (1)
 802 when it checks whether a custom image exists.
 803 It's set to
 804 .B ${@image-dir}/${image-file}
 805 in the standard configuration file's
 806 .B @COMMON
 807 section,
 808 and there is probably no need to override it;
 809 .B @image-dir
 810 is set in the
 811 .B @BUILTIN
 812 section
 813 .RB ( @image-dir
 814 is set in the
 815 .N @BUILTIN
 816 section \(en see above \(en and
 817 .B image-file
 818 must be set in this section
 819 (or one of its ancestors)
 820 before
 821 .BR runlisp (1)
 822 would not attempt to check for an image file.
 823 .
 824 .TP
 825 .B run-script
 826 The complete command to use
 827 to get this Lisp implementation to execute a script.
 828 The value is subjected to expansion and word-splitting before use.
 829 The script name is available as
 830 .B @script
 831 in the
 832 .B @BUILTIN
 833 section \(en see above.
 834 If a custom image is available, then
 835 .B @image
 836 is defined
 837 (to the value
 838 .BR t )
 839 .I "in this section"
 840 (not in
 841 .BR @BUILTIN );
 842 the full path to the image file to use is given by
 843 .B ${image-path}
 844 \(en see above.
 845 .
 846 .\"--------------------------------------------------------------------------
 847 .
 848 .SH SEE ALSO
 849 .BR dump-runlisp-image (1),
 850 .BR query-runlisp-config (1),
 851 .BR runlisp (1).
 852 .
 853 .SH AUTHOR
 854 Mark Wooding, <mdw@distorted.org.uk>
 855 .
 856 .\"----- That's all, folks --------------------------------------------------