This directory tree contains the Fortran to C wrappers for all MPI routines.

(still to do: configure/make details)

This directory contains code to implement the Fortran interface to the MPI
routines.  For reasons discussed below, a full implementation requires
cooperation with the C implementation (whose MPI_Init must call certain
routines defined by this library).

This subsystem builds the following files (the meaning of {name} is described
below): 

   mpif.h                 - The include file to be used by Fortran programs
   libf{name}mpich.a      - Contains the Fortran wrappers
   libf{name}mpichsup.a   - Contains the routines to initialize the 
                            Fortran interface
   mpif77{name}           - Script that can be used to compile 
                            Fortran MPI programs
   mpif77{name}.conf      - Information that can be used by any (compatible)
                            mpif77 to compile Fortran MPI programs.  See below.
   mpi_fortdefs.h         - Contains the typedef for the type MPI_Fint 
                            (needed to build an MPI implementation)

This subsystem is designed to allow multiple Fortran compilers to use the same
MPICH C library installation, as long as they have the same data lengths
(e.g., the sizeof INTEGER is the same) and they use the calling conventions.

The value of {name} is either null or (typically) "-<compilername>".  For 
example, if there are two Fortran compilers, f77 and g77, then {name} might be
"-f77" and "-g77".  

The script "mpif77{name}" is a special case.  Through a command line option,
it can load the mpif77{name}.conf file, allowing any mpif77 script to handle
all compilers.  In an installation, a "default" Fortran compiler should be
chosen, and the mpif77{name} corresponding to that version should be installed
in $bindir as mpif77 (with no name).

These files are built in their source directories.  The install target puts
them into the following directories (shown with the default values):

       file                   directory
   ===================    ===================
   mpif.h                 $includedir/{name}
   libf{name}mpich.a      $libdir
   libf{name}mpichsup.a   $libdir
   mpif77{name}           $bindir
   mpif77-$subname.conf   $sysconfdir
   mpi_fortdefs.h         $includedir

The value of 'subname' is set with the configure option --with-subname=name
The names of the libraries can be changed as well, as can the installation
directories.

In a typical MPICH installation, subname is empty, and the Fortran libraries
are placed into the same directories as the other MPICH files.  



Grubby details:
===============

Organization:

In order to ensure that the MPI profiling interface is correctly supported,
each routine is in a separate file (use strip to generate smaller object files
if that is desired).

A major challenge is supporting multiple Fortran compilers, particularly
multiple Fortran to external name mappings (e.g., names all lower case, with
zero, one, or two underscores).  As a result, all name mappings are controlled
by a configure option, and are contained in a single include file,
"mpi_fortnames.h" .  

We also allow the use of weak symbols to provide the MPI versions of the
names.  In this form, both PMPI (the strong symbol) and MPI routines are
defined by the same file, eliminating the need to compile each file twice.
If weak symbols are not supported and both the MPI and PMPI interfaces are
desired, the interface files are recompiled, with the file name changed to
have an underscore prefix (this allows both the MPI and PMPI routines to share
the same object library).  Because weak pragmas may need to be restricted to
the file that defines the strong symbol, the weak pragma blocks remain in the
interface files.

In order to support other MPIs, we use the MPI-2 functions MPI_xx_f2c and
MPI_xx_c2f.  (MPICH provides these already.)  If these are not provided, we
can guess that they are just the identity function (i.e., the C and Fortran
values are identical, typically either small integers or pointers where
Fortran integers can contain an address).

(We use the support for other MPI implementations to work with the MPE
libraries; this makes it easier to support tracing functions for MPI
implementations that don't implement the Fortran interface by calling the C
versions.  However, not everything can be handled easily this way; see the 
comments on initfutil.c below.) 


Directory tree:

                     fortran  
                      /   \   
                 include  src 
                           
All files go into the src directory.  This means that the directory has (for
all of MPI-1 and 2) about 250 files, but it simplifies the creation of
libraries.  Also in src is mpif77, the compilation script for MPI programs
that use Fortran (see below)

All Fortran support (including configure) should move into this directory.



Special Issues for tight integration with the MPI implementation:
=================================================================
The MPI Standard (in MPI-2) requires that MPI_INIT initialize MPI for all
languages.  Thus, the C/C++ version of MPI_INIT must ensure that all of the 
Fortran attributes and datatypes are correctly initialized.  In MPICH, this is
done by having MPI_Init call these routines:

    MPIR_InitFortran
    MPIR_InitFortranDatatypes

MPI_Finalize calls

    MPIR_Free_Fortran_dtes

to free any created MPI Fortran datatypes.  These functions are defined in
src/initfutil.c .  Compiling this file *MUST* be done as part of an MPICH
build (it needs implementation and device dependent data); otherwise, this
file is not compiled. 

Output:
=======
