\chapter{The distribution}
\section{Files included}
\subsection{Executable files}
\begin{verbatim}
        gpm             ; the parent process of the compiler
        gpmd            ; the body of the compiler frontend
        dgen            ; the body of the native code generator
        build           ; the parent process of the builder
        build2          ; the body of the builder
        gpxrf           ; the cross-reference generator
        gpmake          ; the smart recompilation utility
        decider         ;   used by gpmake
        graphbuild      ;   used by gpmake
        gpscript        ; generates complete recompilation script
        grepdef         ; the definition finder
        decode          ; symbol file decoder
        mkenumio        ; creates IO procedures for an enumeration
\end{verbatim}

\subsection{Library definition files}
All library modules must have their symbol files on the M2SYM directory path.
\begin{verbatim}
        ascii.def               ; Ascii
        asciitime.def           ; AsciiTime
        buildargs.def           ; BuildArgs
        cardsequences.def       ; CardSequences
        cardstr.def             ; CardStr
        charinfo.def            ; CharInfo
        convtypes.def           ; ConvTypes
        coroutines.def          ; Coroutines
        frexp.def               ; FREXP
        gensequencesupport.def  ; GenSequenceSupport
        gpfiles.def             ; file lookup strategy
        inout.def               ; InOut
        intstr.def              ; IntStr
        pathlookup.def          ; PathLookup
        pipeutilities.def       ; PipeUtilities
        progargs.def            ; ProgArgs
        random.def              ; Random
        realinout.def           ; RealInOut
        realmath.def            ; RealMath
        realstr.def             ; RealStr
        shellpipes.def          ; ShellPipes
        stderror.def            ; StdError
        stdstrings.def          ; StdStrings
        storage.def             ; Storage
        sysclock.def            ; SysClock
        system.def              ; SYSTEM (pseudo module)
        terminal.def            ; Terminal
        textinout.def           ; TextInOut
        types.def               ; Types
        uxfiles.def             ; UxFiles
        uxhandles.def           ; UxHandles
        uxprocesses.def         ; UxProcesses
\end{verbatim}

\subsubsection*{Other files on M2SYM path}
\begin{verbatim}
        gp2d.cfg                ; frontend configuration file
        m2errlst.dat            ; the verbose error-list file
        gpmain.dcf              ; the DCode main() used by BUILD
\end{verbatim}

\subsection{Library Object files}
All libraries must have their object files on the M2LIB directory path.
Exceptions are those !{\em FOREIGN} modules whose implementations are
entirely within the header file, and those marked !{\em SYSTEM}.
\begin{verbatim}
        asciitime.o             ; AsciiTime
        buildargs.o             ; BuildArgs
        cardsequences.o         ; CardSequences
        cardstr.o               ; CardStr
        charinfo.o              ; CharInfo
        convtypes.o             ; ConvTypes
        coroutines.o            ; Coroutines
        frexp.o                 ; FREXP
        gensequencesupport.o    ; GenSequenceSupport
        gpfiles.o               ; file lookup strategy
        inout.o                 ; InOut
        intstr.o                ; IntStr
        pathlookup.o            ; PathLookup
        pipeutilities.o         ; PipeUtilities
        random.o                ; Random
        realinout.o             ; RealInOut
        realmath.o              ; RealMath
        realstr.o               ; RealStr
        shellpipes.o            ; ShellPipes
        stderror.o              ; StdError
        stdstrings.o            ; StdStrings
        storage.o               ; Storage
        sysclock                ; SysClock
        terminal.o              ; Terminal
        textinout.o             ; TextInOut
        uxfiles.o               ; UxFiles
        uxhandles.o             ; UxHandles
        uxprocesses.o           ; UxProcesses
\end{verbatim}

\subsubsection*{Other object files}
\begin{verbatim}
        gprts.o                 ; generic runtime system
        gpmrts.o                ; modula specific runtime
\end{verbatim}

\subsection{Library reference files}
All libraries (except those marked {\em FOREIGN\/} or
{\em INTERFACE\/}) must have reference 
files which are readable on the \$M2LIB directory path.
\begin{verbatim}
        buildargs.rfx           ; BuildArgs
        cardsequences.rfx       ; CardSequences
        cardstr.rfx             ; CardStr
        charinfo.rfx            ; CharInfo
        convtypes.rfx           ; ConvTypes
        gensequencesupport.rfx  ; GenSequenceSupport
        gpfiles.rfx             ; file lookup strategy
        intstr.rfx              ; IntStr
        pathlookup.rfx          ; PathLookup
        random.rfx              ; Random
        realstr.rfx             ; RealStr
        stdstrings.rfx          ; StdStrings
        types.rfx               ; Types
\end{verbatim}

\subsection{Library source files}
These files are included only as examples of foreign implementations
where the functionality of the module is already available in the 
standard $C$ libraries.
\begin{verbatim}
        textinout.c             ; foreign implementation of TextInOut
        asciitime.c             ; foreign implementation of AsciiTime
        sysclock.c              ; foreign implementation of SysClock
        uxhandles.c             ; foreign implementation of UxHandles
\end{verbatim}

\subsection{Other source files}
These files are simple examples of modules written in \gpm.
\begin{verbatim}
        build.mod               ; parent process of Build
        buildargs.mod           ; source of BuildArgs
        cardsequences.mod       ; source of CardSequences
        gensequencesupport.mod  ; source of GenSequenceSupport
        gpm.mod                 ; parent process of gpm
        pathlookup.mod          ; source of PathLookup
        tautology.mod           ; a tautology checker
        traverse.mod            ; a coroutine exercise
\end{verbatim}
The program {\em tautology} is an example of several techniques: recursive 
descent parsing, creating an abstract syntax tree, and short-circuit 
evaluation of Boolean expressions. The program prompts for a command,
and will parse boolean expressions, construct truth tables, and evaluate 
Boolean expressions (prompting as necessary for variable values).

{\em Traverse} is an interesting exercise in coroutine use. A coroutine 
body encapsulates a conventional inorder walk of an ordered binary tree. 
The state of the traversal is frozen while the coroutine is inactive, 
allowing the tree elements to be accessed one-by-one. The tree interface 
provides {\em Initialize} and {\em GetNext} operations, effectively 
transforming the {\em table} abstract data object into a {\em list}. 

\subsection{Files for the administrator}
The following files are also on the distribution for the system
adminstrator to use.

These files are the raw source files for the {\bf man} entries for 
\gpm,  {\bf build} etc.
\begin{verbatim}
        gpm.man                 ; gpm manual entry
        build.man               ; build manual entry
        grepdef.man
        gpmake.man
        gpxrf.man
        decode.man
\end{verbatim}

The final two files allow adaptation of the verbose error lists
\begin{verbatim}
        m2errs.txt              ; error text file
        m2errlst.mod            ; source of indexing program
\end{verbatim}
The program M2ErrLst reads the source file {\tt m2errs.txt}
in the current directory, and writes an error-index file 
{\tt m2errlst.dat} in  the current directory. This file is in the 
format required by \gpm\ for verbose error listings, and for the 
interactive option. If the error text file is modified, it must be 
processed by M2ErrLst, and the resulting data file copied to a 
directory on the M2SYM environment variable.

\section{Directory organization}
The symbol files of library modules must be in directories defined by the
M2SYM environment variable.  This path must also contain the configuration
file and the verbose error message data file.  The reference and object files
of library modules must be available in directories defined by the M2LIB
environment variable.  This path must also contain the runtime system object
files.  In cases where all \gpm\ users are sharing the same libraries it is
possible to place all these files in a single directory.

Both \gpm\ and {\bf build} search the current directory before searching 
the library paths. It is possible therefore to replace library object 
files by local versions without disturbing other users.


\section{Installation instructions}
\gpm\ is normally distributed either as a compressed {\em tar} file or as a
{\em zip} file.

The steps in unarchiving and installing \gpm\ are the following ---
\begin{itemize}
\item[1] make a directory (for example {\tt /gpm}) for the installation of gpm
\item[2] change to the new directory, for example {\tt cd /gpm}
\item[3] extract the files using unzip or tar as appropriate. For example,\\
\verb+          gzip -d gpmlinux.tar.gz+\\
\verb+          tar -xf gpmlinux.tar+
\item[4] set up the M2SYM and M2LIB environment variables
         See Chapter 7 of the Reference Manual for information about other
	 optional environment variables that \gpm\ uses.
\end{itemize}
You are now ready to use GPM!

