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