diff --git a/ompi/tools/wrappers/Makefile.am b/ompi/tools/wrappers/Makefile.am index 57dcebc366..70b4c7b38e 100644 --- a/ompi/tools/wrappers/Makefile.am +++ b/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 diff --git a/opal/tools/wrappers/Makefile.am b/opal/tools/wrappers/Makefile.am index 9504d31baa..1f1ff80d03 100644 --- a/opal/tools/wrappers/Makefile.am +++ b/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) diff --git a/opal/tools/wrappers/opalcc.1 b/opal/tools/wrappers/opalcc.1 new file mode 100644 index 0000000000..131a60180b --- /dev/null +++ b/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-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\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 diff --git a/orte/tools/wrappers/Makefile.am b/orte/tools/wrappers/Makefile.am index 575cbb37b1..8ea47ea24c 100644 --- a/orte/tools/wrappers/Makefile.am +++ b/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