3 .\" Manual for `runlisp' configuration files
5 .\" (c) 2020 Mark Wooding
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
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.
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
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/>.
40 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
43 .\"--------------------------------------------------------------------------
44 .TH runlisp.conf 5 "27 August 2020" "Mark Wooding"
46 runlisp.conf \- configuration files for runlisp
48 .\"--------------------------------------------------------------------------
51 .SS "Default configuration files"
54 programs read configuration from the following files.
57 command-line option is given, then
58 these default files are
62 .B @etcdir@/runlisp.d/*.conf
66 then all of the files within
70 in ascending lexicographical order by name.
71 This directory name can be overridden by setting the
72 .B RUNLISP_SYSCONFIG_DIR
75 .B @etcdir@/runlisp.conf
77 .B @etcdir@/runlisp.conf
78 is read; the file must exist.
79 This filename can be overridden by setting the
84 If there is a file named
86 in the user's home directory,
88 The home directory is determined to be
91 environment variable, or, if that is not set,
92 the home directory associated with the process's real uid
93 in the system password database.
94 This filename can be overridden by setting the
98 .B ~/.config/runlisp.conf
99 If there is a file named
101 in the user's XDG configuration directory,
103 The XDG configuration directory is determined to be the value of the
105 environment variable, or the
107 directory in the user's home directory
108 (as determined above).
109 This filename can be overridden by setting the
110 .B RUNLISP_USERCONFIG
111 environment variable.
112 (Note, therefore, that this variable overrides
114 of the user configuration files.)
118 a configuration file is structured as a collection of assignments
122 gathered into named sections by header lines
125 Comments are indicated by a semicolon
127 in the leftmost column,
128 and extend to the end of the line;
129 comments and lines consisting only of whiteapace are ignored
130 and have no effect whatever.
131 Semicolons not in the first column do
134 and have no special meaning.
138 is a non-empty sequence of ASCII alphanumeric characters,
139 or the special constituent characters
157 .RB ` *organa-solo* '
166 are reserved for use by the
173 are by convention private.
177 is a line of the form
183 is a name, as defined above.
184 There may be whitespace before and after the
188 Section headers need not have distinct names.
189 Subsequent assignments are applied to the section called
191 up until the next section header, or the end of the file.
192 Assignments prior to the first section header in a file
199 begins with a line of the form
207 is a name, as defined above,
208 and it includes all subsequent
209 (non-empty, non-comment)
210 lines up to, but not including,
211 the next line which does
213 begin with whitespace or a semicolon,
214 or the end of the input file.
215 There may be space before or after the
219 assigned consists of the text of the initial line following the
225 together with the contents of the subsequent lines;
226 initial and trailing whitespace is removed from each piece,
227 and the (nonempty) pieces are joined,
228 separated by single spaces.
229 We say that an assignment
230 assigns a value to the variable
232 namely, the section in which the assignment is applied.
235 consider the following file.
243 ; this line is a comment
247 short = just a quick note
253 is assigned the value
254 .RB ` "one two ; not a comment three" ',
257 .RB ` "just a quick note" '.
259 The assignments applied to a section
260 need not have distinct variable names.
261 Only the last assignment to a particular variable name in a section is
263 the earlier assignments are simply ignored.
264 If an effective assignment assigns a value to a variable in a section,
265 we say that the variable is
267 to that value in the section.
269 .SS "Lookup and inheritance"
270 A section may have zero or more
278 sections have no parents.
281 section has one parent, namely
286 is set in a section other than one of those named above,
287 then it must consist of a space- or comma-separated list
289 which name the section's parents.
290 Currently, the parents need not be distinct,
291 though duplicates have no effect other than slowing down lookup.
292 The order in which parents are listed is not significant.
295 is not set in a section other than one of those named above,
296 then by default it has one parent, namely
299 It is currently possible to build a cyclic structure of parent links.
300 This is not recommended.
301 If lookup (explained below) detects a cycle
302 then it will report a fatal error,
303 but cycles may exist without being detected.
307 in a section as follows.
309 If there is an effective assignment
310 of a value to that variable in the section
311 then lookup finds that assignment.
313 If the section has no parents,
316 Otherwise, the variable is looked up in each of the section's parents.
317 If none of these lookups succeeds, then the lookup fails.
318 If all of the successful lookups found the
320 (not just the same value!)
321 then lookup finds that assignment.
322 Otherwise, the lookup reports an error.
324 .SS "Expansion and word-splitting"
327 relative to some home section,
328 and optionally split into words.
332 Values set by assignments in a configuration file are always expandable.
333 Values set on the command line \(en in
335 options \(en are not expandable.
338 section from environment variables (see below) are not expandable.
339 Some values set in the
341 section are expandable and some are not.
342 Applying expansion to a value that is not expandable
343 simply results in that same value, unchanged.
345 Applying expansion to an expandable value
346 produces a result string as follows.
347 The value is scanned from start to end.
351 is discarded, but the immediately following character
352 is copied to the output without further inspection.
355 .I variable substitution
367 is looked up in the section named
369 or, if omitted, in the home section.
370 If the lookup succeeds,
371 then the value is expanded,
375 and appended to the output.
376 If the lookup failed,
382 is expanded and appended to the output.
384 if the lookup fails and there is no
386 text, then an error is reported.
390 causes the expanded value to be converted to uppercase;
393 causes the expanded value to be converted to lowercase.
396 causes a backslash to be inserted before each
397 backslash or double-quote character in the expanded value,
398 so that this can be used as part of a quoted Common Lisp string.
412 is looked up in the section named
414 or, if omitted, in the home section.
415 If the lookup succeeds, then
417 is expanded and appended to the output;
420 is present, then it is expanded and appended to the output;
421 otherwise, nothing happens.
423 A dollar sign which doesn't introduce one of the forms above
424 is invalid, and a fatal error is reported.
426 Any other characters are simply appended to the output.
428 Word-splitting is similar but more complex.
429 The result is not a string, but a sequence of strings.
430 At any given point in this procedure,
431 there may be a partially constructed word,
434 Outside of quotes (see below),
435 whitespace serves to separate words.
436 When a whitespace character is encountered,
437 if there is a word under construction,
438 then it is finished and added to the output list;
439 otherwise it is simply ignored.
441 If a backslash is encountered,
442 then a word is started if there is none currently under construction,
443 and the character following the backslash is added to the current word.
445 If a single-quote character
448 then a word is started if there is none currently under construction,
451 characters up to the next single quote
452 are added to the current word.
453 This includes double quotes, dollar signs, and backslashes.
454 (Neither of the two single quotes is appended to the current word.)
456 If a double-quote character
459 then a word is started if there is none currently under construction.
460 Until the next double quote is encountered,
461 whitespace and single quotes treated literally,
462 and simply added to the current word;
463 backslashes can be used to escape characters,
464 such as double quotes,
469 \(en a variable substitution or conditional (as described above) \(en
471 and there is a current word under construction,
472 then the result of the
474 is appended to the current word.
475 If there is no current word,
476 then the variable value, or consequent or alternative text,
477 is subjected to word splitting in addition to expansion,
478 and the resulting words appended to the output sequence.
480 If any other character is encountered,
481 then a word is started if there is none currently under construction,
482 and the character is appended to the current word.
484 One case which deserves attention:
487 is encountered outside of a word,
488 so that the result is subject to word splitting,
489 then an error is reported if a new word is started
490 without there being whitespace between the closing brace of the
492 and the character which started the new word.
495 .B "bad = one ${x}two"
497 would be invalid in a word-splitting context.
499 .SS "Other special variables"
500 In every section, the section's name
501 is automatically assigned to the variable
505 be overridden by an explicit assignment,
506 but this is not recommended.
508 .SS "Predefined variables in @BUILTIN"
511 Section has no parents.
512 You should not override its settings in configuration files.
513 it holds a number of variables set by the
519 The directory in which
521 auxiliary data files and scripts are located.
522 This is determined by the
524 environment variable,
530 or a value determined at compile time.
534 The preferred option prefix for ECL, either
539 the ECL developers are changing
540 the way ECL recognizes command-line options,
541 because they think that the minor aesthetic improvement
542 is worth breaking everyone's scripts.)
543 This is determined by the
548 or a value determined at compile time.
553 .BR dump-runlisp-image (1)
555 (a string of hexadecimal digits)
556 identifying the versions of the Lisp code included
557 \(en or to be included \(en
559 This is constructed by hashing the result of evaluating the
561 expression in the system definition.
565 The directory in which
568 .B dump-runlisp-image
569 stores, custom Lisp images.
570 This is determined by the
572 environment variable,
578 or a value determined at compile time.
582 The well-known name of the image;
583 actually a symbolic link to the `real' image file,
584 whose name includes a hash
585 which identifies the versions of the Lisp code included in the image.
590 .BR dump-runlisp-image (1)
591 to the filename that a
593 command should create.
594 .RB ( dump-runlisp-image
595 will rename the image into place itself,
596 if the command completes successfully.)
601 .BR dump-runlisp-image (1)
602 to the name to use for the updated symbolic link to the image file.
603 This is used internally,
604 and is not expected to be useful in Lisp system definitions.
609 .BR dump-runlisp-image (1)
610 to the filename of the intended output image.
621 to the name of the script being invoked.
626 .BR dump-runlisp-image (1)
627 to be the name of a directory in which a
629 command can put temporary files.
631 .SS "Environment variables in @ENV"
635 and is used to hold a copy of the system environment.
637 it contains an assignment for every environment variable.
640 section has no parents.
641 The values are not expandable.
642 It is possible to override
644 settings in configuration files
645 or on the command line,
646 but this is not recommended.
648 .SS "The @COMMON section"
651 is the default parent for nearly all other configuration sections
652 (the exceptions being
656 which have no parents, and
658 itself, whose parent is
660 It is used in the provided configuration
661 to hold various common snippets of Lisp code and other settings,
664 programs themselves make no direct use of it.
666 .SS "Overall configuration in @CONFIG"
669 are consulted for various administrative reasons.
671 Because of the open-ended nature of this configuration mechanism,
672 users can easily invent new configuration variables
673 for any purpose they can imagine.
674 The following variables are used by the
676 programs directly, or its default configuration.
677 All values are expanded before use;
686 The directory in which
688 auxiliary data files and scripts are located.
689 There is a hardcoded default
690 determined at compile-time,
691 which is probably correct.
694 environment variable.
695 Don't refer to this setting directly:
704 A comma-separated list of Lisp implementation names
705 which should have custom images dumped by
706 .BR "dump-runlisp-image \-a" .
707 The order is not especially significant.
708 The default is all of the configured implementations
712 and whose command can be found.
716 The preferred option prefix for ECL, either
720 There is a hardcoded default
721 determined at compile-time,
722 which was correct for the system on which
725 Don't refer to this setting directly:
734 The directory in which
737 .B dump-runlisp-image
738 stores, custom Lisp images.
741 environment variable.
742 Don't refer to this setting directly:
751 A comma-separated list of names of
753 Lisp implementations,
756 environment variable.
758 .SS "Lisp implementation definitions"
759 A Lisp implementation is described to
761 by a configuration section.
762 The section's name is used to refer to the implementation,
771 lists described above.
773 The following variable settings are used directly;
774 of course, a Lisp implementation definition may contain other settings
775 for internal purposes.
779 The name of the program used to invoke the Lisp implementation.
780 .BR dump-runlisp-image
781 looks to see whether this program is installed when invoked with the
784 it will fail if there is no
788 (but not universally)
794 It's conventional to set this to
796 so that the command name can be overridden from the environment.
800 The complete command to use to dump a custom image
801 for this Lisp implementation.
802 The value is subjected to expansion and word-splitting before use.
803 It should write the newly created image to the file named by the
811 The basename of the custom image file
812 (i.e., not containing any
815 to use when invoking this Lisp implementation.
818 .BR dump-runlisp-image (1)
819 use the presence of this setting to decide
820 whether the implementation supports custom images.
824 The complete (but not necessarily absolute) pathname
825 of the custom image file for this Lisp implementation.
826 It is the (expanded) value of this variable
829 when it checks whether a custom image exists.
831 .B ${@image-dir}/${image-file}
832 in the standard configuration file's
835 and there is probably no need to override it;
843 section \(en see above \(en and
845 must be set in this section
846 (or one of its ancestors)
849 would not attempt to check for an image file.
853 The complete command to use
854 to get this Lisp implementation to execute a script.
855 The value is subjected to expansion and word-splitting before use.
856 The script name is available as
860 section \(en see above.
861 If a custom image is available, then
869 the full path to the image file to use is given by
873 .\"--------------------------------------------------------------------------
876 .BR dump-runlisp-image (1),
877 .BR query-runlisp-config (1),
881 Mark Wooding, <mdw@distorted.org.uk>
883 .\"----- That's all, folks --------------------------------------------------