-*- text -*-

Copyright 1997-1999, University of Notre Dame.
Authors: Jeremy G. Siek, Michael P. McNally, Jeffery M. Squyres,
         Andrew Lumsdaine

This file is part of the Notre Dame C++ bindings for MPI

You should have received a copy of the License Agreement for the
Notre Dame C++ bindings for MPI along with the software;  see the
file LICENSE.  If not, contact Office of Research, University of Notre
Dame, Notre Dame, IN  46556.

Permission to modify the code and to distribute modified code is
granted, provided the text of this NOTICE is retained, a notice that
the code was modified is included with the above COPYRIGHT NOTICE and
with the COPYRIGHT NOTICE in the LICENSE file, and that the LICENSE
file is distributed with the modified code.

LICENSOR MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.
By way of example, but not limitation, Licensor MAKES NO
REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED SOFTWARE COMPONENTS
OR DOCUMENTATION WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS
OR OTHER RIGHTS.

-----------------------------------------------------------------------

                       MPI 1.2 C++ Bindings

I. INSTALLATION INSTRUCTIONS
----------------------------

There are three basic steps to the installation of the MPI-1.2 C++
bindings:

        1. ./configure <options>
        2. make
        3. make install

These steps are covered in detail below.


1. ./configure <options>

The MPI-1.2 C++ bindings have been compiled and tested on the
combinations listed in Table 1.

Hardware        Operating System        Compilers       MPI Implementations
=============== ======================= =============== ======================
Sun SPARC       Solaris 2.5.1           Workshop CC     LAM 6.2b-pl5,  
                Solaris 2.6             v4.2,           6.3-b2, 6.4-a2,
                                        g++ v2.7.2,	MPICH 1.1.2
                                        g++ v2.8.1,
--------------- ----------------------- --------------- ----------------------
SGI             IRIX 6.4                CC v7.2.1.1     Native v3.1.1.0,
                                                        LAM 6.2b-pl5,
							6.3-b4, 6.4-a2,
                                                        MPICH 1.1.2
--------------- ----------------------- --------------- ----------------------
IBM RS/6000     AIX 4.1.2, AIX 4.1.4    xlC v3.1.4.7    Native POE v2.1.0.18,
and SP                                  g++ v2.8.1      LAM 6.2b-pl4,
							6.3-b4, 6.4-a2,
                                                        MPICH 1.1.2
--------------- ----------------------- --------------- ----------------------
HP              HP-UX 11.00             aCC X.03.11.10  Native v1.5,
                                                        LAM 6.2b-pl5,
							6.3-b4, 6.4-a2,
                                                        MPICH 1.1.2
--------------- ----------------------- --------------- ----------------------
Intel x86       Linux 2.0.36            g++ v2.8.1      MPICH 1.1.2, LAM 6.2,
							6.3-b4, 6.4-a2
--------------- ----------------------- --------------- ----------------------
        Table 1: Supported hardware/OSs/Compilers/MPI implementations

*** LAM Users: You *must* use version 6.2 or later.  The bindings
depend on using the hcp compiler; it must be in your path.  See the
LAM documentation for details.

*** MPICH Users: Be sure to install all relevant patches for your
architecture / operating system.  It is strongly recomended that you
upgrade to MPICH version 1.1.1 as it contains bug fixes concerning the
mpiCC compiler script.  Compiling this package with versions of MPICH
prior to 1.1.1 may fail (if supplemental libraries are required by
your communications device).

Architecture specific notes on MPICH:
 - MPICH must be compiled in 64 bit mode on IRIX systems.

*** GNU g++ Users: Unfortunately, the GNU compilers do not seem to
always handle exceptions properly.  "-fhandle-exceptions" seems to
work most of the time, but not always.  See below for important
information regarding the test suite and the [mis]handling of
exceptions with g++.

*** SGI IRIX Users: The default behavior is that the C++ bindings will
be built using the n32 version of libmpi.so if it is available (in
/usr/lib32).  If the n32 version is not available, it will be built
using the 64 bit version from /usr/lib64 (if available).  This
behavior can be overriden by forcing compilation in 64 bit mode with a
command line option to the "./configure" script (see below).
Additionally, the test suite makes use of the MPI_CHECK_ARGS
environment variable.  Set this variable to "1" *before* invoking
mpirun on the test suite for proper checking of exception handling
upon MPI errors.  If it is not set, some tests will be skipped.

* HP-UX Users: We have turned off the warning messages for this
compiler because it is slightly broken and reports warnings for things
it should not. It has been reported to HP. The v1.2 cancel seems to
have some problems with it. However, setting the MPI_FLAGS to sa5 in
v1.3.1 and v1.5 passes all the tests we have thrown at it. 

Shortcuts for the systems listed above have been built into the
configure script.  As more hardware/OS/compiler/MPI combinations are
tested, more shortcuts will be added to the script.  See the contact
information in the README file if you wish to provide information for
another hardware/OS/compiler/MPI combination in the C++ bindings
package.

Although the configure script is fairly intelligent in how it attempts
to find your MPI implementation, it still may need a bit of help.
Listed below are the flags that configure accepts.  You should only
need to specify one of the MPI implementation flags (unless you are
using MPICH; see below).  Additionally, the CXX environment variable
may be set to override the default C++ compiler that the package will
use to build itself unless the MPI implementation has a wrapper
compiler script such as hcp for LAM and mpiCC for MPICH.

*** Please note that all of the bindings components are built with
high levels of optimization.  If you are confident that the optimizer
for your compiler is functioning properly, you can disable the
optimization of the compilation of the test suite and example programs
(which can save a *lot* of time in compiling!) with the
"--with-testopt" and "--with-examopt" flags to "./configure".  See the
table of "./configure" options, below.

-------------------------------------------------------------------------
Generic flags:
--prefix=dir            Specifies the top-level directory where the
                        bindings should be installed (i.e. dir/lib,
                        dir/include, and dir/bin).  If no prefix is 
                        specified, /usr/local is used.

Specific MPI implementation switches:
--with-lam=dir          Specifies the top-level directory where LAM 6.x 
                        was installed.  If "hcp" is already in your
                        path, you do not need to specify "dir".
--with-mpich=dir        Specifies the top-level directory where MPICH 
                        (version 1.0.13 or later) was installed.
--with-mpichdev=subdir  Specifies the subdirectory of which
                        architecture/device you wish to use.  If MPICH
                        was compiled for only one architecture/device,
                        this option need not be specified.  If
                        multiple devices exist in the MPICH tree and
                        this option is not specified, configure will
                        prompt for which device to use. If using MPICH
			1.1.2, you may need to include the /lib ending
			in the device directory.
--with-sp               Specifies to use the native IBM POE/MPI
                        implementation.
--with-sgi              Specifies to use the native SGI MPI implementation.
--with-sgi64            Specifies to use the native SGI MPI implementation,
                        forcing it to compile in 64 bit mode.
--with-hp               Specifies to use the native HP MPI implementation.
--with-cray             Specifies to use the native Cray MPI implementation.

Generic MPI implementation switches:
(only use these if you did not use one of the above switches)

--with-mpidir=dir       Specifies a top-level directory where dir/mpi.h
                        and dir/libmpi.a may be found.

or if mpi.h and libmpi.a are in different directories:

--with-mpiinc=dir       Specifies a top-level directory where dir/mpi.h
                        may be found.
--with-mpilib=dir       Specifies a top-level directory where dir/libmpi.a
                        may be found.

Compiler specific switches:
--with-exflags=exflags  Speficies the flags necessary to enable 
                        exceptions on your compiler (may not be
                        necessary).
--with-namespace        Speficially force compilation with the C++
                        "namespace" construct.
--without-namespace     Speficially force compilation without the C++
                        "namespace" construct ("class" is used
                        instead).

Other flags:
--without-opt           Use no optimization flags in compiling any part
                        of this package.  Useful for debugging.
--with-libopt=flags     Use <flags> when compiling libmpi++.a.
--with-testopt=flags    Use <flags> when compiling the test suite.
--with-examopt=flags    Use <flags> when compiling the examples.
--with-profiling        Build the profilable library.  The default
                        (when this option is not used) is to build a
                        non-profilable library.
-------------------------------------------------------------------------
                        Table 2: "./configure" flags

2. make

"make" by itself will compile the C++ bindings library, the test suite
(found in contrib/test_suite), and several example programs (found in
contrib/examples).  "make" can actually take several arguments, most
of which are similar to the GNU coding standards:

"make" by itself actually invokes "make clean lib examples".

        Argument                Function
        ----------------------- ------------------------------------
        lib                     Compiles the C++ bindings library.
        examples                Compiles everything in contrib/.
        install                 Installs the C++ bindings (see below).
        uninstall               Opposite of install; removes the C++ 
                                bindings from their installed locations.
        clean                   Removes .o and associated files.
                                It is safe to do this after you
                                install the bindings (to conserve disk
                                space).
        distclean               Restores the distribution tree to the
                                the same state as it was when it was
                                un-tarred from the distribution tar.
        ----------------------- ------------------------------------
                Table 3: Targets for the default Makefile


3. make install

"make install" installs the following files:

        Source                  Destination
        ----------------------- ------------------------------------
        src/libmpi++.a          $prefix/lib/libmpi++.a
        src/mpi++.h             $prefix/include/mpi++.h
        src/[many_files].h      $prefix/include/mpi2c++-1.0.0/[many_files].h
        balky/balky             $prefix/bin/balky
                                Symbolic link from 
                                  $prefix/include/mpi2c++-1.0.0 to
                                  $prefix/include/mpi2c++
        ----------------------- ------------------------------------
             Table 4: Destination for files in a "make install"

The destination directories are created if they do not already exist.
The MPI-1.2 C++ bindings are now ready to use.


4. make uninstall

This is the opposite of "make install".  All files are removed from
their installed locations (from within $prefix), but the $prefix/lib,
$prefix/include, and $prefix/bin directories are not removed.  

The $prefix/include/mpi2c++-<version> directory *is* removed, and
the $prefix/include/mpi2c++ symbolic link is removed *only* if it still
points to the $prefix/include/mpi2c++-<version> that you are
uninstalling.


5. make clean

This removes all .o and associated files from the MPI-1.2 C++
distribution tree.  This is safe to do after a "make install"; its
purpose is to conserve disk space after the bindings have been fully
installed.


6. make distclean

As per GNU standards, "make distclean" will restore the distribution
tree to the same state that it was when it was unzipped and untarred it
(barring any additional files or changes that the user may have
made).  This is also safe to do after a "make install", but you will
lose your configure information.  If a re-build is necessary, you
will need to run configure again.


II. EXECUTION INSTRUCTIONS
--------------------------

1. Source code

Programs that use the MPI-1.2 C++ classes and functions need only
include <mpi++.h> in their respective source files.


2. Test suite

This package comes with a test suite that tests every method of every
class in the C++ bindings library.  It is highly recommended that you
run this program to ensure that the bindings have installed correctly,
your C++ compiler is functioning properly, and your MPI environment
works according to the MPI 1.1 (or 1.2) standard.  While the test
suite does not perform stress tests on any of the subsystems listed
above, it verifies the basic functionality of the bindings themselves.

The test suite lists each method as it is tested.  There are three
possible outcomes of each test:

        Outcome         Meaning
        --------------- --------------------------------------------
        PASS            The test passed.
        FAIL            The test failed, and the test suite will
                        abort.  A brief error message will describe
                        the error.  The test suite will abort.
        SKIPPED         The test is skipped because of a particular
                        known problem with the underlying MPI 
                        implementation.
        --------------- --------------------------------------------
           Table 5: Outcome of individual tests in the test suite

The test suite executable is located at
contrib/test_suite/mpi2-c++_test.  It is designed to run on an even
number of processors, and can take the following command line
switches:

        Switches        Meaning
        --------------- --------------------------------------------
        -help           Print out a short description of the command
                        line switches.
        -lam61          Skip tests of MPI functions that are faulty
                        in LAM 6.1.
        -lam62          Skip tests of MPI functions that are faulty
                        in LAM 6.2.
        -lam63          Skip tests of MPI functions that are faulty
                        in LAM 6.3.
        -lam64          Skip tests of MPI functions that are faulty
                        in LAM 6.4.
        -mpich110       Skip tests of MPI functions that are faulty
                        in MPICH 1.1.0
        -mpich111       Skip tests of MPI functions that are faulty
                        in MPICH 1.1.1
        -mpich112       Skip tests of MPI functions that are faulty
                        in MPICH 1.1.2
        -ibm21014       Skip tests of MPI functions that are faulty
                        in the IBM POE maintenance version 2.1.0.14
        -ibm21015       Same, IBM POE 2.1.0.15
        -ibm21016       Same, IBM POE 2.1.0.16
        -ibm21017       Same, IBM POE 2.1.0.17
        -ibm21018       Same, IBM POE 2.1.0.18
        -sgi20          Skip tests of MPI functions that are faulty
                        in the SGI MPI release 2.0
        -sgi30          Skip tests of MPI functions that are faulty
                        in the SGI MPI release 3.0
        -hpux0102       Skip tests of MPI functions that are faulty
                        in the HP-UX MPI release 01.02
        -g++            Skip tests of MPI functions that are faulty
                        because the g++ compiler is broken.
        -nothrow        Skip error handler test. This test tries
                        to cause a "soft" error in the underlying MPI
                        which in many cases causes a not-so soft error.
                        Also, the exception handling mechanism for
                        several compilers (see g++ below) does
                        not handle this test properly.
        --------------- --------------------------------------------
             Table 6: Command line switches to the test suite

* SP Users: There are several functions that fail on the SP, most of
which are not commonly used.  For versions before the fixes, the test
suite will always fail unless the -sp flag is used.  Skipped tests
are noted in the right hand column.  Additionally, it seems that
MPI_DIMS_CREATE is rather fragile -- it works for some cases, and
not with others.  By 2.1.0.18, all bugs except MPI_CART_GET appear
to have been fixed.

* SGI Users: MPI_TESTALL, MPI_GRAPH_GET, and MPI_CANCEL do not work
properly in release 2.0 of SGI's MPI.  Most problems have been fixed
in SGI's MPI release 3.0, which is available from the SGI website
(http://www.sgi.com/Products/Evaluation/evaluation.html).  However,
the test suite makes use of the MPI_CHECK_ARGS environment variable.
It must be set to "1" *before* mpirun is used to invoke the
mpi2c++_test program.  If it is not, the test checking for proper
exception handling will be skipped.

* GNU g++ users: The test suite tests the error handling mechanism
of the C++ bindings. Normally, an exception would be thrown, but the
latest version of g++ (2.8.1 at the time of this writing) doesn't
always handle exceptions properly. For these cases the tests are
skipped. Note that most of the time the exception handling mechanism
will not work with g++.

*** Please report any errors or problems with the test suite to
mpi2c++-bugs@mpi.nd.edu.  Please include the version of this package
that you are working with as well as the output of configure, make,
make install, and the test suite.


4. Example code

Several example C++ programs are provided in contrib/examples.  These
examples are C++ versions of popular MPI example programs, as well as
all the example programs in chapter 10 of the MPI-2 standard.  They
are well commented, and intended to demonstrate C++ techniques to MPI
programmers.
