.\" -*-nroff-*-
.\"
.\" Manual for `runlisp' configuration files
.\"
.\" (c) 2020 Mark Wooding
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
.\"
.\" Runlisp is free software: you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" Runlisp is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Runlisp.  If not, see <https://www.gnu.org/licenses/>.
.
.ie t \{\
.  ds o \(bu
.  if \n(.g \{\
.    fam P
.    ev an-1
.    fam P
.    ev
.  \}
.\}
.el \{\
.  ds o o
.\}
.
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.ds .. \&.\|.\|.
.
.\"--------------------------------------------------------------------------
.TH runlisp.conf 5 "27 August 2020" "Mark Wooding"
.SH NAME
runlisp.conf \- configuration files for runlisp
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
.SS "Default configuration files"
By default, the
.B runlisp
programs read configuration from the following files.
(Note that if a
.RB ` \-c '
command-line option is given, then
these default files are
.I not
read.)
.TP
.B @etcdir@/runlisp.d/*.conf
If a directory named
.B @etcdir@/runlisp.d
exists,
then all of the files within
whose names end in
.RB ` .conf '
are read,
in ascending lexicographical order by name.
This directory name can be overridden by setting the
.B RUNLISP_SYSCONFIG_DIR
environment variable.
.TP
.B @etcdir@/runlisp.conf
The file named
.B @etcdir@/runlisp.conf
is read; the file must exist.
This filename can be overridden by setting the
.B RUNLISP_SYSCONFIG
environment variable.
.TP
.B ~/.runlisp.conf
If there is a file named
.B .runlisp.conf
in the user's home directory,
then it is read.
The home directory is determined to be
the value of the
.B HOME
environment variable, or, if that is not set,
the home directory associated with the process's real uid
in the system password database.
This filename can be overridden by setting the
.B RUNLISP_USERCONFIG
environment variable.
.TP
.B ~/.config/runlisp.conf
If there is a file named
.B runlisp.conf
in the user's XDG configuration directory,
then it is read.
The XDG configuration directory is determined to be the value of the
.B XDG_CONFIG_HOME
environment variable, or the
.B .config
directory in the user's home directory
(as determined above).
This filename can be overridden by setting the
.B RUNLISP_USERCONFIG
environment variable.
(Note, therefore, that this variable overrides
.I both
of the user configuration files.)
.
.SS "General syntax"
In summary,
a configuration file is structured as a collection of assignments
.I variable
.B =
.IR value ,
gathered into named sections by header lines
.BI [ section ]\fR.
.PP
Comments are indicated by a semicolon
.RB ` ; '
in the leftmost column,
and extend to the end of the line;
comments and lines consisting only of whiteapace are ignored
and have no effect whatever.
Semicolons not in the first column do
.I not
introduce comments,
and have no special meaning.
.PP
A
.I name
is a non-empty sequence of ASCII alphanumeric characters,
or the special constituent characters
.RB ` \- ',
.RB ` _ ',
.RB ` . ',
.RB ` / ',
.RB ` * ',
.RB ` + ',
.RB ` *% ',
or
.RB ` @ '.
For example,
.RB ` foo ',
.RB ` 12345 ',
.RB ` \-2.718 ',
.RB ` 113/355 ',
.RB ` image-dir ',
.RB ` @%IMAGEDIR ',
and
.RB ` *organa-solo* '
are all names, but
.RB ` foo:bar '
.RB ` happy? '
and
.RB ` $3.95 '
are not.
Names beginning with
.RB ` @ '
are reserved for use by the
.B runlisp
programs;
names beginning with
.RB ` % '
or
.RB ` @% '
are by convention private.
.PP
A
.I section header
is a line of the form
.IP
.BI [ section ]
.PP
where
.I section
is a name, as defined above.
There may be whitespace before and after the
.I name
or after the
.RB  ` ] '.
Section headers need not have distinct names.
Subsequent assignments are applied to the section called
.IR name ,
up until the next section header, or the end of the file.
Assignments prior to the first section header in a file
are applied to the
.B @CONFIG
section.
.PP
An
.I assignment
begins with a line of the form
.IP
.I variable
.B =
.I rest
.PP
where
.I variable
is a name, as defined above,
and it includes all subsequent
(non-empty, non-comment)
lines up to, but not including,
the next line which does
.I not
begin with whitespace or a semicolon,
or the end of the input file.
There may be space before or after the
.RB ` = '.
The
.I value
assigned consists of the text of the initial line following the
.RB ` = '
character
(shown as
.I rest
above),
together with the contents of the subsequent lines;
initial and trailing whitespace is removed from each piece,
and the (nonempty) pieces are joined,
separated by single spaces.
We say that an assignment
assigns a value to the variable
in some section \(en
namely, the section in which the assignment is applied.
.PP
For example,
consider the following file.
.IP
.ft B
.nf
long =
	one

	two
; this line is a comment
	; not a comment
	three

short = just a quick note
.fi
.ft P
.PP
Then
.B long
is assigned the value
.RB ` "one two ; not a comment three" ',
and
.B short
is assigned
.RB ` "just a quick note" '.
.PP
The assignments applied to a section
need not have distinct variable names.
Only the last assignment to a particular variable name in a section is
.IR effective ;
the earlier assignments are simply ignored.
If an effective assignment assigns a value to a variable in a section,
we say that the variable is
.I set
to that value in the section.
.
.SS "Lookup and inheritance"
A section may have zero or more
.I parent
sections.
.PP
The
.B @BUILTIN
and
.B @ENV
sections have no parents.
The
.B @COMMON
section has one parent, namely
.BR @BUILTIN .
.PP
If the variable
.B @parents
is set in a section other than one of those named above,
then it must consist of a space- and/or comma-separated list
of names,
which name the section's parents.
Currently, the parents need not be distinct,
though duplicates have no effect other than slowing down lookup.
The order in which parents are listed is not significant.
If
.B @parents
is not set in a section other than one of those named above,
then by default it has one parent, namely
.BR @COMMON .
.PP
It is currently possible to build a cyclic structure of parent links.
This is not recommended.
If lookup (explained below) detects a cycle
then it will report a fatal error,
but cycles may exist without being detected.
.PP
A variable is
.I "looked up"
in a section as follows.
.hP 1.
If there is an effective assignment
of a value to that variable in the section
then lookup finds that assignment.
.hP 2.
If the section has no parents,
then lookup fails.
.hP 3.
Otherwise, the variable is looked up in each of the section's parents.
If none of these lookups succeeds, then the lookup fails.
If all of the successful lookups found the
.I "same assignment"
(not just the same value!)\&
then lookup finds that assignment.
Otherwise, the lookup reports an error.
.
.SS "Expansion and word-splitting"
A value can be
.I expanded
relative to some home section,
and optionally split into words.
.PP
Not all values are
.IR expandable .
Values set by assignments in a configuration file are always expandable.
Values set on the command line \(en in
.B \-o
options \(en are not expandable.
Values in the
.B @ENV
section from environment variables (see below) are not expandable.
Some values set in the
.B @BUILTIN
section are expandable and some are not.
Applying expansion to a value that is not expandable
simply results in that same value, unchanged.
.PP
Applying expansion to an expandable value
produces a result string as follows.
The value is scanned from start to end.
.hP \*o
A backslash
.RB ` \e '
is discarded, but the immediately following character
is copied to the output without further inspection.
.hP \*o
A
.I variable substitution
takes the form
.BR ${ [ \c
.IB sect : \c
.RI ] var \c
.RB [ | \c
.IR filter ]\*(.. \c
.RB [ ? \c
.IR alt ] \c
.BR } .
A variable named
.I var
is looked up in the section named
.IR sect ,
or, if omitted, in the home section.
If the lookup succeeds,
then the value is expanded,
processed by the
.IR filter s
(explained below),
and appended to the output.
If the lookup failed,
and
.BI ? alt
is present,
then
.I alt
is expanded and appended to the output.
Otherwise,
if the lookup fails and there is no
.I alt
text, then an error is reported.
.IP
A filter
.B u
causes the expanded value to be converted to uppercase;
similarly,
.B l
causes the expanded value to be converted to lowercase.
A filter
.B q
causes a backslash to be inserted before each
backslash or double-quote character in the expanded value,
so that this can be used as part of a quoted Common Lisp string.
.hP \*o
A
.I conditional
takes the form
.BR $? [ \c
.IB sect : \c
.RI ] var \c
.BI { conseq \c
.RB [ | \c
.IR alt ] \c
.BR } .
A variable named
.I var
is looked up in the section named
.IR sect ,
or, if omitted, in the home section.
If the lookup succeeds, then
.I conseq
is expanded and appended to the output;
otherwise, if
.I alt
is present, then it is expanded and appended to the output;
otherwise, nothing happens.
.hP \*o
A dollar sign which doesn't introduce one of the forms above
is invalid, and a fatal error is reported.
.hP \*o
Any other characters are simply appended to the output.
.PP
Word-splitting is similar but more complex.
The result is not a string, but a sequence of strings.
At any given point in this procedure,
there may be a partially constructed word,
or there might not.
.hP \*o
Outside of quotes (see below),
whitespace serves to separate words.
When a whitespace character is encountered,
if there is a word under construction,
then it is finished and added to the output list;
otherwise it is simply ignored.
.hP \*o
If a backslash is encountered,
then a word is started if there is none currently under construction,
and the character following the backslash is added to the current word.
.hP \*o
If a single-quote character
.RB ` ' '
is encountered,
then a word is started if there is none currently under construction,
and
.I all
characters up to the next single quote
are added to the current word.
This includes double quotes, dollar signs, and backslashes.
(Neither of the two single quotes is appended to the current word.)
.hP \*o
If a double-quote character
.RB ` """" '
is encountered,
then a word is started if there is none currently under construction.
Until the next double quote is encountered,
whitespace and single quotes are treated literally,
and simply added to the current word;
backslashes can be used to escape characters,
such as double quotes,
as usual.
.hP \*o
If a
.BR $ -expansion
\(en a variable substitution or conditional (as described above) \(en
is encountered
and there is a current word under construction,
then the result of the
.BR $ -expansion
is appended to the current word.
If there is no current word,
then the variable value, or consequent or alternative text,
is subjected to word splitting in addition to expansion,
and the resulting words appended to the output sequence.
.hP \*o
If any other character is encountered,
then a word is started if there is none currently under construction,
and the character is appended to the current word.
.PP
One case which deserves attention:
if a
.BR $ -expansion
is encountered outside of a word,
so that the result is subject to word splitting,
then an error is reported if a new word is started
without there being whitespace between the closing brace of the
.BR $ -expansion
and the character which started the new word.
For example,
.IP
.B "bad = one ${x}two"
.PP
would be invalid in a word-splitting context.
.
.SS "Other special variables"
In every section, the section's name
is automatically assigned to the variable
.BR @name .
This variable
.I can
be overridden by an explicit assignment,
but this is not recommended.
.
.SS "Predefined variables in @BUILTIN"
The
.B @BUILTIN
section has no parents.
You should not override its settings in configuration files.
It holds a number of variables set by the
.B runlisp
programs.
.
.TP
.B @data-dir
The directory in which
.BR runlisp 's
auxiliary data files and scripts are located.
This is determined by the
.B RUNLISP_DATADIR
environment variable,
the
.B data-dir
variable in the
.B @CONFIG
section,
or a value determined at compile time.
.
.TP
.B @ecl-opt
The preferred option prefix for ECL, either
.RB ` \- '
or
.RB ` \-\- '.
(For some reason,
the ECL developers are changing
the way ECL recognizes command-line options,
because they think that the minor \(aesthetic improvement
is worth breaking everyone's scripts.)
This is determined by the
.B ecl-opt
variable in the
.B @CONFIG
section,
or a value determined at compile time.
.
.TP
.B @hash
Set by
.BR dump-runlisp-image (1)
to the hash
(a string of hexadecimal digits)
identifying the versions of the Lisp code included
\(en or to be included \(en
in a custom image.
This is constructed by hashing the result of evaluating the
.B lisp-version
expression in the system definition.
.
.TP
.B @image-dir
The directory in which
.B runlisp
looks for, and
.B dump-runlisp-image
stores, custom Lisp images.
This is determined by the
.B RUNLISP_IMAGEDIR
environment variable,
the
.B image-dir
variable in the
.B @CONFIG
section,
or a value determined at compile time.
.
.TP
.B @image-link
The well-known name of the image;
actually a symbolic link to the `real' image file,
whose name includes a hash
which identifies the versions of the Lisp code included in the image.
.
.TP
.B @image-new
Set by
.BR dump-runlisp-image (1)
to the filename that a
.B dump-image
command should create.
.RB ( dump-runlisp-image
will rename the image into place itself,
if the command completes successfully.)
.
.TP
.B @image-newlink
Set by
.BR dump-runlisp-image (1)
to the name to use for the updated symbolic link to the image file.
This is used internally,
and is not expected to be useful in Lisp system definitions.
.
.TP
.B @image-out
Set by
.BR dump-runlisp-image (1)
to the filename of the intended output image.
(Don't use this in
.B dump-image
commands: use
.B @image-new
instread.)
.
.TP
.B @script
Set by
.BR runlisp (1)
to the name of the script being invoked.
.
.TP
.B @tmp-dir
Set by
.BR dump-runlisp-image (1)
to be the name of a directory in which a
.B dump-image
command can put temporary files.
.
.SS "Environment variables in @ENV"
The
.B @ENV
section is special,
and is used to hold a copy of the system environment.
At startup,
it contains an assignment for every environment variable.
The
.B @ENV
section has no parents.
The values are not expandable.
It is possible to override
.B @ENV
settings in configuration files
or on the command line,
but this is not recommended.
.
.SS "The @COMMON section"
The
.B @COMMON section
is the default parent for nearly all other configuration sections
(the exceptions being
.B @BUILTIN
and
.BR @ENV ,
which have no parents, and
.B @COMMON
itself, whose parent is
.BR @BUILTIN ).
It is used in the provided configuration
to hold various common snippets of Lisp code and other settings,
but the
.B runlisp
programs themselves make no direct use of it.
.
.SS "Overall configuration in @CONFIG"
Variable settings in
.B @CONFIG
are consulted for various administrative reasons.
.PP
Because of the open-ended nature of this configuration mechanism,
users can easily invent new configuration variables
for any purpose they can imagine.
The following variables are used by the
.B runlisp
programs directly, or its default configuration.
All values are expanded before use;
the
.B @CONFIG
section's parent is
.BR @COMMON ,
as usual.
.
.TP
.B data-dir
The directory in which
.BR runlisp 's
auxiliary data files and scripts are located.
There is a hardcoded default
determined at compile-time,
which is probably correct.
Overridden by the
.B RUNLISP_DATADIR
environment variable.
Don't refer to this setting directly:
expand
.B @data-dir
from the
.B @BUILTIN
section instead.
.
.TP
.B dump
A comma-separated list of Lisp implementation names
which should have custom images dumped by
.BR "dump-runlisp-image \-a" .
The order is not especially significant.
The default is all of the configured implementations
which define a
.B dump-image
variable
and whose command can be found.
.
.TP
.B ecl-opt
The preferred option prefix for ECL, either
.RB ` \- '
or
.RB ` \-\- '.
There is a hardcoded default
determined at compile-time,
which was correct for the system on which
.B runlisp
was built.
Don't refer to this setting directly:
expand
.B @ecl-opt
from the
.B @BUILTIN
section instead.
.
.TP
.B image-dir
The directory in which
.B runlisp
looks for, and
.B dump-runlisp-image
stores, custom Lisp images.
Overridden by the
.B RUNLISP_IMAGEDIR
environment variable.
Don't refer to this setting directly:
expand
.B @image-dir
from the
.B @BUILTIN
section instead.
.
.TP
.B prefer
A comma-separated list of names of
.I preferred
Lisp implementations.
Overridden by the
.B RUNLISP_PREFER
environment variable.
.
.SS "Lisp implementation definitions"
A Lisp implementation is described to
.B runlisp
by a configuration section.
The section's name is used to refer to the implementation,
e.g., in
.BR runlisp 's
.B \-L
option,
or in the
.B dump
and
.B prefer
lists described above.
.PP
The following variable settings are used directly;
of course, a Lisp implementation definition may contain other settings
for internal purposes.
.
.TP
.B command
The name of the program used to invoke the Lisp implementation.
.BR dump-runlisp-image
looks to see whether this program is installed when invoked with the
.B \-i
option:
it will fail if there is no
.B command
setting.
It is also commonly
(but not universally)
used in the
.B run-script
and
.B dump-image
variables.
It's conventional to set this to
.B ${@ENV:FOO?foo}
so that the command name can be overridden from the environment.
.
.TP
.B dump-image
The complete command to use to dump a custom image
for this Lisp implementation.
The value is subjected to expansion and word-splitting before use.
It should write the newly created image to the file named by the
.B @image-new
setting in the
.B @BUILTIN
section.
.
.TP
.B image-file
The basename of the custom image file
(i.e., not containing any
.BR ` / '
characters)
to use when invoking this Lisp implementation.
.BR runlisp (1)
and
.BR dump-runlisp-image (1)
use the presence of this setting to decide
whether the implementation supports custom images.
.
.TP
.B image-path
The complete (but not necessarily absolute) pathname
of the custom image file for this Lisp implementation.
It is the (expanded) value of this variable
which is used by
.BR runlisp (1)
when it checks whether a custom image exists.
It's set to
.B ${@image-dir}/${image-file}
in the standard configuration file's
.B @COMMON
section,
and there is probably no need to override it;
.B @image-dir
is set in the
.B @BUILTIN
section \(en see above \(en and
.B image-file
must be set in this section
(or one of its ancestors)
before
.BR runlisp (1)
would not attempt to check for an image file.
.
.TP
.B run-script
The complete command to use
to get this Lisp implementation to execute a script.
The value is subjected to expansion and word-splitting before use.
The script name is available as
.B @script
in the
.B @BUILTIN
section \(en see above.
If a custom image is available, then
.B @image
is defined
(to the value
.BR t )
.I "in this section"
(not in
.BR @BUILTIN );
the full path to the image file to use is given by
.B ${image-path}
\(en see above.
.
.\"--------------------------------------------------------------------------
.
.SH SEE ALSO
.BR dump-runlisp-image (1),
.BR query-runlisp-config (1),
.BR runlisp (1).
.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------