-*- text -*-

$Id: README.cvs,v 1.3 2003/02/06 14:26:39 jsquyres Exp $

Welcome to the CVS tree for LAM/MPI.

The main web page for LAM/MPI is http://www.lam-mpi.org/.  There is a
wealth of information available online; please be sure to visit there
for additional information.

Before trying to compile this tree, there are several things that you
should know.  Please visit http://www.lam-mpi.org/cvs/ for more
information.

Organization
------------

The LAM/MPI source code is loosely divided into the following:

- config/ - extra "helper" files
- doc/ - various documents and documentation
- etc/ - extra data files used at run time
- examples/ - example MPI programs
- lamtests/ - source code for the lamtests MPI test suite
- man/ - source code for some non-automatically-generated man pages
- otb/ - source code for various LAM executables, including the lamd
- romio/ - import of the ROMIO package
- share/ - source code for the LAM and MPI libraries
- tools - source code for various LAM/MPI executables

Source code
-----------

If you look at any of the LAM source code, you may have two immediate
questions:

1. Why is the indenting so inconsistent?
2. Why are some functions prototyped in a pre-ANSI format?

The answers to both questions lie in the history of LAM/MPI.  The
original Llamas used 8 space tabs.  We, the current Llamas, use 2
space tabs.  We made an executive decision when we first inherited the
LAM source code to import the LAM source code to CVS as-is without
first running it through a tool such as GNU's indent to reformat it to
2 space tabs.  This was mainly because we did not yet feel comfortable
with the LAM source code and because indent really doesn't understand
function pointer syntax (which LAM uses a lot).

As such, although we are now quite familiar with the LAM source code
and could probably successfully run indent and re-format the code, we
don't for the following reasons:

a) there's little value-added for the time it would take to do this
b) the potential for error is still too high since indent still
   doesn't understand function pointer syntax
c) it would create enormous CVS diffs and make comparisons to
   previous code extremely difficult

c) is perhaps the most important to us.  So we compromised: all new
code and bug fixes use 2 space tabs.  Old code can be re-formatted on
an as-needed basis.

As for why some functions are still left in a pre-ANSI declaration
format, again, there's little reason to update them.  We update them
on an as-needed basis, but we just can't justify spending the time of
making a sweep through the entire tree to ANSI-ize the code.  We do
have an informal policy that any time a .c file is edited, it must be
ANSI-ified.  So this is a slow process, but it will eventually allow
the LAM source code to be compiled by a C++ compiler.  There's no
rush.

But at least you can see that there is method to our madness.  :-)