Copyright 1998-1999, University of Notre Dame.
Authors: Brian W. Barrett, Arun F. Rodrigues, Jeffrey M. Squyres,
	 and Andrew Lumsdaine

This file is part of XMPI

You should have received a copy of the License Agreement for XMPI 
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.


Installation instructions for XMPI 2.2
=========================================

XMPI 2.2 will only work with LAM 6.3.  It will not work with any
version of LAM prior to LAM 6.3.

This file contains the installation instructions for XMPI 2.2
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


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-6.3.tar.gz | tar xf -
     % cd xmpi-2.2-6.3.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 web site:

     http://www.mpi.nd.edu/lam/.

Uncompress the archive and extract the sources.

     % gunzip -c xmpi-2.2-6.3.tar.gz | tar xf -

or 

     % uncompress -c xmpi-2.2-6.3.tar.Z | tar xf -


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

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

Change directory to the top level LAM directory (xmpi-2.2-6.3) 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.mk, XMPI, 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.  The C compiler can also be selected by
setting the "CC" environment variable before running configure.  This
compiler will be used both to compile LAM, and as the default compiler
for the hcc(1) and mpicc(1) wrapper compilers.

--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.  These flags are used to compile
LAM, ROMIO, and some example programs that come with LAM.  If CFLAGS
are not specified, ./configure will pick optimization flags to use.

     These flags are *not* used as default flags in any of the wrapper
compilers.

--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.  These flags
are used to link LAM executables and all example programs that come
with LAM.  If LDFLAGS (and CFLAGS) are not specified, ./configure will
pick optimization flags to use.

     These flags are *not* used as default flags in any of the wrapper
compilers.

'--with-shared'
    builds the LAM libxmpi library as a shared library (libxmpi.so or
    libxmpi.sl), not the default static library (libxmpi.a)
 
`--with-lam'
   Build XMPI with the LAM-libxmpi version of libxmpi.  This will
   allow you to use XMPI with the LAM implementation of MPI.
 
`--with-sgi'
    Build with the default SGI libxmpi.
 
`--with-vendor-libxmpi=DIR'
    Build with vendor supplied libxmpi in DIR
 
`--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.

Example: 

 % ./configure --with-sgi --with-cc=/bin/cc --with-cflags=-O4 -with-fc=no

Compile for the SGI MPI using the C compiler /bin/cc with options -O4.

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.mpi.nd.edu/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"
b. The config.mk file (in the top level LAM build directory)
c. The config.log file (also in the top level LAM 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

Due to problems with spam, only subscribers are allowed to post to the
list.  To subscribe to the list, send mail to the following address:

	majordomo@mpi.nd.edu

with the line "subscribe xmpi" in the body of the e-mail (the contents
of the Subject line are irrelevant).  You may unsubscribe at any time
by sending an e-mail with "unsubscribe xmpi" in the body of the
message to the same majordomo address.

After you have subscribed (and received a confirmation e-mail), you
can send mail to the list at the following address:

	xmpi@mpi.nd.edu

NOTE: People tend to only reply to the list; if you subscribe, post,
and then unsubscribe from the list, you will likely miss replies

Also please be aware that xmpi@mpi.nd.edu is a list that goes to a few
hundred people around the world -- it is not uncommon to move a
high-volume exchange off the list, and only post the final resolution
of the problem/bug fix to the list.