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
44 .\"--------------------------------------------------------------------------
45 .TH runlisp.conf 5 "27 August 2020" "Mark Wooding"
47 runlisp.conf \- configuration files for runlisp
49 .\"--------------------------------------------------------------------------
52 .SS "Default configuration files"
55 programs read configuration from the following files.
58 command-line option is given, then
59 these default files are
63 .B @etcdir@/runlisp.d/*.conf
67 then all of the files within
71 in ascending lexicographical order by name.
72 This directory name can be overridden by setting the
73 .B RUNLISP_SYSCONFIG_DIR
76 .B @etcdir@/runlisp.conf
78 .B @etcdir@/runlisp.conf
79 is read; the file must exist.
80 This filename can be overridden by setting the
85 If there is a file named
87 in the user's home directory,
89 The home directory is determined to be
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
99 .B ~/.config/runlisp.conf
100 If there is a file named
102 in the user's XDG configuration directory,
104 The XDG configuration directory is determined to be the value of the
106 environment variable, or the
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
115 of the user configuration files.)
119 a configuration file is structured as a collection of assignments
123 gathered into named sections by header lines
126 Comments are indicated by a semicolon
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
135 and have no special meaning.
139 is a non-empty sequence of ASCII alphanumeric characters,
140 or the special constituent characters
158 .RB ` *organa-solo* '
167 are reserved for use by the
174 are by convention private.
178 is a line of the form
184 is a name, as defined above.
185 There may be whitespace before and after the
189 Section headers need not have distinct names.
190 Subsequent assignments are applied to the section called
192 up until the next section header, or the end of the file.
193 Assignments prior to the first section header in a file
200 begins with a line of the form
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
214 begin with whitespace or a semicolon,
215 or the end of the input file.
216 There may be space before or after the
220 assigned consists of the text of the initial line following the
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
233 namely, the section in which the assignment is applied.
236 consider the following file.
244 ; this line is a comment
248 short = just a quick note
254 is assigned the value
255 .RB ` "one two ; not a comment three" ',
258 .RB ` "just a quick note" '.
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
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
268 to that value in the section.
270 .SS "Lookup and inheritance"
271 A section may have zero or more
279 sections have no parents.
282 section has one parent, namely
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
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.
296 is not set in a section other than one of those named above,
297 then by default it has one parent, namely
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.
308 in a section as follows.
310 If there is an effective assignment
311 of a value to that variable in the section
312 then lookup finds that assignment.
314 If the section has no parents,
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
321 (not just the same value!)
322 then lookup finds that assignment.
323 Otherwise, the lookup reports an error.
325 .SS "Expansion and word-splitting"
328 relative to some home section,
329 and optionally split into words.
333 Values set by assignments in a configuration file are always expandable.
334 Values set on the command line \(en in
336 options \(en are not expandable.
339 section from environment variables (see below) are not expandable.
340 Some values set in the
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.
346 Applying expansion to an expandable value
347 produces a result string as follows.
348 The value is scanned from start to end.
352 is discarded, but the immediately following character
353 is copied to the output without further inspection.
356 .I variable substitution
368 is looked up in the section named
370 or, if omitted, in the home section.
371 If the lookup succeeds,
372 then the value is expanded,
376 and appended to the output.
377 If the lookup failed,
383 is expanded and appended to the output.
385 if the lookup fails and there is no
387 text, then an error is reported.
391 causes the expanded value to be converted to uppercase;
394 causes the expanded value to be converted to lowercase.
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.
413 is looked up in the section named
415 or, if omitted, in the home section.
416 If the lookup succeeds, then
418 is expanded and appended to the output;
421 is present, then it is expanded and appended to the output;
422 otherwise, nothing happens.
424 A dollar sign which doesn't introduce one of the forms above
425 is invalid, and a fatal error is reported.
427 Any other characters are simply appended to the output.
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,
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.
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.
446 If a single-quote character
449 then a word is started if there is none currently under construction,
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.)
457 If a double-quote character
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,
470 \(en a variable substitution or conditional (as described above) \(en
472 and there is a current word under construction,
473 then the result of the
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.
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.
485 One case which deserves attention:
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
493 and the character which started the new word.
496 .B "bad = one ${x}two"
498 would be invalid in a word-splitting context.
500 .SS "Other special variables"
501 In every section, the section's name
502 is automatically assigned to the variable
506 be overridden by an explicit assignment,
507 but this is not recommended.
509 .SS "Predefined variables in @BUILTIN"
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
520 The directory in which
522 auxiliary data files and scripts are located.
523 This is determined by the
525 environment variable,
531 or a value determined at compile time.
535 The preferred option prefix for ECL, either
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
549 or a value determined at compile time.
554 .BR dump-runlisp-image (1)
556 (a string of hexadecimal digits)
557 identifying the versions of the Lisp code included
558 \(en or to be included \(en
560 This is constructed by hashing the result of evaluating the
562 expression in the system definition.
566 The directory in which
569 .B dump-runlisp-image
570 stores, custom Lisp images.
571 This is determined by the
573 environment variable,
579 or a value determined at compile time.
583 The well-known name of the image;
584 actually a symbolic link to the `real' image file,
585 whose name includes a hash
586 which identifies the versions of the Lisp code included in the image.
591 .BR dump-runlisp-image (1)
592 to the filename that a
594 command should create.
595 .RB ( dump-runlisp-image
596 will rename the image into place itself,
597 if the command completes successfully.)
602 .BR dump-runlisp-image (1)
603 to the name to use for the updated symbolic link to the image file.
604 This is used internally,
605 and is not expected to be useful in Lisp system definitions.
610 .BR dump-runlisp-image (1)
611 to the filename of the intended output image.
622 to the name of the script being invoked.
627 .BR dump-runlisp-image (1)
628 to be the name of a directory in which a
630 command can put temporary files.
632 .SS "Environment variables in @ENV"
636 and is used to hold a copy of the system environment.
638 it contains an assignment for every environment variable.
641 section has no parents.
642 The values are not expandable.
643 It is possible to override
645 settings in configuration files
646 or on the command line,
647 but this is not recommended.
649 .SS "The @COMMON section"
652 is the default parent for nearly all other configuration sections
653 (the exceptions being
657 which have no parents, and
659 itself, whose parent is
661 It is used in the provided configuration
662 to hold various common snippets of Lisp code and other settings,
665 programs themselves make no direct use of it.
667 .SS "Overall configuration in @CONFIG"
670 are consulted for various administrative reasons.
672 Because of the open-ended nature of this configuration mechanism,
673 users can easily invent new configuration variables
674 for any purpose they can imagine.
675 The following variables are used by the
677 programs directly, or its default configuration.
678 All values are expanded before use;
687 The directory in which
689 auxiliary data files and scripts are located.
690 There is a hardcoded default
691 determined at compile-time,
692 which is probably correct.
695 environment variable.
696 Don't refer to this setting directly:
705 A comma-separated list of Lisp implementation names
706 which should have custom images dumped by
707 .BR "dump-runlisp-image \-a" .
708 The order is not especially significant.
709 The default is all of the configured implementations
713 and whose command can be found.
717 The preferred option prefix for ECL, either
721 There is a hardcoded default
722 determined at compile-time,
723 which was correct for the system on which
726 Don't refer to this setting directly:
735 The directory in which
738 .B dump-runlisp-image
739 stores, custom Lisp images.
742 environment variable.
743 Don't refer to this setting directly:
752 A comma-separated list of names of
754 Lisp implementations,
757 environment variable.
759 .SS "Lisp implementation definitions"
760 A Lisp implementation is described to
762 by a configuration section.
763 The section's name is used to refer to the implementation,
772 lists described above.
774 The following variable settings are used directly;
775 of course, a Lisp implementation definition may contain other settings
776 for internal purposes.
780 The name of the program used to invoke the Lisp implementation.
781 .BR dump-runlisp-image
782 looks to see whether this program is installed when invoked with the
785 it will fail if there is no
789 (but not universally)
795 It's conventional to set this to
797 so that the command name can be overridden from the environment.
801 The complete command to use to dump a custom image
802 for this Lisp implementation.
803 The value is subjected to expansion and word-splitting before use.
804 It should write the newly created image to the file named by the
812 The basename of the custom image file
813 (i.e., not containing any
816 to use when invoking this Lisp implementation.
819 .BR dump-runlisp-image (1)
820 use the presence of this setting to decide
821 whether the implementation supports custom images.
825 The complete (but not necessarily absolute) pathname
826 of the custom image file for this Lisp implementation.
827 It is the (expanded) value of this variable
830 when it checks whether a custom image exists.
832 .B ${@image-dir}/${image-file}
833 in the standard configuration file's
836 and there is probably no need to override it;
844 section \(en see above \(en and
846 must be set in this section
847 (or one of its ancestors)
850 would not attempt to check for an image file.
854 The complete command to use
855 to get this Lisp implementation to execute a script.
856 The value is subjected to expansion and word-splitting before use.
857 The script name is available as
861 section \(en see above.
862 If a custom image is available, then
870 the full path to the image file to use is given by
874 .\"--------------------------------------------------------------------------
877 .BR dump-runlisp-image (1),
878 .BR query-runlisp-config (1),
882 Mark Wooding, <mdw@distorted.org.uk>
884 .\"----- That's all, folks --------------------------------------------------