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...]
91 .\"--------------------------------------------------------------------------
96 program has two main functions.
98 It can be used in a script's
100 line to run a Common Lisp script.
102 It can be used in build scripts
103 to invoke a Common Lisp system,
104 e.g., to build a standalone program.
107 Options are read from the command line, as usual,
108 but also (by default) from the script's second line,
113 below for the details.
116 The options accepted are as follows.
119 .BR "\-h" ", " "\-\-help"
121 .BR query-runlisp-config 's
123 and a description of the command-line options
125 and immediately exit with status 0.
128 .BR "\-V" ", " "\-\-version"
130 .BR query-runlisp-config 's
133 and immediately exit with status 0.
136 .BR "\-D" ", " "\-\-vanilla-image"
137 Don't check for a custom Lisp image.
140 tries to start Lisp systems using a custom image,
141 so that they'll start more quickly;
144 option forces the use of the default `vanilla' image
145 provided with the system.
146 There's not usually any good reason to prefer the vanilla image,
147 except for performance comparisons, or debugging
153 .BR \-\-no-vanilla-image .
156 .BR "\-E" ", " "\-\-command-line-only"
157 Don't read embedded options from the
164 .BR \-\-no-command-line-only .
165 This has no effect in eval mode.
166 which is set at compile time.
169 .BI "\-L" "\fR, " "\-\-accept-lisp=" sys , sys ,\fR...
170 Use one of the named Lisp systems.
173 must name a supported Lisp system;
174 the names are separated by a comma
176 and/or one or more whitespace characters.
177 This option may be given more than once:
178 the effect is the same as a single option
179 listing all of the systems named, in the same order.
180 If a system is named more than once,
181 a warning is issued (at verbosity level 1 or higher),
182 and all but the first occurrence is ignored.
185 .BI "\-c" "\fR, " "\-\-config-file=" conf
186 Read configuration from
190 is a directory, then all of the files within
193 are loaded, in ascending lexicographical order;
197 All of the files are expected to be as described in
198 .BR runlisp.conf (5).
201 .BI "\-e" "\fR, " "\-\-evaluate-expression=" expr
202 Evaluate the expression(s)
204 and discard the resulting values.
212 .BI "\-l" "\fR, " "\-\-load-file=" file
213 Read and evaluate forms from the
222 .BR "\-n" ", " "\-\-dry-run"
223 Don't actually start the Lisp environment.
224 This may be helpful for the curious,
227 to increase the verbosity.
231 .BR "\-\-no-dry-run" .
234 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect :\fR] var = value
239 in configuration section
243 if no section is specified.
244 The value is unexpandable,
245 and overrides any similarly named setting
246 from the configuration file(s).
249 .BI "\-p" "\fR, " "\-\-print-expressin=" expr
250 Evaluate the expression(s)
252 and print the resulting value(s)
256 If a form produces multiple values,
257 they are printed on a single line,
258 separated by a single space character;
259 if a form produces no values at all,
260 then nothing is printed \(en not even a newline character.
268 .BR "\-q" ", " "\-\-quiet"
269 Don't print warning messages.
270 This option may be repeated:
271 each use reduces verbosity by one step,
275 The default verbosity level is 1,
276 which prints only warning measages.
279 .BR "\-v" ", " "\-\-verbose"
280 Print informational or debugging messages.
281 This option may be repeated:
282 each use increases verbosity by one step,
286 The default verbosity level is 1,
287 which prints only warning measages.
288 Higher verbosity levels print informational and debugging messages.
296 options may only be given on the command-line itself,
300 These options may be given multiple times:
301 they will be processed in the order given.
302 If any of these options is given, then no
307 to load code from files.
311 are still made available to the evaluated forms and loaded files.
316 program behaves as follows.
319 The first thing it does is parse its command line.
320 Options must precede positional arguments,
321 though the boundary may be marked explicitly using
324 If the command line contains any of
331 treats all of its positional arguments as
333 to provide to the given forms and files,
337 otherwise, the first positional argument becomes the
339 name, the remaining ones become
351 reads the second line of the script file,
352 and checks to see if it contains the string
354 If so, then the following text is parsed
356 .IR "embedded options" ,
360 The text is split into words
361 separated by sequences of whitespace characters.
363 and other special characters,
364 can be included in a word by
368 Text between single quotes
370 is included literally, without any further interpretation;
371 text between double quotes
373 is treated literally,
374 except that escaping can still be used
375 to escape (e.g.) double quotes and the escape character itself.
376 Outside of single quotes, a backslash
378 causes the following character to be included in a word
379 regardless of its usual meaning.
380 (None of this allows a newline character
381 to be included in a word:
382 this is simply not possible.)
385 before processing quoting and escaping
386 marks the end of embedded options.
387 As a concession to Emacs users,
390 appears at the start of a word
391 before processing quoting and escaping,
392 then everything up to and including the next occurrence of
396 The resulting list of words
397 is processed as if it held further command-line options.
402 options are permitted in embedded option lists:
406 are clearly only useful in interactive use;
411 would just be annoying;
416 would override the user's command-line settings;
417 it's clearly too late to set
423 mode, so it's too late for
430 (This feature allows scripts to provide options even if they use
436 or to provide more than one option,
437 since many operating systems pass the text following
438 the interpreter name on a
440 line as a single argument, without further splitting it at spaces.)
447 then the default configuration files are read:
448 the system configuration from
449 .B @etcdir@/runlisp.conf
451 .BR @etcdir@/runlisp.d/*.conf ,
452 and the user configuration from
455 .BR ~/.config/runlisp.conf :
462 .I "acceptable Lisp implementations"
466 options have been found,
467 then the list of acceptable implementations
468 consists of all of the implementations mentioned in
474 in the order of their first occurrence.
475 (If an implementation is named more than once,
478 prints a warning to stderr
479 and ignores all but the first occurrence.)
482 option is given, then
485 which consists of all of the Lisp implementations
486 defined in its configuration,
487 in the order in which they were defined.
491 .I "preferred Lisp implementations"
493 If the environment variable
496 then its value should be a list of names of Lisp implementations
497 separated by a comma and/or one or more whitespace characters.
498 Otherwise, if there is a setting for the variable
502 configuration section,
503 then its (expanded) value should be a list of Lisp implementations,
505 Otherwise, the list of preferred implementations is empty.
512 mode, then a new command line is built,
513 which invokes an internal script,
514 instructing it to evaluate and print the requested expressions,
515 and load the requested files.
518 Acceptable Lisp implementations are tried in turn.
519 First, the preferred implementations
520 which are also listed as acceptable implementations
521 are tried, in the order in which they appear
522 in the preferred implementations list;
523 then, the remaining acceptable implementations are tried
524 in the order in which they appear
525 in the acceptable implementations list.
528 A Lisp implementation is defined by a configuration section
529 which defines a variable
531 The name of the configuration section
532 is the name of the Lisp implementation,
533 as used in the acceptable and preferred lists described above.
537 is looked up in the configuration section.
538 If a value is found, then
542 and checks to see if a file exists with the resulting name.
543 If so, it sets the variable
547 in the configuration section.
551 is expanded and word-split.
554 (an internal script, in
560 the entire list is passed to the
563 If that succeeds, the Lisp implementation runs;
566 then other Lisp systems are tried;
567 if it fails with some other error, then
569 reports an error message to stderr
570 and exits unsuccessfully
574 option was given, then
576 just simulates the behaviour of
578 printing messages to stderr
579 if the verbosity level is sufficiently high,
582 .SS "Script environment"
583 Many Lisp implementations don't provide a satisfactory environment
584 for scripts to run in.
585 The actual task of invoking a Lisp implementation
586 is left to configuration,
587 but the basic configuration supplied with
589 ensures the following facts about their environment.
601 Most Lisp systems support a user initialization file
602 which they load before entering the REPL;
603 some also have a system initialization file.
609 so that the Lisp environment is reasonably predictable,
610 and to avoid slowing down script startup
611 with things which are convenient for use in an interactive session,
612 but can't be relied upon by a script anyway.
614 The Unix standard input, standard output, and standard error files
615 are available through the Lisp
616 .BR *standard-input* ,
617 .BR *standard-output* ,
620 streams, respectively.
628 .B ext:*require-verbose*
630 Alas, this is insufficient to muffle noise while loading add-on systems
631 on some implementations.
633 If an error is signalled, and not caught by user code,
634 then the process will print a message to stderr
635 and exit with a nonzero status.
636 The reported message may be a long, ugly backtrace,
637 or a terse error report.
638 If no error is signalled but not caught,
639 then the process will exit with status 0.
641 The initial package is
642 .BR COMMON-LISP-USER ,
643 which has no symbols `present' (i.e., imported or interned).
649 systems are already loaded.
650 Further systems can be loaded using
654 (which is only meaningful if
659 and arguments are available through the
662 .B uiop:*command-line-arguments*
663 variable, respectively.
665 .\"--------------------------------------------------------------------------
669 Loading ASDF systems is irritatingly noisy
670 with some Lisp implementations.
671 Suggestions for how to improve this are welcome.
673 More Lisp implementations should be supported.
674 I've supported the ones I have installed.
675 I'm not willing to put a great deal of effort into supporting
676 non-free Lisp implementations;
677 but help supporting free Lisps is much appreciated.
679 The protocol for passing the script name through to
681 (specifically, through the
683 environment variable)
687 is obviously a better approach than introducing a
688 .BR runlisp -specific
689 interface to the same information.
690 I don't know how to fix this:
691 suggestions are welcome.
694 .BR dump-runlisp-image (1),
695 .BR query-runlisp-config (1),
696 .BR runlisp.conf (5).
699 Mark Wooding, <mdw@distorted.org.uk>
701 .\"----- That's all, folks --------------------------------------------------