Split out the map/rank/bind into a separate man

src/mca/schizo/pmix/schizo_pmix.c

@@ -74,14 +74,14 @@ prte_schizo_base_module_t prte_schizo_pmix_module = {
 static prte_cmd_line_init_t cmd_line_init[] = {
     /* setup MCA parameters */
     { '\0', "pmixmca", 2, PRTE_CMD_LINE_TYPE_STRING,
-      "Pass context-specific PMIx MCA parameters; they are considered global if --gmca is not used and only one context is specified (arg0 is the parameter name; arg1 is the parameter value)",
+      "Pass context-specific PMIx MCA parameters; they are considered global if --gpmixmca is not used and only one context is specified (arg0 is the parameter name; arg1 is the parameter value)",
+      PRTE_CMD_LINE_OTYPE_LAUNCH },
+    { '\0', "gmca", 2, PRTE_CMD_LINE_TYPE_STRING,
+      "Pass global MCA parameters that are applicable to all contexts (arg0 is the parameter name; arg1 is the parameter value)",
       PRTE_CMD_LINE_OTYPE_LAUNCH },
     { '\0', "gpmixmca", 2, PRTE_CMD_LINE_TYPE_STRING,
       "Pass global PMIx MCA parameters that are applicable to all contexts (arg0 is the parameter name; arg1 is the parameter value)",
       PRTE_CMD_LINE_OTYPE_LAUNCH },
-    { '\0', "pmixam", 1, PRTE_CMD_LINE_TYPE_STRING,
-      "Aggregate PMIx MCA parameter set file list",
-      PRTE_CMD_LINE_OTYPE_LAUNCH },
 
     /* End of list */
     { '\0', NULL, 0, PRTE_CMD_LINE_TYPE_NULL, NULL }

src/mca/schizo/prte/schizo_prte.c

@@ -111,11 +111,15 @@ static prte_cmd_line_init_t cmd_line_init[] = {
 
     /* setup MCA parameters */
     { '\0', "mca", 2, PRTE_CMD_LINE_TYPE_STRING,
-      "Pass context-specific MCA parameters; they are considered global if --gmca is not used and only one context is specified (arg0 is the parameter name; arg1 is the parameter value)",
+      "Pass context-specific MCA parameters; they are considered global if --gpmixmca is not used and only one context is specified (arg0 is the parameter name; arg1 is the parameter value)",
       PRTE_CMD_LINE_OTYPE_LAUNCH },
     { '\0', "prtemca", 2, PRTE_CMD_LINE_TYPE_STRING,
-      "Pass context-specific PRTE MCA parameters; they are considered global if --gmca is not used and only one context is specified (arg0 is the parameter name; arg1 is the parameter value)",
+      "Pass context-specific PRTE MCA parameters; they are considered global if --gpmixmca is not used and only one context is specified (arg0 is the parameter name; arg1 is the parameter value)",
       PRTE_CMD_LINE_OTYPE_LAUNCH },
+    { '\0', "gprtemca", 2, PRTE_CMD_LINE_TYPE_STRING,
+      "Pass global PRRTE MCA parameters that are applicable to all contexts (arg0 is the parameter name; arg1 is the parameter value)",
+      PRTE_CMD_LINE_OTYPE_LAUNCH },
+
 
     /* Request parseable help output */
     { '\0', "prte_info_pretty", 0, PRTE_CMD_LINE_TYPE_BOOL,
@@ -230,7 +234,8 @@ static int parse_cli(int argc, int start, char **argv,
 
     for (i = 0; i < (argc-start); ++i) {
         ignore = true;
-        if (0 == strcmp("--prtemca", argv[i])) {
+        if (0 == strcmp("--prtemca", argv[i]) ||
+            0 == strcmp("--gprtemca", argv[i])) {
             if (NULL == argv[i+1] || NULL == argv[i+2]) {
                 /* this is an error */
                 return PRTE_ERR_FATAL;

src/tools/prte/prte.1.md

@@ -1,13 +1,19 @@
 # NAME
 
-prte - Establish a PRTE Distributed Virtual Machine (DVM).
+prte - Establish a PRRTE Distributed Virtual Machine (DVM).
 
 # SYNOPSIS
 
+Persistent DVM mode:
 ```
 prte [ options ]
 ```
 
+Single-Use DVM mode:
+```
+prte [ options ] <program> [ <args> ]
+```
+
 Invoking `prte` via an absolute path name is equivalent to
 specifying the `--prefix` option with a `<dir>` value equivalent to
 the directory where `prte` resides, minus its last subdirectory.
@@ -20,115 +26,138 @@ $ /usr/local/bin/prte ...
 is equivalent to
 
 ```
-$ prte --prefix /usr/local
+$ prte --prefix /usr/local ...
 ```
 
 # QUICK SUMMARY
 
-`prte` will establish a DVM that can be used to execute subsequent
-applications. Use of `prte` can be advantageous, for example, when
-you want to execute a number of short-lived tasks. In such cases, the
-time required to start the PRTE DVM can be a significant fraction of
-the time to execute the overall application. Thus, creating a persistent
-DVM can speed the overall execution. In addition, a persistent DVM will
-support executing multiple parallel applications while maintaining
-separation between their respective cores.
+`prte` can be invoked in one of two DVM modes, namely, Persistent and Single-Use
+modes.
+
+In Persistent mode, `prte` will establish a Distributed Virtual Machine (DVM)
+that can be used to execute subsequent applications. Use of `prte` in this mode
+can be advantageous, for example, when you want to execute a number of
+short-lived tasks (e.g., in a workflow scenario). In such cases, the time
+required to start the PRRTE DVM can be a significant fraction of the time to
+execute the overall application. Thus, creating a persistent PRRTE DVM can
+speed the overall execution. In addition, a persistent DVM will support
+executing multiple parallel applications while maintaining separation between
+their respective cores.
+
+In Single-Use mode, `prte` will establish a Distributed Virtual Machine (DVM),
+run the specified `<program>`, then shutdown the PRRTE DVM. Use of `prte` in
+this mode can streamline applications that only want to execute a single
+application. In this mode `prte` accepts all of the `prun` command line options
+for starting the application.
 
 # OPTIONS
 
+`prte` accepts all of the command line options from `prun`. Some of which are
+only meaningful when `prte` is used in the Single-Use mode. Below are frequently
+used options and those options unique to `prte`.
+
 `-h, --help`
 
 :   Display help for this command
 
 `-V, --version`
 
 :   Print version number. If no other arguments are given, this will
-    also cause prte to exit.
+    also cause `prte` to exit.
 
-Use one of the following options to specify which hosts (nodes) of the
-cluster to use for the DVM.
+`--daemonize`
 
-`-H, --host <host1,host2,...,hostN>`
+:   Daemonize the DVM daemons into the background
 
-:   List of hosts for the DVM.
+`--no-ready-msg`
 
-`--hostfile <hostfile>`
+:  Do not print a "DVM ready" message
 
-:   Provide a hostfile to use.
+`--report-pid <channel>`
+
+:   Print out `prte`'s PID during startup. The `<channel>` must be
+    either a '-' to indicate that the URI is to be output to stdout, a
+    '+' to indicate that the URI is to be output to stderr, or a
+    filename to which the URI is to be written.
 
-`--machinefile <machinefile>`
+`--report-uri <channel>`
 
-:   Synonym for `-hostfile`.
+:   Print out `prte`'s URI during startup. The `<channel>` must be
+    either a '-' to indicate that the URI is to be output to stdout, a
+    '+' to indicate that the URI is to be output to stderr, or a
+    filename to which the URI is to be written.
 
-`--prefix <dir>`
+`--system-server`
 
-:   Prefix directory that will be used to set the `PATH` and
-    `LD_LIBRARY_PATH` on the remote node before invoking the PRTE
-    daemon.
+:   Start the DVM as the system server
 
-Setting MCA parameters:
+`--set-sid`
 
-`--gmca <key> <value>`
+:   Direct the DVM daemons to separate from the current session
 
-:   Pass global MCA parameters that are applicable to all contexts.
-    `<key>` is the parameter name; `<value>` is the parameter value.
+`--max-vm-size <arg0>`
 
-`--mca <key> <value>`
+:   The number of DVM daemons to start
 
-:   Send arguments to various MCA modules. See the "MCA" section,
-    below.
+`--launch-agent <arg0>`
 
-`--report-uri <channel>`
+:   Name of DVM daemon executable used to start processes on remote nodes.
+    Default: `prted`
 
-:   Print out prte's URI during startup. The channel must be
-    either a '-' to indicate that the URI is to be output to stdout, a
-    '+' to indicate that the URI is to be output to stderr, or a
-    filename to which the URI is to be written.
+## Debugging Options
 
 The following options are useful for developers; they are not generally
-useful to most PRTE users:
+useful to most PRRTE users:
 
 `-d, --debug-devel`
 
-:   Enable debugging of the PRTE layer.
+:   Enable debugging of the PRRTE layer.
+
+`--debug`
+
+:   Top-level PRRTE debug switch (default: false)
+
+`--debug-daemons`
+
+:   Enable debugging of the PRRTE daemons in the DVM, output to the terminal.
 
 `--debug-daemons-file`
 
-:   Enable debugging of the PRTE daemons in the DVM, storing output in
+:   Enable debugging of the PRRTE daemons in the DVM, storing output in
     files.
 
+`--debug-verbose <arg0>`
+
+:  Verbosity level for PRRTE debug messages (default: `1`)
+
+`--leave-session-attached`
+
+:  Do not discard stdout/stderr of remote PRRTE daemons
+
+`--test-suicide <arg0>`
+
+:  Suicide instead of clean abort after delay
+
 There may be other options listed with `prte --help`.
 
+
 # DESCRIPTION
 
 `prte` starts a Distributed Virtual Machine (DVM) by launching a
 daemon on each node of the allocation, as modified or specified by the
-`--host` and `--hostfile` options. Applications can subsequently be
-executed using the `prun` command. The DVM remains in operation until
-receiving the `pterm` command.
-
-## Specifying Host Nodes
+`--host` and `--hostfile` options.
 
-Host nodes can be identified on the `prte` command line with the
-`--host` option or in a hostfile.
+In the Persistent mode, applications can subsequently be executed using the
+`prun` command. In this mode, the DVM remains in operation until receiving the
+`pterm` command.
 
-For example,
+In the Single-Use mode, applications are executed immediately after `prte`
+establishes the DVM, and the DVM is cleaned up when the application terminates.
 
-`prte -H aa,aa,bb ./a.out`
+# RETURN VALUE
 
-:   launches two processes on node aa and one on bb.
-
-Or, consider the hostfile
-
-```
-$ cat myhostfile aa slots=2 bb slots=2 cc slots=2
-```
+In the Persistent mode, `prte` returns 0 if no abnormal daemon failure occurs
+during the life of the DVM, and non-zero otherwise.
 
-Here, we list both the host names (`aa`, `bb`, and `cc`) but also how
-many "slots" there are for each. Slots indicate how many processes can
-potentially execute on a node. For best performance, the number of
-slots may be chosen to be the number of cores on the node or the
-number of processor sockets. If the hostfile does not provide slots
-information, a default of 1 is assumed. When running under resource
-managers (e.g., SLURM, Torque, etc.), PRTE will obtain both the
-hostnames and the number of slots directly from the resource manger.
+In the Single-Use mode, `prte` returns the value that `prun` would have returned
+for that application. See the `prun` man page for details.

src/tools/prun/help-prun.txt

@@ -27,7 +27,7 @@ attempting to %s.  Returned value %d instead of PRTE_SUCCESS.
 [prun:usage]
 %s (%s) %s
 
-Usage: %s [OPTION]...
+Usage: %s [ options ] <program> [ <args> ]
 Submit job to the PMIx Reference RTE
 
 %s