# -*- text -*-
#
# Copyright (c) 2025-2026 Nanook Consulting  All rights reserved.
# $COPYRIGHT$
#
# Additional copyrights may follow
#
# $HEADER$
#
# This is the US/English general help file for PRTE's prte.
#
[version]

%s (%s) %s

%s
#
[usage]

%s (%s) %s

Usage: %s [OPTION]...

Initiate an instance of the PMIx Reference RTE (PRRTE) DVM

The following list of command line options are available. Note that
more detailed help for any option can be obtained by adding that
option to the help request as "--help <option>".

+----------------------+-----------------------------------------------+
|                      | General Options                               |
+----------------------+-----------------------------------------------+
| Option               | Description                                   |
|======================|===============================================|
| "-h" | "--help"      | This help message                             |
+----------------------+-----------------------------------------------+
| "-h" | "--help       | Help for the specified option                 |
| <arg0>"              |                                               |
+----------------------+-----------------------------------------------+
| "-v" | "--verbose"   | Enable typical debug options                  |
+----------------------+-----------------------------------------------+
| "-V" | "--version"   | Print version and exit                        |
+----------------------+-----------------------------------------------+

+----------------------+-----------------------------------------------+
|                      | Debug Options                                 |
+----------------------+-----------------------------------------------+
| Option               | Description                                   |
|======================|===============================================|
| "--debug-daemons"    | Debug daemons - if not set, any "verbose"     |
|                      | settings will be limited to the DVM           |
|                      | controller to reduce clutter                  |
+----------------------+-----------------------------------------------+
| "--debug-daemons-    | Enable debugging of any PRRTE daemons used by |
| file"                | this application, storing their verbose       |
|                      | output in files                               |
+----------------------+-----------------------------------------------+
| "--leave-session-    | Do not discard stdout/stderr of remote PRRTE  |
| attached"            | daemons                                       |
+----------------------+-----------------------------------------------+
| "--display <arg0>"   | Comma-delimited list of options for           |
|                      | displaying information                        |
+----------------------+-----------------------------------------------+
| "--no-aggregate-help" | Do not aggregate help output from multiple   |
|                      | processes.                                    |
+----------------------+-----------------------------------------------+

+----------------------+-----------------------------------------------+
|                      | DVM Options                                   |
+----------------------+-----------------------------------------------+
| Option               | Description                                   |
|======================|===============================================|
| "--runtime-options   | Comma-delimited list of runtime directives    |
| <options>"           | for the job (e.g., show progress reports on   |
|                      | DVM startup for large systems)                |
+----------------------+-----------------------------------------------+
| "--default-hostfile  | Provide a default hostfile                    |
| <filename>"          |                                               |
+----------------------+-----------------------------------------------+
| "-H|--host           | List of hosts to use for the DVM              |
| <hostname>"          |                                               |
+----------------------+-----------------------------------------------+
| "--hostfile          | Provide a hostfile                            |
| <filename>"          |                                               |
+----------------------+-----------------------------------------------+
| "--machinefile       | Provide a hostfile (synonym for "--hostfile") |
| <filename>"          |                                               |
+----------------------+-----------------------------------------------+
| "--pmixmca <key>     | Pass PMIx MCA parameters                      |
| <value>"             |                                               |
+----------------------+-----------------------------------------------+
| "--prtemca <key>     | Pass PRTE MCA parameters to the DVM           |
| <value>"             |                                               |
+----------------------+-----------------------------------------------+
| "-x                  | Export an environment variable, optionally    |
| <var_name>[=value]"  | specifying a value                            |
+----------------------+-----------------------------------------------+
| "--allow-run-as-     | Allow execution as root (**STRONGLY           |
| root"                | DISCOURAGED**)                                |
+----------------------+-----------------------------------------------+
| "--daemonize"        | Daemonize the DVM daemons into the background |
+----------------------+-----------------------------------------------+
| "--exec-agent        | Executable to be used to start an application |
| <path>"              | process. The resulting command will be        |
|                      | "<path> app <app-argv>"; the path may contain |
|                      | its own command line arguments                |
+----------------------+-----------------------------------------------+
| "--forward-signals   | Comma-delimited list of the signals (names or |
| <signals>"           | integers) to be forwarded, replacing the      |
|                      | default set                                   |
+----------------------+-----------------------------------------------+
| "--keepalive <arg0>" | Pipe to monitor - DVM will terminate upon     |
|                      | closure                                       |
+----------------------+-----------------------------------------------+
| "--launch-agent      | Name of daemon executable used to start       |
| <executable>"        | processes on remote nodes (default: "prted")  |
+----------------------+-----------------------------------------------+
| "--max-vm-size       | Max number of daemons to start                |
| <size>"              |                                               |
+----------------------+-----------------------------------------------+
| "--no-ready-msg"     | Do not print a "DVM ready" message            |
+----------------------+-----------------------------------------------+
| "--noprefix"         | Disable automatic "--prefix" behavior         |
+----------------------+-----------------------------------------------+
| "--prefix <dir>"     | Prefix to be used to look for RTE executables |
|                      | AND their libraries on remote nodes. Note     |
|                      | that an assumption is made that the libraries |
|                      | will be located at the same subdirectory as   |
|                      | per the configuration options given when      |
|                      | PRRTE was built.                              |
+----------------------+-----------------------------------------------+
| "--pmix-prefix <dir>" | Prefix to be used to look for the PMIx       |
|                      | library used by RTE executables on remote     |
|                      | nodes. This is the location of the top-level  |
|                      | directory for the installation.               |
+----------------------+-----------------------------------------------+
| "--report-pid <arg>" | Print out PID on stdout ("-"), stderr ("+"),  |
|                      | or a file (anything else)                     |
+----------------------+-----------------------------------------------+
| "--report-uri <arg>" | Print out URI on stdout ("-"), stderr ("+"),  |
|                      | or a file (anything else)                     |
+----------------------+-----------------------------------------------+
| "--set-sid"          | Direct the DVM daemons to separate from the   |
|                      | current session                               |
+----------------------+-----------------------------------------------+
| "--singleton <id>"   | ID of the singleton process that started us   |
+----------------------+-----------------------------------------------+
| "--system-server"    | Start the DVM as the system server            |
+----------------------+-----------------------------------------------+
| "--tune <arg0>"      | File(s) containing MCA params for tuning DVM  |
|                      | operations                                    |
+----------------------+-----------------------------------------------+
| "--timeout           | Timeout DVM startup if time exceeds the       |
| <seconds>"           | specified number of seconds                   |
+----------------------+-----------------------------------------------+
| "--uniform-nodes"    | The allocation contains only one topology,    |
|                      | so optimize the launch for that scenario.     |
|                      | This includes ensuring that all CPU           |
|                      | allocations are the same on each node, that   |
|                      | each node contains the same number of devices |
|                      | and topological layers, etc.                  |
+----------------------+-----------------------------------------------+

%s
#
[prtemca]

Pass a PRRTE MCA parameter.

Syntax: "--prtemca <key> <value>", where "key" is the parameter name and
"value" is the parameter value.
#
[pmixmca]

Pass a PMIx MCA parameter

Syntax: "--pmixmca <key> <value>", where "key" is the parameter name and
"value" is the parameter value.
#
[tune]

Comma-delimited list of one or more files containing MCA parameters for
tuning DVM and/or application operations. The option may be given more
than once. A file named by a relative path is looked for first in the
current directory and then among the parameter sets installed with
PRRTE.

Syntax in the file is:

   param = value

with one parameter per line. Empty lines and lines beginning with the
"#" character are ignored, as is any whitespace around the "="
character. Quotes around the value are removed.

Each parameter is a *generic* MCA parameter, so it is treated exactly
like "--mca param value": it is applied to PRRTE if it belongs to a
PRRTE framework, and otherwise to PMIx. A parameter that belongs to
neither is an error, as is a parameter given twice with different
values. A parameter given explicitly on the command line ("--prtemca",
"--pmixmca") overrides the same parameter in a tune file.
#
[exec-agent]

Executable to be used to start an application process. The resulting
command for starting an application process will be "<path> app
<app-argv>". The path may contain its own command line arguments.

Note that this can also be given as a runtime option (see "--help
runtime-options"), and that "--runtime-options default-exec-agent"
returns the job to the system default agent.
#
[uniform-nodes]

The "uniform-nodes" command line directive is used to indicate that the
allocated nodes should be treated as having only one topology, so
optimize the launch for that scenario. This includes ensuring that all
CPU allocations are the same on each node, that each node contains the
same number of devices and topological layers, etc.

Note:

  The runtime does not currently support mixes of chips with different
  endianness.
#
[no-ready-msg]

Do not print a DVM ready message
#
[daemonize]

Daemonize the DVM daemons and controller into the background
#
[system-server]

Start the DVM controller and its daemons as the system server on their
nodes
#
[set-sid]

Direct the DVM (controller and daemons) to separate from the current
session
#
[report-pid]

Print the PID of this process: on stdout if the argument is "-", on
stderr if it is "+", into the already-open file descriptor it names if
it is a non-negative integer, and otherwise into the file it names.
#
[report-uri]

Print the PMIx contact URI of this process: on stdout if the argument is
"-", on stderr if it is "+", and otherwise into the file it names.
#
[default-hostfile]

Specify a default hostfile.

Also see "--help hostfile".
#
[singleton]

DVM is being started by a singleton process (i.e., one not started by
a DVM) - the argument must be the PMIx ID of the singleton process
that started us
#
[keepalive]

Pipe for DVM controller to monitor - DVM will terminate upon closure
#
[launch-agent]

Name of daemon executable used to start processes on remote nodes
(default: prted).  This is the executable the DVM controller shall
start on each remote node when establishing the DVM.
#
[max-vm-size]

Maximum number of daemons to start - sets the maximum size of the DVM.
#
[debug-daemons]

Debug daemon output enabled. This is a somewhat limited stream of
information normally used to simply confirm that the daemons started.
Includes leaving the output streams open.
#
[debug-daemons-file]

Debug daemon output is enabled and all output from the daemons is
redirected into files with names of the form:

   output-prted-<daemon-nspace>-<nodename>.log

These names avoid conflict on shared file systems. The files are located
in the top-level session directory assigned to the DVM.

See the "Session directory" HTML documentation for additional details
about the PRRTE session directory.
#
[leave-session-attached]

Do not discard stdout/stderr of remote PRRTE daemons. The primary use
for this option is to ensure that the daemon output streams (i.e.,
stdout and stderr) remain open after launch, thus allowing the user to
see any daemon-generated error messages. Otherwise, the daemon will
"daemonize" itself upon launch, thereby closing its output streams.
#
[prefix]

Prefix to be used to look for PRRTE executables. PRRTE automatically
sets the prefix for remote daemons if it was either configured with the
"--enable-prte-prefix-by-default" option OR prte itself was executed
with an absolute path to the prte command. This option overrides those
settings, if present, and forces use of the provided path.
#
[noprefix]

Disable automatic "--prefix" behavior. PRRTE automatically sets the
prefix for remote daemons if it was either configured with the
"--enable-prte-prefix-by-default" option OR prte itself was executed
with an absolute path to the "prte" command. This option disables that
behavior.
#
[pmix-prefix]

Prefix to be used by a PRRTE executable to look for its PMIx
installation on remote nodes. This is the location of the top-level
directory for the installation. If the installation has not been moved,
it would be the value given to "--prefix" when the installation was
configured.

Note that PRRTE cannot determine the exact name of the library
subdirectory under this location. For example, some systems will call it
"lib" while others call it "lib64". Accordingly, PRRTE will use the
library subdirectory name of the PMIx installation used to build PRRTE.
#
[forward-signals]

Comma-delimited list of the signals (names or integers) to be forwarded
to application processes ("none" = forward nothing).

The list *replaces* the default set rather than adding to it, so it
names every signal that is to be forwarded. The default set, used when
this option is not given, is SIGTSTP, SIGUSR1, SIGUSR2, SIGABRT,
SIGALRM, and SIGCONT.
#
[allow-run-as-root]

Allow execution as root **(STRONGLY DISCOURAGED)**.

Running as root exposes the user to potentially catastrophic file system
corruption and damage — e.g., if the user accidentally points the root
of the session directory to a system required point, this directory and
all underlying elements will be deleted upon job completion, thereby
rendering the system inoperable.

It is recognized that some environments (e.g., containers) may require
operation as root, and that the user accepts the risks in those
scenarios. Accordingly, one can override PRRTE's run-as-root protection
by providing one of the following:

* The "--allow-run-as-root" command line directive

* Adding **BOTH** of the following environmental parameters:

    * "PRTE_ALLOW_RUN_AS_ROOT=1"
    * "PRTE_ALLOW_RUN_AS_ROOT_CONFIRM=1"

Again, we recommend this only be done if absolutely necessary.
#
[no-aggregate-help]

Do not aggregate help output from multiple processes. PRRTE defaults
to aggregating messages generated by its "help" subsystem so that only
one is printed out per topic (along with the number of processes that
reported the same issue). This is done to avoid users receiving a
flood of one-per-process error messages, all containing the identical
error report.  Setting this option turns off the aggregation, thereby
allowing the user to see duplicate reports from multiple processes.
#
[timeout]

Timeout DVM startup if time exceeds the specified number of seconds.
The DVM startup will abort after the specified interval.
#
[x]

Export an environment variable, optionally specifying a value. For
example:

* "-x foo" exports the environment variable "foo" and takes its value
  from the current environment.

* "-x foo=bar" exports the environment variable name "foo" and sets its
  value to "bar" in the started processes.

* "-x foo*" exports all current environmental variables starting with
  "foo".
#
[hostfile]

#include#help-hostfile.txt#dvm-hostfile

#
[machinefile]

#include#help-hostfile.txt#machinefile

#
[host]

#include#help-hostfile.txt#host

#
[display]

#include#help-schizo-display.txt#display

#
[runtime-options]

#include#help-schizo-rtos.txt#runtime-options

#
[rtos]

#include#help-schizo-rtos.txt#rtos

#
[bad-singleton]
%s was given a malformed singleton identifier:

  Identifier: %s

The value of the "--singleton" option must have the form

  <namespace>.<rank>

for example, "myapp.0". Please correct the identifier and try again.
