.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
.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
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
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.
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.
mode.
.
.TP
-.BI "\-l " file
+.BI "\-l" "\fR, " "\-\-load-file=" file
Read and evaluate forms from the
.IR file .
This option causes
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)
mode.
.
.TP
-.B "\-q"
+.BR "\-q" ", " "\-\-quiet"
Don't print warning messages.
This option may be repeated:
each use reduces verbosity by one step,
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,
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
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
runs in
.I script
mode.
-.PP
+.hP 2.
In
.I script
mode,
for
.IR "embedded options" ,
as follows.
+.RS
+.PP
The text is split into words
separated by sequences of whitespace characters.
Whitespace,
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
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 '
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
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;
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
~mdw / runlisp / blobdiff