chiark - git - mdw - runlisp/blob - runlisp.1.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for `runlisp'
   4 .\"
   5 .\" (c) 2020 Mark Wooding
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
  11 .\"
  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.
  16 .\"
  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
  20 .\" for more details.
  21 .\"
  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/>.
  24 .
  25 .ie t \{\
  26 .  ds o \(bu
  27 .  if \n(.g \{\
  28 .    fam P
  29 .    ev an-1
  30 .    fam P
  31 .    ev
  32 .  \}
  33 .\}
  34 .el \{\
  35 .  ds o o
  36 .\}
  37 .
  38 .de hP
  39 .IP
  40 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
  41 ..
  42 .ds .. \&.\|.\|.
  43 .
  44 .\"--------------------------------------------------------------------------
  45 .TH runlisp 1 "2 August 2020" "Mark Wooding"
  46 .SH NAME
  47 runlisp \- run Common Lisp programs as scripts
  48 .
  49 .\"--------------------------------------------------------------------------
  50 .SH SYNOPSIS
  51 .
  52 .B runlisp
  53 .RI [ options ]
  54 .RB [ \-\- ]
  55 .I script
  56 .RI [ arguments
  57 \*(..]
  58 .br
  59 .B runlisp
  60 .RI [ options ]
  61 .RB [ \-d
  62 .IR form ]
  63 .RB [ \-e
  64 .IR form ]
  65 .RB [ \-l
  66 .IR file ]
  67 .RB [ \-p
  68 .IR form ]
  69 .if !t \{\
  70 .br
  71         \c
  72 .\}
  73 .RB [ \-\- ]
  74 .RI [ arguments
  75 \*(..]
  76 .PP
  77 where
  78 .I options
  79 is
  80 .br
  81         \c
  82 .RB [ \-CDEnqv ]
  83 .RB [ +DEn ]
  84 .RB [ \-L
  85 .IB sys , sys , \fR\*(..]
  86 .if !t \{\
  87 .br
  88         \c
  89 .\}
  90 .RB [ \-c
  91 .IR conf ]
  92 .RB [ \-o
  93 .RI [ sect \c
  94 .BR : ] \c
  95 .IB var = \c
  96 .IR value ]
  97 .
  98 .\"--------------------------------------------------------------------------
  99 .SH DESCRIPTION
 100 .
 101 The
 102 .B runlisp
 103 program has two main functions.
 104 .hP 1.
 105 It can be used in a script's
 106 .RB ` #! '
 107 line to run a Common Lisp script.
 108 .hP 2.
 109 It can be used in build scripts
 110 to invoke a Common Lisp system,
 111 e.g., to build a standalone program.
 112 .
 113 .SS "Options"
 114 Options are read from the command line, as usual,
 115 but also (by default) from the script's second line,
 116 following a
 117 .RB ` @RUNLISP: '
 118 marker: see
 119 .B Operation
 120 below for the details.
 121 .
 122 .PP
 123 The options accepted are as follows.
 124 .
 125 .TP
 126 .BR "\-h" ", " "\-\-help"
 127 Write a synopsis of
 128 .BR query-runlisp-config 's
 129 command-line syntax
 130 and a description of the command-line options
 131 to standard output
 132 and immediately exit with status 0.
 133 .
 134 .TP
 135 .BR "\-V" ", " "\-\-version"
 136 Write
 137 .BR query-runlisp-config 's
 138 version number
 139 to standard output
 140 and immediately exit with status 0.
 141 .
 142 .TP
 143 .BR "\-D" ", " "\-\-vanilla-image"
 144 Don't check for a custom Lisp image.
 145 Usually,
 146 .B runlisp
 147 tries to start Lisp systems using a custom image,
 148 so that they'll start more quickly;
 149 the
 150 .RB ` \-D '
 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
 155 .B runlisp
 156 itself.
 157 Negate with
 158 .B +D
 159 or
 160 .BR \-\-no-vanilla-image .
 161 .
 162 .TP
 163 .BR "\-E" ", " "\-\-command-line-only"
 164 Don't read embedded options from the
 165 second line of the
 166 .I script
 167 file.
 168 Negate with
 169 .B +E
 170 or
 171 .BR \-\-no-command-line-only .
 172 This has no effect in eval mode.
 173 .
 174 .TP
 175 .BI "\-L" "\fR, " "\-\-accept-lisp=" sys , sys ,\fR\*(..
 176 Use one of the named Lisp systems.
 177 The
 178 .I sys
 179 names are separated by a comma
 180 .RB ` , '
 181 and/or one or more whitespace characters.
 182 This option may be given more than once:
 183 the effect is the same as a single option
 184 listing all of the systems named, in the same order.
 185 If a system is named more than once,
 186 a warning is issued (at verbosity level 1 or higher),
 187 and all but the first occurrence is ignored.
 188 System names which do not refer to known Lisp systems
 189 are silently ignored:
 190 otherwise, a script which supports an unusual Lisp system
 191 could never run at a site which doesn't have
 192 configuration runes for that Lisp system,
 193 even though they're useless
 194 if the system isn't actually installed.
 195 .
 196 .TP
 197 .BI "\-c" "\fR, " "\-\-config-file=" conf
 198 Read configuration from
 199 .IR conf .
 200 If
 201 .I conf
 202 is a directory, then all of the files within
 203 whose names end with
 204 .RB ` .conf ',
 205 are loaded, in ascending lexicographical order;
 206 otherwise,
 207 .I conf
 208 is opened as a file.
 209 All of the files are expected to be as described in
 210 .BR runlisp.conf (5).
 211 .
 212 .TP
 213 .BI "\-d" "\fR, " "\-\-dump-expression=" expr
 214 Evaluate the expression(s)
 215 .I expr
 216 and print the resulting value(s)
 217 to standard output
 218 (with
 219 .B *print-escape*
 220 true, as if by
 221 .BR prin1 ).
 222 If a form produces multiple values,
 223 they are printed on a single line,
 224 separated by a single space character;
 225 if a form produces no values at all,
 226 then nothing is printed \(en not even a newline character.
 227 This option causes
 228 .B runlisp
 229 to execute in
 230 .I eval
 231 mode.
 232 See also
 233 .RB ` \-p ',
 234 which prints with
 235 .B *print-escape*
 236 false.
 237 .
 238 .TP
 239 .BI "\-e" "\fR, " "\-\-evaluate-expression=" expr
 240 Evaluate the expression(s)
 241 .I expr
 242 and discard the resulting values.
 243 This option causes
 244 .B runlisp
 245 to execute in
 246 .I eval
 247 mode.
 248 .
 249 .TP
 250 .BI "\-l" "\fR, " "\-\-load-file=" file
 251 Read and evaluate forms from the
 252 .IR file .
 253 This option causes
 254 .B runlisp
 255 to execute in
 256 .I eval
 257 mode.
 258 .
 259 .TP
 260 .BR "\-n" ", " "\-\-dry-run"
 261 Don't actually start the Lisp environment.
 262 This may be helpful for the curious,
 263 in conjunction with
 264 .RB ` \-v '
 265 to increase the verbosity.
 266 Negate with
 267 .B +n
 268 or
 269 .BR "\-\-no-dry-run" .
 270 .
 271 .TP
 272 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect :\fR] var = value
 273 Assign
 274 .I value
 275 to the variable
 276 .I var
 277 in configuration section
 278 .IR sect ,
 279 or
 280 .B @CONFIG
 281 if no section is specified.
 282 The value is unexpandable,
 283 and overrides any similarly named setting
 284 from the configuration file(s).
 285 .
 286 .TP
 287 .BI "\-p" "\fR, " "\-\-print-expression=" expr
 288 Evaluate the expression(s)
 289 .I expr
 290 and print the resulting value(s)
 291 to standard output
 292 (with
 293 .B *print-escape*
 294 false, as if by
 295 .BR princ ).
 296 If a form produces multiple values,
 297 they are printed on a single line,
 298 separated by a single space character;
 299 if a form produces no values at all,
 300 then nothing is printed \(en not even a newline character.
 301 This option causes
 302 .B runlisp
 303 to execute in
 304 .I eval
 305 mode.
 306 See also
 307 .RB ` \-d ',
 308 which prints with
 309 .B *print-escape*
 310 true.
 311 .
 312 .TP
 313 .BR "\-q" ", " "\-\-quiet"
 314 Don't print warning messages.
 315 This option may be repeated:
 316 each use reduces verbosity by one step,
 317 counteracting one
 318 .RB ` \-v '
 319 option.
 320 The default verbosity level is 1,
 321 which prints only warning measages.
 322 .
 323 .TP
 324 .BR "\-v" ", " "\-\-verbose"
 325 Print informational or debugging messages.
 326 This option may be repeated:
 327 each use increases verbosity by one step,
 328 counteracting one
 329 .RB ` \-q '
 330 option.
 331 The default verbosity level is 1,
 332 which prints only warning measages.
 333 Higher verbosity levels print informational and debugging messages.
 334 .
 335 .PP
 336 The
 337 .RB ` \-d ',
 338 .RB ` \-e ',
 339 .RB ` \-l ',
 340 and
 341 .RB ` \-p '
 342 options may only be given on the command-line itself,
 343 not following a
 344 .RB ` @RUNLISP: '
 345 marker in a script.
 346 These options may be given multiple times:
 347 they will be processed in the order given.
 348 If any of these options is given, then no
 349 .I script
 350 name will be parsed;
 351 instead, use
 352 .RB ` \-l '
 353 to load code from files.
 354 The
 355 .IR arguments ,
 356 if any,
 357 are still made available to the evaluated forms and loaded files.
 358 .
 359 .SS "Operation"
 360 The
 361 .B runlisp
 362 program behaves as follows.
 363 .
 364 .hP 1.
 365 The first thing it does is parse its command line.
 366 Options must precede positional arguments,
 367 though the boundary may be marked explicitly using
 368 .RB ` \-\- '
 369 if desired.
 370 If the command line contains any of
 371 .RB ` \-d ',
 372 .RB ` \-e ',
 373 .RB ` \-l ',
 374 or
 375 .RB ` \-p ',
 376 then
 377 .B runlisp
 378 treats all of its positional arguments as
 379 .I arguments
 380 to provide to the given forms and files,
 381 and runs in
 382 .I eval
 383 mode;
 384 otherwise, the first positional argument becomes the
 385 .I script
 386 name, the remaining ones become
 387 .IR arguments ,
 388 and
 389 .B runlisp
 390 runs in
 391 .I script
 392 mode.
 393 .hP 2.
 394 In
 395 .I script
 396 mode,
 397 and if the
 398 .RB ` \-E '
 399 option was not given,
 400 .B runlisp
 401 reads the second line of the script file,
 402 and checks to see if it contains the string
 403 .RB ` @RUNLISP: '.
 404 If so, then the following text is parsed
 405 for
 406 .IR "embedded options" ,
 407 as follows.
 408 .RS
 409 .PP
 410 The text is split into words
 411 separated by sequences of whitespace characters.
 412 Whitespace,
 413 and other special characters,
 414 can be included in a word by
 415 .I quoting
 416 or
 417 .IR escaping .
 418 Text between single quotes
 419 .BR ' \*(.. '
 420 is included literally, without any further interpretation;
 421 text between double quotes
 422 .BR """" \*(.. """"
 423 is treated literally,
 424 except that escaping can still be used
 425 to escape (e.g.) double quotes and the escape character itself.
 426 Outside of single quotes, a backslash
 427 .RB ` \e '
 428 causes the following character to be included in a word
 429 regardless of its usual meaning.
 430 (None of this allows a newline character
 431 to be included in a word:
 432 this is simply not possible.)
 433 A word which is
 434 .RB ` \-\- '
 435 before processing quoting and escaping
 436 marks the end of embedded options.
 437 As a concession to Emacs users,
 438 if the sequence
 439 .RB ` \-*\- '
 440 appears at the start of a word
 441 before processing quoting and escaping,
 442 then everything up to and including the next occurrence of
 443 .RB ` \-*\- '
 444 is ignored.
 445 .PP
 446 The resulting list of words
 447 is processed as if it held further command-line options.
 448 Currently, only
 449 .RB ` \-D '
 450 and
 451 .RB ` \-L '
 452 options are permitted in embedded option lists:
 453 .RB ` \-h '
 454 and
 455 .RB ` \-v '
 456 are clearly only useful in interactive use;
 457 setting
 458 .RB ` \-q '
 459 or
 460 .RB ` \-v '
 461 would just be annoying;
 462 setting
 463 .RB ` \-c '
 464 or
 465 .RB ` \-o '
 466 would override the user's command-line settings;
 467 it's clearly too late to set
 468 .RB ` \-E ';
 469 and
 470 .B runlisp
 471 is now committed to
 472 .I script
 473 mode, so it's too late for
 474 .RB ` \-d ',
 475 .RB ` \-e ',
 476 .RB ` \-l ',
 477 and
 478 .RB ` \-p '
 479 too.
 480 .PP
 481 (This feature allows scripts to provide options even if they use
 482 .BR env (1)
 483 to find
 484 .B runlisp
 485 on the
 486 .BR PATH ,
 487 or to provide more than one option,
 488 since many operating systems pass the text following
 489 the interpreter name on a
 490 .RB ` #! '
 491 line as a single argument, without further splitting it at spaces.)
 492 .RE
 493 .
 494 .hP 3.
 495 If no
 496 .RB ` \-c '
 497 options were given,
 498 then the default configuration files are read:
 499 the system configuration from
 500 .B @etcdir@/runlisp.conf
 501 and
 502 .BR @etcdir@/runlisp.d/*.conf ,
 503 and the user configuration from
 504 .B ~/.runlisp.conf
 505 and/or
 506 .BR ~/.config/runlisp.conf :
 507 see
 508 .RB runlisp.conf (5)
 509 for the details.
 510 .
 511 .hP 4.
 512 The list of
 513 .I "acceptable Lisp implementations"
 514 is determined.
 515 If any
 516 .RB ` \-L '
 517 options have been found,
 518 then the list of acceptable implementations
 519 consists of all of the implementations mentioned in
 520 .RB ` \-L '
 521 options
 522 in any of the places
 523 .B runlisp
 524 looked for options,
 525 in the order of their first occurrence.
 526 (If an implementation is named more than once,
 527 then
 528 .B runlisp
 529 prints a warning to stderr
 530 and ignores all but the first occurrence.)
 531 If no
 532 .RB ` \-L '
 533 option is given, then
 534 .B runlisp
 535 uses a default list,
 536 which consists of all of the Lisp implementations
 537 defined in its configuration,
 538 in the order in which they were defined.
 539 .
 540 .hP 5.
 541 The list of
 542 .I "preferred Lisp implementations"
 543 is determined.
 544 If the environment variable
 545 .B RUNLISP_PREFER
 546 is set,
 547 then its value should be a list of names of Lisp implementations
 548 separated by a comma and/or one or more whitespace characters.
 549 Otherwise, if there is a setting for the variable
 550 .B prefer
 551 in the
 552 .B @CONFIG
 553 configuration section,
 554 then its (expanded) value should be a list of Lisp implementations,
 555 in the same way.
 556 Otherwise, the list of preferred implementations is empty.
 557 .
 558 .hP 6.
 559 If
 560 .B runlisp
 561 is running in
 562 .I eval
 563 mode, then a new command line is built,
 564 which invokes an internal script,
 565 instructing it to evaluate and print the requested expressions,
 566 and load the requested files.
 567 .
 568 .hP 7.
 569 Acceptable Lisp implementations are tried in turn.
 570 First, the preferred implementations
 571 which are also listed as acceptable implementations
 572 are tried, in the order in which they appear
 573 in the preferred implementations list;
 574 then, the remaining acceptable implementations are tried
 575 in the order in which they appear
 576 in the acceptable implementations list.
 577 .RS
 578 .PP
 579 A Lisp implementation is defined by a configuration section
 580 which defines a variable
 581 .BR run-script .
 582 The name of the configuration section
 583 is the name of the Lisp implementation,
 584 as used in the acceptable and preferred lists described above.
 585 .hP (a)
 586 The variable
 587 .B image-file
 588 is looked up in the configuration section.
 589 If a value is found, then
 590 .B runlisp
 591 looks up and expands
 592 .BR image-path ,
 593 and checks to see if a file exists with the resulting name.
 594 If so, it sets the variable
 595 .B @image
 596 to
 597 .B t
 598 in the configuration section.
 599 .hP (b)
 600 The variable
 601 .B run-script
 602 is expanded and word-split.
 603 The
 604 .I script
 605 (an internal script, in
 606 .I eval
 607 mode)
 608 and
 609 .IR argument s
 610 are appended, and
 611 the entire list is passed to the
 612 .BR execvp (3)
 613 function.
 614 If that succeeds, the Lisp implementation runs;
 615 if it fails with
 616 .B ENOENT
 617 then other Lisp systems are tried;
 618 if it fails with some other error, then
 619 .B runlisp
 620 reports an error message to stderr
 621 and exits unsuccessfully
 622 (with code 127).
 623 If the
 624 .RB ` \-n '
 625 option was given, then
 626 .B runlisp
 627 just simulates the behaviour of
 628 .BR execvp (3),
 629 printing messages to stderr
 630 if the verbosity level is sufficiently high,
 631 and exits.
 632 .
 633 .SS "Script environment"
 634 Many Lisp implementations don't provide a satisfactory environment
 635 for scripts to run in.
 636 The actual task of invoking a Lisp implementation
 637 is left to configuration,
 638 but the basic configuration supplied with
 639 .B runlisp
 640 ensures the following facts about their environment.
 641 .hP \*o
 642 The keyword
 643 .B :runlisp-script
 644 is added to the
 645 .B *features*
 646 list if
 647 .B runlisp
 648 is running in
 649 .I script
 650 mode.
 651 .hP \*o
 652 Most Lisp systems support a user initialization file
 653 which they load before entering the REPL;
 654 some also have a system initialization file.
 655 The
 656 .B runlisp
 657 program arranges
 658 .I not
 659 to read these files,
 660 so that the Lisp environment is reasonably predictable,
 661 and to avoid slowing down script startup
 662 with things which are convenient for use in an interactive session,
 663 but can't be relied upon by a script anyway.
 664 .hP \*o
 665 The Unix standard input, standard output, and standard error files
 666 are available through the Lisp
 667 .BR *standard-input* ,
 668 .BR *standard-output* ,
 669 and
 670 .BR *error-output*
 671 streams, respectively.
 672 .hP \*o
 673 Both
 674 .B *compile-verbose*
 675 and
 676 .B *load-verbose*
 677 are set to nil.
 678 On CMU\ CL,
 679 .B ext:*require-verbose*
 680 is also nil.
 681 Alas, this is insufficient to muffle noise while loading add-on systems
 682 on some implementations.
 683 .hP \*o
 684 If an error is signalled, and not caught by user code,
 685 then the process will print a message to stderr
 686 and exit with a nonzero status.
 687 The reported message may be a long, ugly backtrace,
 688 or a terse error report.
 689 If no error is signalled but not caught,
 690 then the process will exit with status 0.
 691 .hP \*o
 692 The initial package is
 693 .BR COMMON-LISP-USER ,
 694 which has no symbols `present' (i.e., imported or interned).
 695 .hP \*o
 696 The
 697 .B asdf
 698 and
 699 .B uiop
 700 systems are already loaded.
 701 Further systems can be loaded using
 702 .B asdf:load-system
 703 as usual.
 704 The script name
 705 (which is only meaningful if
 706 .B runlisp
 707 is in
 708 .I script
 709 mode, obviously)
 710 and arguments are available through the
 711 .B uiop:argv0
 712 function and
 713 .B uiop:*command-line-arguments*
 714 variable, respectively.
 715 .
 716 .\"--------------------------------------------------------------------------
 717 .
 718 .SH BUGS
 719 .hP \*o
 720 Loading ASDF systems is irritatingly noisy
 721 with some Lisp implementations.
 722 Suggestions for how to improve this are welcome.
 723 .hP \*o
 724 More Lisp implementations should be supported.
 725 I've supported the ones I have installed.
 726 I'm not willing to put a great deal of effort into supporting
 727 non-free Lisp implementations;
 728 but help supporting free Lisps is much appreciated.
 729 .hP \*o
 730 The protocol for passing the script name through to
 731 .B uiop
 732 (specifically, through the
 733 .B __CL_ARGV0
 734 environment variable)
 735 is terribly fragile,
 736 but supporting
 737 .B uiop
 738 is obviously a better approach than introducing a
 739 .BR runlisp -specific
 740 interface to the same information.
 741 I don't know how to fix this:
 742 suggestions are welcome.
 743 .
 744 .SH SEE ALSO
 745 .BR dump-runlisp-image (1),
 746 .BR query-runlisp-config (1),
 747 .BR runlisp.conf (5).
 748 .
 749 .SH AUTHOR
 750 Mark Wooding, <mdw@distorted.org.uk>
 751 .
 752 .\"----- That's all, folks --------------------------------------------------