97b3603036
* fixed some bugs where "unknown" tokens were allowed on the command
line (which should really only be used for ortertun).
* if an unknown token is encountered, print a short error to stderr
and quit with a nonzero exit status
* if we don't find the right number of parameters to an option, print
a short error to stderr and quit with a nonzero exit status
* when --help is given, print the help message to stdout (not stderr)
and quit with a zero exit status
* added --showme:help option to the wrapper compilers
* updated docs in opal/util/cmd_line.h
* other small/miscellaneous CLI parsing bugs in various tools
I won't bore you with what we did before. :-) Here's some examples
of what the new behavior looks like:
{{{
% ompi_info --bogus
ompi_info: Error: unknown option "--bogus"
Type 'ompi_info --help' for usage.
% ompi_info --param bogus
ompi_info: Error: option "--param" did not have enough parameters (2)
Type 'ompi_info --help' for usage.
%
}}}
This commit was SVN r26072.
244 строки
7.3 KiB
Plaintext
244 строки
7.3 KiB
Plaintext
.\" Copyright (c) 2008 Sun Microsystems, Inc. All rights reserved.
|
|
.\" Copyright (c) 2011-2012 Cisco Systems, Inc. All rights reserved.
|
|
.TH #COMMAND# 1 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
|
|
.
|
|
.SH NAME
|
|
#COMMAND# -- #PROJECT# #LANGUAGE# wrapper compiler
|
|
.
|
|
.SH SYNTAX
|
|
#COMMAND# [-showme|-showme:compile|-showme:link] ...
|
|
.
|
|
.SH OPTIONS
|
|
.TP
|
|
--showme
|
|
This option comes in several different variants (see below). None of
|
|
the variants invokes the underlying compiler; they all provide
|
|
information on how the underlying compiler would have been invoked had
|
|
.I --showme
|
|
not been used.
|
|
The basic
|
|
.I --showme
|
|
option outputs 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 "#COMMAND# --showme" and
|
|
"#COMMAND# --showme my_source.c" will show all the wrapper-supplied
|
|
flags. But "#COMMAND# --showme -v" will only show the underlying
|
|
compiler name and "-v".
|
|
.TP
|
|
--showme:compile
|
|
Output the compiler flags that would have been supplied to the
|
|
#LANGUAGE# compiler.
|
|
.TP
|
|
--showme:link
|
|
Output the linker flags that would have been supplied to the
|
|
#LANGUAGE# compiler.
|
|
.TP
|
|
--showme:command
|
|
Outputs the underlying #LANGUAGE# compiler command (which may be one
|
|
or more tokens).
|
|
.TP
|
|
--showme:incdirs
|
|
Outputs a space-delimited (but otherwise undecorated) list of
|
|
directories that the wrapper compiler would have provided to the
|
|
underlying #LANGUAGE# compiler to indicate where relevant header files
|
|
are located.
|
|
.TP
|
|
--showme:libdirs
|
|
Outputs a space-delimited (but otherwise undecorated) list of
|
|
directories that the wrapper compiler would have provided to the
|
|
underlying linker to indicate where relevant libraries are located.
|
|
.TP
|
|
--showme:libs
|
|
Outputs a space-delimited (but otherwise undecorated) list of library
|
|
names that the wrapper compiler would have used to link an
|
|
application. For example: "mpi open-rte open-pal util".
|
|
.TP
|
|
--showme:version
|
|
Outputs the version number of Open MPI.
|
|
.TP
|
|
--showme:help
|
|
Output a brief usage help message.
|
|
.PP
|
|
See the man page for your underlying #LANGUAGE# compiler for other
|
|
options that can be passed through #COMMAND#.
|
|
.
|
|
.
|
|
.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 #PROJECT#
|
|
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 and \fIopalc++\fR
|
|
.
|
|
.TP
|
|
ORTE
|
|
\fIortecc\fR and \fIortec++\fR
|
|
.
|
|
.TP
|
|
OMPI
|
|
\fImpicc\fR, \fImpic++\fR, \fImpicxx\fR, \fImpiCC\fR (only on systems with
|
|
case-senstive file systems), \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.
|
|
.
|
|
.PP
|
|
The Fortran wrapper compilers for MPI (\fImpif77\fR and \fImpif90\fR)
|
|
will be inoperative and will return an error on use if Fortran 77 /
|
|
Fortran 90 support was not built into the MPI layer.
|
|
.
|
|
.
|
|
.SS Overview
|
|
\fI#COMMAND#\fR is a convenience wrappers for the underlying
|
|
#LANGUAGE# compiler. Translation of an #PROJECT# program requires the
|
|
linkage of the #PROJECT#-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
|
|
\fI#COMMAND#\fR passes its arguments to the underlying #LANGUAGE#
|
|
compiler along with the -I, -L and -l options required by #PROJECT#
|
|
programs.
|
|
.
|
|
.PP
|
|
The #PROJECT# Team \fIstrongly\fR encourages using the wrapper
|
|
compilers instead of attempting to link to the #PROJECT# libraries
|
|
manually. This allows the specific implementation of #PROJECT# 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 #PROJECT# was configured and
|
|
built; the values can change between different installations of the
|
|
same version of #PROJECT#.
|
|
.
|
|
.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 \fI#COMMAND#\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 NOTES
|
|
.PP
|
|
It is possible to make the wrapper compilers multi-lib aware. That
|
|
is, the libraries and includes specified may differ based on the
|
|
compiler flags specified (for example, with the GNU compilers on
|
|
Linux, a different library path may be used if -m32 is seen versus
|
|
-m64 being seen). This is not the default behavior in a standard
|
|
build, but can be activated (for example, in a binary package
|
|
providing both 32 and 64 bit support). More information can be found
|
|
at:
|
|
.PP
|
|
https://svn.open-mpi.org/trac/ompi/wiki/compilerwrapper3264
|
|
.
|
|
.
|
|
.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 #PROJECT# and installed to
|
|
\fI$pkgdata/#COMMAND#-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 #PROJECT#.
|
|
.
|
|
.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
|
|
#PROJECT# 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_SHORT#_value".
|
|
.
|
|
.PP
|
|
Valid value names are:
|
|
.
|
|
.TP
|
|
CPPFLAGS
|
|
Flags added when invoking the preprocessor (C or C++)
|
|
.
|
|
.TP
|
|
LDFLAGS
|
|
Flags added when invoking the linker (C, C++, or Fortran)
|
|
.
|
|
.TP
|
|
LIBS
|
|
Libraries added when invoking the linker (C, C++, or Fortran)
|
|
.
|
|
.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
|