\documentclass[a4paper,11pt]{article}
\title{REDUCE 3.7 User Guide}
\author{Codemist Ltd}
\begin{document}
\maketitle
\section{Introduction}
This document provides information that may help REDUCE users. It documents
all the command-line options that REDUCE supports and explains about
images, checkpointing and user-written initialisation files. For information
on how to test or re-build all or parts of REDUCE see the installation guide.
\section{Command-line options}
The options here are can be used when REDUCE is run from a command prompt
or of the windows interface provides a start-up dialog box that allows you
to specify some of them.
\begin{description}
\item[{\ttfamily -- \rmfamily \slshape filename}]
arranges that output is sent to the indicated file. It is
intended to behave a little like ``{\ttfamily > \rmfamily \slshape filename}''
as command-line output
redirection, but is for use in in windowed environments (in particular
Windows NT) where this would not work. Under Windows if {\ttfamily --} is
used REDUCE starts off with its main window minimised. If you launch
REDUCE from a script and want to capture all its output it is suggested
that you use this rather than shell re-direction of the standard output
to get behaviour which is maximally portable across all the platforms that
REDUCE runs on.
\item[{\ttfamily -b}]
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 "-b" (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 {\ttfamily -b} allows the
user to coax the system into better behaviour.
\item[{\ttfamily -c}]
just prints a dull and unimaginative copyright notice --
having this option in there will tend to ensure that a copyright
message is embedded in the object code somehow, while with luck nobody
will be bothered too much by the fact that there is a stray option to get
it displayed. Note that on some systems there is a proper character
for the Copyright symbol\ldots but there is little agreement about what
that code is! Thus in some cases the message displayed may appear to have
a junk character in it.
\item[{\ttfamily -d \rmfamily \slshape name=value}]
defines a symbol at the start of a run.
You may leave a blank after {\ttfamily -d} or start the symbol name
immediately. The value specified will be set up as a Lisp string. If the
equals sign and following value are omitted the name concerned gets set to
the value {\ttfamily t}, the regular Lisp representation of ``true''. This
mechanism makes it possible to pass information from the command line down
into REDUCE and is used to control several of the testing and re-compilation
jobs that are distributed as part of REDUCE.
\item[{\ttfamily -e}] is reserved by Codemist to enable ``experimental''
features in its code. The option may well be ignored, but if it is not its
behaviour will not necessarily be consistent across versions or time. For
instance it may at times have been used to enable special debugging modes
within the Lisp system.
\item[{\ttfamily -f \rmfamily \slshape number}] is not supported on all
versions of REDUCE. It instructs the system to start up and listen on
a socket with the specified number (the request {\ttfamily -f-} uses
a default socket, which is number 1206). Requests on this socket cause
a new copy of REDUCE to be forked (with a limit to how many such tasks
can be active at once) and requests passed down the socket are then processed
much as if they came directly from the keyboard. This facility is intended to
be of use when running REDUCE on a central system to support remote clients.
In this release of the software it is not guaranteed and end-users of
REDUCE are not given any further information about how to try to use it.
\item[{\ttfamily -g}] sets some options that may be usefule when
debugging code. Specifically it is a short-hand for
{\ttfamily -d*backtrace}, and has an effect similar to saying ``{\ttfamily
on~backtrace;}'' at the start of a REDUCE run.
\item[{\ttfamily -i \rmfamily \slshape image-file}] specifies an image
file that should be made readable by REDUCE when it start up. See the
section on image files later in this guide. The request {\ttfamily -i-}
specifies the default image, which will normally by called {\ttfamily r37.img}
and will be found in the directory where the REDUCE executable lives.
\item[{\ttfamily -k \rmfamily \slshape number}] sets the size of the
heap that REDUCE should use in units of Kilobytes. Thus {\ttfamily -k12000}
suggests use of (around) 12 Mbytes. REDUCE normally expands its memory
when it needs to and most users should not need to use this option.
An extended form of the request such as {\ttfamily -k8000/2} uses a
second number (2 in this example) to control the amount of space used
for one of the system's internal stacks. The default value for this second
number is 1: if you experience stack overflow problems it may be worth
increasing this number to 2 or even 3, but unless you do see stack overflow
crashes there is no benefit at all in trying to tune this parameter.
REDUCE should (on a large enough computer) be able to cope with heap sizes
up to most of 2000 Mbytes. {\ttfamily -k0} tells REDUCE to use its default
storage allocation, which is to start off with a few megabytes allocate but
then to expand its heap as need-be. A directive to use a specified
amount of memory disables this ability to increase the heap size at run-time.
\item[{\ttfamily -l \rmfamily \slshape filename}] arranges to send a
transcript of a REDUCE session to the named file. This option differs
from {\ttfamily --} in that it displays all output on your screen in the
normal way as well as keeping the transcript. Once REDUCE is running the
Lisp-level function {\ttfamily spool} can be used to set up exactly the same
sort of logging, eg using a command such as
\begin{verbatim}
lisp spool "logfile.log";
\end{verbatim}
\noindent and on some versions of REDUCE there may be a menu item for
the same purpose. These all use the same mechanism so use of one overrides
and previous use of one of the others. Which you choose to find is a matter
of personal preference and convenience.
\item[{\ttfamily -m \rmfamily \slshape n:l:h}]
If {\ttfamily MEMORY\_TRACE} was defined when REDUCE was compiled then
this option makes it possible to provoke an interrupt
after {\slshape n} memory probes when a reference in the (inclusive)
range {\slshape l} to {\slshape h} is next made. The release version of REDUCE
is not compiled with this option active, and indeed use of the option slows
REDUCE down dramatically but makes it possible for Codemist to collect
detailed traces of how it accesses memory. These traces have been used in the
past to guide optimisation of the code. In normal cases this option will
not be accepted and would not be useful or relevant to end users.
\item[{\ttfamily -n}] is sometimes useful to developers if they have
created a new image file that doe snot restart properly. To be more specific,
an image file contains copies of all the REDUCE code, and an indication of
which part ot it should be run when REDUCE is started. If a new image
had a restart function that was damaged but all other parts of it were
useful it may be useful to launch REDUCE with the {\ttfamily -n} option
which tells the system to ignore the restart function specified in the image
and run a simple Lisp read-eval-print loop instead. This may allow an expert
to debug or possibly correct the problem they had introduced. It should
be clear from this explanation that ordinary users are not likely to
want to use this switch, and if they do they will be faced with a Lisp-like
interface that will tend to confuse them.
\item[{\ttfamily -o \rmfamily \slshape image-file}] is similar to
{\ttfamily -i} but specifies an image file that is to be opened for
output. There shoudl only be one such file and it will be the one that
{\ttfamily faslout} and {\ttfamily preserve} write information to. See
the later section on image files.
\item[{\ttfamily -p}] is reserved for system profiling options, and will
normally have no effect on a release version of REDUCE.
\item[{\ttfamily -q}] is a specific converse of {\ttfamily -v} but
represents the default behaviour for REDUCE and so is not generally
useful.
\item[{\ttfamily -r \rmfamily \slshape n [,n]}] sets a seed for a random
number generator. The default REDUCE-level generator is deterministic:
it yields the same sequence each time REDUCE is run. For cases where this
is not what is wanted an alternative Lisp-level function
{\ttfamily random-number} exists. Its default behavior (which can be
asked for specifically by saying {\ttfamily -r0}) is to seed its
sequence based on the time of day and such other hard to repeat things.
On some computers it may include timing information from user keystrokes
and mouse activity and only freeze the seed when the user first asks for
a random value, and in such cases best unpredictability will be achieved
by performing several other calculations before doing anything that
asks for a random number. This Lisp-level generator can be forced
into a defined state by giving a command line option {\ttfamily -r}
followed by one or two integers. If two integers are used up to 64
bits of seed can be specified.
\item[{\ttfamily -s}] is a short-hand for {\ttfamily -s*plap} and thus
causes the Lisp compiler to display the bytecodes that it generates
when compiling any REDUCE code. Some users may be interested to see
this code and to judge how compact it is, but probably not many!
\item[{\ttfamily -t \rmfamily -slshape module-name}] was implemented to support
some {\ttfamily perl} scripts that were being written to keep a version
of REDUCE up to date. When invoked with this command-line option REDUCE does
not run at all. It just prints a message to its standard output reporting
the size and date associated with a module with the given name and it then
stops. The idea here was that {\ttfamily perl} could capture and parse
this information to test if the compiled module contained within the
REDUCE image was up to date relative to the corresponding source file.
This release version of REDUCE uses other schemes to re-build modules
but the option is left enabled in case it is useful to others who wish to
embed REDUCE within some larger software support structure. Note that
when running with Windows there is no ``standard output'' so on that
platform you either need to use the {\ttfamily r37c} command-line version
of REDUCE or use {\ttfamily --} to capture the information to a file.
\item[{\ttfamily -u \rmfamily \slshape name}] undefines the given symbol,
and is thus a converse of {\ttfamily -d}. There are probably not many
circumstances where this is useful, but the inclusion of this option is
motivated by completeness and by analogy with the options usually provided
by C compilers.
\item[{\ttfamily -v}] causes more messages to be displayed when REDUCE starts
up, and also a message when it stops (reporting the total run-time used).
To see garbage collection messages from REDUCE it is necessary to issue
a request
\begin{verbatim}
lisp verbos 3;
\end{verbatim}
\item one REDUCE has started running.
\item[{\ttfamily -w}] is not used on current versions of REDUCE but is
reserved for command-line control over whether REDUCE should run as a
windowed or a command-line program.
\item[{\ttfamily -x}] is a debugging option only intended for use by Codemist.
Normally if REDUCE detects in internal exception it attempts to recover.
If {\ttfamily -x} is specified on the command line it allows the trap to
take effect and this will typically generate a {\ttfamily core} file
on Unix or attempt to enter a debugger on Windows. Anybody who attempts
to modify the C code of the REDUCE/Lisp kernel and then find that they
need to debug the resulting system may need this option, but in such
circumstances Codemist can obviously not guarantee anything!
\item[{\ttfamily -y}] is a short-hand for {\ttfamily -d*hankaku} and this
flag is associated with Japanese language support in some versions of
REDUCE. In versions distributed directly by Codemist such support
is not available.
\item[{\ttfamily -z}] instructs the system that it should not load an
initial heap image, but should
run in ``cold start'' mode. This is only intended to be useful for
system builders: it arises in a few of the rebuilding scripts that are
included with REDUCE.
\item[{\slshape filename}] indicates a file that REDUCE should read input
from in preference to accepting input from the terminal.
\end{description}
\section{Image files}
@@@@@@@@@@@@@@@@@@
\section{Initialisation files}
When REDUCE starts up it checks for the presence of an initialisation
file. If you need to avoid this you can specify {\ttfamily -dno\_init\_file}
on the command line when starting REDUCE, and indeed the various REDUCE
maintainance scripts do just this.
REDUCE tries to identify a ``home directory''. It does this by looking first
for the value of a shell variable {\ttfamily home}, then {\ttfamily HOME}
and then {\ttfamily HOMEDRIVE} and {\tt HOMEPATH}. The first two such
cases should work under almost all Unix environments and find your home
directory. Under Windows you can arrange to set {\ttfamily HOME} or
you can set {\ttfamily HOMEDRIVE} and {\ttfamily HOMEPATH} and the full
home directory will be taken as the concatenation of these. If none of these
environment variables are set then REDUCE will look in the current directory.
In the directory so identified it looks for one of the following files
\begin{verbatim}
.r37.rc
r37.rc
r37.ini
\end{verbatim}
\noindent and it will use the first of these files that it finds. It reads
and executes REDUCE commands.
The various places that REDUCE searches are intended to mean that users
of various flavours of Unix and of Windows can put an initialisation
file in the place and with the name that looks most familiar to them.
Obviously an initialisation file can be used to set REDUCE flags or
otherwise set up a custom configuration. When reporting any REDUCE
problems either demonstrate them with {\ttfamily -dno\_init\_file} or
remember to report the exact contents of your initialisation file since
otherwise the behaviour that puzzles you may be hard to reproduce.
You may have several different initial behaviours that you want to have.
If you copy the files {\ttfamily r37.exe} and {\ttfamily r37.img} and give
them different names such as {\ttfamily myr37.exe} and {\ttfamily myr37.img}
then this copy of REDUCE will look for its initialisation file as
{\ttfamily myr37.rc} (or the other variants). Under Windows the command
{\ttfamily r37c.exe} is a command-line version of REDUCE (as distinct
from one that runs in a window). It uses the same image file and
initialisation files as the normal version of REDUCE. If you copy a
REDUCE executable to another location you should follow the convention
that a windowed version has a name not ending in ``c'' and a command-line
version has the same name but with ``c'' added to the end, as in {\ttfamily
myr37c.exe}.
\end{document}