3 .\" Manual for `runlisp'
5 .\" (c) 2020 Mark Wooding
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
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.
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
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/>.
40 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
44 .\"--------------------------------------------------------------------------
45 .TH runlisp 1 "2 August 2020" "Mark Wooding"
47 runlisp \- run Common Lisp programs as scripts
49 .\"--------------------------------------------------------------------------
79 .IB sys , sys , \fR\*(..]
92 .\"--------------------------------------------------------------------------
97 program has two main functions.
99 It can be used in a script's
101 line to run a Common Lisp script.
103 It can be used in build scripts
104 to invoke a Common Lisp system,
105 e.g., to build a standalone program.
108 Options are read from the command line, as usual,
109 but also (by default) from the script's second line,
114 below for the details.
117 The options accepted are as follows.
120 .BR "\-h" ", " "\-\-help"
122 .BR query-runlisp-config 's
124 and a description of the command-line options
126 and immediately exit with status 0.
129 .BR "\-V" ", " "\-\-version"
131 .BR query-runlisp-config 's
134 and immediately exit with status 0.
137 .BR "\-D" ", " "\-\-vanilla-image"
138 Don't check for a custom Lisp image.
141 tries to start Lisp systems using a custom image,
142 so that they'll start more quickly;
145 option forces the use of the default `vanilla' image
146 provided with the system.
147 There's not usually any good reason to prefer the vanilla image,
148 except for performance comparisons, or debugging
154 .BR \-\-no-vanilla-image .
157 .BR "\-E" ", " "\-\-command-line-only"
158 Don't read embedded options from the
165 .BR \-\-no-command-line-only .
166 This has no effect in eval mode.
167 which is set at compile time.
170 .BI "\-L" "\fR, " "\-\-accept-lisp=" sys , sys ,\fR\*(..
171 Use one of the named Lisp systems.
174 must name a supported Lisp system;
175 the names are separated by a comma
177 and/or one or more whitespace characters.
178 This option may be given more than once:
179 the effect is the same as a single option
180 listing all of the systems named, in the same order.
181 If a system is named more than once,
182 a warning is issued (at verbosity level 1 or higher),
183 and all but the first occurrence is ignored.
186 .BI "\-c" "\fR, " "\-\-config-file=" conf
187 Read configuration from
191 is a directory, then all of the files within
194 are loaded, in ascending lexicographical order;
198 All of the files are expected to be as described in
199 .BR runlisp.conf (5).
202 .BI "\-e" "\fR, " "\-\-evaluate-expression=" expr
203 Evaluate the expression(s)
205 and discard the resulting values.
213 .BI "\-l" "\fR, " "\-\-load-file=" file
214 Read and evaluate forms from the
223 .BR "\-n" ", " "\-\-dry-run"
224 Don't actually start the Lisp environment.
225 This may be helpful for the curious,
228 to increase the verbosity.
232 .BR "\-\-no-dry-run" .
235 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect :\fR] var = value
240 in configuration section
244 if no section is specified.
245 The value is unexpandable,
246 and overrides any similarly named setting
247 from the configuration file(s).
250 .BI "\-p" "\fR, " "\-\-print-expressin=" expr
251 Evaluate the expression(s)
253 and print the resulting value(s)
257 If a form produces multiple values,
258 they are printed on a single line,
259 separated by a single space character;
260 if a form produces no values at all,
261 then nothing is printed \(en not even a newline character.
269 .BR "\-q" ", " "\-\-quiet"
270 Don't print warning messages.
271 This option may be repeated:
272 each use reduces verbosity by one step,
276 The default verbosity level is 1,
277 which prints only warning measages.
280 .BR "\-v" ", " "\-\-verbose"
281 Print informational or debugging messages.
282 This option may be repeated:
283 each use increases verbosity by one step,
287 The default verbosity level is 1,
288 which prints only warning measages.
289 Higher verbosity levels print informational and debugging messages.
297 options may only be given on the command-line itself,
301 These options may be given multiple times:
302 they will be processed in the order given.
303 If any of these options is given, then no
308 to load code from files.
312 are still made available to the evaluated forms and loaded files.
317 program behaves as follows.
320 The first thing it does is parse its command line.
321 Options must precede positional arguments,
322 though the boundary may be marked explicitly using
325 If the command line contains any of
332 treats all of its positional arguments as
334 to provide to the given forms and files,
338 otherwise, the first positional argument becomes the
340 name, the remaining ones become
352 reads the second line of the script file,
353 and checks to see if it contains the string
355 If so, then the following text is parsed
357 .IR "embedded options" ,
361 The text is split into words
362 separated by sequences of whitespace characters.
364 and other special characters,
365 can be included in a word by
369 Text between single quotes
371 is included literally, without any further interpretation;
372 text between double quotes
374 is treated literally,
375 except that escaping can still be used
376 to escape (e.g.) double quotes and the escape character itself.
377 Outside of single quotes, a backslash
379 causes the following character to be included in a word
380 regardless of its usual meaning.
381 (None of this allows a newline character
382 to be included in a word:
383 this is simply not possible.)
386 before processing quoting and escaping
387 marks the end of embedded options.
388 As a concession to Emacs users,
391 appears at the start of a word
392 before processing quoting and escaping,
393 then everything up to and including the next occurrence of
397 The resulting list of words
398 is processed as if it held further command-line options.
403 options are permitted in embedded option lists:
407 are clearly only useful in interactive use;
412 would just be annoying;
417 would override the user's command-line settings;
418 it's clearly too late to set
424 mode, so it's too late for
431 (This feature allows scripts to provide options even if they use
437 or to provide more than one option,
438 since many operating systems pass the text following
439 the interpreter name on a
441 line as a single argument, without further splitting it at spaces.)
448 then the default configuration files are read:
449 the system configuration from
450 .B @etcdir@/runlisp.conf
452 .BR @etcdir@/runlisp.d/*.conf ,
453 and the user configuration from
456 .BR ~/.config/runlisp.conf :
463 .I "acceptable Lisp implementations"
467 options have been found,
468 then the list of acceptable implementations
469 consists of all of the implementations mentioned in
475 in the order of their first occurrence.
476 (If an implementation is named more than once,
479 prints a warning to stderr
480 and ignores all but the first occurrence.)
483 option is given, then
486 which consists of all of the Lisp implementations
487 defined in its configuration,
488 in the order in which they were defined.
492 .I "preferred Lisp implementations"
494 If the environment variable
497 then its value should be a list of names of Lisp implementations
498 separated by a comma and/or one or more whitespace characters.
499 Otherwise, if there is a setting for the variable
503 configuration section,
504 then its (expanded) value should be a list of Lisp implementations,
506 Otherwise, the list of preferred implementations is empty.
513 mode, then a new command line is built,
514 which invokes an internal script,
515 instructing it to evaluate and print the requested expressions,
516 and load the requested files.
519 Acceptable Lisp implementations are tried in turn.
520 First, the preferred implementations
521 which are also listed as acceptable implementations
522 are tried, in the order in which they appear
523 in the preferred implementations list;
524 then, the remaining acceptable implementations are tried
525 in the order in which they appear
526 in the acceptable implementations list.
529 A Lisp implementation is defined by a configuration section
530 which defines a variable
532 The name of the configuration section
533 is the name of the Lisp implementation,
534 as used in the acceptable and preferred lists described above.
538 is looked up in the configuration section.
539 If a value is found, then
543 and checks to see if a file exists with the resulting name.
544 If so, it sets the variable
548 in the configuration section.
552 is expanded and word-split.
555 (an internal script, in
561 the entire list is passed to the
564 If that succeeds, the Lisp implementation runs;
567 then other Lisp systems are tried;
568 if it fails with some other error, then
570 reports an error message to stderr
571 and exits unsuccessfully
575 option was given, then
577 just simulates the behaviour of
579 printing messages to stderr
580 if the verbosity level is sufficiently high,
583 .SS "Script environment"
584 Many Lisp implementations don't provide a satisfactory environment
585 for scripts to run in.
586 The actual task of invoking a Lisp implementation
587 is left to configuration,
588 but the basic configuration supplied with
590 ensures the following facts about their environment.
602 Most Lisp systems support a user initialization file
603 which they load before entering the REPL;
604 some also have a system initialization file.
610 so that the Lisp environment is reasonably predictable,
611 and to avoid slowing down script startup
612 with things which are convenient for use in an interactive session,
613 but can't be relied upon by a script anyway.
615 The Unix standard input, standard output, and standard error files
616 are available through the Lisp
617 .BR *standard-input* ,
618 .BR *standard-output* ,
621 streams, respectively.
629 .B ext:*require-verbose*
631 Alas, this is insufficient to muffle noise while loading add-on systems
632 on some implementations.
634 If an error is signalled, and not caught by user code,
635 then the process will print a message to stderr
636 and exit with a nonzero status.
637 The reported message may be a long, ugly backtrace,
638 or a terse error report.
639 If no error is signalled but not caught,
640 then the process will exit with status 0.
642 The initial package is
643 .BR COMMON-LISP-USER ,
644 which has no symbols `present' (i.e., imported or interned).
650 systems are already loaded.
651 Further systems can be loaded using
655 (which is only meaningful if
660 and arguments are available through the
663 .B uiop:*command-line-arguments*
664 variable, respectively.
666 .\"--------------------------------------------------------------------------
670 Loading ASDF systems is irritatingly noisy
671 with some Lisp implementations.
672 Suggestions for how to improve this are welcome.
674 More Lisp implementations should be supported.
675 I've supported the ones I have installed.
676 I'm not willing to put a great deal of effort into supporting
677 non-free Lisp implementations;
678 but help supporting free Lisps is much appreciated.
680 The protocol for passing the script name through to
682 (specifically, through the
684 environment variable)
688 is obviously a better approach than introducing a
689 .BR runlisp -specific
690 interface to the same information.
691 I don't know how to fix this:
692 suggestions are welcome.
695 .BR dump-runlisp-image (1),
696 .BR query-runlisp-config (1),
697 .BR runlisp.conf (5).
700 Mark Wooding, <mdw@distorted.org.uk>
702 .\"----- That's all, folks --------------------------------------------------