Commit b53ca7e0 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

4.0.8.1: use markdown for the internal help message.

Generate a manpage from that using md2man-nroff
parent 969dfaed
#!/bin/sh
#| cl-launch.sh -- shell wrapper generator for Common Lisp software -*- Lisp -*-
CL_LAUNCH_VERSION='4.0.8'
#| cl-launch.sh -- shell wrapper for Common Lisp -*- Lisp -*-
CL_LAUNCH_VERSION='4.0.8.1'
license_information () {
AUTHOR_NOTE="\
# Please send your improvements to the author:
......@@ -8,11 +8,11 @@ AUTHOR_NOTE="\
"
SHORT_LICENSE="\
# cl-launch is available under the terms of the bugroff license.
# http://tunes.org/legalese/bugroff.html
# http://tunes.org/legalese/bugroff.html
# You may at your leisure use the MIT license instead < http://opensource.org/licenses/MIT >
"
WEB_SITE="# For the latest version of cl-launch, see its web page at:
# http://www.cliki.net/cl-launch
# http://www.cliki.net/cl-launch
"
LICENSE_COMMENT="\
# This software can be used in conjunction with any other software:
......@@ -28,7 +28,7 @@ LICENSE_COMMENT="\
# manually, using cl-launch --update or whichever means you prefer.
# That said, if you believe in any of that intellectual property scam,
# you may be subject to the terms of my End-Seller License:
# http://www.livejournal.com/users/fare/21806.html
# http://www.livejournal.com/users/fare/21806.html
"
DISCLAIMER="\
# This file was automatically generated and contains parts of CL-Launch
......@@ -46,15 +46,15 @@ DEFAULT_USE_QUICKLISP=
### Initialize cl-launch variables
unset \
SOFTWARE_BUILD_FORMS SOFTWARE_FINAL_FORMS SOFTWARE_INIT_FORMS \
SOURCE_REGISTRY INCLUDE_PATH LISPS WRAPPER_CODE \
OUTPUT_FILE UPDATE LISP_CONTENT \
LINE LINE1 LINE2 NO_QUIT \
SOFTWARE_BUILD_FORMS SOFTWARE_FINAL_FORMS SOFTWARE_INIT_FORMS \
SOURCE_REGISTRY INCLUDE_PATH LISPS WRAPPER_CODE \
OUTPUT_FILE UPDATE LISP_CONTENT \
LINE LINE1 LINE2 NO_QUIT \
TRIED_CONFIGURATION HAS_CONFIGURATION \
EXEC_LISP DO_LISP DUMP LOAD_IMAGE RESTART RESTART_PACKAGE IMAGE IMAGE_OPT \
EXTRA_CONFIG_VARIABLES \
EXECUTABLE_IMAGE STANDALONE_EXECUTABLE CL_LAUNCH_STANDALONE \
CL_LAUNCH_FILE __CL_ARGV0 IS_X_SCRIPT \
EXEC_LISP DO_LISP DUMP LOAD_IMAGE RESTART RESTART_PACKAGE IMAGE IMAGE_OPT \
EXTRA_CONFIG_VARIABLES \
EXECUTABLE_IMAGE STANDALONE_EXECUTABLE CL_LAUNCH_STANDALONE \
CL_LAUNCH_FILE __CL_ARGV0 IS_X_SCRIPT \
TEST_SHELLS TORIG IMPL
LISPS="$DEFAULT_LISPS"
......@@ -88,487 +88,575 @@ PROGBASE="${0##*/}" # "$(basename "$0")"
CL_LAUNCH_URL="http://fare.tunes.org/files/cl-launch/cl-launch.sh"
HELP_HEADER="cl-launch.sh $CL_LAUNCH_VERSION -- shell wrapper generator for Common Lisp software"
HELP_HEADER="cl-launch.sh $CL_LAUNCH_VERSION \"(August 2014)\" \"Francois-Rene Rideau's\" \"shell wrapper for Common Lisp\""
print_help_header () {
ECHO "$HELP_HEADER"
ECHO "============"
}
print_help () {
cat <<EOF
Usage:
$PROGBASE [options] '(lisp (form) to evaluate)'
evaluate specified form, print the results followed by newline
as in: cl -l sbcl -sp my-system-and-package '(some form)'
$PROGBASE [options] script-file arguments...
run specified Lisp script, passing arguments, as in a script with
#!/usr/bin/cl -sp my-system-and-package -E main
$PROGBASE [options] --execute [options] [-- arguments...]
run the specified software without generating a script (default)
$PROGBASE [options] --output SCRIPT [options]
generate a runnable shell script from the software specification
$PROGBASE [ --version | --help | --more-help ]
display information (can be long, you may pipe it into a \$PAGER)
Special modes:
-h or -? --help display a short help message
-H --more-help display a longer help message
-V --version display cl-launch version and configuration
-u FILE --update FILE update a cl-launch script to current version
Software specification:
-w CODE --wrap CODE shell wrapper CODE to run in cl-launch
-l LISP... --lisp LISP... try use these LISP implementation(s)
-m IMAGE --image IMAGE build from Lisp image IMAGE
-f FILE --file FILE include lisp FILE while building
-L FILE --load FILE load lisp FILE while building
-S X --source-registry X override source registry of asdf systems
-s SYSTEM --system SYSTEM load asdf SYSTEM while building
--load-system SYSTEM same as above (buildapp compatibility)
-p PACKAGE --package PACKAGE change current package to PACKAGE
-sp SP --system-package SP combination of -s SP and -p SP
-e FORM --eval FORM evaluate FORM while building
--require MODULE require MODULE while building
-r FUNC --restart FUNC restart from build by calling (FUNC)
-E FUNC --entry FUNC restart from build by calling (FUNC argv)
-i FORM --init FORM evaluate FORM after restart
-ip FORM --print FORM evaluate and princ FORM after restart
-iw FORM --write FORM evaluate and write FORM after restart
-F FORM --final FORM evaluate FORM before dumping IMAGE
-I PATH --include PATH runtime PATH to cl-launch installation
+I --no-include disable cl-launch installation feature
-R --rc try read /etc/cl-launchrc, ~/.cl-launchrc
+R --no-rc skip /etc/cl-launchrc, ~/.cl-launchrc
-Q --quicklisp use quicklisp (see --more-help)
+Q --no-quicklisp do not use quicklisp
-b --clbuild use clbuild (see --more-help)
+b --no-clbuild do not use clbuild
-v --verbose be quite noisy while building
-q --quiet be quite quiet while building (default)
Output options:
-x -o ! --execute run the specified software NOW (default)
-o FILE --output FILE create executable FILE
-d IMAGE --dump IMAGE dump IMAGE for faster startup
-X ... -- (see more help) use #!/.../cl-launch as script interpreter
-- -- end of arguments when using -x or -X
Name
----
cl-launch - shell wrapper for Common Lisp
Normal Usage
------------
$PROGBASE [options] '(lisp (form) to evaluate)'
evaluate specified form, print the results followed by newline
as in: cl -l sbcl -sp my-system-and-package '(some form)'
$PROGBASE [options] script-file arguments...
run specified Lisp script, passing arguments, as in a script with
#!/usr/bin/cl -sp my-system-and-package -E main
$PROGBASE [options] --execute [options] [-- arguments...]
run the specified software without generating a script (default)
$PROGBASE [options] --output SCRIPT [options]
generate a runnable shell script from the software specification
Special modes
-------------
-h or -? --help display a short help message
-H --more-help show complete help (you may use a \$PAGER)
-V --version display cl-launch version and configuration
-u FILE --update FILE update a cl-launch script to current version
Software specification
----------------------
-w CODE --wrap CODE shell wrapper CODE to run in cl-launch
-l LISP... --lisp LISP... try use these LISP implementations
-m IMAGE --image IMAGE build from Lisp image IMAGE
-f FILE --file FILE include lisp FILE while building
-L FILE --load FILE load lisp FILE while building
-S X --source-registry X override source registry of asdf systems
-s SYSTEM --system SYSTEM load asdf SYSTEM while building
--load-system SYSTEM same as above (buildapp compatibility)
-p PACKAGE --package PACKAGE change current package to PACKAGE
-sp SP --system-package SP combination of -s SP and -p SP
-e FORM --eval FORM evaluate FORM while building
--require MODULE require MODULE while building
-r FUNC --restart FUNC restart from build by calling (FUNC)
-E FUNC --entry FUNC restart from build by calling (FUNC argv)
-i FORM --init FORM evaluate FORM after restart
-ip FORM --print FORM evaluate and princ FORM after restart
-iw FORM --write FORM evaluate and write FORM after restart
-F FORM --final FORM evaluate FORM before dumping IMAGE
-I PATH --include PATH runtime PATH to cl-launch installation
+I --no-include disable cl-launch installation feature
-R --rc try read /etc/cl-launchrc, ~/.cl-launchrc
+R --no-rc skip /etc/cl-launchrc, ~/.cl-launchrc
-Q --quicklisp use quicklisp (see --more-help)
+Q --no-quicklisp do not use quicklisp
-b --clbuild use clbuild (see --more-help)
+b --no-clbuild do not use clbuild
-v --verbose be quite noisy while building
-q --quiet be quite quiet while building (default)
Output options
--------------
-x -o ! --execute run the specified software NOW (default)
-o FILE --output FILE create executable FILE
-d IMAGE --dump IMAGE dump IMAGE for faster startup
-X ... -- (see more help) use #!/.../cl-launch as script interpreter
-- -- end of arguments when using -x or -X
EOF
}
print_help_footer () {
cat<<EOF
See our web page on
http://www.cliki.net/cl-launch
See our web page on:
<http://www.cliki.net/cl-launch>
Note: if this help is too long for you, you may scroll back, or use
$PROG --more-help | less
Note: if this help is too long for you, you may scroll back, or use:
$PROGBASE --more-help | less
EOF
}
print_more_help () {
cat<<EOF
INVOCATION OF CL-LAUNCH
Invocation of \`cl-launch\`
-------------------------
cl-launch will evaluate Common Lisp code or create shell scripts or executable
binaries that evaluate Common Lisp code. cl-launch follows the invocation
conventions of both Unix script interpreters and Common Lisp implementations.
\`cl-launch\` will evaluate Common Lisp code or create shell scripts or
executable binaries that evaluate Common Lisp code. cl-launch follows
the invocation conventions of both Unix script interpreters
and Common Lisp implementations.
A suggested short-hand name for cl-launch is cl (you may create a symlink
if it isn't included in your operating system's cl-launch package).
We'd like to homestead the path /usr/bin/cl while we can, so that
A suggested short-hand name for \`cl-launch\` is \`cl\` (you may create a
symlink if it isn't included in your operating system's \`cl-launch\` package).
We'd like to homestead the path \`/usr/bin/cl\` while we can, so that
script authors can reasonably expect a script to work when it starts with:
#!/usr/bin/cl
(See SIMPLE CL-LAUNCH SCRIPTS below for caveats with #! scripts though.)
\`#!/usr/bin/cl\`
(See *Simple cl-launch scripts* below for caveats with \`#!\` scripts though.)
Recent Linux kernels support a script interpreter itself being a script;
BSD kernels don't and require a small C program cl-shim to be compiled and
installed as /usr/bin/cl to use cl-launch this way.
To work properly, cl-launch 4.0.4 depends on ASDF 3.0.1 or later, and
on its portability layer UIOP, to manage compilation and image life cycle.
To work properly, \`cl-launch\` 4.0.8 depends on \`ASDF\` 3.0.1 or later, and
on its portability layer \`UIOP\`, to manage compilation and image life cycle.
The software is specified as the evaluation of code in several phases;
the distinction matters most for creating executable binaries,
but understanding the evaluation model can avoid surprises in other cases too.
In the first phase, the Lisp image is initialized:
* optionally having your Lisp start from a Lisp IMAGE (option -I --image)
* loading a small header of code that provides common cl-launch functionality
* loading ASDF3. The cl-launch header will try to load ASDF 3.0.1 or later.
If your implementation does not provide it via (require "asdf"),
you can configure your implementation's ASDF (if any) to find it.
Or you can put it in your home, under ~/common-lip/asdf/ and cl-launch will find it.
Or it may be installed in /usr/share/common-lisp/source/cl-asdf/
in which case cl-launch will also find it.
Failing any of the above, cl-launch will be unable to proceed.
* optionally loading quicklisp
* optionally having your Lisp start from a Lisp \`IMAGE\`
(option \`-I --image\`)
* loading a small header of code that provides common \`cl-launch\` functionality
* loading \`ASDF3\`.
The \`cl-launch\` header will try hard to load \`ASDF 3.0.1\` or later.
If your implementation does not provide it via \`(require "asdf")\`,
you can configure your implementation's \`ASDF\` (if any) to find it.
Or you can put it in your home, under \`~/common-lip/asdf/\`
and \`cl-launch\` will find it.
Or it may be installed in \`/usr/share/common-lisp/source/cl-asdf/\`
in which case \`cl-launch\` will also find it.
Failing any of the above, \`cl-launch\` will be unable to proceed.
* optionally loading [quicklisp](http://beta.quicklisp.org/)
(option \`-Q --quicklisp\`)
In a second phase, your software is built, based on the following options,
in order of appearance:
* evaluating one or several FORMS (option -e --eval) in the current package.
The series of forms is evaluated as by LOAD, in a context where the package
* evaluating one or several \`FORMS\` (option \`-e --eval\`)
in the current package. The series of forms is evaluated
as by \`LOAD\`, in a context where the \`*package*\`
has been set to the current package (see below explanations on packages).
* compiling a FILE and load the fasl (option -L --load)
Files are loaded with *package* bound to the current package (see below).
* including a FILE, compiling it and loading the fasl (option -f --file)
The contents of the FILE, which will have be included in the output script,
will be compiled and the fasl loaded as if by option -L --load.
* compiling a \`FILE\` and load the fasl (option \`-L --load\`)
Files are loaded with \`*package*\` bound to the current package (see below).
* including a \`FILE\`, compiling it and loading the fasl (option \`-f --file\`)
The contents of the \`FILE\`, which will have be included in the output script,
will be compiled and the fasl loaded as if by option \`-L --load\`.
The difference matters mostly when creating an output script,
as opposed to executing the code immediately or dumping an image.
Only one file may be specified this way.
If a filename specified with -f --file is '-' (without the quotes),
If a filename specified with \`-f --file\` is \`-\` (after stripping quotes),
then the standard input is used. You may thus concatenate several files
and feed them to cl-launch through a pipe.
To use a file named '-', pass the argument './-'.
* A script file, as specified by -X ... -- or by use of #! or by following
options with an immediate filename that does not start with ( or -, counts
as if preceded by --package cl-user --load and followed by --execute --
* requiring an implementation-provided MODULE (option --require)
* having ASDF3 compile and load a SYSTEM (option -s --system --load-system).
Option -sp --system-package loads the SYSTEM like -s --system and also
changes the current package like -p --package (see below on packages)
also changes the package at runtime, see option -p --package below.
* optionally having your Lisp DUMP an image to restart from (option -d --dump),
and just before evaluating one or several FINAL forms (option -F --final).
See section DUMPING IMAGES.
If you are creating a shell script with option -o --output but without using
option -d --dump, then these first two phases only happen when the script is
invoked. If you are using option -d --dump, then these two phases happen
immediately, and no compilation happen when invoking the output.
and feed them to \`cl-launch\` through a pipe.
To use a file named \`-\`, pass the argument \`./-\`
(same trick as for \`cat\` and other Unix commands).
* A script file, as specified by \`-X ... --\` or by use of \`#!\`
or by following options with an immediate filename that does not start with
\`(\` or \`-\`, counts as if preceded by \`--package cl-user --load\`
and followed by \`--execute --\`
* requiring an implementation-provided \`MODULE\` (option \`--require\`)
* having \`ASDF3\` compile and load a \`SYSTEM\`
(option \`-s --system --load-system\`).
Option \`-sp --system-package\` loads the \`SYSTEM\` like \`-s --system\`
and also changes the current \`*package*\` like \`-p --package\`
(see below on packages).
* optionally having your Lisp \`DUMP\` an image to restart from
(option \`-d --dump\`), and just before
evaluating one or several \`FINAL\` forms (option \`-F --final\`).
See section *Dumping images*.
If you are creating a shell script with option \`-o --output\` but
without using option \`-d --dump\`, then these first two phases only happen
when the script is invoked. If you are using option \`-d --dump\`,
then these two phases happen immediately, and
no compilation happen when invoking the output.
Note that compiled files are cached, so that the compilation only happens
the first time a file is loaded via --load of --system, or if the source file
has been modified. This may cause slower startup the first time over.
The cache is controlled by ASDF's output-translations mechanism.
See your ASDF manual regarding the configuration of this cache,
which is typically under ~/.cache/common-lisp/
In a third phase, your software is run via UIOP:RESTORE-IMAGE. This happens
immediately if using option -x --execute or calling cl-launch as a Unix
interpreter on a script; or it can happen later if you use option -o --output
in combination with or without option -d --dump to dump an image (which gives
you faster startup and single-file or double-file delivery, at the expense of
disk space), at which point it happens when you invoke the executable output
file.
* Hooks from ASDF3's UIOP:*IMAGE-RESTORE-HOOK* are called (in FIFO order).
* a series of FORMS specified via options -i --init, -ip --print, -iw --write,
stored as a text string, are read and evaluated in order of appearance,
each in the context of the package that was current at the time it was
requested. (Concatenate together with separating whitespace, these forms
constitute the UIOP:*IMAGE-PRELUDE* as handled by RESTORE-IMAGE).
Arguments that start with an open parenthesis are assumed to be FORMS that
follow an implicit --print.
the first time a file is loaded via \`--load of --system\`,
or if the source file has been modified.
This may cause slower startup the first time over.
The cache is controlled by \`ASDF\`'s \`output-translations\` mechanism.
See your \`ASDF\` manual regarding the configuration of this cache,
which is typically under \`~/.cache/common-lisp/\`
In a third phase, your software is run via \`UIOP:RESTORE-IMAGE\`.
This happens immediately if using option \`-x --execute\` or
calling \`cl-launch\` as a Unix interpreter on a script e.g. via \`#!\`;
or it can happen later if you use option \`-o --output\` in combination
with (or without) option \`-d --dump\` to dump an image (which gives you faster
startup and single-file or double-file delivery, at the expense of disk space),
at which point it happens when you invoke the executable output file:
* Hooks from \`ASDF3\`'s \`UIOP:*IMAGE-RESTORE-HOOK*\` are called
(in FIFO order).
* a series of \`FORMS\` specified via options \`-i --init\`,
\`-ip --print\`, \`-iw --write\`, stored as a text string,
are read and evaluated in order of appearance, each in the context
of the package that was current at the time it was requested.
(Concatenated together with separating whitespace, these forms constitute
the \`UIOP:*IMAGE-PRELUDE*\` as handled by \`RESTORE-IMAGE\`).
Arguments that start with an open parenthesis are assumed to be \`FORMS\`
that follow an implicit \`--print\`.
Loading from a stream means you don't have to worry about nasty read-time
issues; forms will be read by the fully built Lisp image; however it also
means that if you care a lot about the very last drop of startup delay when
invoking a dumped image, you'll only use option -r --restart or -E --entry
and avoid using --init and its variants.
Option -ip --print specifies FORMS such that the result of the last form
will be printed as if by PRINC, followed by a newline.
Option -iw --write is similar to --print, using WRITE instead of PRINC.
* An optional FUNCTION provided option -r --restart or -E --entry is invoked.
If the function was provided with option -r --restart (compatible with
earlier versions of cl-launch), it will be called with no argument. If it was
provided with option -E --entry (compatible with buildapp), it will be called
invoking a dumped image, you'll only use option \`-r --restart\`
or \`-E --entry\` and avoid using \`--init\` and its variants.
Option \`-ip --print\` specifies \`FORMS\` such that the result of
the last form will be printed as if by \`PRINC\`, followed by a newline.
Option \`-iw --write\` is similar to \`--print\`,
using \`WRITE\` instead of \`PRINC\`.
* An optional \`FUNCTION\` provided option \`-r --restart\` or \`-E --entry\`
is invoked. If the function was provided with option \`-r --restart\`
(compatible with earlier versions of \`cl-launch\`),
it will be called with no argument. If it was provided with
option \`-E --entry\` (compatible with \`buildapp\`), it will be called
with one argument, being the list of arguments passed to the program,
not including argv[0], which is available on most implementations via the
function uiop:argv0 (available in ASDF 3.1.2 and later). Using either option,
the argument may be a function name or a lambda expression, that is read from
the current package (see below option -p --package and -sp --system-package).
Only one restart or entry function may be specified; if multiple are provided,
the last one provided overrides previous ones. If you want several functions
to be called, you may DEFUN one that calls them and use it as a restart,
or you may use multiple init forms as below.
not including \`argv[0]\`, which is available on most implementations via the
function \`uiop:argv0\` (available in \`ASDF\` 3.1.2 and later).
Using either option, the argument may be a function name
or a lambda expression, that is read from the current package
(see below option \`-p --package\` and \`-sp --system-package\`).
Only one restart or entry function may be specified;
if multiple are provided, the last one provided overrides previous ones.
If you want several functions to be called, you may \`DEFUN\` one that calls
them and use it as a restart, or you may use multiple init forms as below.
* If neither restart nor entry function is provided, the program will exit with
status 0 (success). If a function was provided, the program will exit after
the function returns (if it returns), with status 0 if and only if the
primary return value of result is generalized boolean true, and with status 1
if this value is NIL. See documentation for UIOP:RESTORE-IMAGE for details.
The current package can be controlled by option -p --package and its variant
-sp --system-package that also behaves like -s --system. All forms passed to
--eval, --init, --print, --write, --final, --restart, --entry, etc., are read
in the current package. Files specified with -f --file --load are read in the
current package. Current means the package specified by the latest option -p
--package or -sp --system-package preceding the option being processed, or
cl-user if there was none. Note that multiple -i --init or -F --final forms
status \`0\` (success). If a function was provided, the program will exit
after the function returns (if it returns), with status \`0\` if and only if
the primary return value of result is generalized boolean true, and
with status 1 if this value is \`NIL\`.
See documentation for \`UIOP:RESTORE-IMAGE\` for details.
The current package can be controlled by option \`-p --package\` and its variant
\`-sp --system-package\` that also behaves like \`-s --system\`.
All forms passed to \`--eval\`, \`--init\`, \`--print\`, \`--write\`,
\`--final\`, \`--restart\`, \`--entry\`, etc., are read in the current package.
Files specified with \`-f --file --load\` are read in the current package.
Current means the package specified by the latest option \`-p --package\` or
\`-sp --system-package\` preceding the option being processed,
or \`cl-user\` if there was none.
Note that multiple \`-i --init\` or \`-F --final\` forms
may be evaluated consecutively after a package has been changed, and that
if one of these form itself modifies the package, or some other syntax control
mechanism such as the reader, it may adversely affect later forms in the same
category, but not those in other categories (if reached).
General note on cl-launch invocation: options are processed from left to right;
usually, repeated options accumulate their effects, with the earlier instances
taking effect before latter instances. In case of conflicting or redundant
options, the latter override the former.
cl-launch defines a package :cl-launch that exports the following symbol:
compile-and-load-file
Runtime functionality formerly provided by cl-launch is now provided by UIOP,
the portability layer provided by ASDF3.
See below section 'CL-LAUNCH RUNTIME API'.
When the first non-recognized option is a filename, cl-launch will try to
load this filename as a script, as if by --load, then execute it immediately
as if by --execute --, with the rest of the command line passed as arguments.
The file name may not start with a '-' or a '(' (without quotes).
General note on \`cl-launch\` invocation:
options are processed from left to right;
usually, repeated options accumulate their effects,
with the earlier instances taking effect before latter instances.
In case of conflicting or redundant options, the latter override the former.
\`cl-launch\` defines a package \`cl-launch\` that exports the following symbol:
\`compile-and-load-file\`
Runtime functionality formerly provided by \`cl-launch\`
is now provided by \`UIOP\`, the portability layer provided by \`ASDF3\`.
See below section *cl-launch runtime API*.
When the first non-recognized option is a filename, \`cl-launch\` will try to
load this filename as a script, as if by \`--load\`,
then execute it immediately as if by \`--execute --\`,
with the rest of the command line passed as arguments.
The file name may not start with the character \`-\` or a \`(\` ---
To use a file with one of these (or something unknown) as a first character,
prepend './' to the filename. Note that it is a security risk to let
prepend \`./\` to the filename. Note that it is a security risk to let
adversaries control the names of files passed to cl-launch or other commands.
When option --execute is specified, the specified software is executed.
When option \`--execute\` is specified, the specified software is executed.
Command-line arguments may be given to software being executed by putting
them after a special marker '--', that ends cl-launch option processing.
them after a special marker \`--\`, that ends \`cl-launch\` option processing.
When option --output FILE is used, code will be generated into the specified
FILE. The output file itself will be created atomically from complete
generated contents and may thus have the same pathname as the input file.
When option \`--output FILE\` is used, code will be generated
into the specified \`FILE\`. The output file itself
will be created atomically from complete generated contents
and may thus have the same pathname as the input file.
The restart function and init forms will not be evaluated, but kept for
when the output file is executed.
If '-' (without quotes) is specified, then the standard output is used.
If '!' (without quotes) is specified, then option --execute is assumed.
If \`-\` (after quoting) is specified, then the standard output is used.
If \`!\` (after quoting) is specified, then option \`--execute\` is assumed.
When no --output file is specified, option --execute is implicitly assumed.
The last --output or --execute option takes precedence over the previous ones.
When no \`--output\` file is specified,
option \`--execute\` is implicitly assumed.
The last \`--output\` or \`--execute\` option
takes precedence over the previous ones.
If only one argument exists and it doesn't start with '-' then the argument is
considered as if given to option -ip, to be evaluated and printed immediately.
If only one argument exists and it doesn't start with \`-\`
then the argument is considered as if given to option \`-ip\`,
to be evaluated and printed immediately.
The ASDF3 source-registry configuration can be overridden with option
--source-registry SOURCE_REGISTRY. The provided configuration will take
The \`ASDF3\` source-registry configuration can be overridden with option
\`--source-registry SOURCE_REGISTRY\`. The provided configuration will take
priority over anything provided by the environment or configuration files,
though it may inherit from them as usual. See the ASDF3 manual about that.
though it may inherit from them as usual. See the \`ASDF3\` manual about that.
Options -l --lisp and -w --wrap may be used to control the way that
Options \`-l --lisp\` and \`-w --wrap\` may be used to control the way that
a Common Lisp implementation is found when the software is run.
Option -l --lisp specifies the list of implementations to try to use; the list
is whitespace-separated, and consists in nicknames recognized by cl-launch.
Option -w --wrap supplies arbitrary code to be evaluated by the shell wrapper,
after it has read its configuration and defined its internal functions, but
before it tries to find and run a Lisp implementation. Such wrapper code is
typically used to modify the variables that control the run-time behaviour
of generated scripts, as documented below. Use of other internals of cl-launch
is possible, but not supported, which means that it is your responsibility to
keep a copy of the specific version of cl-launch with which your code works and
to update your code if you later make an upgrade to an incompatible cl-launch.
For instance, --lisp "foo bar" is equivalent to --wrap 'LISPS="foo bar"'.
See below the documentation section on 'LISP IMPLEMENTATION INVOCATION'.
Option --no-include specifies that cl-launch should generate a standalone
Option \`-l --lisp\` specifies the list of implementations to try to use;
the list is whitespace-separated, and consists in
nicknames recognized by \`cl-launch\`.
Option \`-w --wrap\` supplies arbitrary code to be evaluated
by the shell wrapper, after it has read its configuration
and defined its internal functions, but before it tries
to find and run a Lisp implementation. Such wrapper code is typically used to
modify the variables that control the run-time behaviour of generated scripts,
as documented below. Use of other internals of \`cl-launch\` is possible,
but not supported, which means that it is your responsibility to keep a copy
of the specific version of cl-launch with which your code works and to
update your code if you later make an upgrade to an incompatible \`cl-launch\`.
For instance, \`--lisp "foo bar"\` is equivalent
to \`--wrap 'LISPS="foo bar"'\`.
See below the documentation section on *Lisp implementation invocation*.
Option \`--no-include\` specifies that cl-launch should generate a standalone
script that includes the configuration, shell wrapper, Lisp header, and
user-provided Lisp code (from --file). If you can rely on the presence of
a recent Lisp implementation that provides ASDF, then the script is pretty
user-provided Lisp code (from \`--file\`). If you can rely on the presence of
a recent Lisp implementation that provides \`ASDF\`, then the script is pretty
much standalone indeed and may be moved around the filesystem and still used.
However the size of the output will be the size of the user Lisp code
plus about 28KiB.
Option --include PATH specifies that cl-launch should generate a very small
script (typically under 1KiB) that when run will read the cl-launch shell
wrapper and Lisp header from a specified installation directory PATH.
Also, if option --include is used, and Lisp code is specified with --file
and an absolute pathname starting with / as opposed to a relative pathname
plus about 36KiB.
Option \`--include PATH\` specifies that \`cl-launch\` should generate
a very small script (typically under 1KiB) that when run
will read the \`cl-launch\` shell wrapper and Lisp header
from a specified installation directory \`PATH\`.
Also, if option \`--include\` is used, and
Lisp code is specified with \`--file\`
and an absolute pathname starting with \`/\` as opposed to a relative pathname
or to the standard input, then Lisp code will also be loaded from the specified
location at runtime rather than embedded into the script at generation time.
This option generates leaner scripts, but may not be applicable when
the very same script is to used in a variety of situations
that lack common coherent filesystem management.
Which of --include or --no-include is the default may depend on your cl-launch
installation. The version of cl-launch distributed by the author uses
--no-include by default, but the version of cl-launch available in your
operating system distribution may rely on a well-managed include path (this is
the case with debian for instance). You may query the configuration of an
instance of cl-launch with option --version.
For instance, one may expect a debian version of cl-launch to use
/usr/share/common-lisp/source/cl-launch/
Which of \`--include\` or \`--no-include\` is the default
may depend on your cl-launch installation.
The version of \`cl-launch\` distributed by the author
uses \`--no-include\` by default, but
the version of \`cl-launch\` available in your operating system distribution may
rely on a well-managed include path (this is the case with debian for instance).
You may query the configuration of an instance of \`cl-launch\`
with option \`--version\`.
For instance, one may expect a debian version of cl-launch to use:
\`/usr/share/common-lisp/source/cl-launch/\`
as a system-managed include path. One may also expect that Lisp implementations
managed by the system would come with cl-launch precompiled in Lisp images.
Since the cl-launch provides feature :cl-launch, and since the cl-launch Lisp
header is conditionalized to not be read with this feature, this would make
cl-launch startup faster, while still allowing non-system-managed Lisp
implementations to run fine.
You may create an installation of cl-launch with such a command as
cl-launch --include /usr/share/common-lisp/source/cl-launch \\
--lisp 'sbcl ccl clisp' \\
managed by the system would come with \`cl-launch\` precompiled in Lisp images.
Since \`cl-launch\` provides feature \`:cl-launch\`,
and since the \`cl-launch\` Lisp header is conditionalized to not be read