\documentstyle{article}

\begin{document}

\sloppy
\pagestyle{plain}

\title{{\em Adlib} version 1.0 \\ Installation Notes}

\author{D.B. Carpenter}

\maketitle

\section{Prerequisites for installation}

    {\em Adlib} is a C++ class library for data-parallel programming.
The current implmentation is layered on MPI.

Prerequisites for installation are:
\begin{itemize}
	\item a C++ compiler, and
	\item an MPI installation.
\end{itemize}
These two systems form the {\em software platform} for the Adlib
installation.  Section \ref{platforms} records the platforms on which
we have successfully installed Adlib so far.  If you have a
significantly different platform, please contact
\verb$dbc@npac.syr.edu$.  We will make our best efforts to help with
the installation (and incorporate the knowledge gained into subsequent
releases).

Public domain releases of C++ and MPI are available by anonymous ftp
as follows:
\begin{itemize}
	\item The GNU C++ compiler is available from various sites, 
e.g.\ Imperial College at \verb$ftp://src.doc.ac.uk/pub/GNU/gcc-2.6.3.tar.gz$.  
You will also need \verb$ftp://src.doc.ac.uk/pub/GNU/libg++-2.6.2.tar.gz$.

	\item The Argonne National Laboratory MPI implementation, MPICH, 
is available from \verb$ftp://info.mcs.anl.gov/pub/mpi$.  For further 
information, see the WWW page at \verb$http://www.mcs.anl.gov/mpi/index.html$.
\end{itemize}

\section{How to obtain Adlib}

The Adlib release package is available by anonymous ftp from
{\em [\ldots]}
where it is contained in the archive file \verb$Adlib.1.0.tar.Z$.

     Working in a suitable root directory, extract the archive file.  For
example:
\begin{verbatim}
  zcat mpich.tar.Z | tar xvf -
\end{verbatim}
This creates a subdirectory called \verb$Adlib$ in the current directory.
\verb$Adlib$ is now the home directory for the installation.


\section{\label{building}Building Adlib}

\begin{enumerate}
\item
Ensure that the C++ compiler is on your path.

\item
Change directory to the Adlib home directory, e.g.:
\begin{verbatim}
  cd Adlib
\end{verbatim}

\item
Configure the release with the \verb$configure$ script 
located in this directory.  This script tailors
various scripts and \verb$make$ files to the local software platform.
Eventually we hope to provide a more intelligent GNU-style
configuration script.  For now, you must provide the required
information about the platform as arguments to \verb$configure$.  
The usage of \verb$configure$ is:
\begin{verbatim}
  configure  -c++com=C++_COM
            [-mpilib=MPI_LIB] [-mpiinc=MPI_INC_DIR] [-cmpih]
\end{verbatim}
where:
\begin{description}
\item{\verb$C++_COM$}
is the command to execute the C++ 
compiler.  The \verb$-c++com$ argument is compulsory.
\item{\verb$MPI_LIB$}
is the library (or list of libraries) containing MPI.
The library may be specified by an absolute file name
(usually with a \verb$.a$ or \verb$.so$ extension) or in the
conventional \verb$-l${\em name} form.
This option can be omitted if the library concerned
is imported by the C++ command.
\item{\verb$MPI_INC_DIR$} is the directory where MPI 
include files are located.  The \verb$-mpiinc$ argument may be omitted if 
the include directory is specified in the C++ command.
\end{description}
Section \ref{configure} provides a complete guide to the
\verb$configure$ arguments.
This release includes various wrapper scripts called 
\verb$configure.${\em host} which illustrate the argument values we have 
used for to configure the software for various platforms.  You may be able
to choose the wrapper script for the software platform most similar to 
your own, and edit it.  See section \ref{platforms} for further details.

\item If \verb$configure$ completed successfully, build everything 
by typing:
\begin{verbatim}
  make
\end{verbatim}

\end{enumerate}


\section{Using \tt ad++}

Add the \verb$bin$ directory in the Adlib home directory to your path, e.g.:
\begin{verbatim}
  set path = ($path ~/Adlib/bin)
\end{verbatim}
and the \verb$man$ directory to your \verb$man$-path, e.g.:
\begin{verbatim}
  setenv MANPATH ${MANPATH}:~/Adlib/man
\end{verbatim}
The command
\begin{verbatim}
  man ad++
\end{verbatim}
tells you how to use the \verb$ad++$ command to compile an Adlib program.

The output of the compilation is an executable containing calls to the
MPI library.  The procedure for executing this program depends on your
MPI platform.

For example, suppose that Adlib has been configured to use a P4-based
installation of MPICH.  If \verb$test.C$ is an Adlib program requiring 3
processors for its execution, it may be compiled and run by the commands:
\begin{verbatim}
  ad++ test.C
  mpirun -mr_pg -machinefile ~/machines -mr_np 3 a.out
\end{verbatim}
where \verb$machines$ is a file in your current working directory or personal
home directory, containing a list of host names upon which MPI processes 
can be spawned.  For instance, if you want to allow a maximum of 4 MPI
processes to be run on just one workstation called \verb$weed$, the
\verb$machines$ file might contain the lines:
\begin{verbatim}
  weed
  weed
  weed
  weed
\end{verbatim}


\section{\label{platforms}Platforms on which Adlib has been installed}

\begin{table}[hbtp]
\centerline{
\begin{tabular}{|c|c|c|c|c|}
\hline
C++        & MPI        & architecture & host  \\
\hline
GNU g++    & MPICH/P4   & Sun 4      & bacchus \\
SunOS CC   &    ''      &    ''      & nag     \\
Solaris CC &    ''      &    ''      & uxa     \\
GNU g++    & CHIMP MPI  &    ''      & epcc    \\
           &            &            &         \\
GNU g++    & MPICH/P4   & IBM RS6000 & ben     \\
AIX xlC    &    ''      &    ''      &  ''     \\
           &            &            &         \\
AIX xlC    & MPICH/EUI  & IBM SP2    & sp2     \\
    ''     & Native MPI &    ''      & sp2xx   \\
           &            &            &         \\
DEC cxx    & MPICH/P4   & DEC Alpha  & asterix \\
           &            &            &         \\
IRIX CC    & MPICH/P4   & SGI        & pawnee-atm \\
\hline
\end{tabular}
}
\caption{\label{plat_table}Some installation platforms}
\end{table}

Table \ref{plat_table} lists the platforms on which Adlib
has been installed so far.  They are labelled by host name or site.  

The release directory contains a set of wrapper scripts
called \verb$configure.${\em host} which illustrate the options we used
for these platforms.  If your software platform is the same as any of those
in Table \ref{plat_table}, it should be possible to construct an appropriate 
set of \verb$configure$ options with minimal changes to the corresponding
wrapper.

\section{\label{configure}More on configuring}

The information in this section is provided for completeness---it may 
or may not be useful to typical installers.  In later releases we intend 
to provide a more intelligent configuration script, but first we have 
to gain experience manually configuring the system on as many platforms 
as possible.

\subsection*{What the {\tt configure} script does}

It creates the following files in the Adlib home directory:
\begin{verbatim}
  src/adlib/Makefile
  bin/ad++
\end{verbatim}
They are constructed from templates, by filling in details about the
local software platform.  It also creates an empty directory, \verb$lib$.

Once this has been done, the installation can be built by simply typing 
\verb@make@ in the Adlib home directory, which invokes the above 
\verb@Makefile@ to compile the library.

\subsection*{Arguments to {\tt configure}}

The usage of the \verb$configure$ script was given in section
\ref{building}.  This section gives more detail on the choice of
the various fields in the arguments for \verb$configure$.
\begin{description}
\item[\tt -c++com=C++\_COM]

\mbox{~~~} \\
\verb$C++_COM$ is the command to execute the C++ compiler.  It is
invoked to compile the HPF run-time library when the installation is
being built.  The command will be applied to one C++ file at a time,
with filename suffix \verb$.C$.

It is also invoked by the \verb$ad++$ script to compile the code
the users program, and link it with the Adlib library.

Often the \verb$C++_COM$ string will include \verb$-L$ options
to tell the linker where to search for MPI libraries.

\item[\tt -mpilib=MPI\_LIB]

\mbox{~~~} \\
\verb$MPI_LIB$ is the file or list of files containing the MPI library.  
It is passed to the linker by the \verb$ad++$ script.
The \verb$-l${\em name} form will also work, provided the compiler
command knows where to find the named library---see the description of
\verb$C++_COM$.

This argument can be omitted if the MPI library is automatically imported
by the compiler command.

\item[\tt -mpiinc=MPI\_INC\_DIR]

\mbox{~~~} \\
\verb$MPI_INC_DIR$ is the directory where MPI include files are located.
This argument affects compilation of the Adlib library, which occurs 
when the installation is being built.

This argument can be omitted if the MPI include directory is automatically
searched by the C++ command.

\item[\tt -cmpih]

\mbox{~~~} \\
This flag affects the compilation of the Adlib library.  
It forces \verb$#include mpi.h$ directives to be wrapped in an
\verb$extern "C"$ linkage specifier.  Normally this is unnecessary (it
is omitted by default).  Unfortunately some combinations of C++
compiler and MPI implementation require this wrapper, and (worse)
some combinations refuse to accept it.
\end{description}

\end{document}


