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