mdw@git.distorted.org.uk Git - runlisp/blob - runlisp.1

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