% Copyright (C) 1989, Digital Equipment Corporation
% All rights reserved.
% See the file COPYRIGHT for a full description.
%
% Last modified on Thu Jan  7 18:40:11 PST 1993 by muller                    .
%      modified on Tue Dec 15 11:47:59 PST 1992 by kalsow                    .



\chapter{Installation}

This chapter describes how to get and install the \srcmodula system.

\section{What is available}
%==========================

        \index{FTP@{\tt FTP}}
        \index{gatekeeper.dec.com@{\tt gatekeeper.dec.com}}
\srcmodula is distributed via anonymous {\tt ftp} from {\tt
gatekeeper.dec.com}.   The distribution is in a set of compressed \tar
files in the directory named {\tt pub/DEC/Modula-3/release}.  The
files are of the form {\tt {\it archive}-\release.tar.Z}.

        \index{platforms, supported}
        \index{architectures, supported}
        \index{systems, supported}

The archives {\tt boot.{\it architecture}} are used to build and
install {\tt m3make}, a driver and a compiler.  These programs are
built from intermediate C files that are architecture specific; you
need to get the archive(s) corresponding to the architecture(s) on
which you want to install \srcmodula.  The supported {\it
architecture}s are:

\begin{center}
\begin{tabular}{l | l l | r c | r}
\multicolumn{1}{c|}{\it architecture}
   & Hardware 
   & Operating system
   & \multicolumn{2}{c|}{Build} 
   & \multicolumn{1}{c}{Install} \\

   & & & \multicolumn{1}{c}{disk} 
   & \multicolumn{1}{c|}{cpu}
   & \\       

   & & & \multicolumn{1}{c}{(KB)}
   & \multicolumn{1}{c|}{(min)}
   & \multicolumn{1}{c}{(KB)} \\ \hline

AIX386 &                      & AIX/PS2           &       &           &      \\
AP3000 & Apollo DN4500        & Domain/OS 10.2    &       &           &      \\
ARM    & Acorn R260           & RISC iX 1.21      &       &           &      \\
\input bsize.tex
HP300  & HP 9000/300          & HP-UX 7.0         &       &           &      \\
HPPA   & HP 700/800           & HP-UX 8.0         &       &           &      \\
IBMR2  & IBM RISC System/6000 & AIX 3.1           &       &           &      \\
IBMRT  & IBM RT               & IBM/4.3 (AOS 4.3) &       &           &      \\
NEXT   & NeXT                 &                   &       &           &      \\
OKI    & Okidata 7300 (i860)  & AT\&T SVR4.0      &       &           &      \\
SPARC  & Sparcstation-1       & SunOS 4.1.x       &       &           &      \\
SUN3   & Sun 3/?              & SunOS ?           &       &           &      \\
SUN386 & Sun 386i             & SunOS 4.0.1       &       &           &      \\
UMAX   & Encore Multimax      & UMAX 4.3 (R4.1.1) &       &           &      \\
VAX    & VAX 8800             & Ultrix 4.2        &       &           &      \\
\end{tabular}
\end{center}
\label{configurations}

Each of these archives is about 4000 kilobytes.  The column ``Build'' indicates
the resources you need to build and install the programs: ``disk'' is the
amount of disk space (in kilobytes), ``cpu'' is the amount of user and system
cpu time (in minutes).  The column ``Install'' indicates the amount of disk
space that will be permanently used after the installation is done.

          \index{libraries}
          \index{archives}
The other archives contain Modula-3 source files for various libraries
and programs.

\begin{center}
\begin{tabular}{l r | r r | r | r | l }
\multicolumn{2}{c|}{File}
   & \multicolumn{2}{c|}{Build} 
   & Install
   & Sources
   & Contents \\
Name
   & Size
   & \multicolumn{1}{c}{disk}
   & \multicolumn{1}{c|}{cpu}
   & & & \\

   & \multicolumn{1}{c|}{KB}
   & \multicolumn{1}{c}{KB} 
   & \multicolumn{1}{c|}{min}
   & \multicolumn{1}{c|}{KB}
   & \multicolumn{1}{c|}{KB}
   & \\ \hline
\input sizes
\end{tabular}
\end{center}

The column ``File Size'' is the size (in kilobytes) of the compressed
tar file.  The column ``Build'' indicates the resources you need to
build and install these pieces of sources: ``disk'' is the amount of
disk space (in kilobytes), ``cpu'' is the amount of user and system
cpu time (in minutes).  The column ``Install'' indicates the amount of
disk space that will be permanently used after the installation is
done and the sources are deleted.  If you want to keep the sources
around, you will need the additional space indicated in the
``Sources'' column.  These time and sizes were measured on a
DECstation 5000/240 running Ultrix 4.2; other architectures may have
different requirements.

You need to build and install {\tt libm3} to have a useful system, but
all the other pieces are optional.  Here is the dependency graph for
the archives:

\begin{center}
\input dep.tex
\end{center}

The {\tt m3make} and {\tt doc} archives are included in the {\tt boot}
archives so you don't need to install them explicitly.

The {\tt compiler} and {\tt driver} archives contain the Modula-3 sources
while the {\tt boot} archives contain the intermediate C code for those
programs.  Unless you want to look at the sources of these programs, you don't
need to install the {\tt compiler} and {\tt driver} archives.


\section{Getting \srcmodula\relax}
%=================================
\label{getting-srcmodula}

            \index{FTP@{\tt FTP}}
In the following, {\tt \$} is the shell prompt and {\tt ftp>} is the
{\tt ftp} prompt. To get \srcmodula:

\begin{enumerate}

\item Make sure that you have enough disk space using the tables above.
  
\item Create a fresh directory for the software and go there. Path
  names below are relative to that directory, and it will be called the
  top-level directory:
\begin{verse} \tt
    \$ mkdir {\it top-level} \\
    \$ cd {\it top-level} \\
\end{verse}

\item Open an \ftp connection with {\tt gatekeeper.dec.com}
[16.1.0.2]; give {\tt anonymous} for the name and your login id for the
password:
\begin{verse} \tt
    \$ ftp gatekeeper.dec.com\\
    Connected to gatekeeper.dec.com.\\
    ...\\
    Name (gatekeeper.dec.com): anonymous\\
    Password (gatekeeper.dec.com:anonymous): {\it your name}@{\it your machine}\\
    ...\\
\end{verse}

\item Change to the proper directory:
\begin{verse} \tt
    ftp> cd pub/DEC/Modula-3/release
\end{verse}

\item Set the transmission type to binary:
\begin{verbatim}
    ftp> type binary
\end{verbatim}

\item Get the distribution bootstrap:
\begin{verse} \tt
    ftp> get boot.{\it architecture}-\release.tar.Z
\end{verse}

%% Other files are also available in the same directory; {\tt Report.ps}
%% is the \modula in PostScript format. \verb|Report{1,2,3}.ps| is the
%% same, but in pieces. The files {\tt m3-mail.{\it month}-{\it year}.Z}
%% contain (in compressed format) the messages sent to the
%% \verb|m3@src.dec.com| mailing list (through 1990) and to \newsgroup
%% (after).

\item Get {\tt libm3} along with any other \modula sources that you want:
\begin{verse} \tt
    \verb|ftp>| get libm3-\release.tar.Z \\
    \verb|ftp>| get ... \\
\end{verse}

\item Close the connection:
\begin{verbatim}
    ftp> quit
\end{verbatim}

\end{enumerate}

\section{Installation procedure}
%===============================

Once you have ftp'ed the archives, you need to do the following
from the top-level directory to build and install the system:

\begin{enumerate}

\item Unpack the {\tt boot.{\it architecture}} archive:
\begin{verse}\tt
    \$ zcat boot.{\it architecture}-\release.tar.Z | tar xpof - \\
    \$ rm  boot.{\it architecture}-\release.tar.Z
\end{verse}

\item Using {\tt m3make/model-configs/{\it architecture}} as a model, create a
configuration file for your installation of \srcmodula in {\tt m3make/{\it
architecture}/config}.
  
\item Make sure that the directory named on the ``\verb|BIN_USE = |'' line
in your {\tt config} is on your search path.

\item Build and install the {\tt m3make} system:
\begin{verse} \tt
    \$ (cd m3make/{\it architecture}; make -f ../src/Makefile all install)
\end{verse}
You may need to tell your shell that new executables ({\tt m3make})
are present after the install step, using {\tt rehash}, for example.

\item You may want to change chapter~\ref{local} of this document to
  describe your installation (see that chapter to know how to proceed).

\item Build and install the \srcmodula driver and compiler:
\begin{verbatim}
    $ m3make -f m3makefile.boot all install
\end{verbatim}
This moves the driver, the compiler and some other files to the
directories specified in your {\tt config} file.
Again, you may need to tell your shell that new executables ({\tt m3})
are present, using {\tt rehash}, for example.

\item At this point, you should have successfully installed the \modula
compiler and driver.  To check, type
\begin{verbatim}
    $ m3 -\?
\end{verbatim}
The driver should list its configuration options.

\item You can now delete the bootstrap directories to conserve space:
\begin{verbatim}
    $ rm -f m3make driver compiler
\end{verbatim}
(Note: if you are doing a port, don't do that!)

\item Build and install the other libraries and tools.
Now, you have a choice.  You can install all of them at once (a)
or install them one at a time by hand (b).  Installing them all
at once is easiest, but requires more disk space at its worst moment.

\begin{enumerate}
\item To install all of them at once, starting from the compressed tar files:
\begin{verbatim}
    $ m3make build_install.all
\end{verbatim}
After this is done, you can:
\begin{verbatim}
    $ m3make clean.all
\end{verbatim}
to remove all the derived files and keep only the sources, or you can:
\begin{verbatim}
    $ m3make delete.all
\end{verbatim}
to delete all the non-installed files.

\item To build and install the archive {\it archive}:
\begin{verse} \tt
         \$ m3make build\_install.{\it archive}
\end{verse}
After this is done, you can:
\begin{verse} \tt
         \$ m3make clean.{\it archive}
\end{verse}
to remove all the derived files and keep only the sources, or you can:
\begin{verse} \tt
         \$ m3make delete.{\it archive}
\end{verse}
to delete all the files.
\end{enumerate}

If you select (b), you need to start with \verb|libm3| and make sure that you
build according to the dependency graph shown above.
There is no need to rebuild and reinstall the \verb|m3make|, \verb|doc|,
\verb|driver| or \verb|compiler| source archives (but you can do so if you 
want).

Whether you choose option (a) or option (b), the libraries and tools
will be built using the system installed in the previous step and
should help detecting problems in the installation.  

\item If you want to build the gnuemacs tags file for the public interfaces:
\begin{verbatim}
    $ m3make FTAGS
\end{verbatim}
\end{enumerate}

Later, you can upgrade any of the source components, including \verb|m3make|,
\verb|doc|, the \verb|driver| or the \verb|compiler|, by building and 
installing the corresponding source archive; you should not need to remove the
existing files then.



\section{Running the tests}
%==========================

\srcmodula includes a collection of test programs.  While these
programs are primarily intended to help the developers of \srcmodula,
you may want to look at them or run them.  The tests are available in the
archive {\tt tests}. If you're interested, see the {\tt README}
file at the top-level of that archive.

