\documentstyle{article}

\begin{document}

\sloppy

\pagestyle{empty}

\title{Installation Notes \\
       Southampton {\em High Performance Fortran} Translation System,
       Beta release 0.1}

\author{D.B. Carpenter}

\maketitle

\pagestyle{plain}

\section{Prerequisites for installation}

    The translation system works by translating HPF to standard
Fortran 90, with calls to an HPF run-time system written in C++; the
run-time library is layered on MPI.  Besides the standard
UNIX utilities, prerequisites for installation are
\begin{itemize}
\item
A standard Fortran 90 compiler.
\item
A C++ compiler.
\item
An MPI installation.
\end{itemize}
The combination of these three systems is the {\em software platform} for
the HPF installation.  Section \ref{platforms} records the platforms on
which we have successfully installed HPF so far.  If you have a
significantly different platform, please contact us
at \verb$info-hpf@par.soton.ac.uk$ or \verb$bug-hpf@par.soton.ac.uk$.
We will make our best efforts to help with the installation (and
incorporate the knowledge gained into subsequent releases).

Public domain releases of C++ are available from
\begin{itemize}
\item
The GNU compiler is available in the UK from the FTP site at imperial
college: \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$.
\end{itemize}

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

\section{Distribution}

     The HPF distribution is contained in the archive file
\verb$shpf.0.1.tar$.  The beta release is available by FTP from
\verb$par.soton.ac.uk$ in the directory \verb$/pcsg/hpf_trans$.
Contact us at \verb$info-hpf@par.soton.ac.uk$ to receive the password.

     Working in a suitable root directory, extract the archive file.  For
example
\begin{verbatim}
  tar xvf shpf.0.1.tar
\end{verbatim}
This creates a directory called \verb$shpf$ in the current directory.
\verb$shpf$ is now the home directory for the HPF installation.

\section{\label{building}Configuring and building HPF}

\begin{enumerate}
\item
Ensure the C++ compiler and the Fortran 90 compiler are somewhere on
your path.
\item
Change directory to the HPF home directory, eg
\begin{verbatim}
  cd shpf
\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 ``by hand''.  The usage of is
\verb$configure$ is
\begin{verbatim}
  configure [-mpiinc=MPI_INC_DIR] [-mpilib=MPI_LIB]
            [-f90=F90]
            [-f90com=F90_COM] [-f90lib=F90_LIB]
            [-c++com=C++_COM] [-c++lib=C++_LIB]
            [-lnkcom=LNK_COM]
\end{verbatim}
Here
\begin{description}
\item{\verb$MPI_INC_DIR$}
is the directory where MPI include files are located.
\item{\verb$MPI_LIB$}
is the file (or list of files) containing the MPI libraries.
\item{\verb$F90$}
is a symbol identifying the Fortran 90 platform.  Currently it must be
one of \verb$nag$ or \verb$aix$.
\item{\verb$F90_COM$}
is the command to execute the Fortran 90 compiler
\item{\verb$F90_LIB$}
is the file (or list of files) containing Fortran 90 run-time
libraries.
\item{\verb$C++_COM$}
is the command to execute the C++ compiler.
\item{\verb$C++_LIB$}
is the file (or list of files) containing C++ run-time
libraries.
\item{\verb$LNK_COM$}
is the command to execute the linker.
\end{description}
This release includes various wrapper scripts called
\verb$configure.${\em host} which illustrate the options we used for to
configure the software for various local platforms.  You may be able to
choose the wrapper script for the host most similar to your own, and
edit it.  See section \ref{platforms} for further details.  Section
\ref{configure} provides a more complete guide to the choice of
\verb$configure$ options.

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

\end{enumerate}

\section{Using HPF}

Add the \verb$bin$ directory in the HPF home directory to your path, eg
\begin{verbatim}
  set path = ($path /local/shpf/bin)
\end{verbatim}
and the \verb$man$ directory to you \verb$man$-path, eg
\begin{verbatim}
  setenv MANPATH ${MANPATH}:/local/shpf/man
\end{verbatim}
The command
\begin{verbatim}
  man hpf
\end{verbatim}
tells you how to use the \verb$hpf$ script to compile an HPF program
(this information is also provided in the accompanying release notes).

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.

As an example, suppose HPF has been configured to use a P4-based
installation of MPICH.  If \verb$test.hpf$ is an HPF program requiring 3
processors for its execution, it might be compiled and run by
the commands
\begin{verbatim}
  hpf test.hpf
  mpirun -mr_pg -machinefile ~/machines -mr_np 3 a.out
\end{verbatim}
Because this particular platform was used frequently during development
of the HPF system, this release includes a short script called
\verb$hpfrun$ in the \verb$bin$ directory.  The call to \verb$mpirun$
can be replaced by
\begin{verbatim}
  hpfrun 3 a.out
\end{verbatim}
The example assumed you have a file \verb$machines$ in your personal
home directory, containing a list of host names upon which MPI
processes can be spawned.  If you want to allow a maximum of 4 MPI
processes to be run on just one workstation called \verb$bacchus$---the
\verb$machines$ file might contain the lines
\begin{verbatim}
  bacchus
  bacchus
  bacchus
  bacchus
\end{verbatim}
(We emphasize that \verb$hpfrun$ is {\em not} a portable mechanism for
running HPF programs; if your platform is different from the one
referred to above you will probably have to provide your own script for
this purpose.)

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

\begin{table}[hbtp]
\centerline{
\begin{tabular}{|c|c|c|c|c|}
\hline
Fortran		& C++		& MPI		& architecture	& host    \\
\hline
Nag f90		& GNU g++	& MPICH/P4	& RS6000	& ben     \\
Nag f90		& GNU g++	& MPICH/P4	& SUN 4		& bacchus \\
AIX xlf90	& AIX mpCC	& MPICH/EUI 	& SP2		& sp2     \\
\hline
\end{tabular}
}
\caption{\label{plat_table}Some installation platforms}
\end{table}

Table \ref{plat_table} lists a set of platforms on which the
translation system has been installed.  They are tagged by
host names.  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 the ones
above, it should be possible to construct an appropriate set of
\verb$configure$ options with minimal changes to the corresponding
wrapper---for example, you may only need to change the MPI home
directory path name.

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

Configuration can be a tedious process, due to the need to get the
three major components of the software platform---Fortran 90, C++ and
MPI---interworking smoothly.  If you experience problems, especially if
your platform is significantly different from any of those listed in
section \ref{platforms}, please contact us 
at \verb$info-hpf@par.soton.ac.uk$ or \verb$bug-hpf@par.soton.ac.uk$.
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 configure script does}

It creates the following files in the HPF home directory
\begin{verbatim}
  src/adlib/Makefile
  src/interface/Makefile
  bin/hpf
  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$.

\subsection*{Options to configure}

The syntax of the \verb$configure$ script was given in section
\ref{building}.  This section goes into more detail on the choice of
the various fields in the options for the configure script---their
effects, and typical values.

Currently, most of the options are compulsory.

\subsubsection*{-mpiinc=MPI\_INC\_DIR}

\verb$MPI_INC_DIR$ is the directory where MPI include files are located.
This option affects compilation of the HPF run-time system, which occurs when
the HPF installation is being built.

{\em EXAMPLE:} if the MPI installation is MPICH and the MPI home
directory is \verb$/local/mpich$, the \verb$MPI_INC_DIR$ field should
be set to \verb$/local/mpich/include$.

\subsubsection*{-mpilib=MPI\_LIB}

\verb$MPI_LIB$ is the file (or list of files) containing the MPI
libraries.  These libraries are passed to the linker by the \verb$hpf$
script.  (The \verb$-l${\em name} form should also work, provided the
linker command knows where to find the named library---see the section
on \verb$LNK_COM$, below.)

{\em EXAMPLE:} if, again, the MPI installation is MPICH, and the MPI
home directory is \verb$/local/mpich$, and MPICH is layered on P4 on an
RS6000 workstation, the \verb$MPI_LIB$ field should probably be set to
\verb$/local/mpich/lib/rs6000/ch_p4/libmpi.a$.

\subsubsection*{-f90=F90}

\verb$F90$ is a symbol identifying the Fortran 90 platform.  This option
affects compilation of the HPF run-time system, which occurs when the HPF
installation is being built.

This flag compromises portability, because only a limited number of
platforms are recognised.  It is needed for the following
reason: the HPF run-time library, through which the generated code
interfaces to MPI, is written in C (and C++).  The C version of the
MPI initialisation procedure requires access to the command line
arguments passed to the executable at run-time---\verb$argc$ and
\verb$argv$.  But the code generated by the HPF translator is
Fortran---the Fortran calls the C.  The C has to pick up the argument
information somehow.  It gets it from the Fortran run-time library.
Presently C code appropriate to a particular Fortran platform is
compiled in conditionally, according to the value of \verb$F90$.

{\em EXAMPLES:} if the Fortran 90 platform is NAG f90, \verb$F90$
should be set to \verb$nag$.  If it is AIX xlf90, \verb$F90$ should be
set to \verb$aix$.  If you have any other Fortran 90 platform, please
contact us
at \verb$info-hpf@par.soton.ac.uk$ or \verb$bug-hpf@par.soton.ac.uk$.

\subsubsection*{-f90com=F90\_COM}

\verb$F90_COM$ is the command to execute the Fortran 90 compiler.  This
command is invoked by the \verb$hpf$ script to compile the code
generated by the translator.

The command will be applied to a single, automatically-generated
Fortran 90 file, with file suffix \verb$.f$.  The code in this file is
in {\em fixed} source format.  The \verb$F90_COM$ command may have to
include options to specify this format.

The compiled code will be linked with C run-time library functions,
written on the assumption that Fortran subroutine names are presented
to the linker after conversion to lower case, with an underscore
character appended.
The \verb$F90_COM$ command may have to include options to specify that it
treats procedure names this way.

{\em EXAMPLES:} if the Fortran platform is NAG f90, a likely value for
\verb$F90_COM$ is \verb$"f90 -mismatch -w"$.  The first option disables
some over-zealous checking of procedure interfaces, which can prevent
the generated code from compiling; the second option just switches off
some associated warning messages.  If it is AIX xlf90, a likely value
for \verb$F90_COM$ is \verb$"xlf90 -qfixed -qextname"$.  The first
options specifies that the source format is fixed; the second specifies
the treatment of procedure names described above.

\subsubsection*{-f90lib=F90\_LIB}

\verb$F90_LIB$ is the file (or list of files) containing the Fortran 90
run-time libraries.  These libraries are passed to the linker by the
\verb$hpf$ script.  The \verb$-l${\em name} form will also work,
provided the linker command knows where to find the named library---see
the section on \verb$LNK_COM$, below.

The location of these libraries may be documented in the manual page
for the compiler; otherwise, they can sometimes be discovered by
watching the compiler operate, with a ``verbose'' option specified.

{\em EXAMPLE:} if the Fortran platform is NAG f90, a likely value for
the \verb$MPI_LIB$ is \verb$"/usr/local/lib/f90/libf90.a -lm"$.

\subsubsection*{-c++com=C++\_COM}

\verb$C++_COM$ is the command to execute the C++ compiler.  This option
affects compilation of the HPF run-time system, which occurs when the HPF
installation is being built.

The command will be applied to a single C++ file with file suffix
\verb$.C$.

{\em EXAMPLE:} if the C++ platform is GNU gcc, a likely value for
the \verb$C++_COM$ is \verb$g++$.

\subsubsection*{-c++lib=C++\_LIB}

\verb$C++_LIB$ is the file (or list of files) containing the C++
run-time libraries.  These libraries are passed to the linker by the
\verb$hpf$ script.

The comments about the Fortran library are applicable, but note that if
the C++ compiler is also used as the linker (a likely choice) this
option can be omitted, because then the ``linker'' already knows about
the C++ libraries.

\subsubsection*{-lnkcom=LNK\_COM}

\verb$LNK_COM$ is the command to execute the linker.  This command is
invoked by the \verb$hpf$ script.

The linker must link together compiled Fortran 90 and C++ programs,
their run-time libraries, and the MPI library.  Because C++ may make
special demands on its linker, we have found that the easiest thing is
to use the C++ compiler itself as the linker.

{\em EXAMPLE:} if the C++ platform is GNU gcc, a likely value for the
\verb$LNK_COM$ is \verb$g++$.  On the IBM SP2 we have used the parallel C++
compiler \verb$mpCC$---it was then necessary to specify an import list
for linking with AIX Fortran: the value for \verb$LNK_COM$ was
\verb$"mpCC -bI:/usr/lpp/xlf/lib/lowsys.exp"$

\end{document}


