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.

--gui

Encourage the system to run in its own window. Similar behaviour to -w+.

--guimin

Encourage the system to run as in its own window, but start that window off minimised. Similar to -w..

--help

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.

--my-path

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?

--nogui

Encourage the system to run as a console-style application. Similar to -w- or just simply -w.

--texmacs

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.

--version

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 often Reduce).

-a

-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

-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 work yet!

-c

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.

-d

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.

-e

A “spare” option used from time to time to activate experiments within CSL.

-f

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.

-g

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.

-h

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 effect.

-i

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.

-j

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

-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.

-l

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.

-m

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.

-n

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.

-o

See -i. This specifies an image file used for output via faslout and reserve.

-p

If a suitable profile option gets implemented one day this will activate it, but for now it has no effect.

-q

This option sets !*echo to nil and switches off garbage collector messages to give a slightly quieter run.

-r

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.

-s

Sets the Lisp variable !*plap and hence the compiler generates an assembly listing.

-t

-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 instantly available.

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.

-u

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.

-v

An option to make things mildly more verbose. It displays more of a banner at startup and switches garbage collection messages on.

-w

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 expected manner.

-x

-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

-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 supported.

-z

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
SourceForge