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