bgirgis/cpp-thirdparty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Upgrade macos

Browse Source
This commit is contained in:
Bassem Girgis
2025-03-19 08:52:56 -05:00
parent 53580cb51f
commit d29ef955f5
8041 changed files with 1936720 additions and 130842 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
macx64/mpi/openmpi/share/doc/pmix/html/.buildinfo Normal file
View File

@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 680df0d2507dd93bc347982f29ffd740
tags: 645f666f9bcd5a90fca523b33c5a78b7

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_images/compatibility.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.7 KiB

173
macx64/mpi/openmpi/share/doc/pmix/html/_sources/building-apps/building-static-apps.rst.txt Normal file
View File

@@ -0,0 +1,173 @@
.. _label-building-fully-static-apps:
Building fully-static PMIx applications
=======================================
Is fully-static really what you need?
-------------------------------------
No one ends up in this documentation section by accident.
If you are reading this text, it is likely because you are looking to
solve a problem, and fully-static applications sound like the
right answer. There are two common problems that people think that
fully-static applications will solve:
#. Applications fail to launch because dependent shared libraries
are not found at run-time.
#. Filesystem performance when launching at scale is terrible.
If either of these are your problems, the PMIx community *strongly
encourages you to use other mechanisms to fix the problem*:
fully-static applications are *possible*, but are sub-optimal for
other reasons.
The following sections discuss the above problems.
Finding dependent shared libraries at run-time
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are running into problems finding shared libraries at run time
|mdash| particularly on nodes that are remote from where you have invoked
your launcher |mdash| your best bet is to set ``LD_LIBRARY_PATH`` (or
equivalent mechanism) properly on *all* nodes (including remote
nodes).
This is an involved topic, but even so, it is generally simpler to
solve this problem than creating and maintaining static builds.
Improving filesystem performance at scale
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Prior to v4.2.0, PMIx compiled a large number of plugins as
individual dynamic shared objects (DSOs) |mdash| i.e., individual
files in the filesystem. Many of these DSOs would be opened by each
application process at run time.
This could cause filesystem congestion, particularly when the application is
installed on a network filesystem and a large job is launched: many
nodes will simultaneously communicate with the file server(s), and
potentially need to transfer a large number of small(ish) files.
Starting with v4.2.0, by default, PMIx's plugins are no longer
built as DSOs. As such, PMIx typically only opens a small number
of shared libraries at launch time. Even if PMIx is installed on
a network filesystem, these libraries are likely to be cached on nodes
over time, and therefore generate a fairly small amount network
filesystem traffic when PMIx-based jobs are launched.
In short: PMIx |opmix_ver|'s impact on network filesystems is
greatly diminished compared to prior versions. Compiling fully-static
applications to eliminate the open-every-DSO-file-at-launch-time
behavior is no longer necessary.
Other reasons fully-static applications are bad
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here are a few other reasons that fully-static applications are
sub-optimal:
#. When applications link all of their dependencies statically, the
operating system cannot share code between multiple copies of the
process.
For example, if you launch N copies of your fully-statically-linked
application on a node, it will consume (N *
size_of_the_application) bytes of RAM. Alternately, launching N
copies of a dynamically-linked MPI application |mdash| where each
of the copies have the same dependent libraries |mdash| will only
load each shared dependent library into RAM once.
In other words: *using dynamic linking saves memory.*
#. If you disable PMIx's ``dlopen`` functionality (which is
necessary to create *fully*-static MPI applications), you may
lose access to functionality that is dependent on third-party
libraries that cannot operate (or are not provided) as static
libraries. Note that your application also cannot use a
memory manager (such as most MPI libraries do by default).
Are you convinced yet? *Please try to avoid building fully-static
applications if at all possible.*
Building fully-static PMIx-based applications
---------------------------------------------
.. caution:: If, after reading all of the above, you are still of the
mind that you want to build fully-static
applications, be aware that fully static linking is not
for the meek, and it is not recommended. But it is
possible, with some caveats.
#. You must have static libraries available for *everything* to which
your program links. This includes PMIx; you must have used the
``--enable-static`` option to PMIx's ``configure`` or otherwise
have available the static versions of the PMIx library.
.. note:: Some Linux distributions may not have static versions of
popular Linux libraries by default (e.g., libnuma), or
require additional RPMs to be installed to get the
equivalent static libraries.
#. Your application must have been built without a memory manager.
For example, this means that Open MPI must have been configured with the
``--without-memory-manager`` flag.
.. important:: Not including memory manager support can lead to
lower performance when using
OS-bypass networks.
This is how to configure PMIx to build fully-static libraries on
Linux:
.. code-block:: sh
shell$ ./configure --disable-dlopen \
--enable-static --disable-shared ...
The ``--disable-shared`` flag is optional; it will prevent PMIx
from *also* building shared libraries.
Alternatively, you could build PMIx with as many static libraries
as possible, but still preserve ``dlopen`` functionality by omitting
the ``--disable-dlopen`` flag:
.. code-block:: sh
shell$ ./configure --enable-static --disable-shared ...
This gives you a *mostly* static build of PMIx, but has the
advantage of preserving at least some dynamic libraries.
Including whole archives
^^^^^^^^^^^^^^^^^^^^^^^^
Some systems may have additional constraints about their support
libraries that require additional steps to produce working
fully-static PMIx-based applications. For example, any library that has its
own run-time plugin system (i.e., that opens dynamically shared
objects ("DSOs") at run time) will have additional complications in
producing fully-static builds.
In such cases, you generally want to run ``pmixcc ... --showme`` to see
the compiler / linker commands that PMIx's wrapper commands will
use, and then augment those commands with linker arguments for the
static versions of the DSO plugins that you will need at run time.
For example, if you have ``libfoo.a`` that dynamically loads
``plugin.so`` at run time, you'll need to have a ``plugin.a`` and
|mdash| assuming the GNU linker |mdash| add arguments similar to the
following:
* ``-static``: Tell the linker to generate a static executable.
* ``-Wl,--whole-archive -lfoo /path/to/plugin.a -Wl,--no-whole-archive``:
Tell the linker to include the entire ``foo`` library and the entire
``plugin.a`` archive in the executable.
You can either add these arguments on the command line manually, or
you can :ref:`modify the default behavior of the wrapper compilers
<label-customizing-wrapper-compiler>` to hide this complexity from end
users (but be aware that if you modify the wrapper compilers' default
behavior, *all* users will be creating static applications!).

95
macx64/mpi/openmpi/share/doc/pmix/html/_sources/building-apps/customizing-wrappers.rst.txt Normal file
View File

@@ -0,0 +1,95 @@
.. _label-customizing-wrapper-compiler:
Customizing wrapper compiler behavior
=====================================
The PMIx wrapper compiler is driven by text files that contain,
among other things, the flags that are passed to the underlying
compiler. The text file is generated automatically for PMIx
and is customized for the compiler set that was selected when PMIx
was configured; it is *not* recommended that users edit this
file.
However, there are cases where it may be necessary or desirable to
edit the file and add to or subtract from the flags that PMIx
selected. The file is installed in ``$pkgdatadir``, which
defaults to ``$prefix/share/pmix/pmixcc-wrapper-data.txt``.
Several environment variables are also available for run-time
replacement of the wrapper's default values (from the text file):
.. note:: You may need to scroll right in the following table.
.. list-table::
:header-rows: 1
* - Wrapper compiler
- Compiler
- Preprocessor flags
- Compiler flags
- Linker flags
- Linker library flags
- Data file
* - ``mpmixcc``
- ``PMIX_CC``
- ``PMIX_CPPFLAGS``
- ``PMIX_CFLAGS``
- ``PMIX_LDFLAGS``
- ``PMIX_LIBS``
- ``pmixcc-wrapper-data.txt``
.. caution:: Note that changing the underlying compiler may not work
at all.
The traditional method of using multiple different compilers
with PMIx is to install PMIx multiple times; each
installation should be built/installed with a different compiler.
This is annoying, but it is beyond the scope of PMIx to be able
to fix.
Note that the values of these fields can be directly influenced by
passing flags to PMIx's ``configure`` script. :ref:`See this
section in the Installation guide <label-building-installation-cli-options>` for
more details.
The files cited in the above table use fairly simplistic "key=value"
data formats. The following are several fields that are likely to be
of interest to end-users:
* ``project_short``: Prefix for all environment variables. See
below.
* ``compiler_env``: Specifies the base name of the environment
variable that can be used to override the wrapper's underlying
compiler at run-time. The full name of the environment variable is
of the form ``<project_short>_<compiler_env>``; see table above.
* ``compiler_flags_env``: Specifies the base name of the environment
variable that can be used to override the wrapper's compiler flags
at run-time. The full name of the environment variable is of the
form ``<project_short>_<compiler_flags_env>``; see table above.
* ``compiler``: The executable name of the underlying compiler.
* ``extra_includes``: Relative to ``$installdir``, a list of directories
to also list in the preprocessor flags to find header files.
* ``preprocessor_flags``: A list of flags passed to the preprocessor.
* ``compiler_flags``: A list of flags passed to the compiler.
* ``linker_flags``: A list of flags passed to the linker.
* ``libs``: A list of libraries passed to the linker.
* ``required_file``: If non-empty, check for the presence of this file
before continuing. If the file is not there, the wrapper will abort
saying that the language is not supported.
* ``includedir``: Directory containing PMIx's header files. The
proper compiler "include" flag is prepended to this directory and
added into the preprocessor flags.
* ``libdir``: Directory containing PMIx's library files. The
proper compiler "include" flag is prepended to this directory and
added into the linker flags.

13
macx64/mpi/openmpi/share/doc/pmix/html/_sources/building-apps/deprecation-warnings.rst.txt Normal file
View File

@@ -0,0 +1,13 @@
Deprecated Definitions
======================
The PMIx Standard will occasionally decide to deprecate and subsequently
remove attribute and constant definitions - and on rarer occasions, functional
APIs. The OpenPMIx library, however, maintains a policy of never actually
removing deprecated definitions. This is done with the intent of maintaining,
to the maximum extent possible, full backward compatibility.
Deprecated definitions are moved from their original header files to the
`pmix_deprecated.h` file to identify them as deprecated. While continuing
to be valid, users are encouraged to migrate away from these definitions
to remain in sync with the continued evolution of the PMIx Standard.

101
macx64/mpi/openmpi/share/doc/pmix/html/_sources/building-apps/extracting-wrapper-flags.rst.txt Normal file
View File

@@ -0,0 +1,101 @@
Extracting flags from the wrapper compilers
===========================================
If you cannot use the wrapper compiler for some reason, there are
multiple supported ways to extract the compiler/linker flags that you
will need.
Using the ``--showme`` option
-----------------------------
The wrapper compiler supports a ``--showme`` command line option
that will show what commands would have been invoked.
.. note:: If you pass ``--showme`` *and additional command line
parameters* to the wrapper compiler, be sure to *also* pass in a
filename. Otherwise, the ``--showme`` functionality will not
display output as expected.
.. warning:: It is almost never a good idea to hard-code these results
in a ``Makefile`` (or other build system). It is almost always
best to run (for example) ``pmixcc --showme:compile`` in a dynamic
fashion to find out what you need. For example, GNU Make allows
running commands and assigning their results to variables:
.. code-block:: make
PMIX_COMPILE_FLAGS = $(shell pmixcc --showme:compile)
PMIX_LINK_FLAGS = $(shell pmixcc --showme:link)
my_app: my_app.c
$(CC) $(PMIX_COMPILE_FLAGS) my_app.c $(PMIX_LINK_FLAGS) -o my_app
Using ``pkg-config``
--------------------
Alternatively, PMIx also installs ``pkg-config(1)`` configuration
files under ``$libdir/pkgconfig``. If ``pkg-config`` is configured to
find these files (e.g., if you add ``$libdir/pkgconfig`` |mdash| which
is usually ``$prefix/lib/pkgconfig`` |mdash| to the
``PKG_CONFIG_PATH`` environment variable), then compiling / linking
PMIx programs can be performed like this:
.. code-block:: sh
shell$ export PKG_CONFIG_PATH=/opt/pmix/lib/pkgconfig
shell$ gcc hello_world.c -o hello_world -g \
`pkg-config pmix --cflags --libs`
shell$
.. note:: PMIx's ``pkg-config`` file *works properly*, but it
probably isn't *technically correct*.
Specifically: PMIx will list all of its dependent
libraries that are necessary to link PMIx-based application,
even if a given dependency has a ``.pc`` file and should
therefore be listed as a ``Requires`` and/or
``Requires.private`` in PMIx's ``.pc`` files.
For example, PMIx lists ``-lhwloc`` in both ``Libs`` and
``Libs.private``. But since HWLOC provides its own
``pmix.pc`` file, it would be more correct for PMIx to
*not* list ``-lhwloc`` in ``Libs`` / ``Libs.private``, and
instead include:
.. code-block::
Requires: hwloc
Requires.private: hwloc
The end result is likely immaterial, but we document this
just in case it ever becomes an issue someday.
Using ``pmix_info``
-------------------
This method is not directly suitable for getting all the compiler /
linker flags needed to compile PMIx-based applications because it does not
include the relevant flags to find PMIx's headers and libraries.
But it does show a breakdown of all other flags.
.. code-block::
shell$ pmix_info --all | grep Build
Build CFLAGS:
Build LDFLAGS:
Build LIBS: -ldl -levent_core -levent_pthreads -lhwloc
This installation is *only* adding options in the ``xLIBS`` areas of the
wrapper compilers; all other values are blank (remember: the ``-I``'s
and ``-L``'s are implicit).
Note that the ``--parsable`` option can be used to obtain
machine-parsable versions of this output. For example:
.. code-block::
shell$ ompi_info --all --parsable | grep option:build
option:build:cflags:
option:build:ldflags:
option:build:libs:-ldl -levent_core -levent_pthreads -lhwloc

14
macx64/mpi/openmpi/share/doc/pmix/html/_sources/building-apps/index.rst.txt Normal file
View File

@@ -0,0 +1,14 @@
Building PMIx applications
==========================
The simplest way to compile and link PMIx applications is to use the
PMIx "wrapper" compilers.
.. toctree::
:maxdepth: 1
quickstart
customizing-wrappers
extracting-wrapper-flags
deprecation-warnings
building-static-apps

44
macx64/mpi/openmpi/share/doc/pmix/html/_sources/building-apps/quickstart.rst.txt Normal file
View File

@@ -0,0 +1,44 @@
.. _label-quickstart-building-apps:
Quick start: Building PMIx-based applications
=============================================
Although this section skips many details, it offers examples that will
probably work in many environments.
.. caution:: Note that this section is a "Quick start" |mdash| it does
not attempt to be comprehensive or describe how to build PMIx
in all supported environments. The examples below may therefore
not work exactly as shown in your environment.
Please consult the other sections in this chapter for more details,
if necessary.
PMIx provides a "wrapper" compiler (```pmixcc`` <man1-pmixcc>`)that can be used for
compiling PMIx-based applications. The intent is that users can simply invoke the
PMIx wrapper compiler instead of their usual language compiler (e.g., ``gcc``).
For example, instead of invoking your usual C compiler to build your
application, use ``pmixcc``:
.. code-block:: sh
shell$ pmixcc hello_world_pmix.c -o hello_world_pmix
shell$
All the wrapper compiler does is add a variety of compiler and linker
flags to the command line and then invoke a back-end compiler. To be
specific: the wrapper compilers do not parse source code at all; they
are solely command-line manipulators, and have nothing to do with the
actual compilation or linking of programs. The end result is anI
executable that is properly linked to all the relevant libraries.
.. caution:: It is *absolutely not sufficient* to simply add ``-lpmix``
to your link line and assume that you will obtain a valid
PMIx executable.
.. note:: You should use the wrapper compiler provided by your higher-level
library instead of ``pmix`` if (a) your library provides a wrapper,
and (b) your library also uses PMIx (in which case, its wrapper
should not only include the necessary linkages, but also ensures
that your application and library are both using the *same* PMIx
library)

79
macx64/mpi/openmpi/share/doc/pmix/html/_sources/contributing.rst.txt Normal file
View File

@@ -0,0 +1,79 @@
Contributing to OpenPMIx
========================
Open source contributions
-------------------------
All code contributions are submitted as pull requests on the `OpenPMIx
GitHub repository <https://github.com/openpmix/openpmix/>`_.
.. important:: All commits must include a ``Signed-off-by:`` line,
indicating the submitter's agreement to the :ref:`OpenPMIx
Contributor's Declaration
<contributing-contributors-declaration-label>`.
.. _contributing-contributors-declaration-label:
Contributor's Declaration
^^^^^^^^^^^^^^^^^^^^^^^^^
In order to ensure that we can keep distributing OpenPMIx under our
:doc:`open source license </license>`, we need to ensure that
all contributions are compatible with that license. Put differently:
we need to have an established intellectual property pedigree of the
code in OpenPMIx. This means being able to ensure that all code
included in OpenPMIx is free, open source, and able to be distributed
under :doc:`the BSD license </license>`.
OpenPMIx has therefore adopted requirements based on the signed-off-by
process as described in Section 11 of the Linux kernel document on
`Submitting Patches
<https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_.
Each proposed contribution to the OpenPMIx code base must include the
text ``Signed-off-by:`` followed by the contributor's name and email
address. This is a developer's certification that he or she has the
right to submit the patch for inclusion into the project, and
indicates agreement to the Developer's Certificate of Origin:
By making a contribution to this project, I certify that:
#. The contribution was created in whole or in part by me and I
have the right to submit it under the :doc:`OpenPMIx open
source license </license>`; or
#. The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part by
me, under the :doc:`OpenPMIx open source license
</license>` (unless I am permitted to submit under a
different license); or
#. The contribution was provided directly to me by some other
person who certified (1) or (2) and I have not modified it.
#. I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off)
is maintained indefinitely and may be redistributed consistent
with this project and the open source license(s) involved.
Proposed contributions failing to include the ``Signed-off-by:``
certification will not be accepted into any OpenPMIx code
repository. The community reserves the right to revert any commit
inadvertently made without the required certification.
.. note:: This policy prevents a situation where intellectual property
gets into the OpenPMIx code base and then someone later
claims that we owe them money for it. OpenPMIx is a free,
open source code base. We intend it to remain that way.
If you have not already done so, please ensure that *every* commit in
your pull request contains the ``Signed-off-by:`` line.
.. admonition:: Pro tip
:class: tip
You can use the ``-s`` flag to the ``git commit`` command (i.e.,
``git commit -s ...``) to automatically add the appropriate
``Signed-off-by:`` line to your commit message.

45
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/autogen.rst.txt Normal file
View File

@@ -0,0 +1,45 @@
Running ``autogen.pl``
======================
You can now run PMIx's top-level ``autogen.pl`` script. This script
will invoke the GNU Autoconf, Automake, and Libtool commands in the
proper order and do a bunch of component discovery and housekeeping to
setup to run PMIx's top-level ``configure`` script.
Running ``autogen.pl`` may take a few minutes, depending on your
system. It's not very exciting to watch.
If you have a multi-processor system, enabling the multi-threaded
behavior in Automake 1.11 (or newer) can result in ``autogen.pl``
running faster. Do this by setting the ``AUTOMAKE_JOBS`` environment
variable to the number of processors (threads) that you want it to use
before invoking ``autogen.pl``. For example (you can put this in your
shell startup files)::
# For bash/sh/zsh:
export AUTOMAKE_JOBS=4
# For csh/tcsh:
set AUTOMAKE_JOBS 4
.. important:: ``autogen.pl`` will fail and report an error if you
forgot to install the required submodule prior to running the
autogen script. You can either do this by adding the ``--recursive``
flag to your Git ``clone`` command, or by manually populating the
submodule by running:
.. code-block:: sh
shell$ git submodule update --init
prior to executing ``autogen.pl``.
.. important:: You generally need to run ``autogen.pl`` whenever the
top-level file ``configure.ac`` changes, or any files in the
``config/`` or ``<project>/config/`` directories change (these
directories are where a lot of "include" files for PMIx's
``configure`` script live).
.. note:: You do *NOT* need to re-run ``autogen.pl`` if you modify a
``Makefile.am``.

9
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/building-pmix.rst.txt Normal file
View File

@@ -0,0 +1,9 @@
Building PMIx
=================
Once you have run ``autogen.pl`` successfully, you can configure and
build PMIx just like end users do with official distribution PMIx
tarballs.
See the :doc:`general "Install PMIx" documentation for more
details. </installing-pmix/index>`

22
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/compiler-pickyness.rst.txt Normal file
View File

@@ -0,0 +1,22 @@
Compiler Pickyness by Default
=============================
If you are building PMIx from a Git clone (i.e., there is a
``.git`` directory in your build tree), the default build includes
extra compiler pickyness, which will result in more compiler warnings
than in non-developer builds and will mandate that warnings be
treated as errors. Getting these extra compiler warnings
is helpful to PMIx developers in making the code base as clean as
possible.
Developers can disable this picky-by-default behavior by using the
``--disable-picky`` configure option. Also note that extra-picky
compiles do *not* happen automatically when you do a VPATH build
(e.g., if ``.git`` is in your source tree, but not in your build
tree).
Prior versions of PMIx would automatically activate a lot of
(performance-reducing) debugging code by default if ``.git`` was found
in your build tree. This is no longer true. You can manually enable
these (performance-reducing) debugging features in the PMIx code
base with the ``--enable-debug`` configure option.

71
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/frameworks.rst.txt Normal file
View File

@@ -0,0 +1,71 @@
.. _label-frameworks:
Internal frameworks
===================
The Modular Component Architecture (MCA) is the backbone of PMIx
-- most services and functionality are implemented through MCA
components.
Here is a list of all the component frameworks in PMIx as of
this writing |date|:
* ``bfrops``: Buffer Operations, including support for pack/unpack,
copy, print, compare, and load of data types and structured objects
* ``gds``: Generalized DataStore for storing job-level and other data
* ``pcompress``: Compress to support compression of large data objects
* ``pdl``: DLopen support
* ``pfexec``: Fork/Exec support to allow tools to start child processes
* ``pgpu``: GPU support
* ``pif``: Interface discovery
* ``pinstalldirs``: Install Directories - provides a struct containing
all installation locations
* ``plog``: Logging of user-provided alerts
* ``pmdl``: Programming Model - provides support for a range of
programming models and libraries, including collection of default
parameters and environmental variables for forwarding and setting
of library-specific environmental variables
* ``pnet``: Network support, including computation of endpoints to
support the ``instant on`` launch procedure
* ``preg``: Regular expression generator and parser
* ``prm``: Resource Manager support - translation of generic PMIx directives
(e.g., mapping and resource definitions) to RM-specific values and
general RM-specific support
* ``psec``: Security operations such as connection handshakes
* ``psensor``: Sensor framework for monitoring processes, including
resource utilization and state-of-health (e.g., heartbeat)
* ``psquash``: Internal framework for squashing integer data values
during transmission
* ``pstat``: Statistics, including reporting resource usage at the
process, node, and disk levels
* ``ptl``: Transport Layer for client-server and tool-server
communication
Framework notes
---------------
Each framework typically has one or more components that are used at
run-time. For example, the ``bfrops`` framework is used by PMIx
to pack/unpack data for transmission, copy data objects, and other
data manipulation operations. The ``v3`` component, for example,
supports the data object definitions introduced in v3 of the
library, while the ``v41`` component supports those introduced
in v4.1.
MCA parameter notes
-------------------
Each component typically has some tunable parameters that can be
changed at run-time. Use the :ref:`pmix_info(1) <man1-pmix_info>`
command to check a component to see what its tunable parameters are.
For example:
.. code-block:: sh
shell$ pmix_info --param psensor file
shows the parameters (and default values) for the ``file`` ``psensor``
component.
See :ref:`this section <label-running-setting-mca-param-values>` for
details on how to set MCA parameters at run time.

185
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/git-github.rst.txt Normal file
View File

@@ -0,0 +1,185 @@
GitHub, Git, and related topics
===============================
GitHub
------
PMIx's Git repository is `hosted at GitHub
<https://github.com/openpmix/openpmix>`_.
#. First, you will need a Git client. We recommend getting the latest
version available. If you do not have the command ``git`` in your
path, you will likely need to download and install Git.
#. `openpmix <https://github.com/openpmix/openpmix/>`_ is the main PMIx
repository where most active development is done. Git clone this
repository. Note that the use of the ``--recursive`` CLI option is
necessary because PMIx uses Git submodules::
shell$ git clone --recursive https://github.com/openpmix/openpmix.git
Note that Git is natively capable of using many forms of web
proxies. If your network setup requires the user of a web proxy,
`consult the Git documentation for more details
<https://git-scm.com/>`_.
Git commits: open source / contributor's declaration
----------------------------------------------------
In order to remain open source, all new commits to the PMIx
repository must include a ``Signed-off-by:`` line, indicating the
submitter's agreement to the :ref:`PMIx Contributor's Declaration
<contributing-contributors-declaration-label>`.
.. tip:: You can use the ``-s`` option to ``git commit`` to
automatically add the ``Signed-off-by:`` line to your commit
message.
.. _git-github-branch-scheme-label:
Git branch scheme
-----------------
Generally, PMIx has two types of branches in its Git repository:
#. ``master``:
* All active development occurs on the ``master`` branch (new features,
bug fixes, etc.).
#. Release branches of the form ``vMAJOR.MINOR.x`` (e.g., ``v4.0.x``,
``v4.1.x``, ``v5.0.x``).
* The ``.x`` suffix indicates that this branch is used to create
all releases in the PMIx vMAJOR.MINOR series.
* Periodically, the PMIx community will make a new release
branch, typically from ``master``.
* A Git tag of the form ``vMAJOR.MINOR.RELEASE`` is used to
indicate the specific commit on a release branch from where
official PMIx release tarball was created (e.g., ``v4.1.0``,
``v4.1.1``, ``v4.1.2``, etc.).
Once a bug is fixed or a new feature is implemented on ``master``, it is
cherry-picked over to the relevant release branch(es).
.. attention:: It may seem odd to some, but the PMIx community
development model does *not* PR bug fixes or new
features directly to release branches. Instead,
initial bug-fix / feature PRs are generally first made
to ``master``.
This helps us ensure that future releases (with
``master`` as a Git ancestor) will contain the bug fix /
feature.
For example:
.. code:: sh
shell$ git checkout master
shell$ git pull --rebase
shell$ git checkout pr/bug-fix
# ... make changes / fix a bug / etc. ...
shell$ git add ...
shell$ git commit -s ...
shell$ git push myfork
At this point, you go create a PR from your fork's ``pr/bug-fix``
branch to the PMIx community GitHub repo ``master`` branch. Work
with the community to get the PR completed and merged. Then you can
open a new PR to cherry pick the Git commits from that bug fix to each
of the relevant release branches.
Depending on how far the release branch has diverged from ``master``,
there may be some porting effort involved in the cherry-pick.
For example, if your bug fix on ``master`` is comprised of a single Git
commit hash ``123abc``:
.. code:: sh
# Fetch all upstream git activity, including the merge of the "master" PR.
shell$ get fetch --all
# Check out the target release branch, and advance to the most recent commit.
shell$ git checkout v5.0.x
shell$ git pull --rebase
# Make a branch for your bug fix
shell$ git checkout -b pr/v5.0.x/bug-fix
# Cherry pick the commit from the "master" branch
shell$ git cherry-pick -x 123abc
# Push to your fork
shell$ git push myfork
The PMIx development community *requires* adding the following
line to the commit message of cherry-picked commits on release
branches:
.. code:: text
(cherry picked from commit [git_hash_of_original_commit])
.. note:: Note the use of the ``-x`` option to ``git cherry-pick``.
This option automatically adds the ``(cherry picked from
...)`` line to your commit message.
.. admonition:: Rationale
:class: tip
Git does not actually store any meta data about Git cherry-picks in
the commit. Having a standardized text line containing the source
Git commit hash in the commit messages helps the PMIx
development community track where commits came from on release
branches, and therefore allows us to check whether all relevant
commits have been ported to a given release branch.
Once your commits are ready and pushed up to your fork, make a PR to
the target release branch.
.. warning:: A GitHub PR CI job checks all commits on release branches
for the ``(cherry picked from...)`` line. It will also
ensure that the Git hash cited in that line actually
exists on the ``master`` branch.
This check ensures that commits are not made to release
branches before their corresponding ``master`` PR was
merged.
All this being said, sometimes there is a need for a non-cherry-picked
commit on a release branch. E.g., sometimes a release branch has
diverged so much that the bug no longer exists on ``master``. It would
therefore not make sense |mdash| or even be impossible |mdash| to
commit the bug fix in question to ``master``.
In such cases, make a regular PR to the target branch (with commits
that do *not* include ``(cherry picked from ...)`` lines). In the PR
description, add a line with the following token:
.. code:: text
bot:notacherrypick
This tells the GitHub CI job that this PR contains commits that are
not cherry-picked from ``master``.
.. warning:: ``bot:notacherrypick`` should only be used when
absolutely necessary. It is not a license to avoid
the process of PR'ing to ``master`` first.
CI (testing)
------------
The PMIx community generally runs a bunch of tests on each PR
(Continuous Integration / CI). These tests are a mixture of
GitHub Actions and other CI systems (e.g., Jenkins). Examples
include (but are not limited to):
* Check each Git commit for bozo email addresses
* Check that each Git commit contains a ``Signed-off-by`` line
* Check that commits on release branches contain a cherry-pick
notice
* Build and publish the docs
* Build PMIx in a variety of environments and run sanity tests
with that installation

210
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/gnu-autotools.rst.txt Normal file
View File

@@ -0,0 +1,210 @@
.. _developers-installing-autotools-label:
Manually installing the GNU Autootools
======================================
There is enough detail in building the GNU Autotools that it warrants
its own section.
.. note:: As noted above, you only need to read/care about this
section if you are building PMIx from a Git clone. End
users installing an PMIx distribution tarball do *not*
need to have the GNU Autotools installed.
Use a package manager
---------------------
It is recommended that you use your Linux distribution's package
manager, or Homebrew or MacPorts on macOS to install recent versions
of GNU Autoconf, Automake, and Libtool.
If you cannot, keep reading in this section to see how to build and
install these applications manually (i.e., download the source from
the internet and build/install it yourself).
Autotools versions
------------------
The following tools are required for developers to compile PMIx
from its repository sources (users who download PMIx tarballs do
not need these tools - they are only required for developers working
on the internals of PMIx itself):
.. list-table::
:header-rows: 1
* - Software package
- Version
- URL
* - GNU m4
- 1.4.17
- https://ftp.gnu.org/gnu/m4/
* - GNU Autoconf
- 2.69
- https://ftp.gnu.org/gnu/autoconf/
* - GNU Automake
- 1.15
- https://ftp.gnu.org/gnu/automake/
* - GNU Libtool
- 2.4.6
- https://ftp.gnu.org/gnu/libtool/
* - Flex
- 2.5.35
- https://sourceforge.net/projects/flex/
* - Sphinx
- 4.2.0
- https://www.sphinx-doc.org/en/master/index.html
The above table lists the versions that are used to make official
release PMIx tarballs. Other versions of the
tools *may* work for some (but almost certainly not all) platforms;
the ones listed below are the versions that we know work across an
extremely wide variety of platforms and environments.
To strengthen this point: the core PMIx developers typically
use very, very recent versions of the GNU tools. There are known bugs
in older versions of the GNU tools that PMIx no longer compensates
for (it seemed senseless to indefinitely support patches for ancient
versions of Autoconf, for example).
.. warning:: You **will** have problems if you do not use recent
versions of the GNU Autotools.
That being said, ``autogen.pl`` and ``configure.ac`` scripts tend to
be a bit lenient and enforce slightly older minimum versions than the
ones listed above. This is because such older versions still make
usable PMIx builds on many platforms - especially Linux on x86_64
with GNU compilers - and are convenient for developers whose Linux
distribution may not have as recent as the versions listed above (but are
recent enough to produce a working version for their platform).
To be clear: the versions listed above are required to support a wide
variety of platforms and environments, and are used to make the official
release tarballs. When building PMIx, YMMV when using
versions older than those listed above |mdash| especially if you are
not building on Linux x86_64 with the GNU compilers.
Using older versions is unsupported. If you run into problems, upgrade
to at least the versions listed above.
.. note:: Sphinx was only recently added to the list of required tools
to generate the documentation. It is not required for PMIx
versions prior to v4.2.3.
Checking your versions
----------------------
You can check what versions of the Autotools you have installed with
the following:
.. code-block:: sh
shell$ m4 --version
shell$ autoconf --version
shell$ automake --version
shell$ libtoolize --version
Installing the GNU Autotools from source
----------------------------------------
.. note:: Most operating system packaging systems (to include Homebrew
and MacPorts on MacOS) install recent-enough versions of the
GNU Autotools. You should generally only install the GNU
Autotools manually if you can't use your operating system
packaging system to install them for you.
The GNU Autotools sources can be can be downloaded from:
* https://ftp.gnu.org/gnu/autoconf/
* https://ftp.gnu.org/gnu/automake/
* https://ftp.gnu.org/gnu/libtool/
* And if you need it: https://ftp.gnu.org/gnu/m4/
It is certainly easiest to download/build/install all four of these
tools together. But note that PMIx has no specific m4
requirements; it is only listed here because Autoconf requires minimum
versions of GNU m4. Hence, you may or may not *need* to actually
install a new version of GNU m4. That being said, if you are confused
or don't know, just install the latest GNU m4 with the rest of the GNU
Autotools and everything will work out fine.
Build and install ordering
--------------------------
You must build and install the GNU Autotools in the following order:
#. m4
#. Autoconf
#. Automake
#. Libtool
.. important:: You *must* install the last three tools (Autoconf,
Automake, Libtool) into the same prefix directory.
These three tools are somewhat inter-related, and if
they're going to be used together, they *must* share a
common installation prefix.
You can install m4 anywhere as long as it can be found in the path;
it may be convenient to install it in the same prefix as the other
three. Or you can use any recent-enough m4 that is in your path.
.. warning:: It is *strongly* encouraged that you do **not** install
your new versions over the OS-installed versions. This could cause
other things on your system to break. Instead, install into
``$HOME/local``, or ``/usr/local``, or wherever else you tend to
install "local" kinds of software.
In doing so, be sure to prefix your ``$PATH`` with the directory
where they are installed. For example, if you install into
``$HOME/local``, you may want to edit your shell startup file
(``.bashrc``, ``.cshrc``, ``.tcshrc``, etc.) to have something
like
.. code-block:: sh
# For bash/sh:
export PATH=$HOME/local/bin:$PATH
# For csh/tcsh:
set path = ($HOME/local/bin $path)
Ensure to set your ``$PATH`` *before* you configure/build/install
the four packages.
All four packages require two simple commands to build and
install:
.. code-block:: sh
shell$ cd M4_DIRECTORY
shell$ ./configure --prefix=PREFIX
shell$ make all install
.. important:: If you are using a shell that does not automatically
re-index the ``$PATH`` (e.g., the ``csh`` or ``tcsh``
shells), be sure to run the ``rehash`` command before
you install the next package so that the executables
that were just installed can be found by the next
package.
.. code-block:: sh
# Make $PATH be re-indexed if necessary, e.g., via "rehash"
shell$ cd AUTOCONF_DIRECTORY
shell$ ./configure --prefix=PREFIX
shell$ make all install
.. code-block:: sh
# Make $PATH be re-indexed if necessary, e.g., via "rehash"
shell$ cd AUTOMAKE_DIRECTORY
shell$ ./configure --prefix=PREFIX
shell$ make all install
.. code-block:: sh
# Make $PATH be re-indexed if necessary, e.g., via "rehash"
shell$ cd LIBTOOL_DIRECTORY
shell$ ./configure --prefix=PREFIX
shell$ make all install

24
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/index.rst.txt Normal file
View File

@@ -0,0 +1,24 @@
Developer's guide
=================
This section is here for those who are building/exploring the
internals of PMIx in its source code form, most likely through a
developer's tree (i.e., a Git clone).
If you are simply *using* PMIx, you probably don't need to read this
section.
.. toctree::
:maxdepth: 2
prerequisites.rst
git-github
compiler-pickyness
autogen
building-pmix
terminology
source-code
frameworks
gnu-autotools
sphinx
rst-for-markdown-expats.rst

132
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/prerequisites.rst.txt Normal file
View File

@@ -0,0 +1,132 @@
Prerequisites
=============
Compilers
---------
Although it should probably be assumed, you'll need a C compiler that
supports C99.
GNU Autotools
-------------
When building OpenPMIx from its repository sources, the GNU Autotools
must be installed (i.e., `GNU Autoconf
<https://www.gnu.org/software/autoconf/>`_, `GNU Automake
<https://www.gnu.org/software/automake/>`_, and `GNU Libtool
<https://www.gnu.org/software/libtool/>`_).
.. list-table::
:header-rows: 1
:widths: 10 10
* - Tool
- Minimum version
* - Autoconf
- |autoconf_min_version|
* - Automake
- |automake_min_version|
* - Libtool
- |libtool_min_version|
.. note:: The GNU Autotools are *not* required when building OpenPMIx
from distribution tarballs. OpenPMIx distribution tarballs
are bootstrapped such that end-users do not need to have the
GNU Autotools installed.
You can generally install GNU Autoconf, Automake, and Libtool via your
Linux distribution native package system, or via Homebrew or MacPorts
on MacOS. This usually "just works."
If you run into problems with the GNU Autotools, or need to download /
build them manually, see the :ref:`how to build and install GNU
Autotools section <developers-installing-autotools-label>` for much
more detail.
Perl
----
OpenPMIx still uses Perl for a few of its build scripts (most notably,
``autogen.pl``).
Generally speaking, any recent-ish release of Perl 5 should be
sufficient to correctly execute OpenPMIx's Perl scripts.
Flex
----
Minimum supported version: |flex_min_version|.
`Flex <https://github.com/westes/flex>`_ is used during the
compilation of a developer's checkout (it is not used to build
official distribution tarballs). Other flavors of lex are *not*
supported: given the choice of making parsing code portable between
all flavors of lex and doing more interesting work on OpenPMIx, we
greatly prefer the latter.
Note that no testing has been performed to see what the minimum
version of Flex is required by OpenPMIx. We suggest that you use
v2.5.35 at the earliest.
For now, OpenPMIx will allow developer builds with Flex |flex_min_version|. This
is primarily motivated by the fact that RedHat/CentOS 5 ships with
Flex 2.5.4. It is likely that someday OpenPMIx developer builds will
require Flex version >=2.5.35.
Note that the ``flex``-generated code generates some compiler warnings
on some platforms, but the warnings do not seem to be consistent or
uniform on all platforms, compilers, and flex versions. As such, we
have done little to try to remove those warnings.
If you do not have Flex installed and cannot easily install it via
your operating system's packaging system (to include Homebrew or
MacPorts on MacOS), see `the Flex Github repository
<https://github.com/westes/flex>`_.
Sphinx (and therefore Python)
-----------------------------
`Sphinx <https://www.sphinx-doc.org/>`_ is a Python-based tool used to
generate both the HTML version of the documentation (that you are
reading right now) and the nroff man pages.
Official OpenPMIx distribution tarballs contain pre-built HTML
documentation and man pages. This means that -- similar to the GNU
Autotools -- end users do not need to have Sphinx installed, but will
still have both the HTML documentation and man pages installed as part
of the normal configure / build / install process.
However, the HTML documentation and man pages are *not* stored in OpenPMIx's
Git repository; only the ReStructred Text source code of the
documentation is in the Git repository. Hence, if you are building
OpenPMIx from a Git clone, you will need Sphinx (and some Python
modules) in order to build the HTML documentation and man pages.
.. important:: Most systems do not have Sphinx and/or the required
Python modules installed by default. :ref:`See the
Installing Sphinx section
<developers-installing-sphinx-label>` for details on
how to install Sphinx and the required Python modules.
If ``configure`` is able to find Sphinx and the required Python
modules, it will automatically generate the HTML documentation and man
pages during the normal build procedure (i.e., during ``make all``).
If ``configure`` is *not* able to find Sphinx and/or the required
Python modules, it will simply skip building the documentation.
.. note:: If you have built/installed OpenPMIx from a Git clone and
unexpectedly did not have the man pages installed, it is
likely that you do not have Sphinx and/or the required
Python modules available.
:ref:`See the Installing Sphinx section
<developers-installing-sphinx-label>` for details on how
to install Sphinx and the required Python modules.
.. important:: ``make dist`` will fail if ``configure`` did not find
Sphinx and/or the required Python modules.
Specifically: if ``make dist`` is not able to generate
the most up-to-date HTML documentation and man pages,
you cannot build a distribution tarball. **This is an
intentional design decision.**

404
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/rst-for-markdown-expats.rst.txt Normal file
View File

@@ -0,0 +1,404 @@
.. _developers-rst-for-markdown-expats:
ReStructured Text for those who know Markdown
=============================================
You can think of RST as "Markdown, but much better". Meaning:
#. RST is basically just as simple as Markdown
#. But RST is both more precise, and has more available formatting
constructs (without getting crazy complicated)
The full Sphinx / RST documentation is available here:
https://www.sphinx-doc.org/en/master/index.html
If you're familiar with Markdown, the following sections contain some
tips to get you started in RST.
Whitespace and indenting
------------------------
* MD: Whitespace and indenting generally doesn't matter in most
cases. It does matter with bullets and sub bullets, but the rules
get pretty weird, and vary between different Markdown renderers.
* RST: **Indenting matters**. A lot. Just like Python. In
general, you indent all RST text to keep it within the same level.
For example, all this text would be a single paragraph
**Blank lines also matter**. A lot. You use blank lines to
delimit sections within an indenting level. For example, the
blank line before this paragraph denotes a paragraph break.
.. note:: RST was created by the Python community. Hence,
whitespace is quite important.
* Indenting matters
* Blank lines between content matter
Using a blank line and outdenting indicates the end of the previous
item. For example, this paragraph is not part of the MD/RST
bulleted list.
Fixed width font
----------------
* MD: Use single quotes:
.. code-block:: md
`hello world`
* RST: Use a pair of single quotes:
.. code-block:: rst
``hello world``
Italics
-------
* MD: ``*hello world*`` or ``_hello world_``
* RST: ``*hello world*``
Boldface
--------
* MD: ``**hello world**``
* RST: Same as MD
Chapter and section delimiters
------------------------------
* MD: Either use one or more pound signs (#, ##, ###) to the left of
the line of text, or underline the line of text with pound signs
* RST: Have a single line of text, underlined by non-ASCII
characters.
* The length of the underlying *must* be at least as long as the
line of text
* Which non-ASCII character is used for the underlying does not
matter, but the order in which they are used denotes chapters
/ sections / subsections / etc.
In these OpenPMIx docs, the sequence of underline characters we use
are:
.. code-block:: rst
Chapter 1: hello world
======================
.. code-block:: rst
Section 1: hello world
----------------------
.. code-block:: rst
Subsection 1: hello world
^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: rst
Subsubsection 1: hello world
++++++++++++++++++++++++++++
Meaning: underlines made of ``=`` denotes chapters, underlines
made of ``-`` denotes sections, underlines made of ``^`` denotes
subsections, and underlines made of ``+`` denote subsubsections.
Multi-line code/fixed-width font
--------------------------------
* MD: Use three single quotes to delimit blocks of text. Optionally
include a token keyword to denote the syntax highlighting to use
inside that block.
.. code-block:: md
```c
int main() { printf("Hello world\n"); return 0 }
```
* RST: Use ``.. code-block:: KEYWORD`` to start a section of code.
.. code-block:: rst
.. code-block:: c
int main() { printf("Hello world\n"); return 0 }
* KEYWORD indicates which syntax highlighting to use (e.g., ``c``,
``c++`` ``make``, ``sh``, ``ini``, ``Fortran``, ``diff``,
``python``, ``java``, ``rst``, ... etc.).
* KEYWORD can be omitted if no specific highlighting is to be
used.
* There *MUST* be a blank line after the ``code-block`` line.
* The lines in the block must be indented to the same column as the
first ``c`` in ``code-block``. For example:
.. code-block:: rst
.. code-block:: sh
shell$ tar xf pmix-<version>.tar.bz2
shell$ cd pmix-<version>
shell$ ./configure --prefix=<path> |& tee config.out
Note that the code block will be rendered at the same level as
where the first ``.`` of ``.. code-block::`` starts. In this
case, the example code block will be rendered in the bulleted
item.
Whereas this parargraph and code block will be outside of the
above bulleted list:
.. code-block:: sh
shell$ tar xf pmix-<version>.tar.bz2
shell$ cd pmix-<version>
shell$ ./configure --prefix=<path> |& tee config.out
# Fun note: the code-block can contain blank lines.
The code-block is terminated by a blank line and then outdent back
to the same level as the first ``.`` in ``.. code-block::``.
Un-numbered bullets
-------------------
* MD: Start lines with ``*`` or ``-``
* RST: Start lines with ``*``. You can wrap lines at the same
indenting level to make paragraphs in the same bullet.
Having a blank line and then more text at the same indenting level
makes another paragraph in the same bullet. You even put other
directives in this same indenting level.
* For example, you can start a sub bullet.
This text is the next paragraph in the same sub bullet.
.. code-block:: none
This is a verbatim code block within this same sub bullet.
More about code-blocks below.
This is the next paragraph (after the code block) in the same
sub bullet.
* If you start a new bullet, that terminates the previous bullet.
* You **MUST** put blank lines between bullets!
Numbered bullets:
-----------------
* MD: Start lines with ``#``
* RST: Start lines with ``#.``
.. important:: Yes, the trailing ``.`` is important
For example:
.. code-block:: rst
#. Item number 1
#. The second item
#. A third item
All the same rules for indentation apply as described above.
Comments
--------
* MD: Enclose content in ``<!--`` and ``-->`` (i.e., HTML comments,
but they are included in the output)
* RST: Start a line with two periods and a space.
For example, the following block is a comment, and will not be
included in the output:
.. code-block:: rst
.. Hello world. This is a comment. This whole block is a
comment. You can leave it here in the final document, and it
will not be included in the rendered output.
Your comment can even include blank lines. You terminate a
comment -- just like most other things in RST -- by a blank
line and then outdenting back out to the same column as the
first ".".
This line is no longer part of the comment.
Including files
---------------
* MD: You cannot include files in Markdown.
* RST: Use the ``.. include:: FILENAME`` directive. For example:
.. code-block:: rst
.. include:: features-extensions.rst
.. include:: features-java.rst
Those directives include those 2 files right here in this RST file.
.. important:: Chapter/section/subsection delimiters will be
continued in those files as part of rendering this
file.
Hyperlinks to URLs
------------------
* MD:
.. code-block:: md
[this is the link text](https://example.com/)
* RST:
.. code-block:: rst
`this is the link text <https://example.com/>`_
.. important:: Yes, the trailing underscore in RST is important.
It's a little weird, but you'll cope.
Hyperlinks to anchors
---------------------
* MD: I forget offhand how to make anchors and links to them in MD.
* RST: Use the ``:ref:`` directive.
Make an anchor like this:
.. code-block:: rst
.. _ANCHOR_NAME:
It *must* start with and underscore and end with a colon.
I've typically used anchor names that either begin with ``label-``
or end in ``-label`` to make it blatantly obvious that it's a
label. For example:
.. code-block:: rst
.. _building-and-installing-section-label:
Then you can use the ``:ref:`` directive:
.. code-block:: rst
be sure to see :ref:`the VPATH build section
<building-and-installing-section-label>`.
Hyperlinks to other (RST) pages
-------------------------------
* MD:
.. code-block:: md
[link text](page_name)
* RST: Use the ``:doc:`` directive.
General format:
.. code-block:: rst
:doc:`link text <PAGE_PATH>`
For example:
.. code-block:: rst
You should read :doc:`the Developer's Guide </developers>`.
The page path is relative to the ``docs`` dir in the OpenPMIx git tree.
Macros
------
* MD: There are no macros in Markdown.
* RST: We have defined a few OpenPMIx-specific macros in RST. You can
insert these macros anywhere in RST content text.
* ``|ompi_ver|`` is the full OpenPMIx version number, including
alpha/beta/rc/greek denotation. For example ``5.0.0rc1``.
* ``|ompi_series|`` is the major/minor OpenPMIx version, e.g.,
``5.0.x``.
.. important:: Think twice about hard-coding the OpenPMIx version
number or series when referring to the current
version or series. It can be appropriate to
hard-code an "x.y.0" version to denote a
generational epoch, but in most other cases, you
probably want to use one of the macros.
* ``|mdash|`` is a unicode long dash, an "em" dash. Use it instead
of ``--``.
* ``|rarrow|`` is a unicode right arrow. Use it instead of ``->``
or ``-->``.
Brightly-colored boxes
----------------------
* MD: There are no brightly-colored boxes in MD.
* RST: You can use various directives to make brightly-colored
"note" boxes (Called admonitions) in RST. For example:
.. important:: a green box with a "!" icon
Standard indenting rules apply for the content in the box. You
can have multiple lines and multiple paragraphs, for example.
Yippee.
* You can even have bullets.
.. code-block:: none
You can even have code blocks inside the bullet inside the
caution box.
* All the standard indenting rules apply.
.. hint:: a green box with a "!" icon
.. note:: a blue box with a "!" icon
.. caution:: an orange box with a "!" icon
.. attention:: an orange box with a "!" icon
.. warning:: an orange box with a "!" icon
.. error:: a red box with a "!" icon
.. danger:: a red box with a "!" icon
.. admonition:: Custom title
:class: tip
You can name this box whatever you want:
.. code-block:: rst
.. admonition:: Custom title
:class: tip
Content of your box here.
Custom text for this custom admonition. Note that the ``:class: <type>``
will change the coloring to the color for the basic admonition of that
type. E.g., ``:class: tip`` makes the box be green.

234
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/source-code.rst.txt Normal file
View File

@@ -0,0 +1,234 @@
Source code
===========
Code style
----------
We intentionally do not have too many code conventions in the PMIx
code base.
All languages
^^^^^^^^^^^^^
* 4 space tabs. No more, no less.
* **NEVER** use actual tab characters; always use spaces. Both emacs
and vim have secret mojo that can automatically use spaces when you
hit the ``<TAB>`` key. This makes the code look the same in every
browser, regardless of individual tab display settings.
C / C++
^^^^^^^
* When comparing constants for equality or inequality, always put the
constant on the left. This is defensive programming: if you have a
typo in the test and miss a ``!`` or ``=``, you'll get a compiler error.
For example:
.. code-block:: c
/* Do this */
if (NULL == foo) { ... }
/* Because if you have a typo (i.e., = instead of ==), this will
be a compile error rather than a subtle bug */
if (NULL = foo) { ... }
* More defensive programming: *always* include blocks in curly braces
``{ }``, even if they are only one line long. For example:
.. code-block:: c
/* Do this */
if (whatever) {
return OMPI_SUCCESS;
}
/* Not this */
if (whatever)
return OMPI_SUCCESS;
* PMIx requires a C99-compliant compiler.
* C++-style comments are now allowed (and preferred).
* C99-style mixing declarations are allow allowable (and preferred).
* **ALWAYS** include ``pmix_config.h`` as your first #include file.
There are very, very few cases where
this is not true (E.g., some bizarre Windows scenarios). But in
99.9999% of cases, this file should be included **first** so that it
can affect system-level #include files if necessary.
* Filenames and symbols must follow the **prefix rule** (see [e-mail
thread](http://www.open-mpi.org/community/lists/devel/2009/07/6389.php)):
* Filenames must be prefixed with ``<framework>_<component>``.
* Public symbols must be prefixed in components with
``pmix_<framework>_<component>``. When in doubt about
whether a symbol is public, be safe and add the prefix.
* Non-public symbols must be declared ``static`` or otherwise made to
not appear in the global scope.
* **ALWAYS** #define macros, even for logical values.
* The GNU Way is to ``#define`` a macro when it is "true" and to
``#undef`` it when it is "false".
* In PMIx, we **always** ``#define`` a logical macro to be
either 0 or 1 -- we never ``#undef`` it.
* The reason for this is defensive programming: if you are only
checking if a preprocessor macro is defined (via ``#ifdef FOO`` or
``#if defined(FOO)``), you will get no warning when compiling if
you accidentally misspell the macro name. However, if you use the
logic test ``#if FOO`` with an undefined macro (e.g., because you
misspelled it), you'll get a compiler warning or error.
.. admonition:: Rationale
:class: tip
Misspelled macro names can be tremendously difficult to find
when they are buried in thousands of lines of code; we will
take all the help from the preprocessor/compiler that we can
get!
.. code-block:: c
/* GNU Way - you will get no warning from the compiler if you
misspell "FOO"; the test will simply be false */
#ifdef FOO
...
#else
...
#endif
/* PMIx Way - you will get a warning from the compiler if you
misspell "FOO"; the result of the test is a different value
than whether you spelled the macro name right or not */
#if FOO
...
#else
...
#endif
Shell scripting
^^^^^^^^^^^^^^^
Please read some of the existing shell code in the source code tree
and try to use a similar style.
* Always enclose evaluated shell variables in quotes to ensure that
multi-token values are handled properly.
.. code-block:: sh
# This is bad
if test $foo = bar; then
# This is good
if test "$foo" = "bar"; then
* The one exception to this is that when doing an assignment to a
shell variable from another shell variable, it is not necessary to
use quotes on the right hand side:
.. code-block:: sh
# This is harmless, but unnecessary
foo="$bar"
# This is actually sufficient, even for multi-token values of $bar
foo=$bar
* Do not use the ``==`` operator for ``test`` |mdash| this is a GNU
extension and can cause portability problems on BSD systems.
Instead, use the single ``=`` operator.
.. code-block:: sh
# This is bad
if test "$foo" == "bar"; then
# This is good
if test "$foo" = "bar"; then
m4
^^^
We do not have specific coding style guidelines for m4 (the language
used to create the ``configure`` script). Please read some of the
existing m4 code in the source code tree and try to use a similar
style.
Tree layout
-----------
There are a few notable top-level directories in the source
tree:
* The main PMIx source is under the ``src`` directory
* ``config``: M4 scripts supporting the top-level ``configure`` script
* ``etc``: Some miscellaneous text files
* ``docs``: Source code for PMIx documentation
* ``examples``: Trivial example programs
* ``include``: The public PMIx headers
The ``src`` directory generates a top-level library named ``libpmix``.
It can be built as either a static or shared library. The directory
structure under it includes:
* ``class``: C++-like "classes" (using the OPAL class system)
specific to this project
* ``include``: Top-level internal include files
* ``mca``: MCA frameworks and components specific to PMIx
* ``runtime``: Startup and shutdown of PMIx at runtime
* ``tools``: Executables specific to PMIx
* ``util``: Random utility code
The layout of the ``mca`` tree is strictly defined to be of the
form:
.. code-block:: text
mca/FRAMEWORK/COMPONENT
To be explicit: it is forbidden to have a directory under the ``mca``
tree that does not meet this template (with the exception of ``base``
directories, explained below). Hence, only framework and component
code can be in the ``mca`` tree.
That is, framework and component names must be valid directory names
(and C variables; more on that later). For example, the CLIENT PTL
component is located in ``mca/ptl/client/``.
The name ``base`` is reserved; there cannot be a framework or component
named ``base``. Directories named ``base`` are reserved for the
implementation of the MCA and frameworks. Here are a few examples (as
of the |opmix_series| source tree):
.. code-block:: sh
# Main implementation of the MCA
mca/base
# Implementation of the ptl framework
mca/ptl/base
# Implementation of the client component of the ptl framework
mca/ptl/client
Under these mandated directories, frameworks and/or components may have
arbitrary directory structures, however.
Symbol Visibility
-----------------
The ``PMIX_EXPORT`` macro provides a method to annotate symbols to indicate
their intended visibility when compiling dynamically shared object files
(e.g., ``libpmix.so``).
The macro expands to the appropriate compiler and platform flags for marking
whether a symbol should be explicitly made public in the PMIx
library namespace.
The ``PMIX_EXPORT`` attribute is used to declare that a symbol is to be
visible outside of the PMIx DSO's scope.
.. note:: This is entirely related to dynamic library compilation and does not
apply to static compilation.

236
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/sphinx.rst.txt Normal file
View File

@@ -0,0 +1,236 @@
.. _developers-installing-sphinx-label:
Installing and running Sphinx (building the OpenPMIx docs)
==========================================================
As with all content in the Developer's Guide, this section is only
relevant for developers who work in the OpenPMIx code base itself.
End users who install a binary OpenPMIx package or build from an
official OpenPMIx distribution tarball do not need to have Sphinx
installed.
Installing Python
-----------------
The `Sphinx tool <https://www.sphinx-doc.org/>`_ is written in Python,
and therefore needs to have Python available. As of late 2022, Sphinx
requires Python >= v3.7.
This documentation does not contain detailed instructions for
installing a Python version sufficient for using Sphinx. Consult your
local OS documentation for how to obtain Python >= v3.7, or search the
internet for further information.
Installing Sphinx
-----------------
`The Sphinx documentation
<https://www.sphinx-doc.org/en/master/usage/installation.html>`_
recommends installing Sphinx (and its required Python dependencies)
via ``pip``, which typically requires connectivity to the general
internet.
.. note:: If you are running on MacOS, you may be tempted to use
Homebrew or MacPorts to install Sphinx. The Sphinx documentation
recommends **against** this. Instead, you should use ``pip`` to
install Sphinx.
There are three general ways to install Sphinx; you only need one of
them.
Install Sphinx in a Python virtual environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The preferred method of installing Sphinx for OpenPMIx documentation
development is to install Sphinx in a Python virtual environment.
This places Sphinx in a sandbox that will not conflict with other
``pip``-installed Python modules. This example installs Sphinx and
other Python modules in the ``ompi-docs-venv`` tree under your OpenPMIx
Git clone directory:
.. code-block:: sh
# Create the Python virtual environment
shell$ cd TOP_OF_OpenPMIx_GIT_CLONE
shell$ python3 -m venv ompi-docs-venv
# Or: python3 -m virtualenv ompi-docs-venv
# Or: virtualenv --python=python3 ompi-docs-venv
# Activate the virtual environment
shell$ . ./ompi-docs-venv/bin/activate
# Notice that the shell prompt changes
# Now install the required Python modules
(ompi-docs-venv) shell$ pip3 install -r docs/requirements.txt
# Or: python3 -m pip install install -r docs/requirements.txt
Note that sourcing the ``activate`` script will change your prompt to
put the name of your virtual environment directory at the front, just
as a visual reminder that you are operating in a Python virtual
environment. You can run ``deactivate`` to leave the virtual
environment.
.. important:: You will need to source the ``activate`` script to put
Sphinx in your ``PATH`` *before* running ``configure``.
Install Sphinx globally
^^^^^^^^^^^^^^^^^^^^^^^
If Python virtual environments are not desirable on your system, you
can install Sphinx globally on your system (you may need to run with
root privileges):
.. code-block:: sh
shell$ cd TOP_OF_OpenPMIx_GIT_CLONE
shell$ pip3 install -r docs/requirements.txt
# Or: python3 -m pip install install -r docs/requirements.txt
This will install Sphinx and some Python modules required for building
the OpenPMIx documentation in a system-wide location.
This will likely install the ``sphinx-build`` executable in a location
that is already in your ``PATH``. If the location is not already in
your ``PATH``, then you need to add it to your ``PATH``.
.. important:: You will need to ensure that Sphinx is in your ``PATH``
*before* running ``configure``.
Install Sphinx locally
^^^^^^^^^^^^^^^^^^^^^^
If you cannot or do not want to install Sphinx globally on your
system, the following will install Sphinx somewhere under your
``$HOME``. It is the same ``pip`` command as shown above, but with
the addition of the ``--user`` flag (you should not need ``root``
permissions to run this command):
.. code-block:: sh
shell$ cd TOP_OF_OpenPMIx_GIT_CLONE
shell$ pip3 install --user -r docs/requirements.txt
# Or: python3 -m pip install install -r docs/requirements.txt
This will install Sphinx and some Python modules required for building
the OpenPMIx documentation in a system-wide location.
You will likely need to find the location where ``sphinx-build`` was
installed and add it to your ``PATH``.
.. note:: On MacOS, look for ``sphinx-build`` under
``$HOME/Library/Python/VERSION/bin`` (where ``VERSION`` is
the version number of Python). Or it may have installed to
``/usr/local/bin/sphinx-build``. YMMV.
.. important:: You will need to ensure that Sphinx is in your ``PATH``
*before* running ``configure``.
Running Sphinx
--------------
OpenPMIx's build environment is setup to invoke Sphinx automatically;
you should not need to invoke Sphinx manually.
.. important:: You will need to ensure that Sphinx is in your ``PATH``
*before* running ``configure``.
As long as ``configure`` found Sphinx, ``make`` will invoke Sphinx to
build the documentation. You can also run ``make`` directly in the
``docs/`` directory to build *just* the docs and skip building the
rest of the OpenPMIx software. This can be a huge time-saver when
iteratively writing, rendering, and viewing/proofing documentation.
.. note:: The fully-built HTML and man page docs are included in
official OpenPMIx distribution tarballs. Meaning: if you
download an official distribution OpenPMIx tarball,
the pre-built HTML and man page files are included
in the tarball.
Sphinx is a requirement for *developers* who want to build
the OpenPMIx docs. End users do *not* need to have Sphinx
available to build OpenPMIx or have its docs installed from
an official distribution tarball.
Sphinx execution time
^^^^^^^^^^^^^^^^^^^^^
Sphinx is stateful: subsequent runs can be significantly faster
because Sphinx will only re-render HTML files that have changes. This
is a nice time saver for OpenPMIx (e.g., if you are iterating over
writing the docs and running ``make`` to see how they rendered in
HTML).
.. caution:: Sphinx is only *somewhat* smart in its partial
re-rendering. If you change a title in an RST file, for
example, Sphinx will (by default) only re-render *that*
page. The Tables of Contents / left hand navigation on
other pages may not be updated.
You can always force a full re-render via:
.. code:: sh
shell$ cd docs
shell$ rm -rf _build
shell$ make
Checking Sphinx HTML links
^^^^^^^^^^^^^^^^^^^^^^^^^^
``make linkcheck`` will invoke Sphinx's functionality to check all the
external links in the documentation:
.. code:: sh
shell$ cd docs
shell$ make linkcheck
.. important:: You will need to be on a computer that has good access
to the internet when running this command.
Viewing docs locally
^^^^^^^^^^^^^^^^^^^^
Once you have built the docs in your local Git clone, you can view
them locally in the build tree:
#. Open ``docs/_build/html/index.html`` in a browser to view the HTML
docs. For example, on MacOS, the following command opens the build
tree docs in the default web browser:
.. code:: sh
shell$ open docs/_build/html/index.html
#. Use the ``man`` command to view the Nroff files in
``docs/_build/man`` (you may need to use an absolute or relative
filename to prevent ``man`` from using its search paths). For
example:
.. code:: sh
shell$ cd docs/_build/man
shell$ man ./PMIx_Abort.3
Alternatively, you can view these files in their installed locations
after running ``make install``:
#. The HTML docs are installed (by default) to
``$prefix/share/doc/pmix/html``. You can use a web browser to
open the ``index.html`` in that directory to view the docs locally.
For example, on MacOS, the following command opens the installed
docs in the default web browser:
.. code:: sh
shell$ open $prefix/share/doc/pmix/html/index.html
#. The man pages are installed (by default) to ``$preix/share/man``.
If your man page search path includes this location, you can invoke
commands similar to the following to see the same content that you
see in these HTML pages:
.. code:: sh
shell$ man PMIx_Abort

54
macx64/mpi/openmpi/share/doc/pmix/html/_sources/developers/terminology.rst.txt Normal file
View File

@@ -0,0 +1,54 @@
OpenPMIx terminology
====================
OpenPMIx is a medium-sized project containing a number of different sub-systems and
a relatively big code base. Let's first cover some fundamental
terminology in order to make the rest of the discussion easier.
First, note that you will see ``OpenPMIx`` frequently referred to
as just ``PMIx``. While there is a separate PMIx Standard, there
are (as of this writing) no alternative implementations of that
Standard. In fact, the Standard post-dates the library by several
years, and often lags behind the library in terms of new definitions.
Thus, it is customary to refer to the library as just ``PMIx`` and
drop the longer name - at least, until some other implementation
arises (which many consider unlikely).
Modular Component Architecture (MCA)
------------------------------------
:ref:`See this section <label-mca>` for a discussion of the Modular
Component Architecture (MCA). Seriously. Go read it now. From
reading that section, you should understand the following terms before
continuing reading these docs:
* Framework
* Component
* Module
* Parameters (variables)
Frameworks, components, and modules can be dynamic or static. That is,
they can be available as plugins or they may be compiled statically
into libraries (e.g., ``libpmix``).
In PMIx, ``configure`` defaults to:
* Building ``libpmix`` as a dynamic library
* Linking all components directly into the ``libpmix`` libraries
(vs. compiling them as independent DSOs)
These defaults can be modified by :doc:`command line
arguments to configure
</installing-pmix/configure-cli-options/index>`.
Required 3rd party libraries
----------------------------
Note that PMIx uses two third-party libraries for core
functionality:
* Libevent or Libev
* Hardware Locality ("hwloc")
These are discussed in detail in the :ref:`required support libraries
section <label-install-required-support-libraries>`.

1620
macx64/mpi/openmpi/share/doc/pmix/html/_sources/exceptions.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

21
macx64/mpi/openmpi/share/doc/pmix/html/_sources/getting-help.rst.txt Normal file
View File

@@ -0,0 +1,21 @@
Getting help
============
Found a bug? Got a question? Want to make a suggestion? Want to
contribute to OpenPMIx? Please let us know!
Many common questions about building and using OpenPMIx are answered
in these documents. If they aren't enough, questions and comments should generally be
posted to the `OpenPMIx GitHub issue tracker
<https://github.com/openpmix/openpmix/issues>`_.
Alternatively, questions can also be sent to the `OpenPMIx mailing list
<https://groups.google.com/d/forum/pmix>`_
(pmix@googlegroups.com). Because of spam, only subscribers are
allowed to post to this list (ensure that you subscribe with and post
from *exactly* the same e-mail address -- joe@example.com is
considered different than joe@mycomputer.example.com!).
When submitting questions and problems, be sure to include as much
extra information as possible. A list of requested information is
provided in the "issues" template.

20
macx64/mpi/openmpi/share/doc/pmix/html/_sources/history.rst.txt Normal file
View File

@@ -0,0 +1,20 @@
History
========
The Process Management Interface (PMI) has been used for quite some
time as a means of exchanging wireup information needed for
interprocess communication. Two versions (PMI-1 and PMI-2) have been
released as part of the MPICH effort. While PMI-2 demonstrates better
scaling properties than its PMI-1 predecessor, attaining rapid launch
and wireup of the roughly 1M processes executing across 100k nodes
expected for exascale operations remains challenging.
PMI Exascale (PMIx) represents an attempt to resolve these questions
by providing an extended version of the PMI standard specifically
designed to support clusters up to and including exascale sizes. The
overall objective of the project is not to branch the existing
pseudo-standard definitions - in fact, PMIx fully supports both of the
existing PMI-1 and PMI-2 APIs - but rather to (a) augment and extend
those APIs to eliminate some current restrictions that impact
scalability, and (b) provide a reference implementation of the
PMI-server that demonstrates the desired level of scalability.

12
macx64/mpi/openmpi/share/doc/pmix/html/_sources/how-things-work/index.rst.txt Normal file
View File

@@ -0,0 +1,12 @@
How Things Work
===============
This section explains how some of the functions inside
PMIx perform their job. If you have questions about, for
example, how device distances are computed, then you will
find information on that subject here.
.. toctree::
:maxdepth: 2
session_dirs.rst

114
macx64/mpi/openmpi/share/doc/pmix/html/_sources/how-things-work/session_dirs.rst.txt Normal file
View File

@@ -0,0 +1,114 @@
Session Directories
===================
In general, servers, tools, and application processes all have access to their own ``session directory`` - a location where scratch files can be safely placed with a reasonable guarantee of automatic cleanup upon termination. Session directories provide a safe location (i.e., in a temporary file system and guaranteed not to conflict with other sessions/jobs/applications) for executables to use when creating scratch files such as shared memory backing files and rendezvous files. PMIx and PRRTE also provide a reasonable guarantee that any files and/or subdirectories created under the specified location will be automatically cleaned up at finalize and/or termination. In this case, ``reasonable`` means that we will do our best to remove all files and subdirectories, but cannot fully guarantee removal in situations outside of our control (e.g., being forcibly terminated via `SIGKILL`).
.. note:: In general, the host (e.g., PRRTE) is responsible for creating session
directories. In some cases, PMIx creates a limited set of session
directories if the host does not provide them - e.g., in the case of a
self-launched tool - for storing contact information. This is outlined
below.
The following attributes can be used to pass session directory information to the PMIx library:
* ``PMIX_SYSTEM_TMPDIR``: temporary directory for this system (typically ``/tmp`` for Linux systems).
The PMIx server will place tool rendezvous points and contact info in this location. In the
absence of this attribute during ``PMIx_Init`` (or the server/tool version), the PMIx library
will first look for the ``TMPDIR`` envar, then ``TEMP``, and finally ``TMP`` - if none of
those are found, the library will default to the ``/tmp`` location.
* ``PMIX_SERVER_TMPDIR``: session directory where the PMIx server will place client rendezvous
points and contact info. If not provided, the library will first look for the ``PMIX_SERVER_TMPDIR``
envar, then ``TMPDIR``, ``TEMP``, and finally ``TMP`` - if none of those are found, the
library will default to the ``/tmp`` location.
* ``PMIX_TMPDIR``: top-level temporary directory assigned to a session. Often equated to
``PMIX_SERVER_TMPDIR`` by host environments.
* ``PMIX_NSDIR``: session directory assigned to a namespace. Usually placed underneath the
``PMIX_SERVER_TMPDIR`` and given a name based on the namespace itself.
* ``PMIX_PROCDIR``: session directory assigned to an individual process. Usually placed underneath
the ``PMIX_NSDIR`` assigned to the namespace of the process, and given a string name equivalent
to the rank of the process.
* ``PMIX_LAUNCHER_RENDEZVOUS_FILE``: the full path name of a file wherein a tool shall output its
connection information - e.g., a launcher to store contact information so that a debugger
can attach to it.
* ``PMIX_TDIR_RMCLEAN``: the host environment (often known as the "resource manager" or "RM") will
cleanup the session directories. In the absence of this attribute, the PMIx library will
remove all files in any session directory it created and then remove the directory itself.
These same attributes can be used in calls to ``PMIx_Get`` by application processes to retrieve
the session directory locations for their own use.
Client Session Directories
--------------------------
The PMIx client library does not create its own session directories as it does not publish
contact information. Host daemons often create one or more session directory levels for use
by client application processes (e.g., for storing shared memory backing files) - the location
of those directories is passed to clients using the above attributes.
As the client library never creates session directories, it does not perform any cleanup of
the session directory tree.
Tool and Server Session Directories
-----------------------------------
The PMIx library utilizes appropriate session directory locations to store one or more
"rendezvous files" - i.e., files containing connection information. Note that the library does not
always create all levels of the session directory tree, although the process
itself can of course create directories as it sees fit. Only the directories that (a) are required
for generating the particular rendezvous file, and (b) do not already exist are created. Only
directories actually created by the library are cleaned up and removed upon finalization.
The following rendezvous files are provided:
* if ``PMIX_LAUNCHER_RENDEZVOUS_FILE`` is given (either via an attribute to an "init" function
or as an envar), then the specified file (including any required path elements) will be created.
* if the server is designated as a "system" server (i.e., the ``PMIX_SERVER_SYSTEM_SUPPORT`` attribute
was provided to ``PMIx_server_init``), then a rendezvous file named "pmix.sys.<hostname>" will be
created in the ``PMIX_SYSTEM_TMPDIR`` location.
* if the server is designated as a "session" server (i.e., the ``PMIX_SERVER_SESSION_SUPPORT`` attribute
was provided to ``PMIx_server_init``), then a rendezvous file named "pmix.sys.<hostname>" will be
created in the ``PMIX_SERVER_TMPDIR`` location.
* if the server declares that it will support tool connections (i.e., the ``PMIX_SERVER_TOOL_SUPPORT``
attribute was provided to ``PMIx_server_init``), then the following rendezvous files will be created
under the ``PMIX_SERVER_TMPDIR`` location:
* a PID file: "pmix.<hostname>.<pid>"
* a namespace file using the nspace of the server: "pmix.<hostname>.<nspace>"
* if the server is designated as a "scheduler" (i.e., the ``PMIX_SERVER_SCHEDULER`` attribute
was provided to ``PMIx_server_init``), then a rendezvous file named "pmix.sched.<hostname>" will be
created in the ``PMIX_SYSTEM_TMPDIR`` location.
* if the server is designated as a "system controller" (i.e., the ``PMIX_SERVER_SYS_CONTROLLER`` attribute
was provided to ``PMIx_server_init``), then a rendezvous file named "pmix.sysctrlr.<hostname>" will be
created in the ``PMIX_SYSTEM_TMPDIR`` location.
.. note:: The above rendezvous files are additive - i.e., generating any one of the files has
no bearing on whether another file will be output. Thus, a single server could
generate anywhere from one to five (or more) rendezvous files spanning several
directory levels.
.. warning:: There is a potential conflict in rendezvous file names - e.g., if multiple processes
declare themselves to be a "session" server on the same node. The format of the
names used by PMIx are intended to support tool connection in the absence of specific
connection directives - i.e., they provide a means by which PMIx can search for and
find the rendezvous file for a particular type of process without requiring the user
to manually identify it. Thus, a tool can request connection to the "system controller"
without necessarily knowing the PID of that process and PMIx can facilitate the
connection. As a result, only one system server can be operating on a node at a time.
This is also (independently) true for schedulers and system controllers.

66
macx64/mpi/openmpi/share/doc/pmix/html/_sources/index.rst.txt Normal file
View File

@@ -0,0 +1,66 @@
OpenPMIx |opmix_ver|
====================
The charter of the PMIx community is to:
#. Develop an open source (non-copy-left licensed) and independent
(i.e., not affiliated with any specific programming model code
base) standalone library to support application interactions with
Resource Managers (RMs).
#. Retain transparent compatibility with the existing PMI-1 and PMI-2
definitions, and any future PMI releases.
#. Support the *Instant On* initiative for rapid startup of
applications at exascale and beyond.
#. Work with the HPC community to define and implement new APIs that
support evolving programming model requirements for application-RM
interactions.
.. note:: You will see ``OpenPMIx`` frequently referred to
as just ``PMIx``. While there is a separate PMIx Standard, there
are (as of this writing) no alternative implementations of that
Standard. In fact, the Standard post-dates the library by several
years, and often lags behind the library in terms of new definitions.
Thus, it is customary to refer to the library as just ``PMIx`` and
drop the longer name - at least, until some other implementation
arises (which many consider unlikely).
PMIx is designed to be particularly easy for resource managers to
adopt, thus facilitating a rapid uptake into that community for
application portability. Both client and server libraries are
included, along with reference examples of client usage and
server-side integration.
PMIx targets support for the Linux operating system. A reasonable
effort is made to support all major, modern Linux distributions;
however, validation is limited to the most recent 2-3 releases of
RedHat Enterprise Linux (RHEL), Fedora, CentOS, and SUSE Linux
Enterprise Server (SLES). Support for vendor-specific operating
systems is included as provided by the vendor.
Table of contents
=================
.. toctree::
:maxdepth: 2
:numbered:
quickstart
getting-help
release-notes/index
exceptions
installing-pmix/index
how-things-work/index
release-notes
history
versions
mca
building-apps/index
developers/index
contributing
license
security
news/index
man/index

77
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/compilers-and-flags.rst.txt Normal file
View File

@@ -0,0 +1,77 @@
.. _install-configure-compilers-and-flags-label:
Specifying compilers and flags
==============================
Changing the compilers that PMIx uses to build itself uses the
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``:
* ``CC``: C compiler to use
* ``CFLAGS``: Compile flags to pass to the C compiler
* ``CPPFLAGS``: Preprocessor flags to pass to the C compiler
* ``LDFLAGS``: Linker flags to pass to all compilers
* ``LIBS``: Libraries to pass to all compilers (it is rarely
necessary for users to need to specify additional ``LIBS``)
* ``PKG_CONFIG``: Path to the ``pkg-config`` utility
.. note:: PMIx |opmix_ver| does not contain any C++ code. However,
you can use a C++ compiler to build PMIx if you so choose.
For example, to build with a specific instance of ``gcc``:
.. code-block:: sh
shell$ ./configure \
CC=/opt/gcc-a.b.c/bin/gcc CFLAGS=-m64 ...
.. note:: The PMIx 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.
.. warning:: Note that setting ``CFLAGS`` (etc.) does *not* affect the
flags used by the :ref:`wrapper compiler
<label-quickstart-building-apps>`. In the above, example, you may
also need to add ``-m64`` to the ``--with-wrapper-cflags``
option:
.. code-block::
shell$ ./configure CFLAGS=-m64 \
--with-wrapper-cflags=-m64 ...
Failure to do this will result in PMIx-based applications
failing to compile / link properly.
See the :ref:`Customizing wrapper compiler behavior
<label-customizing-wrapper-compiler>` section for more
details.
Note that if you intend to compile PMIx with a ``make`` other than
the default one in your ``PATH``, then you must either set the ``$MAKE``
environment variable before invoking PMIx's ``configure`` script, or
pass ``MAKE=your_make_prog`` to configure. For example:
.. code-block:: sh
shell$ ./configure MAKE=/path/to/my/make ...
This could be the case, for instance, if you have a shell alias for
``make``, or you always type ``gmake`` out of habit. Failure to tell
``configure`` which non-default ``make`` you will use to compile PMIx
can result in undefined behavior (meaning: don't do that).
Note that you may also want to ensure that the value of
``LD_LIBRARY_PATH`` is set appropriately (or not at all) for your build
(or whatever environment variable is relevant for your operating
system). For example, some users have been tripped up by setting to
use a non-default C compiler via the ``CC`` environment variable,
but then failing to set ``LD_LIBRARY_PATH`` to include the directory
containing that non-default C compiler's support libraries.
This causes PMIx's ``configure`` script to fail when it tries to
compile / link / run simple C programs.

58
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/configure-cli-options/conventions.rst.txt Normal file
View File

@@ -0,0 +1,58 @@
.. _building-pmix-cli-options-conventions-label:
``configure`` CLI option conventions
------------------------------------
``configure`` will, by default, search for header files and/or
libraries for various optional features (e.g., various network
support libraries). If the relevant files are found, PMIx
will built support for that feature. If they are not found, PMIx
will skip building support for that feature.
However, if you specify ``--with-FOO`` (where ``FOO`` is the
corresponding CLI option name for the feature) on the ``configure``
command line and PMIx is unable to find relevant support for
``FOO``, ``configure`` will assume that it was unable to provide a
feature that was specifically requested, and will therefore abort so
that a human can resolve out the issue.
.. note:: Using ``--with-FOO`` to force PMIx's ``configure``
script to abort it if can't find support for a given feature
may be preferable to unexpectedly discovering at run-time
that PMIx is missing support for a critical feature.
Additionally, if a search directory is specified for ``FOO`` in the
form ``--with-FOO=DIR``, PMIx will:
#. Search for ``FOO``'s header files in ``DIR/include``.
#. Search for ``FOO``'s library files:
#. If ``--with-FOO-libdir=LIBDIR`` was specified, search in
``LIBDIR``.
#. Otherwise, search in ``DIR/lib64``, and if they are not found
there, search again in ``DIR/lib``.
#. If both the relevant header files and libraries are found:
#. PMIx will build support for ``FOO``.
#. If the root path where the FOO libraries are found is neither
``/usr`` nor ``/usr/local``, PMIx will compile itself with
RPATH flags pointing to the directory where ``FOO``'s libraries
are located.
.. important:: PMIx does not RPATH ``/usr/lib[64]`` and
``/usr/local/lib[64]`` because many systems
already search these directories for run-time
libraries by default; adding RPATH for them could
have unintended consequences for the search path
ordering.
.. caution:: The ``--with-FOO-libdir=LIBDIR`` options are not usually
needed; they are typically only needed when ``FOO``'s libraries are
installed in an "unexpected" location.
Also note the difference between ``--with-FOO=DIR`` and
``--with-FOO-libdir=LIBDIR``: the former is a directory to which
suffixes such as ``/include`` and ``/lib`` are added, whereas the
latter is assumed to be a full library directory name (e.g.,
``/opt/some_library/lib``).

18
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/configure-cli-options/index.rst.txt Normal file
View File

@@ -0,0 +1,18 @@
``configure`` command line options
==================================
There are many available ``configure`` command line options; see
``./configure --help`` for a full list.
Conventions for the command line options and many commonly-used
options (but not all of them!) are described in the sections listed
below.
.. toctree::
:maxdepth: 1
conventions
installation
runtime
required-support-libraries
rpath-and-runpath

316
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/configure-cli-options/installation.rst.txt Normal file
View File

@@ -0,0 +1,316 @@
.. _label-building-installation-cli-options:
Installation options
^^^^^^^^^^^^^^^^^^^^
The following are general installation command line options that can
be used with ``configure``:
* ``--prefix=DIR``:
Install PMIx into the base directory named ``DIR``. Hence, PMIx
will place its executables in ``DIR/bin``, its header files in
``DIR/include``, its libraries in ``DIR/lib``, etc.
.. note:: Also see the section on :ref:`installation location
<building-pmix-installation-location-label>` for more
information on the installation prefix.
* ``--disable-shared``: By default, PMIx builds a
shared library, and all components are included as part of those
shared library. This switch disables this default; it is really
only useful when used with ``--enable-static``. Specifically, this
option does *not* imply ``--enable-static``; enabling static
libraries and disabling shared libraries are two independent
options.
.. tip::
:ref:`See this section <label-install-packagers-dso-or-not>` for
advice to packagers about this CLI option.
* ``--enable-static``:
Build PMIx as a static library, and statically link in
all components. Note that this option does *not* imply
``--disable-shared``; enabling static libraries and disabling shared
libraries are two independent options.
.. tip::
:ref:`See this section <label-install-packagers-dso-or-not>` for
advice to packagers about this CLI option.
* ``--disable-wrapper-runpath`` / ``--disable-wrapper-rpath``: By
default, the wrapper compiler (``pmixcc``) will explicitly add
"runpath" and "rpath" linker flags when linking user executables on
systems that support them. That is, the created executables will
include a filesystem path reference to the location of PMIx's
libraries in the application executable itself. This means that the
user does not have to set ``LD_LIBRARY_PATH`` to find PMIx's
libraries, which can be helpful if they are installed in a location
that the run-time linker does not search by default.
Using the ``--disable-wrapper-r*path`` options will prevent the
wrappers from explicitly adding one or both of these linker flags.
.. note:: By default, the wrapper compiler prefers "runpath"
behavior over "rpath" behavior.
* Using ``--disable-wrapper-runpath`` alters this
preference: explicit "runpath" linker flags will not be
added by the wrapper. However, "rpath" flags may still
be added, if the platform supports them.
* Using both ``--disable-wrapper-runpath`` *and*
``--disable-wrapper-rpath`` will prevent the wrapper
from explicitly adding "runpath" *and* "rpath" linker
flags.
.. caution:: Even if the wrapper compiler does not explicitly add
"runpath" or "rpath" linker flags, the local compiler,
linker, and/or operating system may implicitly enable
either "runpath" or "rpath" behavior when linking.
.. important:: The ``--disable-wrapper-runpath`` and
``--disable-wrapper-rpath`` CLI options *only* affect
the flags that the wrapper compiler uses when
building PMIx-based applications. These options do
not affect how PMIx is built (to
include the wrapper compiler itself).
See the :ref:`Linker "rpath" and "runpath"
functionality
<building-pmix-cli-options-rpath-and-runpath-label>`
section for details on how "rpath" and "runpath"
affect the building and linking of PMIx itself.
When either of "runpath" or "rpath" behaviors are enabled, the
applications will have the filesystem path location of the PMIx
library hard-coded into a PMIx-based application. The
most notable differences between "runpath" and "rpath" behavior are:
* runpath
#. The run-time linker first searches the paths in the
``LD_LIBRARY_PATH`` environment variable for the relevant PMIx
library.
#. If not found there, the run-time linker falls back to checking
the hard-coded location for the relevant PMIx
library.
* rpath
#. The run-time linker first checks the hard-coded location for
the relevant PMIx library.
#. If not found there, the run-time linker falls back to
searching the paths in the ``LD_LIBRARY_PATH`` environment
variable for the relevant PMIx library.
.. warning:: There are other, subtle differences between "runpath"
and "rpath" which are out of scope for this
documentation. You may wish to consult other sources
for more information.
For example, a decent set of explanations can be found
in the slides for a Linux course entitled "Building and
Using Shared Libraries on Linux // `Shared Libraries:
The Dynamic Linker
<https://man7.org/training/download/shlib_dynlinker_slides.pdf>`_".
For example, consider that you install PMIx vA.B.0 and
compile/link your PMIx-based application against it. Later, you
install PMIx vA.B.1 to a different installation prefix (e.g.,
``/opt/pmix/A.B.1`` vs. ``/opt/pmix/A.B.0``), and you leave
the old installation intact.
In the runpath case, you can set the ``LD_LIBRARY_PATH`` environment
variable to point to the A.B.1 installation, and then your
application will use those libraries, since the runtime will search
the paths in ``LD_LIBRARY_PATH`` first.
In the rpath case, since the run-time linker searches the
``/opt/pmix/A.B.0`` location that is hard-coded in your
application first, your application will use the libraries from your
A.B.0 installation (regardless of the value of the
``LD_LIBRARY_PATH`` environment variable).
Note that in both cases, however, if you remove the original A.B.0
installation and set ``LD_LIBRARY_PATH`` to point to the A.B.1
installation, your application will use the A.B.1 libraries.
As noted above, both runpath/rpath behaviors can be disabled via
``--disable-wrapper-rpath``.
.. note:: You can also :ref:`customize the compiler/linker flags
that are used by the wrapper compilers
<label-customizing-wrapper-compiler>` to build PMIx-based
applications.
* ``--enable-dlopen``: Enable PMIx to load components as
standalone Dynamic Shared Objects (DSOs) at run-time. This option
is enabled by default.
The opposite of this option, ``--disable-dlopen``, causes the following:
#. PMIx will not attempt to open any DSOs at run-time.
#. configure behaves as if the ``--enable-mca-static`` argument was set.
#. configure will ignore the ``--enable-mca-dso`` argument.
See the description of ``--enable-mca-static`` / ``--enable-mca-dso`` for
more information.
.. note:: This option does *not* change how PMIx's libraries
(``libpmix``, for example) will be built. You can change
whether PMIx builds static or dynamic libraries via
the ``--enable|disable-static`` and
``--enable|disable-shared`` arguments.
.. _building-pmix-cli-options-mca-dso-label:
* ``--enable-mca-dso[=LIST]`` and ``--enable-mca-static[=LIST]``
These two options, along with ``--enable-mca-no-build``, govern the
behavior of how PMIx's frameworks and components are built.
The ``--enable-mca-dso`` option specifies which frameworks and/or
components are built as Dynamic Shared Objects (DSOs).
Specifically, DSOs are built as "plugins" outside of the core PMIx
library, and are loaded by PMIx at run time.
The ``--enable-mca-static`` option specifies which frameworks and/or
components are built as part of the core PMIx library (i.e.,
they are not built as DSOs, and therefore do not need to be
separately discovered and opened at run time).
Both options can be used one of two ways:
#. ``--enable-mca-OPTION`` (with no value)
#. ``--enable-mca-OPTION=LIST``
``--enable-mca-OPTION=no`` or ``--disable-mca-OPTION`` are both legal
options, but have no impact on the selection logic described below.
Only affirmative options change the selection process.
``LIST`` is a comma-delimited list of PMIx frameworks and/or
framework+component tuples. Examples:
* ``ptl`` specifies the entire PTL framework
* ``ptl-client`` specifies just the CLIENT component in the PTL framework
* ``plog,ptl-client`` specifies the entire PLOG framework and the CLIENT
component in the PTL framework
PMIx's ``configure`` script uses the values of these two options
when evaluating each component to determine how it should be built
by evaluating these conditions in order:
#. If an individual component's build behavior has been specified
via these two options, ``configure`` uses that behavior.
#. Otherwise, if the component is in a framework whose build
behavior has been specified via these two options, ``configure``
uses that behavior.
#. Otherwise, ``configure`` uses the global default build behavior.
At each level of the selection process, if the component is
specified to be built as both a static and dso component, the static
option will win.
.. note:: As of PMIx v4.2.3, ``configure``'s global default
is to build all components as static (i.e., part of the
PMIx core library, not as DSOs). Prior to PMIx
4.2.3, the global default behavior was to build
most components as DSOs.
.. important:: If the ``--disable-dlopen`` option is specified, then
PMIx will not be able to search for DSOs at run
time, and the value of the ``--enable-mca-dso``
option will be silently ignored.
Some examples:
#. Default to building all components as static (i.e., as part of
the PMIx core libraries -- no DSOs)::
shell$ ./configure
#. Build all components as static, except the CLIENT PTL, which will be
built as a DSO::
shell$ ./configure --enable-mca-dso=ptl-client
#. Build all components as static, except all PTL components, which
will be built as DSOs::
shell$ ./configure --enable-mca-dso=ptl
#. Build all components as static, except all PLOG components and the
CLIENT PTL component, which will be built as DSOs::
shell$ ./configure --enable-mca-dso=plog,ptl-client
#. Build all PTLs as static, except the CLIENT PTL, as the
``<framework-component>`` option is more specific than the
``<framework>`` option::
shell$ ./configure --enable-mca-dso=ptl --enable-mca-static=ptl-client
#. Build the CLIENT PTL as static, because the static option at the
same level always wins::
shell$ ./configure --enable-mca-dso=ptl-client --enable-mca-static=ptl-client
.. tip::
:ref:`See this section <label-install-packagers-dso-or-not>` for
advice to packagers about this CLI option.
* ``--enable-mca-no-build=LIST``: Comma-separated list of
``<framework>-<component>`` pairs that will not be built. For
example, ``--enable-mca-no-build=plog-syslog,psensor-file`` will
disable building both the ``syslog`` PLOG component and the
``file`` PSENSOR component.
.. note:: This option is typically only useful for components that
would otherwise be built. For example, if you are on a
machine without OmniPath support, it is not necessary to
specify::
shell$ ./configure --enable-mca-no-build=pnet-opa
because the ``configure`` script will naturally see that
you do not have support for OmniPath and will
automatically skip the ``opa`` PNET component.
* ``--disable-show-load-errors-by-default``:
Set the default value of the ``mca_base_component_show_load_errors``
MCA variable: the ``--enable`` form of this option sets the MCA
variable to true, the ``--disable`` form sets the MCA variable to
false. The MCA ``mca_base_component_show_load_errors`` variable can
still be overridden at run time via the usual MCA-variable-setting
mechanisms; this configure option simply sets the default value.
The ``--disable`` form of this option is intended for PMIx
packagers who tend to enable support for many different types of
networks and systems in their packages. For example, consider a
packager who includes support for both the FOO and BAR networks in
their PMIx package, both of which require support libraries
(``libFOO.so`` and ``libBAR.so``). If an end user only has BAR
hardware, they likely only have ``libBAR.so`` available on their
systems -- not ``libFOO.so``. Disabling load errors by default will
prevent the user from seeing potentially confusing warnings about
the FOO components failing to load because ``libFOO.so`` is not
available on their systems.
Conversely, system administrators tend to build an PMIx that is
targeted at their specific environment, and contains few (if any)
components that are not needed. In such cases, they might want
their users to be warned that the FOO network components failed to
load (e.g., if ``libFOO.so`` was mistakenly unavailable), because PMIx
may otherwise silently fail to provide support for that network.
* ``--with-platform=FILE``:
Load configure options for the build from ``FILE``. Options on the
command line that are not in ``FILE`` are also used. Options on the
command line and in ``FILE`` are replaced by what is in ``FILE``.
* ``--with-libpmix-name=STRING``:
Replace ``libpmix.*`` with ``libSTRING.*``. This is provided as a convenience mechanism
for third-party packagers of PMIx that might want to rename
these libraries for their own purposes. This option is *not*
intended for typical users of PMIx.

36
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/configure-cli-options/required-support-libraries.rst.txt Normal file
View File

@@ -0,0 +1,36 @@
.. _label-building-pmix-cli-options-required-support-libraries:
CLI Options for required support libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following ``configure`` command line options are for PMIx's
:ref:`required support libraries
<label-install-required-support-libraries>`
* ``--with-hwloc[=VALUE]``:
* ``--with-libevent[=VALUE]``:
* ``--with-libev[=VALUE]``:
These options specify where to find
the headers and libraries for the `Hwloc
<https://www.open-mpi.org/projects/hwloc/>`_, `Libevent
<https://libevent.org/>`_, and `libev <https://metacpan.org/dist/EV/view/libev/ev.pod/>`_ libraries,
respectively.
.. note:: Either ``libevent`` *or* ``libev`` must be provided.
PMIx's ``configure`` script will error out if both
are specified. In the absence of user direction,
PMIx will default to using ``libevent``.
The following ``VALUE``\s are permitted:
* ``DIR``: Specify the location of a specific installation to use.
``configure`` will abort if it cannot find suitable header files
and libraries under ``DIR``.
* ``--with-hwloc-libdir=LIBDIR``:
* ``--with-libevent-libdir=LIBDIR``:
* ``--with-libev-libdir=LIBDIR``:
:ref:`See the configure CLI
options conventions <building-pmix-cli-options-conventions-label>`
for a description of these options.

63
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/configure-cli-options/rpath-and-runpath.rst.txt Normal file
View File

@@ -0,0 +1,63 @@
.. _building-pmix-cli-options-rpath-and-runpath-label:
Linker "rpath" and "runpath" functionality
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PMIx |opmix_ver| is composed of multiple
libraries that depend on each other.
When built from official distribution tarballs,
PMIx is built with the following versions of the
GNU Autotools:
* Autoconf |autoconf_min_version|
* Automake |automake_min_version|
* Libtool |libtool_min_version|
This set of GNU Autotools invokes the ``libtool`` executable to build
PMIx's libraries and executables with the `-rpath CLI option
<https://www.gnu.org/software/libtool/manual/html_node/Link-mode.html#Link-mode>`_.
The behavior of ``libtool -rpath ...`` is, unfortunately, highly
system-dependent. In conjunction with compiler-, linker-, and other
system-level settings, the end result may be to effect "rpath"
behavior, "runpath" behavior, or possibly even neither behavior.
Although the specific behavior of ``libtool -rpath ..`` is outside the
scope of this documentation, you can run commands such as ``readelf -d
...`` to find out with which behavior your PMIx was built.
For example:
.. code::
shell$ ./configure --prefix=/opt/pmix/ ...
...
shell$ make -j 32 all && make install
...
shell$ readelf -d /opt/pmix/lib/libmpi.so | egrep -i 'rpath|runpath'
0x000000000000001d (RUNPATH) Library runpath: [/opt/pmix/lib]
The above output indicates that ``libpmix.so`` was built with "runpath"
support, whereas output like this:
.. code::
shell$ readelf -d /opt/pmix/lib/libpmix.so | egrep -i 'rpath|runpath'
0x000000000000000f (RPATH) Library rpath: [/opt/pmix/lib]
indicates that ``libpmix.so`` was built with "rpath" support.
.. note:: If you want to utilize additional compiler or linker flags
(such as runpath flags) when building PMIx,
you can :ref:`specify these flags on the configure command
line <install-configure-compilers-and-flags-label>`.
For example, if invoking ``libtool -rpath ...`` on your
system actually effects "rpath" behavior, and you wish to
effect "runpath" behavior, you could set ``LDFLAGS`` when
invoking ``configure``, like this:
.. code-block:: sh
shell$ ./configure LDFLAGS=-Wl,--enable-new-dtags ...

46
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/configure-cli-options/runtime.rst.txt Normal file
View File

@@ -0,0 +1,46 @@
.. This file is included by building-pmix.rst
Run-time system support
^^^^^^^^^^^^^^^^^^^^^^^
The following are command line options for various runtime systems that
can be used with ``configure``:
* ``--with-alps``:
Force the building of for the Cray Alps run-time environment. If
Alps support cannot be found, configure will abort.
* ``--with-lsf=DIR``:
Specify the directory where the LSF libraries and header files are
located. This option is generally only necessary if the LSF headers
and libraries are not in default compiler/linker search paths.
LSF is a resource manager system, frequently used as a batch
scheduler in HPC systems.
* ``--with-lsf-libdir=DIR``:
Look in directory for the LSF libraries. By default, Open MPI will
look in ``DIR/lib`` and ``DIR/lib64``, which covers most cases. This
option is only needed for special configurations.
* ``--with-slurm``:
Force the building of Slurm scheduler support.
* ``--with-sge``:
Specify to build support for the Oracle Grid Engine (OGE) resource
manager and/or the Open Grid Engine. OGE support is disabled by
default; this option must be specified to build OMPI's OGE support.
The Oracle Grid Engine (OGE) and open Grid Engine packages are
resource manager systems, frequently used as a batch scheduler in
HPC systems. It used to be called the "Sun Grid Engine", which is
why the option is still named ``--with-sge``.
* ``--with-tm=DIR``:
Specify the directory where the TM libraries and header files are
located. This option is generally only necessary if the TM headers
and libraries are not in default compiler/linker search paths.
TM is the support library for the Torque and PBS Pro resource
manager systems, both of which are frequently used as a batch
scheduler in HPC systems.

13
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/configure-output-summary.rst.txt Normal file
View File

@@ -0,0 +1,13 @@
``configure`` output summary
============================
At the end of ``configure``, a summary of many configuration options
are shown.
The PMIx Team *highly* recommends examining the ``configure``
summary to validate that PMIx plans to build all the features that
you expect it to build.
If the summary does not agree with what you think should be done, you
can look earlier in ``configure``'s output to see why particular
options and behaviors were selected.

16
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/definitions.rst.txt Normal file
View File

@@ -0,0 +1,16 @@
Definitions
===========
* **Source tree:** The tree where the PMIx source code is located.
It is typically the result of expanding an PMIx distribution
source code bundle, such as a tarball.
* **Build tree:** The tree where PMIx was built. It is always
related to a specific source tree, but may actually be a different
tree (:ref:`since PMIx supports VPATH builds
<building-pmix-vpath-label>`). Specifically, this is the tree
where you invoked ``configure``, ``make``, etc. to build and install
PMIx.
* **Installation tree:** The tree where PMIx was installed. It is
typically the "prefix" argument given to PMIx's ``configure``
script; it is the directory from which you run installed PMIx
executables.

24
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/filesystem-requirements.rst.txt Normal file
View File

@@ -0,0 +1,24 @@
Filesystem requirements
=======================
.. _install-filesystem-timestamp-warning-label:
.. warning:: If you are building PMIx on a network filesystem, the
machine you on which you are building *must* be time-synchronized
with the file server.
Specifically: PMIx's build system *requires* accurate filesystem
timestamps. If your ``make`` output shows that it ran GNU Automake,
Autoconf, and/or Libtool, or includes warning about timestamps in the
future, perhaps looking something like this::
Warning: File `Makefile.am' has modification time 3.6e+04 s in the future
**Know that this is not normal**, and you likely have an invalid
build.
In this case, you should remove the PMIx source directory and
start over (e.g., by re-extracting the PMIx tarball): either
switch to build on a local filesystem, or ensure that the time on your
build machine is synchronized with the time on your file server before
building again.

19
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/index.rst.txt Normal file
View File

@@ -0,0 +1,19 @@
.. _building-and-installing-section-label:
Building and installing PMIx
============================
.. toctree::
:maxdepth: 1
quickstart
definitions
filesystem-requirements
vpath-builds
compilers-and-flags
required-support-libraries
configure-cli-options/index
configure-output-summary
make-targets
installation-location
packagers

238
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/installation-location.rst.txt Normal file
View File

@@ -0,0 +1,238 @@
.. _building-pmix-installation-location-label:
Installation location
=====================
A common environment to run PMIx is in a "Beowulf"-class or
similar cluster (e.g., a bunch of 1U servers in a bunch of racks).
Simply stated, PMIx can run on a group of servers or workstations
connected by a network.
This raises the question for PMIx system administrators: where to
install the PMIx binaries, header files, etc.? This discussion
mainly addresses this question for homogeneous clusters (i.e., where
all nodes and operating systems are the same), although elements of
this discussion apply to heterogeneous clusters as well.
.. important:: For simplicity, the PMIx team *strongly* recommends
that you install PMIx at the same path location on all nodes in
your cluster. This *greatly* simplifies the user experience of
running jobs across multiple nodes in your cluster.
It is *possible* to install PMIx in unique path locations in
the different nodes in your cluster, but it is not *advisable*.
Filesystem types
----------------
There are two common approaches.
Network filesystem
^^^^^^^^^^^^^^^^^^
Have a common filesystem, such as NFS, between all the machines to be
used. Install PMIx such that the installation directory is the
*same value* on each node. This will *greatly* simplify user's shell
startup scripts (e.g., ``.bashrc``, ``.cshrc``, ``.profile`` etc.)
|mdash| the ``PATH`` can be set without checking which machine the
user is on. It also simplifies the system administrator's job; when
the time comes to patch or otherwise upgrade PMIx, only one copy
needs to be modified.
For example, consider a cluster of four machines: ``inky``,
``blinky``, ``pinky``, and ``clyde``.
* Install PMIx on ``inky``'s local hard drive in the directory
``/opt/pmix-VERSION``. The system administrator then mounts
``inky:/opt/pmix-VERSION`` on the remaining three machines, such
that ``/opt/pmix-VERSION`` on all machines is effectively "the
same". That is, the following directories all contain the PMIx
installation:
.. code-block::
inky:/opt/pmix-VERSION
blinky:/opt/pmix-VERSION
pinky:/opt/pmix-VERSION
clyde:/opt/pmix-VERSION
* Install PMIx on ``inky``'s local hard drive in the directory
``/usr/local/pmix-VERSION``. The system administrator then
mounts ``inky:/usr/local/pmix-VERSION`` on *all four* machines in
some other common location, such as ``/opt/pmix-VERSION`` (a
symbolic link can be installed on ``inky`` instead of a mount point
for efficiency). This strategy is typically used for environments
where one tree is NFS exported, but another tree is typically used
for the location of actual installation. For example, the following
directories all contain the PMIx installation:
.. code-block::
inky:/opt/pmix-VERSION
blinky:/opt/pmix-VERSION
pinky:/opt/pmix-VERSION
clyde:/opt/pmix-VERSION
Notice that there are the same four directories as the previous
example, but on ``inky``, the directory is *actually* located in
``/usr/local/pmix-VERSION``.
There is a bit of a disadvantage in this approach; each of the remote
nodes have to incur NFS (or whatever filesystem is used) delays to
access the PMIx directory tree. However, both the administration
ease and low cost (relatively speaking) of using a networked file
system usually greatly outweighs the cost.
Local filesystem
^^^^^^^^^^^^^^^^
If you are concerned with networked filesystem costs of accessing the
PMIx binaries, you can install PMIx on the local hard drive of
each node in your system. Again, it is *highly* advisable to install
PMIx in the *same* directory on each node so that each user's
``PATH`` can be set to the same value, regardless of the node that a
user has logged on to.
This approach will save some network latency of accessing the PMIx
binaries, but is typically only used where users are very concerned
about squeezing every single cycle out of their machines, or are
running at extreme scale where a networked filesystem may get
overwhelmed by filesystem requests for PMIx binaries when running
very large parallel jobs.
.. _building-pmix-install-overwrite-label:
Installing over a prior PMIx installation
-----------------------------------------
.. warning:: The PMIx team does not recommend installing a new
version of PMIx over an existing / older installation of PMIx.
In its default configuration, an PMIx installation consists of
several shared libraries, header files, executables, and plugins
(dynamic shared objects |mdash| DSOs). These installation files act
together as a single entity. The specific filenames and
contents of these files are subject to change between different
versions of PMIx.
.. important:: Installing one version of PMIx does *not* uninstall
another version.
If you install a new version of PMIx over an older version, this
may not overwrite all the files from the older version. Hence, you
may end up with an incompatible muddle of files from two different
installations |mdash| which can cause problems.
The PMIx team recommends one of the following methods for
upgrading your PMIx installation:
* Install newer versions of PMIx into a different directory. For
example, install into ``/opt/pmix-a.b.c`` and
``/opt/pmix-x.y.z`` for versions a.b.c and x.y.z, respectively.
* Completely uninstall the old version of PMIx before installing
the new version. The ``make uninstall`` process from PMIx a.b.c
build tree should completely uninstall that version from the
installation tree, making it safe to install a new version (e.g.,
version x.y.z) into the same installation tree.
* Remove the old installation directory entirely and then install the
new version. For example ``rm -rf /opt/pmix`` *(assuming that
there is nothing else of value in this tree!)* The installation of
PMIx x.y.z will safely re-create the ``/opt/pmix`` tree.
This method is preferable if you no longer have the source and build
trees to PMIx a.b.c available from which to ``make
uninstall``.
* Go into the PMIx a.b.c installation directory and manually
remove all old PMIx files. Then install PMIx x.y.z into the
same installation directory. This can be a somewhat painful,
annoying, and error-prone process. *We do not recommend it.*
Indeed, if you no longer have access to the original PMIx a.b.c
source and build trees, it may be far simpler to download PMIx
version a.b.c again from the PMIx web site, configure it with
the same installation prefix, and then run ``make uninstall``. Or
use one of the other methods, above.
Relocating an PMIx installation
-------------------------------
It can be desirable to initially install PMIx to one location
(e.g., ``/path/to/pmix``) and then later move it to another
location (e.g., ``/opt/myproduct/bundled-pmix-a.b.c``).
.. note:: PMIx hard-codes some directory paths in its executables
based on installation paths specified by the ``configure``
script. For example, if you configure with an installation
prefix of ``/opt/pmix/``, PMIx encodes in its
executables that it should be able to find its help files in
``/opt/pmix/share/pmix``.
The "installdirs" functionality in PMIx lets you change any of
these hard-coded directory paths at run time (*assuming* that you have
already adjusted your ``PATH`` and/or ``LD_LIBRARY_PATH`` environment
variables to the new location where PMIx now resides).
There are three methods.
Move an existing PMIx installation to a new prefix
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Set the ``PMIX_PREFIX`` environment variable before launching a
PMIx-based application. For example, if PMIx had initially been installed to
``/opt/pmix`` and the entire ``pmix`` tree was later moved to
``/home/pmix``, setting ``PMIX_PREFIX`` to ``/home/pmix`` will
enable PMIx to function properly.
"Stage" an PMIx installation in a temporary location
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When *creating* self-contained installation packages, systems such as
RPM install PMIx into temporary locations. The package system
then bundles up everything under the temporary location into a package
that can be installed into its real location later. For example, when
*creating* an RPM that will be installed to ``/opt/pmix``, the RPM
system will transparently prepend a "destination directory" (or
"destdir") to the installation directory. As such, PMIx will
think that it is installed in ``/opt/pmix``, but it is actually
temporarily installed in (for example)
``/var/rpm/build.1234/opt/pmix``. If it is necessary to *use* PMIx
while it is installed in this staging area, the ``PMIX_DESTDIR``
environment variable can be used; setting ``PMIX_DESTDIR`` to
``/var/rpm/build.1234`` will automatically prefix every directory such
that PMIx can function properly.
Overriding individual directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PMIx uses the GNU-specified directories (per Autoconf/Automake),
and can be overridden by setting environment variables directly
related to their common names. The list of environment variables that
can be used is:
* ``PMIX_PREFIX``
* ``PMIX_EXEC_PREFIX``
* ``PMIX_BINDIR``
* ``PMIX_SBINDIR``
* ``PMIX_LIBEXECDIR``
* ``PMIX_DATAROOTDIR``
* ``PMIX_DATADIR``
* ``PMIX_SYSCONFDIR``
* ``PMIX_SHAREDSTATEDIR``
* ``PMIX_LOCALSTATEDIR``
* ``PMIX_LIBDIR``
* ``PMIX_INCLUDEDIR``
* ``PMIX_INFODIR``
* ``PMIX_MANDIR``
* ``PMIX_PKGDATADIR``
* ``PMIX_PKGLIBDIR``
* ``PMIX_PKGINCLUDEDIR``
Note that not all of the directories listed above are used by PMIx;
they are listed here in entirety for completeness.
Also note that several directories listed above are defined in terms
of other directories. For example, the ``$bindir`` is defined by
default as ``$prefix/bin``. Hence, overriding the ``$prefix`` (via
``PMIX_PREFIX``) will automatically change the first part of the
``$bindir`` (which is how method 1 described above works).
Alternatively, ``PMIX_BINDIR`` can be set to an absolute value that
ignores ``$prefix`` altogether.

13
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/make-targets.rst.txt Normal file
View File

@@ -0,0 +1,13 @@
``make`` targets
================
PMIx supports all the ``make`` targets that are provided by GNU
Automake, such as:
* ``all``: build the entire PMIx package
* ``install``: install PMIx
* ``uninstall``: remove all traces of PMIx from the installation tree
* ``clean``: clean out the build tree
Once PMIx has been built and installed, it is safe to run ``make
clean`` and/or remove the entire build tree.

75
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/packagers.rst.txt Normal file
View File

@@ -0,0 +1,75 @@
Advice for packagers
====================
.. _label-install-packagers-dso-or-not:
Components ("plugins"): DSO or no?
----------------------------------
PMIx contains a large number of components (sometimes called
"plugins") to effect different types of functionality in PMIx. For
example, some components provide support for networks and
may link against specialized libraries to do so.
PMIx |opmix_ver| has two ``configure``-time defaults regarding the
treatment of components that may be of interest to packagers:
#. PMIx's libraries default to building as shared libraries
(vs. static libraries). For example, on Linux, PMIx will
default to building ``libpmix.so`` (vs. ``libpmix.a``).
.. note:: See the descriptions of ``--disable-shared`` and
``--enable-static`` :ref:`in this section
<label-building-installation-cli-options>` for more
details about how to change this default.
Also be sure to :ref:`see this warning about building
static apps <label-building-fully-static-apps>`.
#. PMIx will default to including its components in its libraries
(as opposed to being compiled as dynamic shared objects, or DSOs).
For example, ``libpmix.so`` on Linux systems will contain the OPA
PNET component, instead of the OPA PNET being compiled into
``mca_pnet_opa.so`` and dynamically opened at run time via
``dlopen(3)``.
.. note:: See the descriptions of ``--enable-mca-dso`` and
``--enable-mca-static`` :ref:`in this section
<label-building-installation-cli-options>` for more
details about how to change this defaults.
A side effect of these two defaults is that all the components
included in the PMIx libraries will bring their dependencies with
them. For example (on Linux), if the XYZ PNET component
requires ``libXYZ.so``, then these defaults mean that
``libpmix.so`` will depend on ``libXYZ.so``. This dependency will
likely be telegraphed into the PMIx binary package that includes
``libpmix.so``.
Conversely, if the XYZ PNET component was built as a DSO, then |mdash|
assuming no other parts of PMIx require ``libXYZ.so`` |mdash|
``libpmix.so`` would *not* be dependent on ``libXYZ.so``. Instead, the
``mca_pnet_xyz.so`` DSO would have the dependency upon ``libXYZ.so``.
Packagers can use these facts to potentially create multiple binary
PMIx packages, each with different dependencies by, for example,
using ``--enable-mca-dso`` to selectively build some components as
DSOs and leave the others included in their respective PMIx
libraries.
.. code:: sh
# Build all the "pnet" components as DSOs (all other
# components will default to being built in their respective
# libraries)
shell$ ./configure --enable-mca-dso=pnet ...
This allows packaging ``$libdir`` as part of the "main" PMIx
binary package, but then packaging
``$libdir/pmix/mca_pnet_*.so`` as sub-packages. These
sub-packages may inherit dependencies on their own.
Users can always install the "main" PMIx
binary package, and can install the additional "pnet" PMIx
binary sub-package if they actually have network hardware
installed (which will cause the installation of additional
dependencies).

208
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/quickstart.rst.txt Normal file
View File

@@ -0,0 +1,208 @@
.. _label-quickstart-building-pmix:
Installation
============
This file is a *very* short overview of building and installing the
PMIx library. Much more information is available in the `How-To
section on the PMIx web site <https://pmix.org/support/how-to/>`_.
Developer Builds
----------------
If you have checked out a DEVELOPER'S COPY of PMIx (i.e., you checked
out from Git), you should read the :doc:`Developer's Guide
</developers/index>` section before attempting to build PMIx. You
must then run:
.. code-block:: sh
shell$ git submodule update --init
shell$ ./autogen.pl
The ``submodule update`` is required as PMIx incorporates a submodule
to support its `autoconf` logic. You can, however, omit the explicit
submodule update step `if` you cloned the Git repository with the
``--recursive`` flag.
You will need very recent versions of GNU Autoconf, Automake, and
Libtool. If ``autogen.pl`` fails, read the :doc:`Developer's Guide
</developers/index>`. If anything else fails, read the
:doc:`Developer's Guide </developers/index>`. Finally, we suggest
reading the :doc:`Developer's Guide </developers/index>`.
.. note:: Developer's copies of OpenPMIx typically include a large
performance penalty at run-time because of extra debugging
overhead.
User Builds
-----------
Building PMIx is typically a combination of running ``configure``
and ``make``. Execute the following commands to install the PMIx
system from within the directory at the top of the tree:
.. code-block:: sh
shell$ ./configure --prefix=/where/to/install
[...lots of output...]
shell$ make all install
.. note:: This version of PMIx requires the following 3rd-party
packages to build and operate:
* either the `Libevent package
<https://libevent.org/>`_ (any version
of Libevent greater than or equal to 2.0.21 is acceptable) or
the `libev package <https://metacpan.org/dist/EV/view/libev/ev.pod>`_
(no minimum version has been identified).
* the `HWLOC package
<https://www.open-mpi.org/projects/hwloc/>`_ for providing
topology information to both the host environment (by
collecting local inventory for rollup) and local client
processes. Any version of HWLOC greater than 1.10 is
supported, although versions in the 2.x series are
recommended.
Note that you must point ``configure`` at these packages if they are
in a non-standard location - libevent using the ``--with-libevent=<dir>``
option; libev using the ``-with-libev=<dir>`` option, and HWLOC package
using the ``--with-hwloc=<dir>`` option. In all cases,
PMIx will automatically detect these packages in standard locations
and use them unless otherwise specified using the
respective configure option.
If you need special access to install, then you can execute ``make
all`` as a user with write permissions in the build tree, and a
separate ``make install`` as a user with write permissions to the
install tree.
Compiling support for specific compilers and environments may require
additional command line flags when running ``configure``. See the
:ref:`compiler flags <install-configure-compilers-and-flags-label>` entry
for more details.
Note that VPATH builds are fully supported. For example:
.. code-block:: sh
shell$ tar xf pmix-X.Y.Z.tar.gz
shell$ cd pmix-X.Y.Z
shell$ mkdir build
shell$ cd build
shell$ ../configure ...your options...
[...lots of output...]
shell$ make all install
Parallel builds are also supported (although some versions of ``make``,
such as GNU make, will only use the first target listed on the command
line when executable parallel builds). For example (assume GNU make):
.. code-block:: sh
shell$ make -j 4 all
[...lots of output...]
shell$ make install
Parallel make is generally only helpful in the build phase; the
installation process is mostly serial and does not benefit much from
parallel make.
``configure`` options
---------------------
There are many available options to ``configure`` (see ``./configure --help``
for a full list); a summary of the more commonly used ones follows:
* ``--prefix=<directory>``: Install PMIx into the base directory named
``<directory>``. Hence, PMIx will place its executables in
``<directory>/bin``, its header files in ``<directory>/include``,
its libraries in ``<directory>/lib``, etc.
* ``--disable-shared``: By default, ``libpmix`` is built as a shared
library. This switch disables this default; it is really only
useful when used with ``--enable-static``. Specifically, this
option does *not* imply ``--enable-static``; enabling static
libraries and disabling shared libraries are two independent
options.
* ``--enable-static``: Build ``libpmix`` as a static library. Note
that this option does *not* imply ``--disable-shared``; enabling
static libraries and disabling shared libraries are two independent
options. Please see the :ref:`Building Static Libraries
<label-install-static-libraries>` section below for important
details on building PMIx as a static library.
* ``--disable-show-load-errors-by-default``: Set the default value of
the ``mca_base_component_show_load_errors`` MCA variable: the
``--enable`` form of this option sets the MCA variable to true, the
``--disable`` form sets the MCA variable to false. The MCA
``mca_base_component_show_load_errors`` variable can still be
overridden at run time via the usual MCA-variable-setting
mechanisms; this configure option simply sets the default value.
The ``--disable`` form of this option is intended for OpenPMIx
packagers who tend to enable support for many different types of
networks and systems in their packages. For example, consider a
packager who includes support for both the FOO and BAR networks in
their PMIx package, both of which require support libraries
(``libFOO.so`` and ``libBAR.so``). If an end user only has BAR
hardware, they likely only have ``libBAR.so`` available on their
systems -- not ``libFOO.so``. Disabling load errors by default will
prevent the user from seeing potentially confusing warnings about
the FOO components failing to load because ``libFOO.so`` is not
available on their systems.
Conversely, system administrators tend to build an OpenPMIx that is
targeted at their specific environment, and contains few (if any)
components that are not needed. In such cases, they might want
their users to be warned that the FOO network components failed to
load (e.g., if ``libFOO.so`` was mistakenly unavailable), and thus
some PMIx calls might unexpectedly return "not supported".
* ``--with-platform=FILE``: Load configure options for the build from
``FILE``. Options on the command line that are not in ``FILE`` are
also used. Options on the command line and in ``FILE`` are replaced
by what is in ``FILE``.
* ``--enable-python-bindings``:
Build the Python bindings for PMIx. Note the following packages
are required to be installed:
.. code-block:: sh
shell$ yum install Cython python3 python3-devel
or...
shell$ pip3 install Cython
Once OpenPMIx has been built and installed, it is safe to run ``make
clean`` and/or remove the entire build tree.
VPATH and parallel builds are fully supported.
Generally speaking, the only thing that users need to do to use OpenPMIx
is ensure that ``<prefix>/lib`` is in their ``LD_LIBRARY_PATH``. Users may
need to ensure to set ``LD_LIBRARY_PATH`` in their shell setup files (e.g.,
``.bashrc``, ``.cshrc``) so that non-interactive SSH-based logins will
be able to find the OpenPMIx library.
.. _label-install-static-libraries:
Building Static Libraries
-------------------------
PMIx depends on a number of external libraries for critical
functionality. Some of these libraries, such as `HWLOC
<https://www.open-mpi.org/projects/hwloc/>`_, can have dependencies on
a varying number of additional libraries (such as libpci or libudev).
While PMIx's wrapper compiler will add the correct direct dependencies
for third party packages, it will frequently not pull in the right
sub-libraries. When linking against dyanamic library versions of
these dependencies, this is not a problem (and is preferred behavior
to avoid adding unnecessary indirect linking dependencies). However,
this does cause problems for building entirely static versions of
PMIx. It may be necessary in some circumstances to add these
dependencies via the ``LIBS`` environment variable (for building PMIx
binaries) or ``--with-wrapper-libs=LIBS`` for the wrapper compiler.

119
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/required-support-libraries.rst.txt Normal file
View File

@@ -0,0 +1,119 @@
.. _label-install-required-support-libraries:
Required support libraries
==========================
PMIx requires the following support libraries with the minimum listed versions:
.. list-table::
:header-rows: 1
:widths: 10 10 25
* - Library
- Minimum version
- Notes
* - `Hardware Locality <https://www.open-mpi.org/projects/hwloc/>`_
- |hwloc_min_version|
- This library is required; PMIx will not build without it.
* - `Libevent <https://libevent.org/>`_
- |event_min_version|
- Either libevent or libev must be provided
* - `libev <https://metacpan.org/dist/EV/view/libev/ev.pod>`_
- no specified minimum
- Either libevent or libev must be provided
These support libraries are fundamental to PMIx's operation
and pretty universally available in all environments. Worst case,
they can easily be built from their respective source tarballs.
Library dependencies
--------------------
These support libraries do not have dependencies upon each other.
However, it often is true that another library being used by an
application, or the application itself, can include a dependency
on one or more of them.
At run time, it is critical that the run-time linker loads *exactly
one copy* of each of these libraries. It is therefore vital that
you have a clear understanding of the dependencies within your
application.
Potential problems
------------------
Problems can (will) arise if multiple different copies of the above
shared libraries are loaded into a single process. For example,
consider if:
* Loading the PMIx shared library causes the loading of Libevent
shared library vA.B.C.
* But then the subsequent loading of the FOO shared library causes
the loading of Libevent shared library vX.Y.Z.
Since there are now two different versions of the Libevent shared
library loaded into the same process (yes, this can happen!),
unpredictable behavior can (will) occur.
Many variations on this same basic erroneous scenario are possible.
All of them are bad, and can be extremely difficult to diagnose.
Avoiding the problems
---------------------
A simple way to avoid these problems is to configure your system such
that it has exactly one copy of each of the required support libraries.
.. important:: If possible, use your OS / environment's package
manager to install as many of these support libraries |mdash|
including their development headers |mdash| as possible before
invoking PMIx's ``configure`` script.
Not all package managers provide all of the required support
libraries. But even if your package manager installs |mdash| for
example |mdash| only one of Libevent and Hwloc, that somewhat simplifies the
final PMIx configuration, and therefore avoids some potentially
erroneous configurations.
Overriding ``configure`` behavior
---------------------------------
PMIx's ``configure`` will (minus any configure flags) attempt to
find the HWLOC and libevent packages in standard locations. Note
that PMIx by default will look for libevent (and not libev), though
either can be used. If a required package is not found and no flags
were given, the ``configure`` operation will exit with a suitable
error message.
If ``configure``'s default searching behavior is not sufficient for
your environment, you can use :ref:`command line options to override
its default behavior
<label-building-pmix-cli-options-required-support-libraries>`.
For example, if libevent and/or HWLOC are installed such that the default
header file and linker search paths will not find them, you can
provide command line options telling PMIx's ``configure`` where to
search. Here's an example ``configure`` invocation where HWLOC
and libevent have both been installed under the ``/opt`` directory:
.. code-block:: sh
./configure --prefix=$HOME/pmix-install \
--with-libevent=/opt/libevent \
--with-hwloc=/opt/hwloc ...
.. danger:: Be very, very careful when overriding ``configure``'s
default search behavior for these libraries. Remember the critical
requirement: that PMIx infrastructure and applications load
*exactly one copy* of each support library. For simplicity, it may
be desirable to ensure to use exactly the support libraries that
PMIx was compiled and built against.
For example, using the PMIx installed from the sample
``configure`` line (above), you may want to prefix your run-time
linker search path (e.g., ``LD_LIBRARY_PATH`` on Linux) with
``$HOME/pmix-install/lib:/opt/libevent/lib:/opt/hwloc/lib``.
This will ensure that the linker finds
the support libraries used by your PMIx installation tree,
even if other copies of the same support libraries are present
elsewhere on your system.

16
macx64/mpi/openmpi/share/doc/pmix/html/_sources/installing-pmix/vpath-builds.rst.txt Normal file
View File

@@ -0,0 +1,16 @@
.. _building-pmix-vpath-label:
VPATH builds
============
VPATH build are fully supported. For example:
.. code-block:: sh
shell$ tar xf pmix-VERSION.tar.bz2
shell$ cd pmix-VERSION
shell$ mkdir build
shell$ cd build
shell$ ../configure [...options...]
<... lots of output ...>
shell$ make -j 4

5
macx64/mpi/openmpi/share/doc/pmix/html/_sources/license.rst.txt Normal file
View File

@@ -0,0 +1,5 @@
License
=========
.. literalinclude:: ../LICENSE
:language: text

22
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/index.rst.txt Normal file
View File

@@ -0,0 +1,22 @@
OpenPMIx manual pages
=====================
All of the content in this section is also installed as individual
manual ("man") pages in a OpenPMIx installation. If your man page search
path includes the location where OpenPMIx installed its man pages (which
defaults to ``$prefix/share/man``), you can invoke commands similar to
the following to see the same content that you see in these HTML
pages:
.. code:: sh
shell$ man PMIx_Abort
OpenPMIx man pages, by section:
.. toctree::
:maxdepth: 1
man1/index
man3/index
man5/index

14
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/index.rst.txt Normal file
View File

@@ -0,0 +1,14 @@
Commands (section 1)
====================
.. toctree::
:maxdepth: 1
pmix_info.1.rst
palloc.1.rst
pattrs.1.rst
pevent.1.rst
plookup.1.rst
pmixcc.1.rst
pps.1.rst
pquery.1.rst

125
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/palloc.1.rst.txt Normal file
View File

@@ -0,0 +1,125 @@
.. _man1-palloc:
palloc
=========
.. include_body
palloc |mdash| Request a resource allocation
SYNOPSIS
--------
``palloc [options]``
DESCRIPTION
-----------
``palloc`` allows a user to request an allocation of resources,
either as part of a job script or for an interactive session.
In addition to describing the requested resources, users can
provide a job script or application to be executed upon establishment
of the resulting session.
Note that ``palloc`` can also be used to *modify* an existing
allocation or allocation request - e.g., extending its time limit,
or changing the allocated resources.
OPTIONS
-------
``palloc`` accepts the following options:
* ``-h`` | ``--help <arg0>``: Show help message. If the optional
argument is not provided, then a generalized help message similar
to the information provided here is returned. If an argument is
provided, then a more detailed help message for that specific
command line option is returned.
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``--uri <arg0>``: Specify the URI of the server to which we are to connect, or
the name of the file (specified as ``file:filename``) that contains that info
* ``--namespace <arg0>``: Namespace of the daemon to which we should connect
* ``--nspace <arg0>``: Synonym for ``namespace``
* ``--pid <arg0>``: PID of the daemon to which we should connect (``int`` => ``PID``
or ``file:<file>`` for file containing the PID
* ``--system-server-first``: First look for a system server and connect to it if found
* ``--system-server-only``: Connect only to a system-level server
* ``--system-controller``: Connect to the system controller
* ``--tmpdir <arg0>``: Set the root for the session directory tree
* ``--connect-order <arg0>``: Specify search order for server connections - e.g., scheduler, system controller, system-level server, or local server
* ``--wait-to-connect <arg0>``: Delay specified number of seconds before trying to connect
* ``--num-connect-retries <arg0>``: Max number of times to try to connect
* ``--request-id <arg0>``: String identifier for this allocation request
* ``-q`` | ``--queue <arg0>``: Scheduler queue this request should be passed to for processing
* ``-N`` | ``--nodes <arg0>``: Number of nodes to be allocated
* ``-i`` | ``--image <arg0>``: OS image to be provisioned on allocated nodes prior to initiating execution of specified job, or turning nodes over to an interactive session
* ``-x`` | ``--exclude <arg0>``: Comma-delimited list of nodes that are to be excluded from consideration for scheduling this allocation
* ``--wait-all-nodes``: Wait for all nodes to be ready before starting execution of the specified job.
* ``-w`` | ``--nodelist <arg0>``: Comma-delimited list of ranges of specific nodes being requested [e.g., host0[1-5],host128]. Can also pass the argument as a filename using the "file:<path>" syntax. Ordering of names and/or duplicate names are ignored.
* ``--uid <arg0>``: Assign the resulting allocation to the specified user ID
* ``--gid <arg0>``: Assign the resulting allocation to the specified group ID
* ``-t`` | ``--time <arg0>``: Time limit on the assigned allocation.
* ``--signal <arg0>[@arg1]``: Send all processes executing within the allocated session the specified signal when it reaches the (optional) specified seconds of its end time.
* ``-s`` | ``--share``: Allocated resources can be shared with other allocations.
* ``--extend <arg0>``:Extend the specified existing session ID per the rest of the given request.
* ``--shrink <arg0>``: Shrink the specified existing session ID per the rest of the given request.
* ``--no-shell``: Immediately exit after allocating resources, without running a command.
* ``--begin <arg0>``: Direct the scheduler to defer allocation until the specified time.
* ``-I``| ``--immediate <arg0>``: Exit if resources are not available within the time period specified.
* ``-d`` | ``--dependency <arg0>``: Defer the start of this session until the specified dependencies have successfully completed.
* ``--do-not-wait``: Submit the allocation request to the scheduler, but do not wait for the allocation to be assigned. Intended for use when submitting a job for batch execution.
EXIT STATUS
-----------
Returns 0 for success, non-zero error code if a problem occurred. Note that success does not necessarily translate to success of the requested operation, depending upon provided options, but may instead mean that the request has been accepted for processing.
The command outputs the integer session ID of the resulting allocation, or if executed with the ``--do-not-wait`` option, a message indicating
if the request has been accepted for processing. Any command line arguments following the provided
options are taken as the job script or executable to be run within the allocation (once assigned) and its attendant
argv array. In this case, the allocation will terminate once the provide job script or executable completes.
EXAMPLES
--------
Examples of using this command.
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

87
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/pattrs.1.rst.txt Normal file
View File

@@ -0,0 +1,87 @@
.. _man1-pattrs:
pattrs
=========
.. include_body
pattrs |mdash| Display information about supported attributes
SYNOPSIS
--------
``pattrs [options]``
DESCRIPTION
-----------
``pattrs`` provides information on the attributes supported by the
client, server, and tool interfaces of the PMIx library being used.
OPTIONS
-------
``pattrs`` accepts the following options:
* ``-h`` | ``--help <arg0>``: Show help message. If the optional
argument is not provided, then a generalized help message similar
to the information provided here is returned. If an argument is
provided, then a more detailed help message for that specific
command line option is returned.
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``--pmixmca <arg0> <arg1>``: Set MCA parameter value
* ``--do-not-connect``: Do not connect to a server
* ``--uri <arg0>``: Specify the URI of the server to which we are to connect, or the name of the file (specified as file:filename) that contains that info
* ``--namespace <arg0>``: Namespace of the daemon to which we should connect
* ``--pid <arg0>``: PID of the daemon to which we should connect (int => PID or file:<file> for file containing the PID
* ``--system-server-first``: First look for a system server and connect to it if found
* ``--system-server``: Connect to a system-level server
* ``--tmpdir <arg0>``: Set the root for the session directory tree
* ``--wait-to-connect <arg0>``: Delay specified number of seconds before trying to connect
* ``--num-connect-retries <arg0>``: Max number of times to try to connect
* ``--client <arg0>``: Comma-delimited list of client functions whose attributes are to be printed (function or "all")
* ``--server <arg0>``: Comma-delimited list of server functions whose attributes are to be printed (function or "all")
* ``--tool <arg0>``: Comma-delimited list of tool functions whose attributes are to be printed (function or "all")
* ``--host <arg0>``: Comma-delimited list of host functions whose attributes are to be printed (function or "all")
* ``--client-fns``: List the functions supported in this client library
* ``--server-fns``: List the functions supported in this server library
* ``--tool-fns``: List the functions supported in this tool library
* ``--host-fns``: List the functions supported by this host environment
EXIT STATUS
-----------
Returns 0 for successful completion or a non-zero error code. The command outputs the requested information to stdout.
EXAMPLES
--------
Examples of using this command.
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

59
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/pevent.1.rst.txt Normal file
View File

@@ -0,0 +1,59 @@
.. _man1-pevent:
pevent
=========
.. include_body
pevent |mdash| inject specified event into the system
SYNOPSIS
--------
``pevent [options] <EVENT>``
DESCRIPTION
-----------
``pevent`` requests that the specified event be passed to
processes in the given range.
OPTIONS
-------
``pevent`` accepts the following options:
* ``-h`` | ``--help <arg0>``: Show help message. If the optional
argument is not provided, then a generalized help message similar
to the information provided here is returned. If an argument is
provided, then a more detailed help message for that specific
command line option is returned.
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``--pmixmca <arg0> <arg1>``: Set MCA parameter value
* ``--pid <arg0>``: PID of the daemon to which we should connect (int => PID or file:<file> for file containing the PID
* ``--tmpdir <arg0>``: Set the root for the session directory tree
* ``--range <arg0>``: Range of event to be sent. If not provided, the request will default to the ``PMIX_GLOBAL`` range
EXIT STATUS
-----------
Returns 0 if the event was successfully sent, a non-zero error code if otherwise.
EXAMPLES
--------
Examples of using this command.
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

62
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/plookup.1.rst.txt Normal file
View File

@@ -0,0 +1,62 @@
.. _man1-plookup:
plookup
=========
.. include_body
plookup |mdash| lookup the value of keys posted using the ``PMIx_Publish`` API
SYNOPSIS
--------
``plookup [options] <KEY1>,<KEY2>,...``
DESCRIPTION
-----------
``plookup`` performs a ``PMIx_Lookup`` for each of the provided
keys and returns the results
OPTIONS
-------
``plookup`` accepts the following options:
* ``-h`` | ``--help <arg0>``: Show help message. If the optional
argument is not provided, then a generalized help message similar
to the information provided here is returned. If an argument is
provided, then a more detailed help message for that specific
command line option is returned.
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``--pmixmca <arg0> <arg1>``: Set MCA parameter value
* ``--pid <arg0>``: PID of the daemon to which we should connect (int => PID or file:<file> for file containing the PID
* ``--tmpdir <arg0>``: Set the root for the session directory tree
* ``--timeout <arg0>``: Max number of seconds to wait for data to become available
* ``--wait``: Wait for data to become available if not immediately present
EXIT STATUS
-----------
Returns 0 upon success, or else a non-zero error code. Prints any returned values to stdout.
EXAMPLES
--------
Examples of using this command.
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

133
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/pmix_info.1.rst.txt Normal file
View File

@@ -0,0 +1,133 @@
.. _man1-pmix_info:
pmix_info
=========
.. include_body
pmix_info |mdash| Display information about the PMIx installation
SYNOPSIS
--------
``pmix_info [options]``
DESCRIPTION
-----------
``pmix_info`` provides detailed information about the PMIx
installation. It can be useful for at least three common scenarios:
#. Checking local configuration and seeing how PMIx was installed.
#. Submitting bug reports / help requests to the PMIx community
(see :doc:`Getting help </getting-help>`).
#. Seeing a list of installed PMIx plugins and querying what MCA
parameters they support.
OPTIONS
-------
``pmix_info`` accepts the following options:
* ``-h`` | ``--help <arg0>``: Show help message. If the optional
argument is not provided, then a generalized help message similar
to the information provided here is returned. If an argument is
provided, then a more detailed help message for that specific
command line option is returned.
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``-a`` | ``--all``: Show all configuration options and MCA
parameters.
* ``--arch``: Show architecture on which PMIx was compiled.
* ``-c`` | ``--config``: Show configuration options
* ``--hostname``: Show the hostname on which PMIx was configured
and built.
* ``--internal``: Show internal MCA parameters (not meant to be
modified by users).
* ``--param <arg0>:<arg1>,<arg2>``: Show MCA parameters. The first
parameter is the framework (or the keyword "all"); the second parameter
is a comma-delimited list of specific component names (if only <arg0>
is given, then all components will be reported).
* ``--path <type>``: Show paths that PMIx was configured
with. Accepts the following parameters: ``prefix``, ``bindir``,
``libdir``, ``incdir``, ``pkglibdir``, ``sysconfdir``.
* ``--pretty-print``: When used in conjunction with other parameters, the output is
displayed in "prettyprint" format (default)
* ``--parsable``: When used in conjunction with other parameters, the output is
displayed in a machine-parsable format
* ``--parseable``: Synonym for ``--parsable``
* ``--show-failed``: Show the components that failed to load along with the reason why they failed
* ``--selected-only``: Show only variables from selected components.
EXIT STATUS
-----------
Returns 0 if successful, non-zero if an error is encountered
EXAMPLES
--------
Examples of using this command.
Show the default output of options and listing of installed
components in a human-readable / prettyprint format:
.. code-block::
pmix_info
Show the default output of options and listing of installed components
in a machine-parsable format:
.. code-block::
pmix_info --parsable
Show the MCA parameters of the "opa" PNET component in a
human-readable / prettyprint format:
.. code-block::
pmix_info --param pnet opa
Show the "bindir" that PMIx was configured with:
.. code-block::
pmix_info --path bindir
Show the version of PMIx version numbers in a prettyprint format:
.. code-block::
pmix_info --version
Show *all* information about the PMIx installation, including all
components that can be found, all the MCA parameters that they support,
versions of PMIx and the components, etc.:
.. code-block::
pmix_info --all
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

132
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/pmixcc.1.rst.txt Normal file
View File

@@ -0,0 +1,132 @@
.. _man1-pmixcc:
pmixcc
=========
.. include_body
pmixcc |mdash| wrapper compiler for PMIx-based applications or tools
SYNOPSIS
--------
``pmixcc [options] <file>``
DESCRIPTION
-----------
``pmixcc`` is a wrapper compiler that can be used to build PMIx-based
applications or tools.
OPTIONS
-------
``pmixcc`` accepts the following options:
* ``-h`` | ``--help``: Show help message
* ``--help={common|optimizers|params|target|warnings|[^]{joined|separate|undocumented}}[,...].``: Display specific types of command line options
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``-dumpspecs``: Display all of the built in spec strings.
* ``-dumpversion``: Display the version of the compiler.
* ``-dumpmachine``: Display the compiler's target processor.
* ``-foffload=<targets>``: Specify offloading targets.
* ``-print-search-dirs``: Display the directories in the compiler's search path.
* ``-print-libgcc-file-name``: Display the name of the compiler's companion library.
* ``-print-file-name=<lib>``: Display the full path to library <lib>.
* ``-print-prog-name=<prog>``: Display the full path to compiler component <prog>.
* ``-print-multiarch``: Display the target's normalized GNU triplet, used as a component in the library path.
* ``-print-multi-directory``: Display the root directory for versions of libgcc.
* ``-print-multi-lib``: Display the mapping between command line options and multiple library search directories.
* ``-print-multi-os-directory``: Display the relative path to OS libraries.
* ``-print-sysroot``: Display the target libraries directory.
* ``-print-sysroot-headers-suffix``: Display the sysroot suffix used to find headers.
* ``-Wa,<options>``: Pass comma-separated <options> on to the assembler.
* ``-Wp,<options>``: Pass comma-separated <options> on to the preprocessor.
* ``-Wl,<options>``: Pass comma-separated <options> on to the linker.
* ``-Xassembler <arg>``: Pass <arg> on to the assembler.
* ``-Xpreprocessor <arg>``: Pass <arg> on to the preprocessor.
* ``-Xlinker <arg>``: Pass <arg> on to the linker.
* ``-save-temps``: Do not delete intermediate files.
* ``-save-temps=<arg>``: Do not delete intermediate files.
* ``-no-canonical-prefixes``: Do not canonicalize paths when building relative prefixes to other gcc components.
* ``-pipe``: Use pipes rather than intermediate files.
* ``-time``: Time the execution of each subprocess.
* ``-specs=<file>``: Override built-in specs with the contents of <file>.
* ``-std=<standard>``: Assume that the input sources are for <standard>.
* ``--sysroot=<directory>``: Use <directory> as the root directory for headers and libraries.
* ``-B <directory>``: Add <directory> to the compiler's search paths.
* ``-v``: Display the programs invoked by the compiler.
* ``-###``: Like -v but options quoted and commands not executed.
* ``-E``: Preprocess only; do not compile, assemble or link.
* ``-S``: Compile only; do not assemble or link.
* ``-c``: Compile and assemble, but do not link.
* ``-o <file>``: Place the output into <file>.
* ``-pie``: Create a dynamically linked position independent executable.
* ``-shared``: Create a shared library.
* ``-x <language>``: Specify the language of the following input files.
Permissible languages include: c c++ assembler none
'none' means revert to the default behavior of
guessing the language based on the file's extension.
Options starting with ``-g``, ``-f``, ``-m``, ``-O``, ``-W``, or ``--param`` are automatically
passed on to the various sub-processes invoked by the compiler. In order to pass
other options on to these processes the ``-W<letter>`` options must be used.
EXIT STATUS
-----------
Returns 0 if build is successful, a non-zero error code if otherwise.
EXAMPLES
--------
Examples of using this command.
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

71
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/pps.1.rst.txt Normal file
View File

@@ -0,0 +1,71 @@
.. _man1-pps:
pps
=========
.. include_body
pps |mdash| report identity of jobs running
in the system
SYNOPSIS
--------
``pps [options]``
DESCRIPTION
-----------
``pps`` provides the namespace of jobs currently executing
in the system.
OPTIONS
-------
``pps`` accepts the following options:
* ``-h`` | ``--help <arg0>``: Show help message. If the optional
argument is not provided, then a generalized help message similar
to the information provided here is returned. If an argument is
provided, then a more detailed help message for that specific
command line option is returned.
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``--uri <arg0>``: Specify the URI of the server to which we are to connect, or the name of the file (specified as file:filename) that contains that info
* ``--namespace <arg0>``: Namespace of the daemon to which we should connect
* ``--pid <arg0>``: PID of the daemon to which we should connect (int => PID or file:<file> for file containing the PID
* ``--system-server-first``: First look for a system server and connect to it if found
* ``--system-server``: Connect to a system-level server
* ``--tmpdir <arg0>``: Set the root for the session directory tree
* ``--wait-to-connect <arg0>``: Delay specified number of seconds before trying to connect
* ``--num-connect-retries <arg0>``: Max number of times to try to connect
* ``--nodes``: Display Node Information
EXIT STATUS
-----------
Returns 0 for success, a non-zero error code otherwise.
EXAMPLES
--------
Examples of using this command.
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

80
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man1/pquery.1.rst.txt Normal file
View File

@@ -0,0 +1,80 @@
.. _man1-pquery:
pquery
=========
.. include_body
pquery |mdash| query information from the host environment
SYNOPSIS
--------
``pquery [options] <KEY1>,<KEY2>,...``
DESCRIPTION
-----------
``pquery`` requests the host environment for values associated
with the provided keys
OPTIONS
-------
``pquery`` accepts the following options:
* ``-h`` | ``--help <arg0>``: Show help message. If the optional
argument is not provided, then a generalized help message similar
to the information provided here is returned. If an argument is
provided, then a more detailed help message for that specific
command line option is returned.
* ``-v`` | ``--verbose``: Enable debug output.
* ``-V`` | ``--version``: Print version and exit.
* ``--pmixmca <arg0> <arg1>``: Set MCA parameter value
* ``--uri <arg0>``: Specify the URI of the server to which we are to connect, or
the name of the file (specified as file:filename) that contains that info
* ``--namespace <arg0>``: Namespace of the daemon to which we should connect
* ``--pid <arg0>``: PID of the daemon to which we should connect (int => PID or file:<file>
for file containing the PID
* ``--system-server-first``: First look for a system server and connect to it if found
* ``--system-server``: Connect to a system-level server
* ``--tmpdir <arg0>``: Set the root for the session directory tree
* ``--wait-to-connect <arg0>``: Delay specified number of seconds before trying to connect
* ``--num-connect-retries <arg0>``: Max number of times to try to connect
Keys passed to pquery may optionally include one or more qualifiers, with the
individual qualifiers delimited by semi-colons. For example:
.. code::
$ pquery "PMIX_STORAGE_XFER_SIZE[PMIX_STORAGE_ID=lustre1,lustre2;PMIX_STORAGE_PATH=foo]""
EXIT STATUS
-----------
Returns 0 for success, or a non-zero value otherwise. Values returned by the query
are printed to stdout.
EXAMPLES
--------
Examples of using this command.
.. seealso::
:ref:`openpmix(5) <man5-openpmix>`

79
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man3/PMIx_Abort.3.rst.txt Normal file
View File

@@ -0,0 +1,79 @@
.. _man3-PMIx_Abort:
PMIx_Abort
==========
PMIx_Abort - Abort the specified processes
SYNOPSIS
--------
.. code-block:: c
#include <pmix.h>
pmix_status_t PMIx_Abort(int status, const char msg[],
pmix_proc_t procs[], size_t nprocs);
ARGUMENTS
---------
* ``status``: Status value to be returned. A value of zero is
permitted by PMIx, but may not be returned by some resource
managers.
* ``msg``: A string message to be displayed.
* ``procs``: An array of ``pmix_proc_t`` structures defining the
processes to be aborted. A NULL for the proc array indicates that
all processes in the caller's namespace are to be aborted. A
wildcard value for the rank in any structure indicates that all
processes in that namespace are to be aborted.
* ``nprocs``: Number of ``pmix_proc_t`` structures in the ``procs``
array.
DESCRIPTION
-----------
Request that the provided array of procs be aborted, returning the
provided status and printing the provided message. A NULL for the
``procs`` array indicates that all processes in the caller's namespace
are to be aborted.
The response to this request is somewhat dependent on the specific
resource manager and its configuration (e.g., some resource managers
will not abort the application if the provided status is zero unless
specifically configured to do so), and thus lies outside the control
of PMIx itself. However, the client will inform the RM of the request
that the application be aborted, regardless of the value of the
provided status.
Passing a NULL ``msg`` parameter is allowed. Note that race conditions
caused by multiple processes calling ``PMIx_Abort`` are left to the server
implementation to resolve with regard to which status is returned and
what messages (if any) are printed.
RETURN VALUE
------------
Returns ``PMIX_SUCCESS`` on success. On error, a negative value
corresponding to a PMIx ``errno`` is returned.
ERRORS
------
PMIx errno values are defined in ``pmix_common.h``.
.. JMS COMMENT When more man pages are added, they can be :ref:'ed
appropriately, so that HTML hyperlinks are created to link to the
corresponding pages.
.. seealso::
PMIx_Commit(3),
:ref:`PMIx_Finalize(3) <man3-PMIx_Finalize>`,
:ref:`PMIx_Init(3) <man3-PMIx_Init>`,
PMIx_Initialized(3),
PMIx_Put(3),
pmiAddInstance(3),
pmiAddMetric(3)

41
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man3/PMIx_Finalize.3.rst.txt Normal file
View File

@@ -0,0 +1,41 @@
.. _man3-PMIx_Finalize:
PMIx_Finalize
=============
PMIx_Finalize - Finalize the PMIx Client
SYNOPSIS
--------
.. code-block:: c
#include <pmix.h>
pmix_status_t PMIx_Finalize(void);
DESCRIPTION
-----------
Finalize the PMIx client, closing the connection with the local PMIx
server.
RETURN VALUE
------------
Returns ``PMIX_SUCCESS`` on success. On error, a negative value
corresponding to a PMIx ``errno`` is returned.
ERRORS
------
PMIx ``errno`` values are defined in ``pmix_common.h``.
.. seealso::
:ref:`PMIx_Abort(3) <man3-PMIx_Abort>`,
PMIx_Commit(3),
:ref:`PMIx_Init(3) <man3-PMIx_Init>`,
PMIx_Initialized(3),
PMIx_Put(3),
pmiAddInstance(3),
pmiAddMetric(3)

68
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man3/PMIx_Init.3.rst.txt Normal file
View File

@@ -0,0 +1,68 @@
.. _man3-PMIx_Init:
PMIx_Init
=========
PMIx_Init - Initialize the PMIx Client
SYNOPSIS
--------
.. code-block:: c
#include <pmix.h>
pmix_status_t PMIx_Init(pmix_proc_t *proc);
ARGUMENTS
---------
* ``proc``: Pointer to a ``pmix_proc_t`` object in which the client's
namespace and rank are to be returned.
DESCRIPTION
-----------
Initialize the PMIx client, returning the process identifier assigned
to this client's application in the provided ``pmix_proc_t``
struct. Passing a parameter of NULL for this parameter is allowed if
the user wishes solely to initialize the PMIx system and does not
require return of the identifier at that time.
When called, the PMIx client will check for the required connection
information of the local PMIx server and will establish the
connection. If the information is not found, or the server connection
fails, then an appropriate error constant will be returned.
If successful, the function will return ``PMIX_SUCCESS`` and will fill
the provided structure with the server-assigned namespace and rank of
the process within the application.
Note that the PMIx client library is referenced counted, and so
multiple calls to ``PMIx_Init`` are allowed. Thus, one way to obtain
the namespace and rank of the process is to simply call ``PMIx_Init``
with a non-NULL parameter.
RETURN VALUE
------------
Returns ``PMIX_SUCCESS`` on success. On error, a negative value
corresponding to a PMIx ``errno`` is returned.
ERRORS
------
PMIx ``errno`` values are defined in ``pmix_common.h``.
.. JMS COMMENT When more man pages are added, they can be :ref:'ed
appropriately, so that HTML hyperlinks are created to link to the
corresponding pages.
.. seealso::
PMIx_Initialized(3),
:ref:`PMIx_Abort(3) <man3-PMIx_Abort>`,
PMIx_Commit(3),
:ref:`PMIx_Finalize(3) <man3-PMIx_Finalize>`,
PMIx_Put(3),
pmiAddInstance(3),
pmiAddMetric(3)

14
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man3/index.rst.txt Normal file
View File

@@ -0,0 +1,14 @@
APIs (section 3)
================
.. admonition:: PMIx Docs TODO
:class: error
Need to supply all the rest of the man pages for section 3.
.. toctree::
:maxdepth: 1
PMIx_Abort.3.rst
PMIx_Init.3.rst
PMIx_Finalize.3.rst

7
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man5/index.rst.txt Normal file
View File

@@ -0,0 +1,7 @@
Config file manual pages (section 5)
====================================
.. toctree::
:maxdepth: 1
openpmix.5.rst

11
macx64/mpi/openmpi/share/doc/pmix/html/_sources/man/man5/openpmix.5.rst.txt Normal file
View File

@@ -0,0 +1,11 @@
.. _man5-openpmix:
OpenPMIx
========
Write more here.
.. admonition:: PMIx Docs TODO
:class: error
Need to write this man page.

339
macx64/mpi/openmpi/share/doc/pmix/html/_sources/mca.rst.txt Normal file
View File

@@ -0,0 +1,339 @@
.. _label-mca:
The Modular Component Architecture (MCA)
========================================
PMIx is a highly-customizable system; it can be configured via
configuration files, command line parameters, and environment
variables. The main functionality of PMIx's configuration system
is through the Modular Component Architecture (MCA).
* This section describes the MCA itself and how to set MCA parameters at
run time.
* Later sections in this documentation describe different parts of
PMIx's functionality, and the specific names and values of MCA
parameters that can be used to affect PMIx's behavior.
/////////////////////////////////////////////////////////////////////////
Terminology
-----------
The Modular Component Architecture (MCA) is the backbone for much of
PMIx's functionality. It is a series of *frameworks*,
*components*, and *modules* that are assembled at run-time to create
the PMIx implementation.
MCA *parameters* (also known as MCA *variables*) are used to customize
PMIx's behavior at run-time.
Each of these entities are described below.
Frameworks
^^^^^^^^^^
An MCA framework manages zero or more components at run-time and is
targeted at a specific task (e.g., providing support for network
functionality). Although each MCA framework supports only a single
type of component, it may support multiple components of that type.
Some of the more common frameworks that users may want or need to
customize include the following:
* ``ptl``: PMIx Transport Layer; users may need to assist the
messaging layer with selection of network interfaces and
controls parameters
* ``pmdl``: Programming Model and Library; identify environmental
variables to be forwarded to application processes
There are many frameworks within PMIx; the exact set varies
between different versions of PMIx. You can use the
:ref:`pmix_info(1) <man1-pmix_info>` command to see the full list of
frameworks that are included in PMIx |opmix_ver|.
Components
^^^^^^^^^^
An MCA component is an implementation of a framework's formal
interface. It is a standalone collection of code that can be bundled
into a plugin that can be inserted into the PMIx code base, either
at run-time and/or compile-time.
.. note:: Good synonyms for PMIx's "component" concept are
"plugin", or "add-on".
The exact set of components varies between different versions of Open
MPI. PMIx's code base includes support for many components, but
not all of them may be present or available on your system. You can
use the :ref:`pmix_info(1) <man1-pmix_info>` command to see what
components are included in PMIx |opmix_ver| on your system.
Modules
^^^^^^^
An MCA module (frequently called a ``plugin``) is an instance of a
component. While it is possible for a component to have multiple
active plugins, it would be a very rare component that did so.
Parameters (variables)
^^^^^^^^^^^^^^^^^^^^^^
MCA *parameters* (sometimes called MCA *variables*) are the basic unit
of run-time tuning for PMIx. They are simple "key = value" pairs
that are used extensively throughout PMIx. The general rules of
thumb that the developers use are:
#. Instead of using a constant for an important value, make it an MCA
parameter so users can adjust it if necessary.
#. If a task can be implemented in multiple, user-discernible ways,
implement as many as possible, and use an MCA parameter to
choose between them at run-time.
For example, the PMIx server sets a maximum value on the number of
events it will cache. Events received after that point cause the
oldest events in the cache to be released. This allows the server
to provide a process with events it registers to receive, even if
the registration occurs after the event has been received by the
server - thereby reducing the likelihood of a process missing an
event due to a race condition. Applications that generate a large
volume of events (e.g., an application relying on the PMIx Group
invite/join method for creating collections of processes) might
require a significantly larger cache than the default size.
/////////////////////////////////////////////////////////////////////////
.. _label-running-setting-mca-param-values:
Setting MCA parameter values
----------------------------
MCA parameters may be set in several different ways.
.. admonition:: Rationale
:class: tip
Having multiple methods to set MCA parameters allows, for example,
system administrators to fine-tune the PMIx installation for
their hardware / environment such that normal users can simply use
the default values (that were set by the system administrators).
HPC environments |mdash| and the applications that run on them
|mdash| tend to be unique. Providing extensive run-time tuning
capabilities through MCA parameters allows the customization of
PMIx to each system's / user's / application's particular
needs.
The following are the different methods to set MCA parameters, listed
in priority order:
#. Environment variables
#. Configuration files
Environment variables
^^^^^^^^^^^^^^^^^^^^^
Environment variables are given the highest priority. Any environment variable
named ``PMIX_MCA_<param_name>`` will be examined for use. Note that
misspelling of names will cause the value to be ignored - i.e.,
PMIx does not report unrecognized MCA parameters, it simply ignores
them.
.. note:: Just like with command line values, setting environment
variables to values with multiple words requires shell
quoting, such as:
.. code-block:: sh
shell$ export OMPI_MCA_param="value with multiple words"
Configuration files
^^^^^^^^^^^^^^^^^^^
Simple configuration text files can also be used to set MCA
parameter values. Parameters are set one per line (comments are
permitted). For example:
.. code-block:: ini
# This is a comment
# Set an MCA parameter
mca_component_show_load_errors = 1
Note that quotes are *not* necessary for setting multi-word values
in MCA parameter files. Indeed, if you use quotes in the MCA
parameter file, they will be used as part of the value itself. For
example:
.. code-block:: ini
# The following two values are different:
param1 = value with multiple words
param2 = "value with multiple words"
By default, two files are searched (in order):
#. ``$HOME/.pmix/mca-params.conf``: The user-supplied set of
values has the higher precedence.
#. ``$prefix/etc/pmix-mca-params.conf``: The system-supplied set
of values has a lower precedence.
More specifically, the MCA parameter ``mca_param_files`` specifies a
colon-delimited path of files to search for MCA parameters. Files to
the left have lower precedence; files to the right are higher
precedence.
.. note:: Keep in mind that, just like components, these parameter
files are *only* relevant where they are "visible". Typically,
these files are read by the host daemon responsible for
launching an application and then forwarded to all
daemons (and their child application processes) in their
environment.
.. warning:: Setting PMIx MCA parameters via configuration files
entails editing (by default) the following files:
``$HOME/.pmix/mca-params.conf`` or
``$prefix/etc/pmix-mca-params.conf``
/////////////////////////////////////////////////////////////////////////
.. _label-running-selecting-framework-components:
Selecting which PMIx components are used at run time
--------------------------------------------------------
Each MCA framework has a top-level MCA parameter that helps guide
which components are selected to be used at run-time. Specifically,
every framework has an MCA parameter of the same name that can be used
to *include* or *exclude* components from a given run.
For example, the ``pmdl`` MCA parameter can used to control which PMDL
components are used. It takes a comma-delimited list of component
names, and may be optionally prefixed with ``^``. For example:
.. note:: The Programming Model ``PMDL`` framework provides support
for a range of programming models and libraries, including collection
of default parameters and environmental variables for forwarding and
setting of library-specific environmental variables
.. code-block:: sh
# Tell PMIx to include *only* the PMDL components listed here and
# implicitly ignore all the rest:
export PMIX_MCA_pmdl=ompi,oshmem ...
# Tell PMIx to exclude the ompi and oshmem PMDL components
# and implicitly include all the rest
export PMIX_MCA_pmdl=^ompi,oshmem ...
Note that ``^`` can *only* be the prefix of the *entire*
comma-delimited list because the inclusive and exclusive behavior are
mutually exclusive. Specifically, since the exclusive behavior means
"use all components *except* these", it does not make sense to mix it
with the inclusive behavior of not specifying it (i.e., "use all of
these components"). Hence, something like this:
.. code-block:: sh
export PMIX_MCA_pmdl=ompi,^oshmem ...
does not make sense |mdash| and will cause an error |mdash| because it
says "use only the ``ompi`` component" but
also "use all components except ``oshmem``". These two statements
clearly contradict each other.
/////////////////////////////////////////////////////////////////////////
Common MCA parameters
---------------------
PMIx has a *large* number of MCA parameters available. Users can
use the :ref:`pmix_info(1) <man1-pmix_info>` command to see *all*
available MCA parameters.
The vast majority of these MCA parameters, however, are not useful to
most users. Although the full list of MCA parameters can be found in the output of
``pmix_info(1)``, the following list of commonly-used parameters is
presented here so that they can easily be found via internet searches:
* Individual framework names with the ``_base_verbose`` suffix
appended (e.g., ``ptl_base_verbose``, ``pmdl_base_verbose``, etc.)
can be used to set the general verbosity level of all the components
in that framework.
* This can be helpful when troubleshooting why certain components
are or are not being selected at run time.
* The PMIx Transport Layer supports "include" and "exclude"
types of components (e.g., ``ptl_tcp_if_include`` and
``ptl_tcp_if_exclude``). The "include" parameters specify an
explicit set of network interfaces to use; the "exclude" parameters
specify an explicit set of network interfaces to ignore. Check the
output from :ref:`pmix_info(1)'s <man1-pmix_info>` to see the full list
of PTL-related parameters.
.. important:: You can only use the "include" *or* the "exclude"
parameter |mdash| they are mutually exclusive from each
other.
* ``mca_base_component_show_load_errors``: By default, PMIx
emits a warning message if it fails to open a DSO component at run
time. This typically happens when a shared library that the DSO
requires is not available.
.. admonition:: Rationale
:class: tip
In prior versions of PMIx, components defaulted to building
as DSOs (vs. being included in the parent library,
``libpmix.so``). On misconfigured systems, sometimes libraries
required by various components would not be present, thereby causing
those components to fail to open at run time.
Having PMIx warn about such failures to load was useful
because it alerted users to the misconfiguration.
.. note:: By default, PMIx |opmix_ver| includes all components in
its base libraries (e.g., on Linux, ``libpmix.so`` includes
all the components that were built with PMIx, and
therefore no component need to be opened dynamically), and
does not build its components as DSOs.
This MCA parameter *only* affects the behavior when a
component DSO fails to open.
This MCA parameter can take four general values:
#. ``yes`` or a boolean "true" value (e.g., ``1``): PMIx will
emit a warning about every component DSO that fails to load.
#. ``no`` or a boolean "false" value (e.g., ``0``): PMIx will
never emit warnings about component DSOs that fail to load.
#. A comma-delimited list of frameworks and/or components: PMIx
will emit a warning about any dynamic component that fails to
open and matches a token in the list. "Match" is defined as:
* If a token in the list is only a framework name, then any
component in that framework will match.
* If a token in the list specifies both a framework name and a
component name (in the form ``framework/component``), then
only the specified component in the specified framework will
match.
For example, if the value of this MCA parameter is
``pmdl,pnet/opa``, then PMIx will warn if any component in
the PMDL framework or if the OPA PNET component fails to load at run
time.
#. The value can also be a ``^`` character followed by a
comma-delimited list of ``framework[/component]`` values: This
is similar to the comma-delimited list of tokens, except it will
only emit warnings about dynamic components that fail to load
and do *not* match a token in the list.
For example, if the value of this MCA parameter is
``^pmdl,pnet/opa``, then PMIx will only warn about the
failure to load DSOs that are neither in the PMDL
framework nor are the OPA PNET component.

44
macx64/mpi/openmpi/share/doc/pmix/html/_sources/news/index.rst.txt Normal file
View File

@@ -0,0 +1,44 @@
.. PMIx NEWS
This page serves as a high level NEWS page which includes NEWS
from various PMIx series
News
====
This file contains the main features as well as overviews of specific
bug fixes (and other actions) for each version of PMIx since
version 1.0.
As more fully described in the :ref:`Software Version Number section
<label-version-numbers>`,
PMIx typically releases two separate version
series simultaneously. Since these series have different goals and
are semi-independent of each other, a single NEWS-worthy item may be
introduced into different series at different times. For example,
feature F was introduced in the vA.B series at version vA.B.C, and was
later introduced into the vX.Y series at vX.Y.Z.
The first time feature F is released, the item will be listed in the
vA.B.C section, denoted as:
(** also to appear: X.Y.Z) -- indicating that this item is also
likely to be included in future release
version vX.Y.Z.
When vX.Y.Z is later released, the same NEWS-worthy item will also be
included in the vX.Y.Z section and be denoted as:
(** also appeared: A.B.C) -- indicating that this item was previously
included in release version vA.B.C.
:ref:`search`
.. toctree::
:maxdepth: 1
news-v5.x
news-v4.x
news-v3.x
news-v2.x
news-v1.x

138
macx64/mpi/openmpi/share/doc/pmix/html/_sources/news/news-v1.x.rst.txt Normal file
View File

@@ -0,0 +1,138 @@
PMIx v1.x series
====================
This file contains all the NEWS updates for all the PMIx v1.x
series, in reverse chronological order.
1.2.5 -- 6 Feb 2018
----------------------
- Fix cross-version issue when v1.2 client interacts with v2.1 server (PR #564)
- Update client connection for cross-version support (PR #591)
- Fix write memory barrier ASM for PowerPC (PR #606)
- Add protection from overly-large messages
1.2.4 -- 13 Oct. 2017
----------------------
- Silence some unnecessary warning messages (PR #487)
- Coverity fix - TOCTOU (PR #465)
- automake 1.13 configure fix (PR #486)
- Update RPM spec file (rpmbuild -ta, and --rebuild fixes) (PR #523)
- Support singletons in PMI-1/PMI-2 (PR #537)
1.2.3 -- 24 Aug. 2017
----------------------
- Resolve visibility issues for public APIs (PR #451)
- Atomics update - remove custom ASM atomics (PR #458)
- Fix job-fence test (PR #423)
- Replace stale PMIX_DECLSPEC with PMIX_EXPORT (PR #448)
- Memory barrier fixes for thread shifting (PR #387)
- Fix race condition in dmodex (PR #346)
- Allow disable backward compatability for PMI-1/2 (PR #350)
- Fix segv in PMIx_server_deregister_nspace (PR #343)
- Fix possible hang in PMIx_Abort (PR #339)
1.2.2 -- 21 March 2017
----------------------
- Compiler fix for Sun/Oracle CC (PR #322)
- Fix missing include (PR #326)
- Improve error checking around posix_fallocate (PR #329)
- Fix possible memory corruption (PR #331)
1.2.1 -- 21 Feb. 2017
----------------------
- dstore: Fix data corruption bug in key overwrite cases
- dstore: Performance and scalability fixes
- sm: Use posix_fallocate() before mmap
- pmi1/pmi2: Restore support
- dstore: Fix extension slot size allocation (Issue #280)
1.2.0 -- 14 Dec. 2016
----------------------
- Add shared memory data storage (dstore) option. Default: enabled
Configure option: --disable-dstore
- PMIx_Commit performance improvements
- Disable errhandler support
- Keep job info in the shared memory dstore
- PMIx_Get performance and memory improvements
1.1.5
-----
- Add pmix_version.h to support direct detection of PMIx library version
- Fix support for Solaris 10 by using abstract version of strnlen
- Fix native security module for Solaris by using getpeerucred in
that environment
- Ensure man pages don't get installed in embedded builds
- Pass temporary directory locations in info keys instead of
the environment
1.1.4
-----
- Properly increment the reference count for PMIx_Init
- Fix examples so all run properly
- Fix/complete PMI2 backward compatibility support to handle
keys that are not associated with a specific rank
- Do a better job of hiding non-API symbols
- Correct handling of semi-colon terminations on macros.
Thanks to Ashley Pittman for the patch
- Add more man pages
- Improve error checking and messages for connection
attempts from client to server
- If the tmpdir name is too long, provide an appropriate
help message to the user (particularly relevant on
Mac OSX). Thanks to Rainer Keller for the patch.
- Fix some C++ compatibility issues
- Fix/complete PMI-1 backward compatibility support
- Do not install internal headers unless specifically
requested to do so
- Add support for multiple calls to Put/Commit
1.1.3
-----
- Update the symbol hiding file to cover all symbols
- Fix examples and test directory Makefile.am's so
the Makefiles are automatically built and the
code compiled, but not installed
- Do not install the pmix library in embedded use-cases
1.1.2
-----
- Provide a check for hwloc support - if not found, then
don't pass any topology info down to the client as it
won't know how to unpack it anyway.
- Fix a few places where thread safety wasn't provided
- Fix several issues identified by Paul Hargrove:
* PMIx_Init(NULL) is supported
* Incomplete PMIx_constants man page had some lingering cruft
* Missing prototype for pmix_value_load
- Fix race condition in PMIx_Get/PMIx_Get_nb
- Fix double-free error in pmix_server_commit.
- Fix PMIX_LOAD_BUFFER to be safe.
1.1.1
-----
- Fix an issue where the example and test programs
were incorrectly being installed. Thanks to Orion
Poplawski for reporting it
1.1.0
-----
- major update of APIs to reflect comments received from 1.0.0
non-production release
- fixed thread-safety issues
- fixed a range of pack/unpack issues
- added unit tests for all APIs
1.0.0
------
Initial public release of draft APIs for comment - not production
intended

273
macx64/mpi/openmpi/share/doc/pmix/html/_sources/news/news-v2.x.rst.txt Normal file
View File

@@ -0,0 +1,273 @@
PMIx v2.x series
================
This file contains all the NEWS updates for all the PMIx v2.x
series, in reverse chronological order.
2.2.4 -- 07 Jun 2020
--------------------
- PR #1466: Silence spurious error log
- PR #1489: Allow specification of hostname to use by client
- PR #1499/#1512/#1518/#1525/#1528/#1533/#1553: Fix internal tests
- PR #1678: Update "check_vendor" for PGI problem
- PR #1734: Fix resource leaks in ptl/usock component
- PR #1777: Fix crash of dstor locks destructor in ds12
- PR #1788: Remove unnecessary error logs
2.2.3 -- 15 Aug 2019
--------------------
- PR #1162: Fix race condition when clients fail while in a PMIx
collective operation
- PR #1163: Fix a compiler warning in atomics on POWER arch
- PR #1165: Add BuildRequires: libevent-devel to spec file
- PR #1180: Remove dependency on C++ compiler for thread detection
- PR #1180: Add detection for Flex when building in non-tarball situations
- PR #1182: configury: use PMIX_ENABLE_DLOPEN_SUPPORT instead of enable_dlopen
- PR #1188: Link libpmix.so to MCA component libraries
- PR #1190: Ensure any cached notifications arrive after reg completes
- PR #1194: Ensure any cached notifications arrive after registration completes
- PR #1209: Update configure logic for clock_gettime
- PR #1213/#1217/#1221: Add configure option "--enable-nonglobal-dlopen"
If the MCA component libraries should link back to libpmix.so
- PR #1231: SPEC: Allow splitting PMIx in pmix and pmix-libpmi packages
- PR #1253: Preserve user-provided CFLAGS to protect autotools
- PR #1267: Correct dmodex example
- PR #1275: IPv6 IF Read: Buffer Overflow
- PR #1295: Fix comment: IPv6 IF_NAMESIZE
- PR #1296: Allow setup_fork to proceed even if gdds and pnet don't contribute
- PR #1296: Allow servers to pass NULL module
- PR #1297: Provide internal blocking ability to the register/deregister fns
- PR #1298: Add dummy handshake component to psec framework for testing
- PR #1303: Allow jobs to not specify proc-level info
- PR #1304: Provide proc data in cases where host does not
- PR #1305: Add some more values that can be computed
- PR #1308: Add missing tool rendezvous file
- PR #1309: Fix potential integer overflow in regex
- PR #1311: Work around memory bug in older gcc compilers
- PR #1329: Add -fPIC to static builds
- PR #1334: Cache only -W CFLAG entries to fix 32-bit builds
- PR #1341: Do not use '==' in m4 test statements
- PR #1342: Fix if_linux_ipv6_open interface filter
- PR #1344: Remove unnecessary libtool init for c++
- PR #1346: Fix incorrect pointer casts/deref
- PR #1347/#1348: Fix use of gethostname
- PR #1353/#1357: util/environ: use setenv() if available
- PR #1354: Plug a misc memory leak in the pmix_query_caddy_t destructor
- PR #1356: Fix another pointer cast/deref in test suite
- PR #1358: Implement support for class-based info arrays
- PR #1359: Plug misc minor memory leaks
- PR #1369: Fix legacy support for PMI-1
- PR #1370: Cleanup handling of data requests for different nspaces
- PR #1193: Resolve get of proc-specific job-level info from another nspace
- PR #1377: Skip fastpath/dstore for NULL keys
- PR #1379: Change IF_NAMESIZE to PMIX_IF_NAMESIZE and set to safe size
- PR #1385: Check for EINVAL return from posix_fallocate
- PR #1389: Plug misc memory leaks in configure
2.2.2 -- 24 Jan 2019
--------------------
- Fix a bug in macro identifying system events
2.2.1 -- 18 Jan 2019
--------------------
- Fix a bug in registration of default event handlers
that somehow slipped thru testing
2.2.0 -- 17 Jan 2019
--------------------
.. important:: THIS RELEASE MARKS THE STARTING POINT FOR FULL COMPLIANCE
WITH THE PMIX v2.2 STANDARD. ALL API BEHAVIORS AND ATTRIBUTE
DEFINITIONS MEET THE v2.2 STANDARD SPECIFICATIONS.
- Add a new, faster dstore GDS component 'ds21'
- Performance optimizations for the dstore GDS components.
- Plug miscellaneous memory leaks
- Silence an unnecessary warning message when checking connection
to a non-supporting server
- Ensure lost-connection events get delivered to default event
handlers
- Correctly handle cache refresh for queries
- Protect against race conditions between host and internal library
when dealing with async requests
- Cleanup tool operations and add support for connections to
remote servers.
- Automatically store the server URI for easy access by client
- Provide MCA parameter to control TCP connect retry/timeout
- Update event notification system to properly evict oldest events
when more space is needed
- Fix a number of error paths
- Handle setsockopt(SO_RCVTIMEO) not being supported
- Pass the tool's command line to the server so it can be returned
in queries
- Add support for C11 atomics
- Fix a bug when registering default event handlers
2.1.4 -- 18 Sep 2018
--------------------
- Updated configury to silence warnings on older compilers
- Implement job control and sensor APIs
- Update sensor support
- Fix a few bugs in the event notification system and provide some
missing implementation (support for specifying target procs to
receive the event).
- Add PMIX_PROC_TERMINATED constant
- Properly deal with EOPNOTSUPP from getsockopt() on ARM
2.1.3 -- 23 Aug 2018
--------------------
- Fixed memory corruption bug in event notification
system due to uninitialized variable
- Add numeric version definition
- Transfer all cached data to client dstore upon first connect
2.1.2 -- 6 July 2018
--------------------
- Added PMIX_VERSION_RELEASE string to pmix_version.h
- Added PMIX_SPAWNED and PMIX_PARENT_ID keys to all procs
started via PMIx_Spawn
- Fixed faulty compares in PMI/PMI2 tests
- Fixed bug in direct modex for data on remote node
- Correctly transfer all cached job info to the client's
shared memory region upon first connection
- Fix potential deadlock in PMIx_server_init in an error case
- Fix uninitialized variable
- Fix several memory and file descriptor leaks
2.1.1 -- 23 Feb 2018
--------------------
- Fix direct modex when receiving new nspace
- Resolve direct modex of job-level info
- Fix a bug in attribute configuration checks
- Fix a couple of bugs in unpacking of direct modex job-level data
- Correcly handle application setup data during "instant on" launch
- add a PMIX_BYTE_OBJECT_LOAD convenience macro
- Fix two early "free" bugs
- Add an example PMI-1 client program
2.1.0 -- 1 Feb 2018
-------------------
.. important:: This release contains the first implementation of cross-version
support. Servers using v2.1.0 are capable of supporting clients using
PMIx versions v1.2 and above. Clients using v2.1.0 are able to interact
with servers based on v1.2 and above.
- Added cross-version communication support
- Enable reporting of contact URI to stdout, stderr, or file (PR #538)
- Enable support for remote tool connections (PR #540, #542)
- Cleanup libevent configure logi to support default install paths (PR #541)
- Debounce "unreachable" notifications for tools when they disconnect (PR #544)
- Enable the regex generator to support node names that include multiple
sets of numbers
2.0.3 -- 1 Feb 2018
-------------------
- Fix event notification so all sides of multi-library get notified
of other library's existence
- Update syslog protection to support Mac High Sierra OS
- Remove usock component - unable to support v1.x clients due
to datatype differences
- Cleanup security handshake
- Cleanup separation of PMI-1/2 libraries and PMIx symbols
- Protect against overly-large messages
- Update data buffer APIs to support cross-version operations
- Protect receive callbacks from NULL and/or empty buffers as this
can occur when the peer on a connection disappears.
- Fix tool connection search so it properly descends into the directory
tree while searching for the server's contact file.
- Fix store_local so it doesn't reject a new nspace as that can happen
when working with tools
- Ensure we always complete PMIx_Finalize - don't return if something
goes wrong in the middle of the procedure
- Fix several tool connection issues
2.0.2 -- 19 Oct 2017
--------------------
- Update RPM spec file (rpmbuild -ta, and --rebuild fixes) (PR #523)
- Support singletons in PMI-1/PMI-2 (PR #537)
- Provide missing implementation support for arrays of pmix_value_t's (PR #531)
- Remove unsupported assembly code for MIPS and ARM processors
prior to v6 (PR #547)
- Fix path separator for PMIx configuration files (PR #547)
- Add configure option to enable/disable the default value for the
show-load-errors MCA param (PR #547)
2.0.1 -- 24 Aug. 2017
---------------------
- Protect PMIX_INFO_FREE macro from NULL data arrays
- Added attributes to support HWLOC shared memory regions
- Fixed several syntax errors in configure code
- Fixed several visibility errors
- Correctly return status from PMIx_Fence operation
- Restore tool connection support and implement search
operations to discover rendezvous files
2.0.0 -- 22 Jun 2017
--------------------
.. important:: This release implements the complete PMIX v2.0 Standard
and therefore includes a number of new APIs and features. These
can be tracked by their RFC's in the RFC repository at:
https://github.com/pmix/RFCs. A formal standards document will
be included in a later v2.x release. Some of the changes are
identified below.
- Added the Modular Component Architecture (MCA) plugin manager and
converted a number of operations to plugins, thereby allowing easy
customization and extension (including proprietary offerings)
- Added support for TCP sockets instead of Unix domain sockets for
client-server communications
- Added support for on-the-fly Allocation requests, including requests
for additional resources, extension of time for currently allocated
resources, and return of identified allocated resources to the scheduler
(RFC 0005 - https://github.com/pmix/RFCs/blob/master/RFC0005.md)
- Tightened rules on the processing of PMIx_Get requests, including
reservation of the "pmix" prefix for attribute keys and specifying
behaviors associated with the PMIX_RANK_WILDCARD value
(RFC 0009 - https://github.com/pmix/RFCs/blob/master/RFC0009.md)
- Extended support for tool interactions with a PMIx server aimed at
meeting the needs of debuggers and other tools. Includes support
for rendezvousing with a system-level PMIx server for interacting
with the system management stack (SMS) outside of an allocated
session, and adds two new APIs:
- PMIx_Query: request general information such as the process
table for a specified job, and available SMS capabilities
- PMIx_Log: log messages (e.g., application progress) to a
system-hosted persistent store
(RFC 0010 - https://github.com/pmix/RFCs/blob/master/RFC0010.md)
- Added support for fabric/network interactions associated with
"instant on" application startup
(RFC 0012 - https://github.com/pmix/RFCs/blob/master/RFC0012.md)
- Added an attribute to support getting the time remaining in an
allocation via the PMIx_Query interface
(RFC 0013 - https://github.com/pmix/RFCs/blob/master/RFC0013.md)
- Added interfaces to support job control and monitoring requests,
including heartbeat and file monitors to detect stalled applications.
Job control interface supports standard signal-related operations
(pause, kill, resume, etc.) as well as checkpoint/restart requests.
The interface can also be used by an application to indicate it is
willing to be pre-empted, with the host RM providing an event
notification when the preemption is desired.
(RFC 0015 - https://github.com/pmix/RFCs/blob/master/RFC0015.md)
- Extended the event notification system to support notifications
across threads in the same process, and the ability to direct
ordering of notifications when registering event handlers.
(RFC 0018 - https://github.com/pmix/RFCs/blob/master/RFC0018.md)
- Expose the buffer manipulation functions via a new set of APIs
to support heterogeneous data transfers within the host RM
environment
(RFC 0020 - https://github.com/pmix/RFCs/blob/master/RFC0020.md)
- Fix a number of race condition issues that arose at scale
- Enable PMIx servers to generate notifications to the host RM
and to themselves

276
macx64/mpi/openmpi/share/doc/pmix/html/_sources/news/news-v3.x.rst.txt Normal file
View File

@@ -0,0 +1,276 @@
PMIx v3.x series
================
This file contains all the NEWS updates for the PMIx v3.x
series, in reverse chronological order.
3.2.2 -- 7 Dec 2020
-------------------
- PR #1930: Remove man page setup as there are no manpages in v3.2
- PR #1933: Remove stale config command
- PR #1940: Fix dependency issue with hwloc
- PR #1941: .spec: add ``*-devel`` packages
3.2.1 -- 12 Nov 2020
--------------------
- PR #1890:
- Fix Issue #1889: Fix symlinks in unit tests to include new timeout
- Fix Issue #1891: Remove pnet/opa component that should not be in v3.2
- PR #1904: Add more metadata to string generated from preg/compress
- PR #1919: Fix memory leak in PMIx_Get/fastpath
3.2.0 -- 22 Oct 2020
--------------------
- PR #1402/#1403/#1421/#1423: Modex size reductions
- PR #1752: Convert man pages to Markdown (pandoc)
- PR #1766: Move from -levent to -levent_core for linking Libevent
- PR #1832: Sync 3.2 branch with master
- New attributes:
- PMIX_HOSTNAME_ALIASES
- PMIX_HOSTNAME_KEEP_FQDN
- PMIX_GET_REFRESH_CACHE
- PMIX_REQUIRED_KEY
- Removed PMIX_VALUE_COMPRESSED_STRING_UNPACK macro from pmix_common.h
- New frameworks
- PR #1139: pcompress - Compression methods
- PR #1423: psquash - Flexible integer packing
- New components
- PR #1139: preg/compress - regular expression methods
- PR #1422 Modified string representations produced by PMIx_generate_regex
and PMIx_generate_ppn.
- Issue #1586: Fixed dmodex support and PMIx_Get behavior
- PR #1748: Removed --with-pmix-symbol-rename configure option
- PR #1848: Expose PMIX_REGEX constant per v3.2 standard
- PR #1885: Fix immediate flag behavior at the server
3.1.5 -- 14 Feb 2020
--------------------
.. important:: The signature of the PMIx_Allocation_request has changed
in accordance with an Errata update of the PMIx v3 Standard
- PR #1413/#1465: Remove unnecessary error log
- PR #1433: Return the correct status from PMIx_Publish
- PR #1445: Sync. with master to fix 'get' of data for unknown namespace
Includes the following PRs from master
- PR #1382: dstore: fixed truncate key-names while restoring
- PR #1405: Fix xnspace dmodex and add verbose debug
- PR #1406: Resolve request for job-level data
- PR #1407/#1409/#1411: Fix dmodex across nspaces
- PR #1434/#1436: Cleanup handling of info arrays
- PR #1435: Cleanup example and remove debug
- PR #1437: Update blocking Allocation_request signature
- PR #1440: Fix 'get' of data for unknown namespace
- PR #1442: Fix fences with namespaces where no local processes are running
- PR #1472: Initialize nlocal and local in the tracker
- PR #1487: Sync. with master to fix info array and cross-version issues
- PR #1493/#1497/#1501/#1505/#1589: Info array and Cross-version fixes
- PR #1511/#1517/#1520/#1523/#1534/#1565: Fix pmix tests
- PR #1530: Improve handling of servers piror to v3.1.5
- PR #1531: Update transfer from hash to dstore
- PR #1538: Fix singleton initialization
- PR #1547: Add missing PMIx_IOF_deregister function
- PR #1554/#1591: Fix memory leak on namespace deregister
- PR #1561: Configury fix for reproducible builds
- PR #1579: Protect pthread setpshared calls
- PR #1587: Fix to gds/dstore configure logic
- PR #1610: Adjust hotel timeout to be in whole seconds
- PR #1613: dstore: Fix cache size calculation
- PR #1622: Fix multiple occurrences of unaligned access in pmix tests
- PR #1620: Re-address the collective tracker problem
3.1.4 -- 9 Aug 2019
-------------------
- PR #1342: Fix if_linux_ipv6_open interface filter
- PR #1344: Remove unnecessary libtool init for c++
- PR #1346: Fix incorrect pointer casts/deref
- PR #1347/#1348: Fix use of gethostname
- PR #1353/#1357: util/environ: use setenv() if available
- PR #1354: Plug a misc memory leak in the pmix_query_caddy_t destructor
- PR #1356: Fix another pointer cast/deref in test suite
- PR #1358: Implement support for class-based info arrays
- PR #1359: Plug misc minor memory leaks
- PR #1368: Backport support for libev
- PR #1369: Fix legacy support for PMI-1
- PR #1370: Cleanup handling of data requests for different nspaces
- PR #1193: Resolve get of proc-specific job-level info from another nspace
- PR #1376: Fix problems in the Log code path, updates to simple test suite
- PR #1377: Skip fastpath/dstore for NULL keys
- PR #1379: Change IF_NAMESIZE to PMIX_IF_NAMESIZE and set to safe size
- PR #1385: Check for EINVAL return from posix_fallocate
- PR #1389: Plug misc memory leaks in configure
3.1.3 -- 2 July 2019
--------------------
- PR #1096: Restore PMIX_NUM_SLOTS for backward compatibility
- PR #1106: Automatically generate PMIX_NUMERIC_VERSION
- PR #1143: Fix tool connection handshake for tools that are registered
clients
- PR #1163: Fix a compiler warning in atomics on POWER arch
- PR #1162: Fix race condition when clients fail while in a PMIx
collective operation
- PR #1166: Fix a regression in spinlock atomics
- PR #1159: Fix missing pointer update when shared memory segment
was re-attached
- PR #1180: Remove dependency on C++ compiler for thread detection
- PR #1180: Add detection for Flex when building in non-tarball situations
- PR #1165: Add dependency on libevent-devel to rpm spec file
- PR #1188: Link libpmix.so to MCA component libraries
- PR #1194: Ensure any cached notifications arrive after registration completes
- PR #1205: Add "make check" support
- PR #1209: Update configure logic for clock_gettime
- PR #1213/#1217/#1221: Add configure option "--enable-nonglobal-dlopen"
If the MCA component libraries should link back to libpmix.so
- PR #1231: SPEC: Allow splitting PMIx in pmix and pmix-libpmi packages
- PR #1222: Fix case of multiple launcher calls in job script
- PR #1237: Avoid double-free of collective tracker
- PR #1237: Ensure all participants are notified of fence complete
- PR #1237: Ensure all participants are notified of connect and disconnect complete
- PR #1250: Fix PMIx_server_finalize hang (rare)
- PR #1271: PTL/usock doesn't support tools
- PR #1280: Fix the PTL connection establishment protocol
- PR #1280: Fix tool connection in psec/handshake mode
- PR #1289: Avoid output_verbose overhead when it won't print
- PR #1296: Allow setup_fork to proceed even if gdds and pnet don't contribute
- PR #1296: Allow servers to pass NULL module
- PR #1297: Provide internal blocking ability to the register/deregister fns
- PR #1298: Add dummy handshake component to psec framework for testing
- PR #1303: Allow jobs to not specify proc-level info
- PR #1304: Provide proc data in cases where host does not
- PR #1305: Add some more values that can be computed
- PR #1308: Add missing tool rendezvous file
- PR #1309: Fix potential integer overflow in regex
- PR #1311: Work around memory bug in older gcc compilers
- PR #1321: Provide memory op hooks in user-facing macros
- PR #1329: Add -fPIC to static builds
- PR #1340: Do not use '==' in m4 test statements
3.1.2 -- 24 Jan 2019
--------------------
- Fix a bug in macro identifying system events
- Restore some non-standard macros to the pmix_extend.h
header - these are considered "deprecated" and will be
removed from public-facing headers in future releases
3.1.1 -- 18 Jan 2019
--------------------
- Fix a bug in registration of default event handlers
that somehow slipped thru testing
3.1.0 -- 17 Jan 2019
--------------------
.. important:: THIS RELEASE MARKS THE STARTING POINT FOR FULL COMPLIANCE
WITH THE PMIX v3 STANDARD. ALL API BEHAVIORS AND ATTRIBUTE
DEFINITIONS MEET THE v3 STANDARD SPECIFICATIONS.
- Add a new, faster dstore GDS component 'ds21'
- Performance optimizations for the dstore GDS components.
- Plug miscellaneous memory leaks
- Silence an unnecessary warning message when checking connection
to a non-supporting server
- Ensure lost-connection events get delivered to default event
handlers
- Correctly handle cache refresh for queries
- Protect against race conditions between host and internal library
when dealing with async requests
- Cleanup tool operations and add support for connections to
remote servers. Initial support for debugger direct/indirect
launch verified with PRRTE. Cleanup setting of tmpdir options.
Drop rendezvous files when acting as a launcher
- Automatically store the server URI for easy access by client
- Provide MCA parameter to control TCP connect retry/timeout
- Update event notification system to properly evict oldest events
when more space is needed
- Fix a number of error paths
- Update IOF cache code to properly drop oldest message. Provide
MCA parameter for setting cache size.
- Handle setsockopt(SO_RCVTIMEO) not being supported
- Ensure that epilogs get run even when connections unexpectedly
terminate. Properly split epilog strings to process multiple
paths
- Pass the tool's command line to the server so it can be returned
in queries
- Add support for C11 atomics
- Support collection and forwarding of fabric-specific envars
- Improve handling of hwloc configure option
- Fix PMIx_server_generate_regex to preserve node ordering
- Fix a bug when registering default event handlers
3.0.2 -- 18 Sept 2018
---------------------
- Ensure we cleanup any active sensors when a peer departs. Allow the
heartbeat monitor to "reset" if a process stops beating and subsequently
returns
- Fix a few bugs in the event notification system and provide some
missing implementation (support for specifying target procs to
receive the event).
- Add PMIX_PROC_TERMINATED constant
- Properly deal with EOPNOTSUPP from getsockopt() on ARM
3.0.1 -- 23 Aug 2018
--------------------
.. warning:: DEPRECATION WARNING The pmix_info_array_t struct was
initially marked for deprecation in the v2.x series.
We failed to provide clear warning at that time. This
therefore serves as warning of intended removal of
pmix_info_array_t in the future v4 release series.
- Fixed memory corruption bug in event notification
system due to uninitialized variable
- Add numeric version field to pmix_version.h
- Transfer all cached data to client dstore upon first connect
- Implement missing job control and sensor APIs
3.0.0 -- 6 July 2018
--------------------
.. important:: This release implements the complete PMIX v3.0 Standard
and therefore includes a number of new APIs and features. These
can be tracked by their RFC's on the community website:
https://pmix.org/pmix-standard.
- Added blocking forms of several existing APIs:
- PMIx_Log
- PMIx_Allocation_request
- PMIx_Job_control
- PMIx_Process_monitor
- Added support for getting/validating security credentials
- PMIx_Get_credential, PMIx_Validate_credential
- Extended support for debuggers/tools
- Added IO forwarding support allowing tools to request
forwarding of output from specific application procs,
and to forward their input to specified target procs
- Extended tool attributes to support synchronization
during startup of applications. This includes the
ability to modify an application's environment
(including support for LD_PRELOAD) and define an
alternate fork/exec agent
- Added ability for a tool to switch server connections
so it can first connect to a system-level server to
launch a starter program, and then reconnect to that
starter for debugging purposes
- Extended network support to collect network inventory by
either rolling it up from individual nodes or by direct
query of fabric managers. Added an API by which the
host can inject any rolled up inventory into the local
PMIx server. Applications and/or the host RM can access
the inventory via the PMIx_Query function.
- Added the ability for applications and/or tools to register
files and directories for cleanup upon their termination
- Added support for inter-library coordination within a process
- Extended PMIx_Log support by adding plugin support for new
channels, including local/remote syslog and email. Added
attributes to query available channels and to tag and
format output.
- Fix several memory and file descriptor leaks

777
macx64/mpi/openmpi/share/doc/pmix/html/_sources/news/news-v4.x.rst.txt Normal file
View File

@@ -0,0 +1,777 @@
PMIx v4.x series
================
This file contains all the NEWS updates for the PMIx v4.x
series, in reverse chronological order.
4.2.6 -- 9 Sep 2023
----------------------
.. warning:: CVE-2023-41915
A security issue was reported by François Diakhate (CEA)
which is addressed in the PMIx v4.2.6 and v5.0.1 releases.
(Older PMIx versions may be vulnerable, but are no longer
supported.)
A filesystem race condition could permit a malicious user
to obtain ownership of an arbitrary file on the filesystem
when parts of the PMIx library are called by a process
running as uid 0. This may happen under the default
configuration of certain workload managers, including Slurm.
Detailed changes include:
- PR #3150 Do not follow links when doing `chown`
- PR #3147 Multiple commits
- Retrieve pset names upon PMIx_Get request
- Add a new "pctrl" tool for requesting job control ops
- PR #3143 Multiple commits
- Properly support the "log" example
- Enable building of tarball
- show_help: strip leading/trailing blank lines
- docs: fix some leftover "Open MPI" references
- docs: fix HTML word wapping in table cells
- Improve error handling in setup_topology
- Minor cleanups for disable-dlopen
- Fix Python bindings
- PR #3132 Multiple commits
- Switch to using event lib for connections
- Roll to v4.2.6
4.2.5 -- 6 Aug 2023
----------------------
- PR #3121 Multiple commits
- Allow to override build date with SOURCE_DATE_EPOCH
- Adjust NEWS and VERSION for release
- PR #3120 Multiple commits
- Repair the pattrs utility
- docs: speed up Sphinx processing
- Fix bitrot in pquery tool
- Fix bitrot in plookup
- Construct the array of event strings
- Add new API and cleanup pevent tool
- Minor formatting cleanups
- Expose pmix_getline utility
- PR #3102 Multiple commits
- Protect against HWLOC v3 and above
- pmix_hwloc.c: use NUMANODE by default
- pmix_hwloc.h: PACKAGE/NUMANODE replaced SOCKET/NODE in 1.11, not 1.10
4.2.4 -- 17 Jun 2023
----------------------
- PR #3093 Require cherry picks and update github actions
- PR #3086 Multiple commits
- Handle the case of unbound proc. Also ensure topology is available
- Remove the group from client tracking when destruct is done
- Return the correct status from PMIx_Init
- Update asm config, shmem ref counting, atomic ops.
- Remove environ from public header
- Update MCA param file handling
- Cleanup changes and update to rc2
- PR #3081 Remove unimplemented component
- PR #3078 Eliminate double-free
- PR #3066 RTD: Add .readthedocs.yaml file
- PR #3064 Add missing frees
- PR #3060 Multiple commits
- Provide tool for checking compatibility between two PMIx libraries
- Ensure tools always send their event registration to their servers
- Include the OAC subdir in the autoconf make directories
- PR #3058 setserver fixes for v4.2 branch
- PR #3053 Multiple commits
- Attempt to resolve gcc13 complaint
- Add/update documentation
- PMIx: Fix compile error in macro
- Ensure tools send requests to their server
- Sort the procs for a fence operation
- Silence UBSan warning
- Make pmix_test MSan clean
- Silence TSan data race warnings
- Avoid python setup.py installdir error
- Remove duplicate atomic definitions
- PR #3029: Fix a few corner cases in the cmd line parser
- PR #3009: Fix fetch of globally unique keys
- PR #3008: Multiple commits
- Plug memory leaks
- Convert majority of PMIX_*_FREE() macros
- Improve PMIX_*_RELEASE() consistency
- Silence couple of nit warnings
- Complete PMIX_*_FREE() conversion
- Fix some Python bindings errors
- Correct cbdata type in pmix_show_help callback function
- Cleanup code style, fix bit checks, and fix backward compatibility
- PR #3002: Update OAC submodule pointer
- PR #2992: Multiple commits
- Update rpm spec file
- Silence debug output
- Avoid large stack allocations in pmix_bfrops_base_tma_setenv()
- PR #2977: Fix handling of cmd line arguments
- PR #2972: Handle the case where prterun is given no options
- PR #2966: Update sphinx requirements
- PR #2964: Trim v5 crossover from the Python bindings
- PR #2963: Multiple commits
- Remove the PMIX_SIZE_ESTIMATE attribute
- Remove GDS "set_size" entry points
4.2.3 -- 7 Feb 2023
-------------------
- PR #2959 Move release of pmix_client_globals.myserver to later
- PR #2937 Multiple commits
- Update exceptions doc
- Disable the "sentinel" attribute in Solaris
- Handle some Solaris errors/warnings
- Hide unused params
- Turn off the "format" attribute on Solaris
- PR #2927 Add option to abort on component find failure
- PR #2922 Fix memory leak in pmix_hash_fetch
- PR #2920 ptl/base: retry recv() when it encounter EAGAIN or EWOULDBLOCK
- PR #2913 Multiple commits
- Fix some backport issues
- Fix component name declarations
- Silence unnecessary repository item warnings
- Silence unnecessary warnings
- Correct libpmix_mca_common_dstore versioning
- Fix the static build
- PR #2911 Multiple commits
- Avoid double-caching of events
- Add const qualifier to nspace strings
- Provide support for estimating the size of value objects
- Enable size estimates for modex-like operations
- Fix segfault in fence operation with groups
- Add an attribute to request display of available cpus
- Initialize client topology
- Add attribute to stipulate parseable output for display info
- Add malloc return check in bfrops for byte object unpack
- Add a draft security policy
- Update docs/security.rst
- Provide pointer to online security policy in README.md
- Missing cleanups
- PR #2902 Multiple commits
- First cut of Sphinx / ReadTheDocs docs
- Update Github actions to use submodules
- build: Update to use OAC_C_COMPILER_VENDOR
- Update OAC submodule pointer
- First cut of Sphinx / ReadTheDocs docs
- mlnx Github action: install Sphinx
- docs: put restrictions on Sphinx versions
- PR #2895 python: updates for Python bindings
- PR #2885 Protect against NULL topology when destructing pmix_topology_t
- PR #2882 Multiple commits
- Minor compatibility touchup
- Cleanup
- Fix singleton support
- Re-implement the timeout support for purely local grp ops
- Fix local group operations
- Correctly identify Cython as a required package
- Move SIGCHLD capture to aux event base
- Silence a warning during Python binding install
- Fix a typo in the macro backers and add a "stop" pt in deprecated.h
- Silence a few Coverity complaints
- Add an attribute for passing an auxiliary event base
- Complete the macro-to-function conversion
- Continue macro converstion to functions
- Checkpoint work on macro conversion to functions
- Extend handling of bool MCA params
- Fix a couple of bugs in the modex/get path
- Convert macros to functions
- Always allow the GDS to use the namespace list
- Ensure the ptl connection handler includes the provided info
- Change function signature of mark_modex_complete().
- Add some scheduler integration support
- Add hooks for GDS components to handshake modex complete
- Include deprecated definitions in Python bindings
- Add attribute to report index of topology in storage array
- Add attribute to query allocation info
- Add an API to pretty-print pmix_app_t structures
- Try both peer and server storage for connect info
- Remove debug print statements
- Allow gds function fallback to hash take II.
- Add support for scheduler connections
- Cleanup a couple of warnings in Python bindings
- Add an API and attribute
- Avoid infinite loop in fabric registration
- Roll version to 4.2.3
- PR #2829: Multiple commits
- Minor correction to check_os_flavors
- Allow Python tool to set server module functions
- Some repairs to the Python bindings
- Fix the Python tests
- PR #2828: Remove chatty error log output
- PR #2823: Some cleanup of the Python bindings build system
- PR #2821: Correct return codes for two APIs
- PR #2817: Modify the pmix_output system
- PR #2813: Fix bashism in oac_check_package.m4
- PR #2811: Multiple commits
- build: fix bashisms in configure
- build: fix -Wstrict-prototypes
- PR #2808: pmix_list: fix a bug in pmix_list_insert()
- PR #2806: Multiple commits
- Have python bindings properly setup the env
- The PMIx_IOF_Push() function can take a NULL option for its
buffer object. Update Python bindings so it can use this.
- PR #2803: oneapi (and probably llvm): patch to allow
pmix tests to compile using icx, icpx, etc.
- PR #2801: intel oneapi: fix a munge code error
4.2.2 -- 25 Oct 2022
--------------------
.. important:: This is the minimum version required to support PRRTE v3.0.
- PR #2799: Multiple commits
- Add const qualifier to pset_name
- Fix one place that complained about lost qualifier
- PR #2797 Silence complaint about enum vs int
- PR #2793 Update NEWS
- PR #2792 Multiple commits
- Handle app-info in the gds/hash component
- Handle session-info in the gds/hash component
- PR #2790 Update NEWS
- PR #2789 Multiple commits
- Cleanup some store/retrieve issues
- Stop-in-init applies to all procs in a job
- PR #2787 Update EXCEPTIONS
- PR #2783 Multiple commits
- Add some debug macros for tracking key values
- Provide a little more useful error output
- PR #2777 Multiple commits
- llvm/oneapi: fixes to bring pmix up to iso c99
- pnet/nvd: Fix macro escaping issue
- Enhance the performance of the var_scope_push/pop script
- PMIX_OBJ_STATIC_INIT: fixed initialization
- PR #2775 Plug amemory leaks
- PR #2772 Update headers for release
- PR #2771 Plug a memory leak
- PR #2770 Multiple commits
- Fix the "check_cli_option" code
- Provide more detailed process failure codes and fix
CLI parsing
- pmix_reinit: a fix to allow PMIx to be reinitable
- Update specfile BuildRequires
- Additional BuildRequires in spec
- PR #2766 Roll to v4.2.2
4.2.1 -- 13 Sept 2022
---------------------
- PR #2754 Multiple commits
- Export the output_stream_t class declaration
- Update NEWS for release
- PR #2752 Catch missing library renames
- PR #2751 Multiple commits
- Remove stale m4 and unimplemented function declaration
- Mark that proc arrays being passed have been sorted
- Add improved debug and correct param passing to pmix_init_util
- PR #2747 Final prep for release
- PR #2746 Ensure tools relay events to their server
- PR #2744 Multiple commits
- Clean up leftover .gitignore entry
- Fix a number of Coverity issues
- Add a couple of macro definitions
- PR #2739 Multiple commits
- Consistently use PMIx_Error_string in client example
- Convert the MCA parameter for "show_load_errors"
- PR #2734 Add some detail to warning output by flex detector
- PR #2731 Do not set the buffer type in construct
- PR #2728 Prep for v4.2.1rc1
- Add some attributes to support job launch
- Update EXCEPTIONS, NEWS, VERSION for v4.2.1rc1
- PR #2725 Multiple updates
- Make the session info array support conform to the standard
- Remove stale common/sse code and cleanup pnet/sshot configure
- Resolve confused use of PMIX_UNIV_SIZE for PMIX_JOB_SIZE in
test code
- Minor cleanups
- PR #2718 Release GIL before registering event handler in Python
bindings
- PR #2716 Multiple commits
- Add support for HPE Slingshot fabric
- Add runtime options attribute
- PR #2713 Multiple commits
- iof: Fix merging of stderr to stdout.
- Fix bad dereferences when passed a NULL parameter to PMIx_Init
- Add new attribute definitions to support display options
- PR #2706 Remove man pages
- PR #2703 Fix flex detection
- PR #2700 Multiple commits
- Fix the buildrpm script
- Enable show_help output on tools
- Bump VERSION to v4.2.1
4.2.0 -- 20 Aug 2022
--------------------
.. important:: This release includes a number of new features that
may be of use to library and application developers. These include:
* support for qualified values - i.e., the ability to reuse an
attribute, assigning it different values with each value
contingent upon one or more qualifiers. Thus, requests to
return the value can specify the corresponding qualifiers
to identify the specific version of the value being requested.
* provide additional information to be included in group construct
operations. The result of the operation shall include exchange
of such information with all participants, with the information
"qualified" by the assigned group context ID.
* new output formats that allow prepending output streams with
the hostname and pid of the source process
* improved support for tools that allow connection to multiple
simultaneous servers and better handshakes for establishing
connections
* fixes for access to session/node/app-realm information
* broader support for pretty-print of PMIx structures such
as pmix_info_t and pmix_value_t
* compliance with the new PMIx ABI definitions. This includes
converting some macros to functions, with macros retained
for backward compatibility
* capture and forwarding of default MCA parameter file values,
both from the system and user level
Detailed changes:
- PR #2697 Multiple commits
- Add example to simulate OMPI group usage
- Cleanup singleton IOF lists
- PR #2695 Output IO as singleton, support background commands
- PR #2692,2690 Silence gcc12 warnings
- PR #2689 Need to replace the entire proc in fence with group member
- PR #2687 Update NEWS/VERSION for rc2
- PR #2686 Fix/implement the group invite support
- PR #2682 Do not error out if lib is symlinked to lib64
- PR #2681 Separate out pinstalldirs for inclusion by PRRTE
- PR #2679 Fix the tm configure logic
- PR #2675 Minor cleanup of timestamp output
- PR #2673 Update NEWS, remove unready components, fix missing var
- PR #2672 Fix make_tarball and remove unused variable
- PR #2670 Support broader range of output formats
- PR #2668 Multiple commits
- Sort proc arrays to remove order sensitivity
- Fix multi-node group info distribution
- PR #2666 Coordinate psec modules across pfexec child
- PR #2665 Complete implementation of group info exchange
- PR #2659 Multiple commits
- Fix IOF of stdin
- Protect "create" macros from zero entries
- Return the correct code for register fabric
- Forward stdin to apps started using pfexec
- PR #2651 Multiple commits
- Enable picky compiler options by default in Git repo builds
- Remove bad destruct call
- Fix PMIX_INFO_PROCESSED macros
- Update show-help system
- Fix show_help output to include tools in distribution
- Fix dmodex operations
- Properly cast the pmix_list_item_t struct
- Fix potential use after free in tests
- Add "const" qualifiers to some string print APIs
- Cleanup some debug output
- construct_dictionary.py: make .format() safe for Python 2
- src/include/Makefile.am: avoid potential file corruption
- Stop multiple invocations of debugger-release
- Update the dmodex example
- PR #2629 Multiple commits
- Setup PMIX_STD_ABI_VERSION in the VERSION file
- Define the PMIX_QUERY_ABI_VERSION attribute
- Backend query support for PMIX_QUERY_ABI_VERSION and local keys
- Add examples for using PMIx_Query_info with PMIX_QUERY_ABI_VERSION
- Add PMIx Standard version info to pmix_info
- Fix pcompress/zlib implementation
- Return "succeeded" status when outputting help/version info
- PR #2623 Fix greek versioning
- PR #2614 Fix retrieval of node/app/session-realm info
- PR #2613 Some minor cleanups for picky compilers
- PR #2612 Some initial valgrind cleanup
- PR #2610 Multiple commits
- Remove unnecessary function call in pmix_gds_hash_fetch()
- pmix_fd: cap the max FD to try to close
- Support colocation of processes
- Optimize the file descriptor cleanup on OSX
- Require flex only when keyval_lex.c is not provided
- Fix hwloc verbose output
- PR #2601 Initialize pmix_info_t flags when loading
- PR #2594 Backport the utility and class exposure to support PRRTE
- PR #2588 configure.ac: update directory space check
- PR #2585 configury: do look for sed
- PR #2576 Refactor show_help() to use the PMIx_Log() api
- PR #2567 Make pmix_common.h stand alone
- PR #2564 Error out if no atomic support is available
- PR #2543 Properly deal with delayed local get requests
- PR #2540 Ensure we get correct return status
- PR #2538 Multiple commits
- Fix warning - compare of different signs
- Fix dmodex operation on local host
- PR #2535 Update the configure logic to track master
- PR #2534 Initialize size for getsockopt() and revert bad free
- PR #2533 Example fixes
- PR #2532 Protect critical zone in pmix_obj_update()
- PR #2518 Prohibit Python bindings with non-shared lib builds
- PR #2517 Fix Coverity warnings
- PR #2516 Properly handle queries of tools
- PR #2507 Properly handle tools that have tools connected to them
- PR #2506 Add print APIs and update pquery to use them
- PR #2505 Update configure flags
- PR #2504 Don't search home component path if not present
- PR #2502 Add missing function and improve error message
- PR #2460 Multiple commits
- Remove unneeded atomics code
- Begin stripping configure of unnecessary checks
- Initialize the mutex when constructing an object
- Sync the library to the Standard
- convert pmix_value_xfer to PMIx_Value_xfer
- pmix_iof.c: malloc buffer before memcpy()
- Clean up unused return value warnings
- Remove unnecessary sys/sysctl.h includes
- Include typedef for GCC builtin atomics
4.1.2 -- 11 Feb 2022
--------------------
.. important:: This release contains a workaround that resolves the prior
conflict with HWLOC versions 2.5.0 through 2.7.0 (inclusive).
Those versions of HWLOC are now supported.
- PR #2453: Avoid string literals in environ
- Be defensive against string literals in env
- Remove block of hwloc 2.5 - 2.7
- Adjust Mellanox CI Dockerfile so it can build
4.1.1 -- 1 Feb 2022
-------------------
.. important:: As of v4.1.1, PMIx includes an EXCEPTIONS file that lists
all deviations from the PMIx Standard. This primarily includes
extensions that have not yet been adopted by the Standard.
.. important:: As of v4.1.1, PMIx no longer has a dependency on "pandoc"
for building and installing man pages.
.. warning:: PMIx has identified a bug in HWLOC versions 2.5.0 thru
2.7.0 (inclusive) that causes PMIx to segfault during certain
operations. We have worked with the HWLOC developers to fix
that problem, and the fix will be included beginning in HWLOC
version 2.7.1. Accordingly, PMIx now checks for the problem
HWLOC versions and will error out of configure if they are
encountered.
- PR #2445 and 2447: Update HWLOC version detection
- Reject versions 2.5.0-2.7.0, inclusive
- PR #2428: Update for rc6
- Enable buffered IOF output
- Cleanups and docs for rc6
- PR #2426: Updates from master
- Updates to cleanup conflicts and touchups
- Silence Coverity warnings
- Be more flexible in library handling
- Finish cleaning up nocopy behavior
- test_v2: use static declaration for client parser
- Respect the nocopy qualifier
- Add static library note to README
- PMIX_HAVE_LIBEV and PMIX_HAVE_LIBEVENT flags must always
be defined
- Fix two bugs in PMIX_FLAGS_APPEND_MOVE
- Fix a problem using PMIX_RANK
- Final minor diddles of configure summary categories
- Add configure support for pgpu/pnet components
- libevent: prefer compiler tests over linking tests
- Cleanup libevent/libev selection logic
- Remove pkg-config dependency list
- Add wrapper compiler mca link argument passing
- Reintroduce PMIX_DYN_LIB_SUFFIX define
- config: remove string checks in hwloc/libevent
- Fix devel-check of test_v2
- Silence Coverity warning and cleanup code
- Fix a number of warnings and cleanup a few things
- Select all adapters with IPv4 addresses with specified
subnet ranges
- Fix environmental variable name in help-pmix-runtime
- Remove curl/jansson default search assumption
- Remove cobuild remnants from configure
- V2 suite test case for multiple inits and finalizes
- PR #2410: Mark dependencies private in pkg-config file
- PR #2396: Fix the network support components
- PR #2394: Update for landing zone 1
- Update NEWS/Version
- PR #2393:
- Correct copy/paste error - use correct procID
- Add a little debug info to a verbose output
- PR #2389: delete use of PMIX_CHECK_BROKEN_QSORT refs
- PR #2384: Final update for v4.1.1 rc5
- Ensure a param is always initialized
- Provide static initializers for all structures
- Stop in init if rndz URI given
- Update EXCEPTIONS/NEWS files
- PR #2380: Update 4.1.1 rc5
- Improve handling of compiler version string
- Fix corner case on iof flags
- Squash unused variable warnings
- Remove duplicate defines of client build dependencies
- Ensure we terminate the input channel when done
- Ensure pmix library gets a chance to cleanly terminate children
- Avoid ABI break in mid-series
- Define a static initializer for data_buffer_t
- Fix typos - replace OMPI with PMIx
- Silence Coverity concerns
- Make the backward-compatible ABI functions visible
- Avoid warning on void function return
- Allow operation if ONLY a loopback device is present
- PR #2332: Update 4.1.1 rc4
- Modify configure logic
- Add a missing helpfile (util) and few fixups
- Fix --output to ignore err on existing dirs
- Squash unused param warnings
- PR #2317: Update 4.1.1 rc3
- Add test_v2 to autoconf/automake processing
- Silence Coverity warnings
- Fix resource leak
- Change construct.py to mark PMIx functions with nogil
- Enable ultra-picky compiler options
- Ensure picky flags not set until after AC is done
- Add missing simptest.h file to tarball
- Expand the tm/pbs config to check for lib64
- Update portable platform file
- Abort configure if gcc is <= v4.8.1
- Enable support for address sanitizers, but only on request
- Fix issues raised by picky compiler checks
- Don't check for Python 3.4+ if not building the Python bindings
- Update VERSION and NEWS
- PR #2299: Update 4.1.1 rc2
- Update VERSION and NEWS
- Add some spawn-specific timeout attributes
- Resolve race condition in lost connection
- Provide "partial_success" error when collectives not complete
- Only conditionally decode the nspace return value when we
are sure the spawn was successful
- Correctly copy stone age hwloc topologies
- Remove man page Markdown source and build dependency on pandoc
- PR #2277: Update v4.1.1 release candidate
- Add missing m4 file
- Add a Standard extension value to the compliance version
- Properly read/output stdout/err from a fork/exec'd child
- Default to using our local_output flag
- Cleanup compiler warnings for ancient hwloc versions
- Prefix the output files with "pmix"
- Ensure tools wait until all active events are processed
- autogen.pl: ignore all excluded components
- Don't treat inability to open shmem file as fatal
- Avoid use of MCA params for singleton and report-uri
- Ensure the server waits for all IOF and message events to complete
- Restore the thread join in progress thread "stop"
- Mark the read event as no longer active
- Avoid blocking in the stdin read handler
- Some cleanup of IOF output
- Add missing .m4 files to extra_dist
- Check for libevent minimum 2.0.21
- Add Intel GPU component
- Correct vendor IDs and generalize check_vendor
- Add missing storage-related datatype support
- Add missing storage constants
- Improve pnet component selection
- Cleanup the device distance computation
- PR #2257: Check for libevent minimum 2.0.21
- PR #2253: Fix up string creation functions, take the GIL in the callback code,
and system malloc instead of the Python malloc for datastructures
going to PMIx
- PR #2250: Update attribute support tables
4.1.0 -- 29 July 2021
---------------------
.. important:: This release implements the complete PMIx v4.1 Standard
and therefore includes a number of new APIs and features. These
are fully documented in the official document. It also includes
some extensions that have not yet been included in that document.
Beyond the v4.1 modifications and additions to APIs, datatypes, attributes,
and macros, changes to the library include:
- PR #2251: More updates from master
- Replaced PMIx_Notify_Event with cbfunc call in errhandler to match
- Update attribute support tables
- PR #2248: Continue updates to support MPICH integration
- Extend IOF outputting format to cover Hydra options.
- PR #2246: Cleanup some IOF attributes
- PR #2235: Cherry-pick updates from master branch
- Default tools to outputting their IOF
- Initalize val before get in case get isn't successful
- Some cleanups of the event notification and keepalive support
- Remove stale travis.yml file
- Update simptest to truly support PMIx_Abort
- Some cleanups for client finalize and IOF output
- Do not forward cached IOF to self
- Update how C to Python bytes/strings are handled for get and byte objects
- Add test_v2 directory
- Add configure logic for RM and sse support
- Add pstat framework
- Remove duplicate PMIx_Data_load and PMIx_Data_unload definitions
- Add manpage files for tools
- Add sse common component
- Add the prm components
- Add the storage framework
- General update of code base to track master branch
- PR #2224: common/dstore: Fix inconsistent Makefile.am
- PR #2216: Cherry-pick updates from master branch
- Add missing osname endpt elements to bfrops
- Optimize check for nodes
- Transfer stdout/err formatting to PMIx
- Ensure tool output of IOF
- PR #2208: Cherry-pick updates from master branch
- Enable re-init of clients
- Add attribute to indicate copy/nocopy of output directed to files
- PR #2204: Add a few job error constants
- PR #2201: Cherry-pick updates from master branch
- Minor updates based on Standards review
- Correct references to help-ptl-tool.txt
- Protect register_nspace against new entries
- Add oversubscribed attribute
- PR #2195: configury: Use AC_CHECK_ALIGNOF and fix cross-compiling
- PR #2190:Cherry-pick updates from master branch
- Remove duplicative pmdl/ompi directories
- Add missing m4 file
- Update hwloc support to handle revised version string
- Register ompi5 and ompi4 as aliases for ompi plugin
- Correct the PMIx_Get signature
- Silence some gcc warnings
- Silence some gcc11 warnings
- Protect against bad nspace input
- Cleanup few lingering gcc11 warnings
- Protect against duplicate envar harvesting
- PR #2177: Cleanup shadow variables in dstore base and components
- PR #2156: Ensure we pass the desired scope on a PMIx_Get call
- PR #2170: Remove non-required items
- PR #2168: Cherry-pick updates from master branch
- Add missing datatype support in darray macros
- Update comments on debug attributes
- Remove stale envar settings in hwloc support
- Silence warning of unused var
- Minor addition to debug output
- PR #2158: atomics: Fix broken make dist
- PR #2154: Cherry-pick updates from master branch
- Spawn needs to do a little checking of the app
- build: Allow autogen.pl to be run from a tarball
- Enable singletons to connect to system servers
- Fix compile error in ptl_base_connect.c
- Update ptl_base_connect.c
- build: Change default build mode for components
- build: Remove options around mca direct calling
- Setup clients to output forwarded IO
- Set the default for enable-mca-dso
- Tool finalize crash due to ref count issue
- Reject ambiguous connection options
- ptl: prevent free of uninited suri variable
- Clang-format the code
- psec: include missing psec.h
- ptl: help on too-many-conns: mention conn handle files
- Some mods/cleanup of debugger definitions and handling
- build: Explicitly list libpmix dependencies
- build: Fix compiler attribute detection
- build: Fix compiler family detection
- atomics: Only support C11 and GCC builtin atomics
- Clean out unneeded test directory
- PR #2112: Add a bfrops 4.0.1 component
- PR #2111: Cherry-pick updates from master branch
- Add missing items
- Add missing PMIx_Data... functions
- Fix signature of new compression APIs
- Add compress/decompress APIs
- Update clang format
- Slight touchups on event notification and name print
- PR #2108: Cherry-pick updates from master branch
- leak: Free items in nslist for fence tracker
- Update src/common/pmix_iof.c
- Properly handle stdin forwarding
- Eliminate shadow variables
- leak: Fix case where buffer was unloaded, losing the pointer
- Leak: Always free ns->jobbkt in pmix_nspace_caddy_t destructor.
- Add clang format support
- PR #2105: Add zlib warning and compression checks
- PR #2100: Cherry-pick updates from master branch
- Correct listener - this is a PMIx v4 (not 4.1) server
- Purge shadowing as reported by gcc.
- Add -Wshadow to --picky-compiler
- Avoid zero byte malloc in argv_join_range
- Minor fix to libevent configury
- Minor configure cleanups
- Use LT_PATH_NM instead of AC_PATH_PROG to find nm
- Update to Autoconf 2.7x
- Enable singleton "comm_spawn" operations
- Link against libz when testing for TM
- Initialize myproc structure before calling PMIx_tool_set_server
- Py: Open files as UTF-8 while processing
- Fix Python binding build
- Correctly pass the right object to dereg cbfunc
- Extend check for empty buffer
- Correct miscast of object type
- Validate CFLAGS individually
- Use the provided caddy instead of creating a new one
- Silence -qinline xlc compiler warning
- Fix case where var->mbv_enumerator can be released when static
- Cleanup several places based on testing with PRRTE
- Ensure proper handling of IOF pull requests
- Protect against empty message
- Remove PMIX_BUFFER datatype and extend macro definition
- Fix stale definition for PMIX_HAVE_ATOMIC_LLSC_PTR
- Add datatype support for new types
- configury: fix _PMIX_CHECK_PACKAGE_LIB() macro
- Missed a spot - check for HWLOC_VERSION defined
- Protect HWLOC_VERSION
- Fix configury where most compilers will get mislabeled as 'gnu'
- Ensure the topology support matches the Standard
- Fix check for IBM xl compilers for v13.1 and later
- Cleanup the IOF register/dereg response code path
- Fix clang compliler regression
- Have developer builds use -O3 by default
- Silence PGI atomics warnings, while not breaking clang
- Update the new hybrid test a bit
- Fix build failure on Apple silicon
- Correctly handle precedence for first/last overall events
- Fix various PGI warnings
- Fix bugs in OFI configure and HWLOC component
- Add the local reference ID to iof/pull request
- Add a couple of useful macros
- Correct name of PSM2 envar
- configury: fix --with-ofi=DIR handling
- Add the psm2 auth_key to the job info and silence warning
- Update the pnet/opa component to current architecture
- Ensure the data array always gets initialized in PMIX_INFO_LIST_CONVERT
- Cleanup indirect debugger launch against mpirun
- PR #2014: Silence a couple of Coverity warnings
- PR #2013: Add the PMIx Standard version level to the version string
- PR #2012: Fix Python binding build for VPATH
- PR #2007: Disable IPv6 by default
- PR #2000: Set hostname in global to NULL on finalize
- PR #1998: Specify Python 3 for the configure check
4.0.0 -- 30 Dec 2020
--------------------
.. important:: This release implements the complete PMIx v4.0 Standard
and therefore includes a number of new APIs and features. These
are fully documented in the official document - the details of
the revisions included in v4.0 are summarized here:
https://pmix.github.io/uploads/2020/12/pmix-standard-4.0.pdf#page=549
Note that this version of OpenPMIx includes a first-cut at the
Python bindings described in Appendix A of the v4.0 Standard.
Beyond the v4.0 modifications and additions to APIs, datatypes, attributes,
and macros, changes to the library include:
- Removal of the usock messaging component - only TCP is now supported
- Removal of the PMI-1 and PMI-2 backward compatibility libraries into
a new separate repository
- Packaging changes to push the headers into ``*-devel`` packages
- libtool patch for Mac BigSur OS
- Fixed dependency issue with HWLOC to protect against stone-age versions
- Changed man page format to Markdown, requires pandoc to generate from
Git repository (but not from tarball)
- Enable local fork/exec by tools when not connected to a server - this
is done transparently
- Support reproducible builds
- Multiple bug fixes and memory leak repairs
- Add support for network interface and GPU device distances
- Allow retrieval of the caller's own rank and process ID via PMIx_Get
- Provide full delineation of client, server, and tool attribute support
- Add support for libev in lieu of libevent
- Detect/avoid conflict with LSF version of "libevent"
- Auto-detect and forward envars from various identified programming models
(e.g., OpenMPI, OpenSHMEM) and fabrics
- Change the default component build behavior to prefer building components
as part of libpmix.so instead of individual DSOs.

272
macx64/mpi/openmpi/share/doc/pmix/html/_sources/news/news-v5.x.rst.txt Normal file
View File

@@ -0,0 +1,272 @@
PMIx v5.x series
================
This file contains all the NEWS updates for the PMIx v5.x
series, in reverse chronological order.
5.0.5 -- 15 Dec 2024
--------------------
Detailed changes include:
- PR #3469: Final update for release
- PR #3468: Remove remnants of unsupported capability
- PR #3467: Remove stale configure.m4 scripts
- PR #3465: Update NEWS and VERSION
- PR #3463: Remove prm framework as not currently implemented
- PR #3462: Remove unused components from various frameworks
- PR #3461: Remove pgpu framework
- PR #3460: Remove pstrg framework
- PR #3452: .gitignore: add configure~
- PR #3449: Multiple commits
- Retry fetch with wildcard rank
- Fix typo in shmem2 fetch
5.0.4 -- 13 Nov 2024
--------------------
.. important:: This release represents the expected end of
the v5.0 series. Any follow-on bug fixes will
be committed to the release branch, but are
unlikely to generate an official release
tarball.
Detailed changes include:
- PR #3441: Update NEWS and VERSION for final release
- PR #3440: Minor cleanups plus resolve peers example
- PR #3434: Collapse the pfexec framework
- PR #3432: Update VERSION for release
- PR #3430: Multiple commits
- Update NEWS to include v5.0 branch
- Drop the sphinx required level to match PRRTE
- Ensure IOF respects formatting requests
- PR #3419: Add some missing attributes
- PR #3417: Multiple commits
- Fix typo in equality check
- Fix delayed get
- avoid warn-as-error for variable init
- Add support for libz-ng
- PR #3408: Update pmix_portable_platform_real.h from upstream gasnet
- PR #3404: Path must start with "src"
- PR #3402: Remove unused yaml
- PR #3400: add contrib/construct_event_strings.py to the dist tarball
- PR #3397: Multiple commits
- Add missing files
- mca/pif: fix pmix_found_linux typo
- Add cross-version compatibility to docs
- PR #3393: Multiple commits
- Add python directive
- Cleanup pfexec spawn operations
- Add missing function call
- PR #3387: Update OAC to latest HEAD
- PR #3385: Correctly check MCA params
- PR #3383: Protect against LTO optimizer
- PR #3381: Read The Docs updates
- PR #3379: Multiple commits
- Revert Sphinx requirements
- Warn against building tarball on MacOSX
- configure: fix regression that caused python to be mandatory to build
- configure: fix broken bashisms resulting in logic failure
- Update the requirements for Sphinx
- PR #3372: Multiple commits
- Update MLNX CI
- Apply prefix to copied version of the app array
5.0.3 -- 8 Jul 2024
-------------------
Detailed changes include:
- PR #3369: Update NEWS and VERSION for release
- PR #3366: Transfer results from partial success of lookup
- PR #3363: Multiple commits
- Fix singletons
- Protect against NULL fields
- PR #3361: Remove unused function in shmem2
- PR #3357: Github action: bring back MacOS builds
- PR #3354: Multiple commits
- Don't strip quotes from cmd line entries
- Handle single character filenames
- Update tar format to tar-pax
- Perform some cleanup
- Include devel-check status in configure summary
- Turn off MacOS CI
- PR #3334: Fix function declaration
- PR #3332: Fixes for PR3329
5.0.2 -- 21 Mar 2024
--------------------
.. important:: Cross-version incompatibility
The known issue of cross-version operability between
members of the PMIx v5.0 release series has been
resolved in this release. Thus, v5.0.2 and all subsequent
releases can operate across versions, including the
v5.0.1 and v5.0.0 releases.
Detailed changes include:
- PR #3330: Do not include PMIX_PREFIX in spawn upcall
- PR #3325: Multiple commits
- Correctly set the app cmd and argv0 fields
- Don't overwrite user's args
- Correct error in retrieval of node and app info
- PR #3319: Toughen the submodule checks in autogen.pl
- PR #3317 Correct group modex storage to avoid duplication
- PR #3314 Fix memory leak in storing of modex data
- PR #3311 More cleanup of group operations and local client array
- PR #3307 Include notes about submodules in docs
- PR #3299 Multiple commits
- gds/shmem2: provide a useful error message on memory allocation failure
- Add "close stale issues" actions
- oac: strengthen Sphinx check
- Remove stat call when destroying a dirpath
- Do not remove the system tmpdir during cleanup
- PR #3293 Multiple commits
- gds/shmem: fix build
- Update how PMIx attributes are looked up.
- Improve PMIx attribute lookup efficiency.
- gds/shmem: improve cross-version capabilities
- Revert "Disable gds/shmem at runtime"
- Revert "gds/shmem: fix build."
- Rename the gds/shmem component to gds/shmem2
- Protect output files during cleanup
- Begin to add man pages for PMIx commands
- Restore support for HWLOC truly ancient
- Continue work on tool man pages
- Fix the dictionary transfer in shmem2
- PR #3280 Multiple commits
- Implement attribute to specify connection order and process MCA params
- Error out of attempts for 32-bit builds
- hash: Add internal APIs that specify target key index.
- hash: Update pmix_hash functions to accept a pmix_keyindex_t*
- gds/shmem: Improve error message in tma_realloc()
- Remove static version of global function
- Fix handling of "--" in cmd lines
- Update the doubleget test
- Fully implement refresh cache support
- Adjust preg component priorities
- Remove unused function
- gds/shmem: Implement first cut of tma_realloc()
- Begin work on removing use of "stat"
- Fix typo
- avoid loopback in resolve_nspace_requests
- Refactor the prm framework
- Assign NULL to free'd pointer
- Cleanup some "unused params" errors
- Protect a variable
- Check for stdatomic.h
- Remove pmix_osd_dirpath_access
- Remove use of stat from pmix_getcwd
- Remove use of stat
- Remove use of stat in pmix_globals
- Remove use of stat to check file existence
- Test open a dir instead of using stat
- Minor cleanups for unused params
- pmix.h: Add capability flags
- Cleanup comments and prep for commit
- Do not remove the system tmpdir during cleanup
- Cleanup palloc and prun connections
- Cleanup a few typos and remove debug output
- Cast a few parameters when translating macros to functions
- Resolve problem of stack variables and realloc
- Restore support for detecting shared file systems
- Properly handle directories during cleanup
- gds/shmem: revert tma_free() strategy
- gds/shmem: fix potentially confusing error output
- Touchup the dirpath_destroy code
- Fix broken link in README
- Add a query attribute for number of available slots
- Do not add no-unused-parameter for non-devel-check builds
- Better support global keys
- PMIx_Query_info: removed duplicated PMIX_RELEASE
- Provide an explanation of session directories
- Fix --enable-devel-check builds
- Restore default to enable-devel-check in Git repos
- Protect against empty envar definition for mca_base_param_files
- Fix test builds with picky compiler options
- Protect against NULL hash table labels in debug output
- Update the Python regex for doc build
- Disable gds/shmem at runtime
- Cleanup update
- PR #3182 Multiple commits
- Remove debug print
- Make checking min versions consistent
- Add an action to test older HWLOC version
- Touchup the OMPI integration
- Fix couple of bugs in cmd line parser
- Fix typo in cmd line processor
- Add a new attribute to specify connection order
- PR #3166: Blacklist the HWLOC GL component to avoid deadlock
- PR #3162: Add a new Github Action
5.0.1 -- 9 Sep 2023
-------------------
.. warning:: CVE-2023-41915
A security issue was reported by François Diakhate (CEA)
which is addressed in the PMIx v4.2.6 and v5.0.1 releases.
(Older PMIx versions may be vulnerable, but are no longer
supported.)
A filesystem race condition could permit a malicious user
to obtain ownership of an arbitrary file on the filesystem
when parts of the PMIx library are called by a process
running as uid 0. This may happen under the default
configuration of certain workload managers, including Slurm.
.. warning:: Cross-version incompatibility
There is a known issue when operating between
PMIx versions v5.0.1 and v5.0.0. This occurs due
to a difference in the key-to-index conversion
between the two versions. Users are advised
to set the PMIX_MCA_gds=hash parameter
in their environment when using these two
versions.
Detailed changes include:
- Update news and version for release
- PR #3149 Multiple commits
- Do not follow links when doing "chown"
- Cleanup a little debug in new pctrl tool
- PR #3145 Multiple commits
- Retrieve pset names upon PMIx_Get request
- Add a new "pctrl" tool for requesting job control ops
- PR #3144 Multiple commits
- Properly support the "log" example
- show_help: strip leading/trailing blank lines
- docs: fix some leftover "Open MPI" references
- docs: fix HTML word wapping in table cells
- Improve error handling in setup_topology
- Define a new server type and connection flags
- Minor cleanups for disable-dlopen
- Fix Python bindings
- PR #3131 Multiple commits
- Switch to using event lib for connections
- Roll to version 5.0.1
5.0.0 -- 7 Aug 2023
-------------------
.. important:: This is the first release in the v5 family
and includes some significant changes, both internal
and user-facing. A partial list includes:
* initial attribute and API definitions in support of
scheduler integration to both applications and
resource managers/runtime environments.
* a new shared memory implementation that removes the need
for special "workaround" logic due to limitations in the
prior method
* support for "qualified" values whereby an application
can post multiple values to the same key, each with one
or more qualifiers - and then retrieve the desired one
by specifying the appropriate qualifier.
* availability of both function and macro equivalents
for all support operations (e.g., PMIX_ARGV_APPEND and
PMIx_Argv_append). Note that the macro versions have
been deprecated by the PMIx Standard, but remain highly
recommended for use by those compiling against the
library (as opposed to dlopen'ing it)
A full list of individual changes will not be provided here,
but will commence with the v5.0.1 release.

44
macx64/mpi/openmpi/share/doc/pmix/html/_sources/quickstart.rst.txt Normal file
View File

@@ -0,0 +1,44 @@
.. _label-quickstart:
Quick start
===========
In many cases, OpenPMIx can be built and installed by simply
indicating the installation directory on the command line:
.. code-block:: sh
$ tar xf pmix-<version>.tar.bz2
$ cd pmix-<version>
$ ./configure --prefix=<path> |& tee config.out
...lots of output...
$ make -j 8 |& tee make.out
...lots of output...
$ make install |& tee install.out
...lots of output...
Note that there are many, many configuration options to the
``./configure`` step. Some of them may be needed for your particular
environment; see below for descriptions of the options available.
If your installation prefix path is not writable by a regular user,
you may need to use ``sudo`` or ``su`` to run the ``make install``
step. For example:
.. code-block:: sh
$ sudo make install |& tee install.out
[sudo] password for builduser: <enter your password here>
...lots of output...
Finally, note that VPATH builds are fully supported. For example:
.. code-block:: sh
$ tar xf pmix-<version>.tar.bz2
$ cd pmix-<version>
$ mkdir build
$ cd build
$ ../configure --prefix=<path> |& tee config.out
...etc.

50
macx64/mpi/openmpi/share/doc/pmix/html/_sources/release-notes.rst.txt Normal file
View File

@@ -0,0 +1,50 @@
Release Notes
=============
The following abbreviated list of release notes applies to this code
base as of this writing (10 Mar 2023):
General notes
-------------
* Systems that have been tested are:
* Linux (various flavors/distros), 64 bit (x86), with gcc, Intel,
and Portland (*)
* OS X (10.7 and above), 64 bit (x86_64), with gcc and clang (*)
* OpenPMIx has taken some steps towards Reproducible Builds
(https://reproducible-builds.org/). Specifically, OpenPMIx's
``configure`` and ``make`` process, by default, records the build date
and some system-specific information such as the hostname where OpenPMIx
was built and the username who built it. If you desire a
Reproducible Build, set the ``$SOURCE_DATE_EPOCH``, ``$USER`` and ``$HOSTNAME``
environment variables before invoking ``configure`` and ``make``, and
OpenPMIx will use those values instead of invoking ``whoami`` and/or
``hostname``, respectively. See
https://reproducible-builds.org/docs/source-date-epoch/ for
information on the expected format and content of the
``$SOURCE_DATE_EPOCH`` variable.
Compiler Notes
--------------
* The Portland Group compilers prior to version 7.0 require the
``-Msignextend`` compiler flag to extend the sign bit when converting
from a shorter to longer integer. This is is different than other
compilers (such as GNU). When compiling PMIx with the Portland
compiler suite, the following flags should be passed to PMIx's
configure script:
.. code-block:: sh
shell$ ./configure CFLAGS=-Msignextend ...
This will compile PMIx with the proper compile flags.
* Running on nodes with different endian and/or different datatype
sizes within a single parallel job is supported in this release.
However, PMIx does not resize data when datatypes differ in size
(for example, sending a 4 byte double and receiving an 8 byte
double will fail).

67
macx64/mpi/openmpi/share/doc/pmix/html/_sources/release-notes/compilers.rst.txt Normal file
View File

@@ -0,0 +1,67 @@
.. _compiler-notes-section-label:
Compiler Notes
==============
* PMIx requires a C99-capable compiler to build.
* PMIx requires a compiler that either supports C11 atomics or the GCC
``__atomic`` atomics (e.g., GCC >= v4.8.x).
* 32-bit platforms are not currently supported.
* In general, the latest versions of compilers of a given vendor's
series have the least bugs. We have seen cases where Vendor XYZ's
compiler version A.B fails to compile PMIx, but version A.C
(where C>B) works just fine. If you run into a compile failure, you
might want to double check that you have the latest bug fixes and
patches for your compiler.
* PMIx does not support the PGI compiler suite on OS X or MacOS.
See issues below for more details:
* https://github.com/open-mpi/ompi/issues/2604
* https://github.com/open-mpi/ompi/issues/2605
* At least some versions of the Intel 8.1 compiler seg fault while
compiling certain PMIx source code files. As such, it is not
supported.
* It has been reported that the Intel 9.1 and 10.0 compilers fail to
compile PMIx on IA64 platforms. As of 12 Sep 2012, there is
very little (if any) testing performed on IA64 platforms (with any
compiler). Support is "best effort" for these platforms, but it is
doubtful that any effort will be expended to fix the Intel 9.1 /
10.0 compiler issuers on this platform.
* Early versions of the Intel 12.1 Linux compiler suite on x86_64 seem
to have a bug that prevents PMIx from working. Symptoms
including immediate segv of the wrapper compiler (``pmixcc``) and
PMIx-based applications. If you upgrade to the latest
version of the Intel 12.1 Linux compiler suite, the problem will go
away.
* The Portland Group compilers prior to version 7.0 require the
``-Msignextend`` compiler flag to extend the sign bit when converting
from a shorter to longer integer. This is different than other
compilers (such as GNU). When compiling PMIx with the Portland
compiler suite, the following flags should be passed to PMIx's
``configure`` script:
.. code-block:: sh
shell$ ./configure CFLAGS=-Msignextend \
--with-wrapper-cflags=-Msignextend ...
This will both compile PMIx with the proper compile flags and
also automatically add ``-Msignextend`` when the C wrapper
compiler is used to compile user PMIx-based applications.
* It has been reported that Pathscale 5.0.5 and 6.0.527 compilers
give an internal compiler error when trying to build PMIx.
* As of July 2017, the Pathscale compiler suite apparently has no
further commercial support, and it does not look like there will be
further releases. Any issues discovered regarding building /
running PMIx with the Pathscale compiler suite therefore may not
be able to be resolved.

39
macx64/mpi/openmpi/share/doc/pmix/html/_sources/release-notes/general.rst.txt Normal file
View File

@@ -0,0 +1,39 @@
General notes
=============
The following list of release notes applies to this code base as of
this writing:
* PMIx includes support for a wide variety of supplemental
hardware and software packages. When configuring PMIx, you may
need to supply additional flags to the ``configure`` script in order
to tell PMIx where the header files, libraries, and any other
required files are located. As such, running ``configure`` by itself
may not include support for all the devices (etc.) that you expect,
especially if their support headers / libraries are installed in
non-standard locations. See the
listing of configure command-line switches, below, for more details.
* The majority of PMIx's documentation is now on the `ReadTheDocs site <http://openpmix.readthedocs.io/>`_.
The man pages are also installed by default.
* Note that PMIx documentation uses the word "component"
frequently; the word "plugin" is probably more familiar to most
users. As such, end users can probably completely substitute the
word "plugin" wherever you see "component" in our documentation.
For what it's worth, we use the word "component" for historical
reasons, mainly because it is part of our acronyms and internal API
function calls.
* PMIx has taken some steps towards `Reproducible Builds
<https://reproducible-builds.org/>`_. Specifically, PMIx's
``configure`` and ``make`` process, by default, records the build date
and some system-specific information such as the hostname where PMIx
was built and the username who built it. If you desire a
Reproducible Build, set the ``$SOURCE_DATE_EPOCH``, ``$USER`` and
``$HOSTNAME`` environment variables before invoking ``configure`` and
``make``, and PMIx will use those values instead of invoking
``whoami`` and/or ``hostname``, respectively. See
https://reproducible-builds.org/docs/source-date-epoch/ for
information on the expected format and content of the
``$SOURCE_DATE_EPOCH`` variable.

10
macx64/mpi/openmpi/share/doc/pmix/html/_sources/release-notes/index.rst.txt Normal file
View File

@@ -0,0 +1,10 @@
Release notes
=============
.. toctree::
:maxdepth: 1
general
platform
compilers
run-time

25
macx64/mpi/openmpi/share/doc/pmix/html/_sources/release-notes/platform.rst.txt Normal file
View File

@@ -0,0 +1,25 @@
.. _platform-notes-section-label:
Platform Notes
==============
* Systems that have been tested are:
* Linux (various flavors/distros), 64 bit (x86, ppc, aarch64),
with gcc (>=4.8.x+), clang (>=3.6.0), Intel,
and Portland (be sure to also see :ref:`the Compiler Notes
section <compiler-notes-section-label>`)
* macOS (10.14-10.15, 11.x, 12.x), 64 bit (x86_64 and M1) with XCode
compilers
* Other systems have been lightly (but not fully) tested:
* Cygwin 64 bit with gcc
* ARMv6, ARMv7, ARMv9
* Other 64 bit platforms.
* OpenBSD. Requires configure option``--disable-dlopen`` with this release.
* Problems have been reported when building on FreeBSD 11.1
using the clang-4.0 system compiler. A workaround is to build
PMIx using the GNU compiler.
.. note:: 32-bit environments are no longer supported.

23
macx64/mpi/openmpi/share/doc/pmix/html/_sources/release-notes/run-time.rst.txt Normal file
View File

@@ -0,0 +1,23 @@
General Run-Time Support Notes
==============================
* The PMIx installation must be in your ``PATH`` on all nodes (and
potentially ``LD_LIBRARY_PATH`` or ``DYLD_LIBRARY_PATH``, if
``libpmix`` is a shared library).
* PMIx's run-time behavior can be customized via Modular Component
Architecture (MCA) parameters (see the :ref:`MCA section <label-mca>`
for more information on how to get/set MCA parameter values).
* If specified, we recommend that the ``ptl_tcp_if_include`` parameter
include the loopback device (``lo`` on many Linux platforms) to ensure
that at least one intra-node transport can be found between a local
client and its server. For example:
``export PMIX_MCA_ptl_tcp_if_include lo,eth1 ...``
* Running on nodes with different endian and/or different datatype
sizes within a single PMIx-based application is supported in this release,
at least from a PMIx perspective (i.e., we will pack/unpack to
handle the situation). However, PMIx does not resize data when the
same datatype differs in size (for example, sending a 4 byte ``double``
and receiving an 8 byte ``double`` will fail).

58
macx64/mpi/openmpi/share/doc/pmix/html/_sources/security.rst.txt Normal file
View File

@@ -0,0 +1,58 @@
OpenPMIx Security Policy
========================
Historically, PMIx has operated as a library at the user level in relatively controlled environments (i.e., the typical high-performance computing cluster embedded in a protected network, and thus not exposed to the general Internet). This situation has changed, however, as system management stack packages and other software operating at privileged levels have begun to operate PMIx servers. Increasingly, the PMIx library finds itself in situations where its communications are between entities at different privilege levels (e.g., between root and user) and operating on head nodes with direct connection to more exposed networks.
The PMIx community takes security associated with use of its library seriously, recognizing that our ability to respond to concerns is bound by our limited access to volunteer resources. We deeply appreciate coordinated efforts done in partnership with our reporters as these have the highest probability for a successful and satisfactory resolution. Reports that simply state something is wrong while providing no assistance in triaging the problem or developing the solution will be treated seriously, but with correspondingly longer response times.
PMIx does not have formal, contractual relationships with its users. Instead, we have informal relationships with downstream packagers (e.g., Debian, Fedora, SUSE), resource managers (e.g., Slurm, PBS, PALS), and libraries (e.g., Open MPI, MPICH, OpenSHMEM, PGAS). This quite frequently takes the form of individuals as opposed to organizational contacts. Thus, it isn't possible for the PMIx community to offer any guarantees as to the breadth or immediacy of notification for security issues. We can only do our best to alert the people we know about, and hope that they spread the word as required.
Our vulnerability disclosure process reflects this situation. While we strongly encourage discoverers to report potential security issues to us and follow our process, we will respect their wishes and work with them in cases where their preferred process may vary.
NOTE: any potential security issue should be reported immediately to us at security@pmix.org
Vulnerability Disclosure Process
--------------------------------
This process covers security issues pertaining to the PMIx library itself. Issues with closely related components — such as libevent, HWLOC, MUNGE or third-party plugins — may be raised with us and we will work with the reporter to identify the appropriate contacts and coordinate disclosure.
The PMIx Vulnerability Disclosure Process consists of several distinct, but possibly overlapping steps:
1. Problem identification and initial triage.
The problem is reported to the community and a first-level triage performed. Primary focus here is on scoping the extent of the issue so it can properly be communicated (both in terms of severity and complexity to address) to the rest of the community.
2. Notification and embargo
Once the problem has been triaged, it will be communicated to the known consumers of the PMIx library (as noted above). This will be done in a private manner and all informed will be asked to maintain that privacy during the embargo period. The purpose of this step is to ensure the timely notification of the problem without alerting potential bad players as to the vulnerability, thus giving the community time to respond to the problem. The community will use this period to assemble a team to address the problem.
The embargo period is expected to continue during the entire time work is being performed towards a resolution of the problem. The PMIx community, of course, has no control over the actions of its members or users, and therefore cannot guarantee confidentiality throughout the resolution process. However, the community will request best efforts from all involved due to the shared interest.
3. Private release
Once a solution to the problem has been devised, a new release of the library will be made that includes the fix. This will first be made available to the known consumers of the library, as well as the initial reporter if not a member of that list. A reasonable amount of time will be provided (as defined by general discussion across the involved parties) for rollout to occur through the participants. The embargo on public discussion will be maintained throughout this step.
4. General release
At this point, the embargo will be lifted and a general announcement (including email to the PMIx mailing lists) of the problem and availability of the solution will be made. All users will be urged to update as quickly as possible. All vulnerable releases will be removed from the GitHub release pages, though the tags corresponding to those releases will be retained for historical purposes.
Software Authenticity and Integrity
-----------------------------------
Authenticity and integrity of PMIx software should always be confirmed by computing the checksum of the archive and comparing it with the value listed on the GitHub release page. Assuming you downloaded the file pmix-4.2.2.tar.bz2, you can run the ``sha1sum`` command like this:
.. code-block:: sh
shell$ sha1sum pmix-4.2.2.tar.bz2
Check that the output matches what is printed in the release announcement, which may look like this:
.. code-block:: sh
b4e1cb79dfd94c1b9db8eaba02f725c07ef9df2b pmix-4.2.2.tar.bz2
To avoid having to manually compare the string, you may use the ``sha1sum -c parameter`` as follows:
.. code-block:: sh
echo 'b4e1cb79dfd94c1b9db8eaba02f725c07ef9df2b pmix-4.2.2.tar.bz2'|sha1sum -c

150
macx64/mpi/openmpi/share/doc/pmix/html/_sources/versions.rst.txt Normal file
View File

@@ -0,0 +1,150 @@
.. _label-version-numbers:
Version Numbers and Binary Compatibility
========================================
OpenPMIx has two sets of version numbers that are likely of interest
to end users / system administrator:
* Software version number
* Shared library version numbers
Both are described below, followed by a discussion of application
binary interface (ABI) compatibility implications.
Software Version Number
-----------------------
OpenPMIx's version numbers are the union of several different values:
major, minor, release, and an optional quantifier.
* Major: The major number is the first integer in the version string
(e.g., v1.2.3). Changes in the major number typically indicate a
significant change in the code base and/or end-user
functionality. The major number is always included in the version
number.
* Minor: The minor number is the second integer in the version
string (e.g., v1.2.3). Changes in the minor number typically
indicate a incremental change in the code base and/or end-user
functionality. The minor number is always included in the version
number:
* Release: The release number is the third integer in the version
string (e.g., v1.2.3). Changes in the release number typically
indicate a bug fix in the code base and/or end-user
functionality.
* Quantifier: OpenPMIx version numbers sometimes have an arbitrary
string affixed to the end of the version number. Common strings
include:
* ``aX``: Indicates an alpha release. X is an integer indicating
the number of the alpha release (e.g., v1.2.3a5 indicates the
5th alpha release of version 1.2.3).
* ``bX``: Indicates a beta release. X is an integer indicating
the number of the beta release (e.g., v1.2.3b3 indicates the 3rd
beta release of version 1.2.3).
* ``rcX``: Indicates a release candidate. X is an integer
indicating the number of the release candidate (e.g., v1.2.3rc4
indicates the 4th release candidate of version 1.2.3).
Although the major, minor, and release values (and optional
quantifiers) are reported in OpenPMIx nightly snapshot tarballs, the
filenames of these snapshot tarballs follow a slightly different
convention.
Specifically, the snapshot tarball filename contains three distinct
values:
* Most recent Git tag name on the branch from which the tarball was
created.
* An integer indicating how many Git commits have occurred since
that Git tag.
* The Git hash of the tip of the branch.
For example, a snapshot tarball filename of
``pmix-v1.0.2-57-gb9f1fd9.tar.bz2`` indicates that this tarball was
created from the v1.0 branch, 57 Git commits after the ``v1.0.2`` tag,
specifically at Git hash gb9f1fd9.
OpenPMIx's Git master branch contains a single ``dev`` tag. For example,
``pmix-dev-8-gf21c349.tar.bz2`` represents a snapshot tarball created
from the master branch, 8 Git commits after the "dev" tag,
specifically at Git hash gf21c349.
The exact value of the "number of Git commits past a tag" integer is
fairly meaningless; its sole purpose is to provide an easy,
human-recognizable ordering for snapshot tarballs.
Shared Library Version Number
-----------------------------
OpenPMIx uses the GNU Libtool shared library versioning scheme.
.. note:: Only official releases of OpenPMIx adhere to this versioning
scheme. "Beta" releases, release candidates, and nightly
tarballs, developer snapshots, and Git snapshot tarballs
likely will all have arbitrary/meaningless shared library
version numbers.
The GNU Libtool official documentation details how the versioning
scheme works. The quick version is that the shared library versions
are a triple of integers: (current,revision,age), or ``c:r:a``. This
triple is not related to the PMIx software version number. There
are six simple rules for updating the values (taken almost verbatim
from the Libtool docs):
#. Start with version information of ``0:0:0`` for each shared library.
#. Update the version information only immediately before a public
release of your software. More frequent updates are unnecessary,
and only guarantee that the current interface number gets larger
faster.
#. If the library source code has changed at all since the last
update, then increment revision (``c:r:a`` becomes ``c:r+1:a``).
#. If any interfaces have been added, removed, or changed since the
last update, increment current, and set revision to 0.
#. If any interfaces have been added since the last public release,
then increment age.
#. If any interfaces have been removed since the last public release,
then set age to 0.
Application Binary Interface (ABI) Compatibility
------------------------------------------------
OpenPMIx provides forward ABI compatibility in all versions of a given
feature release series and its corresponding
super stable series. For example, on a single platform, a PMIx
application linked against OpenPMIx v1.3.2 shared libraries can be
updated to point to the shared libraries in any successive v1.3.x or
v1.4 release and still work properly (e.g., via the ``LD_LIBRARY_PATH``
environment variable or other operating system mechanism).
OpenPMIx reserves the right to break ABI compatibility at new feature
release series. For example, the same PMIx application from above
(linked against PMIx v1.3.2 shared libraries) will *not* work with
PMIx v1.5 shared libraries.
Cross-Version Compatibility
---------------------------
As PMIx adoption has grown, the problem of managing application-SMS interactions between different PMIx library versions has increased in visibility. It soon became clear that use of a common library version by both SMS and application could not be guaranteed, especially in the container-based application use-case. Thus, cross-version compatibility arose as a problem.
PMIx has addressed this by utilizing a plugin-based architecture that allows both the client and server to select from a range of supported protocol levels. The resulting coordination is based on a client-driven handshake – i.e., the client selects the protocol to be used, and the server adapts to support it. The client’s selection is based on a combination of environmental parameters passed to it at launch by the server, filtered against the protocols available to that particular client. For example, a PMIx v1.2 client only has the ``usock`` messaging transport available to it, and so would select that transport even when a PMIx v3 server offered ``usock`` and ``tcp`` options. Note that if the PMIx v3 server had not been instructed to support ``usock``, then the v1.2 client would have failed ``PMIx_Init`` with an error indicating the server was unreachable.
Although the PMIx community is committed to supporting the cross-version use-case, early releases did not fully provide the necessary capabilities. Each release branch has since been updated to include the required translation logic for communicating to other versions, but full compatibility could not be provided due to the level of changes it would introduce to what would otherwise be considered a ``stable`` release series. Thus, the following chart shows the available compatibility:
.. image:: ./images/compatibility.png
Starting with v2.1.1, all versions are fully cross-compatible – i.e., the client and server versions can be any combination of release level. Thus, a v2.1.1 client can connect to a v3.0.0 server, and vice versa.
PMIx v1.2.5 servers can only serve v1.2.x clients, but v1.2.5 clients can connect to v2.0.3, and v2.1.1 or higher servers. Similarly, v2.0.3 servers can only serve v2.0.x and v1.2.5 clients, but v2.0.3 clients can connect to v2.1.1 or higher servers.
.. note:: The cross-version guarantee only means that users of two different versions will be able to communicate requests and their responses. It does not guarantee that both sides will completely support the requests. It is possible, for example, for a server to not include support for an operation that was introduced in a newer version being used by a client. Likewise, it is possible that a bug existed in an earlier version that precludes correct completion of the request.

134
macx64/mpi/openmpi/share/doc/pmix/html/_static/_sphinx_javascript_frameworks_compat.js Normal file
View File

@@ -0,0 +1,134 @@
/*
* _sphinx_javascript_frameworks_compat.js
* ~~~~~~~~~~
*
* Compatability shim for jQuery and underscores.js.
*
* WILL BE REMOVED IN Sphinx 6.0
* xref RemovedInSphinx60Warning
*
*/
/**
* select a different prefix for underscore
*/
$u = _.noConflict();
/**
* small helper function to urldecode strings
*
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
*/
jQuery.urldecode = function(x) {
if (!x) {
return x
}
return decodeURIComponent(x.replace(/\+/g, ' '));
};
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s === 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
};
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node, addItems) {
if (node.nodeType === 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 &&
!jQuery(node.parentNode).hasClass(className) &&
!jQuery(node.parentNode).hasClass("nohighlight")) {
var span;
var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.className = className;
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
var bbox = node.parentElement.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute('class', className);
addItems.push({
"parent": node.parentNode,
"target": rect});
}
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this, addItems);
});
}
}
var addItems = [];
var result = this.each(function() {
highlight(this, addItems);
});
for (var i = 0; i < addItems.length; ++i) {
jQuery(addItems[i].parent).before(addItems[i].target);
}
return result;
};
/*
* backward compatibility for jQuery.browser
* This will be supported until firefox bug is fixed.
*/
if (!jQuery.browser) {
jQuery.uaMatch = function(ua) {
ua = ua.toLowerCase();
var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
/(webkit)[ \/]([\w.]+)/.exec(ua) ||
/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
/(msie) ([\w.]+)/.exec(ua) ||
ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
[];
return {
browser: match[ 1 ] || "",
version: match[ 2 ] || "0"
};
};
jQuery.browser = {};
jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
}

899
macx64/mpi/openmpi/share/doc/pmix/html/_static/basic.css Normal file
View File

@@ -0,0 +1,899 @@
/*
* basic.css
* ~~~~~~~~~
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
div.section::after {
display: block;
content: '';
clear: left;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
div.sphinxsidebar #searchbox form.search {
overflow: hidden;
}
div.sphinxsidebar #searchbox input[type="text"] {
float: left;
width: 80%;
padding: 0.25em;
box-sizing: border-box;
}
div.sphinxsidebar #searchbox input[type="submit"] {
float: left;
width: 20%;
border-left: none;
padding: 0.25em;
box-sizing: border-box;
}
img {
border: 0;
max-width: 100%;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li p.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
margin-left: auto;
margin-right: auto;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable ul {
margin-top: 0;
margin-bottom: 0;
list-style-type: none;
}
table.indextable > tbody > tr > td > ul {
padding-left: 0em;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- domain module index --------------------------------------------------- */
table.modindextable td {
padding: 2px;
border-collapse: collapse;
}
/* -- general body styles --------------------------------------------------- */
div.body {
min-width: 360px;
max-width: 800px;
}
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}
a.brackets:before,
span.brackets > a:before{
content: "[";
}
a.brackets:after,
span.brackets > a:after {
content: "]";
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
img.align-left, figure.align-left, .figure.align-left, object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
img.align-right, figure.align-right, .figure.align-right, object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
img.align-center, figure.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
img.align-default, figure.align-default, .figure.align-default {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left;
}
.align-center {
text-align: center;
}
.align-default {
text-align: center;
}
.align-right {
text-align: right;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar,
aside.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px;
background-color: #ffe;
width: 40%;
float: right;
clear: right;
overflow-x: auto;
}
p.sidebar-title {
font-weight: bold;
}
div.admonition, div.topic, blockquote {
clear: left;
}
/* -- topics ---------------------------------------------------------------- */
div.topic {
border: 1px solid #ccc;
padding: 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- content of sidebars/topics/admonitions -------------------------------- */
div.sidebar > :last-child,
aside.sidebar > :last-child,
div.topic > :last-child,
div.admonition > :last-child {
margin-bottom: 0;
}
div.sidebar::after,
aside.sidebar::after,
div.topic::after,
div.admonition::after,
blockquote::after {
display: block;
content: '';
clear: both;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
margin-top: 10px;
margin-bottom: 10px;
border: 0;
border-collapse: collapse;
}
table.align-center {
margin-left: auto;
margin-right: auto;
}
table.align-default {
margin-left: auto;
margin-right: auto;
}
table caption span.caption-number {
font-style: italic;
}
table caption span.caption-text {
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 5px;
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom: 1px solid #aaa;
}
th {
text-align: left;
padding-right: 5px;
}
table.citation {
border-left: solid 1px gray;
margin-left: 1px;
}
table.citation td {
border-bottom: none;
}
th > :first-child,
td > :first-child {
margin-top: 0px;
}
th > :last-child,
td > :last-child {
margin-bottom: 0px;
}
/* -- figures --------------------------------------------------------------- */
div.figure, figure {
margin: 0.5em;
padding: 0.5em;
}
div.figure p.caption, figcaption {
padding: 0.3em;
}
div.figure p.caption span.caption-number,
figcaption span.caption-number {
font-style: italic;
}
div.figure p.caption span.caption-text,
figcaption span.caption-text {
}
/* -- field list styles ----------------------------------------------------- */
table.field-list td, table.field-list th {
border: 0 !important;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.field-name {
-moz-hyphens: manual;
-ms-hyphens: manual;
-webkit-hyphens: manual;
hyphens: manual;
}
/* -- hlist styles ---------------------------------------------------------- */
table.hlist {
margin: 1em 0;
}
table.hlist td {
vertical-align: top;
}
/* -- object description styles --------------------------------------------- */
.sig {
font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
}
.sig-name, code.descname {
background-color: transparent;
font-weight: bold;
}
.sig-name {
font-size: 1.1em;
}
code.descname {
font-size: 1.2em;
}
.sig-prename, code.descclassname {
background-color: transparent;
}
.optional {
font-size: 1.3em;
}
.sig-paren {
font-size: larger;
}
.sig-param.n {
font-style: italic;
}
/* C++ specific styling */
.sig-inline.c-texpr,
.sig-inline.cpp-texpr {
font-family: unset;
}
.sig.c .k, .sig.c .kt,
.sig.cpp .k, .sig.cpp .kt {
color: #0033B3;
}
.sig.c .m,
.sig.cpp .m {
color: #1750EB;
}
.sig.c .s, .sig.c .sc,
.sig.cpp .s, .sig.cpp .sc {
color: #067D17;
}
/* -- other body styles ----------------------------------------------------- */
ol.arabic {
list-style: decimal;
}
ol.loweralpha {
list-style: lower-alpha;
}
ol.upperalpha {
list-style: upper-alpha;
}
ol.lowerroman {
list-style: lower-roman;
}
ol.upperroman {
list-style: upper-roman;
}
:not(li) > ol > li:first-child > :first-child,
:not(li) > ul > li:first-child > :first-child {
margin-top: 0px;
}
:not(li) > ol > li:last-child > :last-child,
:not(li) > ul > li:last-child > :last-child {
margin-bottom: 0px;
}
ol.simple ol p,
ol.simple ul p,
ul.simple ol p,
ul.simple ul p {
margin-top: 0;
}
ol.simple > li:not(:first-child) > p,
ul.simple > li:not(:first-child) > p {
margin-top: 0;
}
ol.simple p,
ul.simple p {
margin-bottom: 0;
}
dl.footnote > dt,
dl.citation > dt {
float: left;
margin-right: 0.5em;
}
dl.footnote > dd,
dl.citation > dd {
margin-bottom: 0em;
}
dl.footnote > dd:after,
dl.citation > dd:after {
content: "";
clear: both;
}
dl.field-list {
display: grid;
grid-template-columns: fit-content(30%) auto;
}
dl.field-list > dt {
font-weight: bold;
word-break: break-word;
padding-left: 0.5em;
padding-right: 5px;
}
dl.field-list > dt:after {
content: ":";
}
dl.field-list > dd {
padding-left: 0.5em;
margin-top: 0em;
margin-left: 0em;
margin-bottom: 0em;
}
dl {
margin-bottom: 15px;
}
dd > :first-child {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
dl > dd:last-child,
dl > dd:last-child > :last-child {
margin-bottom: 0;
}
dt:target, span.highlighted {
background-color: #fbe54e;
}
rect.highlighted {
fill: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.versionmodified {
font-style: italic;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa;
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
.guilabel, .menuselection {
font-family: sans-serif;
}
.accelerator {
text-decoration: underline;
}
.classifier {
font-style: oblique;
}
.classifier:before {
font-style: normal;
margin: 0 0.5em;
content: ":";
display: inline-block;
}
abbr, acronym {
border-bottom: dotted 1px;
cursor: help;
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
overflow-y: hidden; /* fixes display issues on Chrome browsers */
}
pre, div[class*="highlight-"] {
clear: both;
}
span.pre {
-moz-hyphens: none;
-ms-hyphens: none;
-webkit-hyphens: none;
hyphens: none;
white-space: nowrap;
}
div[class*="highlight-"] {
margin: 1em 0;
}
td.linenos pre {
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
display: block;
}
table.highlighttable tbody {
display: block;
}
table.highlighttable tr {
display: flex;
}
table.highlighttable td {
margin: 0;
padding: 0;
}
table.highlighttable td.linenos {
padding-right: 0.5em;
}
table.highlighttable td.code {
flex: 1;
overflow: hidden;
}
.highlight .hll {
display: block;
}
div.highlight pre,
table.highlighttable pre {
margin: 0;
}
div.code-block-caption + div {
margin-top: 0;
}
div.code-block-caption {
margin-top: 1em;
padding: 2px 5px;
font-size: small;
}
div.code-block-caption code {
background-color: transparent;
}
table.highlighttable td.linenos,
span.linenos,
div.highlight span.gp { /* gp: Generic.Prompt */
user-select: none;
-webkit-user-select: text; /* Safari fallback only */
-webkit-user-select: none; /* Chrome/Safari */
-moz-user-select: none; /* Firefox */
-ms-user-select: none; /* IE10+ */
}
div.code-block-caption span.caption-number {
padding: 0.1em 0.3em;
font-style: italic;
}
div.code-block-caption span.caption-text {
}
div.literal-block-wrapper {
margin: 1em 0;
}
code.xref, a code {
background-color: transparent;
font-weight: bold;
}
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
background-color: transparent;
}
.viewcode-link {
float: right;
}
.viewcode-back {
float: right;
font-family: sans-serif;
}
div.viewcode-block:target {
margin: -1px -10px;
padding: 0 10px;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
span.eqno a.headerlink {
position: absolute;
z-index: 1;
}
div.math:hover a.headerlink {
visibility: visible;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}

1
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/badge_only.css Normal file
View File

@@ -0,0 +1 @@
.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/Roboto-Slab-Bold.woff Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/Roboto-Slab-Bold.woff2 Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/Roboto-Slab-Regular.woff Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/Roboto-Slab-Regular.woff2 Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/fontawesome-webfont.eot Normal file
View File

Binary file not shown.

2671
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/fontawesome-webfont.svg Normal file
View File

File diff suppressed because it is too large Load Diff
Side by Side

After

Width:  |  Height:  |  Size: 434 KiB

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/fontawesome-webfont.ttf Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/fontawesome-webfont.woff Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/fontawesome-webfont.woff2 Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-bold-italic.woff Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-bold-italic.woff2 Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-bold.woff Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-bold.woff2 Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-normal-italic.woff Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-normal-italic.woff2 Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-normal.woff Normal file
View File

Binary file not shown.

BIN
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/fonts/lato-normal.woff2 Normal file
View File

Binary file not shown.

4
macx64/mpi/openmpi/share/doc/pmix/html/_static/css/theme.css Normal file
View File

File diff suppressed because one or more lines are too long

156
macx64/mpi/openmpi/share/doc/pmix/html/_static/doctools.js Normal file
View File

@@ -0,0 +1,156 @@
/*
* doctools.js
* ~~~~~~~~~~~
*
* Base JavaScript utilities for all Sphinx HTML documentation.
*
* :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
"use strict";
const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
"TEXTAREA",
"INPUT",
"SELECT",
"BUTTON",
]);
const _ready = (callback) => {
if (document.readyState !== "loading") {
callback();
} else {
document.addEventListener("DOMContentLoaded", callback);
}
};
/**
* Small JavaScript module for the documentation.
*/
const Documentation = {
init: () => {
Documentation.initDomainIndexTable();
Documentation.initOnKeyListeners();
},
/**
* i18n support
*/
TRANSLATIONS: {},
PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
LOCALE: "unknown",
// gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext)
gettext: (string) => {
const translated = Documentation.TRANSLATIONS[string];
switch (typeof translated) {
case "undefined":
return string; // no translation
case "string":
return translated; // translation exists
default:
return translated[0]; // (singular, plural) translation tuple exists
}
},
ngettext: (singular, plural, n) => {
const translated = Documentation.TRANSLATIONS[singular];
if (typeof translated !== "undefined")
return translated[Documentation.PLURAL_EXPR(n)];
return n === 1 ? singular : plural;
},
addTranslations: (catalog) => {
Object.assign(Documentation.TRANSLATIONS, catalog.messages);
Documentation.PLURAL_EXPR = new Function(
"n",
`return (${catalog.plural_expr})`
);
Documentation.LOCALE = catalog.locale;
},
/**
* helper function to focus on search bar
*/
focusSearchBar: () => {
document.querySelectorAll("input[name=q]")[0]?.focus();
},
/**
* Initialise the domain index toggle buttons
*/
initDomainIndexTable: () => {
const toggler = (el) => {
const idNumber = el.id.substr(7);
const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
if (el.src.substr(-9) === "minus.png") {
el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
toggledRows.forEach((el) => (el.style.display = "none"));
} else {
el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
toggledRows.forEach((el) => (el.style.display = ""));
}
};
const togglerElements = document.querySelectorAll("img.toggler");
togglerElements.forEach((el) =>
el.addEventListener("click", (event) => toggler(event.currentTarget))
);
togglerElements.forEach((el) => (el.style.display = ""));
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
},
initOnKeyListeners: () => {
// only install a listener if it is really needed
if (
!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
)
return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
// bail with special keys
if (event.altKey || event.ctrlKey || event.metaKey) return;
if (!event.shiftKey) {
switch (event.key) {
case "ArrowLeft":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const prevLink = document.querySelector('link[rel="prev"]');
if (prevLink && prevLink.href) {
window.location.href = prevLink.href;
event.preventDefault();
}
break;
case "ArrowRight":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const nextLink = document.querySelector('link[rel="next"]');
if (nextLink && nextLink.href) {
window.location.href = nextLink.href;
event.preventDefault();
}
break;
}
}
// some keyboard layouts may need Shift to get /
switch (event.key) {
case "/":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.focusSearchBar();
event.preventDefault();
}
});
},
};
// quick alias for translations
const _ = Documentation.gettext;
_ready(Documentation.init);

14
macx64/mpi/openmpi/share/doc/pmix/html/_static/documentation_options.js Normal file
View File

@@ -0,0 +1,14 @@
var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '5.0.5',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',
FILE_SUFFIX: '.html',
LINK_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
NAVIGATION_WITH_KEYS: false,
SHOW_SEARCH_SUMMARY: true,
ENABLE_SEARCH_SHORTCUTS: true,
};

Some files were not shown because too many files have changed in this diff Show More