#! /bin/sh
# This script is generated by configure for the purpose of reporting on
# the port of MPICH to a new architecture
#
# To simplify testing and a few special cases, this script takes a few options
# -author="name"        Use instead of 'whoami'
# -nomake               Do not run make
# -noperf               Do not run performance tests
# -file=name            Output LaTeX file (default is doc/doc1.tex)
#                       Exercise care with the file name.  In general, it
#                       should be doc/xxx.tex .  Using a different directory
#                       could cause problems
# -config=filename      File containing the output of configure
# -sysname=name         Use instead of @ARCH@
#
# Some systems don't have whoami.  Use $LOGNAME instead
#author="`whoami`"
author="$LOGNAME"
MAKE="@MAKE@"
nomake=0
noperf=0
dotest=0
systemname="@ARCH@"
filename="doc/doc1.tex"
filebase="doc/doc1"
fileroot="doc1"
for arg in "$@" ; do
    case $arg in 
	-author=* )
	author="`echo $arg|sed -e 's/-author=//' -e 's/_/ /'`"
	;;

	-file=* )
	filebase=`echo $arg|sed 's/-file=//'`
        filename="$filebase.tex"
	fileroot="`basename $filebase`"
	;;


	-config=* )
	configlog=`echo $arg|sed 's/-config=//'`
	;;

	-sysname=* )
	systemname="`echo $arg|sed 's/-sysname=//'`"
	;;

 	-nomake )
	nomake=1
	;;


 	-noperf )
	noperf=1
	;;

 	-dotest )
	dotest=1
	;;

	-echo)
	set -x
	echoarg="-echo"
	;;

	*)
	if test -n "$arg" ; then
   	    echo "port: Unknown argument ($arg)"
	    exit 1
        fi
	;;
    esac
done
#
############################################################################
# Some initial comments...
# sh is not reliable about processing redirects of stdin within if...else..fi
# For such cases, we place the output text within a routine, defined
# outside of the if..else..fi, and called conditionally.
#
# Also, different shells handle digraphs like \t differently.  On some
# systems (e.g., SGI,AIX), echo "\\\t" in the sh shell will generate the 
# characters \t.  On others (e.g., Sun4), echo "\\\t" generates \\t and
# echo "\t" and "\\t" both generate \t.  Putting the "\" into a variable
# doesn't help either...  Neither does using '...' instead of "...".
############################################################################
############################################################################
/bin/rm -f $filename
############################################################################
# Create the preamble...
############################################################################
cat >> $filename <<.
\documentstyle[latexinfo,epsf]{article}
\c
\c Run latex on this from the mpich directory, not the doc directory
\c
\c
\c readfile reads a file only if it exists.
\c
\newread\availtest
\def\readfile#1{
\openin\availtest #1
\ifeof\availtest
\message{Could not open file #1}\else
\input{#1}
\fi\closein\availtest}

\textheight=9in
\textwidth=6.5in
\oddsidemargin=.2in
\topmargin=-0.5in
\hsize=6.5in

\begin{document}
\bibliographystyle{plain}
\title{Porting the MPICH MPI implementation to the $systemname system}
\author{$author}
\maketitle
\section{Introduction}
This document describes the porting of the Argonne National 
Laboratory/Mississippi State University portable implementation of MPI
to the $systemname system.  The MPI standard is given in
\cite{mpi-forum:final}; an introduction to using MPI may be found in
\cite{usingmpi}. 

The MPICH implementation \cite{gropp-lusk-doss-skjellum:mpich} relies on a
abstract device interface (ADI) for its portability.  There are many possible
implementation of this device; the one used in this effort was @DEVICE@.

\section{Configuration}
This version of MPICH was configured with arguments {\tt @CONFIGURE_ARGS@}.
The configure script determined the various flags and programs to use; the
choices are described below.
.
############################################################################
# C Compiler options
############################################################################
cflags=" with flags {\\tt @CFLAGS@}"
if test -z "@CFLAGS@" -o "@CFLAGS@" = " " ; then
   cflags=""
fi
cat >> $filename <<.
The C compiler used was {\tt @CC@}.
.
if test -n "@CFLAGS@" ; then
     cat >> $filename <<.
     The C compiler required the special C flags

\begin{flushleft}
\tt
@CFLAGS@
\end{flushleft}

.
fi
cat >> $filename <<.
The linker for C programs is {\tt @CLINKER@}.
.
if test "@cross_compiling@" = 1 ; then
    cat >> $filename <<.
These are cross-compilers; some features that require running a program could
not be determined by the configure script.
.
fi
if test -n "@DEVCFLAGS@" ; then
    cat >> $filename <<.

Special flags were required to compile the ADI part of the code.  These 
flags were {\tt @DEVCFLAGS@}.
.
fi
if test -n "@INCLUDE_PATH@" ; then
    cat >> $filename <<.
A special include path of {\tt @INCLUDE_PATH@} was required.
.
fi
if test -n "@OPTFLAGS@" ; then
    cat >> $filename <<.
The flags {\tt @OPTFLAGS@} were used to control code optimization for the
compilers.
.
fi
############################################################################
# Fortran Compiler options
############################################################################
if test "@HAS_FORTRAN@" = 1 ; then
   fflags=" with flags {\\tt @FFLAGS@}"
   if test -z "@FFLAGS@" ; then
      fflags=""
   fi
   cat >> $filename <<.
The Fortran compiler used was {\tt @F77@}$fflags.
The linker for Fortran programs is {\tt @FLINKER@}.
.
fi
############################################################################
# Other flags.  Eventually, these should be folded into the text
############################################################################
if test "@AR@" != "ar clr" ; then
    cat >> $filename <<.
This system required a special version of the object file archive program.
The program and options used were {\tt @AR@}.
.
fi
if test "@RANLIB@" = "true" ; then
    cat >> $filename <<.
This system does not use {\\tt ranlib}.
.
fi
if test "@CPRP@" != "cp" ; then
    cat >> $filename <<.
The {\tt cp} program on this system does not support the {\tt -r} or {\tt -p}
flags.  The program {\tt @CPRP@} is used instead.
.
fi
############################################################################
# User interface (compiler, linker, etc)
############################################################################
cat >> $filename <<.
\subsection{Special user flags and options}
On some systems, the user must set special options either when compiling or
when linking.  This section describes which special features must be used
when making MPI programs.
.
if test -n "@USER_CFLAGS@" ; then
    cat >> $filename <<.
Users compiling with C must use the flags {\tt @USER_CFLAGS@}.
.
fi
if test -n "@USER_INCLUDE_PATH@" ; then
    cat >> $filename <<.
Users compiling with C must add the include path {\tt @USER_INCLUDE_PATH@}.
.
fi
cat >> $filename <<.
C programs are linked by using the arguments
\begin{verbatim}
@LIB_PATH@ @LIB_LIST@
\end{verbatim}
with the C linker {\tt @CLINKER@}.
.
if test "@HAS_FORTRAN@" = 1 ; then
    cat >> $filename <<.
Fortran programs are linked by using the arguments 
\begin{verbatim}
@FLIB_PATH@ @LIB_LIST@
\end{verbatim} 
with the Fortran linker {\tt @FLINKER@}.   
.
fi
if test -n "$configlog" ; then
    cat >> $filename <<.
The output of configure (only the exceptional lines are shown) was 
\begin{example}
.
    egrep -v '^[Cc]hecking ' $configlog | egrep -v '^[Cc]reating' >> $filename
    cat >> $filename <<.
\end{example}
.
fi
############################################################################
# Device - specific information
############################################################################
cat >> $filename <<.
\subsection{ADI Device}
MPICH uses a portable, flexible, and powerful {\em abstract device interface}
or ADI to 
perform the actual transmission of messages between processes.  Currently,
there is one base version of this device in the directory 
{\tt mpid/chameleon}; versions
customized to specific message-passing systems are derived from these with
special text-transformation programs.  There are a number of configure options
that apply to all of the current versions.
.

if test "@NODEVDEBUG@" = 1 ; then
    cat >> $filename <<.

This version of the ADI was compiled without the ability to generate debugging
output when the command-line option {\tt -mpichdebug} is used.
.
fi

if test "@USERNDV@" = 1 ; then
    cat >> $filename <<.

This version of the ADI was compiled to use a rendevous protocol for long
messages.  This protocol provides more reliable support for systems with
buffer limitations, and better performance when the underlying system 
software uses an eager protocol.
.
fi

if test "@PREPOST@" = 1 ; then
    cat >> $filename <<.

This version of the ADI pre-posts the receive used for control packets.
This can lead to better performance in some situations, particularly those
where most messages use the short message protocol.  This should only be
used when the underlying message-passing system provides non-blocking 
receives.
.
fi

if test "@PREALLOC@" = 1 ; then
    cat >> $filename <<.

This version of the ADI pre-allocates the storage for control packets.  This
is helpful primarily when the ch_p4 device is used and most messages are 
sent with the short message protocol.
.
fi

if test "@VARPKT@" = 1 ; then
    cat >> $filename <<.

This version of the ADI allows the user to change the cross-over point 
between the short and long message protocol with the {\tt -mpipktsize nn}
command-line option.
.
fi

if test "@COMPRESSEDPKT@" = 1 ; then
    cat >> $filename <<.

This version of the ADI uses a compressed format for the data in the envelope
part of the control packet.  This is appropriate for systems with slow
networks.
.
fi

if test "@LIMITEDBUFFERS@" = 1 ; then
    cat >> $filename <<.

This version of the ADI uses special code to compensate for limited buffer
space in the underlying message-passing system.
.
fi

if test "@TINYBUFFERS@" = 1 ; then
    cat >> $filename <<.

This version of the ADI uses special code to compensate for very small buffer
space in the underlying message-passing system.
.
fi

if test -n "@PKTSIZE@" ; then
    cat >> $filename <<.

This version of the ADI has set the cross-over point from short to long
message protocols at $PKTSIZE.
.
fi

if test -n "@MEMDEBUG@" ; then
    cat >> $filename <<.

This version of the ADI has been built with special code to help in memory 
debugging.
.

fi
############################################################################
# Information on specific devices
############################################################################
if test "@DEVICE@" = "ch_p4" ; then 
    cat >> $filename <<.
This version of the ADI uses p4 \cite{p4-paper}.
To p4, the name of the architecture of this system is {\tt @P4_ARCH@}.
.
    if test -n "@P4_MDEPCFLAGS@" ; then
	cat >>$filename <<.
This device uses the special compile flags CFLAGS = {\\tt @P4_MDEPCFLAGS@}.
.
    fi
fi
#
#
chameleon_text1() {
cat >> $filename <<.

This version of the ADI uses the Chameleon device.  This device supports
many types of parallel environments.  Documentation on Chameleon is available
in \cite{chameleon-user-ref}.

Chameleon is available in debugging (BOPT=g), production (BOPT=O) and 
profiling versions (BOPT=Opg).  The version used here is BOPT=@BOPT@.
The directory containing Chameleon is @TOOLS_DIR@.  

Chameleon uses makefile includes to provide a simple way to build the 
Chameleon libraries for multiple architectures.  The Chameleon ADI uses 
{\tt @DEVICE_MAKE_INCLUDE@} as the source of the makefile includes.
.
}

unknown_dev_text() {
cat >> $filename <<.

This version of the ADI uses $nametype calls.
.
}
#

if test "@DEVICE@" = "chameleon" ; then
    chameleon_text1;
    if test -n "@COMM@" ; then 
        echo "The COMM=@COMM@ transport layer was used." >> $filename
        if test "@COMM@" = "p4" ; then
	    cat >>$filename <<.
	    The directory for p4 used was {\\tt @P4_DIR@}.
.
	fi
    else
        echo "The native MPP transport layer was used." >> $filename
    fi
else
    nametype=`echo @DEVICE@ | sed 's/ch_//g'`
    unknown_dev_text;
fi
if test -n "@GETNAME_DEFS@" ; then
    cat >> $filename <<.
This version of the ADI uses standard Unix system calls to get the name of the
processor.  The precise calls are selected in the ADI with the C definitions 
{\tt @GETNAME_DEFS@}.
.
fi

############################################################################
# MPE Libraries
############################################################################
if test -n "@MPE_DIR@" ; then
    cat >> $filename <<.
\section{MPE Libraries}
The MPICH implementation comes with several MPI libraries that provide
profiling, sequential sections, and optionally graphics.  This collection of
routines is called the MPE library.  Programs that use MPE routines must be
linked with {\tt @MPE_LIBS@} in addition to the MPI libraries.
.
    #
    if test -n "@MPE_GRAPHICS@" ; then
        if test -n "@X_INC@" -o -n "@X_LIB@" ; then
	    echo " " >> $filename
	    echo "The MPE libraries" >> $filename
	    if test -n "@X_INC@" ; then 
		cat >> $filename <<.
used {\tt @X_INC@} for the X11 includes
.
	    fi
            if test -n "@X_LIB@" ; then
		cat >> $filename <<.
and {\tt @X_LIB@} for the X11 libraries.
.
	    else 
		echo "."
	    fi
	fi        
    else
        cat >> $filename <<.

The MPE libraries did not include the X11 graphics routines.
.
    fi
fi
############################################################################
# All of the other items just to remind us...
############################################################################
cat >> $filename <<.
\subsection{Other configure variables}

There are a large number of configure variables.  This table sumarizes the
variables not described elsewhere and their values.

\begin{description}
\item[MPIR_HOME]\file{@MPIR_HOME@}\\\\
Location of MPICH
\item[AUTOMOUNTFIX]\code{@AUTOMOUNTFIX@}\\\\
Fix for automounters
\item[SYNCLOC]\file{@SYNCLOC@}\\\\
Location of \file{sync} program
\item[RSH_COMMAND]\file{@RSH_COMMAND@}\\\\
Remote shell program (if needed)
.
#
if test -n "@PREFIX@" ; then
    cat >> $filename <<.
\item[PREFIX]@PREFIX@\\\\
Directory to install MPICH into
.
fi
#
if test -n "@CPP_DIR@" ; then
    cat >> $filename <<.
\item[CPP_DIR]
@CPP_DIR@\\\\
Location of C++
.
fi
if test -n "@CPP_COMPILER@" ; then
    cat >> $filename <<.
\item[CPP_COMPILER]
@CPP_COMPILER@\\\\
C++ compiler
.
fi
echo "\\end{description}" >> $filename
############################################################################
# Do the build and comment on it...
############################################################################
# Next, we run the make and time used to do the port
# Note that the readfile needs to strip the doc/ from the directory (it 
# should read locally)
if test $nomake = 0 ; then
    @MPIR_HOME@/doc/portbuild -file=$filebase
    if test $? != 0 ; then 
	# The make failed; don't generate any data!
	dotest=0
	noperf=1
    fi
fi
cat >> $filename <<.
\readfile{${fileroot}make.tex}
.
#
# Special case for p4: see if we can build the server
if test "@DEVICE@" = "ch_p4" ; then
    $MAKE serv_p4  > serv_p4.log 2>&1
    if [ $? != 0 ] ; then 
	cat >> $filename <<EOF
\subsection{P4 startup server}
The make of the P4 server, used to speed job startup, failed.  
EOF
    if [ -s serv_p4.log ] ; then 
        cat >> $filename <<EOF
The make output
was
\begin{verbatim}
EOF
	cat serv_p4.log >> $filename
	cat >> $filename <<EOF
\end{verbatim}
EOF
    else
	cat >> $filename <<EOF
There was no output from make, but the make returned a non-zero status.

EOF
    fi
	cat >> $filename <<EOF
This may not be a serious problem; some systems do not support the P4 server.
On these systems, MPICH will use the remote shell command \code{@RSH_COMMAND@}
to start remote jobs.
EOF
    else
	cat >> $filename <<EOF
\subsection{P4 startup server}
The make of the P4 server, used to speed job startup, succeeded.  The
script, \file{chp4_servs}, may be used to start the servers.  Using the server
is optional, but can significantly speed job startup.  See the
installation and users guides for more information.
EOF
    fi
fi
# Special case for p4: if we're going to run the tests or the performance
# tests, try tstmachines
if test $noperf = 0 -o $dotest = 1 ; then
    if test "@DEVICE@" = "ch_p4" ; then
	if test -x @MPIR_HOME@/lib/@ARCH@/ch_p4/tstmachines ; then 
	    /bin/rm -f .tmp
	    if @MPIR_HOME@/lib/@ARCH@/ch_p4/tstmachines @ARCH@ > .tmp 2>&1 ; then
		true
	    else 
		cat >>$filename <<EOF
\section{Test of Network Setup}
The script \code{lib/@ARCH@/ch_p4/tstmachines} has detected some problems
with your list of machines.  The output of this program was
\begin{verbatim}
EOF
		cat .tmp >>$filename
		cat >>$filename <<EOF
\end{verbatim}

Because this will cause problems with the execution of the performance tests
and the correctness tests, they will not be performed.
EOF
		dotest=0
		noperf=1
	    fi
	fi
    fi
fi
#
############################################################################
# Performance of the system
############################################################################
#
############################################################################
# Run the performance tests
############################################################################
if test $noperf = 0 ; then
    @MPIR_HOME@/doc/portperf -file=$filebase $echoarg
else
    /bin/rm -f ${filebase}perf.tex
fi
# In case we add the data later.
cat >> $filename <<.
\readfile{${fileroot}perf.tex}
.
############################################################################
# Run the correctness
############################################################################
if test $dotest = 1 ; then
    @MPIR_HOME@/doc/porttest -file=$filebase $echoarg
else
    # Make sure that there is no old file left over
    /bin/rm -f ${filebase}test.tex
fi
cat >> $filename <<.
\readfile{${fileroot}test.tex}
.
# 
############################################################################
# Finish the document off
############################################################################
cat >> $filename <<.

\begin{tex}
\bibliography{doc}
\end{tex}
\end{document}
.
