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 .\"--------------------------------------------------------------------------
85 .IB sys , sys , \fR\*(..]
98 .\"--------------------------------------------------------------------------
103 program has two main functions.
105 It can be used in a script's
107 line to run a Common Lisp script.
109 It can be used in build scripts
110 to invoke a Common Lisp system,
111 e.g., to build a standalone program.
114 Options are read from the command line, as usual,
115 but also (by default) from the script's second line,
120 below for the details.
123 The options accepted are as follows.
126 .BR "\-h" ", " "\-\-help"
128 .BR query-runlisp-config 's
130 and a description of the command-line options
132 and immediately exit with status 0.
135 .BR "\-V" ", " "\-\-version"
137 .BR query-runlisp-config 's
140 and immediately exit with status 0.
143 .BR "\-D" ", " "\-\-vanilla-image"
144 Don't check for a custom Lisp image.
147 tries to start Lisp systems using a custom image,
148 so that they'll start more quickly;
151 option forces the use of the default `vanilla' image
152 provided with the system.
153 There's not usually any good reason to prefer the vanilla image,
154 except for performance comparisons, or debugging
160 .BR \-\-no-vanilla-image .
163 .BR "\-E" ", " "\-\-command-line-only"
164 Don't read embedded options from the
171 .BR \-\-no-command-line-only .
172 This has no effect in eval mode.
175 .BI "\-L" "\fR, " "\-\-accept-lisp=" sys , sys ,\fR\*(..
176 Use one of the named Lisp systems.
179 must name a supported Lisp system;
180 the names are separated by a comma
182 and/or one or more whitespace characters.
183 This option may be given more than once:
184 the effect is the same as a single option
185 listing all of the systems named, in the same order.
186 If a system is named more than once,
187 a warning is issued (at verbosity level 1 or higher),
188 and all but the first occurrence is ignored.
191 .BI "\-c" "\fR, " "\-\-config-file=" conf
192 Read configuration from
196 is a directory, then all of the files within
199 are loaded, in ascending lexicographical order;
203 All of the files are expected to be as described in
204 .BR runlisp.conf (5).
207 .BI "\-d" "\fR, " "\-\-dump-expression=" expr
208 Evaluate the expression(s)
210 and print the resulting value(s)
216 If a form produces multiple values,
217 they are printed on a single line,
218 separated by a single space character;
219 if a form produces no values at all,
220 then nothing is printed \(en not even a newline character.
233 .BI "\-e" "\fR, " "\-\-evaluate-expression=" expr
234 Evaluate the expression(s)
236 and discard the resulting values.
244 .BI "\-l" "\fR, " "\-\-load-file=" file
245 Read and evaluate forms from the
254 .BR "\-n" ", " "\-\-dry-run"
255 Don't actually start the Lisp environment.
256 This may be helpful for the curious,
259 to increase the verbosity.
263 .BR "\-\-no-dry-run" .
266 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect :\fR] var = value
271 in configuration section
275 if no section is specified.
276 The value is unexpandable,
277 and overrides any similarly named setting
278 from the configuration file(s).
281 .BI "\-p" "\fR, " "\-\-print-expression=" expr
282 Evaluate the expression(s)
284 and print the resulting value(s)
290 If a form produces multiple values,
291 they are printed on a single line,
292 separated by a single space character;
293 if a form produces no values at all,
294 then nothing is printed \(en not even a newline character.
307 .BR "\-q" ", " "\-\-quiet"
308 Don't print warning messages.
309 This option may be repeated:
310 each use reduces verbosity by one step,
314 The default verbosity level is 1,
315 which prints only warning measages.
318 .BR "\-v" ", " "\-\-verbose"
319 Print informational or debugging messages.
320 This option may be repeated:
321 each use increases verbosity by one step,
325 The default verbosity level is 1,
326 which prints only warning measages.
327 Higher verbosity levels print informational and debugging messages.
336 options may only be given on the command-line itself,
340 These options may be given multiple times:
341 they will be processed in the order given.
342 If any of these options is given, then no
347 to load code from files.
351 are still made available to the evaluated forms and loaded files.
356 program behaves as follows.
359 The first thing it does is parse its command line.
360 Options must precede positional arguments,
361 though the boundary may be marked explicitly using
364 If the command line contains any of
372 treats all of its positional arguments as
374 to provide to the given forms and files,
378 otherwise, the first positional argument becomes the
380 name, the remaining ones become
393 option was not given,
395 reads the second line of the script file,
396 and checks to see if it contains the string
398 If so, then the following text is parsed
400 .IR "embedded options" ,
404 The text is split into words
405 separated by sequences of whitespace characters.
407 and other special characters,
408 can be included in a word by
412 Text between single quotes
414 is included literally, without any further interpretation;
415 text between double quotes
417 is treated literally,
418 except that escaping can still be used
419 to escape (e.g.) double quotes and the escape character itself.
420 Outside of single quotes, a backslash
422 causes the following character to be included in a word
423 regardless of its usual meaning.
424 (None of this allows a newline character
425 to be included in a word:
426 this is simply not possible.)
429 before processing quoting and escaping
430 marks the end of embedded options.
431 As a concession to Emacs users,
434 appears at the start of a word
435 before processing quoting and escaping,
436 then everything up to and including the next occurrence of
440 The resulting list of words
441 is processed as if it held further command-line options.
446 options are permitted in embedded option lists:
450 are clearly only useful in interactive use;
455 would just be annoying;
460 would override the user's command-line settings;
461 it's clearly too late to set
467 mode, so it's too late for
475 (This feature allows scripts to provide options even if they use
481 or to provide more than one option,
482 since many operating systems pass the text following
483 the interpreter name on a
485 line as a single argument, without further splitting it at spaces.)
492 then the default configuration files are read:
493 the system configuration from
494 .B @etcdir@/runlisp.conf
496 .BR @etcdir@/runlisp.d/*.conf ,
497 and the user configuration from
500 .BR ~/.config/runlisp.conf :
507 .I "acceptable Lisp implementations"
511 options have been found,
512 then the list of acceptable implementations
513 consists of all of the implementations mentioned in
519 in the order of their first occurrence.
520 (If an implementation is named more than once,
523 prints a warning to stderr
524 and ignores all but the first occurrence.)
527 option is given, then
530 which consists of all of the Lisp implementations
531 defined in its configuration,
532 in the order in which they were defined.
536 .I "preferred Lisp implementations"
538 If the environment variable
541 then its value should be a list of names of Lisp implementations
542 separated by a comma and/or one or more whitespace characters.
543 Otherwise, if there is a setting for the variable
547 configuration section,
548 then its (expanded) value should be a list of Lisp implementations,
550 Otherwise, the list of preferred implementations is empty.
557 mode, then a new command line is built,
558 which invokes an internal script,
559 instructing it to evaluate and print the requested expressions,
560 and load the requested files.
563 Acceptable Lisp implementations are tried in turn.
564 First, the preferred implementations
565 which are also listed as acceptable implementations
566 are tried, in the order in which they appear
567 in the preferred implementations list;
568 then, the remaining acceptable implementations are tried
569 in the order in which they appear
570 in the acceptable implementations list.
573 A Lisp implementation is defined by a configuration section
574 which defines a variable
576 The name of the configuration section
577 is the name of the Lisp implementation,
578 as used in the acceptable and preferred lists described above.
582 is looked up in the configuration section.
583 If a value is found, then
587 and checks to see if a file exists with the resulting name.
588 If so, it sets the variable
592 in the configuration section.
596 is expanded and word-split.
599 (an internal script, in
605 the entire list is passed to the
608 If that succeeds, the Lisp implementation runs;
611 then other Lisp systems are tried;
612 if it fails with some other error, then
614 reports an error message to stderr
615 and exits unsuccessfully
619 option was given, then
621 just simulates the behaviour of
623 printing messages to stderr
624 if the verbosity level is sufficiently high,
627 .SS "Script environment"
628 Many Lisp implementations don't provide a satisfactory environment
629 for scripts to run in.
630 The actual task of invoking a Lisp implementation
631 is left to configuration,
632 but the basic configuration supplied with
634 ensures the following facts about their environment.
646 Most Lisp systems support a user initialization file
647 which they load before entering the REPL;
648 some also have a system initialization file.
654 so that the Lisp environment is reasonably predictable,
655 and to avoid slowing down script startup
656 with things which are convenient for use in an interactive session,
657 but can't be relied upon by a script anyway.
659 The Unix standard input, standard output, and standard error files
660 are available through the Lisp
661 .BR *standard-input* ,
662 .BR *standard-output* ,
665 streams, respectively.
673 .B ext:*require-verbose*
675 Alas, this is insufficient to muffle noise while loading add-on systems
676 on some implementations.
678 If an error is signalled, and not caught by user code,
679 then the process will print a message to stderr
680 and exit with a nonzero status.
681 The reported message may be a long, ugly backtrace,
682 or a terse error report.
683 If no error is signalled but not caught,
684 then the process will exit with status 0.
686 The initial package is
687 .BR COMMON-LISP-USER ,
688 which has no symbols `present' (i.e., imported or interned).
694 systems are already loaded.
695 Further systems can be loaded using
699 (which is only meaningful if
704 and arguments are available through the
707 .B uiop:*command-line-arguments*
708 variable, respectively.
710 .\"--------------------------------------------------------------------------
714 Loading ASDF systems is irritatingly noisy
715 with some Lisp implementations.
716 Suggestions for how to improve this are welcome.
718 More Lisp implementations should be supported.
719 I've supported the ones I have installed.
720 I'm not willing to put a great deal of effort into supporting
721 non-free Lisp implementations;
722 but help supporting free Lisps is much appreciated.
724 The protocol for passing the script name through to
726 (specifically, through the
728 environment variable)
732 is obviously a better approach than introducing a
733 .BR runlisp -specific
734 interface to the same information.
735 I don't know how to fix this:
736 suggestions are welcome.
739 .BR dump-runlisp-image (1),
740 .BR query-runlisp-config (1),
741 .BR runlisp.conf (5).
744 Mark Wooding, <mdw@distorted.org.uk>
746 .\"----- That's all, folks --------------------------------------------------