Add man page for wrapper compilers.

Fixes trac:358.

This commit was SVN r11773.

The following Trac tickets were found above:
  Ticket 358 --> https://svn.open-mpi.org/trac/ompi/ticket/358

ompi/tools/wrappers/Makefile.am

@@ -9,6 +9,7 @@
 #                         University of Stuttgart.  All rights reserved.
 # Copyright (c) 2004-2005 The Regents of the University of California.
 #                         All rights reserved.
+# Copyright (c) 2006      Cisco Systems, Inc.  All rights reserved.
 # $COPYRIGHT$
 # 
 # Additional copyrights may follow
@@ -34,7 +35,11 @@ install-exec-hook:
 	(cd $(DESTDIR)$(bindir); rm -f mpicxx$(EXEEXT); $(LN_S) opal_wrapper mpicxx)
 	(cd $(DESTDIR)$(bindir); rm -f mpif77$(EXEEXT); $(LN_S) opal_wrapper mpif77)
 	(cd $(DESTDIR)$(bindir); rm -f mpif90$(EXEEXT); $(LN_S) opal_wrapper mpif90)
-
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpicc.1; $(LN_S) opalcc.1 mpicc.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpic++.1; $(LN_S) opalcc.1 mpic++.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpiCC.1; $(LN_S) opalcc.1 mpiCC.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpif77.1; $(LN_S) opalcc.1 mpif77.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpif90.1; $(LN_S) opalcc.1 mpif90.1)
 	(cd $(DESTDIR)$(pkgdatadir); rm -f mpiCC-wrapper-data.txt; $(LN_S) mpic++-wrapper-data.txt mpiCC-wrapper-data.txt)
 	(cd $(DESTDIR)$(pkgdatadir); rm -f mpicxx-wrapper-data.txt; $(LN_S) mpic++-wrapper-data.txt mpicxx-wrapper-data.txt)
 else
@@ -46,7 +51,10 @@ install-exec-hook:
 	(cd $(DESTDIR)$(bindir); rm -f mpicxx$(EXEEXT); $(LN_S) opal_wrapper mpicxx)
 	(cd $(DESTDIR)$(bindir); rm -f mpif77$(EXEEXT); $(LN_S) opal_wrapper mpif77)
 	(cd $(DESTDIR)$(bindir); rm -f mpif90$(EXEEXT); $(LN_S) opal_wrapper mpif90)
-
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpicc.1; $(LN_S) opalcc.1 mpicc.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpic++.1; $(LN_S) opalcc.1 mpic++.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpif77.1; $(LN_S) opalcc.1 mpif77.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f mpif90.1; $(LN_S) opalcc.1 mpif90.1)
 	(cd $(DESTDIR)$(pkgdatadir); rm -f mpicxx-wrapper-data.txt; $(LN_S) mpic++-wrapper-data.txt mpicxx-wrapper-data.txt)
 endif
 
@@ -60,6 +68,11 @@ uninstall-local:
 	$(DESTDIR)$(bindir)/mpicxx$(EXEEXT) \
 	$(DESTDIR)$(bindir)/mpif77$(EXEEXT) \
 	$(DESTDIR)$(bindir)/mpif90$(EXEEXT) \
+	$(DESTDIR)$(mandir)/man1/mpicc.1 \
+	$(DESTDIR)$(mandir)/man1/mpic++.1 \
+	$(DESTDIR)$(mandir)/man1/mpiCC.1 \
+	$(DESTDIR)$(mandir)/man1/mpif77.1 \
+	$(DESTDIR)$(mandir)/man1/mpif90.1 \
 	$(DESTDIR)$(pkgdatadir)/mpiCC-wrapper-data.txt \
 	$(DESTDIR)$(pkgdatadir)/mpicxx-wrapper-data.txt
 
@@ -71,6 +84,10 @@ uninstall-local:
 	$(DESTDIR)$(bindir)/mpicxx$(EXEEXT) \
 	$(DESTDIR)$(bindir)/mpif77$(EXEEXT) \
 	$(DESTDIR)$(bindir)/mpif90$(EXEEXT) \
+	$(DESTDIR)$(mandir)/man1/mpicc.1 \
+	$(DESTDIR)$(mandir)/man1/mpic++.1 \
+	$(DESTDIR)$(mandir)/man1/mpif77.1 \
+	$(DESTDIR)$(mandir)/man1/mpif90.1 \
 	$(DESTDIR)$(pkgdatadir)/mpicxx-wrapper-data.txt
 endif
 

opal/tools/wrappers/Makefile.am

@@ -9,6 +9,7 @@
 #                         University of Stuttgart.  All rights reserved.
 # Copyright (c) 2004-2005 The Regents of the University of California.
 #                         All rights reserved.
+# Copyright (c) 2006      Cisco Systems, Inc.  All rights reserved.
 # $COPYRIGHT$
 # 
 # Additional copyrights may follow
@@ -24,6 +25,10 @@ opal_wrapper_DEPENDENCIES = $(top_builddir)/opal/libopal.la
 
 DEFS="-DEXEEXT=\"$(EXEEXT)\""
 
+# Whether or not --enable-binaries was given to configure (useful for
+# multi-lib installations).  If this was not given, we do not build /
+# install anything in this directory.
+
 if OMPI_INSTALL_BINARIES
 
 nodist_pkgdata_DATA = \
@@ -35,9 +40,29 @@ dist_pkgdata_DATA = \
 
 bin_PROGRAMS = opal_wrapper
 
+# List all man pages that will be installed
+
+man_MANS = opalcc.1 opalc++.1
+if CASE_SENSITIVE_FS
+man_MANS += opalCC.1
+endif
+
+# Only include in the distribution tarball the man pages that are not
+# generated (i.e., opalcc.1).
+
+EXTRA_DIST = opalcc.1
+
+# Rules to generate the other man pages
+
+opalc++.1: $(srcdir)/opalcc.1
+	cp -f $(srcdir)/opalcc.1 opalc++.1
+if CASE_SENSITIVE_FS
+opalCC.1: $(srcdir)/opalcc.1
+	cp -f $(srcdir)/opalcc.1 opalCC.1
+endif
+
 if CASE_SENSITIVE_FS
 install-exec-hook:
-	(cd $(DESTDIR)$(bindir); rm -f opalcc$(EXEEXT); $(LN_S) opal_wrapper opalcc)
 	(cd $(DESTDIR)$(bindir); rm -f opalc++$(EXEEXT); $(LN_S) opal_wrapper opalc++)
 	(cd $(DESTDIR)$(bindir); rm -f opalCC$(EXEEXT); $(LN_S) opal_wrapper opalCC)
 

opal/tools/wrappers/opalcc.1

@@ -0,0 +1,212 @@
+.TH opalcc 1 "OPEN MPI TOOLS" "OPEN MPI" "OPEN MPI TOOLS"
+.
+.SH NAME
+This man page describes the wrapper compilers for the Open MPI (OMPI),
+OpenRTE (ORTE), and Open Portable Access Layer (OPAL):
+.
+.PP
+mpicc, mpiCC / mpic++, mpif77, mpif90
+.
+.PP
+ortecc, orteCC / ortec++
+.
+.PP
+opalcc, opalCC / opalc++
+.
+.
+.SH SYNTAX
+mpicc [-showme|-showme:compile|-showme:link] ...
+.
+.PP
+The same syntax works for all the wrapper compilers; \fImpicc\fR is
+shown above as a single example representing all the others.
+.
+.
+.SH OPTIONS
+.TP
+-showme 
+Do not invoke the underlying compiler.  Instead, show the command line
+that would be executed to compile the program.  \fBNOTE:\fR If a
+non-filename argument is passed on the command line, the \fI-showme\fR
+option will \fInot\fR display any additional flags.  For example, both
+"mpicc --showme" and "mpicc --showme my_source.c" will show all the
+wrapper-supplied flags.  But "mpicc -showme -v" will only show the
+underlying compiler name and "-v".
+.TP
+-showme:compile
+Do not invoke the underlying C/C++ compiler.  Instead, show the
+compiler flags that would be supplied to the C/C++ compiler.
+.TP
+-showme:link
+Do not invoke the underlying C/C++ compiler.  Instead, show the linker
+flags that would be supplied to the C/C++ compiler.
+.PP
+See cc(1) and CC(1) (or whatever your underlying C/C++ compilers are)
+for all other options.
+.
+.
+.SH DESCRIPTION
+.PP
+Conceptually, the role of these commands is quite simple:
+transparently add relevant compiler and linker flags to the user's
+command line that are necessary to compile / link OPAL, ORTE, and OMPI
+programs, and then invoke the underlying compiler to actually perform
+the command.
+.
+.PP
+As such, these commands are frequently referred to as "wrapper"
+compilers because they do not actually compile or link applications
+themselves; they only add in command line flags and invoke the
+back-end compiler.
+.
+.
+.SS Background
+Open MPI is comprised of three software layers: OPAL (Open Portable
+Access Layer), ORTE (Open Run-Time Environment), and OMPI (Open MPI).
+There are wrapper compilers for each layer; each layer's wrapper only
+links in the libraries relevant for that layer.  Specifically, each
+layer provides the following wrapper compilers:
+.
+.TP 4
+OPAL
+\fIopalcc\fR, \fIopalc++\fR, \fIopalCC\fR (only on systems with
+case-sensitive filesystems)
+.
+.TP
+ORTE
+\fIortecc\fR, \fIortec++\fR, \fIorteCC\fR (only on systems with
+case-senstive filesystems)
+.
+.TP
+OMPI
+\fImpicc\fR, \fImpic++\fR, \fImpiCC\fR (only on systems with
+case-senstive file systems), \fImpif77\fR, \fImpif90\fR
+.
+.PP
+Some systems may not have all the wrapper compilers listed above
+depending on which back-end compilers are available.  For example, if
+a system does not have any Fortran compilers available, \fImpif77\fR
+and \fImpif90\fR will not be available.
+.PP
+The descriptions below are use the names of the MPI wrapper compilers,
+but generally apply to all wrapper compilers.  Likewise, the name
+\fImpiCC\fR is used in the descriptions below; it is only available on
+systems with a C++ compiler and case-sensitive filesystems
+(\fImpic++\fR is available on all systems with a C++ compiler).
+.
+.
+.SS Overview
+\fImpicc\fR and \fImpiCC\fR (\fImpic++\fR is a synonym for \fImpiCC\fR
+provided for filenames that do not support case-sensitive filenames)
+are convenience wrappers for the underlying C and C++ compilers.
+Likewise, \fImpif77\fR and \fImpif90\fR are convenience wrappers for
+the underlying F77 and F90 compilers.  Translation of an Open MPI
+program requires the linkage of the Open MPI-specific libraries which
+may not reside in one of the standard search directories of ld(1).  It
+also often requires the inclusion of header files what may also not be
+found in a standard location.  
+.
+.PP
+\fImpicc\fR passes its arguments to the underlying C compiler along
+with the -I, -L and -l options required by Open MPI programs.
+Likewise, \fImpiCC\fR (\fImpic++\fR), \fImpif77\FR, and \fImpif90\fR
+are similar, but invoke the underlying C++, F77, and F90 compiler
+instead, respectively.
+.
+.PP
+The Open MPI Team \fIstrongly\fR encourages using the wrapper
+compilers instead of attempting to link to the Open MPI libraries
+manually.  This allows the specific implementation of Open MPI to
+change without forcing changes to linker directives in users'
+Makefiles.  Indeed, the specific set of flags and libraries used by
+the wrapper compilers depends on how Open MPI was configured and
+built; the values can change between different installations of the
+same version of Open MPI.
+.
+.PP
+Indeed, since the wrappers are simply thin shells on top of an
+underlying compiler, there are very, very few compelling reasons
+\fInot\fR to use \fImpicc\fR / \fImpiCC\fR.  When it is not possible
+to use the wrappers directly, the \fI-showme:compile\fR and
+\fI-showme:link\fR options should be used to determine what flags the
+wrappers would have used.  For example:
+.
+.PP
+shell$ cc -c file1.c `mpicc -showme:compile`
+.
+.PP
+shell$ cc -c file2.c `mpicc -showme:compile`
+.
+.PP
+shell$ cc file1.o file2.o `mpicc -showme:link` -o my_mpi_program
+.
+.
+.SH FILES
+.PP
+The string that the wrapper compilers insert into the command line
+before invoking the underlying compiler are stored in a text file
+created by Open MPI and installed to
+\fI$pkgdata/<wrapper_name>-wrapper-data.txt\fR, where \fI$pkgdata\fR
+is typically \fI$prefix/share/openmpi\fR, and \fI$prefix\fR is the top
+installation directory of Open MPI.  \fI<wrapper_name>\fR is the
+executable name of the wrapper compiler, such as \fImpicc\fR and
+\fImpic++\fR.
+.
+.PP
+It is rarely necessary to edit this file, but it can be examined to
+gain insight into what flags the wrappers are placing on the command
+line.
+.
+.
+.SH ENVIRONMENT VARIABLES
+.PP 
+By default, the wrappers use the compilers that were selected when
+Open MPI was configured.  These compilers were either found
+automatically by Open MPI's "configure" script, or were selected by
+the user in the CC, CXX, F77, and/or FC environment variables 
+before "configure" was invoked.  Additionally, other arguments
+specific to the compiler may have been selected by configure.
+.
+.PP
+These values can be selectively overridden by either editing the text
+files containing this configuration information (see the \fBFILES\fR
+section), or by setting selected environment variables of the
+form "project_value".
+.
+.PP
+Valid project names are \fIOPAL\fR, \fIORTE\fR, and \fIOMPI\fR.  Valid
+value names are:
+.
+.TP
+CC
+C compiler
+.
+.TP
+CFLAGS
+C compiler flags
+.
+.TP
+CXX
+C++ compiler
+.
+.TP
+CXXFLAGS
+C++ compiler flags
+.
+.
+.TP
+F77
+Fortran 77 compiler
+.
+.TP
+FFLAGS
+Fortran 77 compiler flags
+.
+.
+.TP
+FC
+Fortran 90 compiler
+.
+.TP
+FCFLAGS
+Fortran 90 compiler flags

orte/tools/wrappers/Makefile.am

@@ -9,6 +9,7 @@
 #                         University of Stuttgart.  All rights reserved.
 # Copyright (c) 2004-2005 The Regents of the University of California.
 #                         All rights reserved.
+# Copyright (c) 2006      Cisco Systems, Inc.  All rights reserved.
 # $COPYRIGHT$
 # 
 # Additional copyrights may follow
@@ -27,22 +28,31 @@ install-exec-hook:
 	(cd $(DESTDIR)$(bindir); rm -f ortecc$(EXEEXT); $(LN_S) opal_wrapper ortecc)
 	(cd $(DESTDIR)$(bindir); rm -f ortec++$(EXEEXT); $(LN_S) opal_wrapper ortec++)
 	(cd $(DESTDIR)$(bindir); rm -f orteCC$(EXEEXT); $(LN_S) opal_wrapper orteCC)
-
+	(cd $(DESTDIR)$(mandir)/man1; rm -f ortecc.1; $(LN_S) opalcc.1 ortecc.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f ortec++.1; $(LN_S) opalcc.1 ortec++.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f orteCC.1; $(LN_S) opalcc.1 orteCC.1)
 	(cd $(DESTDIR)$(pkgdatadir); rm -f orteCC-wrapper-data.txt; $(LN_S) ortec++-wrapper-data.txt orteCC-wrapper-data.txt)
 
 uninstall-local:
 	rm -f $(DESTDIR)$(bindir)/ortecc$(EXEEXT) \
 	$(DESTDIR)$(bindir)/ortec++$(EXEEXT) \
 	$(DESTDIR)$(bindir)/orteCC$(EXEEXT) \
+	$(DESTDIR)$(mandir)/man1/ortecc.1 \
+	$(DESTDIR)$(mandir)/man1/ortec++.1 \
+	$(DESTDIR)$(mandir)/man1/orteCC.1 \
 	$(DESTDIR)$(pkgdatadir)/orteCC-wrapper-data.txt
 
 else
 install-exec-hook:
 	(cd $(DESTDIR)$(bindir); rm -f ortecc$(EXEEXT); $(LN_S) opal_wrapper ortecc)
 	(cd $(DESTDIR)$(bindir); rm -f ortec++$(EXEEXT); $(LN_S) opal_wrapper ortec++)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f ortecc.1; $(LN_S) opalcc.1 ortecc.1)
+	(cd $(DESTDIR)$(mandir)/man1; rm -f ortec++.1; $(LN_S) opalcc.1 ortec++.1)
 
 uninstall-local:
 	rm -f $(DESTDIR)$(bindir)/ortecc$(EXEEXT) \
+	$(DESTDIR)$(mandir)/man1/ortecc.1 \
+	$(DESTDIR)$(mandir)/man1/ortec++.1 \
 	$(DESTDIR)$(bindir)/ortec++$(EXEEXT)
 
 endif