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 .
 174 .TP
 175 .BI "\-L" "\fR, " "\-\-accept-lisp=" sys , sys ,\fR\*(..
 176 Use one of the named Lisp systems.
 177 Each
 178 .I sys
 179 must name a supported Lisp system;
 180 the names are separated by a comma
 181 .RB ` , '
 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.
 189 .
 190 .TP
 191 .BI "\-c" "\fR, " "\-\-config-file=" conf
 192 Read configuration from
 193 .IR conf .
 194 If
 195 .I conf
 196 is a directory, then all of the files within
 197 whose names end with
 198 .RB ` .conf ',
 199 are loaded, in ascending lexicographical order;
 200 otherwise,
 201 .I conf
 202 is opened as a file.
 203 All of the files are expected to be as described in
 204 .BR runlisp.conf (5).
 205 .
 206 .TP
 207 .BI "\-d" "\fR, " "\-\-dump-expression=" expr
 208 Evaluate the expression(s)
 209 .I expr
 210 and print the resulting value(s)
 211 to standard output
 212 (with
 213 .B *print-escape*
 214 true, as if by
 215 .BR prin1 ).
 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.
 221 This option causes
 222 .B runlisp
 223 to execute in
 224 .I eval
 225 mode.
 226 See also
 227 .RB ` \-p ',
 228 which prints with
 229 .B *print-escape*
 230 false.
 231 .
 232 .TP
 233 .BI "\-e" "\fR, " "\-\-evaluate-expression=" expr
 234 Evaluate the expression(s)
 235 .I expr
 236 and discard the resulting values.
 237 This option causes
 238 .B runlisp
 239 to execute in
 240 .I eval
 241 mode.
 242 .
 243 .TP
 244 .BI "\-l" "\fR, " "\-\-load-file=" file
 245 Read and evaluate forms from the
 246 .IR file .
 247 This option causes
 248 .B runlisp
 249 to execute in
 250 .I eval
 251 mode.
 252 .
 253 .TP
 254 .BR "\-n" ", " "\-\-dry-run"
 255 Don't actually start the Lisp environment.
 256 This may be helpful for the curious,
 257 in conjunction with
 258 .RB ` \-v '
 259 to increase the verbosity.
 260 Negate with
 261 .B +n
 262 or
 263 .BR "\-\-no-dry-run" .
 264 .
 265 .TP
 266 .BI "\-o" "\fR, " "\-\-set-option=\fR[" sect :\fR] var = value
 267 Assign
 268 .I value
 269 to the variable
 270 .I var
 271 in configuration section
 272 .IR sect ,
 273 or
 274 .B @CONFIG
 275 if no section is specified.
 276 The value is unexpandable,
 277 and overrides any similarly named setting
 278 from the configuration file(s).
 279 .
 280 .TP
 281 .BI "\-p" "\fR, " "\-\-print-expression=" expr
 282 Evaluate the expression(s)
 283 .I expr
 284 and print the resulting value(s)
 285 to standard output
 286 (with
 287 .B *print-escape*
 288 false, as if by
 289 .BR princ ).
 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.
 295 This option causes
 296 .B runlisp
 297 to execute in
 298 .I eval
 299 mode.
 300 See also
 301 .RB ` \-d ',
 302 which prints with
 303 .B *print-escape*
 304 true.
 305 .
 306 .TP
 307 .BR "\-q" ", " "\-\-quiet"
 308 Don't print warning messages.
 309 This option may be repeated:
 310 each use reduces verbosity by one step,
 311 counteracting one
 312 .RB ` \-v '
 313 option.
 314 The default verbosity level is 1,
 315 which prints only warning measages.
 316 .
 317 .TP
 318 .BR "\-v" ", " "\-\-verbose"
 319 Print informational or debugging messages.
 320 This option may be repeated:
 321 each use increases verbosity by one step,
 322 counteracting one
 323 .RB ` \-q '
 324 option.
 325 The default verbosity level is 1,
 326 which prints only warning measages.
 327 Higher verbosity levels print informational and debugging messages.
 328 .
 329 .PP
 330 The
 331 .RB ` \-d ',
 332 .RB ` \-e ',
 333 .RB ` \-l ',
 334 and
 335 .RB ` \-p '
 336 options may only be given on the command-line itself,
 337 not following a
 338 .RB ` @RUNLISP: '
 339 marker in a script.
 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
 343 .I script
 344 name will be parsed;
 345 instead, use
 346 .RB ` \-l '
 347 to load code from files.
 348 The
 349 .IR arguments ,
 350 if any,
 351 are still made available to the evaluated forms and loaded files.
 352 .
 353 .SS "Operation"
 354 The
 355 .B runlisp
 356 program behaves as follows.
 357 .
 358 .hP 1.
 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
 362 .RB ` \-\- '
 363 if desired.
 364 If the command line contains any of
 365 .RB ` \-d ',
 366 .RB ` \-e ',
 367 .RB ` \-l ',
 368 or
 369 .RB ` \-p ',
 370 then
 371 .B runlisp
 372 treats all of its positional arguments as
 373 .I arguments
 374 to provide to the given forms and files,
 375 and runs in
 376 .I eval
 377 mode;
 378 otherwise, the first positional argument becomes the
 379 .I script
 380 name, the remaining ones become
 381 .IR arguments ,
 382 and
 383 .B runlisp
 384 runs in
 385 .I script
 386 mode.
 387 .hP 2.
 388 In
 389 .I script
 390 mode,
 391 and if the
 392 .RB ` \-E '
 393 option was not given,
 394 .B runlisp
 395 reads the second line of the script file,
 396 and checks to see if it contains the string
 397 .RB ` @RUNLISP: '.
 398 If so, then the following text is parsed
 399 for
 400 .IR "embedded options" ,
 401 as follows.
 402 .RS
 403 .PP
 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 .PP
 440 The resulting list of words
 441 is processed as if it held further command-line options.
 442 Currently, only
 443 .RB ` \-D '
 444 and
 445 .RB ` \-L '
 446 options are permitted in embedded option lists:
 447 .RB ` \-h '
 448 and
 449 .RB ` \-v '
 450 are clearly only useful in interactive use;
 451 setting
 452 .RB ` \-q '
 453 or
 454 .RB ` \-v '
 455 would just be annoying;
 456 setting
 457 .RB ` \-c '
 458 or
 459 .RB ` \-o '
 460 would override the user's command-line settings;
 461 it's clearly too late to set
 462 .RB ` \-E ';
 463 and
 464 .B runlisp
 465 is now committed to
 466 .I script
 467 mode, so it's too late for
 468 .RB ` \-d ',
 469 .RB ` \-e ',
 470 .RB ` \-l ',
 471 and
 472 .RB ` \-p '
 473 too.
 474 .PP
 475 (This feature allows scripts to provide options even if they use
 476 .BR env (1)
 477 to find
 478 .B runlisp
 479 on the
 480 .BR PATH ,
 481 or to provide more than one option,
 482 since many operating systems pass the text following
 483 the interpreter name on a
 484 .RB ` #! '
 485 line as a single argument, without further splitting it at spaces.)
 486 .RE
 487 .
 488 .hP 3.
 489 If no
 490 .RB ` \-c '
 491 options were given,
 492 then the default configuration files are read:
 493 the system configuration from
 494 .B @etcdir@/runlisp.conf
 495 and
 496 .BR @etcdir@/runlisp.d/*.conf ,
 497 and the user configuration from
 498 .B ~/.runlisp.conf
 499 and/or
 500 .BR ~/.config/runlisp.conf :
 501 see
 502 .RB runlisp.conf (5)
 503 for the details.
 504 .
 505 .hP 4.
 506 The list of
 507 .I "acceptable Lisp implementations"
 508 is determined.
 509 If any
 510 .RB ` \-L '
 511 options have been found,
 512 then the list of acceptable implementations
 513 consists of all of the implementations mentioned in
 514 .RB ` \-L '
 515 options
 516 in any of the places
 517 .B runlisp
 518 looked for options,
 519 in the order of their first occurrence.
 520 (If an implementation is named more than once,
 521 then
 522 .B runlisp
 523 prints a warning to stderr
 524 and ignores all but the first occurrence.)
 525 If no
 526 .RB ` \-L '
 527 option is given, then
 528 .B runlisp
 529 uses a default list,
 530 which consists of all of the Lisp implementations
 531 defined in its configuration,
 532 in the order in which they were defined.
 533 .
 534 .hP 5.
 535 The list of
 536 .I "preferred Lisp implementations"
 537 is determined.
 538 If the environment variable
 539 .B RUNLISP_PREFER
 540 is set,
 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
 544 .B prefer
 545 in the
 546 .B @CONFIG
 547 configuration section,
 548 then its (expanded) value should be a list of Lisp implementations,
 549 in the same way.
 550 Otherwise, the list of preferred implementations is empty.
 551 .
 552 .hP 6.
 553 If
 554 .B runlisp
 555 is running in
 556 .I eval
 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.
 561 .
 562 .hP 7.
 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.
 571 .RS
 572 .PP
 573 A Lisp implementation is defined by a configuration section
 574 which defines a variable
 575 .BR run-script .
 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.
 579 .hP (a)
 580 The variable
 581 .B image-file
 582 is looked up in the configuration section.
 583 If a value is found, then
 584 .B runlisp
 585 looks up and expands
 586 .BR image-path ,
 587 and checks to see if a file exists with the resulting name.
 588 If so, it sets the variable
 589 .B @image
 590 to
 591 .B t
 592 in the configuration section.
 593 .hP (b)
 594 The variable
 595 .B run-script
 596 is expanded and word-split.
 597 The
 598 .I script
 599 (an internal script, in
 600 .I eval
 601 mode)
 602 and
 603 .IR argument s
 604 are appended, and
 605 the entire list is passed to the
 606 .BR execvp (3)
 607 function.
 608 If that succeeds, the Lisp implementation runs;
 609 if it fails with
 610 .B ENOENT
 611 then other Lisp systems are tried;
 612 if it fails with some other error, then
 613 .B runlisp
 614 reports an error message to stderr
 615 and exits unsuccessfully
 616 (with code 127).
 617 If the
 618 .RB ` \-n '
 619 option was given, then
 620 .B runlisp
 621 just simulates the behaviour of
 622 .BR execvp (3),
 623 printing messages to stderr
 624 if the verbosity level is sufficiently high,
 625 and exits.
 626 .
 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
 633 .B runlisp
 634 ensures the following facts about their environment.
 635 .hP \*o
 636 The keyword
 637 .B :runlisp-script
 638 is added to the
 639 .B *features*
 640 list if
 641 .B runlisp
 642 is running in
 643 .I script
 644 mode.
 645 .hP \*o
 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.
 649 The
 650 .B runlisp
 651 program arranges
 652 .I not
 653 to read these files,
 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.
 658 .hP \*o
 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* ,
 663 and
 664 .BR *error-output*
 665 streams, respectively.
 666 .hP \*o
 667 Both
 668 .B *compile-verbose*
 669 and
 670 .B *load-verbose*
 671 are set to nil.
 672 On CMU\ CL,
 673 .B ext:*require-verbose*
 674 is also nil.
 675 Alas, this is insufficient to muffle noise while loading add-on systems
 676 on some implementations.
 677 .hP \*o
 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.
 685 .hP \*o
 686 The initial package is
 687 .BR COMMON-LISP-USER ,
 688 which has no symbols `present' (i.e., imported or interned).
 689 .hP \*o
 690 The
 691 .B asdf
 692 and
 693 .B uiop
 694 systems are already loaded.
 695 Further systems can be loaded using
 696 .B asdf:load-system
 697 as usual.
 698 The script name
 699 (which is only meaningful if
 700 .B runlisp
 701 is in
 702 .I script
 703 mode, obviously)
 704 and arguments are available through the
 705 .B uiop:argv0
 706 function and
 707 .B uiop:*command-line-arguments*
 708 variable, respectively.
 709 .
 710 .\"--------------------------------------------------------------------------
 711 .
 712 .SH BUGS
 713 .hP \*o
 714 Loading ASDF systems is irritatingly noisy
 715 with some Lisp implementations.
 716 Suggestions for how to improve this are welcome.
 717 .hP \*o
 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.
 723 .hP \*o
 724 The protocol for passing the script name through to
 725 .B uiop
 726 (specifically, through the
 727 .B __CL_ARGV0
 728 environment variable)
 729 is terribly fragile,
 730 but supporting
 731 .B uiop
 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.
 737 .
 738 .SH SEE ALSO
 739 .BR dump-runlisp-image (1),
 740 .BR query-runlisp-config (1),
 741 .BR runlisp.conf (5).
 742 .
 743 .SH AUTHOR
 744 Mark Wooding, <mdw@distorted.org.uk>
 745 .
 746 .\"----- That's all, folks --------------------------------------------------