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..72acad4bc58 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,29 @@ 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). Unfortunately, we can't AC REQUIRE it
+ # because the OAC SETUP SPHINX macro requires parameters. The
+ # only publicly-visible env variable that OAC SETUP SPHINX sets is
+ # $SPHINX_BUILD -- but it may be empty if sphinx-build
+ # legitimately can't be found. Sooo... we can't really tell here
+ # if OAC SETUP SPHINX has actually been invoked or not.
+
+ # 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 +121,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 +243,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 +315,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..6d7aaf8bbcf 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,175 @@ 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.
+$(builddir)/schizo-ompi-rst-content:
+ $(OMPI_V_MKDIR) mkdir "$@"
+if OMPI_HAVE_PRRTE_RST
+ $(OMPI_V_SPHINX_COPYRST) cp -r $(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)/* "$@"
+else
+ $(OMPI_V_GEN) cp -pf $(srcdir)/no-prrte-content.rst.txt "$@/schizo-ompi-cli.rst"
+endif
-ALL_MAN_BUILT = \
- $(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN7_BUILT) \
- $(OSHMEM_MAN1_BUILT) $(OSHMEM_MAN_3_BUILT)
+# See the comment above schizo-ompi-rst-content. One added wrinkle:
+# only copy the 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. :-(
+$(builddir)/prrte-rst-content: $(builddir)/schizo-ompi-rst-content
+ $(OMPI_V_MKDIR) mkdir "$@"
+if OMPI_HAVE_PRRTE_RST
+ $(OMPI_V_SPHINX_COPYRST) \
+ for file in `fgrep '.. include::' $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rst | awk '{ print $$3 }'`; do \
+ filename=`basename $$file`; \
+ cp -pf $(OMPI_PRRTE_RST_CONTENT_DIR)/$$filename "$@"; \
+ done
+endif
+
+$(ALL_MAN_BUILT): $(builddir)/prrte-rst-content
$(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.
$(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
+ $(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 +1052,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 +1064,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 +1080,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 +1096,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..9b07a7bd160 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.rst
-.. _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