X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/runlisp/blobdiff_plain/8996f767e047eefa8af4d01b1434b54f4c169b79:/runlisp.1..10427eb21d77a0edeb2f17e434515b91b420cdfb:/runlisp.1.in

diff --git a/runlisp.1 b/runlisp.1.in
similarity index 65%
rename from runlisp.1
rename to runlisp.1.in
index 51d470a..00b06fb 100644
--- a/runlisp.1
+++ b/runlisp.1.in
@@ -49,15 +49,14 @@ runlisp \- run Common Lisp programs as scripts
 .SH SYNOPSIS
 .
 .B runlisp
-.RB [ \-CDEnqv ]
-.RB [ \-I
-.IR imagedir ]
-.RB [ \-L
-.IB sys , sys , \fR...]
-.RB [ \-P
-.IB sys , sys , \fR...]
+.RI [ options ]
+.RB [ \-\- ]
+.I script
+.RI [ arguments
+\&...]
 .br
-\h'8n'
+.B runlisp
+.RI [ options ]
 .RB [ \-e
 .IR form  ]
 .RB [ \-l
@@ -65,9 +64,25 @@ runlisp \- run Common Lisp programs as scripts
 .RB [ \-p
 .IR form  ]
 .RB [ \-\- ]
-.RI [ script ]
 .RI [ arguments
 \&...]
+.PP
+where
+.I options
+is
+.br
+	\&
+.RB [ \-CDEnqv ]
+.RB [ +DEn ]
+.RB [ \-L
+.IB sys , sys , \fR...]
+.RB [ \-c
+.IR conf ]
+.RB [ \-o
+.RI [ sect \c
+.BR : ] \c
+.IB var = \c
+.IR value ]
 .
 .\"--------------------------------------------------------------------------
 .SH DESCRIPTION
@@ -84,114 +99,37 @@ It can be used in build scripts
 to invoke a Common Lisp system,
 e.g., to build a standalone program.
 .
-.SS "Supported Common Lisp implementations"
-The following Lisp implementations are currently supported.
-.TP
-.B "abcl"
-Armed Bear Common Lisp.
-.TP
-.B "ccl"
-Clozure Common Lisp.
-.TP
-.B "clisp"
-GNU CLisp.
-.TP
-.B "cmucl"
-Carnegie\(enMellon University Common Lisp.
-.TP
-.B "ecl"
-Embeddable Common Lisp.
-.TP
-.B "sbcl"
-Steel Bank Common Lisp.
-.PP
-The
-.B runlisp
-program expects, by default,
-to be able to run a Lisp system
-as a program with the same name,
-found by searching as directed by the
-.B PATH
-environment variable.
-This can be overridden by setting an environment variable,
-with the same name but in
-.IR "upper case" ,
-to the actual name \(en
-either a bare filename to be searched for on the
-.BR PATH ,
-or a pathname containing a
-.RB ` / ',
-relative to the working directory or absolute,
-to the program.
-Note that the entire variable value is used as the program name:
-it's not possible to provide custom arguments to a Lisp system
-using this mechanism.
-If you want to do that,
-you must write a shell script to do the necessary work,
-and point the environment variable
-(or the
-.BR PATH )
-at your script.
-.
 .SS "Options"
 Options are read from the command line, as usual,
-but also from a number of other sources;
-these are, in order:
-.hP \*o
-If a
-.I script
-is named,
-and the script's second line contains a
+but also (by default) from the script's second line,
+following a
 .RB ` @RUNLISP: '
-marker,
-then text following the marker is parsed as options.
-.hP \*o
-If files named
-.B ~/.runlisprc
-and/or
-.B ~/.config/runlisprc
-exist,
-then their contents are parsed as options.
-.hP \*o
-If an environment variable
-.B RUNLISP_OPTIONS
-is defined,
-then its contents is parsed as options.
-.PP
-A simple quoting and escaping system is implemented
-to allow spaces and other special characters
-to be included in argument words
-in the script, configuration files, and environment variable.
-The details of all of this are given in the section
+marker: see
 .B Operation
-below.
+below for the details.
 .
 .PP
 The options accepted are as follows.
 .
 .TP
-.B "\-\-help"
+.BR "\-h" ", " "\-\-help"
 Write a synopsis of
-.BR runlisp 's
+.BR query-runlisp-config 's
 command-line syntax
 and a description of the command-line options
 to standard output
 and immediately exit with status 0.
 .
 .TP
-.B "\-\-version"
+.BR "\-V" ", " "\-\-version"
 Write
-.BR runlisp 's
+.BR query-runlisp-config 's
 version number
 to standard output
 and immediately exit with status 0.
 .
 .TP
-.B "\-C"
-Clear the list of preferred Lisp implementations.
-.
-.TP
-.B "\-D"
+.BR "\-D" ", " "\-\-vanilla-image"
 Don't check for a custom Lisp image.
 Usually,
 .B runlisp
@@ -205,29 +143,33 @@ There's not usually any good reason to prefer the vanilla image,
 except for performance comparisons, or debugging
 .B runlisp
 itself.
+Negate with
+.B +D
+or
+.BR \-\-no-vanilla-image .
 .
 .TP
-.B "\-E"
+.BR "\-E" ", " "\-\-command-line-only"
 Don't read embedded options from the
 second line of the
 .I script
 file.
+Negate with
+.B +E
+or
+.BR \-\-no-command-line-only .
 This has no effect in eval mode.
-.
-.TP
-.BI "\-I " imagedir
-Look in
-.I imagedir
-for custom Lisp images.
-This option overrides the default image directory,
 which is set at compile time.
 .
 .TP
-.BI "\-L " sys , sys ,\fR...
+.BI "\-L" "\fR, " "\-\-accept-lisp=" sys , sys ,\fR...
 Use one of the named Lisp systems.
 Each
 .I sys
-must name a supported Lisp system.
+must name a supported Lisp system;
+the names are separated by a comma
+.RB ` , '
+and/or one or more whitespace characters.
 This option may be given more than once:
 the effect is the same as a single option
 listing all of the systems named, in the same order.
@@ -236,31 +178,23 @@ a warning is issued (at verbosity level 1 or higher),
 and all but the first occurrence is ignored.
 .
 .TP
-.BI "\-P " sys , sys ,\fR...
-Set the relative preference order of Lisp systems:
-systems listed earlier are more preferred.
-Each
-.I sys
-must name a supported Lisp system.
-This option may be given more than once:
-the effect is the same as a single option
-listing all of the systems named, in the same order.
-If a system is named more than once,
-a warning is issued (at verbosity level 1 or higher),
-and all but the first occurrence is ignored.
-Unmentioned systems are assigned lowest preference:
-if a
-.RB ` \-L '
-option is given,
-then this provides a default preference ordering;
-otherwise, an ordering hardcoded into the program is used.
-The first acceptable Lisp system,
-according to the preference order just described,
-which actually exists,
-is the one selected.
+.BI "\-c" "\fR, " "\-\-config-file=" conf
+Read configuration from
+.IR conf .
+If
+.I conf
+is a directory, then all of the files within
+whose names end with
+.RB ` .conf ',
+are loaded, in ascending lexicographical order;
+otherwise,
+.I conf
+is opened as a file.
+All of the files are expected to as described in
+.BR runlisp.conf (5).
 .
 .TP
-.BI "\-e " expr
+.BI "\-e" "\fR, " "\-\-evaluate-expression=" expr
 Evaluate the expression(s)
 .I expr
 and discard the resulting values.
@@ -271,7 +205,7 @@ to execute in
 mode.
 .
 .TP
-.BI "\-l " file
+.BI "\-l" "\fR, " "\-\-load-file=" file
 Read and evaluate forms from the
 .IR file .
 This option causes
@@ -281,15 +215,19 @@ to execute in
 mode.
 .
 .TP
-.B "\-n"
+.BR "\-n" ", " "-\-dry-run"
 Don't actually start the Lisp environment.
 This may be helpful for the curious,
 in conjunction with
 .RB ` \-v '
 to increase the verbosity.
+Negate with
+.B +n
+or
+.BR "\-\-no-dry-run" .
 .
 .TP
-.BI "\-p " expr
+.BI "\-p" "\fR, " "\-\-print-expressin=" expr
 Evaluate the expression(s)
 .I expr
 and print the resulting value(s)
@@ -308,7 +246,7 @@ to execute in
 mode.
 .
 .TP
-.B "\-q"
+.BR "\-q" ", " "\-\-quiet"
 Don't print warning messages.
 This option may be repeated:
 each use reduces verbosity by one step,
@@ -319,7 +257,7 @@ The default verbosity level is 1,
 which prints only warning measages.
 .
 .TP
-.B "\-v"
+.BR "\-v" ", " "\-\-verbose"
 Print informational or debugging messages.
 This option may be repeated:
 each use increases verbosity by one step,
@@ -339,11 +277,7 @@ and
 options may only be given on the command-line itself,
 not following a
 .RB `@ RUNLISP: '
-marker in a script,
-in a configuration file,
-or in the
-.B RUNLISP_OPTIONS
-environment variable.
+marker in a script.
 These options may be given multiple times:
 they will be processed in the order given.
 If any of these options is given, then no
@@ -354,14 +288,15 @@ instead, use
 to load code from files.
 The
 .IR arguments ,
-if any,
+ppif any,
 are still made available to the evaluated forms and loaded files.
 .
 .SS "Operation"
 The
 .B runlisp
 program behaves as follows.
-.PP
+.
+.hP 1.
 The first thing it does is parse its command line.
 Options must precede positional arguments,
 though the boundary may be marked explicitly using
@@ -389,7 +324,7 @@ and
 runs in
 .I script
 mode.
-.PP
+.hP 2.
 In
 .I script
 mode,
@@ -401,6 +336,8 @@ If so, then the following text is parsed
 for
 .IR "embedded options" ,
 as follows.
+.RS
+.PP
 The text is split into words
 separated by sequences of whitespace characters.
 Whitespace,
@@ -436,18 +373,41 @@ before processing quoting and escaping,
 then everything up to and including the next occurrence of
 .RB ` \-*\- '
 is ignored.
+.PP
 The resulting list of words
 is processed as if it held further command-line options.
-However,
+Currently, only
+.RB ` \-D '
+and
+.RB ` \-L '
+options are permitted in embedded option lists:
+.RB ` \-h '
+and
+.RB ` \-v '
+are clearly only useful in interactive use;
+setting
+.RB ` \-q '
+or
+.RB ` \-v '
+would just be annoying;
+setting
+.RB ` \-c '
+or
+.RB ` \-o '
+would override the user's command-line settings;
+it's clearly too late to set
+.RB ` \-E ';
+and
 .B runlisp
 is now committed to
 .I script
-mode, so
+mode, so it's too late for
 .RB ` \-e ',
 .RB ` \-l ',
 and
 .RB ` \-p '
-options may not appear in a script file's embedded options list.
+too.
+.PP
 (This feature allows scripts to provide options even if they use
 .BR env (1)
 to find
@@ -459,78 +419,32 @@ since many operating systems pass the text following
 the interpreter name on a
 .RB ` #! '
 line as a single argument, without further splitting it at spaces.)
-.PP
-If a file named
-.B .runlisprc
-exists in the user's home directory,
-then this file is read to discover more options.
-(If the variable
-.B HOME
-is set in the environment,
-then its value is assumed to name the user's home directory;
-otherwise, the home directory is determined by looking up
-the process's real uid in the password database.)
-Lines consisting entirely of whitespace,
-and lines whose first whitespace character is either
-.RB ` # '
-or
-.RB ` ; '
-are ignored in this file.
-Other lines are split into words,
-and processed as additional command-line options,
-as described for embedded options above,
-except that:
-a
-.RB ` \-\- '
-marker does not terminate word splitting; and
-Emacs-style
-.RB ` \-*\- ... \-*\- '
-local variable lists are not ignored.
-Each line is processed separately,
-so an option and its argument must be written on the same line.
-By this point
-.B runlisp
-will have committed to
-.I script
-or
-.I eval
-mode,
-so
-.RB ` \-e ',
-.RB ` \-l ',
+.RE
+.
+.hP 3.
+If no
+.RB ` \-c '
+options were given,
+then the default configuration files are read:
+the system configuration from
+.B @etcdir@/runlisp.conf
 and
-.RB ` \-p '
-options may not appear in a configuration file.
-.PP
-If a file
-.B runlisprc
-exists in the user's
-.I "configuration home"
-directory,
-then it is processed as for
-.B .runlisprc
-above.
-If a variable
-.B XDG_CONFIG_HOME
-is set in the environment,
-then its value is assumed to name the configuration home;
-otherwise, the configuration home is the directory
-.B .config
-in the user's home directory, as determined above.
-.PP
-If the variable
-.B RUNLISP_OPTIONS
-is set in the environment,
-then its value is split into words
-and processed as additional command-line options,
-as for a line of a configuration file as described above.
-.PP
+.BR @etcdir@/runlisp.d/*.conf ,
+and the user configuration from
+.B ~/.runlisp.conf
+and/or
+.BR ~/.config/runlisp.conf :
+see
+.RB runlisp.conf (5)
+for the details.
+.
+.hP 4.
 The list of
 .I "acceptable Lisp implementations"
 is determined.
 If any
 .RB ` \-L '
-options have been issued,
+options have been found,
 then the list of acceptable implementations
 consists of all of the implementations mentioned in
 .RB ` -L '
@@ -549,40 +463,39 @@ If no
 option is given, then
 .B runlisp
 uses a default list,
-which consists of all of the supported Lisp implementations
-in an hardcoded order which reflects
-the author's arbitrary preferences.
-.PP
+which consists of all of the Lisp implementations
+defined in its configuration,
+in the order in which they were defined.
+.
+.hP 5.
 The list of
 .I "preferred Lisp implementations"
 is determined.
-If any
-.RB ` \-P '
-options have been issued
-.I "since the last"
-.IB ` \-C '
-.IR "option" ,
-then the list of preferred implementations
-consists of all of the implementations mentioned in
-.RB ` \-P '
-options after the last occurrence of
-.RB ` \-C ',
-in the order of their first occurrences.
-(If an implementation is named more than once,
-then
+If the environment variable
+.B RUNLISP_PREFER
+is set,
+then its value should be a list of names of Lisp implementations
+separated by a comma and/or one or more whitespace characters.
+Otherwise, if there is a setting for the variable
+.B prefer
+in the
+.B @CONFIG
+configuration section,
+then its (expanded) value should be a list of Lisp implementations,
+in the same way.
+Otherwise, the list of preferred implementations is empty.
+.
+.hP 6.
+If
 .B runlisp
-prints a warning to stderr
-and ignores all but the first occurrence.)
-If no
-.RB ` \-P '
-option is given,
-or a
-.RB ` \-C '
-option appears after all of the
-.RB ` \-P '
-options,
-then the list of preferred implementations is empty.
-.PP
+is running in
+.I eval
+mode, then a new command line is built,
+which invokes an internal script,
+instructing it to evaluate and print the requested expressions,
+and load the requested files.
+.
+.hP 7.
 Acceptable Lisp implementations are tried in turn.
 First, the preferred implementations
 which are also listed as acceptable implementations
@@ -591,11 +504,41 @@ in the preferred implementations list;
 then, the remaining acceptable implementations are tried
 in the order in which they appear
 in the acceptable implementations list.
-To
-.I try
-a Lisp implementation means to construct a command line
-(whose effect will be described below)
-and pass it to the
+.RS
+.PP
+A Lisp implementation is defined by a configuration section
+which defines a variable
+.BR run-script .
+The name of the configuration section
+is the name of the Lisp implementation,
+as used in the acceptable and preferred lists described above.
+.hP (a)
+The variable
+.B image-file
+is looked up in the configuration section.
+If a value is found, then
+.B runlisp
+looks up and expands
+.BR image-path ,
+and checks to see if a file exists with the resulting name.
+If so, it sets the variable
+.B @image
+to
+.B t
+in the configuration section.
+.hP (b)
+The variable
+.B run-script
+is expanded and word-split.
+The
+.I script
+(an internal script, in
+.I eval
+mode)
+and
+.IR argument s
+are appended, and
+the entire list is passed to the
 .BR execvp (3)
 function.
 If that succeeds, the Lisp implementation runs;
@@ -616,29 +559,15 @@ just simulates the behaviour of
 printing messages to stderr
 if the verbosity level is sufficiently high,
 and exits.
-.PP
-In
-.I script
-mode,
-the script is invoked.
-In
-.I eval
-mode,
-the instructions given in
-.RB ` \-e ',
-.RB ` \-l ',
-and
-.RB ` \-p '
-options are carried out,
-in the order in which the appeared in the command line.
-The details of the environment
-in which Lisp code is executed
-are described next.
 .
 .SS "Script environment"
-Code in scripts and forms invoked by
+Many Lisp implementations don't provide a satisfactory environment
+for scripts to run in.
+The actual task of invoking a Lisp implementation
+is left to configuration,
+but the basic configuration supplied with
 .B runlisp
-may assume the following facts about their environment.
+ensures the following facts about their environment.
 .hP \*o
 The keyword
 .B :runlisp-script