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