* Add man page for ompi_info, originally contributed by Dirk

Eddelbuettel, one of the Debian/GNU Linux maintainers of the Open MPI package. * Updated the contributed man page with some examples and updated option descriptions, and other small things. * Made the --hostname option work again. * Made the --version option work like it's supposed to. * Updated help strings that are displayed via --help to be a bit more descriptive in the parameters that various options accept. This commit was SVN r15260.
2007-07-02 06:12:02 +00:00 · 2007-07-02 06:12:02 +00:00 · b7a1778f93
--- a/ompi/tools/ompi_info/Makefile.am
+++ b/ompi/tools/ompi_info/Makefile.am
@ -60,5 +60,10 @@ ompi_info_LDADD = $(libs)
 ompi_info_LDFLAGS = 
 ompi_info_DEPENDENCIES = $(libs)

+# AM 1.9.6 seems to have a bug in its dependencies for install-man if
+# dist_ and nodist_ are used, so explicitly add to EXTRA_DIST...
+man_MANS = ompi_info.1
+EXTRA_DIST = $(man_MANS)
+
 clean-local:
 	test -z "$(OMPI_CXX_TEMPLATE_REPOSITORY)" || $(RM) -rf $(OMPI_CXX_TEMPLATE_REPOSITORY)
--- a/ompi/tools/ompi_info/ompi_info.1
+++ b/ompi/tools/ompi_info/ompi_info.1
@ -0,0 +1,161 @@
+.\" Man page contributed by Dirk Eddelbuettel <edd@debian.org>
+.\" and released under the BSD license
+.TH OMPI_INFO 1 "July 2006" "Open MPI" "OPEN MPI COMMANDS"
+.SH NAME
+ompi_info - Display information about the Open MPI installation
+.
+.\" **************************
+.\"    Synopsis Section
+.\" **************************
+.SH SYNOPSIS
+.B ompi_info [options]
+.
+.\" **************************
+.\"    Description Section
+.\" **************************
+.SH DESCRIPTION
+.PP
+.B ompi_info
+provides detailed information about the Open MPI installation.  It can
+be useful for at least three common scenarios:
+.PP
+1. Checking local configuration and seeing how Open MPI was installed.
+.PP
+2. Submitting bug reports / help requests to the Open MPI community
+(see 
+.IR http://www.open-mpi.org/community/help/ )
+.PP
+3. Seeing a list of installed Open MPI plugins and querying what 
+MCA parameters they support.
+.
+.\" **************************
+.\"    Options Section
+.\" **************************
+.SH OPTIONS
+.B ompi_info
+accepts the following options:
+.TP 8
+.I \-a|\-\-all 
+Show all configuration options and MCA parameters
+.TP 8
+.I \-\-arch   
+Show architecture Open MPI was compiled on
+.TP 8
+.I \-c|\-\-config
+Show configuration options
+.TP 8
+.I \-gmca|\-\-gmca <param> <value>
+Pass global MCA parameters that are applicable to all contexts.
+.TP 8
+.I \-h|\-\-help
+Shows help / usage message
+.TP 8
+.I \-\-hostname
+Show the hostname that Open MPI was configured and built on
+.TP 8
+.I \-\-internal
+Show internal MCA parameters (not meant to be modified by users)
+.TP 8
+.I \-mca|\-\-mca <param> <value>
+Pass context-specific MCA parameters; they are considered global if --gmca is
+not used and only one context is specified.
+.TP 8
+.I \-\-param <type> <component>
+Show MCA parameters.  The first parameter is the type of the component
+to display; the second parameter is the specific component to display
+(or the keyword "all", meaning "display all components of this type").
+.TP 8
+.I \-\-parsable
+When used in conjunction with other parameters, the output is
+displayed in a machine-parsable format
+.I \-\-parseable
+Synonym for --parsable
+.TP 8
+.I \-\-path <type>
+Show paths that Open MPI was configured with.  Accepts the following
+parameters: prefix, bindir, libdir, incdir, pkglibdir, sysconfdir.
+.TP 8
+.I \-\-pretty
+When used in conjunction with other parameters, the output is
+displayed in 'prettyprint' format (default)
+.TP 8
+.I \-v|\-\-version <component> <scope>
+Show version of Open MPI or a component.  <component> can be the
+keywords "ompi" or "all", the name of a framework (e.g., "coll" shows
+all components in the coll framework), or the name of a specific
+component (e.g., "pls:rsh" shows the information from the rsh PLS
+component).  <scope> can be one of: full, major, minor, release,
+greek, svn.
+.
+.\" **************************
+.\"    Examples Section
+.\" **************************
+.SH EXAMPLES
+.TP 4
+ompi_info
+Show the default output of options and listing of installed
+components in a human-readable / prettyprint format.
+.
+.
+.TP
+ompi_info --parsable
+Show the default output of options and listing of installed
+components in a machine-parsable format.
+.
+.
+.TP
+ompi_info --param btl openib
+Show the MCA parameters of the "openib" BTL component in a
+human-readable / prettyprint format.
+.
+.
+.TP
+ompi_info --param btl openib --parsable
+Show the MCA parameters of the "openib" BTL component in a
+machine-parsable format.
+.
+.
+.TP
+ompi_info --path bindir
+Show the "bindir" that Open MPI was configured with.
+.
+.
+.TP
+ompi_info --version ompi full --parsable
+Show the full version numbers of Open MPI (including the ORTE and OPAL
+version numbers) in a machine-readable format.
+.
+.
+.TP
+ompi_info --version btl major
+Show the major version number of all BTL components in a prettyprint
+format.
+.
+.
+.TP
+ompi_info --version btl:tcp minor
+Show the minor version number of the TCP BTL component in a
+prettyprint format.
+.
+.
+.TP
+ompi_info --all
+Show 
+.I all 
+information about the Open MPI installation, including all components
+that can be found, the MCA parameters that they support, versions of
+Open MPI and the components, etc.
+.
+.
+.\" **************************
+.\"    Authors Section
+.\" **************************
+.SH AUTHORS
+The Open MPI maintainers -- see 
+.I http://www.openmpi.org/
+or the file
+.IR AUTHORS .
+.PP
+This manual page was originally contributed by Dirk Eddelbuettel
+<edd@debian.org>, one of the Debian GNU/Linux maintainers for Open
+MPI, and may be used by others.
--- a/ompi/tools/ompi_info/ompi_info.cc
+++ b/ompi/tools/ompi_info/ompi_info.cc
@ -95,13 +95,13 @@ int main(int argc, char *argv[])
  }

  opal_cmd_line_make_opt3(cmd_line, 'v', NULL, "version", 2, 
-                          "Show version of Open MPI or a component");
+                          "Show version of Open MPI or a component.  The first parameter can be the keywords \"ompi\" or \"all\", a framework name (indicating all components in a framework), or a framework:component string (indicating a specific component).  The second parameter can be one of: full, major, minor, release, greek, svn.");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "param", 2, 
-                          "Show MCA parameters");
+                          "Show MCA parameters.  The first parameter is the framework (or the keyword \"all\"); the second parameter is the specific component name (or the keyword \"all\").");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "internal", 0, 
                          "Show internal MCA parameters (not meant to be modified by users)");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "path", 1, 
-                          "Show paths that Open MPI was configured with");
+                          "Show paths that Open MPI was configured with.  Accepts the following parameters: prefix, bindir, libdir, incdir, pkglibdir, sysconfdir");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "arch", 0, 
                          "Show architecture Open MPI was compiled on");
  opal_cmd_line_make_opt3(cmd_line, 'c', NULL, "config", 0, 
@ -109,9 +109,9 @@ int main(int argc, char *argv[])
  opal_cmd_line_make_opt3(cmd_line, 'h', NULL, "help", 0, 
                          "Show this help message");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "pretty", 0, 
-                          "Display output in 'prettyprint' format (default)");
+                          "When used in conjunction with other parameters, the output is displayed in 'prettyprint' format (default)");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "parsable", 0, 
-                          "Display output in parsable format");
+                          "When used in conjunction with other parameters, the output is displayed in a machine-parsable format");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "parseable", 0, 
                          "Synonym for --parsable");
  opal_cmd_line_make_opt3(cmd_line, '\0', NULL, "hostname", 0, 
@ -243,7 +243,11 @@ int main(int argc, char *argv[])
    acted = true;
  }
  if (want_all || opal_cmd_line_is_taken(cmd_line, "arch")) {
-    do_arch(cmd_line);
+    do_arch();
+    acted = true;
+  }
+  if (want_all || opal_cmd_line_is_taken(cmd_line, "hostname")) {
+    do_hostname();
    acted = true;
  }
  if (want_all || opal_cmd_line_is_taken(cmd_line, "config")) {
@ -260,7 +264,8 @@ int main(int argc, char *argv[])
  if (!acted) {
    ompi_info::show_ompi_version(ver_full);
    ompi_info::show_path(path_prefix, opal_install_dirs.prefix);
-    ompi_info::do_arch(cmd_line);
+    ompi_info::do_arch();
+    ompi_info::do_hostname();
    ompi_info::do_config(false);
    ompi_info::open_components();
    for (ompi_info::type_vector_t::size_type i = 0; 
--- a/ompi/tools/ompi_info/ompi_info.h
+++ b/ompi/tools/ompi_info/ompi_info.h
@ -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) 2007      Cisco, Inc.  All rights reserved.
 // $COPYRIGHT$
 // 
 // Additional copyrights may follow
@ -85,7 +86,8 @@ namespace ompi_info {
  void do_path(bool want_all, opal_cmd_line_t *cmd_line);
  void show_path(const std::string& type, const std::string& value);

-  void do_arch(opal_cmd_line_t *cmd_line);
+  void do_arch();
+  void do_hostname();
  void do_config(bool want_all);

  //
--- a/ompi/tools/ompi_info/param.cc
+++ b/ompi/tools/ompi_info/param.cc
@ -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) 2007      Cisco, Inc.  All rights reserved.
 // $COPYRIGHT$
 // 
 // Additional copyrights may follow
@ -297,16 +298,15 @@ void ompi_info::show_path(const string& type, const string& value)
 }


-void ompi_info::do_arch(opal_cmd_line_t *cmd_line)
+void ompi_info::do_arch()
 {
-  string prefix;
-  char hostname[MAXHOSTNAMELEN];
+    out("Configured architecture", "config:arch", OMPI_ARCH);
+}

-  if (opal_cmd_line_is_taken(cmd_line, "hostname")) {
-    gethostname(hostname, MAXHOSTNAMELEN);
-    prefix = hostname + string(":");
-  }
-  out("Configured architecture", prefix + "config:arch", OMPI_ARCH);
+
+void ompi_info::do_hostname()
+{
+    out("Configure host", "config:host", OMPI_CONFIGURE_HOST);
 }


--- a/ompi/tools/ompi_info/version.cc
+++ b/ompi/tools/ompi_info/version.cc
@ -104,8 +104,8 @@ void ompi_info::do_version(bool want_all, opal_cmd_line_t *cmd_line)
      // Specific type and component

      else if (string::npos != (pos = arg1.find(':'))) {
-        type = arg1.substr(0, pos - 1);
-        component = arg1.substr(pos);
+        type = arg1.substr(0, pos);
+        component = arg1.substr(pos + 1);

        show_component_version(type, component, scope, ver_all);
      }