Upgrade macos
This commit is contained in:
Bassem Girgis
@@ -0,0 +1,128 @@
|
||||
PRRTE DVM Configuration
|
||||
=======================
|
||||
|
||||
The PMIx Reference RunTime Environment (PRRTE) can be instantiated
|
||||
as a Distributed Virtual Machine (DVM) in two ways. First, the
|
||||
``prte`` command can be executed at a shell prompt. This will discover
|
||||
the available resources (either from hostfile or as allocated by a
|
||||
resource manager) and start a PRRTE shepherd daemon (:ref:`prted(1)
|
||||
<man1-prted>`) on each of the indicated nodes.
|
||||
|
||||
The other method, however, is to bootstrap the DVM at time of cluster
|
||||
startup. Bootstrapping PRRTE allows the DVM to serve as the system-level
|
||||
runtime, providing a full-service PMIx environment to sessions under
|
||||
its purview. Integration to an appropriately enabled scheduler can
|
||||
provide a full workload managed environment for users.
|
||||
|
||||
Establishing the DVM using the bootstrap method requires that a PRRTE
|
||||
configuration file be created and made available on every node of the
|
||||
cluster at node startup. The configuration file provides necessary
|
||||
information for establishing the communication infrastructure between
|
||||
the DVM controller and the compute node daemons. It also provides a
|
||||
means for easily defining DVM behavior for options such as logging,
|
||||
system-level prolog and epilog scripts for each session, and other
|
||||
PRRTE features.
|
||||
|
||||
The configuration file can be manually created or can be created using
|
||||
the `PRRTE configuration tool <configurator.html>`_.
|
||||
Manual creation can best be done
|
||||
by editing the example configuration file (``<source-location>/src/etc/prte.conf``).
|
||||
This file contains all the supported configuration options, with all
|
||||
entries commented out. Simply uncomment the options of interest and
|
||||
set them to appropriate values. The file will be installed into the
|
||||
final ``<install-location>/etc`` when ``make install`` is performed.
|
||||
|
||||
Configuration Options
|
||||
---------------------
|
||||
|
||||
The following options are supported by PRRTE |prte_ver|.
|
||||
While we make every effort to maintain compatibility with prior versions,
|
||||
we recommend that you check options when installing new versions to
|
||||
see what may have changed and/or been added. We also recommend that
|
||||
you use the `PRRTE DVM configurator <configurator.html>`_ for the
|
||||
version you are using to ensure that it is fully compatible.
|
||||
|
||||
Bootstrap Options
|
||||
^^^^^^^^^^^^^^^^^
|
||||
``ClusterName=<string> (default: "cluster")`` is the name of the cluster upon
|
||||
which the DVM is executing. This is used by PRRTE to form the namespace
|
||||
for the DVM daemons, which is taken as ``<clustername>-prte-dvm``.
|
||||
Using different names for each of your clusters is important if you use a single
|
||||
database to record information from multiple PRRTE-managed clusters.
|
||||
|
||||
``DVMControllerHost=<hostname>`` is the host upon which the DVM controller
|
||||
will be executing. The ``prted`` that finds itself booting onto this host
|
||||
will declare itself to be the system controller and will initialize itself
|
||||
accordingly.
|
||||
|
||||
``DVMControllerPort=<number> (default: 7817)`` is the TCP port upon which the
|
||||
DVM controller will be listening for connections from its ``prted`` daemons
|
||||
on the remaining system nodes.
|
||||
|
||||
``PRTEDPort=<number (default: 7818)`` is the TCP port upon which each
|
||||
``prted`` daemon will be listening for connections from its peer daemons
|
||||
on the other system nodes.
|
||||
|
||||
``DVMNodes=<regex of DVM nodes> (default: none)`` provides a regular expression
|
||||
identifying the nodes that upon which user applications can run. IP addresses can
|
||||
be provided in place of hostnames if desired.The regular expression can consist of
|
||||
a simple comma-delimited list of hostnames, or a comma-delimited list of hostname
|
||||
ranges (e.g., "linux0,linux[2-10]"), or a PMIx "native" regular expression.
|
||||
|
||||
|
||||
Operational Options
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
``DVMTempDir=<path> (default: /tmp)`` is the temporary directory that the
|
||||
DVM daemons and controller are to use as the base for their session directories.
|
||||
Working files/directories for the DVM will be placed under this location.
|
||||
|
||||
``SessionTmpDir=<path> (default: DVMTempDir)`` is the temporary directory that
|
||||
the DVM daemons are to use as the base for session directories for all
|
||||
application sessions. Working files for each session will be placed under
|
||||
this location, separated out into a directory for each session.
|
||||
|
||||
Logging Options
|
||||
^^^^^^^^^^^^^^^
|
||||
``ControllerLogJobState=<true|false> (default: false)`` directs the DVM
|
||||
controller to log each DVM-launched job state transition. Log entry includes
|
||||
the namespace of the job, the state to which it is transitioning, and the
|
||||
date/time stamp when the transition was ordered.
|
||||
|
||||
``ControllerLogProcState=<true|false> (default: false)`` directs the DVM
|
||||
controller to log each process (in a DVM-launched job) state transition.
|
||||
Log entry includes the namespace and rank of the process, the state to
|
||||
which it is transitioning, and the date/time stamp when the transition was
|
||||
ordered.
|
||||
|
||||
``ControllerLogPath=<path> (default: DVMTempDir)`` is the path to where the logs are to
|
||||
be written. If a relative path is provided,
|
||||
then the directory will be created under the ``DVMTempDir`` location. The
|
||||
path defaults to the specified SessionTmpDir in the absence of any input
|
||||
to this field. The log filename is formatted as ``prtectrlr-<hostname>-log<``.
|
||||
|
||||
``PRTEDLogJobState=<true|false> (default: false)`` directs each ``prted``
|
||||
in the DVM to log each DVM-launched job state transition. Log entry includes
|
||||
the namespace of the job, the state to which it is transitioning, and the
|
||||
date/time stamp when the transition was ordered.
|
||||
|
||||
``PRTEDLogProcState=<true|false> (default: false)`` directs each ``prted``
|
||||
in the DVM to log each process (in a DVM-launched job) state transition.
|
||||
Log entry includes the namespace and rank of the process, the state to
|
||||
which it is transitioning, and the date/time stamp when the transition was
|
||||
ordered.
|
||||
|
||||
``PRRTEDLogPath=<path> (default: DVMTempDir)`` is the path to where the logs are to
|
||||
be written. If a relative path is provided,
|
||||
then the directory will be created under the ``DVMTempDir`` location. The
|
||||
path defaults to the specified SessionTmpDir in the absence of any input
|
||||
to this field. The log filename is formatted as ``prted-<hostname>-log<``.
|
||||
|
||||
|
||||
Configurator Tool
|
||||
-----------------
|
||||
|
||||
The `PRRTE configuration tool <configurator.html>`_ contains all the supported options in an
|
||||
easy-to-use form. Once you have filled out the desired entries, the
|
||||
"submit" button will show the resulting configuration file on the
|
||||
browser window |mdash| a simple "copy/paste" operation into your target
|
||||
configuration file will yield the final result.
|
||||
@@ -0,0 +1,79 @@
|
||||
Contributing to PRRTE
|
||||
=====================
|
||||
|
||||
Open source contributions
|
||||
-------------------------
|
||||
|
||||
All code contributions are submitted as pull requests on the `PRRTE
|
||||
GitHub repository <https://github.com/openpmix/prrte/>`_.
|
||||
|
||||
.. important:: All commits must include a ``Signed-off-by:`` line,
|
||||
indicating the submitter's agreement to the :ref:`PRRTE
|
||||
Contributor's Declaration
|
||||
<contributing-contributors-declaration-label>`.
|
||||
|
||||
.. _contributing-contributors-declaration-label:
|
||||
|
||||
Contributor's Declaration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In order to ensure that we can keep distributing PRRTE 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 PRRTE. This means being able to ensure that all code
|
||||
included in PRRTE is free, open source, and able to be distributed
|
||||
under :doc:`the BSD license </license>`.
|
||||
|
||||
PRRTE 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 PRRTE 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:`PRRTE 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:`PRRTE 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 PRRTE 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 PRRTE code base and then someone later
|
||||
claims that we owe them money for it. PRRTE 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.
|
||||
@@ -0,0 +1,59 @@
|
||||
GitHub, Git, and related topics
|
||||
===============================
|
||||
|
||||
GitHub
|
||||
------
|
||||
|
||||
PRRTE's Git repositories are `hosted at GitHub
|
||||
<https://github.com/openpmix/prrte>`_.
|
||||
|
||||
#. 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.
|
||||
#. `prrte <https://github.com/openpmix/prrte/>`_ is the main PRRTE
|
||||
repository where most active development is done. Git clone this
|
||||
repository. Note that the use of the ``--recursive`` CLI option is
|
||||
necessary because PRRTE uses Git submodules::
|
||||
|
||||
shell$ git clone --recursive https://github.com/openpmix/prrte.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 PRRTE
|
||||
repository must include a ``Signed-off-by:`` line, indicating the
|
||||
submitter's agreement to the :ref:`PRRTE 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, PRRTE has two types of branches in its Git repository:
|
||||
|
||||
#. ``main``:
|
||||
|
||||
* All active development occurs on the ``main`` 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 PRRTE vMAJOR.MINOR series.
|
||||
* Periodically, the PRRTE community will make a new release
|
||||
branch, typically from ``main``.
|
||||
* A Git tag of the form ``vMAJOR.MINOR.RELEASE`` is used to
|
||||
indicate the specific commit on a release branch from where
|
||||
official PRRTE release tarball was created (e.g., ``v4.1.0``,
|
||||
``v4.1.1``, ``v4.1.2``, etc.).
|
||||
@@ -0,0 +1,319 @@
|
||||
.. _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 PRRTE from a Git clone. End
|
||||
users installing an PRRTE 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 PRRTE
|
||||
from its repository sources (users who download PRRTE tarballs do
|
||||
not need these tools - they are only required for developers working
|
||||
on the internals of PRRTE itself):
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Software package
|
||||
- Notes
|
||||
- URL
|
||||
|
||||
* - GNU m4
|
||||
- See version chart below
|
||||
- https://ftp.gnu.org/gnu/m4/
|
||||
* - GNU Autoconf
|
||||
- See version chart below
|
||||
- https://ftp.gnu.org/gnu/autoconf/
|
||||
* - GNU Automake
|
||||
- See version chart below
|
||||
- https://ftp.gnu.org/gnu/automake/
|
||||
* - GNU Libtool
|
||||
- See version chart below
|
||||
- https://ftp.gnu.org/gnu/libtool/
|
||||
|
||||
The table below lists the versions that are used to make nightly
|
||||
snapshot and official release PRRTE 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 the above point: the core PRRTE developers typically
|
||||
use very, very recent versions of the GNU tools. There are known bugs
|
||||
in older versions of the GNU tools that PRRTE 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 below. This is because such older versions still make
|
||||
usable PRRTE 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 below (but are
|
||||
recent enough to produce a working version for their platform).
|
||||
|
||||
To be clear: the versions listed below are required to support a wide
|
||||
variety of platforms and environments, and are used to make nightly
|
||||
and official release tarballs. When building PRRTE, YMMV when using
|
||||
versions older than those listed below |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 below.
|
||||
|
||||
.. note:: You may need to scroll right in the following table.
|
||||
|
||||
.. admonition:: PRRTE Docs TODO
|
||||
:class: error
|
||||
|
||||
The table below is almost certainly wrong; it has all the values
|
||||
from Open MPI. Need to update the table below with the appropriate
|
||||
values for PRRTE.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - PRRTE
|
||||
- M4
|
||||
- Autoconf
|
||||
- Automake
|
||||
- Libtool
|
||||
- Flex
|
||||
- Sphinx
|
||||
|
||||
* - v1.0.x
|
||||
- NA
|
||||
- 2.58 - 2.59
|
||||
- 1.7 - 1.9.6
|
||||
- 1.5.16 - 1.5.22
|
||||
- 2.5.4
|
||||
- NA
|
||||
* - v1.1.x
|
||||
- NA
|
||||
- 2.59
|
||||
- 1.9.6
|
||||
- 1.5.16 - 1.5.22
|
||||
- 2.5.4
|
||||
- NA
|
||||
* - v1.2.x
|
||||
- NA
|
||||
- 2.59
|
||||
- 1.9.6
|
||||
- 1.5.22 - 2.1a
|
||||
- 2.5.4
|
||||
- NA
|
||||
* - v1.3.x
|
||||
- 1.4.11
|
||||
- 2.63
|
||||
- 1.10.1
|
||||
- 2.2.6b
|
||||
- 2.5.4
|
||||
- NA
|
||||
* - v1.4.x
|
||||
- 1.4.11
|
||||
- 2.63
|
||||
- 1.10.3
|
||||
- 2.2.6b
|
||||
- 2.5.4
|
||||
- NA
|
||||
* - v1.5.x for x=0-4
|
||||
- 1.4.13
|
||||
- 2.65
|
||||
- 1.11.1
|
||||
- 2.2.6b
|
||||
- 2.5.4
|
||||
- NA
|
||||
* - v1.5.x for x>=5
|
||||
- 1.4.16
|
||||
- 2.68
|
||||
- 1.11.3
|
||||
- 2.4.2
|
||||
- 2.5.35
|
||||
- NA
|
||||
* - v1.6.x
|
||||
- 1.4.16
|
||||
- 2.68
|
||||
- 1.11.3
|
||||
- 2.4.2
|
||||
- 2.5.35
|
||||
- NA
|
||||
* - v1.7.x
|
||||
- 1.4.16
|
||||
- 2.69
|
||||
- 1.12.2
|
||||
- 2.4.2
|
||||
- 2.5.35
|
||||
- NA
|
||||
* - v1.8.x
|
||||
- 1.4.16
|
||||
- 2.69
|
||||
- 1.12.2
|
||||
- 2.4.2
|
||||
- 2.5.35
|
||||
- NA
|
||||
* - v1.10.x
|
||||
- 1.4.16
|
||||
- 2.69
|
||||
- 1.12.2
|
||||
- 2.4.2
|
||||
- 2.5.35
|
||||
- NA
|
||||
* - v2.0.x through v4.y
|
||||
- 1.4.17
|
||||
- 2.69
|
||||
- 1.15
|
||||
- 2.4.6
|
||||
- 2.5.35
|
||||
- NA
|
||||
* - v5.0.x
|
||||
- 1.4.17
|
||||
- 2.69
|
||||
- 1.15
|
||||
- 2.4.6
|
||||
- 2.5.35
|
||||
- 4.2.0
|
||||
* - Git main
|
||||
- 1.4.17
|
||||
- 2.69
|
||||
- 1.15
|
||||
- 2.4.6
|
||||
- 2.5.35
|
||||
- 4.2.0
|
||||
|
||||
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 PRRTE 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
|
||||
@@ -0,0 +1,18 @@
|
||||
Developer's guide
|
||||
=================
|
||||
|
||||
This section is here for those who are building/exploring the
|
||||
internals of PRRTE in its source code form, most likely through a
|
||||
developer's tree (i.e., a Git clone).
|
||||
|
||||
If you are simply *using* PRRTE, you probably don't need to read this
|
||||
section.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
prerequisites.rst
|
||||
git-github
|
||||
gnu-autotools
|
||||
sphinx
|
||||
rst-for-markdown-expats.rst
|
||||
@@ -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 PRRTE 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 PRRTE
|
||||
from distribution tarballs. PRRTE 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
|
||||
----
|
||||
|
||||
PRRTE 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 PRRTE'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 PRRTE, we
|
||||
greatly prefer the latter.
|
||||
|
||||
Note that no testing has been performed to see what the minimum
|
||||
version of Flex is required by PRRTE. We suggest that you use
|
||||
v2.5.35 at the earliest.
|
||||
|
||||
For now, PRRTE 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 PRRTE 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 PRRTE 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 PRRTE's
|
||||
Git repository; only the ReStructred Text source code of the
|
||||
documentation is in the Git repository. Hence, if you are building
|
||||
PRRTE 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 PRRTE 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.**
|
||||
@@ -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 PRRTE 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 prte-<version>.tar.bz2
|
||||
shell$ cd prte-<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 prte-<version>.tar.bz2
|
||||
shell$ cd prte-<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 PRRTE git tree.
|
||||
|
||||
Macros
|
||||
------
|
||||
|
||||
* MD: There are no macros in Markdown.
|
||||
* RST: We have defined a few PRRTE-specific macros in RST. You can
|
||||
insert these macros anywhere in RST content text.
|
||||
|
||||
* ``|ompi_ver|`` is the full PRRTE version number, including
|
||||
alpha/beta/rc/greek denotation. For example ``5.0.0rc1``.
|
||||
|
||||
* ``|ompi_series|`` is the major/minor PRRTE version, e.g.,
|
||||
``5.0.x``.
|
||||
|
||||
.. important:: Think twice about hard-coding the PRRTE 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.
|
||||
@@ -0,0 +1,236 @@
|
||||
.. _developers-installing-sphinx-label:
|
||||
|
||||
Installing and running Sphinx (building the PRRTE docs)
|
||||
=======================================================
|
||||
|
||||
As with all content in the Developer's Guide, this section is only
|
||||
relevant for developers who work in the PRRTE code base itself.
|
||||
End users who install a binary PRRTE package or build from an
|
||||
official PRRTE 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 PRRTE 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 PRRTE
|
||||
Git clone directory:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Create the Python virtual environment
|
||||
shell$ cd TOP_OF_PRRTE_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_PRRTE_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 PRRTE 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_PRRTE_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 PRRTE 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
|
||||
--------------
|
||||
|
||||
PRRTE'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 PRRTE 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 PRRTE distribution tarballs. Meaning: if you
|
||||
download an official distribution PRRTE 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 PRRTE docs. End users do *not* need to have Sphinx
|
||||
available to build PRRTE 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 PRRTE (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 ./prterun.1
|
||||
|
||||
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/prte/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/prte/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 prterun
|
||||
@@ -0,0 +1,9 @@
|
||||
Getting help
|
||||
============
|
||||
|
||||
The best way to report bugs, send comments, or ask questions is to
|
||||
post them on the `PRRTE GitHub issue tracker
|
||||
<https://github.com/openpmix/prrte/issues>`_.
|
||||
|
||||
When submitting questions and problems, be sure to include as much
|
||||
extra information as possible.
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-hosts-cli.rst
|
||||
@@ -0,0 +1,4 @@
|
||||
Hostfiles
|
||||
=========
|
||||
|
||||
.. include:: /prrte-rst-content/detail-hostfiles.rst
|
||||
@@ -0,0 +1,19 @@
|
||||
Host specification
|
||||
==================
|
||||
|
||||
PRRTE identifies hosts on which to launch processes by:
|
||||
|
||||
#. A Resource Manager (RM) telling PRRTE which hosts to use
|
||||
#. The user providing a hostfile (also sometimes called a "machine
|
||||
file")
|
||||
#. The user providing a list of hosts on the command line
|
||||
|
||||
The sections below describe each of these in more detail.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
rm
|
||||
hostfiles
|
||||
cli
|
||||
relative-indexing
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-hosts-relative-indexing.rst
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-hosts-rm.rst
|
||||
@@ -0,0 +1,12 @@
|
||||
How Things Work
|
||||
===============
|
||||
|
||||
This section explains how some of the functions inside
|
||||
PRRTE perform their job. If you have questions about, for
|
||||
example, how session directory trees work, then you will
|
||||
find information on that subject here.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
session_dirs.rst
|
||||
@@ -0,0 +1,115 @@
|
||||
.. _session-dir-detail-label:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
PMIx Reference Runtime Environment (PRRTE) |prte_ver|
|
||||
=====================================================
|
||||
|
||||
The project is formally referred to in documentation by "PRRTE", and
|
||||
the GitHub repository is ``prrte``.
|
||||
|
||||
.. note:: We have found that most users do not like typing the two
|
||||
consecutive ``r`` letters in the name. Hence, all of the
|
||||
internal API symbols, environment variables, MCA frameworks,
|
||||
and CLI executables all use the abbreviated ``prte`` (one
|
||||
``r``, not two) for convenience.
|
||||
|
||||
Documentation locations
|
||||
=======================
|
||||
|
||||
This documentation can be found in the following locations:
|
||||
|
||||
* On the web: https://docs.prrte.org/
|
||||
* In the tarball: ``docs/_build/html/index.html``
|
||||
* Installed: ``$prefix/share/doc/prrte/html/index.html``
|
||||
|
||||
Table of contents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
quickstart
|
||||
release-notes
|
||||
getting-help
|
||||
install
|
||||
configuration
|
||||
how-things-work/index
|
||||
hosts/index
|
||||
placement/index
|
||||
notifications
|
||||
session-directory
|
||||
developers/index
|
||||
contributing
|
||||
license
|
||||
man/index
|
||||
versions
|
||||
news/index
|
||||
@@ -0,0 +1,92 @@
|
||||
Installing PRRTE
|
||||
================
|
||||
|
||||
For More Information
|
||||
--------------------
|
||||
|
||||
This file is a *very* short overview of building and installing the
|
||||
PMIx Reference RunTime Environment (PRRTE). More information is
|
||||
available `in the FAQ section on the PRRTE web site
|
||||
<https://github.com/openpmix/prrte>`_.
|
||||
|
||||
Minimum PMIx version
|
||||
--------------------
|
||||
|
||||
The ``configure`` script in PRRTE |prte_ver| must be able to find an
|
||||
OpenPMIx installation that is |pmix_min_version| or higher. If
|
||||
``configure`` cannot find a suitable OpenPMIx version, it will abort
|
||||
with an error.
|
||||
|
||||
If OpenPMIx cannot be found in default preprocessor and linker search
|
||||
paths, you can specify the ``--with-pmix=DIR`` CLI option to tell
|
||||
``configure`` where to find it.
|
||||
|
||||
|
||||
Developer Builds
|
||||
----------------
|
||||
|
||||
If you have checked out a DEVELOPER'S COPY of PRRTE (i.e., you checked
|
||||
out from Git), you should read the :doc:`Developer's Guide
|
||||
</developers/index>` section before attempting to build PRRTE. You
|
||||
must then run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
shell$ ./autogen.pl
|
||||
|
||||
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 PRRTE typically include a large
|
||||
performance penalty at run-time because of extra debugging
|
||||
overhead.
|
||||
|
||||
|
||||
User Builds
|
||||
-----------
|
||||
|
||||
Building PRRTE is typically a combination of running ``configure``
|
||||
and ``make``. Execute the following commands to install the PRRTE
|
||||
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
|
||||
|
||||
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``. Note that
|
||||
VPATH builds are fully supported. For example:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
shell$ tar xf prrte-X.Y.Z.tar.gz
|
||||
shell$ cd prrte-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.
|
||||
@@ -0,0 +1,5 @@
|
||||
License
|
||||
=========
|
||||
|
||||
.. literalinclude:: ../LICENSE
|
||||
:language: text
|
||||
@@ -0,0 +1,21 @@
|
||||
PRRTE manual pages
|
||||
==================
|
||||
|
||||
All of the content in this section is also installed as individual
|
||||
manual ("man") pages in a PRRTE installation. If your man page search
|
||||
path includes the location where PRRTE 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 prterun
|
||||
|
||||
PRRTE man pages, by section:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
man1/index
|
||||
man5/index
|
||||
@@ -0,0 +1,12 @@
|
||||
Commands (section 1)
|
||||
====================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
prte.1.rst
|
||||
prte_info.1.rst
|
||||
prted.1.rst
|
||||
prterun.1.rst
|
||||
prun.1.rst
|
||||
pterm.1.rst
|
||||
@@ -0,0 +1,29 @@
|
||||
.. _man1-prte:
|
||||
|
||||
prte
|
||||
====
|
||||
|
||||
prte |mdash| instantiate an instance of PRRTE DVM
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
.. code:: sh
|
||||
|
||||
shell$ prte ...options...
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
``prte`` instantiates an instance of the PMIx Reference Run Time
|
||||
Environment (PRRTE) distributed virtual machine (DVM).
|
||||
|
||||
Extensive help documentation for this command is provided through
|
||||
``prte --help [topic]``.
|
||||
|
||||
At least for now, that content is not available in man page form.
|
||||
Pull requests to add all the content (via repeatable infrastructure)
|
||||
would be greatly appreciated.
|
||||
|
||||
.. seealso::
|
||||
:ref:`prterun(1) <man1-prterun>`
|
||||
@@ -0,0 +1,29 @@
|
||||
.. _man1-prte_info:
|
||||
|
||||
prte_info
|
||||
=========
|
||||
|
||||
prte_info |mdash| Provide detailed information on your PRRTE installation
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
.. code:: sh
|
||||
|
||||
prte_info ...options...
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
``prte_info`` provide detailed information on your PMIx Reference Run
|
||||
Time (PRRTE) installation.
|
||||
|
||||
Extensive help documentation for this command is provided through
|
||||
``prte_info --help [topic]``.
|
||||
|
||||
At least for now, that content is not available in man page form.
|
||||
Pull requests to add all the content (via repeatable infrastructure)
|
||||
would be greatly appreciated.
|
||||
|
||||
.. seealso::
|
||||
:ref:`prte(1) <man1-prte>`
|
||||
@@ -0,0 +1,29 @@
|
||||
.. _man1-prted:
|
||||
|
||||
prted
|
||||
=====
|
||||
|
||||
prted |mdash| helper daemon for PRRTE
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
.. code:: sh
|
||||
|
||||
shell$ prted ...options...
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
``prted`` is the back end helper daemon for PMIx Reference Runtime
|
||||
Environment (PRRTE).
|
||||
|
||||
Extensive help documentation for this command is provided through
|
||||
``prted --help [topic]``.
|
||||
|
||||
At least for now, that content is not available in man page form.
|
||||
Pull requests to add all the content (via repeatable infrastructure)
|
||||
would be greatly appreciated.
|
||||
|
||||
.. seealso::
|
||||
:ref:`prte(1) <man1-prte>`
|
||||
@@ -0,0 +1,49 @@
|
||||
.. _man1-prterun:
|
||||
|
||||
prterun
|
||||
========
|
||||
|
||||
prterun |mdash| launch an application with a default DVM
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
.. code:: sh
|
||||
|
||||
shell$ prterun ...options...
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
``prterun`` submits a job to the PMIx Reference Runtime Environment
|
||||
(PRRTE). A default set of distributed virtual
|
||||
machine (DVM) options are used; use :ref:`prun(1) <man1-prun>` if you
|
||||
wish to utilize specific DVM options.
|
||||
|
||||
Much of this same help documentation for this command is also provided
|
||||
through ``prun --help [topic]``.
|
||||
|
||||
.. admonition:: PRRTE Docs TODO
|
||||
:class: error
|
||||
|
||||
Need to write this man page.
|
||||
|
||||
COMMAND LINE OPTIONS
|
||||
--------------------
|
||||
|
||||
.. TODO - add in all supported CLI
|
||||
|
||||
|
||||
DEPRECATED COMMAND LINE OPTIONS
|
||||
-------------------------------
|
||||
|
||||
.. TODO - check for deprecated CLI and add those here
|
||||
|
||||
|
||||
EXIT STATUS
|
||||
-----------
|
||||
|
||||
Description of the various exit statuses of this command.
|
||||
|
||||
.. seealso::
|
||||
:ref:`prte(1) <man1-prte>`
|
||||
@@ -0,0 +1,44 @@
|
||||
.. _man1-prun:
|
||||
|
||||
prun
|
||||
=====
|
||||
|
||||
prun |mdash| launch an application
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
.. code:: sh
|
||||
|
||||
shell$ prun ...options...
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
``prun`` submits a job to the PMIx Reference Runtime Environment
|
||||
(PRRTE). The user has control over various distributed virtual
|
||||
machine (DVM) options.
|
||||
|
||||
Much of this same help documentation for this command is also provided
|
||||
through ``prun --help [topic]``.
|
||||
|
||||
.. admonition:: PRRTE Docs TODO
|
||||
:class: error
|
||||
|
||||
Need to write this man page.
|
||||
|
||||
COMMAND LINE OPTIONS
|
||||
--------------------
|
||||
|
||||
The following command line options are supported:
|
||||
|
||||
.. TODO - add in all supported CLI
|
||||
|
||||
DEPRECATED COMMAND LINE OPTIONS
|
||||
-------------------------------
|
||||
|
||||
.. TODO - check for deprecated CLI and add those here
|
||||
|
||||
|
||||
.. seealso::
|
||||
:ref:`prte(1) <man1-prte>`
|
||||
@@ -0,0 +1,29 @@
|
||||
.. _man1-pterm:
|
||||
|
||||
pterm
|
||||
=====
|
||||
|
||||
pterm |mdash| terminate an instance of the PRRTE DVM
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
.. code:: sh
|
||||
|
||||
shell$ pterm ...options...
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
``pterm`` terminates an instance of the PMIx Reference Runtime
|
||||
Environment (PRRTE) distributed virtual machine (DVM).
|
||||
|
||||
Extensive help documentation for this command is provided through
|
||||
``pterm --help [topic]``.
|
||||
|
||||
At least for now, that content is not available in man page form.
|
||||
Pull requests to add all the content (via repeatable infrastructure)
|
||||
would be greatly appreciated.
|
||||
|
||||
.. seealso::
|
||||
:ref:`prte(1) <man1-prte>`
|
||||
@@ -0,0 +1,7 @@
|
||||
Config file manual pages (section 5)
|
||||
====================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
prte.5.rst
|
||||
@@ -0,0 +1,11 @@
|
||||
.. _man5-prte:
|
||||
|
||||
prte
|
||||
====
|
||||
|
||||
PMIx Reference Runtime Environment (PRRTE) - General information
|
||||
|
||||
.. admonition:: PRRTE Docs TODO
|
||||
:class: error
|
||||
|
||||
Need to write this man page.
|
||||
@@ -0,0 +1,40 @@
|
||||
.. 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 PRRTE since
|
||||
version 1.0.
|
||||
|
||||
PRRTE 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-v3.x
|
||||
news-v2.x
|
||||
news-v1.x
|
||||
@@ -0,0 +1,10 @@
|
||||
PRRTE v1.x series
|
||||
=================
|
||||
|
||||
This file contains all the NEWS updates for all the PRTE v1.x
|
||||
series, in reverse chronological order.
|
||||
|
||||
1.0.0 -- 17 Jul 2019
|
||||
----------------------
|
||||
|
||||
Initial public release - not production intended
|
||||
@@ -0,0 +1,128 @@
|
||||
PRRTE v2.x series
|
||||
=================
|
||||
|
||||
This file contains all the NEWS updates for all the PRRTE v2.x
|
||||
series, in reverse chronological order.
|
||||
|
||||
2.0.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 #1197: Cleanup a bit in prep for PMIx v5 release
|
||||
- PR #1195: Remove HWLOC version block
|
||||
- PR #1190: Add missing examples to tarball
|
||||
- PR #1189: Ensure an error gets reported when rankfile fails
|
||||
|
||||
|
||||
2.0.1 -- 1 Feb 2022
|
||||
---------------------
|
||||
.. important:: As of v2.0.1, PRRTE no longer has a dependency on "pandoc"
|
||||
for building and installing man pages.
|
||||
|
||||
.. important:: PRRTE 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, PRRTE now checks for the problem
|
||||
HWLOC versions and will error out of configure if they are
|
||||
encountered.
|
||||
|
||||
- PR #1185 and 1186: Update HWLOC version detection
|
||||
- Reject versions 2.5.0-2.7.0, inclusive
|
||||
- PR #1183: Always build the PBS scheduler support
|
||||
- PR #1182: Cleanup handling of allocated node names
|
||||
- PR #1169: Updates for rc5
|
||||
- Enable support for PMIX_IOF_OUTPUT_RAW attribute
|
||||
- Update NEWS
|
||||
- PR #1167: Updates
|
||||
- Be more flexible in library handling
|
||||
- Update libevent/hwloc handling to match PMIx
|
||||
- Remove event header defines
|
||||
- Minor cleanups and ensure no local IOF copy
|
||||
when persistent
|
||||
- change the pcc wrapper compiler to a symlink
|
||||
to pmixcc
|
||||
- Cleanup code a bit
|
||||
- Select all adapters with IPv4 addresses within
|
||||
specified subnet ranges
|
||||
- validate input for mpiexec --with-ft options
|
||||
- PR #1158: Updates
|
||||
- Fix uninitialized variable
|
||||
- Update NEWS
|
||||
- PR #1157: Fix brackets around code clause that caused
|
||||
erroneous "unable to find tune file" error
|
||||
- PR #1156: Handle default param case for HWT CPUs
|
||||
- PR #1155: Cleanup qualifier detection for mapping policy
|
||||
- PR #1154: Increase speed of rank computation
|
||||
- Remove spurious break in loop
|
||||
- PR #1153: Ensure the direct-multi test ranks-by slot
|
||||
- PR #1151: Revamp map-by NUMA support
|
||||
- PR #1150: Tranlate legacy OMPI params
|
||||
- PR #1147: Updates
|
||||
- Minor infrastructure and example cleanup
|
||||
- Allow external caller to set prte_tool_basename
|
||||
- Restore support for map/rank/bind by NUMA domains
|
||||
- Standardize on use of HWLOC_OBJ_NUMANODE
|
||||
- Activate the colocation code and debug it
|
||||
- Update man pages
|
||||
- PR #1145: delete use of PMIX_CHECK_BROKEN_QSORT refs
|
||||
- PR #1137: Protect against PMIx v4.1.1-only definitions
|
||||
- PR #1135: Final update v2.0.1 for rc3
|
||||
- Show MCA base params in prte_info
|
||||
- Silence variety of warnings
|
||||
- Start enabling picky compilers when requested
|
||||
- Remove unused variables in BMG component
|
||||
- Increase verbosity of detected error
|
||||
- Remove broken qsort support
|
||||
- Add a legacy example
|
||||
- Don't specify parent ID from tool
|
||||
- PR #1104: Update v2.0.1 for rc3
|
||||
- Silence Coverity warnings
|
||||
- Update portable platform file
|
||||
- Only order DVM termination once
|
||||
- Abort configure if gcc is <= 4.8.1
|
||||
- Fix segmentation fault caused by wrong size for vpids buffer
|
||||
- PR #1097: Update v2.0.1 for rc2
|
||||
- Update NEWS and VERSION
|
||||
- Circulate and report local completion status for collectives
|
||||
- Don't require pandoc to make a tarball
|
||||
- Do not register xml topos
|
||||
- Remove the Markdown source files for PRRTE man pages
|
||||
- PR #1089: Updates
|
||||
- Cleanup timeout support to differentiate spawn vs execution time limits
|
||||
- PR #1086: Multiple commits
|
||||
- Use the info list array feature to construct registration data
|
||||
- Fix path check for pandoc
|
||||
- PR #1083: Multiple commits
|
||||
- Add MCA param to control device distance computation
|
||||
- Correctly report --output-directory and --output-filename as deprecated
|
||||
- Check for libevent minimum 2.0.21
|
||||
- Properly handle generic "orte" MCA params
|
||||
- Cleanups associated with IOF operations
|
||||
- Avoid use of MCA params for singleton and report-uri
|
||||
- autogen.pl: ignore all excluded components
|
||||
- Don't allow PRRTE IOF to block during delivery
|
||||
- Update ignores to include Coverity working directory
|
||||
- Ensure we hold the IOF data until the PMIx library is done with it
|
||||
- Add an "unlock" call to balance the code
|
||||
- Use correct ninfo when passing into APIs
|
||||
- Don't locally output stdout/err if prterun has a parent
|
||||
|
||||
|
||||
2.0.0 -- 29 Jul 2021
|
||||
--------------------
|
||||
.. important:: This is the initial production release of the PRRTE
|
||||
software system. It contains full support of the
|
||||
PMIx v4.1 Standard plus extensions as provided by
|
||||
OpenPMIx v4.1. It therefore requires support from
|
||||
that release or above.
|
||||
|
||||
Delineating all the changes from the original v1.0.0 tarball would be
|
||||
overwhelming. The original tarball was provided solely as a means for
|
||||
packagers to prepare for the eventual production version and was not
|
||||
intended for general use. As expected, the code base has been extensively
|
||||
revised/rewritten since that time.
|
||||
|
||||
Further changes shall be tracked here in follow-on releases.
|
||||
@@ -0,0 +1,383 @@
|
||||
PRRTE v3.x series
|
||||
=================
|
||||
|
||||
This file contains all the NEWS updates for the PRRTE v3.x
|
||||
series, in reverse chronological order.
|
||||
|
||||
3.0.8 -- 15 Dec 2024
|
||||
--------------------
|
||||
- PR #2103: Final update for release
|
||||
- PR #2102: Remove stale config .m4 files
|
||||
- PR #2100: Update NEWS and VERSION
|
||||
- PR #2099: maintain correct ref count of child jobs
|
||||
- PR #2097: Correctly parse map-by modifiers
|
||||
- PR #2086: Propertly compute number of procs when not given
|
||||
- PR #2082: Multiple commits
|
||||
- Enclose XML output in a high-level tag
|
||||
- Add support for show_help XML output
|
||||
- Properly build the nidmap
|
||||
- PR #2076: Multiple commits
|
||||
- Register the singleton's nspace with the PMIx server
|
||||
- Fix data type declaration in data server
|
||||
|
||||
|
||||
3.0.7 -- 13 Nov 2024
|
||||
--------------------
|
||||
.. important:: This release represents the expected end of
|
||||
the v3.0 series. Any follow-on bug fixes will
|
||||
be committed to the release branch, but are
|
||||
unlikely to generate an official release
|
||||
tarball.
|
||||
|
||||
- PR #2067: Update NEWS and VERSION for final release
|
||||
- PR #2064: Multiple commits
|
||||
- Update help message to PRTE MCA parameter handling
|
||||
- Fix typo in Makefile
|
||||
- Fix rankfile use of relative node indexing
|
||||
- PR #2060: Update NEWS and VERSION for release
|
||||
- PR #2059: Protect against old PMIx versions
|
||||
- PR #2057: Fix support for hetero LSF environments
|
||||
- PR #2049: Cleanup show-help files
|
||||
- PR #2047: Implement the PMIX_JOB_CHILD_SEP support
|
||||
- PR #2044: Multiple commits
|
||||
- Add a threaded client example
|
||||
- Restore parsing of OMPI param files
|
||||
- PR #2039: Unlock stdin target
|
||||
- PR #2037: Pull a couple of fixes from master branch
|
||||
- PR #2034: Fix deprecation warnings for ppr on socket objects
|
||||
- PR #2032: Multiple commits
|
||||
- avoid warnings (as errors) spots (init vars, etc.)
|
||||
- remove unused Level var
|
||||
- init installdirs structure (avoids warn-as-error)
|
||||
- Pay attention to interface include/exclude params
|
||||
- Protect against the envar version of the Slurm custom args param
|
||||
- PR #2018: fix support for MPIEXEC_TIMEOUT
|
||||
- PR #2017: Update prte_portable_platform_real.h from upstream gasnet
|
||||
- PR #2015: Always have show-help available
|
||||
- PR #2013: Remove unused yaml
|
||||
- PR #2011: Cleanup show help formatting
|
||||
- PR #2009: docs: update for Python 3.12
|
||||
- PR #2007: Fix a segfault when no arguments are provided
|
||||
- PR #2005: Multiple commits
|
||||
- Remove unused function
|
||||
- Revise cmd line parsing to handle special case
|
||||
- PR #2002: Update OAC to latest HEAD
|
||||
- PR #2000: Use the PMIx functions to check params
|
||||
- PR #1998: Protect against LTO optimizer
|
||||
- PR #1996: Read the Docs updates
|
||||
- PR #1994: Provide a warning of potentially unknown Slurm params
|
||||
|
||||
|
||||
3.0.6 -- 8 Jul 2024
|
||||
-------------------
|
||||
- PR #1992: Update NEWS and VERSION for release
|
||||
- PR #1991: Multiple commits
|
||||
- Protect against missing HWLOC object types
|
||||
- Minor fixes to allow compile with pre-stone age HWLOC
|
||||
- PR #1988: Github action: bring back MacOS builds
|
||||
- PR #1986: Tailored backport of "various fixes for singleton support"
|
||||
- PR #1985: Multiple commits
|
||||
- Don't strip quotes from cmd line entries
|
||||
- Update tar format to tar-pax
|
||||
- PR #1983: Check the runtime version of PMIx
|
||||
- PR #1979: Multiple commits
|
||||
- Cleanup issues surfaced by devel-check
|
||||
- Cleanup unused var warning
|
||||
- Add CI build with clang
|
||||
- Enable devel-check by default in Git repos
|
||||
- Stop warning on LSF detection when not requested
|
||||
- Silence warning
|
||||
- MPI 4.1: add support for memory-alloc-kinds
|
||||
- Remove MacOS CI builds
|
||||
- Add support for PMIX_MEM_ALLOC_KIND
|
||||
- PR #1971: Remove stale resilience document
|
||||
- PR #1968: Try to improve an error message a bit
|
||||
- PR #1966: Fix typo
|
||||
- PR #1964: Repair the binding algorithm
|
||||
- PR #1962: Correct name of help file for --hostfile
|
||||
- PR #1959: Multiple commits
|
||||
- Update the allocation simulator
|
||||
- Use of pmix_getline from PMIx started in v4.2.5
|
||||
- PR #1956: Multiple commits
|
||||
- Allow execution without an active plm component
|
||||
- Fix the binding algorithm to handle partial disablement
|
||||
|
||||
|
||||
3.0.5 -- 21 Mar 2024
|
||||
--------------------
|
||||
- PR #1952: Multiple commits
|
||||
- Update docs
|
||||
- Update PMIx-related configure code
|
||||
- update the hwloc utility code
|
||||
- Add missing doc
|
||||
- PR #1949: Update VERSION and NEWS for release
|
||||
- PR #1946: Correct deprecation translation for use-hwthread-cpus
|
||||
- PR #1936: Add missing show_help text
|
||||
- PR #1933: Check for appfile and ingest it if found
|
||||
- PR #1931: Multiple commits
|
||||
- Fix testing of suicide for daemons
|
||||
- Fix daemon suicide and preserve output files
|
||||
- Remove unused MCA param
|
||||
- Only trigger job failed to start once
|
||||
- Add "close stale issues" actions
|
||||
- oac: strengthen Sphinx check
|
||||
- Revamp the session directory system
|
||||
- guard against possible segfault in prted
|
||||
|
||||
|
||||
3.0.4 -- 4 Feb 2024
|
||||
-------------------
|
||||
- PR #1918: Multiple commits
|
||||
- Support query for number of available slots
|
||||
- Add an option '--allow-run-as-root' into prted
|
||||
- Update the Python regex for doc build
|
||||
- PR #1910: Fix the map-by pe-list option
|
||||
- PR #1908: Multiple commits
|
||||
- Use pmix_path_nfs to detect shared file systems
|
||||
- Remove debug
|
||||
- Remove extra character at end of error messages
|
||||
- psets: fix some problems with PMIX_QUERY_PSET_MEMBERSHIP query.
|
||||
|
||||
|
||||
3.0.3 -- 19 Dec 2023
|
||||
--------------------
|
||||
- PR #1893: Check for stdatomic.h
|
||||
- PR #1891: add nodes to job data for ALL jobs included in the launch message
|
||||
- PR #1888: Multiple commits
|
||||
- Minor tweaks of cmd line processing
|
||||
- Preserve the clichk test code for future use
|
||||
- PR #1884: Multiple commits
|
||||
- Fix copy/paste error
|
||||
- Remove daemonize option from prterun
|
||||
- Fix the ras simulator module
|
||||
- Preserve backward compatibility
|
||||
- Check the PMIx version for min required
|
||||
- Correct min version for pmix_getline util
|
||||
- PR #1877: Multiple commits
|
||||
- Remove the "refresh" key before requesting dmodx from PMIx server
|
||||
- Shift a code block to enable MCA param directive for ppr mapping
|
||||
- PR #1870: Multiple commits
|
||||
- Begin to restore the detailed help topics
|
||||
- docs: add prrte-rst-content to conf.py's exclude_patterns
|
||||
- src/docs: update README.txt
|
||||
- Consolidate non-component show_help files
|
||||
- Add missing file
|
||||
- PR #1865: Fix the seq mapper
|
||||
- PR #1860: Multiple commits
|
||||
- prte.c: a prefix of "/" is ok
|
||||
- Correctly translate the plm_rsh MCA params
|
||||
- Fix add-hostfile and add-host operations
|
||||
- Add print functions for node, job, and proc flags
|
||||
- Add missing "acquire_object"
|
||||
- Fix handling of "--" in cmd line
|
||||
- Use global PRRTE event base for sigchld callback
|
||||
- Remove the event base param to prte_wait_cb
|
||||
- Fix OMPI cmd line processing
|
||||
- PR #1846: Multiple commits
|
||||
- Restore the prun help strings
|
||||
- Restore prte_info show help topics
|
||||
- Recover the pterm show-help strings
|
||||
- PR #1843: Avoid adding NULL prefix value to app attributes
|
||||
- PR #1841: Multiple commits
|
||||
- Error out of attempts for 32-bit builds
|
||||
- Convert OMPI MCA params from legacy orte
|
||||
- Fix display of DVM allocation
|
||||
|
||||
|
||||
3.0.2 -- 23 Oct 2023
|
||||
--------------------
|
||||
- PR #1832: Update NEWS for release
|
||||
- PR #1831: Silence error log
|
||||
- PR #1829: Multiple commits
|
||||
- docs/show-help-files: Re-enable Sphinx warning checks
|
||||
- Correctly forward stdin to remote procs
|
||||
- PR #1826: Multiple commits
|
||||
- docs: document minimum PMIx version needed
|
||||
- prte_setup_pmix.m4: use PMIx min version from VERSION
|
||||
- Make checking min versions consistent
|
||||
- Update CPPFLAGS for HWLOC config tests
|
||||
- PR #1822: Fix rpmbuild error
|
||||
- PR #1821: Roll VERSION to v3.0.2
|
||||
|
||||
|
||||
3.0.1 -- 27 Sep 2023
|
||||
--------------------
|
||||
.. important:: This release contains a major revision of the PRRTE
|
||||
documentation infrastructure. Accordingly, the various
|
||||
documents may contain some number of errors and should
|
||||
be regarded as a work-in-progress. We apologize in
|
||||
advance for any inconvenience this may create, and will
|
||||
continue to improve and correct the documents in future
|
||||
releases.
|
||||
|
||||
- PR #1818: Update VERSION and rename news file
|
||||
- PR #1816: Correct confusion over help file names
|
||||
- PR #1814: Update NEWS infrastructure
|
||||
- PR #1810: Blacklist the HWLOC GL component to avoid deadlock
|
||||
- PR #1807: Multiple commits
|
||||
- src/docs/show-help-files/Makefile.am: fix syntax
|
||||
- docs: Fix up several minor bugs that showed up via CI
|
||||
- Prototype Github Actions for PRRTE CI
|
||||
- PR #1800: Keep trying to find the solution to the docs problem
|
||||
- PR #1798: Keep trying to fix this Python stuff
|
||||
- PR #1796: Don't ignore failure to create directory
|
||||
- PR #1793: build-dummy-ini-files: Be safe for Python 2
|
||||
- PR #1791: Update to track master branch
|
||||
- PR #1787: Add support for dynamic definition of process sets
|
||||
- PR #1784: Multiple commits
|
||||
- docs: fix HTML word wapping in table cells
|
||||
- Support fix for OMPI Github issue #11532
|
||||
- Fix binding to multiple pe's
|
||||
- Fix typos in the --enable-dlopen support
|
||||
- Fix typo of variable name (PRRTE->PRTE)
|
||||
- Remove Doxygen
|
||||
- PR #1766: Multiple commits
|
||||
- Update ignores
|
||||
- mca/rmaps: impute process count when np is not set
|
||||
- Complete cleanup of map/bind default settings
|
||||
- PR #1762: v3.0: .github/workflows: update actions versions
|
||||
- PR #1752: [v3.0] rmaps/base: remove call to hwloc_bitmap_andnot() in bind_generic()
|
||||
- PR #1747: Respect "--" marker
|
||||
- PR #1741: [v3.0] RTD: Add .readthedocs.yaml file
|
||||
- PR #1737: Multiple commits
|
||||
- Add debug output in fence upcall
|
||||
- Silence TSan data race warning.
|
||||
- PR #1734: v3.0: backport fixes for ompi v5.0 submodule update
|
||||
- PR #1727: Protect against bad ppr directives
|
||||
- PR #1724: Fix one more place
|
||||
- PR #1721: Just disable the xml map output for ancient hwloc
|
||||
- PR #1718: Protect against ancient hwloc versions
|
||||
- PR #1714: Multiple commits
|
||||
- Parsable output in an XML format
|
||||
- Support odd topologies and relax pe-binding rules
|
||||
- Cleanup some formatting and unnecessary debug
|
||||
- PR #1705: Allow specifying ppr as the default mapping policy
|
||||
- PR #1702: Multiple commits
|
||||
- Recoverable jobs may report more than one proc error over the lifetime
|
||||
- Fix double-counting of failed procs in recoverable jobs
|
||||
- PR #1700: Update headers for rc2
|
||||
- PR #1696: Always set waitpid-fired flag when proc exits
|
||||
- PR #1694: Fix passing of envars for spawn
|
||||
- PR #1692: Multiple commits
|
||||
- Plug small memory leaks.
|
||||
- Plug memory leaks.
|
||||
- Adhere to project's variable declaration convention.
|
||||
- Cleanup initial implementation of allocate and session ctrl
|
||||
- Protect one more place for Session_control
|
||||
- Fix the routing for non-tree-spawn launch
|
||||
- Cleanup prte_info output
|
||||
- Ensure we exit cleanly when a daemon fails to start
|
||||
- Store prted URI under correct name
|
||||
- Remove duplicate computation of routing tree
|
||||
- Minor cleanup of verbose output
|
||||
- Fix typo
|
||||
- Send direct to HNP if we don't know a route
|
||||
- Cleanup some mangled formatting
|
||||
- Cleanup some debug output
|
||||
- Update the pmix server integration
|
||||
- PR #1686: Update config/oac submodule
|
||||
- PR #1682: Multiple commits
|
||||
- Remove wrapper definitions
|
||||
- Extend example to check for sessionID and jobID
|
||||
- PR #1678: Multiple commits
|
||||
- add --debug-daemon to prted options
|
||||
- Add the rml and routed types to prte_info array
|
||||
- PR #1674: Ensure cmd line errors provide error messages
|
||||
- PR #1672: Multiple commits
|
||||
- Correct default binding for map-by node/slot
|
||||
- Provide better error message for cross-package binding
|
||||
- Add missing command line directives
|
||||
- Fix minor issues found in tests.
|
||||
- Silence compiler warning in test/connect.
|
||||
- Silence compiler warnings in examples.
|
||||
- Use exit macros in example dmodex.
|
||||
- Remove antiquated code that can cause problems
|
||||
- Update sphinx requirements
|
||||
- Remove the PMIX_SIZE_ESTIMATE support
|
||||
- PR #1660: Correct function name when using older hwloc versions
|
||||
- PR #1658: Multiple commits
|
||||
- Properly handle overload-allowed
|
||||
- Define MIN for environments that lack it
|
||||
- Fix a typo in the README, fixes #1645
|
||||
- docs: fix Sphinx parsing error
|
||||
- PR #1644: Multiple commits
|
||||
- Add a spawn_multiple test
|
||||
- Provide an estimate of the size of registration data
|
||||
- Provide size estimates for collective operations that return data
|
||||
- Add an option to display the available CPUs
|
||||
- Fix generate_dist type
|
||||
- Protect against missing attribute definition
|
||||
- Set distances array type
|
||||
- Add "parseable" display qualifier
|
||||
- Generate distances by default
|
||||
- Show help message when mapping too low
|
||||
- Fix round-robin by obj with multiple cpus/rank
|
||||
- Fix map-by slot and node for multiple cpus/rank
|
||||
- PR #1633: v3.0.x: First cut of Sphinx/ReadTheDocs docs
|
||||
- PR #1626: Remove unused variable
|
||||
- PR #1622: Multiple commits
|
||||
- Update version to 3.0.1
|
||||
- Extend query support to include allocation info
|
||||
- Remove debug
|
||||
- Include topology in allocated node info
|
||||
- Minor touchups of the "fault" example
|
||||
- Designate the framework project as PRTE
|
||||
- Begin adding support for new server module function pointer
|
||||
- Silence warning - add return values
|
||||
- Update to compatibility with PMIx master ranch
|
||||
- Protect against earlier PMIx versions
|
||||
- Add an IOF stress test
|
||||
- Accept local group op upcalls
|
||||
- Check for and track scheduler attachment
|
||||
- Check for map/bind conflicting directive, improve unbound report
|
||||
- Don't error out on binding if not required
|
||||
- PR #1600: Multiple commits
|
||||
- Minor change to check_os_flavors
|
||||
- Don't emit an error output if not needed
|
||||
- PR #1597: Fix oac_check_package.m4
|
||||
- PR #1595: build: fix bashisms in configure
|
||||
|
||||
|
||||
3.0.0 -- 13 Nov 2022
|
||||
--------------------
|
||||
.. important:: This release represents a major update to the PRRTE
|
||||
code base from prior releases. Many of the changes will be
|
||||
transparent to the user. However, there are a few key areas that
|
||||
may (likely) impact users. These include:
|
||||
|
||||
- changes to the cmd line interpreter. PRRTE has provided an
|
||||
abstraction layer that allows programming library developers
|
||||
and environment vendors to customize the cmd line of PRRTE
|
||||
binaries (e.g., prterun and prun). This is governed by the
|
||||
detection of a "personality" that is to be used for defining
|
||||
the cmd line options. The personality can be set either directly
|
||||
on the cmd line itself (via the "--personality foo" option) or
|
||||
is detected by PRRTE thru the environment.
|
||||
- a more extensive "--help" support system.
|
||||
- reduction in the "--rank-by" options.
|
||||
- addition of new "--output" options
|
||||
- removal of the "mindist" mapper due to lack of a maintainer
|
||||
|
||||
There are quite a few more changes than listed here, but they mostly
|
||||
pertain to code internals. However, these dictate that PRRTE v3.0.0
|
||||
require use of PMIx v4.2 or above to compile. Note that this doesn't
|
||||
impact the PMIx level associated with any applications executed by
|
||||
PRRTE - the only requirement is that applications link against a
|
||||
PMIx version that meets the PMIx cross-version requirements (i.e., a
|
||||
minimum of PMIx v2.5).
|
||||
|
||||
Detailed changes include:
|
||||
|
||||
- PR #1412: Restrict PRRTE to PMIx v4.2+
|
||||
- PR #1410: Remove schizo/hydra component
|
||||
- PR #1409: Add new output options to help string
|
||||
- PR #1407: Support a broader range of IO output formats
|
||||
- PR #1404: Fix a hang in daemon callback
|
||||
- PR #1402: Cleanup race condition in daemon reports
|
||||
- PR #1399: Multiple commits
|
||||
- Allow mapping in overload scenario if bind not specified
|
||||
- Ensure rankfile and seq mappers computer local and app ranks
|
||||
- PR #1394: Add forwarding of stdin to indirect example
|
||||
- PR #1391: Change the default mapping for --bind-to none option to BYSLOT.
|
||||
|
||||
Branch from `master@f3d4089 <https://github.com/openpmix/prrte/commit/f3d4089>`_
|
||||
@@ -0,0 +1,96 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
Copyright (c) 2022-2023 Nanook Consulting. All rights reserved.
|
||||
Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved.
|
||||
|
||||
$COPYRIGHT$
|
||||
|
||||
Additional copyrights may follow
|
||||
|
||||
$HEADER$
|
||||
|
||||
Notifications
|
||||
=============
|
||||
|
||||
PRRTE provides notifications on a variety of process and job
|
||||
states. Each notification includes not only the PMIx event code that
|
||||
generated it, but also information on the cause of the event to the
|
||||
extent to which this is known.
|
||||
|
||||
Supported job events include:
|
||||
|
||||
* ``PMIX_READY_FOR_DEBUG``: indicates that all processes in the
|
||||
reported nspace have reached the specified debug stopping point.
|
||||
|
||||
* ``PMIX_LAUNCH_COMPLETE``: indicates that the reported nspace has
|
||||
been launched |mdash| i.e., the involved PRRTE daemons all report
|
||||
that their respective child processes have completed fork/exec.
|
||||
|
||||
* ``PMIX_ERR_JOB_CANCELED``: indicates that the job was cancelled by
|
||||
user command, usually issued via an appropriate PMIx-enabled tool.
|
||||
|
||||
* ``PMIX_ERR_JOB_FAILED_TO_LAUNCH``: indicates that the specified job
|
||||
failed to launch. This can be due to a variety of factors that
|
||||
include inability to find the executable on at least one involved
|
||||
node.
|
||||
|
||||
Supported process events include:
|
||||
|
||||
* ``PMIX_ERR_PROC_TERM_WO_SYNC``: indicates that at least one process
|
||||
in the job called ``PMIx_Init``, thus indicating some notion of a
|
||||
global existence, and at least one process in the job subsequently
|
||||
exited without calling ``PMIx_Finalize``. This usually indicates a
|
||||
failure somewhere in the application itself that precluded an
|
||||
orderly shutdown of the process. Notification will include the
|
||||
process ID that exited in this manner.
|
||||
|
||||
* ``PMIX_EVENT_PROC_TERMINATED``: indicates that the reported process
|
||||
terminated normally. Notification will include the process ID that
|
||||
exited and its exit status.
|
||||
|
||||
* ``PMIX_ERR_PROC_KILLED_BY_CMD``: indicates that the reported process
|
||||
was killed by PRRTE command. This typically occurs in response to a
|
||||
Ctrl-C (or equivalent) being applied to the PRRTE launcher, thereby
|
||||
instructing PRRTE to forcibly terminate its processes. The event
|
||||
currently will only be issued in the case where forcible termination
|
||||
is commanded via a tool that can pass the process IDs that are
|
||||
specifically to be terminated |mdash| otherwise, in the case of the
|
||||
Ctrl-C event previously described, all processes in the job will be
|
||||
terminated, leaving none to be notified. Notification will include
|
||||
the process ID that was terminated.
|
||||
|
||||
* ``PMIX_ERR_PROC_SENSOR_BOUND_EXCEEDED``: indicates that the
|
||||
specified process exceeded a previously-set sensor boundary |mdash|
|
||||
e.g., it may have grown beyond a defined memory limit. Such events
|
||||
may or may not automatically trigger termination by command,
|
||||
depending upon the behavior of the sensor. Notification will include
|
||||
the process ID that exceeded the sensor boundary plus whatever
|
||||
information the sensor provides regarding measurements and bounds.
|
||||
|
||||
* ``PMIX_ERR_PROC_ABORTED_BY_SIG``: indicates that the specified
|
||||
process was killed by a signal |mdash| e.g., a segmentation
|
||||
fault/violation or an externally applied signal. Notifications will
|
||||
include the process ID that was killed and the corresponding
|
||||
reported signal.
|
||||
|
||||
* ``PMIX_ERR_PROC_REQUESTED_ABORT:`` indicates that the specified
|
||||
process has aborted by calling the ``PMIx_Abort``
|
||||
function. Notification will include the process ID that called abort
|
||||
and its exit status.
|
||||
|
||||
* ``PMIX_ERR_EXIT_NONZERO_TERM``: indicates that the specified process
|
||||
terminated with a non-zero exit status. This notification is only
|
||||
generated in the case where the runtime option
|
||||
``ERROR-NONZERO-STATUS`` is set to true, thereby indicating that a
|
||||
process exiting with non-zero status is to be considered an
|
||||
error. As PRRTE can be overwhelmed by a large job where every
|
||||
process exits with a non-zero status, only the *first* process in a
|
||||
given job that exits with a non-zero status will generate a
|
||||
notification unless the ``RECOVERABLE`` runtime option is also
|
||||
provided as otherwise the job will be immediately
|
||||
terminated. Notifications will include the process ID that exited
|
||||
and the status it returned.
|
||||
|
||||
* ``PMIX_ERR_PROC_RESTART``: indicates that the specified process has
|
||||
been restarted. Additional information may include the hostname
|
||||
where the process is now executing.
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-placement-deprecated.rst
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-placement-diagnostics.rst
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-placement-examples.rst
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-placement-fundamentals.rst
|
||||
@@ -0,0 +1,22 @@
|
||||
Process placement
|
||||
=================
|
||||
|
||||
PRRTE provides a set of three controls for assigning process
|
||||
locations and ranks:
|
||||
|
||||
#. Mapping: Assigns a default location to each process
|
||||
#. Ranking: Assigns a unique integer rank value to each process
|
||||
#. Binding: Constrains each process to run on specific processors
|
||||
|
||||
The sections below describe these controls in more detail.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
overview
|
||||
examples
|
||||
fundamentals
|
||||
limits
|
||||
diagnostics
|
||||
rankfiles
|
||||
deprecated
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-placement-limits.rst
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-placement.rst
|
||||
@@ -0,0 +1 @@
|
||||
.. include:: /prrte-rst-content/detail-placement-rankfiles.rst
|
||||
@@ -0,0 +1,43 @@
|
||||
.. _label-quickstart:
|
||||
|
||||
Quick start
|
||||
===========
|
||||
|
||||
In many cases, PRRTE can be built and installed by simply
|
||||
indicating the installation directory on the command line:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ tar xf prrte-<version>.tar.bz2
|
||||
$ cd prrte-<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
|
||||
environmnet; see below for desciptions 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 prrte-<version>.tar.bz2
|
||||
$ cd prrte-<version>
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ ../configure --prefix=<path> |& tee config.out
|
||||
...etc.
|
||||
@@ -0,0 +1,22 @@
|
||||
Release Notes
|
||||
=============
|
||||
|
||||
- Systems that have been tested are:
|
||||
|
||||
- Linux (various flavors/distros), 32 bit, with gcc
|
||||
- Linux (various flavors/distros), 64 bit (x86), with gcc, Intel,
|
||||
and Portland (*)
|
||||
- OS X (10.7 and above), 32 and 64 bit (x86_64), with gcc (*)
|
||||
|
||||
- PRRTE has taken some steps towards Reproducible Builds
|
||||
(https://reproducible-builds.org/). Specifically, PRRTE's
|
||||
``configure`` and ``make`` process, by default, records the build
|
||||
date and some system-specific information such as the hostname where
|
||||
PRRTE 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 PRRTE 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.
|
||||
@@ -0,0 +1,71 @@
|
||||
Session directory
|
||||
=================
|
||||
|
||||
PRRTE establishes a "session directory" on the filesystem to serve as
|
||||
a top-level location for temporary files used by both the local PRRTE
|
||||
daemon and its child processes.
|
||||
|
||||
This is done to enable quick and easy cleanup in the event that PRRTE
|
||||
is unable to fully cleanup after itself.
|
||||
|
||||
More detail on session directories is provided in the How Things Work
|
||||
:ref:`session directory <session-dir-detail-label>` section.
|
||||
|
||||
Directory location
|
||||
------------------
|
||||
|
||||
PRRTE decides where to located the root of the session directory by
|
||||
examining the following (in precedence order):
|
||||
|
||||
#. If the value of the ``prte_top_session_dir`` MCA parameter is not
|
||||
empty, use that (it defaults to empty).
|
||||
|
||||
.. note:: MCA parameters can be set via environment variables, on
|
||||
the command line, or in a parameter file.
|
||||
|
||||
.. note:: If necessary, the value of the top session directory on
|
||||
the local node where the launcher (e.g., ``prun``, ``prterun``,
|
||||
or ``mpirun``) is executing can be set separately from
|
||||
the value to be used on compute nodes via the
|
||||
``prte_local_tmpdir_base`` and ``prte_remote_tmpdir_base``
|
||||
parameters.
|
||||
|
||||
#. If the environment variable ``TMPDIR`` is not empty, use that.
|
||||
#. If the environment variable ``TEMP`` is not empty, use that.
|
||||
#. If the environment variable ``TMP`` is not empty, use that.
|
||||
#. Use ``/tmp``
|
||||
|
||||
Directory name
|
||||
--------------
|
||||
|
||||
By default, the session directory name is set to
|
||||
|
||||
.. code::
|
||||
|
||||
<tool>.<nodename>.<pid>.<uid>
|
||||
|
||||
where `tool` is the argv[0] of the process setting up the
|
||||
session directory. In most cases, this will be either `prte`,
|
||||
`prterun`, or `prted` - though special tools such as `psched`
|
||||
may also create a session directory tree.
|
||||
|
||||
The session directory name includes the PID
|
||||
of the daemon process to allow a user to have multiple
|
||||
instances of a tool concurrently executing on a node.
|
||||
|
||||
.. note::
|
||||
|
||||
Each tool will generate its own session directory tree. This
|
||||
is done to avoid cleanup race conditions where one tool might
|
||||
cleanup the session directory, and thereby remove the contact
|
||||
information for a tool that is continuing to execute.
|
||||
|
||||
|
||||
Tools
|
||||
-----
|
||||
|
||||
In the case of tools, the rendezvous files containing connection
|
||||
information for a target server are located in the session directory
|
||||
tree. Thus, it may be necessary to point the tool at the location
|
||||
where those files can be found if that location is other than the
|
||||
expected default.
|
||||
@@ -0,0 +1,68 @@
|
||||
.. _label-version-numbers:
|
||||
|
||||
Software Version Numbers
|
||||
========================
|
||||
|
||||
PRRTE'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: PRRTE 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 PRRTE 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
|
||||
``prrte-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.
|
||||
|
||||
PRRTE's Git master branch contains a single ``dev`` tag. For example,
|
||||
``prrte-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.
|
||||
Reference in New Issue
Block a user