Upgrade MPIs on linux
This commit is contained in:
Bassem Girgis
@@ -0,0 +1,197 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>11.2. GitHub, Git, and related topics — PMIx Reference Run Time Environment 3.0.8 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
|
||||
|
||||
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/jquery.js"></script>
|
||||
<script src="../_static/underscore.js"></script>
|
||||
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<script src="../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="11.3. Manually installing the GNU Autootools" href="gnu-autotools.html" />
|
||||
<link rel="prev" title="11.1. Prerequisites" href="prerequisites.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../index.html" class="icon icon-home">
|
||||
PMIx Reference Run Time Environment
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">2. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">3. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../install.html">4. Installing PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../configuration.html">5. PRRTE DVM Configuration</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../how-things-work/index.html">6. How Things Work</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../hosts/index.html">7. Host specification</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../placement/index.html">8. Process placement</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../notifications.html">9. Notifications</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../session-directory.html">10. Session directory</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">11. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">11.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">11.2. GitHub, Git, and related topics</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#github">11.2.1. GitHub</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#git-commits-open-source-contributor-s-declaration">11.2.2. Git commits: open source / contributor’s declaration</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#git-branch-scheme">11.2.3. Git branch scheme</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">11.3. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">11.4. Installing and running Sphinx (building the PRRTE docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">11.5. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">12. Contributing to PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">13. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">14. PRRTE manual pages</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">15. Software Version Numbers</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../index.html">PMIx Reference Run Time Environment</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="index.html"><span class="section-number">11. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">11.2. </span>GitHub, Git, and related topics</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/git-github.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<style>
|
||||
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
|
||||
</style><div class="section" id="github-git-and-related-topics">
|
||||
<h1><span class="section-number">11.2. </span>GitHub, Git, and related topics<a class="headerlink" href="#github-git-and-related-topics" title="Permalink to this heading"></a></h1>
|
||||
<div class="section" id="github">
|
||||
<h2><span class="section-number">11.2.1. </span>GitHub<a class="headerlink" href="#github" title="Permalink to this heading"></a></h2>
|
||||
<p>PRRTE’s Git repositories are <a class="reference external" href="https://github.com/openpmix/prrte">hosted at GitHub</a>.</p>
|
||||
<ol class="arabic">
|
||||
<li><p>First, you will need a Git client. We recommend getting the latest
|
||||
version available. If you do not have the command <code class="docutils literal notranslate"><span class="pre">git</span></code> in your
|
||||
path, you will likely need to download and install Git.</p></li>
|
||||
<li><p><a class="reference external" href="https://github.com/openpmix/prrte/">prrte</a> is the main PRRTE
|
||||
repository where most active development is done. Git clone this
|
||||
repository. Note that the use of the <code class="docutils literal notranslate"><span class="pre">--recursive</span></code> CLI option is
|
||||
necessary because PRRTE uses Git submodules:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>shell$ git clone --recursive https://github.com/openpmix/prrte.git
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Note that Git is natively capable of using many forms of web
|
||||
proxies. If your network setup requires the user of a web proxy,
|
||||
<a class="reference external" href="https://git-scm.com/">consult the Git documentation for more details</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="git-commits-open-source-contributor-s-declaration">
|
||||
<h2><span class="section-number">11.2.2. </span>Git commits: open source / contributor’s declaration<a class="headerlink" href="#git-commits-open-source-contributor-s-declaration" title="Permalink to this heading"></a></h2>
|
||||
<p>In order to remain open source, all new commits to the PRRTE
|
||||
repository must include a <code class="docutils literal notranslate"><span class="pre">Signed-off-by:</span></code> line, indicating the
|
||||
submitter’s agreement to the <a class="reference internal" href="../contributing.html#contributing-contributors-declaration-label"><span class="std std-ref">PRRTE Contributor’s Declaration</span></a>.</p>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>You can use the <code class="docutils literal notranslate"><span class="pre">-s</span></code> option to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> to
|
||||
automatically add the <code class="docutils literal notranslate"><span class="pre">Signed-off-by:</span></code> line to your commit
|
||||
message.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="git-branch-scheme">
|
||||
<span id="git-github-branch-scheme-label"></span><h2><span class="section-number">11.2.3. </span>Git branch scheme<a class="headerlink" href="#git-branch-scheme" title="Permalink to this heading"></a></h2>
|
||||
<p>Generally, PRRTE has two types of branches in its Git repository:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">main</span></code>:</p>
|
||||
<ul class="simple">
|
||||
<li><p>All active development occurs on the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch (new features,
|
||||
bug fixes, etc.).</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><p>Release branches of the form <code class="docutils literal notranslate"><span class="pre">vMAJOR.MINOR.x</span></code> (e.g., <code class="docutils literal notranslate"><span class="pre">v4.0.x</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">v4.1.x</span></code>, <code class="docutils literal notranslate"><span class="pre">v5.0.x</span></code>).</p>
|
||||
<ul class="simple">
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">.x</span></code> suffix indicates that this branch is used to create
|
||||
all releases in the PRRTE vMAJOR.MINOR series.</p></li>
|
||||
<li><p>Periodically, the PRRTE community will make a new release
|
||||
branch, typically from <code class="docutils literal notranslate"><span class="pre">main</span></code>.</p></li>
|
||||
<li><p>A Git tag of the form <code class="docutils literal notranslate"><span class="pre">vMAJOR.MINOR.RELEASE</span></code> is used to
|
||||
indicate the specific commit on a release branch from where
|
||||
official PRRTE release tarball was created (e.g., <code class="docutils literal notranslate"><span class="pre">v4.1.0</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">v4.1.1</span></code>, <code class="docutils literal notranslate"><span class="pre">v4.1.2</span></code>, etc.).</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="prerequisites.html" class="btn btn-neutral float-left" title="11.1. Prerequisites" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="gnu-autotools.html" class="btn btn-neutral float-right" title="11.3. Manually installing the GNU Autootools" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2003-2025, The PRRTE Community.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,484 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>11.3. Manually installing the GNU Autootools — PMIx Reference Run Time Environment 3.0.8 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
|
||||
|
||||
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/jquery.js"></script>
|
||||
<script src="../_static/underscore.js"></script>
|
||||
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<script src="../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="11.4. Installing and running Sphinx (building the PRRTE docs)" href="sphinx.html" />
|
||||
<link rel="prev" title="11.2. GitHub, Git, and related topics" href="git-github.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../index.html" class="icon icon-home">
|
||||
PMIx Reference Run Time Environment
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">2. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">3. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../install.html">4. Installing PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../configuration.html">5. PRRTE DVM Configuration</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../how-things-work/index.html">6. How Things Work</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../hosts/index.html">7. Host specification</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../placement/index.html">8. Process placement</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../notifications.html">9. Notifications</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../session-directory.html">10. Session directory</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">11. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">11.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">11.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">11.3. Manually installing the GNU Autootools</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#use-a-package-manager">11.3.1. Use a package manager</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#autotools-versions">11.3.2. Autotools versions</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#checking-your-versions">11.3.3. Checking your versions</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#installing-the-gnu-autotools-from-source">11.3.4. Installing the GNU Autotools from source</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#build-and-install-ordering">11.3.5. Build and install ordering</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">11.4. Installing and running Sphinx (building the PRRTE docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">11.5. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">12. Contributing to PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">13. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">14. PRRTE manual pages</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">15. Software Version Numbers</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../index.html">PMIx Reference Run Time Environment</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="index.html"><span class="section-number">11. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">11.3. </span>Manually installing the GNU Autootools</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/gnu-autotools.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<style>
|
||||
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
|
||||
</style><div class="section" id="manually-installing-the-gnu-autootools">
|
||||
<span id="developers-installing-autotools-label"></span><h1><span class="section-number">11.3. </span>Manually installing the GNU Autootools<a class="headerlink" href="#manually-installing-the-gnu-autootools" title="Permalink to this heading"></a></h1>
|
||||
<p>There is enough detail in building the GNU Autotools that it warrants
|
||||
its own section.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>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 <em>not</em>
|
||||
need to have the GNU Autotools installed.</p>
|
||||
</div>
|
||||
<div class="section" id="use-a-package-manager">
|
||||
<h2><span class="section-number">11.3.1. </span>Use a package manager<a class="headerlink" href="#use-a-package-manager" title="Permalink to this heading"></a></h2>
|
||||
<p>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.</p>
|
||||
<p>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).</p>
|
||||
</div>
|
||||
<div class="section" id="autotools-versions">
|
||||
<h2><span class="section-number">11.3.2. </span>Autotools versions<a class="headerlink" href="#autotools-versions" title="Permalink to this heading"></a></h2>
|
||||
<p>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):</p>
|
||||
<table class="docutils align-default">
|
||||
<colgroup>
|
||||
<col style="width: 33%" />
|
||||
<col style="width: 33%" />
|
||||
<col style="width: 33%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Software package</p></th>
|
||||
<th class="head"><p>Notes</p></th>
|
||||
<th class="head"><p>URL</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p>GNU m4</p></td>
|
||||
<td><p>See version chart below</p></td>
|
||||
<td><p><a class="reference external" href="https://ftp.gnu.org/gnu/m4/">https://ftp.gnu.org/gnu/m4/</a></p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>GNU Autoconf</p></td>
|
||||
<td><p>See version chart below</p></td>
|
||||
<td><p><a class="reference external" href="https://ftp.gnu.org/gnu/autoconf/">https://ftp.gnu.org/gnu/autoconf/</a></p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>GNU Automake</p></td>
|
||||
<td><p>See version chart below</p></td>
|
||||
<td><p><a class="reference external" href="https://ftp.gnu.org/gnu/automake/">https://ftp.gnu.org/gnu/automake/</a></p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>GNU Libtool</p></td>
|
||||
<td><p>See version chart below</p></td>
|
||||
<td><p><a class="reference external" href="https://ftp.gnu.org/gnu/libtool/">https://ftp.gnu.org/gnu/libtool/</a></p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The table below lists the versions that are used to make nightly
|
||||
snapshot and official release PRRTE tarballs. Other versions of the
|
||||
tools <em>may</em> 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.</p>
|
||||
<p>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).</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>You <strong>will</strong> have problems if you do not use recent
|
||||
versions of the GNU Autotools.</p>
|
||||
</div>
|
||||
<p>That being said, <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> and <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code> 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).</p>
|
||||
<p>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 — especially if you are
|
||||
not building on Linux x86_64 with the GNU compilers.</p>
|
||||
<p>Using older versions is unsupported. If you run into problems, upgrade
|
||||
to at least the versions listed below.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>You may need to scroll right in the following table.</p>
|
||||
</div>
|
||||
<div class="error admonition">
|
||||
<p class="admonition-title">PRRTE Docs TODO</p>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
<table class="docutils align-default">
|
||||
<colgroup>
|
||||
<col style="width: 14%" />
|
||||
<col style="width: 14%" />
|
||||
<col style="width: 14%" />
|
||||
<col style="width: 14%" />
|
||||
<col style="width: 14%" />
|
||||
<col style="width: 14%" />
|
||||
<col style="width: 14%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>PRRTE</p></th>
|
||||
<th class="head"><p>M4</p></th>
|
||||
<th class="head"><p>Autoconf</p></th>
|
||||
<th class="head"><p>Automake</p></th>
|
||||
<th class="head"><p>Libtool</p></th>
|
||||
<th class="head"><p>Flex</p></th>
|
||||
<th class="head"><p>Sphinx</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p>v1.0.x</p></td>
|
||||
<td><p>NA</p></td>
|
||||
<td><p>2.58 - 2.59</p></td>
|
||||
<td><p>1.7 - 1.9.6</p></td>
|
||||
<td><p>1.5.16 - 1.5.22</p></td>
|
||||
<td><p>2.5.4</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>v1.1.x</p></td>
|
||||
<td><p>NA</p></td>
|
||||
<td><p>2.59</p></td>
|
||||
<td><p>1.9.6</p></td>
|
||||
<td><p>1.5.16 - 1.5.22</p></td>
|
||||
<td><p>2.5.4</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>v1.2.x</p></td>
|
||||
<td><p>NA</p></td>
|
||||
<td><p>2.59</p></td>
|
||||
<td><p>1.9.6</p></td>
|
||||
<td><p>1.5.22 - 2.1a</p></td>
|
||||
<td><p>2.5.4</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>v1.3.x</p></td>
|
||||
<td><p>1.4.11</p></td>
|
||||
<td><p>2.63</p></td>
|
||||
<td><p>1.10.1</p></td>
|
||||
<td><p>2.2.6b</p></td>
|
||||
<td><p>2.5.4</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>v1.4.x</p></td>
|
||||
<td><p>1.4.11</p></td>
|
||||
<td><p>2.63</p></td>
|
||||
<td><p>1.10.3</p></td>
|
||||
<td><p>2.2.6b</p></td>
|
||||
<td><p>2.5.4</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>v1.5.x for x=0-4</p></td>
|
||||
<td><p>1.4.13</p></td>
|
||||
<td><p>2.65</p></td>
|
||||
<td><p>1.11.1</p></td>
|
||||
<td><p>2.2.6b</p></td>
|
||||
<td><p>2.5.4</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>v1.5.x for x>=5</p></td>
|
||||
<td><p>1.4.16</p></td>
|
||||
<td><p>2.68</p></td>
|
||||
<td><p>1.11.3</p></td>
|
||||
<td><p>2.4.2</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>v1.6.x</p></td>
|
||||
<td><p>1.4.16</p></td>
|
||||
<td><p>2.68</p></td>
|
||||
<td><p>1.11.3</p></td>
|
||||
<td><p>2.4.2</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>v1.7.x</p></td>
|
||||
<td><p>1.4.16</p></td>
|
||||
<td><p>2.69</p></td>
|
||||
<td><p>1.12.2</p></td>
|
||||
<td><p>2.4.2</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>v1.8.x</p></td>
|
||||
<td><p>1.4.16</p></td>
|
||||
<td><p>2.69</p></td>
|
||||
<td><p>1.12.2</p></td>
|
||||
<td><p>2.4.2</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>v1.10.x</p></td>
|
||||
<td><p>1.4.16</p></td>
|
||||
<td><p>2.69</p></td>
|
||||
<td><p>1.12.2</p></td>
|
||||
<td><p>2.4.2</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>v2.0.x through v4.y</p></td>
|
||||
<td><p>1.4.17</p></td>
|
||||
<td><p>2.69</p></td>
|
||||
<td><p>1.15</p></td>
|
||||
<td><p>2.4.6</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>NA</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>v5.0.x</p></td>
|
||||
<td><p>1.4.17</p></td>
|
||||
<td><p>2.69</p></td>
|
||||
<td><p>1.15</p></td>
|
||||
<td><p>2.4.6</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>4.2.0</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Git main</p></td>
|
||||
<td><p>1.4.17</p></td>
|
||||
<td><p>2.69</p></td>
|
||||
<td><p>1.15</p></td>
|
||||
<td><p>2.4.6</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p>4.2.0</p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<div class="section" id="checking-your-versions">
|
||||
<h2><span class="section-number">11.3.3. </span>Checking your versions<a class="headerlink" href="#checking-your-versions" title="Permalink to this heading"></a></h2>
|
||||
<p>You can check what versions of the Autotools you have installed with
|
||||
the following:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>m4<span class="w"> </span>--version
|
||||
shell$<span class="w"> </span>autoconf<span class="w"> </span>--version
|
||||
shell$<span class="w"> </span>automake<span class="w"> </span>--version
|
||||
shell$<span class="w"> </span>libtoolize<span class="w"> </span>--version
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="installing-the-gnu-autotools-from-source">
|
||||
<h2><span class="section-number">11.3.4. </span>Installing the GNU Autotools from source<a class="headerlink" href="#installing-the-gnu-autotools-from-source" title="Permalink to this heading"></a></h2>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
<p>The GNU Autotools sources can be can be downloaded from:</p>
|
||||
<ul class="simple">
|
||||
<li><p><a class="reference external" href="https://ftp.gnu.org/gnu/autoconf/">https://ftp.gnu.org/gnu/autoconf/</a></p></li>
|
||||
<li><p><a class="reference external" href="https://ftp.gnu.org/gnu/automake/">https://ftp.gnu.org/gnu/automake/</a></p></li>
|
||||
<li><p><a class="reference external" href="https://ftp.gnu.org/gnu/libtool/">https://ftp.gnu.org/gnu/libtool/</a></p></li>
|
||||
<li><p>And if you need it: <a class="reference external" href="https://ftp.gnu.org/gnu/m4/">https://ftp.gnu.org/gnu/m4/</a></p></li>
|
||||
</ul>
|
||||
<p>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 <em>need</em> 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.</p>
|
||||
</div>
|
||||
<div class="section" id="build-and-install-ordering">
|
||||
<h2><span class="section-number">11.3.5. </span>Build and install ordering<a class="headerlink" href="#build-and-install-ordering" title="Permalink to this heading"></a></h2>
|
||||
<p>You must build and install the GNU Autotools in the following order:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>m4</p></li>
|
||||
<li><p>Autoconf</p></li>
|
||||
<li><p>Automake</p></li>
|
||||
<li><p>Libtool</p></li>
|
||||
</ol>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>You <em>must</em> 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 <em>must</em> share a
|
||||
common installation prefix.</p>
|
||||
</div>
|
||||
<p>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.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>It is <em>strongly</em> encouraged that you do <strong>not</strong> install
|
||||
your new versions over the OS-installed versions. This could cause
|
||||
other things on your system to break. Instead, install into
|
||||
<code class="docutils literal notranslate"><span class="pre">$HOME/local</span></code>, or <code class="docutils literal notranslate"><span class="pre">/usr/local</span></code>, or wherever else you tend to
|
||||
install “local” kinds of software.</p>
|
||||
<p>In doing so, be sure to prefix your <code class="docutils literal notranslate"><span class="pre">$PATH</span></code> with the directory
|
||||
where they are installed. For example, if you install into
|
||||
<code class="docutils literal notranslate"><span class="pre">$HOME/local</span></code>, you may want to edit your shell startup file
|
||||
(<code class="docutils literal notranslate"><span class="pre">.bashrc</span></code>, <code class="docutils literal notranslate"><span class="pre">.cshrc</span></code>, <code class="docutils literal notranslate"><span class="pre">.tcshrc</span></code>, etc.) to have something
|
||||
like</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># For bash/sh:</span>
|
||||
<span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="nv">$HOME</span>/local/bin:<span class="nv">$PATH</span>
|
||||
<span class="c1"># For csh/tcsh:</span>
|
||||
<span class="nb">set</span><span class="w"> </span><span class="nv">path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">(</span><span class="nv">$HOME</span>/local/bin<span class="w"> </span><span class="nv">$path</span><span class="o">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Ensure to set your <code class="docutils literal notranslate"><span class="pre">$PATH</span></code> <em>before</em> you configure/build/install
|
||||
the four packages.</p>
|
||||
</div>
|
||||
<p>All four packages require two simple commands to build and
|
||||
install:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>M4_DIRECTORY
|
||||
shell$<span class="w"> </span>./configure<span class="w"> </span>--prefix<span class="o">=</span>PREFIX
|
||||
shell$<span class="w"> </span>make<span class="w"> </span>all<span class="w"> </span>install
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>If you are using a shell that does not automatically
|
||||
re-index the <code class="docutils literal notranslate"><span class="pre">$PATH</span></code> (e.g., the <code class="docutils literal notranslate"><span class="pre">csh</span></code> or <code class="docutils literal notranslate"><span class="pre">tcsh</span></code>
|
||||
shells), be sure to run the <code class="docutils literal notranslate"><span class="pre">rehash</span></code> command before
|
||||
you install the next package so that the executables
|
||||
that were just installed can be found by the next
|
||||
package.</p>
|
||||
</div>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Make $PATH be re-indexed if necessary, e.g., via "rehash"</span>
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>AUTOCONF_DIRECTORY
|
||||
shell$<span class="w"> </span>./configure<span class="w"> </span>--prefix<span class="o">=</span>PREFIX
|
||||
shell$<span class="w"> </span>make<span class="w"> </span>all<span class="w"> </span>install
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Make $PATH be re-indexed if necessary, e.g., via "rehash"</span>
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>AUTOMAKE_DIRECTORY
|
||||
shell$<span class="w"> </span>./configure<span class="w"> </span>--prefix<span class="o">=</span>PREFIX
|
||||
shell$<span class="w"> </span>make<span class="w"> </span>all<span class="w"> </span>install
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Make $PATH be re-indexed if necessary, e.g., via "rehash"</span>
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>LIBTOOL_DIRECTORY
|
||||
shell$<span class="w"> </span>./configure<span class="w"> </span>--prefix<span class="o">=</span>PREFIX
|
||||
shell$<span class="w"> </span>make<span class="w"> </span>all<span class="w"> </span>install
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="git-github.html" class="btn btn-neutral float-left" title="11.2. GitHub, Git, and related topics" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="sphinx.html" class="btn btn-neutral float-right" title="11.4. Installing and running Sphinx (building the PRRTE docs)" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2003-2025, The PRRTE Community.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
148
linx64/mpi/openmpi/share/doc/prrte/html/developers/index.html
Normal file
148
linx64/mpi/openmpi/share/doc/prrte/html/developers/index.html
Normal file
@@ -0,0 +1,148 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>11. Developer’s guide — PMIx Reference Run Time Environment 3.0.8 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
|
||||
|
||||
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/jquery.js"></script>
|
||||
<script src="../_static/underscore.js"></script>
|
||||
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<script src="../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="11.1. Prerequisites" href="prerequisites.html" />
|
||||
<link rel="prev" title="10. Session directory" href="../session-directory.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../index.html" class="icon icon-home">
|
||||
PMIx Reference Run Time Environment
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">2. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">3. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../install.html">4. Installing PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../configuration.html">5. PRRTE DVM Configuration</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../how-things-work/index.html">6. How Things Work</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../hosts/index.html">7. Host specification</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../placement/index.html">8. Process placement</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../notifications.html">9. Notifications</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../session-directory.html">10. Session directory</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">11. Developer’s guide</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">11.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">11.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">11.3. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">11.4. Installing and running Sphinx (building the PRRTE docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">11.5. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">12. Contributing to PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">13. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">14. PRRTE manual pages</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">15. Software Version Numbers</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../index.html">PMIx Reference Run Time Environment</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">11. </span>Developer’s guide</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/index.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<style>
|
||||
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
|
||||
</style><div class="section" id="developer-s-guide">
|
||||
<h1><span class="section-number">11. </span>Developer’s guide<a class="headerlink" href="#developer-s-guide" title="Permalink to this heading"></a></h1>
|
||||
<p>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).</p>
|
||||
<p>If you are simply <em>using</em> PRRTE, you probably don’t need to read this
|
||||
section.</p>
|
||||
<div class="toctree-wrapper compound">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="prerequisites.html">11.1. Prerequisites</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="git-github.html">11.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="gnu-autotools.html">11.3. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="sphinx.html">11.4. Installing and running Sphinx (building the PRRTE docs)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="rst-for-markdown-expats.html">11.5. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="../session-directory.html" class="btn btn-neutral float-left" title="10. Session directory" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="prerequisites.html" class="btn btn-neutral float-right" title="11.1. Prerequisites" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2003-2025, The PRRTE Community.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,265 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>11.1. Prerequisites — PMIx Reference Run Time Environment 3.0.8 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
|
||||
|
||||
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/jquery.js"></script>
|
||||
<script src="../_static/underscore.js"></script>
|
||||
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<script src="../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="11.2. GitHub, Git, and related topics" href="git-github.html" />
|
||||
<link rel="prev" title="11. Developer’s guide" href="index.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../index.html" class="icon icon-home">
|
||||
PMIx Reference Run Time Environment
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">2. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">3. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../install.html">4. Installing PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../configuration.html">5. PRRTE DVM Configuration</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../how-things-work/index.html">6. How Things Work</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../hosts/index.html">7. Host specification</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../placement/index.html">8. Process placement</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../notifications.html">9. Notifications</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../session-directory.html">10. Session directory</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">11. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">11.1. Prerequisites</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#compilers">11.1.1. Compilers</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#gnu-autotools">11.1.2. GNU Autotools</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#perl">11.1.3. Perl</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#flex">11.1.4. Flex</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#sphinx-and-therefore-python">11.1.5. Sphinx (and therefore Python)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">11.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">11.3. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">11.4. Installing and running Sphinx (building the PRRTE docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">11.5. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">12. Contributing to PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">13. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">14. PRRTE manual pages</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">15. Software Version Numbers</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../index.html">PMIx Reference Run Time Environment</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="index.html"><span class="section-number">11. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">11.1. </span>Prerequisites</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/prerequisites.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<style>
|
||||
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
|
||||
</style><div class="section" id="prerequisites">
|
||||
<h1><span class="section-number">11.1. </span>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h1>
|
||||
<div class="section" id="compilers">
|
||||
<h2><span class="section-number">11.1.1. </span>Compilers<a class="headerlink" href="#compilers" title="Permalink to this heading"></a></h2>
|
||||
<p>Although it should probably be assumed, you’ll need a C compiler that
|
||||
supports C99.</p>
|
||||
</div>
|
||||
<div class="section" id="gnu-autotools">
|
||||
<h2><span class="section-number">11.1.2. </span>GNU Autotools<a class="headerlink" href="#gnu-autotools" title="Permalink to this heading"></a></h2>
|
||||
<p>When building PRRTE from its repository sources, the GNU Autotools
|
||||
must be installed (i.e., <a class="reference external" href="https://www.gnu.org/software/autoconf/">GNU Autoconf</a>, <a class="reference external" href="https://www.gnu.org/software/automake/">GNU Automake</a>, and <a class="reference external" href="https://www.gnu.org/software/libtool/">GNU Libtool</a>).</p>
|
||||
<table class="colwidths-given docutils align-default">
|
||||
<colgroup>
|
||||
<col style="width: 50%" />
|
||||
<col style="width: 50%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Tool</p></th>
|
||||
<th class="head"><p>Minimum version</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p>Autoconf</p></td>
|
||||
<td><p>2.69.0</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Automake</p></td>
|
||||
<td><p>1.13.4</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Libtool</p></td>
|
||||
<td><p>2.4.2</p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The GNU Autotools are <em>not</em> 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.</p>
|
||||
</div>
|
||||
<p>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.”</p>
|
||||
<p>If you run into problems with the GNU Autotools, or need to download /
|
||||
build them manually, see the <a class="reference internal" href="gnu-autotools.html#developers-installing-autotools-label"><span class="std std-ref">how to build and install GNU
|
||||
Autotools section</span></a> for much
|
||||
more detail.</p>
|
||||
</div>
|
||||
<div class="section" id="perl">
|
||||
<h2><span class="section-number">11.1.3. </span>Perl<a class="headerlink" href="#perl" title="Permalink to this heading"></a></h2>
|
||||
<p>PRRTE still uses Perl for a few of its build scripts (most notably,
|
||||
<code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code>).</p>
|
||||
<p>Generally speaking, any recent-ish release of Perl 5 should be
|
||||
sufficient to correctly execute PRRTE’s Perl scripts.</p>
|
||||
</div>
|
||||
<div class="section" id="flex">
|
||||
<h2><span class="section-number">11.1.4. </span>Flex<a class="headerlink" href="#flex" title="Permalink to this heading"></a></h2>
|
||||
<p>Minimum supported version: 2.5.4.</p>
|
||||
<p><a class="reference external" href="https://github.com/westes/flex">Flex</a> is used during the
|
||||
compilation of a developer’s checkout (it is not used to build
|
||||
official distribution tarballs). Other flavors of lex are <em>not</em>
|
||||
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.</p>
|
||||
<p>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.</p>
|
||||
<p>For now, PRRTE will allow developer builds with Flex 2.5.4. 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.</p>
|
||||
<p>Note that the <code class="docutils literal notranslate"><span class="pre">flex</span></code>-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.</p>
|
||||
<p>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 <a class="reference external" href="https://github.com/westes/flex">the Flex Github repository</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="sphinx-and-therefore-python">
|
||||
<h2><span class="section-number">11.1.5. </span>Sphinx (and therefore Python)<a class="headerlink" href="#sphinx-and-therefore-python" title="Permalink to this heading"></a></h2>
|
||||
<p><a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a> 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.</p>
|
||||
<p>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.</p>
|
||||
<p>However, the HTML documentation and man pages are <em>not</em> 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.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>Most systems do not have Sphinx and/or the required
|
||||
Python modules installed by default. <a class="reference internal" href="sphinx.html#developers-installing-sphinx-label"><span class="std std-ref">See the
|
||||
Installing Sphinx section</span></a> for details on
|
||||
how to install Sphinx and the required Python modules.</p>
|
||||
</div>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">configure</span></code> 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 <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">all</span></code>).
|
||||
If <code class="docutils literal notranslate"><span class="pre">configure</span></code> is <em>not</em> able to find Sphinx and/or the required
|
||||
Python modules, it will simply skip building the documentation.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>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.</p>
|
||||
<p><a class="reference internal" href="sphinx.html#developers-installing-sphinx-label"><span class="std std-ref">See the Installing Sphinx section</span></a> for details on how
|
||||
to install Sphinx and the required Python modules.</p>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">dist</span></code> will fail if <code class="docutils literal notranslate"><span class="pre">configure</span></code> did not find
|
||||
Sphinx and/or the required Python modules.
|
||||
Specifically: if <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">dist</span></code> is not able to generate
|
||||
the most up-to-date HTML documentation and man pages,
|
||||
you cannot build a distribution tarball. <strong>This is an
|
||||
intentional design decision.</strong></p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="index.html" class="btn btn-neutral float-left" title="11. Developer’s guide" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="git-github.html" class="btn btn-neutral float-right" title="11.2. GitHub, Git, and related topics" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2003-2025, The PRRTE Community.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,557 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>11.5. ReStructured Text for those who know Markdown — PMIx Reference Run Time Environment 3.0.8 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
|
||||
|
||||
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/jquery.js"></script>
|
||||
<script src="../_static/underscore.js"></script>
|
||||
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<script src="../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="12. Contributing to PRRTE" href="../contributing.html" />
|
||||
<link rel="prev" title="11.4. Installing and running Sphinx (building the PRRTE docs)" href="sphinx.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../index.html" class="icon icon-home">
|
||||
PMIx Reference Run Time Environment
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">2. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">3. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../install.html">4. Installing PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../configuration.html">5. PRRTE DVM Configuration</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../how-things-work/index.html">6. How Things Work</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../hosts/index.html">7. Host specification</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../placement/index.html">8. Process placement</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../notifications.html">9. Notifications</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../session-directory.html">10. Session directory</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">11. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">11.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">11.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">11.3. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">11.4. Installing and running Sphinx (building the PRRTE docs)</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">11.5. ReStructured Text for those who know Markdown</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#whitespace-and-indenting">11.5.1. Whitespace and indenting</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#fixed-width-font">11.5.2. Fixed width font</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#italics">11.5.3. Italics</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#boldface">11.5.4. Boldface</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#chapter-and-section-delimiters">11.5.5. Chapter and section delimiters</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#multi-line-code-fixed-width-font">11.5.6. Multi-line code/fixed-width font</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#un-numbered-bullets">11.5.7. Un-numbered bullets</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#numbered-bullets">11.5.8. Numbered bullets:</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#comments">11.5.9. Comments</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#including-files">11.5.10. Including files</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#hyperlinks-to-urls">11.5.11. Hyperlinks to URLs</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#hyperlinks-to-anchors">11.5.12. Hyperlinks to anchors</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#hyperlinks-to-other-rst-pages">11.5.13. Hyperlinks to other (RST) pages</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#macros">11.5.14. Macros</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#brightly-colored-boxes">11.5.15. Brightly-colored boxes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">12. Contributing to PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">13. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">14. PRRTE manual pages</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">15. Software Version Numbers</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../index.html">PMIx Reference Run Time Environment</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="index.html"><span class="section-number">11. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">11.5. </span>ReStructured Text for those who know Markdown</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/rst-for-markdown-expats.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<style>
|
||||
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
|
||||
</style><div class="section" id="restructured-text-for-those-who-know-markdown">
|
||||
<span id="developers-rst-for-markdown-expats"></span><h1><span class="section-number">11.5. </span>ReStructured Text for those who know Markdown<a class="headerlink" href="#restructured-text-for-those-who-know-markdown" title="Permalink to this heading"></a></h1>
|
||||
<p>You can think of RST as “Markdown, but much better”. Meaning:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>RST is basically just as simple as Markdown</p></li>
|
||||
<li><p>But RST is both more precise, and has more available formatting
|
||||
constructs (without getting crazy complicated)</p></li>
|
||||
</ol>
|
||||
<p>The full Sphinx / RST documentation is available here:
|
||||
<a class="reference external" href="https://www.sphinx-doc.org/en/master/index.html">https://www.sphinx-doc.org/en/master/index.html</a></p>
|
||||
<p>If you’re familiar with Markdown, the following sections contain some
|
||||
tips to get you started in RST.</p>
|
||||
<div class="section" id="whitespace-and-indenting">
|
||||
<h2><span class="section-number">11.5.1. </span>Whitespace and indenting<a class="headerlink" href="#whitespace-and-indenting" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>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.</p></li>
|
||||
<li><p>RST: <strong>Indenting matters</strong>. 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</p>
|
||||
<p><strong>Blank lines also matter</strong>. 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.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>RST was created by the Python community. Hence,
|
||||
whitespace is quite important.</p>
|
||||
<ul class="simple">
|
||||
<li><p>Indenting matters</p></li>
|
||||
<li><p>Blank lines between content matter</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
<div class="section" id="fixed-width-font">
|
||||
<h2><span class="section-number">11.5.2. </span>Fixed width font<a class="headerlink" href="#fixed-width-font" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: Use single quotes:</p>
|
||||
<div class="highlight-md notranslate"><div class="highlight"><pre><span></span><span class="sb">`hello world`</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>RST: Use a pair of single quotes:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="s">``hello world``</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="italics">
|
||||
<h2><span class="section-number">11.5.3. </span>Italics<a class="headerlink" href="#italics" title="Permalink to this heading"></a></h2>
|
||||
<ul class="simple">
|
||||
<li><p>MD: <code class="docutils literal notranslate"><span class="pre">*hello</span> <span class="pre">world*</span></code> or <code class="docutils literal notranslate"><span class="pre">_hello</span> <span class="pre">world_</span></code></p></li>
|
||||
<li><p>RST: <code class="docutils literal notranslate"><span class="pre">*hello</span> <span class="pre">world*</span></code></p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="boldface">
|
||||
<h2><span class="section-number">11.5.4. </span>Boldface<a class="headerlink" href="#boldface" title="Permalink to this heading"></a></h2>
|
||||
<ul class="simple">
|
||||
<li><p>MD: <code class="docutils literal notranslate"><span class="pre">**hello</span> <span class="pre">world**</span></code></p></li>
|
||||
<li><p>RST: Same as MD</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="chapter-and-section-delimiters">
|
||||
<h2><span class="section-number">11.5.5. </span>Chapter and section delimiters<a class="headerlink" href="#chapter-and-section-delimiters" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>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</p></li>
|
||||
<li><p>RST: Have a single line of text, underlined by non-ASCII
|
||||
characters.</p>
|
||||
<ul>
|
||||
<li><p>The length of the underlying <em>must</em> be at least as long as the
|
||||
line of text</p></li>
|
||||
<li><p>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.</p>
|
||||
<p>In these PRRTE docs, the sequence of underline characters we use
|
||||
are:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Chapter 1: hello world</span>
|
||||
<span class="gh">======================</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Section 1: hello world</span>
|
||||
<span class="gh">----------------------</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Subsection 1: hello world</span>
|
||||
<span class="gh">^^^^^^^^^^^^^^^^^^^^^^^^^</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Subsubsection 1: hello world</span>
|
||||
<span class="gh">++++++++++++++++++++++++++++</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Meaning: underlines made of <code class="docutils literal notranslate"><span class="pre">=</span></code> denotes chapters, underlines
|
||||
made of <code class="docutils literal notranslate"><span class="pre">-</span></code> denotes sections, underlines made of <code class="docutils literal notranslate"><span class="pre">^</span></code> denotes
|
||||
subsections, and underlines made of <code class="docutils literal notranslate"><span class="pre">+</span></code> denote subsubsections.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="multi-line-code-fixed-width-font">
|
||||
<h2><span class="section-number">11.5.6. </span>Multi-line code/fixed-width font<a class="headerlink" href="#multi-line-code-fixed-width-font" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>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.</p>
|
||||
<div class="highlight-md notranslate"><div class="highlight"><pre><span></span><span class="sb">```c</span>
|
||||
<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">printf</span><span class="p">(</span><span class="s">"Hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="p">}</span>
|
||||
<span class="sb">```</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>RST: Use <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span> <span class="pre">KEYWORD</span></code> to start a section of code.</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> c
|
||||
|
||||
int main() { printf("Hello world\n"); return 0 }
|
||||
</pre></div>
|
||||
</div>
|
||||
<ul>
|
||||
<li><p>KEYWORD indicates which syntax highlighting to use (e.g., <code class="docutils literal notranslate"><span class="pre">c</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">c++</span></code> <code class="docutils literal notranslate"><span class="pre">make</span></code>, <code class="docutils literal notranslate"><span class="pre">sh</span></code>, <code class="docutils literal notranslate"><span class="pre">ini</span></code>, <code class="docutils literal notranslate"><span class="pre">Fortran</span></code>, <code class="docutils literal notranslate"><span class="pre">diff</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">python</span></code>, <code class="docutils literal notranslate"><span class="pre">java</span></code>, <code class="docutils literal notranslate"><span class="pre">rst</span></code>, … etc.).</p></li>
|
||||
<li><p>KEYWORD can be omitted if no specific highlighting is to be
|
||||
used.</p></li>
|
||||
<li><p>There <em>MUST</em> be a blank line after the <code class="docutils literal notranslate"><span class="pre">code-block</span></code> line.</p></li>
|
||||
<li><p>The lines in the block must be indented to the same column as the
|
||||
first <code class="docutils literal notranslate"><span class="pre">c</span></code> in <code class="docutils literal notranslate"><span class="pre">code-block</span></code>. For example:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> <span class="k">sh</span>
|
||||
|
||||
shell$<span class="w"> </span>tar<span class="w"> </span>xf<span class="w"> </span>prte-<version>.tar.bz2
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>prte-<version>
|
||||
shell$<span class="w"> </span>./configure<span class="w"> </span>--prefix<span class="o">=</span><path><span class="w"> </span><span class="p">|&</span><span class="w"> </span>tee<span class="w"> </span>config.out
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Note that the code block will be rendered at the same level as
|
||||
where the first <code class="docutils literal notranslate"><span class="pre">.</span></code> of <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span></code> starts. In this
|
||||
case, the example code block will be rendered in the bulleted
|
||||
item.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Whereas this parargraph and code block will be outside of the
|
||||
above bulleted list:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>tar<span class="w"> </span>xf<span class="w"> </span>prte-<version>.tar.bz2
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>prte-<version>
|
||||
shell$<span class="w"> </span>./configure<span class="w"> </span>--prefix<span class="o">=</span><path><span class="w"> </span><span class="p">|&</span><span class="w"> </span>tee<span class="w"> </span>config.out
|
||||
|
||||
<span class="c1"># Fun note: the code-block can contain blank lines.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The code-block is terminated by a blank line and then outdent back
|
||||
to the same level as the first <code class="docutils literal notranslate"><span class="pre">.</span></code> in <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span></code>.</p>
|
||||
</div>
|
||||
<div class="section" id="un-numbered-bullets">
|
||||
<h2><span class="section-number">11.5.7. </span>Un-numbered bullets<a class="headerlink" href="#un-numbered-bullets" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: Start lines with <code class="docutils literal notranslate"><span class="pre">*</span></code> or <code class="docutils literal notranslate"><span class="pre">-</span></code></p></li>
|
||||
<li><p>RST: Start lines with <code class="docutils literal notranslate"><span class="pre">*</span></code>. You can wrap lines at the same
|
||||
indenting level to make paragraphs in the same bullet.</p>
|
||||
<p>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.</p>
|
||||
<ul>
|
||||
<li><p>For example, you can start a sub bullet.</p>
|
||||
<p>This text is the next paragraph in the same sub bullet.</p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>This is a verbatim code block within this same sub bullet.
|
||||
More about code-blocks below.
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This is the next paragraph (after the code block) in the same
|
||||
sub bullet.</p>
|
||||
</li>
|
||||
<li><p>If you start a new bullet, that terminates the previous bullet.</p></li>
|
||||
<li><p>You <strong>MUST</strong> put blank lines between bullets!</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="numbered-bullets">
|
||||
<h2><span class="section-number">11.5.8. </span>Numbered bullets:<a class="headerlink" href="#numbered-bullets" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: Start lines with <code class="docutils literal notranslate"><span class="pre">#</span></code></p></li>
|
||||
<li><p>RST: Start lines with <code class="docutils literal notranslate"><span class="pre">#.</span></code></p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>Yes, the trailing <code class="docutils literal notranslate"><span class="pre">.</span></code> is important</p>
|
||||
</div>
|
||||
<p>For example:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="m">#.</span> Item number 1
|
||||
<span class="m">#.</span> The second item
|
||||
<span class="m">#.</span> A third item
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>All the same rules for indentation apply as described above.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="comments">
|
||||
<h2><span class="section-number">11.5.9. </span>Comments<a class="headerlink" href="#comments" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: Enclose content in <code class="docutils literal notranslate"><span class="pre"><!--</span></code> and <code class="docutils literal notranslate"><span class="pre">--></span></code> (i.e., HTML comments,
|
||||
but they are included in the output)</p></li>
|
||||
<li><p>RST: Start a line with two periods and a space.</p>
|
||||
<p>For example, the following block is a comment, and will not be
|
||||
included in the output:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="cp">.. Hello world. This is a comment. This whole block is a</span>
|
||||
<span class="cp"> comment. You can leave it here in the final document, and it</span>
|
||||
<span class="cp"> will not be included in the rendered output.</span>
|
||||
|
||||
<span class="cp"> Your comment can even include blank lines. You terminate a</span>
|
||||
<span class="cp"> comment -- just like most other things in RST -- by a blank</span>
|
||||
<span class="cp"> line and then outdenting back out to the same column as the</span>
|
||||
<span class="cp"> first ".".</span>
|
||||
|
||||
This line is no longer part of the comment.
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="including-files">
|
||||
<h2><span class="section-number">11.5.10. </span>Including files<a class="headerlink" href="#including-files" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: You cannot include files in Markdown.</p></li>
|
||||
<li><p>RST: Use the <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">include::</span> <span class="pre">FILENAME</span></code> directive. For example:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">include</span><span class="p">::</span> features-extensions.rst
|
||||
<span class="p">..</span> <span class="ow">include</span><span class="p">::</span> features-java.rst
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Those directives include those 2 files right here in this RST file.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>Chapter/section/subsection delimiters will be
|
||||
continued in those files as part of rendering this
|
||||
file.</p>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="hyperlinks-to-urls">
|
||||
<h2><span class="section-number">11.5.11. </span>Hyperlinks to URLs<a class="headerlink" href="#hyperlinks-to-urls" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD:</p>
|
||||
<div class="highlight-md notranslate"><div class="highlight"><pre><span></span>[<span class="nt">this is the link text</span>](<span class="na">https://example.com/</span>)
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>RST:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="s">`this is the link text </span><span class="si"><https://example.com/></span><span class="s">`_</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>Yes, the trailing underscore in RST is important.
|
||||
It’s a little weird, but you’ll cope.</p>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="hyperlinks-to-anchors">
|
||||
<h2><span class="section-number">11.5.12. </span>Hyperlinks to anchors<a class="headerlink" href="#hyperlinks-to-anchors" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: I forget offhand how to make anchors and links to them in MD.</p></li>
|
||||
<li><p>RST: Use the <code class="docutils literal notranslate"><span class="pre">:ref:</span></code> directive.</p>
|
||||
<p>Make an anchor like this:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_ANCHOR_NAME:</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>It <em>must</em> start with and underscore and end with a colon.</p>
|
||||
<p>I’ve typically used anchor names that either begin with <code class="docutils literal notranslate"><span class="pre">label-</span></code>
|
||||
or end in <code class="docutils literal notranslate"><span class="pre">-label</span></code> to make it blatantly obvious that it’s a
|
||||
label. For example:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_building-and-installing-section-label:</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Then you can use the <code class="docutils literal notranslate"><span class="pre">:ref:</span></code> directive:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>be sure to see :ref:`the VPATH build section
|
||||
<span class="nt"><building-and-installing-section-label></span>`.
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="hyperlinks-to-other-rst-pages">
|
||||
<h2><span class="section-number">11.5.13. </span>Hyperlinks to other (RST) pages<a class="headerlink" href="#hyperlinks-to-other-rst-pages" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD:</p>
|
||||
<div class="highlight-md notranslate"><div class="highlight"><pre><span></span>[<span class="nt">link text</span>](<span class="na">page_name</span>)
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>RST: Use the <code class="docutils literal notranslate"><span class="pre">:doc:</span></code> directive.</p>
|
||||
<p>General format:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:doc:</span><span class="nv">`link text <PAGE_PATH>`</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For example:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>You should read <span class="na">:doc:</span><span class="nv">`the Developer's Guide </developers>`</span>.
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The page path is relative to the <code class="docutils literal notranslate"><span class="pre">docs</span></code> dir in the PRRTE git tree.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="macros">
|
||||
<h2><span class="section-number">11.5.14. </span>Macros<a class="headerlink" href="#macros" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: There are no macros in Markdown.</p></li>
|
||||
<li><p>RST: We have defined a few PRRTE-specific macros in RST. You can
|
||||
insert these macros anywhere in RST content text.</p>
|
||||
<ul>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">|ompi_ver|</span></code> is the full PRRTE version number, including
|
||||
alpha/beta/rc/greek denotation. For example <code class="docutils literal notranslate"><span class="pre">5.0.0rc1</span></code>.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">|ompi_series|</span></code> is the major/minor PRRTE version, e.g.,
|
||||
<code class="docutils literal notranslate"><span class="pre">5.0.x</span></code>.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">|mdash|</span></code> is a unicode long dash, an “em” dash. Use it instead
|
||||
of <code class="docutils literal notranslate"><span class="pre">--</span></code>.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">|rarrow|</span></code> is a unicode right arrow. Use it instead of <code class="docutils literal notranslate"><span class="pre">-></span></code>
|
||||
or <code class="docutils literal notranslate"><span class="pre">--></span></code>.</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="brightly-colored-boxes">
|
||||
<h2><span class="section-number">11.5.15. </span>Brightly-colored boxes<a class="headerlink" href="#brightly-colored-boxes" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>MD: There are no brightly-colored boxes in MD.</p></li>
|
||||
<li><p>RST: You can use various directives to make brightly-colored
|
||||
“note” boxes (Called admonitions) in RST. For example:</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>a green box with a “!” icon</p>
|
||||
<p>Standard indenting rules apply for the content in the box. You
|
||||
can have multiple lines and multiple paragraphs, for example.</p>
|
||||
<p>Yippee.</p>
|
||||
<ul>
|
||||
<li><p>You can even have bullets.</p>
|
||||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>You can even have code blocks inside the bullet inside the
|
||||
caution box.
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>All the standard indenting rules apply.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="admonition hint">
|
||||
<p class="admonition-title">Hint</p>
|
||||
<p>a green box with a “!” icon</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>a blue box with a “!” icon</p>
|
||||
</div>
|
||||
<div class="admonition caution">
|
||||
<p class="admonition-title">Caution</p>
|
||||
<p>an orange box with a “!” icon</p>
|
||||
</div>
|
||||
<div class="admonition attention">
|
||||
<p class="admonition-title">Attention</p>
|
||||
<p>an orange box with a “!” icon</p>
|
||||
</div>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>an orange box with a “!” icon</p>
|
||||
</div>
|
||||
<div class="admonition error">
|
||||
<p class="admonition-title">Error</p>
|
||||
<p>a red box with a “!” icon</p>
|
||||
</div>
|
||||
<div class="admonition danger">
|
||||
<p class="admonition-title">Danger</p>
|
||||
<p>a red box with a “!” icon</p>
|
||||
</div>
|
||||
<div class="tip admonition">
|
||||
<p class="admonition-title">Custom title</p>
|
||||
<p>You can name this box whatever you want:</p>
|
||||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">admonition</span><span class="p">::</span> Custom title
|
||||
<span class="nc">:class:</span> tip
|
||||
|
||||
Content of your box here.
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Custom text for this custom admonition. Note that the <code class="docutils literal notranslate"><span class="pre">:class:</span> <span class="pre"><type></span></code>
|
||||
will change the coloring to the color for the basic admonition of that
|
||||
type. E.g., <code class="docutils literal notranslate"><span class="pre">:class:</span> <span class="pre">tip</span></code> makes the box be green.</p>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="sphinx.html" class="btn btn-neutral float-left" title="11.4. Installing and running Sphinx (building the PRRTE docs)" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="../contributing.html" class="btn btn-neutral float-right" title="12. Contributing to PRRTE" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2003-2025, The PRRTE Community.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
372
linx64/mpi/openmpi/share/doc/prrte/html/developers/sphinx.html
Normal file
372
linx64/mpi/openmpi/share/doc/prrte/html/developers/sphinx.html
Normal file
@@ -0,0 +1,372 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>11.4. Installing and running Sphinx (building the PRRTE docs) — PMIx Reference Run Time Environment 3.0.8 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
|
||||
|
||||
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/jquery.js"></script>
|
||||
<script src="../_static/underscore.js"></script>
|
||||
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<script src="../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="11.5. ReStructured Text for those who know Markdown" href="rst-for-markdown-expats.html" />
|
||||
<link rel="prev" title="11.3. Manually installing the GNU Autootools" href="gnu-autotools.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../index.html" class="icon icon-home">
|
||||
PMIx Reference Run Time Environment
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">2. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">3. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../install.html">4. Installing PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../configuration.html">5. PRRTE DVM Configuration</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../how-things-work/index.html">6. How Things Work</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../hosts/index.html">7. Host specification</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../placement/index.html">8. Process placement</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../notifications.html">9. Notifications</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../session-directory.html">10. Session directory</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">11. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">11.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">11.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">11.3. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">11.4. Installing and running Sphinx (building the PRRTE docs)</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#installing-python">11.4.1. Installing Python</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#installing-sphinx">11.4.2. Installing Sphinx</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#install-sphinx-in-a-python-virtual-environment">11.4.2.1. Install Sphinx in a Python virtual environment</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#install-sphinx-globally">11.4.2.2. Install Sphinx globally</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#install-sphinx-locally">11.4.2.3. Install Sphinx locally</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#running-sphinx">11.4.3. Running Sphinx</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#sphinx-execution-time">11.4.3.1. Sphinx execution time</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#checking-sphinx-html-links">11.4.3.2. Checking Sphinx HTML links</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#viewing-docs-locally">11.4.3.3. Viewing docs locally</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">11.5. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">12. Contributing to PRRTE</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">13. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">14. PRRTE manual pages</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">15. Software Version Numbers</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../index.html">PMIx Reference Run Time Environment</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="index.html"><span class="section-number">11. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">11.4. </span>Installing and running Sphinx (building the PRRTE docs)</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/sphinx.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<style>
|
||||
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
|
||||
</style><div class="section" id="installing-and-running-sphinx-building-the-prrte-docs">
|
||||
<span id="developers-installing-sphinx-label"></span><h1><span class="section-number">11.4. </span>Installing and running Sphinx (building the PRRTE docs)<a class="headerlink" href="#installing-and-running-sphinx-building-the-prrte-docs" title="Permalink to this heading"></a></h1>
|
||||
<p>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.</p>
|
||||
<div class="section" id="installing-python">
|
||||
<h2><span class="section-number">11.4.1. </span>Installing Python<a class="headerlink" href="#installing-python" title="Permalink to this heading"></a></h2>
|
||||
<p>The <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx tool</a> is written in Python,
|
||||
and therefore needs to have Python available. As of late 2022, Sphinx
|
||||
requires Python >= v3.7.</p>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
<div class="section" id="installing-sphinx">
|
||||
<h2><span class="section-number">11.4.2. </span>Installing Sphinx<a class="headerlink" href="#installing-sphinx" title="Permalink to this heading"></a></h2>
|
||||
<p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/installation.html">The Sphinx documentation</a>
|
||||
recommends installing Sphinx (and its required Python dependencies)
|
||||
via <code class="docutils literal notranslate"><span class="pre">pip</span></code>, which typically requires connectivity to the general
|
||||
internet.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>If you are running on MacOS, you may be tempted to use
|
||||
Homebrew or MacPorts to install Sphinx. The Sphinx documentation
|
||||
recommends <strong>against</strong> this. Instead, you should use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to
|
||||
install Sphinx.</p>
|
||||
</div>
|
||||
<p>There are three general ways to install Sphinx; you only need one of
|
||||
them.</p>
|
||||
<div class="section" id="install-sphinx-in-a-python-virtual-environment">
|
||||
<h3><span class="section-number">11.4.2.1. </span>Install Sphinx in a Python virtual environment<a class="headerlink" href="#install-sphinx-in-a-python-virtual-environment" title="Permalink to this heading"></a></h3>
|
||||
<p>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
|
||||
<code class="docutils literal notranslate"><span class="pre">pip</span></code>-installed Python modules. This example installs Sphinx and
|
||||
other Python modules in the <code class="docutils literal notranslate"><span class="pre">ompi-docs-venv</span></code> tree under your PRRTE
|
||||
Git clone directory:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create the Python virtual environment</span>
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>TOP_OF_PRRTE_GIT_CLONE
|
||||
shell$<span class="w"> </span>python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>ompi-docs-venv
|
||||
<span class="c1"># Or: python3 -m virtualenv ompi-docs-venv</span>
|
||||
<span class="c1"># Or: virtualenv --python=python3 ompi-docs-venv</span>
|
||||
|
||||
<span class="c1"># Activate the virtual environment</span>
|
||||
shell$<span class="w"> </span>.<span class="w"> </span>./ompi-docs-venv/bin/activate
|
||||
|
||||
<span class="c1"># Notice that the shell prompt changes</span>
|
||||
<span class="c1"># Now install the required Python modules</span>
|
||||
<span class="o">(</span>ompi-docs-venv<span class="o">)</span><span class="w"> </span>shell$<span class="w"> </span>pip3<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>docs/requirements.txt
|
||||
<span class="c1"># Or: python3 -m pip install install -r docs/requirements.txt</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Note that sourcing the <code class="docutils literal notranslate"><span class="pre">activate</span></code> 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 <code class="docutils literal notranslate"><span class="pre">deactivate</span></code> to leave the virtual
|
||||
environment.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>You will need to source the <code class="docutils literal notranslate"><span class="pre">activate</span></code> script to put
|
||||
Sphinx in your <code class="docutils literal notranslate"><span class="pre">PATH</span></code> <em>before</em> running <code class="docutils literal notranslate"><span class="pre">configure</span></code>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="install-sphinx-globally">
|
||||
<h3><span class="section-number">11.4.2.2. </span>Install Sphinx globally<a class="headerlink" href="#install-sphinx-globally" title="Permalink to this heading"></a></h3>
|
||||
<p>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):</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>TOP_OF_PRRTE_GIT_CLONE
|
||||
shell$<span class="w"> </span>pip3<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>docs/requirements.txt
|
||||
<span class="c1"># Or: python3 -m pip install install -r docs/requirements.txt</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This will install Sphinx and some Python modules required for building
|
||||
the PRRTE documentation in a system-wide location.</p>
|
||||
<p>This will likely install the <code class="docutils literal notranslate"><span class="pre">sphinx-build</span></code> executable in a location
|
||||
that is already in your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>. If the location is not already in
|
||||
your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>, then you need to add it to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>You will need to ensure that Sphinx is in your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>
|
||||
<em>before</em> running <code class="docutils literal notranslate"><span class="pre">configure</span></code>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="install-sphinx-locally">
|
||||
<h3><span class="section-number">11.4.2.3. </span>Install Sphinx locally<a class="headerlink" href="#install-sphinx-locally" title="Permalink to this heading"></a></h3>
|
||||
<p>If you cannot or do not want to install Sphinx globally on your
|
||||
system, the following will install Sphinx somewhere under your
|
||||
<code class="docutils literal notranslate"><span class="pre">$HOME</span></code>. It is the same <code class="docutils literal notranslate"><span class="pre">pip</span></code> command as shown above, but with
|
||||
the addition of the <code class="docutils literal notranslate"><span class="pre">--user</span></code> flag (you should not need <code class="docutils literal notranslate"><span class="pre">root</span></code>
|
||||
permissions to run this command):</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>TOP_OF_PRRTE_GIT_CLONE
|
||||
shell$<span class="w"> </span>pip3<span class="w"> </span>install<span class="w"> </span>--user<span class="w"> </span>-r<span class="w"> </span>docs/requirements.txt
|
||||
<span class="c1"># Or: python3 -m pip install install -r docs/requirements.txt</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This will install Sphinx and some Python modules required for building
|
||||
the PRRTE documentation in a system-wide location.</p>
|
||||
<p>You will likely need to find the location where <code class="docutils literal notranslate"><span class="pre">sphinx-build</span></code> was
|
||||
installed and add it to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>On MacOS, look for <code class="docutils literal notranslate"><span class="pre">sphinx-build</span></code> under
|
||||
<code class="docutils literal notranslate"><span class="pre">$HOME/Library/Python/VERSION/bin</span></code> (where <code class="docutils literal notranslate"><span class="pre">VERSION</span></code> is
|
||||
the version number of Python). Or it may have installed to
|
||||
<code class="docutils literal notranslate"><span class="pre">/usr/local/bin/sphinx-build</span></code>. YMMV.</p>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>You will need to ensure that Sphinx is in your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>
|
||||
<em>before</em> running <code class="docutils literal notranslate"><span class="pre">configure</span></code>.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="running-sphinx">
|
||||
<h2><span class="section-number">11.4.3. </span>Running Sphinx<a class="headerlink" href="#running-sphinx" title="Permalink to this heading"></a></h2>
|
||||
<p>PRRTE’s build environment is setup to invoke Sphinx automatically;
|
||||
you should not need to invoke Sphinx manually.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>You will need to ensure that Sphinx is in your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>
|
||||
<em>before</em> running <code class="docutils literal notranslate"><span class="pre">configure</span></code>.</p>
|
||||
</div>
|
||||
<p>As long as <code class="docutils literal notranslate"><span class="pre">configure</span></code> found Sphinx, <code class="docutils literal notranslate"><span class="pre">make</span></code> will invoke Sphinx to
|
||||
build the documentation. You can also run <code class="docutils literal notranslate"><span class="pre">make</span></code> directly in the
|
||||
<code class="docutils literal notranslate"><span class="pre">docs/</span></code> directory to build <em>just</em> 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.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>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.</p>
|
||||
<p>Sphinx is a requirement for <em>developers</em> who want to build
|
||||
the PRRTE docs. End users do <em>not</em> need to have Sphinx
|
||||
available to build PRRTE or have its docs installed from
|
||||
an official distribution tarball.</p>
|
||||
</div>
|
||||
<div class="section" id="sphinx-execution-time">
|
||||
<h3><span class="section-number">11.4.3.1. </span>Sphinx execution time<a class="headerlink" href="#sphinx-execution-time" title="Permalink to this heading"></a></h3>
|
||||
<p>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 <code class="docutils literal notranslate"><span class="pre">make</span></code> to see how they rendered in
|
||||
HTML).</p>
|
||||
<div class="admonition caution">
|
||||
<p class="admonition-title">Caution</p>
|
||||
<p>Sphinx is only <em>somewhat</em> smart in its partial
|
||||
re-rendering. If you change a title in an RST file, for
|
||||
example, Sphinx will (by default) only re-render <em>that</em>
|
||||
page. The Tables of Contents / left hand navigation on
|
||||
other pages may not be updated.</p>
|
||||
<p>You can always force a full re-render via:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>docs
|
||||
shell$<span class="w"> </span>rm<span class="w"> </span>-rf<span class="w"> </span>_build
|
||||
shell$<span class="w"> </span>make
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="checking-sphinx-html-links">
|
||||
<h3><span class="section-number">11.4.3.2. </span>Checking Sphinx HTML links<a class="headerlink" href="#checking-sphinx-html-links" title="Permalink to this heading"></a></h3>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">linkcheck</span></code> will invoke Sphinx’s functionality to check all the
|
||||
external links in the documentation:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>docs
|
||||
shell$<span class="w"> </span>make<span class="w"> </span>linkcheck
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>You will need to be on a computer that has good access
|
||||
to the internet when running this command.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="viewing-docs-locally">
|
||||
<h3><span class="section-number">11.4.3.3. </span>Viewing docs locally<a class="headerlink" href="#viewing-docs-locally" title="Permalink to this heading"></a></h3>
|
||||
<p>Once you have built the docs in your local Git clone, you can view
|
||||
them locally in the build tree:</p>
|
||||
<ol class="arabic">
|
||||
<li><p>Open <code class="docutils literal notranslate"><span class="pre">docs/_build/html/index.html</span></code> 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:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>open<span class="w"> </span>docs/_build/html/index.html
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>Use the <code class="docutils literal notranslate"><span class="pre">man</span></code> command to view the Nroff files in
|
||||
<code class="docutils literal notranslate"><span class="pre">docs/_build/man</span></code> (you may need to use an absolute or relative
|
||||
filename to prevent <code class="docutils literal notranslate"><span class="pre">man</span></code> from using its search paths). For
|
||||
example:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>docs/_build/man
|
||||
shell$<span class="w"> </span>man<span class="w"> </span>./prterun.1
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Alternatively, you can view these files in their installed locations
|
||||
after running <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code>:</p>
|
||||
<ol class="arabic">
|
||||
<li><p>The HTML docs are installed (by default) to
|
||||
<code class="docutils literal notranslate"><span class="pre">$prefix/share/doc/prte/html</span></code>. You can use a web browser to
|
||||
open the <code class="docutils literal notranslate"><span class="pre">index.html</span></code> in that directory to view the docs locally.
|
||||
For example, on MacOS, the following command opens the installed
|
||||
docs in the default web browser:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>open<span class="w"> </span><span class="nv">$prefix</span>/share/doc/prte/html/index.html
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>The man pages are installed (by default) to <code class="docutils literal notranslate"><span class="pre">$preix/share/man</span></code>.
|
||||
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:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>man<span class="w"> </span>prterun
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="gnu-autotools.html" class="btn btn-neutral float-left" title="11.3. Manually installing the GNU Autootools" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="rst-for-markdown-expats.html" class="btn btn-neutral float-right" title="11.5. ReStructured Text for those who know Markdown" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2003-2025, The PRRTE Community.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user