X-Git-Url: https://git.distorted.org.uk/~mdw/runlisp/blobdiff_plain/8996f767e047eefa8af4d01b1434b54f4c169b79:/runlisp.conf.5..10427eb21d77a0edeb2f17e434515b91b420cdfb:/runlisp.conf.5.in diff --git a/runlisp.conf.5 b/runlisp.conf.5.in similarity index 65% rename from runlisp.conf.5 rename to runlisp.conf.5.in index e7773de..64cbe38 100644 --- a/runlisp.conf.5 +++ b/runlisp.conf.5.in @@ -49,6 +49,71 @@ 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 @@ -208,8 +273,7 @@ A section may have zero or more sections. .PP The -.BR @BUILTIN , -.BR @CONFIG , +.B @BUILTIN and .B @ENV sections have no parents. @@ -433,6 +497,15 @@ For example, .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 @BULITIN @@ -441,6 +514,7 @@ 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 @@ -455,6 +529,7 @@ variable in the .B @CONFIG section, or a value determined at compile time. +. .TP .B @ecl-opt The preferred option prefix for ECL, either @@ -472,6 +547,7 @@ variable in the .B @CONFIG section, or a value determined at compile time. +. .TP .B @image-dir The directory in which @@ -488,6 +564,7 @@ variable in the .B @CONFIG section, or a value determined at compile time. +. .TP .B @image-new Set by @@ -498,6 +575,7 @@ command should create. .RB ( dump-runlisp-image will rename the image into place itself, if the command completes successfully.) +. .TP .B @image-out Set by @@ -508,11 +586,13 @@ to the filename of the intended output 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 @@ -521,19 +601,249 @@ to be the name of a directory in which a .B dump-image command can put temporary files. . -.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, +.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. . -.SH BUGS -.hP \*o +.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 +.RB ( @image-dir +is set in the +.N @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),