X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/runlisp/blobdiff_plain/8996f767e047eefa8af4d01b1434b54f4c169b79..60f1d5fe519c30e68be464696ce9c4ad56a6b050:/README.org diff --git a/README.org b/README.org index 91f3ef8..62f5216 100644 --- a/README.org +++ b/README.org @@ -3,6 +3,8 @@ #+AUTHOR: Mark Wooding #+LaTeX_CLASS: strayman #+LaTeX_HEADER: \usepackage{tikz, gnuplot-lua-tikz} +#+LaTeX_HEADER: \DeclareUnicodeCharacter{200B}{} +#+EXPORT_FILE_NAME: doc/README.pdf ~runlisp~ is a small C program intended to be run from a script ~#!~ line. It selects and invokes a Common Lisp implementation, so as to run @@ -14,7 +16,7 @@ Currently, the following Lisp implementations are supported: + Armed Bear Common Lisp (~abcl~), + Clozure Common Lisp (~ccl~), + GNU CLisp (~clisp~), - + Carnegie--Mellon Univerity Common Lisp (~cmucl~), and + + Carnegie--Mellon Univerity Common Lisp (~cmucl~), + Embeddable Common Lisp (~ecl~), and + Steel Bank Common Lisp (~sbcl~). @@ -23,7 +25,8 @@ configuration file. Of course, there's a benefit to having a collection of high-quality configuration runes curated centrally, so I'm happy to accept submissions in support of any free[fn:free] Lisp implementations. -[fn:free] Here I mean free as in freedom. +[fn:free] Here I mean `free' as in freedom: see +https://www.fsf.org/about/what-is-free-software. * Writing scripts in Common Lisp @@ -67,6 +70,13 @@ in the ~-L~ option, separated by commas: : #-(or sbcl ccl) "an unexpected" : " Common Lisp!~%")) +It is not an error to include the name of an unrecognized Lisp system in +the ~-L~ option: such names are simply ignored. This allows a script to +declare support for unusual or locally installed Lisp systems without +compromising its portability to sites where such systems are unknown, or +which are still running older versions of ~runlisp~ which haven't been +updated with the necessary configuration for those systems. + ** Embedded options If your script requires features of particular Lisp implementations @@ -112,7 +122,7 @@ For example: + The prevailing Unix standard input, output, and error files are available through the Lisp ~*standard-input*~, ~*standard-output*~, - and ~*error-ouptut*~ streams, respectively. (This is, alas, not a + and ~*error-output*~ streams, respectively. (This is, alas, not a foregone conclusion.) + The keyword ~:runlisp-script~ is added to the ~*features*~ list. @@ -150,24 +160,32 @@ command-line interface for evaluating Lisp forms. For example: : 3 If your build script needs to get information out of Lisp, then wrapping -~format~, or even ~prin1~, around forms is annoying; so ~runlisp~ has a +~format~, or even ~princ~, around forms is annoying; so ~runlisp~ has a ~-p~ option which prints the values of the forms it evaluates. : $ runlisp -e '(+ 1 2)' : 3 -If a form produces multiple values, then ~-p~ will print all of them -separated by spaces, on a single line: +If a form produces multiple values, then ~-p~ will print all of them, as +if by ~princ~, separated by spaces, on a single line: : $ runlisp -p '(floor 5 2)' : 2 1 +There's also a ~-d~ option, which does the same thing as ~-p~, only it +prints values as if by ~prin1~. For example, + +: $ runlisp -p '"Hello, world!"' +: Hello, world! +: $ runlisp -d '"Hello, world!"' +: "Hello, world!" + In addition to evaluating forms with ~-e~, and printing their values -with ~-p~, you can also load a file of Lisp code using ~-l~. +with ~-d~ and ~-p~, you can also load a file of Lisp code using ~-l~. When ~runlisp~ is acting on ~-e~, ~-p~, and/or ~-l~ options, it's said to be running in /eval/ mode, rather than its usual /script/ mode. In -script mode, it /doesn't/ set ~:runlisp-script~ in ~*features*~. +eval mode, it /doesn't/ set ~:runlisp-script~ in ~*features*~. You can still insist that ~runlisp~ use a particular Lisp implementation, or one of a subset of implementations, using the ~-L~ @@ -208,7 +226,7 @@ The ~runlisp~ program looks for configuration in a number of places. All of the files in this directory named ~SOMETHING.conf~ are read, in increasing lexicographical order by name. The package comes with a file ~0base.conf~ intended to be read first, so that it can be - overridden if necessar. This sets up basic definitions, and defines + overridden if necessary. This sets up basic definitions, and defines the necessary runes for those Lisp implementations which are supported `out of the box'. New Lisp packages might come with additional files to drop into this directory. @@ -224,14 +242,25 @@ The ~runlisp~ program looks for configuration in a number of places. directories to add support for privately installed Lisp systems, or to override settings made by earlier configuration files. -The configuration syntax is complicated, and explained in detail in the -*runlisp.conf* manpage. +Configuration files generally look like =.ini=-style files. A line +beginning with a semicolon ~;~ is a comment and is ignored. Most lines +are assignments, which look like +#+BEGIN_QUOTE +/name/ ~=~ /value/ +#+END_QUOTE +and assignments are split into sections by section headers in square +brackets: +#+BEGIN_QUOTE +~[~\relax{}/section/\relax{}~]~ +#+END_QUOTE +The details of the configuration syntax are complicated, and explained +in the *runlisp.conf* manpage. Configuration options can also be set on the command line, though the effects are subtly different. Again, see the manual pages for details. [fn:xdg-config] More properly, in ~$XDG_CONFIG_HOME/runlisp.conf~, if -you set that. +you set that variable. ** Deciding which Lisp implementation to use @@ -240,7 +269,12 @@ The ~prefer~ option specifies a /preference list/ of Lisp implementations. The value is a list of Lisp implementation names, as you'd give to ~-L~, separated by commas and/or spaces. If the environment variable ~RUNLISP_PREFER~ is set, then this overrides any -value found in the configuration files. +value found in the configuration files. So your ~$HOME/.runlisp.conf~ +file might look like this: + +: ;;; -*-conf-*- +: +: prefer = sbcl, clisp When deciding which Lisp implementation to use, ~runlisp~ works as follows. It builds a list of /acceptable/ Lisp implementations from the @@ -264,15 +298,14 @@ as possible. An awkward Lisp will of course cause trouble, but ~runlisp~ itself is easy. As a simple example, let's add support for the 32-bit version of -Clozure~CL. The source code for Clozure~CL easily builds both 32- and -64-bit binaries in either 32- or 64-bit userlands, and one might -reasonably want to use the 32-bit CCL for some reason. The following -configuration stanza is sufficient +Clozure\nbsp{}CL. The source code for Clozure\nbsp{}CL easily builds +both 32- and 64-bit binaries in either 32- or 64-bit userlands, and one +might reasonably want to use the 32-bit CCL for some reason. The +following configuration stanza is sufficient : [ccl32] : @PARENTS = ccl : command = ${@ENV:CCL32?ccl32} -: image-file = ccl32+asdf.image + The first line heads a configuration section, providing the name which will be used for this Lisp implementation, e.g., in ~-L~ @@ -296,7 +329,9 @@ Lisp. (SBCL's command-line interface is well thought-out, so this is an ideal opportunity to explain how ~runlisp~ configuration works, without getting bogged down in the details of fighting less amenable Lisps.) -The provided ~0base.conf~ file defines SBCL as follows. +The provided ~0base.conf~ file used to define SBCL as follows. (The +real version now contains a kludge for old versions, which needn't +concern us here.) : [sbcl] : @@ -345,8 +380,9 @@ Let's take this in slightly larger pieces. we add the tokens ~--core "${image-path}" --eval "${image-restore}"~ to the SBCL command line; otherwise, we add ~--eval "${run-script-prelude}"~. The ~@IMAGE~ setting is defined by - ~runlisp~ only if (a)~a custom image was found in the correct placem - and (b)~use of custom images isn't disabled on its command line. + ~runlisp~ only if (a)\nbsp{}a custom image was found in the correct + place, and (b)\nbsp{}use of custom images isn't disabled on its + command line. The ~${image-path}~ token expands to the full pathname to the custom image file; ~image-restore~ is a predefined Lisp expression to be @@ -371,9 +407,9 @@ Let's take this in slightly larger pieces. it's very similar to ~run-script-prelude~, and is built out of many of the same pieces. - The thing we haven't seen before is ~${@IMAENEW|q}~. The + The thing we haven't seen before is ~${@IMAGENEW|q}~. The ~@IMAGENEW~ setting is defined by the ~dump-runlisp-image~ program - the name the file in which the new image should be + to name the file in which the new image should be saved.[fn:image-rename] The ~|q~ `filter' is new: it means that the filename should be escaped suitable for inclusion in a Lisp quoted string, by prefixing each ~\~ or ~"~ with a ~\~. @@ -410,8 +446,8 @@ I timed how long it took to run on all of ~runlisp~'s supported Lisp implementations, and compared them to how long ~cl-launch~ took: the results are shown in table [[tab:runlisp-vanilla]]. ~runlisp~ is /at least/ two and half times faster at running this script than ~cl-launch~ on all -implementations except Clozure CL[fn:slow-ccl], and approaching four and -a half times faster on SBCL. +implementations except Clozure\nbsp{}CL[fn:slow-ccl], and approaching +four and a half times faster on SBCL. #+CAPTION: ~cl-launch~ vs ~runlisp~ (with vanilla images) #+NAME: tab:runlisp-vanilla @@ -494,8 +530,8 @@ XPS13 laptop running Debian `buster'. The tools used to make the measurements are included in the source distribution, in the ~bench/~ subdirectory.) -[fn:slow-ccl] I don't know why Clozure CL shows such a small difference -here. +[fn:slow-ccl] I don't know why Clozure\nbsp{}CL shows such a small +difference here. ** It's inconvenient @@ -538,7 +574,7 @@ impossible to access. : NIL As another example, Armed Bear Common Lisp doesn't seem to believe in -the stderr stream: when it starts up, ~*error-ouptut*~ is bound to the +the stderr stream: when it starts up, ~*error-output*~ is bound to the standard output, just like ~*standard-output*~. Also, ~cl-launch~ loading ASDF causes a huge number of ~style-warning~ messages to be written to stdout, making ABCL pretty much useless for writing filter @@ -562,7 +598,7 @@ scripts. level of shell integration for all its supported Lisp implementations. In particular: - + It ensures that the standard Unix `stdin', `stdout', and `stdarr' + + It ensures that the standard Unix `stdin', `stdout', and `stderr' file descriptors are hooked up to the Lisp ~*standard-input*~, ~*standard-output*~, and ~*error-output*~ streams. @@ -587,5 +623,12 @@ supports. If you want your scripts to be able to run on other Lisps, then ~cl-launch~ is the way to do that. Of course, I welcome patches to help ~runlisp~ support other free Lisp implementations. ~cl-launch~ also supports proprietary Lisps: I have very little interest in these, -so if you want to run scripts using Allegro or LispWorks then -~cl-launch~ is your only choice. +so if you want to run scripts using Allegro or LispWorks then your only +options are to maintain your own ~runlisp~ configuration for these +systems or to use ~cl-launch~. + +* COMMENT Emacs cruft + +# LocalWords: abcl Almquist argv ATTR Attr BST clisp CLisp's Clozure CMU ecl +# LocalWords: env fn ini interp launchrc lua nbsp noinform precompiled prin +# LocalWords: princ sb SBCL's sed SYSCONFDIR sysinit TBLFM tbp tikz xdg XPS