% Copyright (C) 1989, Digital Equipment Corporation
% All rights reserved.
% See the file COPYRIGHT for a full description.
%
% Last modified on Tue Jul 24 00:46:32 1990 by muller
%      modified on Wed Feb 21 17:22:07 1990 by kalsow


\chapter{Installation}

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

\section{Getting \srcmodula\relax}
%=================================

\srcmodula is distributed through anonymous {\tt ftp} on {\tt
gatekeeper.dec.com}, in a compressed \tar file named {\tt
m3-1.5.tar.Z}. This compressed \tar file is 6 Mb. The table below
indicates the resources necessary for the various installations (all
of them can be made from the same distribution):

\begin{center}
\renewcommand{\arraystretch}{1.2}
\begin{tabular}{l | c | c | c | l | l}
\multicolumn{1}{c|}{System} & 
  \multicolumn{3}{c|}{Requirements} & 
  \multicolumn{1}{c|}{Hardware} &
  \multicolumn{1}{c}{Operating system} \\
             & build (Mb) & build (min) & disk (Mb) & & \\ \hline
{\tt VAX}    & 30  & 50  &  5  & VAX 8800        & Ultrix 3.1 \\
{\tt DS3100} & 35  & 13  &  8  & DECstation 5100 & Ultrix 3.1 \& 4.0 \\
{\tt SPARC}  &     &     &     & Sparcstation-1  & SunOS 4.0.3 \\
{\tt AP3000} & 25  & 70  &     & Apollo DN4500   & Domain/OS 10.2 \\
{\tt AIX386} &     &     &     &                 & AIX/PS2 \\
{\tt IBMR2}  &     &     &     & IBM R6000       & AIX 3.1 \\
{\tt IBMRT}  &     &     &     & IBM RT          & IBM/4.3 (AOS 4.3) \\
{\tt HP300}  &     &     &     & HP 9000/300     & HP-UX 7.0 \\
\end{tabular}
\end{center}
\label{configurations}

We have been told that the {\tt SPARC} version runs on SUN-3's as well
(if compiled on a SUN-3, of course).

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. The table
above, in the column ``Requirements, build'', shows the amount of disk
space necessary to build \srcmodula, while ``Requirements, disk''
shows the amount of disk space permanently occupied (if you remove the
sources).

\item Create a fresh directory for the software. Path names below are relative
to that directory, and it will be called the top-level directory:
\begin{verbatim}
    $ mkdir m3
\end{verbatim}

\item Change to the top-level directory:
\begin{verbatim}
    $ cd m3
\end{verbatim}

\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{verbatim}
    ftp> cd /pub/DEC/Modula-3
\end{verbatim}

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

\item Get the distribution in one shot:
\begin{verbatim}
    ftp> get m3-1.5.tar.Z
\end{verbatim}
or in pieces:
\begin{verbatim}
    ftp> mget m3-1.5.tar.Z-*
\end{verbatim}
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. 

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

\item Put the pieces back together if needed:
\begin{verbatim}
    $ cat m3-1.5.tar.Z-* m3-1.5.tar.Z
    $ rm m3-1.5.tar.Z-*
\end{verbatim}

\item Uncompress the file:

\begin{verbatim}
    $ uncompress m3-1.5.tar.Z
\end{verbatim}

\item Extract the files for this \tar file:
\begin{verbatim}
    $ tar xpof m3-1.5.tar
\end{verbatim}
The \tar arguments specify the following options:

\begin{center}
\begin{tabular}{l @{\hspace*{2cm}} p{4in}}
{\tt x} & extract the files from the \tar file to the current
          directory \\
{\tt p} & restore files to their original modes \\
{\tt o} & override the original ownership, this makes you the owner of
          the files \\
{\tt f} & use the following argument {\tt m3-1.5.tar} as the input file \\
\end{tabular}
\end{center}
You can add the \verb|v| option to see what is going on. This will
create a subdirectory named {\tt dist-1.5} in the top-level directory.
 
\item At this point you may delete the \tar file to save space (the
disk requirements indicated above assume that you do delete this file):
\begin{verbatim}
    $ rm m3-1.5.tar
\end{verbatim}
\end{enumerate}

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

If you are supporting multiple architectures from a single file
system, skip to section~\ref{multiple-config}.

\begin{enumerate}

\item Go to the distribution directory
\begin{verbatim}
    $ cd dist-1.5
\end{verbatim}

\item Select in the table on
page~\pageref{configurations} the name of the system you want to build
(e.g. {\tt VAX}); call that {\it system}.

\item \label{first-step} Using {\tt util/config.dist-{\it system}} as
a model, create {\tt util/config} to describe your system.

\item Configure the system for you machine:
\begin{verse} \tt
   \$ make {\it system}
\end{verse}

\item You may want to modify the {\tt m3(1)} manual page (in {\tt
system/driver/m3/m3.man-1}) to tell users how they can obtain this
document. Also, you may want to change chapter~\ref{local} (in {\tt
doc/local.tex}) to describe your installation.

\item Build \srcmodula:
\begin{verbatim}
   $ make
\end{verbatim}
The table above shows in the ``Requirements, build'' column the CPU time
(in minutes) needed to compile the corresponding distribution of
\srcmodula. 

\item Install \srcmodula:
\begin{verbatim}
   $ make install
\end{verbatim}

\item \label{last-step} Conserve space:
\begin{verbatim}
   $ make clean
\end{verbatim}
\end{enumerate}

\section{Installing for several architectures}
%=============================================

\label{multiple-config}

If you are installing for more than one system from a single
file system, you can share the source files. If you are doing a port,
this can be useful. 

For each architecture you want to support, go to the top-level
directory and:

\begin{enumerate}

\item Clone the distribution directory:
\begin{verse} \tt
    \$ (cd dist-1.5; make {\it system}.obj)
\end{verse}
where {\it system} is one of those mentioned in the table on
page~\pageref{configurations}. This will create a directory named {\tt
{\it system}.obj} in the top level directory. The file tree rooted
there is similar to the distribution tree, but plain files are
symbolic links to the corresponding files in the distribution directory.
This operation is performed by a C program that is compiled on the fly;
you may have to redefine {\tt CC} in {\tt dist-1.5/makefile} so that
it compiles properly.

\item Go to the newly created directory:
\begin{verse} \tt
    \$ cd {\it system}.obj
\end{verse}

\item Install that system, following steps \ref{first-step}
through \ref{last-step} in the previous section.

\end{enumerate}

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

\srcmodula includes a collection of tests programs. While these
programs are intended to help the developpers of \srcmodula, you may
want to look at them (they sometime exhibit weird pieces of code) or
run them. From the distribution directory (or the clone directory, if
you installed for multiple architectures):

\begin{verbatim}
    $ make tests
\end{verbatim}

\section{The demo programs}
%==========================

The demo programs are intended to show \modula in action and sometime
take the form of games. In this release, the examples show how to use
the X11R4 interfaces; there are some simple programs and some games.
Because the compilation time is rather long, the demo programs are not
build by the procedure shown above. To build them, go to the
distribution directory (or the clone directory, if you installed for
multiple architectures):

\begin{verbatim}
  $ make demos
\end{verbatim}

\section{What's in the distribution}
%===================================

The distribution hierarchy comprises the following directories:

\begin{center}
\begin{tabular}{ll}
{\tt util}     & tools to build and install the system \\
{\tt system}   & \\
\quad {\tt compiler} & the \modula to C compiler  \\
\quad {\tt driver}   & glue for the compiler passes:
                       compile , C-compile, link, ... \\
\quad {\tt loader}   & the \modula specific loader  \\
\quad {\tt runtime}  & the required runtime system  \\
\quad {\tt corelib}  & utility modules forming a core library  \\
{\tt tests}    & test programs for the \modula system  \\
{\tt libs}     & additional libraries (described in chapter~\ref{libs})\\
{\tt tools}    & \\
\quad {\tt coverage} & a line-based profiler \\
\quad {\tt depend}   & a tool to detect if a file needs to be recompiled  \\
\quad {\tt pp}       & pretty-printer \\
{\tt demos}    & example programs for the libraries \\
{\tt contrib}  & contributed tools and libraries \\
{\tt doc}      & source for this document and license agreement \\
\end{tabular}
\end{center}


Each directory contains a \verb|README| that describes
the contents of that directory and an \verb|Imakefile| that rebuilds and
installs the contents of that directory.