Updates to the README and wrapper compiler man pages for Fortran.

Thanks to Paul Hargrove for spotting these issues.

cmr=v1.7.4:reviewer=rhc:subject=Fortran README+man page updates

This commit was SVN r30414.

README

@@ -305,6 +305,18 @@ Compiler Notes
   *** environment variables are IGNORED.
   ********************************************************************
   ********************************************************************
+  
+  As a direct result, it is STRONGLY recommended that you specify a
+  Fortran compiler that uses file suffixes to determine Fortran code
+  layout (e.g., free form vs. fixed).  For example, with some versions
+  of the IBM XLF compiler, it is preferable to use FC=xlf instead of
+  FC=xlf90, because xlf will automatically determine the difference
+  between free form and fixed Fortran source code.
+
+  However, many Fortran compiler allow specifying additional
+  command-line arguments to indicate which Fortran dialect to use.
+  For example, if FC=xlf90, you may need to use "mpifort --qfixed ..."
+  to compile fixed format Fortran source files.
 
   You can use either ompi_info or oshmem_info to see with which Fortran 
   compiler Open MPI was configured and compiled. 
@@ -346,12 +358,13 @@ Compiler Notes
 
   - The mpi_f08 module is new and has been tested with the Intel
     Fortran compiler.  Other modern Fortran compilers may also work
-    (but are, as yet, currently untested).  It is expected that this
+    (but are, as yet, only lightly tested).  It is expected that this
     support will mature over time.
 
-    As of v4.9, the GNU Fortran compiler (gfortran) is *not* supported
+    As of this release, the GNU Fortran compiler (gfortran) is *not*
-    with the mpi_f08 module (gfortran lacks some necessary modern
+    supported with the mpi_f08 module.  It is likely that a future
-    Fortran features, sorry).
+    release of Open MPI will provide an mpi_f08 module that will be
+    compatible with gfortran >= v4.9.
 
   - All Fortran compilers support the mpif.h/shmem.fh-based bindings.
 
@@ -368,17 +381,10 @@ Compiler Notes
 
     Specifically, all MPI subroutines with no "choice" buffers are
     prototyped and will receive strong parameter type checking at
-    run-time (e.g., MPI_INIT, MPI_COMM_RANK, etc.).
+    run-time (e.g., MPI_INIT, MPI_COMM_RANK, etc.).  Per guidance from
-
+    the MPI-3 specification, all MPI subroutines with "choice" buffers
-    MPI subroutines with one choice buffer (e.g., MPI_SEND) are
+    are specifically *not* included in the "mpi" module, and their
-    prototyped for all intrinsic Fortran types for scalars and ranks 1
+    parameters will not be checked at compile time.
-    through 4 (the --with-gfortran-max-array-dim configure switch can
-    be used to increase the max array rank supported to up to 7).
-
-    MPI subroutines with two choice buffers (e.g., MPI_GATHER) are
-    *not* prototyped.  These subroutines can still be called in MPI
-    applications; they just will not receive strong parameter type
-    checking.
 
 
 General Run-Time Support Notes

opal/tools/wrappers/generic_wrapper.1in

@@ -97,15 +97,46 @@ ORTE
 .TP
 OMPI
 \fImpicc\fR, \fImpic++\fR, \fImpicxx\fR, \fImpiCC\fR (only on systems with
-case-senstive file systems), \fImpif77\fR, and \fImpif90\fR.  Note
+case-senstive file systems), and \fImpifort\fR (and its legacy/deprecated
+names \fImpif77\fR and \fImpif90\fR).  Note
 that \fImpic++\fR, \fImpicxx\fR, and \fImpiCC\fR all invoke the same
 underlying C++ compiler with the same options.  All are provided as
 compatibility with other MPI implementations.
 .
+.
+.SS Fortran Notes
 .PP
-The Fortran wrapper compilers for MPI (\fImpif77\fR and \fImpif90\fR)
+The Fortran wrapper compiler for MPI (\fImpifort\fR, and its
-will be inoperative and will return an error on use if Fortran 77 /
+legacy/deprecated names \fImpif77\fR and \fImpif90\fR) can compile and
-Fortran 90 support was not built into the MPI layer.
+link MPI applications that use any/all of the MPI Fortran bindings:
+.IR mpif.h ,
+the
+.I mpi
+module, and the
+.I mpi_f08
+module (assuming Open MPI was installed with support for each of these
+Fortran bindings).  Specifically: it is no longer necessary to use
+different wrapper compilers for applications that use
+.I mpif.h
+vs. applications that use the
+.I mpi
+module -- just use
+.I mpifort
+for all Fortran MPI applications.
+.
+.PP
+Note, however, that the Fortran compiler may require additional
+command-line options to enforce a specific Fortran dialect.  For
+example, in some versions of the IBM XLF compiler, if xlf90 is the
+underlying Fortran compiler,
+.IR -qfixed
+may be necessary to compile fixed-format Fortran source files.
+.
+.PP 
+Finally, note that
+.I mpifort
+will be inoperative and will return an error on use if Fortran support
+was not built into the MP Ilayer.
 .
 .
 .SS Overview
@@ -226,18 +257,9 @@ C++ compiler flags
 .
 .
 .TP
-F77
-Fortran 77 compiler
-.
-.TP
-FFLAGS
-Fortran 77 compiler flags
-.
-.
-.TP
 FC
-Fortran 90 compiler
+Fortran compiler
 .
 .TP
 FCFLAGS
-Fortran 90 compiler flags
+Fortran compiler flags

opal/tools/wrappers/opal_wrapper.1in

@@ -14,17 +14,23 @@ invoked as the back-end by the Open MPI wrapper commands such as:
 .BR mpicc ,
 .BR mpiCC ,
 .BR mpic++ ,
-.BR mpif77 ,
 and
-.BR mpif90 .
+.BR mpifort 
+(and its legacy/deprecated names
+.BR mpif77
+and
+.BR mpif90 ).
 .PP
 Some Open MPI installations may have additional wrapper commands,
 and/or have renamed the wrapper compilers listed above to avoid
 executable name conflicts with other MPI implementations.  Hence, you
 may also have wrapper compilers installed including the following
 names:
-.BR mpif90.openmpi ,
+.BR mpifort.openmpi 
-.BR mpif77.openmpi ,
+(and the legacy/deprecated names
+.BR mpif90.openmpi 
+and
+.BR mpif77.openmpi ),
 .BR mpicxx.openmpi ,
 .BR mpiCC.openmpi ,
 .BR mpicc.openmpi ,
@@ -45,10 +51,8 @@ installation:
 .BR mpicc (1),
 .BR mpiCC (1),
 .BR mpic++ (1),
-.BR mpif77 (1),
+.BR mpifort (1),
-.BR mpif90 (1),
+.BR mpifort.openmpi (1),
-.BR mpif90.openmpi (1),
-.BR mpif77.openmpi (1),
 .BR mpicxx.openmpi (1),
 .BR mpiCC.openmpi (1),
 .BR mpicc.openmpi (1),