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
43 .\"--------------------------------------------------------------------------
44 .TH runlisp 1 "2 August 2020" "Mark Wooding"
46 runlisp \- run Common Lisp programs as scripts
48 .\"--------------------------------------------------------------------------
78 .IB sys , sys , \fR...]
87 .\"--------------------------------------------------------------------------
92 program has two main functions.
94 It can be used in a script's
96 line to run a Common Lisp script.
98 It can be used in build scripts
99 to invoke a Common Lisp system,
100 e.g., to build a standalone program.
103 Options are read from the command line, as usual,
104 but also (by default) from the script's second line,
109 below for the details.
112 The options accepted are as follows.
115 .BR "\-h" ", " "\-\-help"
117 .BR query-runlisp-config 's
119 and a description of the command-line options
121 and immediately exit with status 0.
124 .BR "\-V" ", " "\-\-version"
126 .BR query-runlisp-config 's
129 and immediately exit with status 0.
132 .BR "\-D" ", " "\-\-vanilla-image"
133 Don't check for a custom Lisp image.
136 tries to start Lisp systems using a custom image,
137 so that they'll start more quickly;
140 option forces the use of the default `vanilla' image
141 provided with the system.
142 There's not usually any good reason to prefer the vanilla image,
143 except for performance comparisons, or debugging
149 .BR \-\-no-vanilla-image .
152 .BR "\-E" ", " "\-\-command-line-only"
153 Don't read embedded options from the
160 .BR \-\-no-command-line-only .
161 This has no effect in eval mode.
162 which is set at compile time.
165 .BI "\-L" "\fR, " "\-\-accept-lisp=" sys , sys ,\fR...
166 Use one of the named Lisp systems.
169 must name a supported Lisp system;
170 the names are separated by a comma
172 and/or one or more whitespace characters.
173 This option may be given more than once:
174 the effect is the same as a single option
175 listing all of the systems named, in the same order.
176 If a system is named more than once,
177 a warning is issued (at verbosity level 1 or higher),
178 and all but the first occurrence is ignored.
181 .BI "\-c" "\fR, " "\-\-config-file=" conf
182 Read configuration from
186 is a directory, then all of the files within
189 are loaded, in ascending lexicographical order;
193 All of the files are expected to as described in
194 .BR runlisp.conf (5).
197 .BI "\-e" "\fR, " "\-\-evaluate-expression=" expr
198 Evaluate the expression(s)
200 and discard the resulting values.
208 .BI "\-l" "\fR, " "\-\-load-file=" file
209 Read and evaluate forms from the
218 .BR "\-n" ", " "-\-dry-run"
219 Don't actually start the Lisp environment.
220 This may be helpful for the curious,
223 to increase the verbosity.
227 .BR "\-\-no-dry-run" .
230 .BI "\-p" "\fR, " "\-\-print-expressin=" expr
231 Evaluate the expression(s)
233 and print the resulting value(s)
237 If a form produces multiple values,
238 they are printed on a single line,
239 separated by a single space character;
240 if a form produces no values at all,
241 then nothing is printed \(en not even a newline character.
249 .BR "\-q" ", " "\-\-quiet"
250 Don't print warning messages.
251 This option may be repeated:
252 each use reduces verbosity by one step,
256 The default verbosity level is 1,
257 which prints only warning measages.
260 .BR "\-v" ", " "\-\-verbose"
261 Print informational or debugging messages.
262 This option may be repeated:
263 each use increases verbosity by one step,
267 The default verbosity level is 1,
268 which prints only warning measages.
269 Higher verbosity levels print informational and debugging messages.
277 options may only be given on the command-line itself,
281 These options may be given multiple times:
282 they will be processed in the order given.
283 If any of these options is given, then no
288 to load code from files.
292 are still made available to the evaluated forms and loaded files.
297 program behaves as follows.
300 The first thing it does is parse its command line.
301 Options must precede positional arguments,
302 though the boundary may be marked explicitly using
305 If the command line contains any of
312 treats all of its positional arguments as
314 to provide to the given forms and files,
318 otherwise, the first positional argument becomes the
320 name, the remaining ones become
332 reads the second line of the script file,
333 and checks to see if it contains the string
335 If so, then the following text is parsed
337 .IR "embedded options" ,
341 The text is split into words
342 separated by sequences of whitespace characters.
344 and other special characters,
345 can be included in a word by
349 Text between single quotes
351 is included literally, without any further interpretation;
352 text between double quotes
354 is treated literally,
355 except that escaping can still be used
356 to escape (e.g.) double quotes and the escape character itself.
357 Outside of single quotes, a backslash
359 causes the following character to be included in a word
360 regardless of its usual meaning.
361 (None of this allows a newline character
362 to be included in a word:
363 this is simply not possible.)
366 before processing quoting and escaping
367 marks the end of embedded options.
368 As a concession to Emacs users,
371 appears at the start of a word
372 before processing quoting and escaping,
373 then everything up to and including the next occurrence of
377 The resulting list of words
378 is processed as if it held further command-line options.
383 options are permitted in embedded option lists:
387 are clearly only useful in interactive use;
392 would just be annoying;
397 would override the user's command-line settings;
398 it's clearly too late to set
404 mode, so it's too late for
411 (This feature allows scripts to provide options even if they use
417 or to provide more than one option,
418 since many operating systems pass the text following
419 the interpreter name on a
421 line as a single argument, without further splitting it at spaces.)
428 then the default configuration files are read:
429 the system configuration from
430 .B @etcdir@/runlisp.conf
432 .BR @etcdir@/runlisp.d/*.conf ,
433 and the user configuration from
436 .BR ~/.config/runlisp.conf :
443 .I "acceptable Lisp implementations"
447 options have been found,
448 then the list of acceptable implementations
449 consists of all of the implementations mentioned in
455 in the order of their first occurrence.
456 (If an implementation is named more than once,
459 prints a warning to stderr
460 and ignores all but the first occurrence.)
463 option is given, then
466 which consists of all of the Lisp implementations
467 defined in its configuration,
468 in the order in which they were defined.
472 .I "preferred Lisp implementations"
474 If the environment variable
477 then its value should be a list of names of Lisp implementations
478 separated by a comma and/or one or more whitespace characters.
479 Otherwise, if there is a setting for the variable
483 configuration section,
484 then its (expanded) value should be a list of Lisp implementations,
486 Otherwise, the list of preferred implementations is empty.
493 mode, then a new command line is built,
494 which invokes an internal script,
495 instructing it to evaluate and print the requested expressions,
496 and load the requested files.
499 Acceptable Lisp implementations are tried in turn.
500 First, the preferred implementations
501 which are also listed as acceptable implementations
502 are tried, in the order in which they appear
503 in the preferred implementations list;
504 then, the remaining acceptable implementations are tried
505 in the order in which they appear
506 in the acceptable implementations list.
509 A Lisp implementation is defined by a configuration section
510 which defines a variable
512 The name of the configuration section
513 is the name of the Lisp implementation,
514 as used in the acceptable and preferred lists described above.
518 is looked up in the configuration section.
519 If a value is found, then
523 and checks to see if a file exists with the resulting name.
524 If so, it sets the variable
528 in the configuration section.
532 is expanded and word-split.
535 (an internal script, in
541 the entire list is passed to the
544 If that succeeds, the Lisp implementation runs;
547 then other Lisp systems are tried;
548 if it fails with some other error, then
550 reports an error message to stderr
551 and exits unsuccessfully
555 option was given, then
557 just simulates the behaviour of
559 printing messages to stderr
560 if the verbosity level is sufficiently high,
563 .SS "Script environment"
564 Many Lisp implementations don't provide a satisfactory environment
565 for scripts to run in.
566 The actual task of invoking a Lisp implementation
567 is left to configuration,
568 but the basic configuration supplied with
570 ensures the following facts about their environment.
582 Most Lisp systems support a user initialization file
583 which they load before entering the REPL;
584 some also have a system initialization file.
590 so that the Lisp environment is reasonably predictable,
591 and to avoid slowing down script startup
592 with things which are convenient for use in an interactive session,
593 but can't be relied upon by a script anyway.
595 The Unix standard input, standard output, and standard error files
596 are available through the Lisp
597 .BR *standard-input* ,
598 .BR *standard-output* ,
601 streams, respectively.
609 .B ext:*require-verbose*
611 Alas, this is insufficient to muffle noise while loading add-on systems
612 on some implementations.
614 If an error is signalled, and not caught by user code,
615 then the process will print a message to stderr
616 and exit with a nonzero status.
617 The reported message may be a long, ugly backtrace,
618 or a terse error report.
619 If no error is signalled but not caught,
620 then the process will exit with status 0.
622 The initial package is
623 .BR COMMON-LISP-USER ,
624 which has no symbols `present' (i.e., imported or interned).
630 systems are already loaded.
631 Further systems can be loaded using
635 (which is only meaningful if
640 and arguments are available through the
643 .B uiop:*command-line-arguments*
644 variable, respectively.
646 .\"--------------------------------------------------------------------------
650 Loading ASDF systems is irritatingly noisy
651 with some Lisp implementations.
652 Suggestions for how to improve this are welcome.
654 More Lisp implementations should be supported.
655 I've supported the ones I have installed.
656 I'm not willing to put a great deal of effort into supporting
657 non-free Lisp implementations;
658 but help supporting free Lisps is much appreciated.
660 The protocol for passing the script name through to
662 (specifically, through the
664 environment variable)
668 is obviously a better approach than introducing a
669 .BR runlisp -specific
670 interface to the same information.
671 I don't know how to fix this:
672 suggestions are welcome.
675 .BR dump-runlisp-image (1),
676 .BR query-runlisp-config (1),
677 .BR runlisp.conf (5).
680 Mark Wooding, <mdw@distorted.org.uk>
682 .\"----- That's all, folks --------------------------------------------------