From 15802338ab2266cc32828550cddfa03273e5e88e Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Sun, 22 Sep 2024 15:46:17 -0600 Subject: [PATCH] Always have show-help text available Remove the generation (by Sphinx) of the show-help text and just maintain it as text. Telling users show-help isn't available just because Sphinx isn't around is unfriendly - and we really don't get much benefit from keeping show-help source in rst. Signed-off-by: Ralph Castain (cherry picked from commit 772e1ac2ed2f7623a32230d4bc5f8defb6d41bc3) --- configure.ac | 1 - src/docs/Makefile.am | 47 +- src/docs/show-help-files/.gitignore | 3 - src/docs/show-help-files/Makefile.am | 121 - .../show-help-files/build-dummy-ini-files.py | 82 - src/docs/show-help-files/conf.py | 1 - src/docs/show-help-files/help-cli.rst | 129 - src/docs/show-help-files/help-cli.txt | 101 + src/docs/show-help-files/help-dash-host.rst | 96 - src/docs/show-help-files/help-dash-host.txt | 68 + src/docs/show-help-files/help-errmgr-base.txt | 117 + src/docs/show-help-files/help-ess-base.txt | 99 + src/docs/show-help-files/help-hostfile.rst | 272 -- src/docs/show-help-files/help-hostfile.txt | 196 ++ src/docs/show-help-files/help-iof-base.txt | 32 + src/docs/show-help-files/help-oob-base.txt | 24 + src/docs/show-help-files/help-oob-tcp.txt | 139 + src/docs/show-help-files/help-plm-base.txt | 177 ++ src/docs/show-help-files/help-plm-slurm.txt | 138 + src/docs/show-help-files/help-plm-ssh.txt | 98 + .../show-help-files/help-prte-filem-raw.txt | 49 + ...wloc-base.rst => help-prte-hwloc-base.txt} | 54 +- src/docs/show-help-files/help-prte-info.rst | 158 - src/docs/show-help-files/help-prte-info.txt | 140 + .../show-help-files/help-prte-odls-base.txt | 104 + .../help-prte-odls-default.txt | 141 + .../show-help-files/help-prte-rmaps-base.txt | 831 +++++ .../show-help-files/help-prte-rmaps-ppr.txt | 71 + .../show-help-files/help-prte-rmaps-rr.txt | 91 + .../show-help-files/help-prte-rmaps-seq.txt | 78 + .../show-help-files/help-prte-rtc-base.txt | 288 ++ .../show-help-files/help-prte-rtc-hwloc.txt | 31 + .../show-help-files/help-prte-runtime.rst | 188 -- .../show-help-files/help-prte-runtime.txt | 146 + src/docs/show-help-files/help-prte-util.rst | 156 - src/docs/show-help-files/help-prte-util.txt | 123 + src/docs/show-help-files/help-prte.rst | 333 -- src/docs/show-help-files/help-prte.txt | 668 +++++ src/docs/show-help-files/help-prted.rst | 318 -- src/docs/show-help-files/help-prted.txt | 276 ++ src/docs/show-help-files/help-prterun.rst | 678 ----- src/docs/show-help-files/help-prterun.txt | 2669 +++++++++++++++++ src/docs/show-help-files/help-prun.rst | 1022 ------- src/docs/show-help-files/help-prun.txt | 1652 ++++++++++ src/docs/show-help-files/help-psched.rst | 178 -- src/docs/show-help-files/help-psched.txt | 318 ++ src/docs/show-help-files/help-pterm.rst | 137 - src/docs/show-help-files/help-pterm.txt | 119 + src/docs/show-help-files/help-ras-base.txt | 64 + src/docs/show-help-files/help-ras-pbs.txt | 43 + .../show-help-files/help-ras-simulator.txt | 35 + src/docs/show-help-files/help-ras-slurm.txt | 81 + src/docs/show-help-files/help-regex.rst | 110 - .../show-help-files/help-rmaps_rank_file.txt | 104 + src/docs/show-help-files/help-schizo-base.txt | 195 ++ src/docs/show-help-files/help-schizo-ompi.txt | 471 +++ src/docs/show-help-files/help-schizo-srun.txt | 273 ++ src/docs/show-help-files/help-state-base.txt | 42 + src/docs/show-help-files/index.rst | 38 - src/docs/show-help-files/prrte-rst-content | 1 - src/docs/show-help-files/requirements.txt | 1 - 61 files changed, 10348 insertions(+), 4068 deletions(-) delete mode 100644 src/docs/show-help-files/.gitignore delete mode 100644 src/docs/show-help-files/Makefile.am delete mode 100755 src/docs/show-help-files/build-dummy-ini-files.py delete mode 120000 src/docs/show-help-files/conf.py delete mode 100644 src/docs/show-help-files/help-cli.rst create mode 100644 src/docs/show-help-files/help-cli.txt delete mode 100644 src/docs/show-help-files/help-dash-host.rst create mode 100644 src/docs/show-help-files/help-dash-host.txt create mode 100644 src/docs/show-help-files/help-errmgr-base.txt create mode 100644 src/docs/show-help-files/help-ess-base.txt delete mode 100644 src/docs/show-help-files/help-hostfile.rst create mode 100644 src/docs/show-help-files/help-hostfile.txt create mode 100644 src/docs/show-help-files/help-iof-base.txt create mode 100644 src/docs/show-help-files/help-oob-base.txt create mode 100644 src/docs/show-help-files/help-oob-tcp.txt create mode 100644 src/docs/show-help-files/help-plm-base.txt create mode 100644 src/docs/show-help-files/help-plm-slurm.txt create mode 100644 src/docs/show-help-files/help-plm-ssh.txt create mode 100644 src/docs/show-help-files/help-prte-filem-raw.txt rename src/docs/show-help-files/{help-prte-hwloc-base.rst => help-prte-hwloc-base.txt} (72%) delete mode 100644 src/docs/show-help-files/help-prte-info.rst create mode 100644 src/docs/show-help-files/help-prte-info.txt create mode 100644 src/docs/show-help-files/help-prte-odls-base.txt create mode 100644 src/docs/show-help-files/help-prte-odls-default.txt create mode 100644 src/docs/show-help-files/help-prte-rmaps-base.txt create mode 100644 src/docs/show-help-files/help-prte-rmaps-ppr.txt create mode 100644 src/docs/show-help-files/help-prte-rmaps-rr.txt create mode 100644 src/docs/show-help-files/help-prte-rmaps-seq.txt create mode 100644 src/docs/show-help-files/help-prte-rtc-base.txt create mode 100644 src/docs/show-help-files/help-prte-rtc-hwloc.txt delete mode 100644 src/docs/show-help-files/help-prte-runtime.rst create mode 100644 src/docs/show-help-files/help-prte-runtime.txt delete mode 100644 src/docs/show-help-files/help-prte-util.rst create mode 100644 src/docs/show-help-files/help-prte-util.txt delete mode 100644 src/docs/show-help-files/help-prte.rst create mode 100644 src/docs/show-help-files/help-prte.txt delete mode 100644 src/docs/show-help-files/help-prted.rst create mode 100644 src/docs/show-help-files/help-prted.txt delete mode 100644 src/docs/show-help-files/help-prterun.rst create mode 100644 src/docs/show-help-files/help-prterun.txt delete mode 100644 src/docs/show-help-files/help-prun.rst create mode 100644 src/docs/show-help-files/help-prun.txt delete mode 100644 src/docs/show-help-files/help-psched.rst create mode 100644 src/docs/show-help-files/help-psched.txt delete mode 100644 src/docs/show-help-files/help-pterm.rst create mode 100644 src/docs/show-help-files/help-pterm.txt create mode 100644 src/docs/show-help-files/help-ras-base.txt create mode 100644 src/docs/show-help-files/help-ras-pbs.txt create mode 100644 src/docs/show-help-files/help-ras-simulator.txt create mode 100644 src/docs/show-help-files/help-ras-slurm.txt delete mode 100644 src/docs/show-help-files/help-regex.rst create mode 100644 src/docs/show-help-files/help-rmaps_rank_file.txt create mode 100644 src/docs/show-help-files/help-schizo-base.txt create mode 100644 src/docs/show-help-files/help-schizo-ompi.txt create mode 100644 src/docs/show-help-files/help-schizo-srun.txt create mode 100644 src/docs/show-help-files/help-state-base.txt delete mode 100644 src/docs/show-help-files/index.rst delete mode 120000 src/docs/show-help-files/prrte-rst-content delete mode 120000 src/docs/show-help-files/requirements.txt diff --git a/configure.ac b/configure.ac index 335628c918..a0f396e9a4 100644 --- a/configure.ac +++ b/configure.ac @@ -1019,7 +1019,6 @@ AC_CONFIG_FILES([ include/prte_version.h docs/Makefile src/docs/Makefile - src/docs/show-help-files/Makefile src/docs/prrte-rst-content/Makefile ]) diff --git a/src/docs/Makefile.am b/src/docs/Makefile.am index 1826b6e290..5abad91a24 100644 --- a/src/docs/Makefile.am +++ b/src/docs/Makefile.am @@ -1,7 +1,7 @@ # # Copyright (c) 2022-2023 Cisco Systems, Inc. All rights reserved. # Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. -# Copyright (c) 2023 Nanook Consulting. All rights reserved. +# Copyright (c) 2023-2024 Nanook Consulting All rights reserved. # # $COPYRIGHT$ # @@ -10,6 +10,47 @@ # $HEADER$ # +dist_prtedata_DATA = \ + show-help-files/help-cli.txt \ + show-help-files/help-dash-host.txt \ + show-help-files/help-errmgr-base.txt \ + show-help-files/help-ess-base.txt \ + show-help-files/help-hostfile.txt \ + show-help-files/help-iof-base.txt \ + show-help-files/help-oob-base.txt \ + show-help-files/help-oob-tcp.txt \ + show-help-files/help-plm-base.txt \ + show-help-files/help-plm-slurm.txt \ + show-help-files/help-plm-ssh.txt \ + show-help-files/help-prte-filem-raw.txt \ + show-help-files/help-prte-hwloc-base.txt \ + show-help-files/help-prte-info.txt \ + show-help-files/help-prte-odls-base.txt \ + show-help-files/help-prte-odls-default.txt \ + show-help-files/help-prte-rmaps-base.txt \ + show-help-files/help-prte-rmaps-ppr.txt \ + show-help-files/help-prte-rmaps-seq.txt \ + show-help-files/help-prte-rtc-base.txt \ + show-help-files/help-prte-rtc-hwloc.txt \ + show-help-files/help-prte-runtime.txt \ + show-help-files/help-prte-util.txt \ + show-help-files/help-prte.txt \ + show-help-files/help-prted.txt \ + show-help-files/help-prterun.txt \ + show-help-files/help-prun.txt \ + show-help-files/help-psched.txt \ + show-help-files/help-pterm.txt \ + show-help-files/help-ras-base.txt \ + show-help-files/help-ras-pbs.txt \ + show-help-files/help-ras-simulator.txt \ + show-help-files/help-ras-slurm.txt \ + show-help-files/help-rmaps_rank_file.txt \ + show-help-files/help-schizo-base.txt \ + show-help-files/help-schizo-ompi.txt \ + show-help-files/help-schizo-srun.txt \ + show-help-files/help-state-base.txt + + + SUBDIRS = \ - prrte-rst-content \ - show-help-files + prrte-rst-content diff --git a/src/docs/show-help-files/.gitignore b/src/docs/show-help-files/.gitignore deleted file mode 100644 index a786516d7e..0000000000 --- a/src/docs/show-help-files/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -_build -cli-*.rst -deprecated-*.rst diff --git a/src/docs/show-help-files/Makefile.am b/src/docs/show-help-files/Makefile.am deleted file mode 100644 index 934a41dc28..0000000000 --- a/src/docs/show-help-files/Makefile.am +++ /dev/null @@ -1,121 +0,0 @@ -# -# Copyright (c) 2022-2023 Cisco Systems, Inc. All rights reserved. -# Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. -# Copyright (c) 2023-2024 Nanook Consulting All rights reserved. -# -# $COPYRIGHT$ -# -# Additional copyrights may follow -# -# $HEADER$ -# - -# We need this Makefile to be executed serially. Below, we list all -# the man pages as the targets of the rule that invokes Sphinx for -# dependency/generation reasons. But a *single* execution of the make -# target will generate *all* of the man pages and HTML files. Hence, -# when "make" determines that none of the man page files exist, it -# should execute the Sphinx-invocation rule once, and then it will -# realize that all the man pages files exist. More specifically: if -# someone invokes "make -j N", we need make to not execute the -# Sphinx-invocation rule multiple times simultaneously. Both GNU Make -# and BSD Make will honor the .NOTPARALLEL target to disable all -# parallel invocation in this Makefile[.am]. -# -# Note that even though we explicitly disable make's parallelism, -# we'll use Sphinx's internal parallelism via "-j auto" -- see -# SPHINX_OPTS. -.NOTPARALLEL: - -OUTDIR = _build -SPHINX_CONFIG = conf.py -SPHINX_OPTS ?= -W --keep-going -j auto - -# All RST source files, including those that are not installed -RST_SOURCE_FILES = \ - $(srcdir)/prrte-rst-content/*.rst \ - $(srcdir)/index.rst \ - $(srcdir)/help-prte-info.rst \ - $(srcdir)/help-prte.rst \ - $(srcdir)/help-prted.rst \ - $(srcdir)/help-prterun.rst \ - $(srcdir)/help-prun.rst \ - $(srcdir)/help-pterm.rst \ - $(srcdir)/help-cli.rst \ - $(srcdir)/help-dash-host.rst \ - $(srcdir)/help-hostfile.rst \ - $(srcdir)/help-prte-hwloc-base.rst \ - $(srcdir)/help-prte-runtime.rst \ - $(srcdir)/help-prte-util.rst - -TXT_OUTDIR = $(OUTDIR)/text - -# These files are the ones that are built that we care about (Sphinx -# will emit lots of files in the TXT_OUTDIR; these are the only ones -# that we care about). -ALL_TXT_BUILT = \ - $(TXT_OUTDIR)/help-prte-info.txt \ - $(TXT_OUTDIR)/help-prte.txt \ - $(TXT_OUTDIR)/help-prted.txt \ - $(TXT_OUTDIR)/help-prterun.txt \ - $(TXT_OUTDIR)/help-prun.txt \ - $(TXT_OUTDIR)/help-pterm.txt \ - $(TXT_OUTDIR)/help-cli.txt \ - $(TXT_OUTDIR)/help-dash-host.txt \ - $(TXT_OUTDIR)/help-hostfile.txt \ - $(TXT_OUTDIR)/help-prte-hwloc-base.txt \ - $(TXT_OUTDIR)/help-prte-runtime.txt \ - $(TXT_OUTDIR)/help-prte-util.txt - -#------------------- - -EXTRA_DIST = \ - requirements.txt \ - $(SPHINX_CONFIG) \ - $(RST_SOURCE_FILES) \ - $(TXT_OUTDIR) - -########################################################################### - -include $(top_srcdir)/Makefile.prte-rules - -# We do not specifically compute or list the RST file dependencies. -# Instead, because Sphinx will do this computation by itself, we just -# say "all Sphinx output is dependent upon all RST input files" here -# in the Makefile. If any of the input RST files are edited, this -# will cause "make" to invoke Sphinx and let it re-generate whatever -# output files need to be re-generated. -# -# Hence, we use a single sentinel file here in the Makefile to -# represent all Sphinx output files. -TXT_SENTINEL_OUTPUT = $(TXT_OUTDIR)/index.txt -$(ALL_TXT_BUILT): $(TXT_SENTINEL_OUTPUT) - -$(TXT_SENTINEL_OUTPUT): $(RST_SOURCE_FILES) -$(TXT_SENTINEL_OUTPUT): $(SPHINX_CONFIG) - -# Technically, we always build the docs files if they're missing -# (e.g., in a git clone). The "PRTE_BUILD_DOCS" conditional really -# refers to whether we have Sphinx or not. -# -# If we have Sphinx, use it to build. -# -# If we do not have Sphinx, then build dummy help files that say "you -# don't have Sphinx, so you didn't get proper help files" files, just -# so that it's obvious as to why you don't have proper help files. -$(TXT_SENTINEL_OUTPUT): -if PRTE_BUILD_DOCS - $(PRTE_V_TXT) $(SPHINX_BUILD) -M text "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS) -else !PRTE_BUILD_DOCS - $(PRTE_V_TXT) \ - $(PYTHON) $(srcdir)/build-dummy-ini-files.py $(TXT_OUTDIR) $(ALL_TXT_BUILT); \ - touch $(TXT_SENTINEL_OUTPUT) -endif !PRTE_BUILD_DOCS - -maintainer-clean-local: - $(SPHINX_BUILD) -M clean "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS) - -########################################################################### - -# Install the generated text files -dist_prtedata_DATA = $(ALL_TXT_BUILT) diff --git a/src/docs/show-help-files/build-dummy-ini-files.py b/src/docs/show-help-files/build-dummy-ini-files.py deleted file mode 100755 index e5ab6d9f55..0000000000 --- a/src/docs/show-help-files/build-dummy-ini-files.py +++ /dev/null @@ -1,82 +0,0 @@ -#!/usr/bin/env python -# -# Copyright 2023 Jeffrey M. Squyres. All rights reserved. -# -# Copyright (c) 2023-2024 Nanook Consulting All rights reserved. -# $COPYRIGHT$ -# -# Additional copyrights may follow -# -# $HEADER$ - -# Trivial script to scrape section names from source .rst files and -# generate dummy show_help-style text files. We only use this script -# a) if the show_help files are not available (i.e., in a git clone), -# and b) if Sphinx is not available. -# -# We generate these show_help files (as opposed to generating a run -# time error when the show_help file is unavailable) just so that it's -# 100% obvious that you're not getting proper help files because you -# did not have Sphinx available. - -# Intentionally use a minimal set of Python modules (to decrease any -# needed dependencies). - -import re -import os -import sys - -# Pop the executable name -exe = sys.argv.pop(0) -abs_srcdir = os.path.abspath(os.path.dirname(exe)) - -# First argument is the text outdir (in the build tree). -outdir = sys.argv.pop(0) -outdir_len = len(outdir) + 1 - -# The rest of the arguments are the text filenames to build. -for outfile in sys.argv: - - # The filenames all have the outdir prefix. We find the - # correspoding source .rst file by stripping that prefix off and - # adding the srcdir prefix to it. - # - # We do this instead of using os.path.basename() because some - # files have subdirectory names in them (e.g., - # "mca/help-something.txt"). - txt_filename = outfile[outdir_len:] - - # Replace the .txt with .rst, and add the srcdir prefix. - rst_filename = txt_filename.replace(".txt", ".rst") - srcfile = os.path.join(abs_srcdir, rst_filename) - - # Read in the source file - with open(srcfile) as fp: - src_rst = fp.readlines() - - # Find all the "[section]" lines. - sections = list() - for line in src_rst: - match = re.search(r"\s*\[(.+)\]\s*$", line) - if match: - sections.append(match.group(1)) - - # Ensure the out directory exists - full_outdir = os.path.abspath(os.path.dirname(outfile)) - if not os.path.exists(full_outdir): - # Use older form of os.mkdirs (without the exist_ok param) to - # make this script runnable in as many environments as - # possible. - os.makedirs(full_outdir) - - try: - # Write the output file - with open(outfile, 'w') as fp: - for section in sections: - # Use Python 2-friendly formatting for environments where - # we don't have Python 3 (!). - fp.write("""[{}] - This help section is empty because PRRTE was built without Sphinx.\n""".format(section)) - except Exception as e: - print("ERROR: {}".format(e)) - pass diff --git a/src/docs/show-help-files/conf.py b/src/docs/show-help-files/conf.py deleted file mode 120000 index cb9acdea07..0000000000 --- a/src/docs/show-help-files/conf.py +++ /dev/null @@ -1 +0,0 @@ -../../../docs/conf.py \ No newline at end of file diff --git a/src/docs/show-help-files/help-cli.rst b/src/docs/show-help-files/help-cli.rst deleted file mode 100644 index 99817b2ce2..0000000000 --- a/src/docs/show-help-files/help-cli.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. Copyright (c) 2009-2020 Cisco Systems, Inc. All rights reserved - Copyright (c) 2017-2020 Intel, Inc. All rights reserved. - Copyright (c) 2022 Nanook Consulting. All rights reserved. - Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. - $COPYRIGHT$ - - Additional copyrights may follow - - $HEADER$ - - This is the US/English general help file for PRTE CLI options. - -[bogus section] - -This section is not used by PRTE code. But we have to put a RST -section title in this file somewhere, or Sphinx gets unhappy. So we -put it in a section that is ignored by PRTE code. - -Hello, world ------------- - -[help] - -Help can be requested in three ways: - -#. A directive to the cmd. For example, the command - - .. code:: - - "%s --help" or "%s -h" - - will provide the high-level help output giving a general - description of each available option. - -#. An option to the help directive. For example, the command - - .. code:: - - "%s --help foo" or "%s -h foo" - - will provide detailed help about the ``foo`` command line - directive. - -#. Specifying "help" as an option to the directive of interest. - For example, the command - - .. code:: - - "%s --foo --help" or "%s --foo -h" - - will provide detailed help about the "foo" command line - directive. Note that the "help" and "h" options do not require the - dash prefixes |mdash| i.e., the following commands - - .. code:: - - "%s --foo help" or "%s --foo h" - - will also output detailed help for ``foo``. Thus, directives are - precluded from defining options of ``help`` and ``h``. - -Note that the last two methods are functionally equivalent -and will return the same output. - -[unknown-option] - -Help was requested for an unknown option: - -.. code:: - - Option: %s - -Please use the ``%s --help`` command to obtain a list of all -supported options. - -[unrecognized-option] - -The help system for %s does not recognize the following: - -.. code:: - - Option: %s - -This might require help from the developers. - -[version] - -Print version and exit - -[verbose] - -Enable debug options - number of times specified sets level of verbosity -(e.g., ``-vvv`` => 3rd level of debug information) - -[quiet] - -Suppress helpful messages - -[parsable] - -When used in conjunction with other parameters, output information -(e.g., help messages) is displayed in a machine-parsable format - -[parseable] - -When used in conjunction with other parameters, the output information -(e.g., help messages) is displayed in a machine-parsable format - -[short-no-long] - -A short option was provided to %s and recognized by the parser, -but has no matching long option: - -.. code:: - - Short option: %s - -This might require help from the developers. - -[unregistered-option] - -An unrecognized option was included on the %s command line: - -.. code:: - - Option: %s - -Please use the ``%s --help`` command to obtain a list of all -supported options. diff --git a/src/docs/show-help-files/help-cli.txt b/src/docs/show-help-files/help-cli.txt new file mode 100644 index 0000000000..25811c6fa3 --- /dev/null +++ b/src/docs/show-help-files/help-cli.txt @@ -0,0 +1,101 @@ +[bogus section] + +This section is not used by PRTE code. But we have to put a RST +section title in this file somewhere, or Sphinx gets unhappy. So we +put it in a section that is ignored by PRTE code. + + +Hello, world +============ + +[help] + +Help can be requested in three ways: + +1. A directive to the cmd. For example, the command + + "%s --help" or "%s -h" + + will provide the high-level help output giving a general + description of each available option. + +2. An option to the help directive. For example, the command + + "%s --help foo" or "%s -h foo" + + will provide detailed help about the "foo" command line directive. + +3. Specifying "help" as an option to the directive of interest. For + example, the command + + "%s --foo --help" or "%s --foo -h" + + will provide detailed help about the "foo" command line directive. + Note that the "help" and "h" options do not require the dash + prefixes — i.e., the following commands + + "%s --foo help" or "%s --foo h" + + will also output detailed help for "foo". Thus, directives are + precluded from defining options of "help" and "h". + +Note that the last two methods are functionally equivalent and will +return the same output. + +[unknown-option] + +Help was requested for an unknown option: + + Option: %s + +Please use the "%s --help" command to obtain a list of all supported +options. + +[unrecognized-option] + +The help system for %s does not recognize the following: + + Option: %s + +This might require help from the developers. + +[version] + +Print version and exit + +[verbose] + +Enable debug options - number of times specified sets level of +verbosity (e.g., "-vvv" => 3rd level of debug information) + +[quiet] + +Suppress helpful messages + +[parsable] + +When used in conjunction with other parameters, output information +(e.g., help messages) is displayed in a machine-parsable format + +[parseable] + +When used in conjunction with other parameters, the output information +(e.g., help messages) is displayed in a machine-parsable format + +[short-no-long] + +A short option was provided to %s and recognized by the parser, but +has no matching long option: + + Short option: %s + +This might require help from the developers. + +[unregistered-option] + +An unrecognized option was included on the %s command line: + + Option: %s + +Please use the "%s --help" command to obtain a list of all supported +options. diff --git a/src/docs/show-help-files/help-dash-host.rst b/src/docs/show-help-files/help-dash-host.rst deleted file mode 100644 index 64d95814e2..0000000000 --- a/src/docs/show-help-files/help-dash-host.rst +++ /dev/null @@ -1,96 +0,0 @@ -.. Copyright (c) 2004-2006 The Trustees of Indiana University and Indiana - University Research and Technology - Corporation. All rights reserved. - Copyright (c) 2004-2005 The University of Tennessee and The University - of Tennessee Research Foundation. All rights - reserved. - Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, - University of Stuttgart. All rights reserved. - Copyright (c) 2004-2005 The Regents of the University of California. - All rights reserved. - Copyright (c) 2019 Intel, Inc. All rights reserved. - Copyright (c) 2020 Cisco Systems, Inc. All rights reserved - Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. - $COPYRIGHT$ - - Additional copyrights may follow - - $HEADER$ - - This is the US/English general help file for hostfile utilities. - -[bogus section] - -This section is not used by PRTE code. But we have to put a RST -section title in this file somewhere, or Sphinx gets unhappy. So we -put it in a section that is ignored by PRTE code. - -Hello, world ------------- - -[not-all-mapped-alloc] - -At least one of the requested hosts is not included in the current allocation. - -.. code:: - - Missing requested host: %s - -Please check your allocation or your request. - -[dash-host:relative-syntax] - -A relative host was specified, but no prior allocation has been made. -Thus, there is no way to determine the proper host to be used. - -.. code:: - - --host: %s - -Re-run this command with ``--help hosts`` for further information. - -[dash-host:relative-node-not-found] - -A relative host was specified, but was not found. The requested host was -specified with ``--host`` as: - -.. code:: - - Index: %d - Syntax given: %s - -Re-run this command with ``--help hosts`` for further information. - -[dash-host:relative-node-out-of-bounds] - -A relative host was specified, but the index given is beyond the number -of hosts in the current allocation: - -.. code:: - - Index: %d - #hosts: %d - -You could obtain a larger allocation or reduce the relative host index. - -Re-run this command with ``--help hosts`` for further information. - -[dash-host:invalid-relative-node-syntax] - -A relative host was improperly specified |mdash| the value provided was. - -.. code:: - - --host: %s - -You may have forgotten to preface a node with ``N`` or ``n``, or used the -``e`` or ``E`` to indicate empty nodes. - -Re-run this command with ``--help hosts`` for further information. - -[dash-host:not-enough-empty] - -The requested number of empty hosts was not available |mdash| the -system was short by %d hosts. Please recheck your allocation. - -Re-run this command with ``--help hosts`` for further information. diff --git a/src/docs/show-help-files/help-dash-host.txt b/src/docs/show-help-files/help-dash-host.txt new file mode 100644 index 0000000000..5667922110 --- /dev/null +++ b/src/docs/show-help-files/help-dash-host.txt @@ -0,0 +1,68 @@ +[bogus section] + +This section is not used by PRTE code. But we have to put a RST +section title in this file somewhere, or Sphinx gets unhappy. So we +put it in a section that is ignored by PRTE code. + + +Hello, world +============ + +[not-all-mapped-alloc] + +At least one of the requested hosts is not included in the current +allocation. + + Missing requested host: %s + +Please check your allocation or your request. + +[dash-host:relative-syntax] + +A relative host was specified, but no prior allocation has been made. +Thus, there is no way to determine the proper host to be used. + + --host: %s + +Re-run this command with "--help hosts" for further information. + +[dash-host:relative-node-not-found] + +A relative host was specified, but was not found. The requested host +was specified with "--host" as: + + Index: %d + Syntax given: %s + +Re-run this command with "--help hosts" for further information. + +[dash-host:relative-node-out-of-bounds] + +A relative host was specified, but the index given is beyond the +number of hosts in the current allocation: + + Index: %d + #hosts: %d + +You could obtain a larger allocation or reduce the relative host +index. + +Re-run this command with "--help hosts" for further information. + +[dash-host:invalid-relative-node-syntax] + +A relative host was improperly specified — the value provided was. + + --host: %s + +You may have forgotten to preface a node with "N" or "n", or used the +"e" or "E" to indicate empty nodes. + +Re-run this command with "--help hosts" for further information. + +[dash-host:not-enough-empty] + +The requested number of empty hosts was not available — the system was +short by %d hosts. Please recheck your allocation. + +Re-run this command with "--help hosts" for further information. diff --git a/src/docs/show-help-files/help-errmgr-base.txt b/src/docs/show-help-files/help-errmgr-base.txt new file mode 100644 index 0000000000..10b4708e33 --- /dev/null +++ b/src/docs/show-help-files/help-errmgr-base.txt @@ -0,0 +1,117 @@ +# -*- text -*- +# +# Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2005 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2014-2020 Intel, Inc. All rights reserved. +# Copyright (c) 2017 IBM Corporation. All rights reserved. +# Copyright (c) 2018 Research Organization for Information Science +# and Technology (RIST). All rights reserved. +# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved +# Copyright (c) 2022-2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +# +[undeliverable-msg] +An attempt was made to send a message to a process whose +address is unknown: + + Sender: %s + From node: %s + Recipient: %s + On node: %s + +The message could not be delivered, and we are aborting. +# +[failed-daemon-launch] +%s was unable to reliably start one or more daemons. +This usually is caused by: + +* the inability to resolve specified hostnames - please check + above for any output regarding this possibility + +* not finding the required libraries and/or binaries on + one or more nodes. Please check your PATH and LD_LIBRARY_PATH + settings, or configure OMPI with --enable-prun-prefix-by-default + +* lack of authority to execute on one or more specified nodes. + Please verify your allocation and authorities. + +* the inability to write startup files into /tmp (--tmpdir/prte_tmpdir_base). + Please check with your sys admin to determine the correct location to use. + +* compilation of the orted with dynamic libraries when static are required + (e.g., on Cray). Please check your configure cmd line and consider using + one of the contrib/platform definitions for your system type. + +* an inability to create a connection back to mpirun due to a + lack of common network interfaces and/or no route found between + them. Please check network connectivity (including firewalls + and network routing requirements). +# +[failed-daemon] +An PRTE daemon has unexpectedly failed after launch and before +communicating back to mpirun. This could be caused by a number +of factors, including an inability to create a connection back +to mpirun due to a lack of common network interfaces and/or no +route found between them. Please check network connectivity +(including firewalls and network routing requirements). +# +[node-died] +PRTE has lost communication with a remote daemon. + + HNP daemon : %s on node %s + Remote daemon: %s on node %s + +This is usually due to either a failure of the TCP network +connection to the node, or possibly an internal failure of +the daemon itself. We cannot recover from this failure, and +therefore will terminate the job. +# +[no-path] +PRTE does not know how to route a message to the specified daemon +located on the indicated node: + + my node: %s + target node: %s + +This is usually an internal programming error that should be +reported to the developers. In the meantime, a workaround may +be to set the MCA param routed=direct on the command line or +in your environment. We apologize for the problem. +# +[no-connect] +PRTE is unable to establish a communication connection to the +specified daemon located on the indicated node: + + my node: %s + target node: %s + +This is usually due to a lack of common network interfaces and/or +no route found between them. Please check network connectivity (including +firewalls and network routing requirements). If these look okay, +then it could be an internal programming error that should be +reported to the developers. In the meantime, a workaround may +be to set the MCA param routed=direct on the command line or +in your environment. +# +[simple-message] +An internal error has occurred in PRTE: + +%s + +This is something that should be reported to the developers. +# +[normal-termination-but] +%s job %s terminated normally, but %d %s. Per user-direction, the job has been aborted. diff --git a/src/docs/show-help-files/help-ess-base.txt b/src/docs/show-help-files/help-ess-base.txt new file mode 100644 index 0000000000..773dc56b9a --- /dev/null +++ b/src/docs/show-help-files/help-ess-base.txt @@ -0,0 +1,99 @@ +# -*- text -*- +# +# Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2005 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2017-2020 Intel, Inc. All rights reserved. +# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved +# Copyright (c) 2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +# This is the US/English general help file for the SDS base. +# +[ess-base:execv-error] +The singleton application was not able to find the executable "orted" in +your PATH or in the directory where PRTE was initially installed, +and therefore cannot continue. + +For reference, we tried the following command: + + %s + +and got the error %s. + +This could mean that your PATH or executable name is wrong, or that you do not +have the necessary permissions. Please ensure that the executable is able to be +found and executed as it is required for singleton operations. +[ess-base:cannot-forward] +The system does not support trapping and forwarding of the +specified signal: + + signal: %s + param: %s + +Please remove that signal from the ess_base_forward_signals MCA parameter. +[ess-base:unknown-signal] +The following signal was included in the ess_base_forward_signals +MCA parameter: + + signal: %s + param: %s + +This is not a recognized signal value. Please fix or remove it. +# +[slurm-error] +The application appears to have been direct launched using "srun", +but OMPI was not built with SLURM's PMI support and therefore cannot +execute. There are several options for building PMI support under +SLURM, depending upon the SLURM version you are using: + + version 16.05 or later: you can use SLURM's PMIx support. This + requires that you configure and build SLURM --with-pmix. + + Versions earlier than 16.05: you must use either SLURM's PMI-1 or + PMI-2 support. SLURM builds PMI-1 by default, or you can manually + install PMI-2. You must then build PRTE using --with-pmi pointing + to the SLURM PMI library location. + +Please configure as appropriate and try again. +# +[slurm-error2] +The application appears to have been direct launched using "srun", +but OMPI was not built with SLURM support. This usually happens +when OMPI was not configured --with-slurm and we weren't able +to discover a SLURM installation in the usual places. + +Please configure as appropriate and try again. +# +[alps-error] +The application appears to have been direct launched using "aprun", +but OMPI was not built with ALPS PMI support and therefore cannot +execute. You must build PRTE using --with-pmi pointing +to the ALPS PMI library location. + +Please configure as appropriate and try again. +# +[alps-error2] +The application appears to have been direct launched using "aprun", +but OMPI was not built with ALPS support. This usually happens +when OMPI was not configured --with-alps and we weren't able +to discover an ALPS installation in the usual places. + +Please configure as appropriate and try again. +# +[legacy-tool] +We no longer support non-PMIx-based tools, and require a +minimum level of PMIx v2.0. + +Please update the tool and/or the PMIx version you are using. diff --git a/src/docs/show-help-files/help-hostfile.rst b/src/docs/show-help-files/help-hostfile.rst deleted file mode 100644 index 44c1b34f71..0000000000 --- a/src/docs/show-help-files/help-hostfile.rst +++ /dev/null @@ -1,272 +0,0 @@ -.. Copyright (c) 2004-2006 The Trustees of Indiana University and Indiana - University Research and Technology - Corporation. All rights reserved. - Copyright (c) 2004-2005 The University of Tennessee and The University - of Tennessee Research Foundation. All rights - reserved. - Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, - University of Stuttgart. All rights reserved. - Copyright (c) 2004-2005 The Regents of the University of California. - All rights reserved. - Copyright (c) 2012 Los Alamos National Security, LLC - All rights reserved. - Copyright (c) 2016 Research Organization for Information Science - and Technology (RIST). All rights reserved. - Copyright (c) 2019-2020 Intel, Inc. All rights reserved. - Copyright (c) 2020 Cisco Systems, Inc. All rights reserved - Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. - Copyright (c) 2024 Nanook Consulting All rights reserved. - $COPYRIGHT$ - - Additional copyrights may follow - - $HEADER$ - - This is the US/English general help file for hostfile utilities. - -[bogus section] - -This section is not used by PRTE code. But we have to put a RST -section title in this file somewhere, or Sphinx gets unhappy. So we -put it in a section that is ignored by PRTE code. - -Hello, world ------------- - -[no-hostfile] - -PRTE was unable to open the hostfile: - -.. code:: - - %s - -Check to make sure the path and filename are correct. - -[port] - -PRTE detected a bad parameter in the hostfile: - -.. code:: - - %s - -The port parameter is less than 0: - -.. code:: - - port=%d - -[slots] - -PRTE detected a bad parameter in the hostfile: - -.. code:: - - %s - -The slots parameter is less than 0: - -.. code:: - - slots=%d - -[max_slots] - -PRTE detected a bad parameter in the hostfile: - -.. code:: - - %s - -The max_slots parameter is less than 0: - -.. code:: - - max_slots=%d - -[max_slots_lt] - -PRTE detected a bad parameter in the hostfile: - -.. code:: - - %s - -The max_slots parameter is less than the slots parameter: - -.. code:: - - slots=%d - max_slots=%d - -[parse_error_string] - -PRTE detected a parse error in the hostfile: - -.. code:: - - %s - -It occured on line number %d on token %d: - -.. code:: - - %s - -[parse_error_int] - -PRTE detected a parse error in the hostfile: - -.. code:: - - %s - -It occured on line number %d on token %d: - -.. code:: - - %d - -[parse_error] - -PRTE detected a parse error in the hostfile: - -.. code:: - - %s - -It occured on line number %d on token %d. - -[not-all-mapped-alloc] - -Some of the requested hosts are not included in the current allocation. - -The requested hosts were in this hostfile: - - .. code:: - - %s - -Please verify that you have specified the allocated resources properly in -the provided hostfile. - -[hostfile:relative-syntax] - -A relative host was specified, but no prior allocation has been made. -Thus, there is no way to determine the proper host to be used. - -.. code:: - - hostfile entry: %s - -Re-run this command with ``--help hosts`` for further information. - -[hostfile:relative-node-not-found] - -A relative host was specified, but was not found. The requested host was -specified as: - -.. code:: - - Index: %d - Syntax given: %s - -This is most likely due to the relative index being out of bounds. You -could obtain a larger allocation or reduce the relative host index. - -Re-run this command with ``--help hosts`` for further information. - -[hostfile:invalid-relative-node-syntax] - -A relative host was improperly specified |mdash| the value provided was. - -.. code:: - - hostfile entry: %s - -You may have forgotten to preface a node with ``N`` or ``n``, or used the -``e`` or ``E`` to indicate empty nodes. - -Re-run this command with ``--help hosts`` for further information. - -[hostfile:not-enough-empty] - -The requested number of empty hosts was not available |mdash| the -system was short by %d hosts. Please recheck your allocation. - -Re-run this command with ``--help hosts`` for further information. - -[boards] - -PRTE detected a bad parameter in the hostfile: - -.. code:: - - %s - -The boards parameter is less than 0: - -.. code:: - - boards=%d - -[sockets] - -PRTE detected a bad parameter in the hostfile: - -.. code:: - - %s - -The packages parameter is less than 0: - -.. code:: - - packages=%d - -[cores] - -PRTE detected a bad parameter in the hostfile: - -.. code:: - - %s - -The cores parameter is less than 0: - -.. code:: - - cores=%d - -[hostfile:extra-node-not-found] - -A hostfile was provided that contains at least one node not -present in the allocation: - -.. code:: - - hostfile: %s - node: %s - -If you are operating in a resource-managed environment, then only -nodes that are in the allocation can be used in the hostfile. You may -find relative node syntax to be a useful alternative to specifying -absolute node names; re-run this command with ``--help hosts`` for -further information. - -[slots-given] - -A hostfile was provided that contains multiple definitions -of the slot count for at least one node: - -.. code:: - - hostfile: %s - node: %s - -You can either list a node multiple times, once for each slot, -or you can provide a single line that contains ``slot=N``. Mixing -the two methods is not supported. - -Please correct the hostfile and try again. diff --git a/src/docs/show-help-files/help-hostfile.txt b/src/docs/show-help-files/help-hostfile.txt new file mode 100644 index 0000000000..587cd39abf --- /dev/null +++ b/src/docs/show-help-files/help-hostfile.txt @@ -0,0 +1,196 @@ +[bogus section] + +This section is not used by PRTE code. But we have to put a RST +section title in this file somewhere, or Sphinx gets unhappy. So we +put it in a section that is ignored by PRTE code. + + +Hello, world +============ + +[no-hostfile] + +PRTE was unable to open the hostfile: + + %s + +Check to make sure the path and filename are correct. + +[port] + +PRTE detected a bad parameter in the hostfile: + + %s + +The port parameter is less than 0: + + port=%d + +[slots] + +PRTE detected a bad parameter in the hostfile: + + %s + +The slots parameter is less than 0: + + slots=%d + +[max_slots] + +PRTE detected a bad parameter in the hostfile: + + %s + +The max_slots parameter is less than 0: + + max_slots=%d + +[max_slots_lt] + +PRTE detected a bad parameter in the hostfile: + + %s + +The max_slots parameter is less than the slots parameter: + + slots=%d + max_slots=%d + +[parse_error_string] + +PRTE detected a parse error in the hostfile: + + %s + +It occured on line number %d on token %d: + + %s + +[parse_error_int] + +PRTE detected a parse error in the hostfile: + + %s + +It occured on line number %d on token %d: + + %d + +[parse_error] + +PRTE detected a parse error in the hostfile: + + %s + +It occured on line number %d on token %d. + +[not-all-mapped-alloc] + +Some of the requested hosts are not included in the current +allocation. + +The requested hosts were in this hostfile: + + %s + +Please verify that you have specified the allocated resources properly +in the provided hostfile. + +[hostfile:relative-syntax] + +A relative host was specified, but no prior allocation has been made. +Thus, there is no way to determine the proper host to be used. + + hostfile entry: %s + +Re-run this command with "--help hosts" for further information. + +[hostfile:relative-node-not-found] + +A relative host was specified, but was not found. The requested host +was specified as: + + Index: %d + Syntax given: %s + +This is most likely due to the relative index being out of bounds. You +could obtain a larger allocation or reduce the relative host index. + +Re-run this command with "--help hosts" for further information. + +[hostfile:invalid-relative-node-syntax] + +A relative host was improperly specified — the value provided was. + + hostfile entry: %s + +You may have forgotten to preface a node with "N" or "n", or used the +"e" or "E" to indicate empty nodes. + +Re-run this command with "--help hosts" for further information. + +[hostfile:not-enough-empty] + +The requested number of empty hosts was not available — the system was +short by %d hosts. Please recheck your allocation. + +Re-run this command with "--help hosts" for further information. + +[boards] + +PRTE detected a bad parameter in the hostfile: + + %s + +The boards parameter is less than 0: + + boards=%d + +[sockets] + +PRTE detected a bad parameter in the hostfile: + + %s + +The packages parameter is less than 0: + + packages=%d + +[cores] + +PRTE detected a bad parameter in the hostfile: + + %s + +The cores parameter is less than 0: + + cores=%d + +[hostfile:extra-node-not-found] + +A hostfile was provided that contains at least one node not present in +the allocation: + + hostfile: %s + node: %s + +If you are operating in a resource-managed environment, then only +nodes that are in the allocation can be used in the hostfile. You may +find relative node syntax to be a useful alternative to specifying +absolute node names; re-run this command with "--help hosts" for +further information. + +[slots-given] + +A hostfile was provided that contains multiple definitions of the slot +count for at least one node: + + hostfile: %s + node: %s + +You can either list a node multiple times, once for each slot, or you +can provide a single line that contains "slot=N". Mixing the two +methods is not supported. + +Please correct the hostfile and try again. diff --git a/src/docs/show-help-files/help-iof-base.txt b/src/docs/show-help-files/help-iof-base.txt new file mode 100644 index 0000000000..9529a32a3f --- /dev/null +++ b/src/docs/show-help-files/help-iof-base.txt @@ -0,0 +1,32 @@ +# -*- text -*- +# +# Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2005 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2014-2019 Intel, Inc. All rights reserved. +# Copyright (c) 2017 IBM Corporation. All rights reserved. +# Copyright (c) 2018 Research Organization for Information Science +# and Technology (RIST). All rights reserved. +# Copyright (c) 2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +# +[unrecognized-directive] +The following directive was given to "--%s": + + Directive: %s + +This directive is not recognized. Please check your spelling +and/or use the "--help" option to find the supported values. +# diff --git a/src/docs/show-help-files/help-oob-base.txt b/src/docs/show-help-files/help-oob-base.txt new file mode 100644 index 0000000000..009fcf0e0e --- /dev/null +++ b/src/docs/show-help-files/help-oob-base.txt @@ -0,0 +1,24 @@ +# -*- text -*- +# +# Copyright (c) 2004-2006 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2006 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2014-2019 Intel, Inc. All rights reserved. +# Copyright (c) 2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +# +[no-interfaces-avail] +No network interfaces were found for out-of-band communications. We require +at least one available network for out-of-band messaging. diff --git a/src/docs/show-help-files/help-oob-tcp.txt b/src/docs/show-help-files/help-oob-tcp.txt new file mode 100644 index 0000000000..950599d810 --- /dev/null +++ b/src/docs/show-help-files/help-oob-tcp.txt @@ -0,0 +1,139 @@ +# -*- text -*- +# +# Copyright (c) 2004-2006 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2006 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2014-2020 Intel, Inc. All rights reserved. +# Copyright (c) 2015-2020 Cisco Systems, Inc. All rights reserved +# Copyright (c) 2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +[static-and-dynamic] +Both static and dynamic port ranges were specified for the +out-of-band (OOB) communication subsystem: + +Static ports: %s +Dynamic ports: %s + +Only one can be specified. Please choose either static or +dynamic ports and try again. +# +[include-exclude] +Both TCP interface include and exclude lists were specified: + + Include: %s + Exclude: %s + +Only one of these can be given. +# +[not-parseable] +The specified network is not parseable. Since we cannot determine +your desired intent, we cannot establish a TCP socket for out-of-band +communications and will therefore abort. Please correct the network +specification and retry. +# +[no-included-found] +None of the TCP networks specified to be included for out-of-band communications +could be found: + + Value given: %s + +Please revise the specification and try again. +# +[excluded-all] +The specified list of networks to be excluded for TCP out-of-band communications +resulted in no networks being available: + + Value given: %s + +Please revise the specification and try again. +# +[invalid if_inexclude] +WARNING: An invalid value was given for oob_tcp_if_%s. This +value will be ignored. + + Local host: %s + Value: %s + Message: %s +# +[authent-fail] +An attempt was made to make a TCP connection between two hosts: + + Initiating host: %s + Receiving host: %s + +Unfortunately, the connection was refused due to a failure to +authenticate. This is usually caused by a mis-match between +the security domains of the two hosts - e.g., one might be +using Munge while the other is not. This can typically be +resolved by specifying the desired security method. For +example, adding "--mca sec basic" to your command line. +# +[accept failed] +WARNING: The accept(3) system call failed on a TCP socket. While this +should generally never happen on a well-configured HPC system, the +most common causes when it does occur are: + + * The process ran out of file descriptors + * The operating system ran out of file descriptors + * The operating system ran out of memory + +Your PRTE job will likely hang until the failure resason is fixed +(e.g., more file descriptors and/or memory becomes available), and may +eventually timeout / abort. + + Local host: %s + Errno: %d (%s) + Probable cause: %s +# +[privilege failure] +An attempt was made to initiate a TCP connection from an +unprivileged source while we are operating at privileged +levels. + + Local host: %s + Listening port: %d + Remote host: %s + Remote port: %d + +The connection was rejected. +# +[static-fwd] +Static ports were requested while prte_fwd_mpirun_port was set. +Both options cannot be simultaneously set. Please either set +prte_fwd_mpirun_port=false or remove any static port directives. +# +[version mismatch] +PRTE detected a mismatch in versions between two processes. This +typically means that you executed "mpirun" (or "mpiexec") from one +version of PRTE on on node, but your default path on one of the +other nodes upon which you launched found a different version of Open +MPI. + +PRTE only supports running exactly the same version between all +processes in a single job. + +This will almost certainly cause unpredictable behavior, and may end +up aborting your job. + + Local host: %s + Local process name: %s + Local PRTE version: %s + Peer host: %s + Peer process name: %s + Peer PRTE version: %s +# +[no-listeners] +No sockets were able to be opened on the available protocols +(IPv4 and/or IPv6). Please check your network and retry. diff --git a/src/docs/show-help-files/help-plm-base.txt b/src/docs/show-help-files/help-plm-base.txt new file mode 100644 index 0000000000..1f3c46d9a6 --- /dev/null +++ b/src/docs/show-help-files/help-plm-base.txt @@ -0,0 +1,177 @@ +# -*- text -*- +# +# Copyright (c) 2004-2006 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2006 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2015-2020 Intel, Inc. All rights reserved. +# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved +# Copyright (c) 2021-2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +[no-available-pls] +No available launching agents were found. + +This is an unusual error; it means that PRTE was unable to find +any mechanism to launch proceses, and therefore is unable to start the +process(es) required by your application. +# +[daemon-no-assigned-node] +A daemon has no recorded node: + + Daemon: %s + Reported from nodename: %s + +This usually indicates a difference between the names of nodes in the +allocation versus what is returned on the node by get_hostname. +# +[daemon-died-no-signal] +A daemon died unexpectedly with status %d while attempting +to launch so we are aborting. + +There may be more information reported by the environment (see above). + +This may be because the daemon was unable to find all the needed shared +libraries on the remote node. You may set your LD_LIBRARY_PATH to have the +location of the shared libraries on the remote nodes and this will +automatically be forwarded to the remote nodes. +# +[daemon-died-signal-core] +A daemon died unexpectedly on signal %d (with core) while +attempting to launch so we are aborting. + +There may be more information reported by the environment (see above). + +This may be because the daemon was unable to find all the needed shared +libraries on the remote node. You may set your LD_LIBRARY_PATH to have the +location of the shared libraries on the remote nodes and this will +automatically be forwarded to the remote nodes. +# +[daemon-died-signal] +A daemon died unexpectedly on signal %d while attempting to +launch so we are aborting. + +There may be more information reported by the environment (see above). + +This may be because the daemon was unable to find all the needed shared +libraries on the remote node. You may set your LD_LIBRARY_PATH to have the +location of the shared libraries on the remote nodes and this will +automatically be forwarded to the remote nodes. +# +[incomplete-exit-cmd] +One or more daemons could not be ordered to exit. This can be caused by a +number of rather rare problems, but typically is caused by a daemon having +died due to the failure of a node or its communications. This could result +in an incomplete cleanup on the affected nodes. Please see below for a list +of nodes which may require additional cleanup. + +We are truly sorry for the inconvenience. +# +[incomplete-kill-procs-cmd] +One or more daemons could not be ordered to kill their local processes. +This can be caused by a number of rather rare problems, but typically +is caused by a daemon having died due to the failure of a node or its +communications. This could result in an incomplete cleanup on the affected +nodes. Additional information may be available below. + +We are truly sorry for the inconvenience. +# +[stdin-target-out-of-range] +The requested stdin target is out of range for this job - it points +to a process rank that is greater than the number of processes in the +job. + +Specified target: %s +Number of procs: %s + +This could be caused by specifying a negative number for the stdin +target, or by mistyping the desired rank. Remember that MPI ranks begin +with 0, not 1. + +Please correct the cmd line and try again. +# +[too-many-hosts] +A call was made to launch a local slave process, but more than one +target host was provided. Currently, each launch of a local slave +can only be to a single host. To launch slaves on multiple hosts, +you must issue one call/host. + +Num hosts specified: %d + +# +[abs-path-reqd] +A call was made to launch a local slave process that requested the +binaries be pre-positioned on the remote host. However, an absolute +path to the target directory was either not specified, or was provided +in a relative path format. + +Path provided: %s + +The path to the target directory must be given as an absolute path. The +target directory does NOT need to exist - the path to the target will +be created, if required. + +# +[exec-not-found] +A call was made to launch a local slave process, but the specified +executable could not be found: + +Exec: %s + +Please either specify an absolute path to the executable, or check +that the executable is in your PATH. + +# +[cp-not-found] +A call was made to launch a local slave process that requested the +binaries be pre-positioned on the remote host. However, we could not +find the %s command in your path. + +Please check that %s is in your PATH and try again. + +# +[file-not-found] +A call was made to launch a local slave process that requested pre-positioning +of one or more files, but the specified files could not be found: + +File: %s +Source directory: %s + +Please either specify an absolute path to the file, or check +that the file is in your current working directory...and ensure +that you have read permissions on the file. + +# +[deprecated-amca] +You're using the --am option. Please be advised that this option is deprecated; +you should use --tune instead. The --tune option allows one to specify mca +parameters as well as environment variables from within a file using the same +command line syntax (e.g. -mca var val -mca var "val" -x var=val -x var). +The --am option will be removed in a future release. +# +[no-oob] +A call was made to launch additional processes, but this process has +no active out-of-band transports and therefore cannot execute this call. +Please check to see if you have the "oob" MCA parameter set and ensure +that it is either unset or at least includes the tcp transport. +# +[multi-endian] +PRTE does not currently support multi-endian operations. We have +detected that the following node differs in endianness: + + + Nodename: %s + Endian: %s + Local endian: %s + +Please correct the situation and try again. diff --git a/src/docs/show-help-files/help-plm-slurm.txt b/src/docs/show-help-files/help-plm-slurm.txt new file mode 100644 index 0000000000..2f71f2bb44 --- /dev/null +++ b/src/docs/show-help-files/help-plm-slurm.txt @@ -0,0 +1,138 @@ +# -*- text -*- +# +# Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2005 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2014-2020 Intel, Inc. All rights reserved. +# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved +# Copyright (c) 2022-2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +[multiple-prefixes] +The SLURM process starter for PRTE does not support multiple +different --prefix options to mpirun. You can specify at most one +unique value for the --prefix option (in any of the application +contexts); it will be applied to all the application contexts of your +parallel job. + +Put simply, you must have PRTE installed in the same location on +all of your SLURM nodes. + +Multiple different --prefix options were specified to mpirun. This is +a fatal error for the SLURM process starter in PRTE. + +The first two prefix values supplied were: + %s +and %s +# +[no-hosts-in-list] +The SLURM process starter for PRTE didn't find any hosts in +the map for this application. This can be caused by a lack of +an allocation, or by an error in the PRTE code. Please check +to ensure you have a SLURM allocation. If you do, then please pass +the error to the PRTE user's mailing list for assistance. +# +[no-local-slave-support] +A call was made to launch a local slave process, but no support +is available for doing so. Launching a local slave requires support +for either rsh or ssh on the backend nodes where MPI processes +are running. + +Please consult with your system administrator about obtaining +such support. +# +[no-srun] +The SLURM process starter for OpenMPI was unable to locate a +usable "srun" command in its path. Please check your path +and try again. +# +[ancient-version] +The Slurm process starter requires a minimum Slurm version level +of v17.11. The detected version being used here is: + + Major: %d + Minor: %d + +SchedMD strongly recommends that you upgrade your Slurm version. +Versions of Slurm prior to 21.08.8 and 20.11.9 have been found +to have a security issue and are not supported - therefore, it +is recommended that you upgrade to a level at or above those +versions. + +It is recognized that upgrades can take some time to complete. +In the interim, you can execute your job by ignoring the Slurm +process starter via the following MCA parameter: + + Environment: PRTE_MCA_plm=^slurm + Cmd line: --prtemca plm ^slurm + Default MCA param file: plm = ^slurm + +This will result in use of the ssh process starter. This will have +no impact on your application, but will result in any accounting +being done solely at the allocation level instead of per-job. +# +[custom-args-in-env] +The Slurm process starter for PRTE detected the presence of an MCA +parameter in the environment that assigns custom command line arguments +to the `srun` command used to start PRTE's daemons on remote nodes: + + Paramater value: %s + +This warning is provided to alert you (the user) to a perhaps +unintentional setting of command line arguments, or the unseen +overriding of your intended arguments by Slurm. + +Background: Starting with Slurm version 23.11, a command line argument +(`--external-launcher`) was added to `srun` to indicate that the +command was being initiated from within a third-party launcher (e.g., +`prte` or `prterun`). This allows Slurm to essentially freely modify +the `srun` command line while retaining a backward compatibility +capability when explicitly told to use it. Notably, the Slurm +environment does this by automatically setting the +PRTE_MCA_plm_slurm_args environment variable to pass in its own +command line arguments. This has the side effect of overriding most +user- or system-level settings. Note that arguments passed on the +PRTE command line will override any Slurm setting of the +PRTE_MCA_plm_slurm_args environment variable, but with potentially +undesirable side effects if newer versions of `srun` misinterpret or +fail to understand the user-specified arguments. + +If the setting of the MCA parameter was intentional, or if the +parameter looks acceptable to you, then please set the following +MCA parameter to disable this warning: + + Environment: PRTE_MCA_plm_slurm_disable_warning=true + Cmd line: --prtemca plm_slurm_disable_warning 1 + Default MCA param file: plm_slurm_disable_warning = true + +If you did not intentionally set the identified command line +arguments and do not wish them to be used, then set the +following MCA param to have them ignored: + + Environment: PRTE_MCA_plm_slurm_ignore_args=true + Cmd line: --prtemca plm_slurm_ignore_args 1 + Default MCA param file: plm_slurm_ignore_args = true + +Note that if you wish to provide custom `srun` command line +arguments and are finding them being overridden by Slurm, you +can ensure that your values are used by setting them with the +following param: + + Environment: PRTE_MCA_plm_slurm_force_args=foo + Cmd line: --prtemca plm_slurm_force_args foo + Default MCA param file: plm_slurm_force_args = foo + +Note that you may need to add the `--external-launcher` option +to your provided args to ensure that `srun` properly functions +if you are using a relatively recent release of Slurm. diff --git a/src/docs/show-help-files/help-plm-ssh.txt b/src/docs/show-help-files/help-plm-ssh.txt new file mode 100644 index 0000000000..302a229b3e --- /dev/null +++ b/src/docs/show-help-files/help-plm-ssh.txt @@ -0,0 +1,98 @@ +# -*- text -*- +# +# Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2005 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2015-2020 Intel, Inc. All rights reserved. +# Copyright (c) 2020-2021 Cisco Systems, Inc. All rights reserved +# Copyright (c) 2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +# This is the US/English general help file for PRTE's prun. +# +[agent-not-found] +The value of the MCA parameter "plm_ssh_agent" was set to a path +that could not be found: + + plm_ssh_agent: %s + +Please either unset the parameter, or check that the path is correct +# +[no-local-orted] +The ssh PLS component was not able to find the executable "orted" in +your PATH or in the directory where PRTE was initially installed, +and therefore cannot continue. + +For reference, your current PATH is: + + %s + +We also looked for orted in the following directory: + + %s + +[multiple-prefixes] +Specified multiple application contexts using different +settings for --prefix. Care should be taken, that corresponding +processes are mapped to different nodes. Having multiple prefixes +per node is not allowed. + +The previously set prefix was + %s + +the prefix to be set overriding: + %s + +[concurrency-less-than-zero] +The value of the MCA parameter "pls_ssh_num_concurrent" is less than +or equal to zero (%d). This parameter is used to determine how many +remote agents (typically ssh) to invoke concurrently while launching +parallel jobs. + +This value has automatically be reset to 1; processing will continue. + +[deadlock-params] +The ssh launcher has been given a number of %d concurrent daemons to +launch and is in a debug-daemons option. However, the total number of +daemons to launch (%d) is greater than this value. This is a scenario that +will cause the system to deadlock. + +To avoid deadlock, either increase the number of concurrent daemons, or +remove the debug-daemons flag. + +[unknown-user] +The user (%d) is unknown to the system (i.e. there is no corresponding +entry in the password file). Please contact your system administrator +for a fix. +# +[cannot-resolve-shell-with-prefix] +The ssh launcher has been given a prefix to use, but could not determine +the type of remote shell being used on the remote node. This is a fatal +error as we cannot determine how to construct the cmd line to set your +remote LD_LIBRARY_PATH and PATH environmental variables. + +The prefix we were given are: + +prte_prefix: %s +prefix_dir: %s +# +[cmd-line-too-long] +The cmd line to launch remote daemons is too long: + + Length: %d + Max length: %d + +Consider setting -mca plm_ssh_pass_environ_mca_params 0 to +avoid including any environmentally set MCA parameters on the +command line. diff --git a/src/docs/show-help-files/help-prte-filem-raw.txt b/src/docs/show-help-files/help-prte-filem-raw.txt new file mode 100644 index 0000000000..66b11858df --- /dev/null +++ b/src/docs/show-help-files/help-prte-filem-raw.txt @@ -0,0 +1,49 @@ + -*- text -*- +# +# Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana +# University Research and Technology +# Corporation. All rights reserved. +# Copyright (c) 2004-2005 The University of Tennessee and The University +# of Tennessee Research Foundation. All rights +# reserved. +# Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, +# University of Stuttgart. All rights reserved. +# Copyright (c) 2004-2005 The Regents of the University of California. +# All rights reserved. +# Copyright (c) 2019 Intel, Inc. All rights reserved. +# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved +# Copyright (c) 2024 Nanook Consulting All rights reserved. +# $COPYRIGHT$ +# +# Additional copyrights may follow +# +# $HEADER$ +# +# This is the US/English general help file for PRTE FileM framework. +# +[prte-filem-rsh:get-file-exists] +WARNING: Could not preload specified file: File already exists. + +Fileset: %s +Host: %s + +Will continue attempting to launch the process. + +[prte-filem-rsh:put-file-not-exist] +WARNING: Could not preload specified file: File does not exist. + +Fileset: %s +Host: %s + +Will continue attempting to launch the process. + +[prte-filem-rsh:remote-get-failed] +WARNING: Remote peer (%s) failed to preload a file. + +Exit Status: %d +Local File: %s +Remote File: %s +Command: + %s + +Will continue attempting to launch the process(es). diff --git a/src/docs/show-help-files/help-prte-hwloc-base.rst b/src/docs/show-help-files/help-prte-hwloc-base.txt similarity index 72% rename from src/docs/show-help-files/help-prte-hwloc-base.rst rename to src/docs/show-help-files/help-prte-hwloc-base.txt index 8badbc13cb..c8ba4cd61a 100644 --- a/src/docs/show-help-files/help-prte-hwloc-base.rst +++ b/src/docs/show-help-files/help-prte-hwloc-base.txt @@ -1,30 +1,18 @@ -.. Copyright (c) 2011-2020 Cisco Systems, Inc. All rights reserved - Copyright (c) 2014-2020 Intel, Inc. All rights reserved. - Copyright (c) 2022-2023 Nanook Consulting. All rights reserved. - $COPYRIGHT$ - - Additional copyrights may follow - - $HEADER$ - - This is the US/English help file for PRTE's hwloc base support - [bogus section] This section is not used by PRTE code. But we have to put a RST section title in this file somewhere, or Sphinx gets unhappy. So we put it in a section that is ignored by PRTE code. + Hello, world ------------- +============ [mbind failure] PRTE failed to bind internal memory to a specific NUMA node. This message will only be reported at most once per process. -.. code:: - Local host: %s PID: %d File: %s:%d @@ -35,19 +23,14 @@ message will only be reported at most once per process. The specified %s policy is not recognized: -.. code:: - Policy: %s -Please check for a typo or ensure that the option is a supported -one. +Please check for a typo or ensure that the option is a supported one. [redefining-policy] -Conflicting directives for binding policy are causing the policy -to be redefined: - -.. code:: +Conflicting directives for binding policy are causing the policy to be +redefined: New policy: %s Prior policy: %s @@ -59,8 +42,6 @@ Please check that only one policy is defined. The following command line option and corresponding MCA parameter have been deprecated and replaced as follows: -.. code:: - Command line option: Deprecated: %s Replacement: %s @@ -78,8 +59,6 @@ PRTE failed to find a cache of a specified type. This is a highly unusual error; it may indicate a system configuration error. This additional information may be of help: -.. code:: - Message: %s Cache level: %d @@ -87,33 +66,26 @@ additional information may be of help: The following binding modifier was given but lacks a required value: -.. code:: - Modifier: %s -Please check for a typo or ensure that the option is a supported -one. +Please check for a typo or ensure that the option is a supported one. [bad-processor-type] The default CPU list contains an invalid modifier: -.. code:: - Default CPU list: %s Modifier: %s -The modifier should indicate the type of CPU being used in the -list |mdash| the only valid values are HWTCPUS (for use of hwthreads -as independent CPUs) or CORECPUS (for use of cores as independent -CPUs). Please correct the input. +The modifier should indicate the type of CPU being used in the list — +the only valid values are HWTCPUS (for use of hwthreads as independent +CPUs) or CORECPUS (for use of cores as independent CPUs). Please +correct the input. [unrecognized-modifier] The binding request contains an unrecognized modifier: -.. code:: - Request: %s Please check your request and try again. @@ -122,13 +94,11 @@ Please check your request and try again. Binding is performed to the first available specified object type within the object where the process was mapped. In other words, -binding can only be done to the mapped object or to a resource -located beneath that object. +binding can only be done to the mapped object or to a resource located +beneath that object. The specified binding lies above the mapping object type: -.. code:: - Mapping level: %s Binding level: %s diff --git a/src/docs/show-help-files/help-prte-info.rst b/src/docs/show-help-files/help-prte-info.rst deleted file mode 100644 index fea5c813c6..0000000000 --- a/src/docs/show-help-files/help-prte-info.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. -*- rst -*- - - Copyright (c) 2021-2023 Nanook Consulting. All rights reserved. - Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. - - $COPYRIGHT$ - - Additional copyrights may follow - - $HEADER$ - -[bogus section] - -This section is not used by PRTE code. But we have to put a RST -section title in this file somewhere, or Sphinx gets unhappy. So we -put it in a section that is ignored by PRTE code. - -Hello, world ------------- - -[usage] - -%s (%s) %s - -Usage: ``%s [OPTION]...`` - -Provide detailed information on your PRRTE installation. - -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