From da9206a4c1df7744d4cc05358336bf1aaff596f4 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Tue, 11 Jul 2023 12:02:54 -0400 Subject: [PATCH 1/4] mailmap: Add alternate email address for Jeff Squyres Signed-off-by: Jeff Squyres --- .mailmap | 1 + 1 file changed, 1 insertion(+) diff --git a/.mailmap b/.mailmap index e8516075720..b463497a038 100644 --- a/.mailmap +++ b/.mailmap @@ -32,6 +32,7 @@ Jeff Squyres Jeff Squyres --quiet <--quiet> Jeff Squyres +Jeff Squyres George Bosilca From ab7013787261ac93d0ea55ea94af00e07cd215a2 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Sun, 24 Sep 2023 10:21:33 -0400 Subject: [PATCH 2/4] Update prrte submodule to include new RST functionality Signed-off-by: Jeff Squyres --- 3rd-party/prrte | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/3rd-party/prrte b/3rd-party/prrte index 0347baa1eda..9015ca02cce 160000 --- a/3rd-party/prrte +++ b/3rd-party/prrte @@ -1 +1 @@ -Subproject commit 0347baa1edaec29c4f0cf1eac7b674ad7ba139c1 +Subproject commit 9015ca02cce72acc03f86d399f939843c42b3dc8 From 1fd09447f4234f15d2d8c14dd4efba7601b67b8d Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Tue, 11 Jul 2023 12:02:04 -0400 Subject: [PATCH 3/4] docs: slurp PRTE's RST files into mpirun.1 This commit introduce a fundamentally new concept: have configure search PRRTE for RST files to include in Open MPI's documentation (regardless of whether we're using the internal/bundled PRRTE or an external PRRTE). If we're building against an external PRRTE that is old enough that it doesn't have any RST files installed, we'll make up some dummy RST files that basically say "you don't get help/content here because your PRRTE is too old." To simplify the configury for this scheme, this commit also makes another change: the pre-built HTML docs and nroff man pages included in distribution tarballs are now located at docs/html/ and docs/man/, respectively (vs. the location where we'll build them: docs/_build/html/ and docs/_build/man/, respectively). There are two cases here: 1. If the user has Sphinx available, we'll build the docs under docs/_build/, and install those (effectively ignoring the pre-built docs). 2. If the user does not have Sphinx available, we'll just install the pre-built docs. This simplified things like "make clean" and "make distcheck". Including RST content from PRTE required another major change: when we build the RST docs in a VPATH scenario, we copy the entire docs/ source tree to the build tree. This allows us to modify the RST sources a bit (e.g., to include the PRRTE RST files or generate dummy PRRTE RST files). mpirun.1.rst is updated to include the RST content from PRRTE about CLI options. More work needs to be done here to remove old, now-redundant content. Finally, we also amend the advice to implementors to have Sphinx installed when building their package so that Open MPI's build system can properly slurp in their PRRTE's RST docs. Signed-off-by: Jeff Squyres --- .gitignore | 9 + Makefile.ompi-rules | 9 + config/ompi_setup_prrte.m4 | 59 +++- configure.ac | 3 +- docs/Makefile.am | 270 ++++++++++++--- docs/conf.py | 20 +- docs/index.rst | 8 +- docs/installing-open-mpi/packagers.rst | 42 +++ .../required-support-libraries.rst | 5 +- docs/man-openmpi/man1/mpirun.1.rst | 307 +++++++++++------- docs/news/news-v5.0.x.rst | 7 +- docs/no-prrte-content.rst.txt | 24 ++ 12 files changed, 590 insertions(+), 173 deletions(-) create mode 100644 docs/no-prrte-content.rst.txt diff --git a/.gitignore b/.gitignore index d15a1bc8f88..c1bfe01444a 100644 --- a/.gitignore +++ b/.gitignore @@ -534,3 +534,12 @@ docs/_templates # Common Python virtual environment directory names venv py?? + +# Copies of PRRTE RST files (i.e., not source controlled in this tree) +docs/prrte-rst-content +docs/schizo-ompi-rst-content + +# Copies of the built HTML docs and man pages (for distribution +# tarballs) +docs/html +docs/man diff --git a/Makefile.ompi-rules b/Makefile.ompi-rules index 567bcfd99f3..d18d49c4978 100644 --- a/Makefile.ompi-rules +++ b/Makefile.ompi-rules @@ -2,6 +2,7 @@ # Copyright (c) 2008-2022 Cisco Systems, Inc. All rights reserved. # Copyright (c) 2008 Sun Microsystems, Inc. All rights reserved. # Copyright (c) 2020 Intel, Inc. All rights reserved. +# Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. # $COPYRIGHT$ # # Additional copyrights may follow @@ -26,6 +27,14 @@ OMPI_V_GEN = $(ompi__v_GEN_$V) ompi__v_GEN_ = $(ompi__v_GEN_$AM_DEFAULT_VERBOSITY) ompi__v_GEN_0 = @echo " GENERATE" $@; +OMPI_V_COPYALL = $(ompi__v_COPYALL_$V) +ompi__v_COPYALL_ = $(ompi__v_COPYALL_$AM_DEFAULT_VERBOSITY) +ompi__v_COPYALL_0 = @echo " COPY tree $@"; + +OMPI_V_SPHINX_COPYRST = $(ompi__v_SPHINX_COPYRST_$V) +ompi__v_SPHINX_COPYRST_ = $(ompi__v_SPHINX_COPYRST_$AM_DEFAULT_VERBOSITY) +ompi__v_SPHINX_COPYRST_0 = @echo " COPY RST source files"; + OMPI_V_SPHINX_HTML = $(ompi__v_SPHINX_HTML_$V) ompi__v_SPHINX_HTML_ = $(ompi__v_SPHINX_HTML_$AM_DEFAULT_VERBOSITY) ompi__v_SPHINX_HTML_0 = @echo " GENERATE HTML docs"; diff --git a/config/ompi_setup_prrte.m4 b/config/ompi_setup_prrte.m4 index 4dffa6ceb2a..97eba7a1bd2 100644 --- a/config/ompi_setup_prrte.m4 +++ b/config/ompi_setup_prrte.m4 @@ -19,6 +19,7 @@ dnl Copyright (c) 2019-2020 Intel, Inc. All rights reserved. dnl Copyright (c) 2020-2022 Amazon.com, Inc. or its affiliates. All Rights reserved. dnl Copyright (c) 2021 Nanook Consulting. All rights reserved. dnl Copyright (c) 2021-2022 IBM Corporation. All rights reserved. +dnl Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. dnl $COPYRIGHT$ dnl dnl Additional copyrights may follow @@ -35,10 +36,25 @@ dnl dnl A Makefile conditional OMPI_WANT_PRRTE will be defined based on the dnl results of the build. AC_DEFUN([OMPI_SETUP_PRRTE],[ - OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy]) + AC_REQUIRE([AC_PROG_LN_S]) + +OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy target_rst_dir]) opal_show_subtitle "Configuring PRRTE" + # We *must* have setup Sphinx before invoking this macro (i.e., it + # is a programming error -- not a run-time error -- if Sphinx was + # not previously setup). + OAC_ASSERT_BEFORE([OAC_SETUP_SPHINX], [OMPI_SETUP_PRRTE]) + + # These are sym links to folders with PRRTE's RST files that we'll + # slurp into mpirun.1.rst. We'll remove these links (or even + # accidental full copies) now and replace them with new links to + # the PRRTE that we find, below. + target_rst_dir="$OMPI_TOP_BUILDDIR/docs" + rm -rf "$target_rst_dir/prrte-rst-content" + rm -rf "$target_rst_dir/schizo-ompi-rst-content" + OPAL_3RDPARTY_WITH([prrte], [prrte], [package_prrte], [1]) AC_ARG_WITH([prrte-bindir], @@ -101,12 +117,15 @@ AC_DEFUN([OMPI_SETUP_PRRTE],[ [$OMPI_USING_INTERNAL_PRRTE], [Whether or not we are using the internal PRRTE]) - OPAL_SUMMARY_ADD([Miscellaneous], [prrte], [], [$opal_prrte_mode]) + AC_SUBST(OMPI_PRRTE_RST_CONTENT_DIR) + AC_SUBST(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR) + AM_CONDITIONAL(OMPI_HAVE_PRRTE_RST, [test $OMPI_HAVE_PRRTE_RST -eq 1]) + + OPAL_SUMMARY_ADD([Miscellaneous], [PRRTE], [], [$opal_prrte_mode]) OPAL_VAR_SCOPE_POP ]) - dnl _OMPI_SETUP_PRRTE_INTERNAL([action-if-success], [action-if-not-success]) dnl dnl Attempt to configure the built-in PRRTE. @@ -220,7 +239,15 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_INTERNAL], [ [AC_MSG_ERROR([PRRTE configuration failed. Cannot continue.])]) AS_IF([test "$internal_prrte_happy" = "yes"], - [$1], [$2]) + [AC_MSG_CHECKING([for internal PRRTE RST files]) + AS_IF([test -n "$SPHINX_BUILD"], + [OMPI_HAVE_PRRTE_RST=1 + OMPI_PRRTE_RST_CONTENT_DIR="$OMPI_TOP_SRCDIR/3rd-party/prrte/src/docs/prrte-rst-content" + OMPI_SCHIZO_OMPI_RST_CONTENT_DIR="$OMPI_TOP_SRCDIR/3rd-party/prrte/src/mca/schizo/ompi" + AC_MSG_RESULT([found])], + [AC_MSG_RESULT([not found])]) + $1], + [$2]) OPAL_VAR_SCOPE_POP ]) @@ -284,9 +311,27 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_EXTERNAL], [ [AC_DEFINE_UNQUOTED([OMPI_PRTERUN_PATH], ["${prterun_path}"], [Path to prterun])]) AS_IF([test "$setup_prrte_external_happy" = "yes"], - [$1], [$2]) + [ # Determine if this external PRRTE has installed the RST + # directories that we care about + + AC_MSG_CHECKING([for external PRRTE RST files]) + prrte_install_dir=${with_prrte}/share/prte/rst + AS_IF([test -n "$SPHINX_BUILD"], + [AS_IF([test -d "$prrte_install_dir/prrte-rst-content" && \ + test -d "$prrte_install_dir/schizo-ompi-rst-content"], + [OMPI_HAVE_PRRTE_RST=1 + OMPI_PRRTE_RST_CONTENT_DIR="$prrte_install_dir/prrte-rst-content" + OMPI_SCHIZO_OMPI_RST_CONTENT_DIR="$prrte_install_dir/schizo-ompi-rst-content" + AC_MSG_RESULT([found]) + ], + [ # This version of PRRTE doesn't have installed RST + # files. + AC_MSG_RESULT([not found]) + OMPI_HAVE_PRRTE_RST=0 + ]) + ]) + $1], + [$2]) OPAL_VAR_SCOPE_POP ]) - - diff --git a/configure.ac b/configure.ac index 7c3c3936c3b..f03bdaf268c 100644 --- a/configure.ac +++ b/configure.ac @@ -28,6 +28,7 @@ # Copyright (c) 2018 FUJITSU LIMITED. All rights reserved. # Copyright (c) 2019 Triad National Security, LLC. All rights # reserved. +# Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. # $COPYRIGHT$ # # Additional copyrights may follow @@ -1072,7 +1073,7 @@ AS_IF([test -z "$LEX" || \ dnl Note that we have to double escape the URL below dnl so that the # it contains doesn't confuse the Autotools -OAC_SETUP_SPHINX([$srcdir/docs/_build/man/MPI_T.3], +OAC_SETUP_SPHINX([$srcdir/docs/man/MPI_T.3], [[https://docs.open-mpi.org/en/main/developers/prerequisites.html#sphinx-and-therefore-python]]) # diff --git a/docs/Makefile.am b/docs/Makefile.am index 3aa2b3b960f..dc9a085e99e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,6 +1,7 @@ # # Copyright (c) 2022 Cisco Systems, Inc. All rights reserved. # +# Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. # $COPYRIGHT$ # # Additional copyrights may follow @@ -26,7 +27,7 @@ .NOTPARALLEL: OUTDIR = _build -SPHINX_CONFIG = conf.py +SPHINX_CONFIG = $(srcdir)/conf.py SPHINX_OPTS ?= -W --keep-going -j auto # Note: it is significantly more convenient to list all the source @@ -58,6 +59,9 @@ RST_SOURCE_FILES = \ EXTRA_DIST = \ requirements.txt \ + no-prrte-content.rst.txt \ + html \ + man \ $(SPHINX_CONFIG) \ $(TEXT_SOURCE_FILES) \ $(IMAGE_SOURCE_FILES) \ @@ -784,27 +788,48 @@ OSHMEM_MAN3 = \ MAN_OUTDIR = $(OUTDIR)/man +# If we're building the docs, then we install from the just-built +# docs. Otherwise, we install from the pre-built docs (i.e., the docs +# included in the tarball). +# +# NOTE: If we're in a git clone with a) no pre-built docs and b) +# Sphinx is not found, then both OPAL_BUILD_DOCS and OPAL_INSTALL_DOCS +# will be false, and the value of MAN_INSTALL_FROM will not not used. +if OPAL_BUILD_DOCS +MAN_INSTALL_FROM = $(MAN_OUTDIR) +HTML_INSTALL_FROM = $(OUTDIR)/html +else +MAN_INSTALL_FROM = man +HTML_INSTALL_FROM = html +endif + +# For each of the man page macros below: +# +# *_RST: the .rst source files +# *_BUILT: the files in the _build/man directory +# *_INSTALL_FROM: the files in either the _build/man/ directory (if we +# are building the Sphinx docs) or the man/ directory (if we are not +# building the Sphinx docs, and are using the pre-built docs that +# are included in the tarballl). OMPI_MAN1_RST = $(OMPI_MAN1:%.1=man-openmpi/man1/%.1.rst) OMPI_MAN1_BUILT = $(OMPI_MAN1:%.1=$(MAN_OUTDIR)/%.1) +OMPI_MAN1_INSTALL_FROM = $(OMPI_MAN1:%.1=$(MAN_INSTALL_FROM)/%.1) OMPI_MAN3_RST = $(OMPI_MAN3:%.3=man-openmpi/man3/%.3.rst) OMPI_MAN3_BUILT = $(OMPI_MAN3:%.3=$(MAN_OUTDIR)/%.3) +OMPI_MAN3_INSTALL_FROM = $(OMPI_MAN3:%.3=$(MAN_INSTALL_FROM)/%.3) OMPI_MAN7_RST = $(OMPI_MAN7:%.7=man-openmpi/man7/%.7.rst) OMPI_MAN7_BUILT = $(OMPI_MAN7:%.7=$(MAN_OUTDIR)/%.7) +OMPI_MAN7_INSTALL_FROM = $(OMPI_MAN7:%.7=$(MAN_INSTALL_FROM)/%.7) OSHMEM_MAN1_RST = $(OSHMEM_MAN1:%.1=man-oshmem/man1/%.1.rst) OSHMEM_MAN1_BUILT = $(OSHMEM_MAN1:%.1=$(MAN_OUTDIR)/%.1) +OSHMEM_MAN1_INSTALL_FROM = $(OSHMEM_MAN1:%.1=$(MAN_INSTALL_FROM)/%.1) OSHMEM_MAN3_RST = $(OSHMEM_MAN3:%.3=man-oshmem/man3/%.3.rst) OSHMEM_MAN3_BUILT = $(OSHMEM_MAN3:%.3=$(MAN_OUTDIR)/%.3) - -EXTRA_DIST += \ - $(OMPI_MAN1_BUILT) \ - $(OMPI_MAN3_BUILT) \ - $(OMPI_MAN7_BUILT) \ - $(OSHMEM_MAN1_BUILT) \ - $(OSHMEM_MAN3_BUILT) +OSHMEM_MAN3_INSTALL_FROM = $(OSHMEM_MAN3:%.3=$(MAN_INSTALL_FROM)/%.3) ########################################################################### @@ -845,49 +870,202 @@ EXTRA_DIST += \ $(OSHMEM_MAN1_CXX_REDIRECTS) \ $(OSHMEM_MAN1_FORTRAN_REDIRECTS) + +########################################################################### + +ALL_MAN_BUILT = \ + $(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN7_BUILT) \ + $(OSHMEM_MAN1_BUILT) $(OSHMEM_MAN_3_BUILT) + +# These 2 targets are used in EXTRA_DIST: we make a full copy of the +# built HTML and man docs into a separate location that is included in +# the tarball. This gives users a fully copy of the docs included in +# distribution tarballs. +html: $(ALL_MAN_BUILT) + $(OMPI_V_COPYALL) rm -rf html; cp -rp $(OUTDIR)/html . + +man: $(ALL_MAN_BUILT) + $(OMPI_V_COPYALL) rm -rf man; cp -rp $(OUTDIR)/man . + +# Remove the copies of the built HTML and man pages to get back to a +# clean git clone. +maintainer-clean-local: + rm -rf html man + +# If we're doing a VPATH build, we may have "html" and "man" +# directories in the build tree (e.g., if we did "make dist"). Remove +# these copies so that we can pass distcheck (of course: we never +# remove these directories from the source tree). +distclean-local: + if test "$(srcdir)" != "$(builddir)"; then \ + rm -rf html man; \ + fi + ########################################################################### if OPAL_BUILD_DOCS include $(top_srcdir)/Makefile.ompi-rules -# Have to not list these targets in EXTRA_DIST outside of the -# OPAL_BUILD_DOCS conditional because "make dist" will fail due to -# these missing targets (and therefore not run the "dist-hook" target -# in the top-level Makefile, which prints a pretty message about why -# "make dist" failed). +# Copy over the PRRTE RST files to this build tree. # -# We list the entire directory trees (html and man) to grab all -# generated files in them. -EXTRA_DIST += \ - $(OUTDIR)/html \ - $(OUTDIR)/man +# 1. If we're building with PRRTE support: +# +# 1a. If we're building the internal/bundled PRRTE, then we'll copy +# the internal/bundled PRRTE's RST files to the build tree. +# 1b. If we're building against an external PRRTE installation that +# has RST files in its install tree, then we'll copy that +# external PRRTE's RST files to the build tree. +# 1c. If we're building against an external PRRTE installation that +# does NOT have RST files in its install tree, then we'll +# create some dummy RST files instead. +# +# 2. If we're building without PRRTE support, we'll create some dummy +# RST files instead. +# +# NOTE: We specifically list $(builddir) in the target name, just to +# ensure that "make" doesn't accidentally find this directory in the +# VPATH srcdir, and therefore not execute this rule (because Sphinx +# does not understand VPATH, and will ignore this directory in the +# VPATH srcdir). We can have this directory in the srcdir by doing a +# VPATH build of an official distribution tarball. -ALL_MAN_BUILT = \ - $(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN7_BUILT) \ - $(OSHMEM_MAN1_BUILT) $(OSHMEM_MAN_3_BUILT) +# Make the 2 directories that we need: schizo-ompi-rst-content and +# prrte-rst-content. +$(builddir)/schizo-ompi-rst-content: + $(OMPI_V_MKDIR) if test ! -d "$@"; then mkdir "$@"; fi +$(builddir)/prrte-rst-content: + $(OMPI_V_MKDIR) if test ! -d "$@"; then mkdir "$@"; fi + +# Get the schizo-ompi-rst-cli.rst file that we need. CAVEAT: we name +# it ".in" so that Sphinx doesn't slurp it in via two different +# locations in the RST docroot (i.e., via +# /schizo-ompi-rst-content/schizo-ompi-cli.rstxt and via +# /man-openmpi/man1/mpirun.1.rst). Sphinx *shouldn't* do this -- it +# should see the ".. include...." directive in mpirun.1.rst and *only* +# include the file once. But somehow it's also seeing it a 2nd time. +# So -- fine. We'll name it something other than .rst so that Sphinx +# doesn't do that. +# +# Regardless, either copy this file from the PRRTE install tree or +# make a bogus one (if we don't have one in the PRRTE install tree). +# +# Also, note: the rule to make the $(builddir)/schizo-ompi-rst-content +# directory must be in the AM_CONDITIONAL here, otherwise Automake +# complains. Meaning: we have to have same dependency listed in both +# the "if" and the "else" blocks. Grumble. +if OMPI_HAVE_PRRTE_RST +$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(builddir)/schizo-ompi-rst-content +$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)/* + $(OMPI_V_SPHINX_COPYRST) \ + dir=`dirname $@`; \ + cp -rpf $(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)/* "$$dir" +else +$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(builddir)/schizo-ompi-rst-content +$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(srcdir)/no-prrte-content.rst.txt + if test ! -d "$$dir"; then mkdir "$$dir"; fi + $(OMPI_V_SPHINX_COPYRST) \ + dir=`dirname $@`; \ + cp -pf $(srcdir)/no-prrte-content.rst.txt "$$dir" +endif + +$(ALL_MAN_BUILT): $(builddir)/prrte-rst-content +$(ALL_MAN_BUILT): $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt $(ALL_MAN_BUILT): $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES) $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG) +# Render the RST source into both 1) full HTML docs and 2) nroff man +# pages. +# # List both commands (HTML and man) in a single rule because they # really need to be run in serial. Specifically, if they were two # different rules and someone ran "make -j", then both of them could # be writing to $(OUTDIR)/doctrees simultaneously, which would be Bad. # Use one of the man pages as a sentinel file to indicate whether all # the HTML docs and man pages have been built. +# +# It's therefore a little bit of a lie to have the target named +# $(ALL_MAN_BUILT) *also* generate all the HTML content, but... so be +# it. +# +# Also note that Open MPI's RST includes some conditional RST (from +# PRRTE -- i.e., whether we get the source RST from the internal +# PRRTE, an external PRRTE, or whether we create RST files from +# scratch). These conditionals mean that we have to make some changes +# to the input Sphinx RST tree before building it. But -- by Automake +# convention -- we can't modify the source tree. Hence, we have to +# copy over all the source RST files -- including its internal +# directory structure -- to the build tree, and then make our desired +# changes here in the build tree. This is a bit ugly, but we could +# not think of anything better to do. +# +# NOTE: This is a little gross in that for a VPATH build, we *always* +# copy from the source tree to the dest tree (if the target does not +# exist or any of the sources in the source tree -- thanks to +# make/VPATH handling -- have changed compared to the target). +# However, we're using "cp -p", so even though we're copying *all the +# sources* from the source tree to the build tree, the timestamp will +# reflect what is in the source tree. Hence, if the source file has +# not changed, then it won't look like the file in the build tree has +# changed. We're going to overwrite any local changes in the build +# tree, but you shouldn't be editing the build tree, anyway. So -- +# good enough. +# +# Finally, one added wrinkle: only copy the RST source files in +# prrte-rst-content that are referenced by ".. include::" in the +# schizo-ompi-cli.rstxt file. We do this because Sphinx complains if +# there are .rst files that are not referenced. :-( $(ALL_MAN_BUILT): - $(OMPI_V_SPHINX_HTML) $(SPHINX_BUILD) -M html "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS) - $(OMPI_V_SPHINX_MAN) $(SPHINX_BUILD) -M man "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS) + $(OMPI_V_SPHINX_COPYRST) if test "$(srcdir)" != "$(builddir)"; then \ + len=`echo "$(srcdir)/" | wc -c`; \ + for file in $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES) $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG); do \ + dir=`dirname $$file | cut -c$$len-`; \ + if test -z "$$dir"; then \ + dir=.; \ + fi; \ + if test ! -d "$$dir"; then \ + mkdir -p "$$dir"; \ + fi; \ + cp -p "$$file" "$$dir"; \ + done; \ + fi; \ + for file in `fgrep '.. include::' $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt | awk '{ print $$3 }'`; do \ + filename=`basename $$file`; \ + cp -pf $(OMPI_PRRTE_RST_CONTENT_DIR)/$$filename "$(builddir)/prrte-rst-content"; \ + done + $(OMPI_V_SPHINX_HTML) OMPI_VERSION_FILE=$(top_srcdir)/VERSION $(SPHINX_BUILD) -M html "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS) + $(OMPI_V_SPHINX_MAN) OMPI_VERSION_FILE=$(top_srcdir)/VERSION $(SPHINX_BUILD) -M man "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS) # A useful rule to invoke manually to ensure that all of the external # HTML links we have are valid. Running this rule requires # connectivity to the general internet. linkcheck: - $(SPHINX_BUILD) -M linkcheck "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS) + $(SPHINX_BUILD) -M linkcheck "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS) .PHONY: linkcheck -maintainer-clean-local: - $(SPHINX_BUILD) -M clean "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS) +# Since we are building the docs, we built $(OUTDIR). Hence, we need +# to delete it during "make clean". Note that we can't add +# directories to CLEANFILES, because Automake only (effectively) does +# "rm -f $(CLEANFILES)" (not "rm -rf ..."). So we have to delete +# directories ourselves. +# +# Also, if this is a VPATH build, then we made a copy of a bunch of +# RST source files to the build tree. So delete all of those, too. +clean-local: + rm -rf $(OUTDIR) + rm -rf prrte-rst-content schizo-ompi-rst-content + if test "$(srcdir)" != "$(builddir)"; then \ + len=`echo "$(srcdir)/" | wc -c`; \ + for file in $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES) $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG); do \ + dir=`dirname $$file | cut -c$$len-`; \ + if test -z "$$dir"; then \ + rm -rf `basename $$file`; \ + fi; \ + if test -n "$$dir" && test -d "$$dir"; then \ + rm -rf "$$dir"; \ + fi; \ + done; \ + fi # List all the built man pages here in the Automake BUILT_SOURCES # macro. This hooks into the normal Automake build mechanisms, and @@ -901,7 +1079,7 @@ endif OPAL_BUILD_DOCS if OPAL_INSTALL_DOCS man1_MANS = \ - $(OMPI_MAN1_BUILT) \ + $(OMPI_MAN1_INSTALL_FROM) \ $(OMPI_MAN1_C_REDIRECTS) if OMPI_HAVE_CXX_COMPILER man1_MANS += $(OMPI_MAN1_CXX_REDIRECTS) @@ -913,12 +1091,12 @@ if OMPI_WANT_JAVA_BINDINGS man1_MANS += $(OMPI_MAN1_JAVA_REDIRECTS) endif -man3_MANS = $(OMPI_MAN3_BUILT) -man7_MANS = $(OMPI_MAN7_BUILT) +man3_MANS = $(OMPI_MAN3_INSTALL_FROM) +man7_MANS = $(OMPI_MAN7_INSTALL_FROM) if PROJECT_OSHMEM man1_MANS += \ - $(OSHMEM_MAN1_BUILT) \ + $(OSHMEM_MAN1_INSTALL_FROM) \ $(OSHMEM_MAN1_C_REDIRECTS) # There is no OSHMEM equivalent of this conditional; just use the OMPI # conditional. @@ -929,7 +1107,7 @@ if OSHMEM_BUILD_FORTRAN_BINDINGS man1_MANS += $(OSHMEM_MAN1_FORTRAN_REDIRECTS) endif -man3_MANS += $(OSHMEM_MAN3_BUILT) +man3_MANS += $(OSHMEM_MAN3_INSTALL_FROM) endif # We do not know the names of all the generated HTML files: we only @@ -945,19 +1123,29 @@ endif # Automake-provided install macros to set desirable permissions on the # target directories and files. # -# Since this might be a VPATH build, first check to see if _build/html -# exists in the source tree. If not, do the find+install from the -# build tree. +# Check to see if we actually built the docs. If we did, copy from +# the _build/html tree in the builddir. In all other cases, see if +# there's a _build/html in the source tree (e.g., if this is a build +# from a tarball that included a _build/html); if that exists, copy +# from that. +# +# NOTE: We can't use the AM_CONDITIONAL OPAL_BUILD_DOCS in the middle +# of a block that uses the shell continuation character at the end of +# each line. Instead, we check if $(SPHINX_BUILD) is non-empty, which +# is the test used to construct OPAL_BUILD_DOCS. install-data-hook: $(MKDIR_P) $(DESTDIR)$(docdir) - if test -d $(srcdir)/_build/html; then \ - topdir=$(srcdir)/_build; \ - else \ - topdir=_build; \ + topdir= ; \ + if test -n "$(SPHINX_BUILD)" && test -d $(builddir)/$(HTML_INSTALL_FROM); then \ + topdir="$(builddir)/$(HTML_INSTALL_FROM)"; \ + elif test -d $(srcdir)/$(HTML_INSTALL_FROM); then \ + topdir="$(srcdir)/$(HTML_INSTALL_FROM)"; \ fi; \ - cd $$topdir; \ - find html -type d -exec $(mkinstalldirs) $(DESTDIR)$(docdir)/{} \; ; \ - find html -type f -exec $(INSTALL_DATA) {} $(DESTDIR)$(docdir)/{} \; + if test -n "$$topdir"; then \ + cd $$topdir/..; \ + find html -type d -exec $(mkinstalldirs) $(DESTDIR)$(docdir)/{} \; ; \ + find html -type f -exec $(INSTALL_DATA) {} $(DESTDIR)$(docdir)/{} \; ; \ + fi uninstall-hook: rm -rf $(DESTDIR)$(docdir) diff --git a/docs/conf.py b/docs/conf.py index bf192f5356b..b8b7e8c4690 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,9 +10,7 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os # -- Project information ----------------------------------------------------- @@ -24,8 +22,20 @@ author = 'The Open MPI Community' # The full version, including alpha/beta/rc tags -# Read the Open MPI version from the VERSION file -with open("../VERSION") as fp: +# Read the Open MPI version from the VERSION file in the source tree +# The docs/Makefile.am will set the env var OMPI_VERSION_FILE, because +# we might be doing a VPATH build. +filename = None +if 'OMPI_VERSION_FILE' in os.environ: + filename = os.environ['OMPI_VERSION_FILE'] +elif os.path.exists("../VERSION"): + filename = '../VERSION' + +if filename is None: + print("ERROR: Could not find Open MPI source tree VERSION file") + exit(1) + +with open(filename) as fp: ompi_lines = fp.readlines() ompi_data = dict() diff --git a/docs/index.rst b/docs/index.rst index a1f7d0b6d2f..c339c213622 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,9 +28,13 @@ Documentation for Open MPI can be found in the following locations: * - v5.0.0 and later - Web: https://docs.open-mpi.org/ - Tarball: ``docs/_build/html/index.html`` + Included in tarball: ``docs/html/index.html`` - Installed: ``$prefix/share/doc/openmpi/html/index.html`` + Built in source tree (if Sphinx available): ``docs/_build/html/index.html`` + + Installed: ``$docdir/html/index.html`` + + (which defaults to: ``$prefix/share/doc/openmpi/html/index.html``) * - v4.1.x and earlier - See the `legacy Open MPI FAQ `_ diff --git a/docs/installing-open-mpi/packagers.rst b/docs/installing-open-mpi/packagers.rst index 6435abded08..e43d52b101a 100644 --- a/docs/installing-open-mpi/packagers.rst +++ b/docs/installing-open-mpi/packagers.rst @@ -1,3 +1,5 @@ +.. _label-install-packagers: + Advice for packagers ==================== @@ -20,9 +22,26 @@ the following: .. code-block:: sh + # Install Sphinx so that Open MPI can re-build its docs with the + # installed PRRTE's docs + + virtualalenv venv + . ./venv/bin/activate + pip install docs/requirements.txt + ./configure --with-libevent=external --with-hwloc=external \ --with-pmix=external --with-prrte=external ... +.. important:: Note the installation of the Sphinx tool so that Open + MPI can re-build its documentation with the external + PRRTE's documentation. + + Failure to do this will mean Open MPI's documentation + will be correct for the version of PRRTE that is + bundled in the Open MPI distribution, but may not be + entirely correct for the version of PRRTE that you are + building against. + The ``external`` keywords will force Open MPI's ``configure`` to ignore all the bundled libraries and only look for external versions of these support libraries. This also has the benefit of causing @@ -36,6 +55,29 @@ independently-built and installed versions. information about the required support library ``--with-FOO`` command line options. +Have Sphinx installed +--------------------- + +Since you should be (will be) installing Open MPI against an external +PRRTE and PMIx, you should have `Sphinx +`_ installed before running Open MPI's +``configure`` script. + +This will allow Open MPI to (re-)build its documentation according to +the PMIx and PRRTE that you are building against. + +To be clear: the Open MPI distribution tarball comes with pre-built +documentation |mdash| rendered in HTML and nroff |mdash| that is +suitable for the versions of PRRTE and PMIx that are bundled in that +tarball. + +However, if you are building Open MPI against not-bundled versions of +PRRTE / PMIx (as all packagers should be), Open MPI needs to re-build +its documentation with specific information from those external PRRTE +/ PMIx installs. For that, you need to have Sphinx installed before +running Open MPI's ``configure`` script. + + .. _label-install-packagers-dso-or-not: Components ("plugins"): DSO or no? diff --git a/docs/installing-open-mpi/required-support-libraries.rst b/docs/installing-open-mpi/required-support-libraries.rst index 9e02297998b..b411e1a02f5 100644 --- a/docs/installing-open-mpi/required-support-libraries.rst +++ b/docs/installing-open-mpi/required-support-libraries.rst @@ -399,6 +399,5 @@ Open MPI package should not include Hwloc, Libevent, PMIx, or PRRTE. Instead, it should depend on external, independently-built versions of these packages. -See the :ref:`Advice for packagers -` section for more -details. +See the :ref:`Advice for packagers ` section +for more details. diff --git a/docs/man-openmpi/man1/mpirun.1.rst b/docs/man-openmpi/man1/mpirun.1.rst index 66a0e75c269..c9168b60076 100644 --- a/docs/man-openmpi/man1/mpirun.1.rst +++ b/docs/man-openmpi/man1/mpirun.1.rst @@ -60,15 +60,17 @@ probably want to use a command line of the following form: This will run ``X`` copies of ```` in your current run-time environment (if running under a supported resource manager, Open MPI's -mpirun will usually automatically use the corresponding resource -manager process starter, as opposed to, for example, ``rsh`` or ``ssh``, which -require the use of a hostfile, or will default to running all ``X`` copies -on the localhost), scheduling (by default) in a round-robin fashion by -CPU slot. See the rest of this page for more details. - -Please note that mpirun automatically binds processes as of the start -of the v1.8 series. Three binding patterns are used in the absence of -any further directives (See :ref:`map/rank/bind defaults ` for more details): +``mpirun`` will usually automatically use the corresponding resource +manager process starter, as opposed to ``ssh`` (for example), which +require the use of a hostfile, or will default to running all ``X`` +copies on the localhost), scheduling (by default) in a round-robin +fashion by CPU slot. See the rest of this documentation for more +details. + +Please note that ``mpirun`` automatically binds processes to hardware +resources. Three binding patterns are used in the absence of any +further directives (See :ref:`map/rank/bind defaults +` for more details): * **Bind to core**: when the number of processes is <= 2 * **Bind to package**: when the number of processes is > 2 @@ -79,103 +81,43 @@ that you are either not bound at all (by specifying ``--bind-to none``), or bound to multiple cores using an appropriate binding level or specific number of processing elements per application process. -.. _man1-mpirun-definition-of-slot: - -DEFINITION OF 'SLOT' --------------------- - -The term "slot" is used extensively in the rest of this manual page. -A slot is an allocation unit for a process. The number of slots on a -node indicate how many processes can potentially execute on that node. -By default, Open MPI will allow one process per slot. - -If Open MPI is not explicitly told how many slots are available on a -node (e.g., if a hostfile is used and the number of slots is not -specified for a given node), it will determine a maximum number of -slots for that node in one of two ways: - -#. Default behavior: By default, Open MPI will attempt to discover the - number of processor cores on the node, and use that as the number - of slots available. - -#. When ``--use-hwthread-cpus`` is used: If ``--use-hwthread-cpus`` is - specified on the ``mpirun`` command line, then Open MPI will attempt to - discover the number of hardware threads on the node, and use that - as the number of slots available. - -This default behavior also occurs when specifying the ``--host`` -option with a single host. Thus, the command: - -.. code:: sh - - shell$ mpirun --host node1 ./a.out - -launches a number of processes equal to the number of cores on node -``node1``, whereas: - -.. code:: sh - - shell$ mpirun --host node1 --use-hwthread-cpus ./a.out - -launches a number of processes equal to the number of hardware -threads on ``node1``. - -When Open MPI applications are invoked in an environment managed by a -resource manager (e.g., inside of a Slurm job), and Open MPI was built -with appropriate support for that resource manager, then Open MPI will -be informed of the number of slots for each node by the resource -manager. For example: - -.. code:: sh - - shell$ mpirun ./a.out - -launches one process for every slot (on every node) as dictated by -the resource manager job specification. - -Also note that the one-process-per-slot restriction can be overridden -in unmanaged environments (e.g., when using hostfiles without a -resource manager) if oversubscription is enabled (by default, it is -disabled). Most MPI applications and HPC environments do not -oversubscribe; for simplicity, the majority of this documentation -assumes that oversubscription is not enabled. - -Slots are not hardware resources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +OPEN MPI'S USE OF PRRTE +----------------------- -Slots are frequently incorrectly conflated with hardware resources. -It is important to realize that slots are an entirely different metric -than the number (and type) of hardware resources available. +Open MPI uses the PMIx Reference Runtime Environment (PRRTE) as the +main engine for launching, monitoring, and terminating MPI processes. -Here are some examples that may help illustrate the difference: +Much of the documentation below is directly imported from PRRTE. As +such, it frequently refers to PRRTE concepts and command line options. +Except where noted, these concepts and command line argument are all +applicable to Open MPI as well. Open MPI extends the available PRRTE +command line options, and also slightly modifies the PRRTE's default +behaviors in a few cases. These will be specifically described in the +docuemtnation below. -#. More processor cores than slots: Consider a resource manager job - environment that tells Open MPI that there is a single node with 20 - processor cores and 2 slots available. By default, Open MPI will - only let you run up to 2 processes. - - Meaning: you run out of slots long before you run out of processor - cores. +COMMAND LINE OPTIONS +-------------------- -#. More slots than processor cores: Consider a hostfile with a single - node listed with a ``slots=50`` qualification. The node has 20 - processor cores. By default, Open MPI will let you run up to 50 - processes. +The core of Open MPI's ``mpirun`` processing is performed via the +`PRRTE `_. Specifically: ``mpirun`` is +effectively a wrapper around ``prterun``, but ``mpirun``'s CLI options +are slightly different than PRRTE's CLI commands. - Meaning: you can run many more processes than you have processor - cores. +.. include:: /schizo-ompi-rst-content/schizo-ompi-cli.rstxt -.. _man1-mpirun-definition-of-processor-element: +OPTIONS (OLD / HARD-CODED CONTENT -- TO BE AUDITED +-------------------------------------------------- -DEFINITION OF 'PROCESSOR ELEMENT' ---------------------------------- +.. admonition:: This is old content + :class: error -By default, Open MPI defines that a "processing element" is a -processor core. However, if ``--use-hwthread-cpus`` is specified on the -mpirun command line, then a "processing element" is a hardware thread. + This is the old section of manually hard-coded content. It should + probably be read / audited and see what we want to keep and what we + want to discard. -OPTIONS -------- + Feel free to refer to https://docs.prrte.org/ rather than + replicating content here (e.g., for the definition of a slot and + other things). mpirun will send the name of the directory where it was invoked on the local node to each of the remote nodes, and attempt to change to that @@ -251,10 +193,11 @@ processes will be bound to the package. context. If no value is provided for the number of copies to execute (i.e., neither the ``-n`` nor its synonyms are provided on the command line), Open MPI will automatically execute a copy of the - program on each process slot (see :ref:`defintion of slot ` for description of a - "process slot"). This feature, however, can only be used in the SPMD - model and will return an error (without beginning execution of the - application) otherwise. + program on each process slot (see PRRTE's `defintion of "slot" + `_ + for description of a "process slot"). This feature, however, can + only be used in the SPMD model and will return an error (without + beginning execution of the application) otherwise. .. note:: The ``-n`` option is the preferred option to be used to specify the number of copies of the program to be executed, but the alternate @@ -280,7 +223,7 @@ To map processes: * ``--map-by ``: Map to the specified object, defaults to ``package``. Supported options include ``slot``, ``hwthread``, ``core``, ``L1cache``, ``L2cache``, ``L3cache``, ``package``, ``numa``, - ``node``, ``seq``, ``rankfile``, ``pe-list=#``, and ``ppr``. + ``node``, ``seq``, ``rankfile``, ``pe-list=#``, and ``ppr``. Any object can include modifiers by adding a ``:`` and any combination of the following: @@ -561,13 +504,17 @@ There are also other options: Note that if a number of slots is not provided to Open MPI (e.g., via the ``slots`` keyword in a hostfile or from a resource manager such as Slurm), the use of this option changes the default - calculation of number of slots on a node. See the :ref:`DEFINITION - OF 'SLOT' ` section. + calculation of number of slots on a node. See the PRRTE's + `defintion of "slot" + `_ + for more details. Also note that the use of this option changes the Open MPI's definition of a "processor element" from a processor core to a - hardware thread. See the :ref:`DEFINITION OF 'PROCESSOR ELEMENT' - ` section. + hardware thread. See + PRRTE's `defintion of a "processor element" + `_ + for more details. The following options are useful for developers; they are not generally useful to most Open MPI users: @@ -601,11 +548,23 @@ There may be other options listed with ``mpirun --help``. Environment Variables ^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + * ``MPIEXEC_TIMEOUT``: Synonym for the ``--timeout`` command line option. DESCRIPTION ----------- +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + One invocation of ``mpirun`` starts an MPI application running under Open MPI. If the application is single process multiple data (SPMD), the application can be specified on the ``mpirun`` command line. @@ -630,6 +589,12 @@ while others are specific to a single program (e.g., ``-n``). Specifying Host Nodes ^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + Host nodes can be identified on the ``mpirun`` command line with the ``--host`` option or in a hostfile. @@ -679,6 +644,12 @@ from the resource manager. Specifying Number of Processes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + As we have just seen, the number of processes to run can be set using the hostfile. Other mechanisms exist. @@ -733,6 +704,12 @@ the ``-n`` option indicated that only 6 processes should be launched. Mapping Processes to Nodes: Using Policies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + The examples above illustrate the default mapping of process processes to nodes. This mapping can also be controlled with various ``mpirun`` options that describe mapping policies. @@ -845,6 +822,12 @@ and 2 each running uptime on nodes ``bb`` and ``cc``, respectively. Mapping, Ranking, and Binding: Oh My! ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + Open MPI employs a three-phase procedure for assigning process locations and ranks: @@ -934,7 +917,7 @@ Alternatively, processes can be mapped and bound to specified cores using the ``--map-by pe-list=`` option. For example, ``--map-by pe-list=0,2,5`` will map three processes all three of which will be bound to logical cores ``0,2,5``. If you intend to bind each of the three processes to different -cores then the ``:ordered`` qualifier can be used like +cores then the ``:ordered`` qualifier can be used like ``--map-by pe-list=0,2,5:ordered``. In this example, the first process on a node will be bound to CPU 0, the second process on the node will be bound to CPU 2, and the third process on the node will be bound to @@ -992,7 +975,7 @@ in ranking when the ``span`` qualifier is used instead of the default. In the above case, the output shows us that 2 cores have been bound per process. Specifically, the mapping by ``slot`` with the ``PE=2`` qualifier indicated that each slot (i.e., process) should consume two processor -elements. By default, Open MPI defines "processor element" as "core", +elements. By default, Open MPI defines "processor element" as "core", and therefore the ``--bind-to core`` caused each process to be bound to both of the cores to which it was mapped. @@ -1030,16 +1013,16 @@ MCA parameters can be set not only on the mpirun command line, but alternatively in a system or user ``mca-params.conf`` file or as environment variables, as described in the :ref:`Setting MCA Parameters `. These are MCA parameters for -the PRRTE runtime so the command line argument ``--PRRTEmca`` must be used to +the PRRTE runtime so the command line argument ``--PRRTEmca`` must be used to pass the MCA parameter key/value pair. Alternatively, the MCA parameter key/ -value pair may be specific on the command line by prefixing the key with +value pair may be specific on the command line by prefixing the key with ``PRRTE_MCA_``. Some examples include: .. list-table:: :header-rows: 1 * - Option - - PRRTE MCA parameter key + - PRRTE MCA parameter key - Value * - ``--map-by core`` @@ -1071,6 +1054,12 @@ value pair may be specific on the command line by prefixing the key with Defaults for Mapping, Ranking, and Binding ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + If the user does not specify each of ``--map-by``, ``--rank-by``, and ``--bind-to`` option then the default values are as follows: * If no options are specified then @@ -1167,6 +1156,12 @@ The mapping pattern might be better seen if we change the default ``--rank-by`` Rankfiles ^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + Rankfiles are text files that specify detailed information about how individual processes should be mapped to nodes, and to which processor(s) they should be bound. Each line of a rankfile specifies @@ -1226,6 +1221,12 @@ indexes of package and cores. Application Context or Executable Program? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + To distinguish the two different forms, mpirun looks on the command line for ``--app`` option. If it is specified, then the file named on the command line is assumed to be an application context. If it is @@ -1234,6 +1235,12 @@ not specified, then the file is assumed to be an executable program. Locating Files ^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + If no relative or absolute path is specified for a file, Open MPI will first look for files by searching the directories specified by the ``--path`` option. If there is no ``--path`` option set or if the @@ -1252,6 +1259,12 @@ current working directory from the invocation of ``mpirun``. Current Working Directory ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + The ``--wdir`` ``mpirun`` option (and its synonym, ``--wd``) allows the user to change to an arbitrary directory before the program is invoked. It can also be used in application context files to specify @@ -1279,6 +1292,12 @@ does not wait until :ref:`MPI_INIT(3) ` is called. Standard I/O ^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + Open MPI directs UNIX standard input to ``/dev/null`` on all processes except the MPI_COMM_WORLD rank 0 process. The MPI_COMM_WORLD rank 0 process inherits standard input from ``mpirun``. @@ -1309,6 +1328,12 @@ will be collected into the ``my_output`` file. Signal Propagation ^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + When ``mpirun`` receives a SIGTERM and SIGINT, it will attempt to kill the entire job by sending all processes in the job a SIGTERM, waiting a small number of seconds, then sending all processes in the job a @@ -1326,6 +1351,12 @@ Other signals are not currently propagated by ``mpirun``. Process Termination / Signal Handling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + During the run of an MPI application, if any process dies abnormally (either exiting before invoking :ref:`MPI_FINALIZE(3) `, or dying as the result of a signal), ``mpirun`` will print out an @@ -1346,6 +1377,12 @@ safest) for the user to only clean up non-MPI state. Process Environment ^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + Processes in the MPI application inherit their environment from the PRRTE daemon upon the node on which they are running. The environment is typically inherited from the user's shell. On remote @@ -1365,6 +1402,12 @@ for more details. Remote Execution ^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + Open MPI requires that the ``PATH`` environment variable be set to find executables on remote nodes (this is typically only necessary in rsh- or ssh-based environments |mdash| batch/scheduled environments @@ -1431,6 +1474,12 @@ is equivalent to Exported Environment Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + All environment variables that are named in the form ``OMPI_*`` will automatically be exported to new processes on the local and remote nodes. Environmental parameters can also be set/forwarded to the new @@ -1448,6 +1497,12 @@ them. Setting MCA Parameters ^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + The ``--mca`` switch allows the passing of parameters to various MCA (Modular Component Architecture) modules. MCA modules have direct impact on MPI programs because they allow tunable parameters to be set @@ -1508,6 +1563,12 @@ page for detailed information on this command. Setting MCA parameters and environment variables from file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + The ``--tune`` command line option and its synonym ``--mca`` ``mca_base_envar_file_prefix`` allows a user to set MCA parameters and environment variables with the syntax described below. This option @@ -1532,6 +1593,12 @@ have higher precedence than variables specified in the file. Running as root ^^^^^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + .. warning:: The Open MPI team **strongly** advises against executing ``mpirun`` as the root user. MPI applications should be run as regular (non-root) users. @@ -1558,6 +1625,12 @@ against this behavior. Exit status ^^^^^^^^^^^ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + There is no standard definition for what ``mpirun`` should return as an exit status. After considerable discussion, we settled on the following method for assigning the ``mpirun`` exit status (note: in @@ -1599,6 +1672,12 @@ bullet points above). EXAMPLES -------- +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + Be sure also to see the examples throughout the sections above. .. code:: sh @@ -1613,6 +1692,12 @@ messages. RETURN VALUE ------------ +.. admonition:: This is old, hard-coded content + :class: error + + Is this content still current / accurate? Should it be updated and + retained, or removed? + ``mpirun`` returns 0 if all processes started by mpirun exit after calling :ref:`MPI_FINALIZE(3) `. A non-zero value is returned if an internal error occurred in mpirun, or one or more diff --git a/docs/news/news-v5.0.x.rst b/docs/news/news-v5.0.x.rst index bd1bc89ad57..749dfa1c7bf 100644 --- a/docs/news/news-v5.0.x.rst +++ b/docs/news/news-v5.0.x.rst @@ -154,9 +154,10 @@ Open MPI version 5.0.0rc12 - Many MPI one-sided and RDMA emulation fixes for the ``tcp`` BTL. - - This patch series fixs many issues when running with ``--mca - osc rdma --mca btl tcp``, i.e., TCP support for one sided - MPI calls. + This patch series fixs many issues when running with ``--mca + osc rdma --mca btl tcp``, i.e., TCP support for one sided + MPI calls. + - Many MPI one-sided fixes for the ``uct`` BTL. - Added support for ``acc_single_intrinsic`` to the one-sided ``ucx`` component. diff --git a/docs/no-prrte-content.rst.txt b/docs/no-prrte-content.rst.txt new file mode 100644 index 00000000000..ea034952d31 --- /dev/null +++ b/docs/no-prrte-content.rst.txt @@ -0,0 +1,24 @@ +.. This file is only used in certain cases. Hence, the original file + in the Open MPI "docs" source tree ends in ".txt", so that Sphinx + will not complain if it is not used. If it *is* used, it is copied + to another file (that ends in ".rst") so that it can be properly + found / used by Sphinx. + +No content +^^^^^^^^^^ + +There is no meaningful content in this file because Open MPI was either: + +* Built without PRRTE support. + +* Built with a PRRTE that was too old to include machine-readable + documentation that could be incorporated into Open MPI's + documentation. + +If you build Open MPI with a newer version of PRRTE (and have the +Sphinx tool available when you run Open MPI's ``configure`` command), +you should get more meaningful documentation here. + +Hence, there is no documentation for this section. + +Sorry! From c3569811ec7cb518bb202b7d2fbeb32b238ca3c2 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Sun, 10 Sep 2023 20:14:37 -0400 Subject: [PATCH 4/4] ReadTheDocs CI builds updates Since RTD doesn't run autogen, configure, or make, we now have to manually copy a few RST files from the embedded PRRTE to the docs/ tree before RTD invokes Sphinx. Signed-off-by: Jeff Squyres --- .readthedocs-pre-create-environment.sh | 36 ++++++++++++++++++++++++++ .readthedocs.yaml | 8 ++++++ 2 files changed, 44 insertions(+) create mode 100755 .readthedocs-pre-create-environment.sh diff --git a/.readthedocs-pre-create-environment.sh b/.readthedocs-pre-create-environment.sh new file mode 100755 index 00000000000..2709b822b80 --- /dev/null +++ b/.readthedocs-pre-create-environment.sh @@ -0,0 +1,36 @@ +#!/bin/bash + +set -euxo pipefail + +# The ReadTheDocs build process does not run autogen/configure/make. +# Hence, we have to copy the PRRTE RST files (from the 3rd-party/prrte +# tree) to our docs/ tree manually. + +# Ensure that we're in the RTD CI environment + +if [[ "${READTHEDOCS:-no}" == "no" ]]; then + echo "This script is only intended to be run in the ReadTheDocs CI environment" + exit 1 +fi + +SCHIZO_SRC_DIR=3rd-party/prrte/src/mca/schizo/ompi +SCHIZO_TARGET_DIR=docs/schizo-ompi-rst-content + +PRRTE_RST_SRC_DIR=3rd-party/prrte/src/docs/prrte-rst-content +PRRTE_RST_TARGET_DIR=docs/prrte-rst-content + +# Copy the OMPI schizo file from PRRTE + +cp -rp $SCHIZO_SRC_DIR $SCHIZO_TARGET_DIR + +# Only copy the PRRTE RST source files in prrte-rst-content that are +# referenced by ".. include::" in the schizo-ompi-cli.rst file. We do +# this because Sphinx complains if there are .rst files that are not +# referenced. :-( + +mkdir -p $PRRTE_RST_TARGET_DIR +files=`fgrep '.. include::' $SCHIZO_TARGET_DIR/schizo-ompi-cli.rstxt | awk '{ print $3 }'` +for file in $files; do + filename=`basename $file` + cp -pf $PRRTE_RST_SRC_DIR/$filename $PRRTE_RST_TARGET_DIR +done diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 44e0bbac5a7..2ba1fc07842 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,6 +12,11 @@ build: os: ubuntu-22.04 tools: python: "3.10" + jobs: + # RTD doesn't run configure or make. So we have to manually copy + # in the PRRTE RST files to docs/. + pre_create_environment: + - ./.readthedocs-pre-create-environment.sh python: install: @@ -21,3 +26,6 @@ python: sphinx: configuration: docs/conf.py fail_on_warning: true + +submodules: + include: all