-*- text -*-

Copyright 1997-2000, University of Notre Dame.
Authors: Jeremy G. Siek, Jeffery M. Squyres, Michael P. McNally, and
         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.

Additional copyrights may follow.

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

                       MPI 1.2 C++ Bindings

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

***IMPORTANT***: Read the "Do you need this package?" section in the
README file before installing this package.


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

        1. ./configure <options>
        2. make
        3. make install
	3. make examples    (optional)

These steps are covered in detail below.


1. ./configure <options>

See the README file for a list of C++ compilers and MPI
implementation issues.  This package should work with most MPI
implementations (except those that already include C++ bindings).  The
main issue as to whether this package will work properly is the C++
compiler.  See the README file.

*** 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++.

* 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 several MPI implementationd 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-sp               Specifies to use the native IBM POE/MPI
                        implementation.
--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) can opti
.  "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/mpi2c++/*.h         $prefix/include/mpi2c++/*.h
        balky/balky             $prefix/bin/balky
        ----------------------- ------------------------------------
             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 examples

This is an optional step that you can invoke after "make install".  It
will use the installed version of the C++ bindings to build several
examples.  There is a set of example programs (including all the code
from Chapter 10 of the MPI-2 standard) under contrib/examples.
Additionally, there is a test suite of the C++ bindings under
contrib/test_suite.  


5. 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.  


6. make clean

This removes all .o and associated files from the MPI 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.


7. 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.
        -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.
        -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
        -ibm2300        Same, IBM POE 2.3.0.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.

* 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.