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