2 Command-line options
The items shown here are the ones that are recognized on the CSL command
line. In general an option that requires an argument can be written as either -x
yyy or as -xyyy. Arguments should be case insensitive.
- If the application is run in console mode then its standard output
could be redirected to a file using shell facilities. But the -- directive
(followed by a file name) redirects output within the Lisp rather than
outside it. If this is done a very limited capability for sending progress
or status reports to stderr (or the title-bar when running in windowed
mode) remains via the report!-right function.
The -w option may frequently make sense in such cases, but if that
is not used and the system tries to run in a window it will create it
starting off minimised.
- Encourage the system to run in its own window. Similar behaviour
- Encourage the system to run as in its own window, but start
that window off minimised. Similar to -w..
- It is probably obvious what this option does! Note that on Windows
the application was linked as a windows binary so it carefully creates
a console to display the help text in, and organizes a delay to give
people a chance to read it.
- At some time I had felt the need for this option, but I now
forget what I expected to use it for! It leads the executable to display
the fully rooted name of the directory it was in and then terminate. It
may be useful in some script?
- Encourage the system to run as a console-style application. Similar
to -w- or just simply -w.
- If CSL/Reduce is launched from texmacs this command-line
flag should be used to arrange that the texmacs flag is set in
lispsystem!*, and the code may then do special things.
- It is probably obvious what this option does! But note that
there is an issue here about whether one is looking at the CSL version
identification or one for the Lisp application from an image file (eg
- -a is a curious option, not intended for general or casual use. If given
it causes the (batchp) function to return the opposite result from
normal! Without “attfamily -a” (batchp) returns T either if at least
one file was specified on the command line, or if the standard input
is “not a tty” (under some operating systems this makes sense – for
instance the standard input might not be a “tty” if it is provided via file
redirection). Otherwise (ie primary input is directly from a keyboard)
(batchp) returns nil. Sometimes this judgement about how “batch”
the current run is will be wrong or unhelpful, so -a allows the user to
coax the system into better behaviour. I hope that this is never used!
- -b tells the system to avoid any attempt to recolour prompts and input
text. It will mainly be needed on X terminals that have been set
up so that they use colours that make the defaults here unhelpful.
Specifically white-on-black and so on. -b can be followed by colour
specifications to make things yet more specific. It is supposed to be
the idea that three colours can be specified after it for output, input
and prompts, with the letters KRGYbMCW standing for blacK, Red,
Green, Yellow, blue, Magenta, Cyan and White. This may not fully
- Displays a notice relating to the authorship of CSL. Note that this is an
authorship statement not a Copyright notice, because if any (L)GPL
code is involved that would place requirements on what was displayed
in a Copyright Notice.
- A command line entry -Dname=value or -D name=value sets the value
of the named lisp variable to the value (as a string). Note that the
value set is a string so if you wish to retrieve it and use it as a symbold
or number within your code you will have to perform some conversion.
- A “spare” option used from time to time to activate experiments within
- At one stage CSL could run as a socket server, and -f portnumber
activated that mode. -f- used a default port, 1206 (a number inspired
by an account number on Titan that I used in the 1960s). The code
that supports this may be a useful foundation to others who want to
make a network service out of this code-base, but is currently disabled.
- In line with the implication of this option for C compilers, this enables
a debugging mode. It sets a lisp variable !*backtrace and arranges
that all backtraces are displayed notwithstanding use of errorset.
- This option is a left-over. When the X-windows version of the code first
started to use Xft it viewed that as optional and could allow a build
even when it was not available. And then even if Xft was detected and
liable to be used by default it provided this option to disable its use.
The remnants of the switch that disabled use of Xft (relating to fonts
living on the Host or the Server) used this switch, but it now has no
- CSL and Reduce use image files to keep both initial heap images and
“fasl” loadable modules. By default if the executable launched has
some name, say xxx, then an image file xxx.img is used. But to support
greater generality -i introduces a new image, -i- indicates the default
one and a sequence of such directives list image files that are searched
in the order given. These are read-only. The similar option -o equally
introduces image files that are scanned for input, but that can also be
used for output. Normally there would only be one -o directive.
- Follow this directive with a file-name, and a record of all the files read
during the Lisp run will be dumped there with a view that it can be
included in a Makefile to document dependencies.
- -K nnn sets the size of heap to be used. If it is given then that much
memory will be allocated and the heap will never expand. Without
this option a default amount is used, and (on many machines) it will
grow if space seems tight.
The extended version of this option is -K nnn/ss and then ss is the
number of “CSL pages” to be allocated to the Lisp stack. The default
value (which is 1) should suffice for almost all users, and it should be
noted that the C stack is separate from and independent of this one
and it too could overflow.
A suffix K, M or G on the number indicates units of kilobytes,
megabytes or gigabytes, with megabytes being the default. So -K200M
might represent typical usage for common-sized computations. In
general CSL will automatically expand its heap, and so it should
normally never be necessary to use this option.
- This is to send a copy of the standard output to a named log file. It
is very much as if the Lisp function (spool ‘‘logfile’’) had been
invoked at the start of the run.
- Memory trace mode. An option that represents an experiment from the
past, and no longer reliably in use. It make it possible to force an
exception at stages whene reference to a specified part of memory was
made and that could be useful for some low level debugging. It is not
supported at present.
- Normally when the system is started it will run a “restart function” as
indicated in its heap image. There can be cases where a heap image
has been created in a bad way such that the saved restart function
always fails abruptly, and hence working out what was wrong becomes
hard. In such cases it may be useful to give the -n option that forces
CSL to ignore any startup function and merely always begin in a
minimal Lisp-style read-eval-print loop. This is intended for experts
to do disaster recovery and diagnosis of damaged image files.
- See -i. This specifies an image file used for output via faslout and
- If a suitable profile option gets implemented one day this will activate
it, but for now it has no effect.
- This option sets !*echo to nil and switches off garbage collector
messages to give a slightly quieter run.
- The random-number generator in CSL is normally initialised to a value
based on the time of day and is hence not reproducible from run to
run. In many cases that behavious is desirable, but for debugging it
can be useful to force a seed. The directive -r nnn,mmm sets the seed to
up to 64 bits taken from the values nnn and mmm. The second value
if optional, and specifying -r0 explicitly asks for the non-reproducible
behaviour (I hope). Note that the main Reduce-level random number
source is coded at a higher level and does not get reset this way – this
is the lower level CSL generator.
- Sets the Lisp variable !*plap and hence the compiler generates an
- -t name reports the time-stamp on the named module, and then exits.
This is for use in perl scripts and the like, and is needed because the
stamps on modules within an image or library file are not otherwise
Note that especially on windowed systems it may be necessary to use
this with -- filename since the information generated here goes to
the default output, which in some cases is just the screen.
- See -d, but this forcibly undefines a symbol. There are probably very
very few cases where it is useful since I do not have a large number of
system-specific predefined names.
- An option to make things mildly more verbose. It displays more of a
banner at startup and switches garbage collection messages on.
- On a typical system if the system is launched it creates a new window
and uses its own windowed intarface in that. If it is run such that
at startup the standard input or output are associated with a file or
pipe, or under X the variable DISPLAY is not set it will try to start
up in console mode. The flag -w indicates that the system should run
in console more regadless, while -w+ attempts a window even if that
seems doomed to failure. When running the system to obey a script
it will often make sense to use the -w option. Note that on Windows
the system is provided as two separate (but almost identical) binaries.
For example the file csl.exe is linked in windows mode. A result is
that if launched from the command line it detaches from its console,
and if launched by double-clicking it does not create a console. It is
in fact very ugly when double clicking on an application causes an
unwanted console window to appear. In contrast csl.com is a console
mode version of just the same program, so when launched from a
command line it can communicate with the console in the ordinary
- -x is an option intended for use only by system support experts – it
disables trapping if segment violations by errorset and so makes it
easier to track down low level disasters – maybe! This can be valuable
when running under a debugger since if the code traps signals in its
usual way and tries to recover it can make it a lot harder to find out
just what was going wrong.
- -y sets the variable !*hankaku, which causes the lisp reader convert a
Zenkaku code to Hankaku one when read. I leave this option decoded
on the command line even if the Kanji support code is not otherwise
compiled into CSL just so I can reduce conditional compilation. This
was part of the Internationalisation effort for CSL bu this is no longer
- When bootstrapping it is necessary to start up the system for one
initial time without the benefit of any image file at all. The option -z
makes this happen, so when it is specified the system starts up with
a minimal environment and only those capabilities that are present in
the CSL kernel. It will normally make sense to start loading some basic
Lisp definitions rather rapidly. The files compat.lsp, extras.lsp and
compiler.lsp have Lisp source for the main things I use, and once
they are loaded the Lisp compiler can be used to compile itself.
Services provided by