# -*- text -*-
#
# Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
# Copyright (c) 2022      IBM Corporation.  All rights reserved.
# $COPYRIGHT$
#
# Additional copyrights may follow
#
# $HEADER$
#
#
[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      *****/

-h|--help                            This help message
-h|--help <arg0>                     Help for the specified option
-v|--verbose                         Enable typical debug options
-V|--version                         Print version and exit


/*****       Debug Options       *****/

   --debug-daemons                   Debug daemons - if not set, any "verbose" settings will be limited to
                                     the prterun itself to reduce clutter
   --debug-daemons-file              Enable debugging of any PRRTE daemons used by this application, storing
                                     their verbose output in files
   --display <arg0>                  Options for displaying information about the allocation and job.
   --spawn-timeout <arg0>            Timeout the job if spawn takes more than the specified number of seconds
   --timeout <arg0>                  Timeout the job if execution is not complete after the specified
                                     number of seconds
   --get-stack-traces                Get stack traces of all application procs on timeout
   --leave-session-attached          Do not discard stdout/stderr of remote PRRTE daemons
   --report-state-on-timeout         Report all job and process states upon timeout
   --stop-on-exec                    If supported, stop each specified process at start of execution
   --stop-in-init                    Direct the specified processes to stop in PMIx_Init
   --stop-in-app                     Direct the specified processes to stop at an application-controlled location
   --test-suicide <arg0>             Direct that the specified daemon suicide after delay
   --do-not-launch                   Perform all necessary operations to prepare to launch the application,
                                     but do not actually launch it (usually used to test mapping patterns)



/*****      Output Options       *****/

   --output <arg0>                   Comma-delimited list of options that control how output is
                                     generated.
   --report-child-jobs-separately    Return the exit status of the primary job only
   --xterm <arg0>                    Create a new xterm window for each of the comma-delimited ranges
                                     of application process ranks



/*****       Input Options       *****/

   --stdin <arg0>                    Specify application rank(s) to receive stdin [rank, all, none]
                                     (default: 0, indicating rank 0)



/*****      Placement Options      *****/

   --map-by <arg0>                   Mapping Policy for job
   --rank-by <arg0>                  Ranking Policy for job
   --bind-to <arg0>                  Binding policy for job.



/*****      Launch Options       *****/
   --runtime-options <arg0>          Comma-delimited list of runtime directives for the job (e.g., do not
                                     abort if a process exits on non-zero status)
-c|--np <arg0>                       Number of processes to run
-n|--n <arg0>                        Number of processes to run
-N|--npernode <arg0>                 Run designated number of processes on each node
   --personality <arg0>              Specify the personality to be used
-H|--host <arg0>                     List of hosts to invoke processes on
   --hostfile <arg0>                 Provide a hostfile
   --machinefile <arg0>              Provide a hostfile (synonym for hostfile)
   --pmixmca <arg0> <arg1>           Pass context-specific PMIx MCA parameters; they are considered global if
                                     only one context is specified (arg0 is the parameter name; arg1 is the parameter value)
   --gpmixmca <arg0> <arg1>          Pass global PMIx MCA parameters that are applicable to all contexts (arg0
                                     is the parameter name; arg1 is the parameter value)
   --preload-files <arg0>            Preload the comma separated list of files to the remote machines current
                                     working directory before starting the remote process.
   --prtemca <arg0> <arg1>           Pass context-specific PRRTE MCA parameters to the DVM
   --pset <arg0>                     User-specified name assigned to the processes in their given application
-s|--preload-binary                  Preload the binary on the remote machine before starting the remote
                                     process.
   --set-cwd-to-session-dir          Set the working directory of the started processes to their session
                                     directory
   --show-progress                   Output a brief periodic report on launch progress
   --wd <arg0>                       Synonym for --wdir
   --wdir <arg0>                     Set the working directory of the started processes
-x <arg0>                            Export an environment variable, optionally specifying a value


/*****    Specific Options   *****/

   --allow-run-as-root               Allow execution as root (STRONGLY DISCOURAGED)
   --daemonize                       Daemonize the prterun and its daemons into the background
   --forward-signals <arg0>          Comma-delimited list of additional signals (names or integers) to forward
                                     to application processes ["none" => forward nothing].
   --keepalive <arg0>                Pipe to monitor - DVM will terminate upon closure
   --launch-agent <arg0>             Name of daemon executable used to start processes on remote nodes
                                     (default: prted)
   --max-vm-size <arg0>              Number of daemons to start
   --no-ready-msg                    Do not print a DVM ready message
   --noprefix                        Disable automatic --prefix behavior
   --prefix <arg0>                   Prefix to be used to look for RTE executables
   --report-pid <arg0>               Printout pid on stdout [-], stderr [+], or a file [anything else]
   --report-uri <arg0>               Printout URI on stdout [-], stderr [+], or a file [anything else]
   --set-sid                         Direct the DVM daemons to separate from the current session
   --singleton <arg0>                ID of the singleton process that started us
   --tmpdir <arg0>                   Set the root for the session directory tree
   --tune <arg0>                     File(s) containing MCA params for tuning DVM operations
   --dvm  <arg0>                     Use a persistent DVM instead of instantiating independent runtime
                                     infrastructure. The argument indicates the pid, uri,
                                     file containing the uri, or namespace of the DVM.

Report bugs to %s
#
[dvm]
Utilize an existing persistent DVM instead of instantiating an
independent runtime infrastructure. This mimics the "prun" command,
but is provided as a convenience option for those wanting to embed
the "prterun" command in a script that can be optionally used to
run either independently or under a persistent DVM.

#include#help-schizo-cli#dvm
#
[prtemca]
#include#help-schizo-cli#prtemca
#
[pmixmca]
#include#help-schizo-cli#pmixmca
#
[gpmixmca]
Syntax: --gpmixmca <arg0> <arg1>
where arg0 is the parameter name and arg1 is the parameter value. The "g" prefix
indicates that this PMIx parameter is to be applied to _all_ application contexts and
not just the one in which the directive appears.
#
[tune]
#include#help-schizo-cli#tune
#
[daemonize]
Daemonize the prterun and the DVM daemons into the background
#
[system-server]
Start prterun 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]
Printout prterun's PID on stdout [-], stderr [+], or a file [anything else]
#
[report-uri]
Printout prterun's URI on stdout [-], stderr [+], or a file [anything else]
#
[test-suicide]
Test DVM cleanup upon daemon failure by having one daemon suicide after delay
#
[singleton]
prterun is being started by a singleton process (i.e., one not started by prterun) - the
argument must be the PMIx ID of the singleton process that started us
#
[keepalive]
Pipe for prterun to monitor - job will terminate upon closure
#
[launch-agent]
Name of daemon executable used to start processes on remote nodes (default: prted).
This is the executable prterun shall start on each remote node when establishing the DVM.
#
[max-vm-size]
Maximum number of daemons to start
#
[debug-daemons]
#include#help-schizo-cli#debug-daemons
#
[debug-daemons-file]
#include#help-schizo-cli#debug-daemons-file
#
[leave-session-attached]
#include#help-schizo-cli#leave-session-attached
#
[tmpdir]
Define the root location for the PRRTE session directory tree

#include#help-schizo-cli#tmpdir
#
[prefix]
#include#help-schizo-cli#prefix
#
[noprefix]
#include#help-schizo-cli#no-prefix
#
[forward-signals]
#include#help-schizo-cli#forward-signals
#
[allow-run-as-root]
#include#help-schizo-cli#allow-run-as-root
#
[report-child-jobs-separately]
Return the exit status of the primary job only
#
[timeout]
Timeout the job if execution time exceeds the specified number of seconds
#
[report-state-on-timeout]
Report all job and process states upon timeout
#
[get-stack-traces]
Get stack traces of all application procs on timeout
#
[spawn-timeout]
Timeout the job if spawn takes more than the specified number of seconds
#
[np]
Specify number of application processes to be started
#
[n]
Specify number of application processes to be started
#
[N]
Specify number of application processes per node to be started
#
[app]
Provide an appfile; ignore all other command line options
#
[xterm]
Create a new xterm window and display output from the specified ranks there.
Ranks are specified as a comma-delimited list of ranges - e.g., "1,3-6,9",
or as "all"."
#
[stop-on-exec]
If supported, stop each process at start of execution
#
[stop-in-init]
Include the PMIX_DEBUG_STOP_IN_INIT attribute in the application's
job info directing that the specified ranks stop in PMIx_Init pending
release. Ranks are specified as a comma-delimited list of ranges - e.g., "1,3-6,9",
or as "all".
#
[stop-in-app]
Include the PMIX_DEBUG_STOP_IN_APP attribute in the application's
job info directing that the specified ranks stop at an application-determined
point pending release. Ranks are specified as a comma-delimited list of
ranges - e.g., "1,3-6,9", or as "all".
#
[x]
#include#help-schizo-cli#x
#
[wdir]
Set the working directory of the started processes
#
[wd]
Synonym for --wdir
#
[set-cwd-to-session-dir]
Set the working directory of the started processes to their session directory
#
[path]
PATH to be used to look for executables to start processes
#
[show-progress]
Output a brief periodic report on launch progress
#
[pset]
User-specified name assigned to the processes in their given application
#
[hostfile]
#include#help-schizo-cli#launcher-hostfile
#
[machinefile]
Provide a hostfile (synonym for "hostfile")

#include#help-schizo-cli#launcher-hostfile
#
[host]
#include#help-schizo-cli#dash-host

#include#help-schizo-cli#relative-indexing
#
[personality]
#include#help-schizo-cli#personality
#
[preload-files]
Syntax: --preload-files <arg0>

Preload the comma separated list of files to the remote machines current
working directory before starting the remote process.
#
[preload-binary]
Syntax: --preload-binary

Preload the binary on the remote machine before starting the
remote process.
#
[output]
#include#help-schizo-cli#output
#
[stdin]
Specify procs to receive stdin [rank, "all", "none"] (default: 0, indicating rank 0)
#
[map-by]
#include#help-prte-rmaps-base#map-by-option
#
[rank-by]
#include#help-prte-rmaps-base#rank-by-option
#
[bind-to]
#include#help-prte-hwloc-base#bind-to-option
#
[runtime-options]
#include#help-schizo-cli#runtime-options
#
[rankfile]
Name of file to specify explicit task mapping
#
[placement]
#include#help-prte-rmaps-base#placement
#
[placement-examples]
#include#help-prte-rmaps-base#placement-examples
#
[placement-all]
#include#help-prte-rmaps-base#placement-all
#
[placement-fundamentals]
#include#help-prte-rmaps-base#placement-fundamentals
#
[placement-limits]
#include#help-prte-rmaps-base#placement-limits
#
[placement-diagnostics]
#include#help-prte-rmaps-base#placement-diagnostics
#
[placement-rankfiles]
#include#help-prte-rmaps-base#placement-rankfiles
#
[placement-deprecated]
#include#help-prte-rmaps-base#placement-deprecated
#
[display]
#include#help-schizo-cli#display
#
[do-not-launch]
Perform all necessary operations to prepare to launch the application, but do not actually
launch it (usually used to test mapping patterns)
#
#
#  DEPRECATED OPTIONS
#
[mca]
#include#help-schizo-deprecated#mca
#
[gmca]
#include#help-schizo-deprecated#gmca
#
[xml]
#include#help-schizo-deprecated#xml
#
[tag-output]
#include#help-schizo-deprecated#tag-output
#
[timestamp-output]
#include#help-schizo-deprecated#timestamp-output
#
[output-directory]
#include#help-schizo-deprecated#output-directory
#
[output-filename]
#include#help-schizo-deprecated#output-filename
#
[merge-stderr-to-stdout]
#include#help-schizo-deprecated#merge-stderr-to-stdout
#
[display-devel-map]
#include#help-schizo-deprecated#display-devel-map
#
[display-topo]
#include#help-schizo-deprecated#display-topo
#
[report-bindings]
#include#help-schizo-deprecated#report-bindings
#
[display-devel-allocation]
#include#help-schizo-deprecated#display-devel-allocation
#
[display-map]
#include#help-schizo-deprecated#display-map
#
[display-allocation]
#include#help-schizo-deprecated#display-allocation
#
