Copyright (c) 2001-2003 The Trustees of Indiana University.  
                        All rights reserved.
Copyright (c) 1998-2001 University of Notre Dame. 
                        All rights reserved.
Copyright (c) 1994-1998 The Ohio State University.  
                        All rights reserved.

This file is part of the XMPI software package.  For license
information, see the LICENSE file in the top level directory of the
XMPI source distribution.

Installation instructions for XMPI 2.2.3b8
=========================================

XMPI 2.2.3b8 will only work with LAM/MPI 6.5.9 and 7.0.x.  It may not
work with any version of LAM/MPI prior to LAM/MPI 6.5.9.

NOTE THAT THIS IS A BETA RELEASE OF XMPI.  Some things are bound to be
broken.

This file contains the installation instructions for XMPI 2.2.3b8
Here's a brief table of contents:

     * For the impatient
     * Unpacking the distribution
     * Configuration
     * Building XMPI
     * Using XMPI
       - Typical usage
     * Troubleshooting
       - Problems with building XMPI
       - Sending mail to the XMPI mailing list


NOTE: In LAM/MPI 6.5, the build process was changed significantly.
Many of the header files that XMPI relies on are now not installed by
default.  You must add the option '--with-trillium' when running
LAM/MPI's configure script in order to successfully build XMPI for
LAM/MPI.


For the impatient
-----------------

If you don't want to read the rest of the instructions, the following
should do the trick for most situations:

     % gunzip -c xmpi-2.2.3b8.tar.gz | tar xf -
     % cd xmpi-2.2.3b8.tar.gz
     % ./configure --prefix=/path/to/install/in
     [...lots of output...]
     % make
     [...lots of output...]
     % make install

If you do not specify a prefix, XMPI install under /usr/local/.

Now go read the Announce file; it contains all the information about
the new features of this release of XMPI.


Unpacking the distribution
--------------------------

The XMPI distribution is available from the main LAM/MPI web site:

     http://www.lam-mpi.org/

Uncompress the archive and extract the sources.

     % gunzip -c xmpi-2.2.3b8.tar.gz | tar xf -

or 

     % uncompress -c xmpi-2.2.3b8.tar.Z | tar xf -


Configuration
-------------

LAM/MPI uses a GNU configure script to perform site and architecture
specific configuration.

Change directory to the top level LAM directory (xmpi-2.2.3b8-LAMLIBRV) and run
the configure script.

     % ./configure {options}

or 

     % sh ./configure {options}

NOTE: Unlike most configure scripts, XMPI's configure does not follow
the CC environmental variable.  If you wish to specify a compiler, you
MUST use --with-cc.

By default the configure script sets the XMPI install directory to
/usr/local/.  This can be overridden with the --prefix option (see
below).

The configure script will create several configuration files:
config.log and Makefile. You may wish to inspect these files for a
sanity check, but ./configure usually guesses correctly.

The configure script recognizes the following options (shown here in
alphabetical order):

--enable-echo

     Will echo all of the commands that configure executes.  This is
usually for debugging purposes only, and is not recommended for end
users.

--prefix=PREFIX

     Sets the installation location LAMHOME for the LAM binaries,
libs, etc., to directory PREFIX.  PREFIX must be specified as an
absolute directory name.

--with-cc=CC

     Use the C compiler CC.

--with-cflags=CFLAGS

     Use the C compiler flags CFLAGS.  The flags passed to the C
compiler can also be selected by setting the "CFLAGS" environment
variable before running configure.

--with-cxx=CXX

     Use the C++ compiler CXX.

--with-cflags=CFLAGS

     Use the C compiler flags CFLAGS.  The flags passed to the C
compiler can also be selected by setting the "CFLAGS" environment
variable before running configure.

--with-ldflags=LDFLAGS

     Use the LD linker flags LDFLAGS.  If this flag is not set on the
./configure command line, the value for CFLAGS is used.
 
`--help'
     Print a summary of the options to `configure', and exit.
 
`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
suppress all normal output, redirect it to `/dev/null' (any error
messages will still be shown).
 
`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
`configure' can determine that directory automatically.
 
`--version'
     Print the version of Autoconf used to generate the `configure'
script, and exit.
 
`configure' also accepts some other, not widely useful, options.


Building XMPI
------------

Once the configuration step has completed, build XMPI by doing:

     % make

in the top level XMPI directory. This will build the XMPI binaries and
libraries.  You should test the binary to make sure that the build
completed normally.  To install the binaries, libraries, and man
pages, enter:

     % make install

Note that you must have write permission in the install directory for
this command to work.


Using XMPI
---------

--- Typical usage

Generally, XMPI is used to launch MPI programs and then review the
communication history at the completion of the program.  In general,
there will be little difference in the process used to run an MPI
program using XMPI in place of a command-line interface.

On some implimentations of MPI (most notably LAM), you may have to
launch a daemon on each of the nodes before running an MPI process.
XMPI does not launch the daemon.  You MUST launch the daemon on the
command line before running the MPI program in XMPI.


Troubleshooting
---------------

--- Problems with building XMPI

It is highly recommended that you execute the following steps *in
order*.  Many people have similar problems with configuration and
initial setup of XMPI, and most common problems have already been
answered in one way or another.

1. Check the mailing list archives.  Use the "search" features to
check old posts and see if others have asked the same question and had
it answered:

	http://www.lam-mpi.org/MailArchives/xmpi/

2. If you do not find a solution to your problem in the above
resources, and your problem specifically has to do with *building*
XMPI, send the following information to the XMPI mailing list (see the
next section below about sending mail to the XMPI mailing list):

a. The output of "uname -a"
c. The config.log file (in the top level XMPI build directory)
d. The output from when you ran "./configure"
e. The output from when you ran "make"

To capture the output of the configure and make steps you can use the
script command or the following technique if using a csh style shell:

     % ./configure {options} |& tee config.LOG
     % make install          |& tee make.LOG

or if using a Bourne style shell:

     % ./configure {options} 2>&1 | tee config.LOG
     % make install 2>&1          | tee make.LOG


--- Sending mail to the XMPI mailing list

In order to post to the XMPI mailing list, you must subscribe to the
list.  This can be done using the MailMan web interface at:

	http://www.lam-mpi.org/mailman/listinfo.cgi/xmpi

Messages can be posted to the list by sending an e-mail to
xmpi@lam-mpi.org