From 0b04e2bb8d615bf5c0698fc9397c0686d5d759a4 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Sat, 12 Mar 2022 18:25:37 -0500 Subject: [PATCH 1/8] Trivial docs updates Minor updates to match the top-level index.rst verbiage on the v4.0.x and v4.1.x branches. Signed-off-by: Jeff Squyres --- docs/conf.py | 3 ++- docs/index.rst | 10 +++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 54abe622f2d..e6f2709d14f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,8 @@ ompi_data = dict() for ompi_line in ompi_lines: if '#' in ompi_line: - ompi_line, _ = ompi_line.split("#") + parts = ompi_line.split("#") + ompi_line = parts[0] ompi_line = ompi_line.strip() if '=' not in ompi_line: diff --git a/docs/index.rst b/docs/index.rst index 8c6a939b051..2e9438bb759 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,11 +14,10 @@ order to build the best MPI library available. Open MPI offers advantages for system and software vendors, application developers and computer science researchers. -Other documentation -=================== +Documentation locations +======================= -Documentation for other versions of Open can be found in the following -locations: +Documentation for Open can be found in the following locations: .. list-table:: :header-rows: 1 @@ -28,7 +27,8 @@ locations: * - v5.0.0 and later - Open MPI documentation has consolidated and moved to - ReadTheDocs.io. + + https://docs.open-mpi.org/. This particular documentation is for |ompi_ver|; use the selector in the From 76c69dd46f38f2de8076f88abc8784a872f57331 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Sat, 12 Mar 2022 19:26:30 -0500 Subject: [PATCH 2/8] docs: show version at top of first page Having the Open MPI version at the top of the front index page is a good, obvious visual indicator to the user to which version these docs apply. Usually, the version we display is derived from the contents of the VERSION file. However, when releasing Open MPI, we typically go back and create an annotated git tag at a commit prior to the head of the release branch. This means that there is no git commit where the VERSION file has an empty "greek" version. As such, use the following scheme to determine what version string to use for the RST macro "|ompi_ver|": 1. If there is an environment variable named READTHEDOCS_VERSION, use that (this env variable is documented here: https://docs.readthedocs.io/en/stable/builds.html#build-environment) 2. Otherwise, use the contents of the Open MPI VERSION file Signed-off-by: Jeff Squyres --- docs/conf.py | 66 ++++++++++++++++++++++++++++++++++++++++++++------ docs/index.rst | 4 +-- 2 files changed, 61 insertions(+), 9 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e6f2709d14f..37ba527f22c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,11 +41,63 @@ ompi_key, ompi_val = ompi_line.split("=") ompi_data[ompi_key.strip()] = ompi_val.strip() -# "release" is a sphinx config variable -- assign it to the computed -# Open MPI version number. -series = f"{ompi_data['major']}.{ompi_data['minor']}.x" -release = f"{ompi_data['major']}.{ompi_data['minor']}.{ompi_data['release']}{ompi_data['greek']}" - +ompi_series = f"v{ompi_data['major']}.{ompi_data['minor']}.x" +ompi_ver = f"v{ompi_data['major']}.{ompi_data['minor']}.{ompi_data['release']}{ompi_data['greek']}" + +# "release" is a sphinx config variable: assign it to the computed +# Open MPI version number. The ompi_ver string begins with a "v"; the +# Sphinx release variable should not include this prefix "v". +release = ompi_ver[1:] + +# If we are building in a ReadTheDocs.io environment, there will be a +# READTHEDOCS environment variables that tell us what version to use. +# Relevant RTD env variables (documented +# https://docs.readthedocs.io/en/stable/builds.html#build-environment): +# +# - READTHEDOCS: will be "True" +# - READTHEDOCS_VERSION: The RTD slug of the version which is being +# built (e.g., "latest") +# - READTHEDOCS_VERSION_NAME: Corresponding version name as displayed +# in RTD's version switch menu (e.g., "stable") +# - READTHEDOCS_VERSION_TYPE: Type of the event triggering the build +# (e.g., "branch", "tag", "external" (for PRs), or "unknown"). +# +# If we're building in an RTD environment for a tag or external (i.e., +# PR), use the RTD version -- not what we just read from the VERSIONS +# file. +import os +key = 'READTHEDOCS' +if key in os.environ and os.environ[key] == 'True': + print("OMPI: found ReadTheDocs build environment") + + rtd_v = os.environ['READTHEDOCS_VERSION'] + if os.environ['READTHEDOCS_VERSION_TYPE'] == 'external': + # Make "release" be shorter than the full "ompi_ver" value. + release = f'PR #{rtd_v}' + ompi_ver += f' (Github PR #{rtd_v})' + else: + ompi_ver = rtd_v + + # The "release" Sphinx variable is supposed to be expressed as + # a simple value, such as "A.B.C[rcX]" (without a leading + # "v"). The ompi_ver value will be one of two things: + # + # - a git branch name (of the form "vA.B.x") + # - a git tag (of the form "A.B.C[rcX]") + # + # If there's a leading "v", we need to strip it. + release = ompi_ver + if ompi_ver[0] == 'v': + release = ompi_ver[1:] + + # Override the branch names "master" and "main" (that would have + # come from the ReadTheDocs version slug) to be "head of + # development". + if release == 'main' or release == 'master': + ompi_ver = 'head of development' + + print(f"OMPI: release = {release}") + print(f"OMPI: ompi_ver = {ompi_ver}") # -- General configuration --------------------------------------------------- @@ -125,6 +177,6 @@ def _doit(topdir): .. |rarrow| unicode:: U+02192 .. Right arrow .. |year| replace:: {year} -.. |ompi_ver| replace:: v{release} -.. |ompi_series| replace:: v{series} +.. |ompi_ver| replace:: {ompi_ver} +.. |ompi_series| replace:: {ompi_series} """ diff --git a/docs/index.rst b/docs/index.rst index 2e9438bb759..f2d0d96473c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,8 @@ .. image:: openmpi_logo.png :align: right -Open MPI -======== +Open MPI |ompi_ver| +=================== `The Open MPI Project `_ is an open source implementation of the `Message Passing Interface (MPI) specification From 5feddf91ad9a2da466d9b78ac1ebc768868586bc Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Sun, 13 Mar 2022 07:33:18 -0400 Subject: [PATCH 3/8] docs compilers-and-flags.rst: minor cleanups Minor fixes and cleanups to the compilers-and-flags.rst page. Signed-off-by: Jeff Squyres --- .../compilers-and-flags.rst | 69 ++++++++++++------- 1 file changed, 44 insertions(+), 25 deletions(-) diff --git a/docs/installing-open-mpi/compilers-and-flags.rst b/docs/installing-open-mpi/compilers-and-flags.rst index f3ce7418826..3e1df4914b0 100644 --- a/docs/installing-open-mpi/compilers-and-flags.rst +++ b/docs/installing-open-mpi/compilers-and-flags.rst @@ -4,15 +4,18 @@ Specifying compilers and flags ============================== Changing the compilers that Open MPI uses to build itself uses the -standard Autoconf mechanism of setting special environment variables +standard GNU Autoconf mechanism of setting special environment variables either before invoking ``configure`` or on the ``configure`` command -line itself The following environment variables are recognized by -``configure``: +line itself. + +The following environment variables are recognized by ``configure``: * ``CC``: C compiler to use * ``CFLAGS``: Compile flags to pass to the C compiler * ``CPPFLAGS``: Preprocessor flags to pass to the C compiler * ``CXX``: C++ compiler to use +* ``CXXCFLAGS``: Compile flags to pass to the C++ compiler +* ``CXXCPPFLAGS``: Preprocessor flags to pass to the C++ compiler * ``FC``: Fortran compiler to use * ``FCFLAGS``: Compile flags to pass to the Fortran compiler * ``LDFLAGS``: Linker flags to pass to all compilers @@ -20,12 +23,18 @@ line itself The following environment variables are recognized by necessary for users to need to specify additional ``LIBS``) * ``PKG_CONFIG``: Path to the ``pkg-config`` utility -.. note:: Open MPI |ompi_ver| does not contain any C++ code. Hence, - specifying ``CXXFLAGS`` or ``CXXCPPFLAGS`` is useless (but - harmless). The value of ``CC`` is used as the compiler for the - ``mpic++`` wrapper compiler, however. +.. note:: Open MPI |ompi_ver| does not contain any C++ code. The only + tests that ``configure`` runs with the C++ compiler is for + the purposes of determining an appropriate value for ``CXX`` + to use in the ``mpic++`` :ref:`wrapper compiler + `. The ``CXXCFLAGS`` and + ``CXXCPPFLAGS`` values are *only* used in these + ``configure`` checks to ensure that the C++ compiler works. + +For example, to build with a specific instance of ``gcc``, ``g++``, +and ``gfortran``: -For example, to build with a specific instance of GCC:: +.. code-block:: sh shell$ ./configure \ CC=/opt/gcc-a.b.c/bin/gcc \ @@ -33,15 +42,20 @@ For example, to build with a specific instance of GCC:: FC=/opt/gcc-a.b.c/bin/gfortran ... Here's another example, this time showing building with the Intel -compiler suite:: +compiler suite: - shell$ ./configure CC=icc CXX=icpc FC=ifort ... +.. code-block:: sh -.. note:: We generally suggest using the above command line form for - setting different compilers (vs. setting environment variables and - then invoking ``./configure``). The above form will save all - variables and values in the ``config.log`` file, which makes - post-mortem analysis easier if problems occur. + shell$ ./configure \ + CC=icc \ + CXX=icpc \ + FC=ifort ... + +.. note:: The Open MPI community generally suggests using the above + command line form for setting different compilers (vs. setting + environment variables and then invoking ``./configure``). The + above form will save all variables and values in the ``config.log`` + file, which makes post-mortem analysis easier if problems occur. Note that the flags you specify must be compatible across all the compilers. In particular, flags specified to one language compiler @@ -68,19 +82,24 @@ The above command line will pass ``-m64`` to all the compilers, and therefore will produce 64 bit objects for all languages. .. warning:: Note that setting ``CFLAGS`` (etc.) does *not* affect the - flags used by the wrapper compilers. In the above, example, you - may also need to add ``-m64`` to various ``--with-wrapper-FOO`` - options: + flags used by the :ref:`wrapper compilers + `. In the above, example, you may + also need to add ``-m64`` to various ``--with-wrapper-FOO`` + options: + + .. code-block:: - .. code-block:: + shell$ ./configure CFLAGS=-m64 FCFLAGS=-m64 \ + --with-wrapper-cflags=-m64 \ + --with-wrapper-cxxflags=-m64 \ + --with-wrapper-fcflags=-m64 ... - shell$ ./configure CFLAGS=-m64 FCFLAGS=-m64 \ - --with-wrapper-cflags=-m64 \ - --with-wrapper-cxxflags=-m64 \ - --with-wrapper-fcflags=-m64 ... + Failure to do this will result in MPI applications + failing to compile / link properly. - Failure to do this will result in MPI applications failing to - compile / link properly. + See the :ref:`Customizing wrapper compiler behavior + ` section for more + details. Note that if you intend to compile Open MPI with a ``make`` other than the default one in your ``PATH``, then you must either set the ``$MAKE`` From 11ac053e0cdd0a358c42a4da2b39f8085aebe0f2 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Sun, 13 Mar 2022 08:02:29 -0400 Subject: [PATCH 4/8] docs: update a bunch of old/stale web links "make linkcheck" showed a bunch of stale links; fix most of them. Also fix one RST minor error in the ULFM doc. Signed-off-by: Jeff Squyres --- docs/faq/debugging.rst | 2 +- docs/faq/fault-tolerance.rst | 14 +++++--------- docs/faq/running-mpi-apps.rst | 9 ++++++--- docs/faq/sysadmin.rst | 2 +- docs/features/ulfm.rst | 9 ++++----- .../configure-cli-options/networking.rst | 2 +- docs/networking/cuda.rst | 2 +- docs/networking/ib-and-roce.rst | 4 ++-- docs/news/news-v1.x.rst | 2 +- docs/release-notes/networks.rst | 2 +- docs/running-apps/gridengine.rst | 3 +++ 11 files changed, 26 insertions(+), 25 deletions(-) diff --git a/docs/faq/debugging.rst b/docs/faq/debugging.rst index 1f74c0b66e0..65a19150da8 100644 --- a/docs/faq/debugging.rst +++ b/docs/faq/debugging.rst @@ -538,7 +538,7 @@ There are two cases: `_. For an evaluation of various internal implementation alternatives of Shadow Memory, please see `Building Workload Characterization Tools with Valgrind - `_. + `_. Further information and performance data with the NAS Parallel diff --git a/docs/faq/fault-tolerance.rst b/docs/faq/fault-tolerance.rst index 099a51296e9..245cfe0b1ac 100644 --- a/docs/faq/fault-tolerance.rst +++ b/docs/faq/fault-tolerance.rst @@ -1,18 +1,14 @@ Fault Tolerance =============== -.. TODO Hello world - -///////////////////////////////////////////////////////////////////////// - What is "fault tolerance"? -------------------------- The phrase "fault tolerance" means many things to many -people. Typical definitions range from user processes dumping vital -state to disk periodically to checkpoint/restart of running processes -to elaborate recreate-process-state-from-incremental-pieces schemes to -... (you get the idea). +people. Typical definitions include user processes dumping vital +state to disk periodically, checkpoint/restart of running processes, +elaborate recreate-process-state-from-incremental-pieces schemes, +and many others. In the scope of Open MPI, we typically define "fault tolerance" to mean the ability to recover from one or more component failures in a @@ -99,7 +95,7 @@ links below: * `MPI Forum's Fault Tolerance Working Group `_ * Fault Tolerant MPI Prototype: * `Development / code `_ - * `Information and support `_ + * `Information and support `_ Support for other types of resilience (e.g., :ref:`data reliability `, checkpoint) has been deprecated over the years diff --git a/docs/faq/running-mpi-apps.rst b/docs/faq/running-mpi-apps.rst index 673db026d3c..30295d701d6 100644 --- a/docs/faq/running-mpi-apps.rst +++ b/docs/faq/running-mpi-apps.rst @@ -762,9 +762,12 @@ Several notable options are: How do I use the ``--hostfile`` option to ``mpirun``? ----------------------------------------------------- -.. error:: TODO For cross reference, this is the PRRTE man page section - about ``--hostfile``: - https://github.com/openpmix/prrte/blame/master/src/tools/prte/prte-map.1.md#L236 +.. error:: TODO For cross reference, this is the PRRTE man page + section about ``--hostfile``: + https://github.com/openpmix/prrte/blob/b70a6f1a8d424e396c40c999a656b04e76cc0f91/src/tools/prte/prte-map.1.md?plain=1#L236 + A subsequent commit removed this markdown file; the commit + message refers to moving the markdown file to another git + repo, but I didn't chase down where it went. The ``--hostfile`` option to ``mpirun`` takes a filename that lists hosts on which to launch MPI processes. diff --git a/docs/faq/sysadmin.rst b/docs/faq/sysadmin.rst index eb17a2f6fd7..f6963c6b769 100644 --- a/docs/faq/sysadmin.rst +++ b/docs/faq/sysadmin.rst @@ -220,7 +220,7 @@ to tweak are: parameters in *levels*, as defined by the MPI_T interface from the MPI standard. You will need to specify ``--level 9`` (or ``--all``) to show *all* MCA parameters. `See this blog entry - `_ + `_ for further information. .. code-block:: sh diff --git a/docs/features/ulfm.rst b/docs/features/ulfm.rst index 202a13f5f5d..00148bb6872 100644 --- a/docs/features/ulfm.rst +++ b/docs/features/ulfm.rst @@ -23,7 +23,7 @@ execution environment up and running. This implementation produces the three supplementary error codes and five supplementary interfaces defined in the communicator section of the `ULFM chapter -`_ +`_ standard draft document. * ``MPIX_ERR_PROC_FAILED`` when a process failure prevents the @@ -95,7 +95,7 @@ please use: J. Dongarra: Post-failure recovery of MPI communication capability: Design and rationale. IJHPCA 27(3): 244-254 (2013).* -Available from: http://journals.sagepub.com/doi/10.1177/1094342013488238. +Available from: https://journals.sagepub.com/doi/10.1177/1094342013488238. Building ULFM support in Open MPI --------------------------------- @@ -522,9 +522,8 @@ joe@mycomputer.example.com!). Visit these pages to subscribe to the lists: https://groups.google.com/forum/#!forum/ulfm When submitting questions and problems, be sure to include as much -extra information as possible. This web page details all the -information that we request in order to provide assistance: -http://www.open-mpi.org/community/help/ +extra information as possible. See the :doc:`Getting help +` section for more details. Thanks for your time. diff --git a/docs/installing-open-mpi/configure-cli-options/networking.rst b/docs/installing-open-mpi/configure-cli-options/networking.rst index 6c00faedebb..3bb9c1f8561 100644 --- a/docs/installing-open-mpi/configure-cli-options/networking.rst +++ b/docs/installing-open-mpi/configure-cli-options/networking.rst @@ -32,7 +32,7 @@ can be used with ``configure``: memory copies (optionally using hardware offload), potentially increasing bandwidth for large messages sent between messages on the same server. See `the Knem web site - `_ for details. + `_ for details. * ``--with-libfabric=DIR``: Specify the directory where the OpenFabrics Interfaces ``libfabric`` diff --git a/docs/networking/cuda.rst b/docs/networking/cuda.rst index 4b4869f47e9..e9601b1bbed 100644 --- a/docs/networking/cuda.rst +++ b/docs/networking/cuda.rst @@ -11,7 +11,7 @@ you use the latest version of Open MPI for best support. Open MPI offers two flavors of CUDA support: -#. Via `UCX `_. +#. Via `UCX `_. This is the preferred mechanism. Since UCX will be providing the CUDA support, it is important to ensure that UCX itself is built diff --git a/docs/networking/ib-and-roce.rst b/docs/networking/ib-and-roce.rst index 7239fe4f0ab..42ee2c61291 100644 --- a/docs/networking/ib-and-roce.rst +++ b/docs/networking/ib-and-roce.rst @@ -19,7 +19,7 @@ supported via the UCX (``ucx``) PML. What is UCX? ------------ -`UCX `_ is an open-source optimized +`UCX `_ is an open-source optimized communication library which supports multiple networks, including RoCE, InfiniBand, uGNI, TCP, shared memory, and others. UCX mixes-and-matches transports and protocols which are available on the @@ -98,7 +98,7 @@ any Open MPI component. For example: mainly uses environment variables for run-time tuning |mdash| not Open MPI MCA parameters. Consult `the UCX documentation - `_ for details + `_ for details about what environment variables are available. ///////////////////////////////////////////////////////////////////////// diff --git a/docs/news/news-v1.x.rst b/docs/news/news-v1.x.rst index d72e6b405f5..bab85fbc521 100644 --- a/docs/news/news-v1.x.rst +++ b/docs/news/news-v1.x.rst @@ -1634,7 +1634,7 @@ Open MPI version 1.5.0 :Date: 10 Oct 2010 - Added "knem" support: direct process-to-process copying for shared - memory message passing. See https://runtime.bordeaux.inria.fr/knem/ + memory message passing. See https://knem.gitlabpages.inria.fr/ and the README file for more details. - Updated shared library versioning scheme and linking style of MPI applications. The MPI application ABI has been broken from the diff --git a/docs/release-notes/networks.rst b/docs/release-notes/networks.rst index 15a108f8b46..c959fabd204 100644 --- a/docs/release-notes/networks.rst +++ b/docs/release-notes/networks.rst @@ -113,7 +113,7 @@ Miscellaneous network notes ``knem`` Linux kernel module is not loaded, the ``knem`` support is (by default) silently deactivated during Open MPI jobs. - See https://knem.gforge.inria.fr/ for details on Knem. + See https://knem.gitlabpages.inria.fr/ for details on Knem. * Linux Cross-Memory Attach (CMA) or XPMEM is used by the ``sm`` shared memory BTL when the CMA/XPMEM libraries are installed, diff --git a/docs/running-apps/gridengine.rst b/docs/running-apps/gridengine.rst index 1412f472a67..5103627c354 100644 --- a/docs/running-apps/gridengine.rst +++ b/docs/running-apps/gridengine.rst @@ -134,6 +134,9 @@ hosts are established successfully or not. emailed Dave Love on 31 Dec 2021 to ask if this is still the correct URL. + Update March 2022: it doesn't look like this web site is good any + more. Perhaps use https://github.com/grisu48/gridengine instead...? + Various Grid Engine documentation with pointers to more is available at `the Son of GridEngine site `_, and configuration instructions can be found at `the Son of GridEngine From bfed1310d69f81900747a142cb765001516b65f6 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Tue, 15 Mar 2022 11:43:23 -0400 Subject: [PATCH 5/8] docs: Add new v4.1.3 NEWS bullet This was just added in https://github.com/open-mpi/ompi/pull/10119. Signed-off-by: Jeff Squyres --- docs/news/news-v4.1.x.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/news/news-v4.1.x.rst b/docs/news/news-v4.1.x.rst index d2d42443349..27e5e38a191 100644 --- a/docs/news/news-v4.1.x.rst +++ b/docs/news/news-v4.1.x.rst @@ -8,6 +8,9 @@ Open MPI version 4.1.3 ---------------------- :Date: March, 2022 +- Added support for ``ELEMENTAL`` to the MPI handle comparison + functions in the ``mpi_f08`` module. Thanks to Salvatore Filippone + for raising the issue. - Minor datatype performance improvements in the CUDA-based code paths. - Fix ``MPI_ALLTOALLV`` when used with ``MPI_IN_PLACE``. - Fix ``MPI_BOTTOM`` handling for non-blocking collectives. Thanks to From 75d50943c7e8606e1156f2df07ee367b3e6d19ec Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Tue, 15 Mar 2022 12:36:51 -0400 Subject: [PATCH 6/8] readthedocs.yaml: make builds fail on warnings Use the .readthedocs.yaml file to make ReadTheDocs fail the build if there are Sphinx warnings. Signed-off-by: Jeff Squyres --- .readthedocs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 73f2d6745e7..8793d4dc74d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -8,3 +8,4 @@ version: 2 # Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py + fail_on_warning: true From cb66147e0c2b47b2066514c70efb1f9797923f8e Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Tue, 15 Mar 2022 13:36:18 -0400 Subject: [PATCH 7/8] docs: man page updates Signed-off-by: Jeff Squyres --- docs/man-openmpi/man1/mpisync.1.rst | 8 +++--- .../man1/ompi-wrapper-compiler.1.rst | 26 +++++++++---------- .../man1/oshmem-wrapper-compiler.1.rst | 26 +++++++++---------- 3 files changed, 31 insertions(+), 29 deletions(-) diff --git a/docs/man-openmpi/man1/mpisync.1.rst b/docs/man-openmpi/man1/mpisync.1.rst index 65f283148a8..19c08f3ca25 100644 --- a/docs/man-openmpi/man1/mpisync.1.rst +++ b/docs/man-openmpi/man1/mpisync.1.rst @@ -12,9 +12,11 @@ Open MPI timing tools SYNTAX ------ -| **mpisync** [*options*] -| **mpirun_prof** [*options*] -| **ompi_timing_post** [**] [**] +``mpisync [options]`` + +``mpirun_prof [options]`` + +``ompi_timing_post [] []`` DESCRIPTION diff --git a/docs/man-openmpi/man1/ompi-wrapper-compiler.1.rst b/docs/man-openmpi/man1/ompi-wrapper-compiler.1.rst index cf0c96dd631..68b6490df87 100644 --- a/docs/man-openmpi/man1/ompi-wrapper-compiler.1.rst +++ b/docs/man-openmpi/man1/ompi-wrapper-compiler.1.rst @@ -14,27 +14,27 @@ mpicc, mpic++, mpicxx, mpifort, mpijavac -- Open MPI wrapper compilers SYNTAX ------ -``mpicc [-showme|-showme:compile|-showme:link] ...`` +``mpicc [--showme | --showme:compile | --showme:link] ...`` -``mpic++ [-showme|-showme:compile|-showme:link] ...`` +``mpic++ [--showme | --showme:compile | --showme:link] ...`` -``mpicxx [-showme|-showme:compile|-showme:link] ...`` +``mpicxx [--showme | --showme:compile | --showme:link] ...`` -``mpifort [-showme|-showme:compile|-showme:link] ...`` +``mpifort [--showme | --showme:compile | --showme:link] ...`` -``mpijavac [-showme|-showme:compile|-showme:link] ...`` +``mpijavac [--showme | --showme:compile | --showme:link] ...`` The following deprecated commands are also available |mdash| but ``mpifort`` should be used instead: -``mpif77 [-showme|-showme:compile|-showme:link] ...`` +``mpif77 [--showme | --showme:compile | --showme:link] ...`` -``mpif90 [-showme|-showme:compile|-showme:link] ...`` +``mpif90 [--showme | --showme:compile | --showme:link] ...`` On case-sensitive filesystems, the following command will also be available: -``mpiCC [-showme|-showme:compile|-showme:link] ...`` +``mpiCC [--showme | --showme:compile | --showme:link] ...`` OPTIONS @@ -50,7 +50,7 @@ The options below apply to all of the wrapper compilers: the program. .. note:: If a non-filename argument is passed on the command line, - the *-showme* option will *not* display any additional + the ``--showme`` option will *not* display any additional flags. For example, both ``"mpicc --showme`` and ``mpicc --showme my_source.c`` will show all the wrapper-supplied flags. But ``mpicc @@ -174,17 +174,17 @@ between different installations of the same version of Open MPI. Indeed, since the wrappers are simply thin shells on top of an underlying compiler, there are very, very few compelling reasons *not* to use Open MPI's wrapper compilers. When it is not possible to use -the wrappers directly, the ``-showme:compile`` and ``-showme:link`` +the wrappers directly, the ``--showme:compile`` and ``--showme:link`` options should be used to determine what flags the wrappers would have used. For example: .. code:: sh - shell$ cc -c file1.c `mpicc -showme:compile` + shell$ cc -c file1.c `mpicc --showme:compile` - shell$ cc -c file2.c `mpicc -showme:compile` + shell$ cc -c file2.c `mpicc --showme:compile` - shell$ cc file1.o file2.o `mpicc -showme:link` -o my_mpi_program + shell$ cc file1.o file2.o `mpicc --showme:link` -o my_mpi_program NOTES diff --git a/docs/man-openshmem/man1/oshmem-wrapper-compiler.1.rst b/docs/man-openshmem/man1/oshmem-wrapper-compiler.1.rst index 66285c4e387..552615ad24d 100644 --- a/docs/man-openshmem/man1/oshmem-wrapper-compiler.1.rst +++ b/docs/man-openshmem/man1/oshmem-wrapper-compiler.1.rst @@ -19,21 +19,21 @@ oshcc, oshcxx, oshc++, oshfort, shmemcc, shmemcxx, shmemc++, shmemfort -- OpenSH SYNTAX ------ -``oshcc [-showme|-showme:compile|-showme:link] ...`` +``oshcc [--showme | --showme:compile | --showme:link] ...`` -``oshcxx [-showme|-showme:compile|-showme:link] ...`` +``oshcxx [--showme | --showme:compile | --showme:link] ...`` -``oshc++ [-showme|-showme:compile|-showme:link] ...`` +``oshc++ [--showme | --showme:compile | --showme:link] ...`` -``oshfort [-showme|-showme:compile|-showme:link] ...`` +``oshfort [--showme | --showme:compile | --showme:link] ...`` -``shmemcc [-showme|-showme:compile|-showme:link] ...`` +``shmemcc [--showme | --showme:compile | --showme:link] ...`` -``shmemcxx [-showme|-showme:compile|-showme:link] ...`` +``shmemcxx [--showme | --showme:compile | --showme:link] ...`` -``shmemc++ [-showme|-showme:compile|-showme:link] ...`` +``shmemc++ [--showme | --showme:compile | --showme:link] ...`` -``shmemfort [-showme|-showme:compile|-showme:link] ...`` +``shmemfort [--showme | --showme:compile | --showme:link] ...`` OPTIONS @@ -49,7 +49,7 @@ The options below apply to all of the wrapper compilers: the program. .. note:: If a non-filename argument is passed on the command line, - the *-showme* option will *not* display any additional + the ``--showme`` option will *not* display any additional flags. For example, both ``"oshcc --showme`` and ``oshcc --showme my_source.c`` will show all the wrapper-supplied flags. But ``oshcc @@ -161,16 +161,16 @@ between different installations of the same version of OpenSHMEM. Indeed, since the wrappers are simply thin shells on top of an underlying compiler, there are very, very few compelling reasons *not* to use ``oshcc``. When it is not possible to use the wrappers -directly, the ``-showme:compile`` and ``-showme:link`` options should be +directly, the ``--showme:compile`` and ``--showme:link`` options should be used to determine what flags the wrappers would have used. For example: .. code:: sh - shell$ cc -c file1.c `shmemcc -showme:compile` + shell$ cc -c file1.c `shmemcc --showme:compile` - shell$ cc -c file2.c `shmemcc -showme:compile` + shell$ cc -c file2.c `shmemcc --showme:compile` - shell$ cc file1.o file2.o `shmemcc -showme:link` -o my_oshmem_program + shell$ cc file1.o file2.o `shmemcc --showme:link` -o my_oshmem_program NOTES From 05487572be717d28fcbe82c0150a44b4abf13076 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Tue, 15 Mar 2022 16:16:46 -0400 Subject: [PATCH 8/8] docs: fix OpenSHMEM man pages in dist Ensure to always include the non-generated man pages (i.e., the pages that are simply nroff redirects to Sphinx-generated man pages). Signed-off-by: Jeff Squyres --- docs/Makefile.am | 61 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 41 insertions(+), 20 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 8a9f71bd044..2310cb294af 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -785,6 +785,40 @@ OSHMEM_MAN1_BUILT = $(OSHMEM_MAN1:%.1=$(MAN_OUTDIR)/%.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_MAN5_BUILT) \ + $(OSHMEM_MAN1_BUILT) \ + $(OSHMEM_MAN3_BUILT) + +########################################################################### + +# These files are not generated by Sphinx (they are redirects to +# Sphinx-generated man pages). +OMPI_MAN1_REDIRECTS = \ + man-openmpi/man1/mpicc.1 \ + man-openmpi/man1/mpicxx.1 \ + man-openmpi/man1/mpic++.1 \ + man-openmpi/man1/mpifort.1 \ + man-openmpi/man1/mpif77.1 \ + man-openmpi/man1/mpif90.1 \ + man-openmpi/man1/mpijavac.1 + +OSHMEM_MAN1_REDIRECTS = \ + man-openshmem/man1/oshcc.1 \ + man-openshmem/man1/oshcxx.1 \ + man-openshmem/man1/oshc++.1 \ + man-openshmem/man1/oshfort.1 \ + man-openshmem/man1/shmemcc.1 \ + man-openshmem/man1/shmemcxx.1 \ + man-openshmem/man1/shmemc++.1 \ + man-openshmem/man1/shmemfort.1 + +EXTRA_DIST += \ + $(OMPI_MAN1_REDIRECTS) \ + $(OSHMEM_MAN1_REDIRECTS) + ########################################################################### if OPAL_BUILD_DOCS @@ -840,32 +874,19 @@ endif OPAL_BUILD_DOCS ########################################################################### if OPAL_INSTALL_DOCS -dist_man1_MANS = \ +man1_MANS = \ $(OMPI_MAN1_BUILT) \ - man-openmpi/man1/mpicc.1 \ - man-openmpi/man1/mpicxx.1 \ - man-openmpi/man1/mpic++.1 \ - man-openmpi/man1/mpifort.1 \ - man-openmpi/man1/mpif77.1 \ - man-openmpi/man1/mpif90.1 \ - man-openmpi/man1/mpijavac.1 + $(OMPI_MAN1_REDIRECTS) -dist_man3_MANS = $(OMPI_MAN3_BUILT) -dist_man5_MANS = $(OMPI_MAN5_BUILT) +man3_MANS = $(OMPI_MAN3_BUILT) +man5_MANS = $(OMPI_MAN5_BUILT) if PROJECT_OSHMEM -dist_man1_MANS += \ +man1_MANS += \ $(OSHMEM_MAN1_BUILT) \ - man-openshmem/man1/oshcc.1 \ - man-openshmem/man1/oshcxx.1 \ - man-openshmem/man1/oshc++.1 \ - man-openshmem/man1/oshfort.1 \ - man-openshmem/man1/shmemcc.1 \ - man-openshmem/man1/shmemcxx.1 \ - man-openshmem/man1/shmemc++.1 \ - man-openshmem/man1/shmemfort.1 + $(OSHMEM_MAN1_REDIRECTS) -dist_man3_MANS += $(OSHMEM_MAN3_BUILT) +man3_MANS += $(OSHMEM_MAN3_BUILT) endif endif OPAL_INSTALL_DOCS