reduce-historical/r34/doc/install.tex

\addtolength{\topmargin}{-.5cm}
\documentstyle[11pt]{report}
\parindent 0pt
\parskip 6pt
\pagestyle{empty}
\setlength{\topsep}{0.5\baselineskip}  % above and below environments
\setlength{\itemsep}{\topsep}
\setlength{\abovedisplayskip}{\topsep}  % for "long" equations
\setlength{\belowdisplayskip}{\topsep}

\renewcommand{\arraystretch}{1.3}
\renewcommand{\thechapter}{\arabic{chapter}}
\renewcommand{\thesection}{\arabic{section}.}
\renewcommand{\thesubsection}{\arabic{subsection}.}
\newcommand{\REDUCE}{REDUCE}

% The following are version dependent.

\newcommand{\zibnumber}{2.013.04}
\newcommand{\system}{Digital Equipment DECstation}
\newcommand{\programsize}{3.5}      % megabytes
\newcommand{\virtualsize}{128}      % megabytes
\newcommand{\timingmachine}{DECstation 3100}
\newcommand{\machinefactors}{DECstation 5100 &0.6
                          \\ DECstation 5800 &1.0}
\newcommand{\cartridgecommand}{tar xb 126}
\newcommand{\tapespace}{22}        % megabytes
\newcommand{\createtime}{11}        % seconds
\newcommand{\executablespace}{4.3}  % megabytes
\newcommand{\testtime}{4.9}         % seconds
\newcommand{\floatingpointdigits}{12}

\begin{document}
\begin{titlepage}
\samepage
%\vspace*{1cm}
\begin{center}
\begin{minipage}{10cm}
\begin{center}
{\LARGE {\bf REDUCE} Installation Guide for the} \vspace*{2mm} \\
{\LARGE {\system} Workstations} \\[0.3cm]
{\LARGE Version 3.4} \\[0.3cm]
{\large by} \\[0.3cm]
{\Large Anthony C. Hearn}\\
{\large RAND} \\
{\large Santa Monica, CA 90407-2138 USA} \\[0.3cm]
{\large and} \\[0.3cm]
{\Large Winfried Neun}\\
{\large ZIB} \\
{\large 1000 Berlin 31, FRG} \\[0.3cm]
{\large July 1991}\\[0.5cm]
\vfill

{\bf Abstract}
\end{center}
\end{minipage}
\end{center}
This guide describes the {\REDUCE} distribution tape and procedures for
installing, testing and maintaining {\REDUCE} for the {\system} workstation.

\begin{center}
{ZIB Publication M 2.011.04} \\*[1cm]
Copyright \copyright 1991 by RAND and ZIB.  All rights reserved.
\end{center}

\nopagebreak
Registered system holders may reproduce all or any part of this
publication for internal purposes, provided that the source of the
material is clearly acknowledged, and the copyright notice is retained.
\end{titlepage}
\newpage
\tableofcontents
\thispagestyle{empty}

\newpage
\setcounter{page}{1}
\pagestyle{plain}

\section{Introduction}
This guide describes the {\REDUCE} distribution tape and procedures for
installing, testing and maintaining {\REDUCE} on {\system} workstation.
{\REDUCE} is based on Standard Lisp, and this version requires the
availability of Portable Standard Lisp (PSL), version 3.4 or later.  The
PSL files necessary to run {\REDUCE} are included on the system tape.  This
is not however a complete PSL system and in particular does not include
PSL sources.  A complete PSL, if needed, is available separately from the
Konrad-Zuse-Zentrum by contacting:

\begin{center}
Konrad-Zuse-Zentrum f\"ur Informationstechnik Berlin \\
- Symbolik - \\
Heilbronner Str. 10 \\
1000 Berlin 31 \\
Federal Republic of Germany \\

Telephone: (+49) 30 89604 195 \\
Electronic Mail: melenk@sc.ZIB-Berlin.dbp.de \\
or:              melenk@sc.ZIB-Berlin.de  (Internet) \\
Facsimile: (+49) 30 89604 125.
\end{center}

The distributed version of {\REDUCE} requires approximately {\programsize}
megabytes for the program alone without taking into account workspace
requirements.  It takes its default execution size from the underlying PSL 
system, which is approximately {\virtualsize}
megabytes, and can be enlarged at runtime (see REDUCE User's Guide).

The  job  times  given in this guide are for a {\timingmachine}.
The  following  approximate  adjustment  factors  for  other  machines
have been found to apply:
\begin{center}
\begin{tabular}{ll}
\machinefactors
\end{tabular}
\end{center}

\newpage

\section{Description of the {\REDUCE} Distribution Tape}
The distribution tape is in {\tt tar} format, and was written from the
{\REDUCE} root directory.  The files are organized in sub-directories,
where the sub-directory name describes the contents of the directory,
e.g., ./reduce.rootdir/doc.  The names and contents of these
sub-directories are:
\begin{enumerate}
\item[{\bf doc}]   {\REDUCE} documents, including descriptions of all user
contributed
packages and the following:
\begin{center}
\begin{tabular}{rl}
reduce.tex & {\REDUCE} User's Manual in \LaTeX\ format \\
install.tex & Installation instructions in \LaTeX\ format \\
oper.tex & System specific operation notes in \LaTeX\ format \\
sl.doc & Standard LISP Report in plain text format.
% bugs33.doc &  Known bugs and problems in REDUCE 3.3.
\end{tabular}
\end{center}
\item [{\bf fasl} ]  Binary versions of sources for fast loading {\REDUCE}
functions
\item [{\bf lib}] {\REDUCE} user library
\item [{\bf log} ] Depository for log files created during system building
and testing (initially empty)
\item [{\bf psl}] PSL binaries and related files needed to run {\REDUCE}
\item [{\bf src}] Sources for creating {\REDUCE}, written in both PSL and
RLISP
\item [{\bf util}] Appropriate scripts for building {\REDUCE}, etc.
\item [{\bf xlog}] ``Exemplary" log files for comparison with your own such
files
\item [{\bf xmpl}] {\REDUCE} tests, demonstrations and the interactive
lessons.
\end{enumerate}

\section{Installing {\REDUCE}}
The following description assumes that {\tt csh} is used as the command shell.
If a different shell is used, please change the commands accordingly.
To install {\REDUCE}, you need to create a directory for the {\REDUCE} file
system.  This is identified as ``\$reduce" from now on.  It is assumed
that you have write access to this directory.  Connect to this directory,
mount the tape and type for a 1/2" tape
\begin{center}
\begin{tabbing}
and for cartridge tape xxx \= tar x \kill
                                          \> tar x \\
and for a cartridge tape \\
                                          \> {\cartridgecommand}
\end{tabbing}
\end{center}
This will retrieve all files, and requires approximately {\tapespace}
megabytes of disk space.
Finally, please run the commands:
\begin{center}
\begin{tabbing}
and for cartridge tape xxx \= tar x \kill
                                          \> util/sparsify psl/bpsl \\
and \\
                                          \> util/sparsify reduce \\
which will diminish the disk space requirements.
\end{tabbing}
\end{center}

In most cases the installation of Reduce is complete after unloading the
tape.  The location of the {\REDUCE} root directory is essential for using
{\REDUCE}.  Please advise users to set the variable {\tt reduce} in their
environment to this location.  It may be useful to add a link from one of
the standard directories for binaries (e.g. /usr/local/bin) to the reduce
root directory.  Alternatively, if you prefer not to ask users to set {\tt
reduce}, the {\tt reduce} script in the util directory, suitably modified
for local file conventions, could be installed in say /usr/local/bin.

{\REDUCE} is stored in the system as a binary executable disk file 
\$reduce/reduce. 
If modifications of the default settings are requested, one can rebuild 
this file, which is on the tape, by the following commands:
\begin{verbatim}
        setenv reduce <REDUCE root directory>
        $reduce/util/mkreduce
\end{verbatim}

Output from this step is logged to the file \$reduce/log/mkreduce.log.

The mkreduce script builds a {\REDUCE} image of the size described above.
This is usually adequate for most calculations.  If you require a larger
(or smaller) image, you should edit the mkreduce script, and modify the
numbers in the call of bpsl.  In particular, the ``td" parameter is the
total heap and binary program space size (in bytes).

During the building of the {\REDUCE} binary, messages saying that various
functions have been defined, or not defined, are normal, and can therefore
be ignored.

\section{Printing Documents}
The distributed documents are in the directory \$reduce/doc.  The
\LaTeX\ files need processing before they can be printed.  Plain text
files may be printed using standard UNIX utilities.  They are paginated
and formatted with standard ASCII control characters.  A maximum of sixty
print lines per page are assumed.  The left margin offset must be supplied
by the user.

\section{Testing {\REDUCE}}
To test the {\REDUCE} installation enter:
\begin{verbatim}
        reduce.bindir/reduce
        in "$reduce/xmpl/reduce.tst";
\end{verbatim}

This requires about {\testtime} seconds on the system as described above.

Other programs for testing the {\REDUCE} system assembly may also be found
in the directory \$reduce/xmpl.

\section{Running {\REDUCE} Programs}
Once reduce.bindir in the user's search path, {\REDUCE} is simply invoked
with its name:
\begin{verbatim}
        reduce
\end{verbatim}
{\REDUCE} will respond with a banner line and then prompt for the first
line of input:
\begin{verbatim}
        REDUCE 3.4, 15-Jul-91 ...
        1:
\end{verbatim}

Prototypical instructions for using this version of {\REDUCE}
are available as the file \$reduce/doc/oper.tex. You should edit this to
reflect your site-specific implementation before issuing it to users.
System independent instructions for the use of {\REDUCE} are given in the
{\REDUCE} User's Manual.

\section{Working with Minimal Disk Space}
Many of the {\REDUCE} system files are not necessary for running
{\REDUCE}.  In situations where disk space is at a premium, the following
files may be deleted from disk:
\begin{enumerate}
\item[--] all files in the sub-directories doc, src, util, xlog, log and xmpl,
\item[--] the files in the sub-directory psl which are listed in the file
cleanup.csh in this sub-directory,
\item[--] the files alg.b, arith.b, entry.b, mathpr.b, module.b, poly.b,
prolog.b, rend.b, and rlisp.b in the sub-directory fasl.
\end{enumerate}

After rebuilding or copying the files psl/bpsl and reduce, you should run
the program {\tt util/sparsify} with the relevant filename as parameter.
This will drastically reduce the amount of disk space used.

Although the sub-directories doc and xmpl are not necessary, it is
advisable to leave at least the {\REDUCE} manual, system operating
instructions, the documents for the user packages and the {\REDUCE}
interactive lessons on line for users.

\section{Rebuilding REDUCE FASL Files}
Because of its organization into independently compilable modules, the
current {\REDUCE} system is fairly easy to maintain.  If any source
updates are necessary, they can be incorporated into the appropriate files
using a convenient editor.  Once any of the system source files have been
updated, it is necessary to rebuild (compile) the equivalent fast loading
modules in order to utilize the changes.

To rebuild any of the {\REDUCE} fasl files, connect to the directory
\$reduce and call the script:
\begin{verbatim}
        util/mkfasl xxx
\end{verbatim}
where {\tt xxx} is the appropriate package name, e.g. rend to rebuild
\$reduce/fasl/rend.b from \$reduce/src/rend.red.  If any of the fasl files
used in building the {\REDUCE} system are changed (alg, arith, entry,
mathpr, module, poly, prolog, rend, and rlisp), the reduce binary image will
need to be rebuilt with the script:
\begin{verbatim}
        util/mkreduce
\end{verbatim}

A separate utility script \$reduce/util/build is available for completely
rebuilding all of the {\REDUCE} fasl files.  This should normally never be
required and is included only in case the system becomes so corrupted that
it is no longer possible to rebuild even single modules with the mkfasl
procedure.

\section{Maintaining {\REDUCE}}
The {\tt util} directory includes a number of scripts that are useful for
the ongoing maintenance of {\REDUCE}.  Most of these are only of interest
to the system maintainer, although some (such as {\tt mkslfile} and {\tt
test}) may be of interest to the general user.  Several of these scripts
have been described earlier in this Guide.  However, for completeness,
they are all described in this section.  The scripts are as follows:

\paragraph{build}

This is used to rebuild the complete {\REDUCE} fast-loading (fasl) file
system from scratch.  It first uses the script {\tt dbuild} to build a
version of {\REDUCE} suitable for compiling all packages, and then uses
the script {\tt xbuild} to create the actual fasl files.

\paragraph{check-all}

This can be used to check the logs generated by {\tt test-all} with the
``exemplary" versions found in {\tt xlog}.  It produces a {\tt diff} of
each log referenced in {\tt test-all}.

\paragraph{dbuild}

This is used by {\tt build} (q.v.) to build a version of {\REDUCE} suitable
for compiling all packages.

\paragraph{mkfasl}

This creates a single fasl file from a package file.  It is used in the
form {\tt  mkfasl <package-name> }.

\paragraph{mkfasl2}

This creates a single fasl file from a package file in the \$2 directory.
It is normally used to make fasl files from the {\tt lib} directory, in
which it is used in the form {\tt mkfasl <package-name> lib}.

\paragraph{mkreduce}

This has been mentioned earlier.  It creates the {\REDUCE} executable from
PSL sources and {\REDUCE} fasl files.

\paragraph{mkslfile}

This has also been mentioned earlier.  It generates a Lisp
equivalent of {\REDUCE} or RLISP source files.

\paragraph{reduce}

This is a prototypical script that can be installed, say, in /usr/local/bin,
to set the environment variable {\tt reduce}, and call the {\REDUCE}
executable.

\paragraph{reduce-names}

This file is normally used as an argument to {\tt source} to set up
symbolic names for the {\REDUCE} sub-directories.  It must be modified to
conform to local file conventions.

\paragraph{sparsify}

This utility is used to remove ``dead" space from various PSL binary files
that grow in size when copied.   In addition to the executable, the source
({\tt sparsify.c}) and a UNIX ``man" page ({\tt sparsify.l}) are included.

\paragraph{test}

This can be used to run one of the test files in the {\tt xmpl} directory.
{\tt  test <file>} will run a test file, $<$file$>$.tst that does
not require the explicit loading of a package.
If a package must be loaded to run a test (e.g., algint), the name of
the required package should be provided as a second argument to {\tt test}.

\paragraph{test-all}

This script runs all the tests contained in the xmpl directory, using the
{\tt test} script on each one.  This script takes about 45 minutes to run
on a SPARCstation 1.

\paragraph{testlib}

This can be used to run the test files in the {\tt lib} directory.
{\tt  testlib <package>} will run the test file {\tt <package>.tst} in the
{\tt lib} directory, assuming the fasl file for that package has been built.

\paragraph{xbuild}

This is used by {\tt build} to generate a complete set of fasl files by
applying the {\tt mkfasl} script to each package.

\section{Program Registration}
After installing {\REDUCE}, please fill out the accompanying registration
form and send to:
\begin{center}
Dr. Anthony C. Hearn \\
RAND \\
1700 Main Street \\
Santa Monica, CA 90407-2138 \\
Telephone (213) 393-0411 \\
Facsimile (213) 393-4818 \\
Email: reduce@rand.org
\end{center}

This should be done so that you can be advised direct of any changes which
are made to the system.  Furthermore, the copyright statement on the
{\REDUCE} documents requires such registration as a requirement for their
local distribution.  The test time requested on the registration form is
the time printed by the final call of {\tt showtime} in the output from
the test described in the section ``Testing {\REDUCE}".

\section{Inquiries and Reporting of Errors}
We would appreciate hearing about other bugs you encounter or
questions you may have regarding the assembly or the operation of the system.
Suspected errors should be accompanied by the relevant job output and a copy
of the input source.  Corrections for documented problems or other
improvements to the system are also welcomed.

\newpage
\pagestyle{empty}
\begin{center}
{\Large\bf  REDUCE 3.4  Registration Form}
\end{center}
After installing {\REDUCE}, please fill out this form and send to the
listed address.  This should be done so that you can be
advised direct of any changes made to the system.  Furthermore, returning
the registration form is a requirement for local reproduction of the
{\REDUCE} documentation.
\vspace*{3mm} \\
Date: \hrulefill \vspace*{3mm}\\
Contact Person: \hrulefill\ \vspace*{3mm}\\
Organization: \hrulefill \vspace*{3mm} \\
Address: \hrulefill \vspace*{3mm} \\
\hspace*{16 mm} \hrulefill \vspace*{3mm} \\
\hspace*{16 mm} \hrulefill \vspace*{3mm} \\
Telephone: \hrulefill\ \vspace*{3mm} \\
Network Address: \hrulefill \\
{\small (Indicate network: Internet, BITNET, EARN, UUCP, etc)}
\vspace*{3 mm} \\
REDUCE Supplier: \hrulefill \\[3mm]
Computer Description:
\vspace*{3 mm} \\
Vendor: \hrulefill \vspace*{2mm}    Model: \hrulefill \vspace*{2mm}
Operating System: \hrulefill \\
Please indicate the test time as printed by the final call of {\tt showtime}
in the output from the installation test described in the
section ``Testing {\REDUCE}" of the {\REDUCE} Installation Guide.  Also
give the total system time, region (virtual) and real system memory
available, if applicable. \vspace*{4mm}
\\
Time: \hrulefill Total System Time: \hrulefill\   Region: \hrulefill \vspace*{4mm}
\\
Real System Memory: \hrulefill  .\hspace*{5cm}
\vspace*{3 mm} \\
Please also write on the back of this form any comments you may have about
the installation procedure, and system documentation and performance.
\\[3mm]
\noindent
If you would like to be listed in a published registry of {\REDUCE} system
holders, please check here $\Box$ .

\end{document}