Upgrade macos
This commit is contained in:
Bassem Girgis
186
macx64/mpi/openmpi/share/doc/pmix/html/developers/autogen.html
Normal file
186
macx64/mpi/openmpi/share/doc/pmix/html/developers/autogen.html
Normal file
@@ -0,0 +1,186 @@
|
||||
<!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>12.4. Running autogen.pl — OpenPMIx 5.0.5 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.5. Building PMIx" href="building-pmix.html" />
|
||||
<link rel="prev" title="12.3. Compiler Pickyness by Default" href="compiler-pickyness.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.4. </span>Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/autogen.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="running-autogen-pl">
|
||||
<h1><span class="section-number">12.4. </span>Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code><a class="headerlink" href="#running-autogen-pl" title="Permalink to this heading"></a></h1>
|
||||
<p>You can now run PMIx’s top-level <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> script. This script
|
||||
will invoke the GNU Autoconf, Automake, and Libtool commands in the
|
||||
proper order and do a bunch of component discovery and housekeeping to
|
||||
setup to run PMIx’s top-level <code class="docutils literal notranslate"><span class="pre">configure</span></code> script.</p>
|
||||
<p>Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> may take a few minutes, depending on your
|
||||
system. It’s not very exciting to watch.</p>
|
||||
<p>If you have a multi-processor system, enabling the multi-threaded
|
||||
behavior in Automake 1.11 (or newer) can result in <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code>
|
||||
running faster. Do this by setting the <code class="docutils literal notranslate"><span class="pre">AUTOMAKE_JOBS</span></code> environment
|
||||
variable to the number of processors (threads) that you want it to use
|
||||
before invoking <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code>. For example (you can put this in your
|
||||
shell startup files):</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># For bash/sh/zsh:</span>
|
||||
<span class="n">export</span> <span class="n">AUTOMAKE_JOBS</span><span class="o">=</span><span class="mi">4</span>
|
||||
|
||||
<span class="c1"># For csh/tcsh:</span>
|
||||
<span class="nb">set</span> <span class="n">AUTOMAKE_JOBS</span> <span class="mi">4</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> will fail and report an error if you
|
||||
forgot to install the required submodule prior to running the
|
||||
autogen script. You can either do this by adding the <code class="docutils literal notranslate"><span class="pre">--recursive</span></code>
|
||||
flag to your Git <code class="docutils literal notranslate"><span class="pre">clone</span></code> command, or by manually populating the
|
||||
submodule by running:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>git<span class="w"> </span>submodule<span class="w"> </span>update<span class="w"> </span>--init
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>prior to executing <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code>.</p>
|
||||
</div>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>You generally need to run <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> whenever the
|
||||
top-level file <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code> changes, or any files in the
|
||||
<code class="docutils literal notranslate"><span class="pre">config/</span></code> or <code class="docutils literal notranslate"><span class="pre"><project>/config/</span></code> directories change (these
|
||||
directories are where a lot of “include” files for PMIx’s
|
||||
<code class="docutils literal notranslate"><span class="pre">configure</span></code> script live).</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>You do <em>NOT</em> need to re-run <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> if you modify a
|
||||
<code class="docutils literal notranslate"><span class="pre">Makefile.am</span></code>.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="compiler-pickyness.html" class="btn btn-neutral float-left" title="12.3. Compiler Pickyness by Default" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="building-pmix.html" class="btn btn-neutral float-right" title="12.5. Building PMIx" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx 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,147 @@
|
||||
<!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>12.5. Building PMIx — OpenPMIx 5.0.5 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.6. OpenPMIx terminology" href="terminology.html" />
|
||||
<link rel="prev" title="12.4. Running autogen.pl" href="autogen.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.5. </span>Building PMIx</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/building-pmix.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="building-pmix">
|
||||
<h1><span class="section-number">12.5. </span>Building PMIx<a class="headerlink" href="#building-pmix" title="Permalink to this heading"></a></h1>
|
||||
<p>Once you have run <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> successfully, you can configure and
|
||||
build PMIx just like end users do with official distribution PMIx
|
||||
tarballs.</p>
|
||||
<p>See the <a class="reference internal" href="../installing-pmix/index.html"><span class="doc">general “Install PMIx” documentation for more
|
||||
details.</span></a></p>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="autogen.html" class="btn btn-neutral float-left" title="12.4. Running autogen.pl" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="terminology.html" class="btn btn-neutral float-right" title="12.6. OpenPMIx terminology" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx 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,159 @@
|
||||
<!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>12.3. Compiler Pickyness by Default — OpenPMIx 5.0.5 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.4. Running autogen.pl" href="autogen.html" />
|
||||
<link rel="prev" title="12.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.3. </span>Compiler Pickyness by Default</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/compiler-pickyness.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="compiler-pickyness-by-default">
|
||||
<h1><span class="section-number">12.3. </span>Compiler Pickyness by Default<a class="headerlink" href="#compiler-pickyness-by-default" title="Permalink to this heading"></a></h1>
|
||||
<p>If you are building PMIx from a Git clone (i.e., there is a
|
||||
<code class="docutils literal notranslate"><span class="pre">.git</span></code> directory in your build tree), the default build includes
|
||||
extra compiler pickyness, which will result in more compiler warnings
|
||||
than in non-developer builds and will mandate that warnings be
|
||||
treated as errors. Getting these extra compiler warnings
|
||||
is helpful to PMIx developers in making the code base as clean as
|
||||
possible.</p>
|
||||
<p>Developers can disable this picky-by-default behavior by using the
|
||||
<code class="docutils literal notranslate"><span class="pre">--disable-picky</span></code> configure option. Also note that extra-picky
|
||||
compiles do <em>not</em> happen automatically when you do a VPATH build
|
||||
(e.g., if <code class="docutils literal notranslate"><span class="pre">.git</span></code> is in your source tree, but not in your build
|
||||
tree).</p>
|
||||
<p>Prior versions of PMIx would automatically activate a lot of
|
||||
(performance-reducing) debugging code by default if <code class="docutils literal notranslate"><span class="pre">.git</span></code> was found
|
||||
in your build tree. This is no longer true. You can manually enable
|
||||
these (performance-reducing) debugging features in the PMIx code
|
||||
base with the <code class="docutils literal notranslate"><span class="pre">--enable-debug</span></code> configure option.</p>
|
||||
</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="12.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="autogen.html" class="btn btn-neutral float-right" title="12.4. Running autogen.pl" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx 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,207 @@
|
||||
<!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>12.8. Internal frameworks — OpenPMIx 5.0.5 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.9. Manually installing the GNU Autootools" href="gnu-autotools.html" />
|
||||
<link rel="prev" title="12.7. Source code" href="source-code.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.8. Internal frameworks</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#framework-notes">12.8.1. Framework notes</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#mca-parameter-notes">12.8.2. MCA parameter notes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.8. </span>Internal frameworks</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/frameworks.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="internal-frameworks">
|
||||
<span id="label-frameworks"></span><h1><span class="section-number">12.8. </span>Internal frameworks<a class="headerlink" href="#internal-frameworks" title="Permalink to this heading"></a></h1>
|
||||
<p>The Modular Component Architecture (MCA) is the backbone of PMIx
|
||||
– most services and functionality are implemented through MCA
|
||||
components.</p>
|
||||
<p>Here is a list of all the component frameworks in PMIx as of
|
||||
this writing February-2025:</p>
|
||||
<ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">bfrops</span></code>: Buffer Operations, including support for pack/unpack,
|
||||
copy, print, compare, and load of data types and structured objects</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">gds</span></code>: Generalized DataStore for storing job-level and other data</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pcompress</span></code>: Compress to support compression of large data objects</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pdl</span></code>: DLopen support</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pfexec</span></code>: Fork/Exec support to allow tools to start child processes</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pgpu</span></code>: GPU support</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pif</span></code>: Interface discovery</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pinstalldirs</span></code>: Install Directories - provides a struct containing
|
||||
all installation locations</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">plog</span></code>: Logging of user-provided alerts</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pmdl</span></code>: Programming Model - provides support for a range of
|
||||
programming models and libraries, including collection of default
|
||||
parameters and environmental variables for forwarding and setting
|
||||
of library-specific environmental variables</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pnet</span></code>: Network support, including computation of endpoints to
|
||||
support the <code class="docutils literal notranslate"><span class="pre">instant</span> <span class="pre">on</span></code> launch procedure</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">preg</span></code>: Regular expression generator and parser</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">prm</span></code>: Resource Manager support - translation of generic PMIx directives
|
||||
(e.g., mapping and resource definitions) to RM-specific values and
|
||||
general RM-specific support</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">psec</span></code>: Security operations such as connection handshakes</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">psensor</span></code>: Sensor framework for monitoring processes, including
|
||||
resource utilization and state-of-health (e.g., heartbeat)</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">psquash</span></code>: Internal framework for squashing integer data values
|
||||
during transmission</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pstat</span></code>: Statistics, including reporting resource usage at the
|
||||
process, node, and disk levels</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">ptl</span></code>: Transport Layer for client-server and tool-server
|
||||
communication</p></li>
|
||||
</ul>
|
||||
<div class="section" id="framework-notes">
|
||||
<h2><span class="section-number">12.8.1. </span>Framework notes<a class="headerlink" href="#framework-notes" title="Permalink to this heading"></a></h2>
|
||||
<p>Each framework typically has one or more components that are used at
|
||||
run-time. For example, the <code class="docutils literal notranslate"><span class="pre">bfrops</span></code> framework is used by PMIx
|
||||
to pack/unpack data for transmission, copy data objects, and other
|
||||
data manipulation operations. The <code class="docutils literal notranslate"><span class="pre">v3</span></code> component, for example,
|
||||
supports the data object definitions introduced in v3 of the
|
||||
library, while the <code class="docutils literal notranslate"><span class="pre">v41</span></code> component supports those introduced
|
||||
in v4.1.</p>
|
||||
</div>
|
||||
<div class="section" id="mca-parameter-notes">
|
||||
<h2><span class="section-number">12.8.2. </span>MCA parameter notes<a class="headerlink" href="#mca-parameter-notes" title="Permalink to this heading"></a></h2>
|
||||
<p>Each component typically has some tunable parameters that can be
|
||||
changed at run-time. Use the <a class="reference internal" href="../man/man1/pmix_info.1.html#man1-pmix-info"><span class="std std-ref">pmix_info(1)</span></a>
|
||||
command to check a component to see what its tunable parameters are.
|
||||
For example:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>pmix_info<span class="w"> </span>--param<span class="w"> </span>psensor<span class="w"> </span>file
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>shows the parameters (and default values) for the <code class="docutils literal notranslate"><span class="pre">file</span></code> <code class="docutils literal notranslate"><span class="pre">psensor</span></code>
|
||||
component.</p>
|
||||
<p>See <a class="reference internal" href="../mca.html#label-running-setting-mca-param-values"><span class="std std-ref">this section</span></a> for
|
||||
details on how to set MCA parameters at run time.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="source-code.html" class="btn btn-neutral float-left" title="12.7. Source code" 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="12.9. 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 2014-2025, The OpenPMIx 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,324 @@
|
||||
<!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>12.2. GitHub, Git, and related topics — OpenPMIx 5.0.5 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.3. Compiler Pickyness by Default" href="compiler-pickyness.html" />
|
||||
<link rel="prev" title="12.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.2. GitHub, Git, and related topics</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#github">12.2.1. GitHub</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#git-commits-open-source-contributor-s-declaration">12.2.2. Git commits: open source / contributor’s declaration</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#git-branch-scheme">12.2.3. Git branch scheme</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#ci-testing">12.2.4. CI (testing)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.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">12.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">12.2.1. </span>GitHub<a class="headerlink" href="#github" title="Permalink to this heading"></a></h2>
|
||||
<p>PMIx’s Git repository is <a class="reference external" href="https://github.com/openpmix/openpmix">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/openpmix/">openpmix</a> is the main PMIx
|
||||
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 PMIx uses Git submodules:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>shell$ git clone --recursive https://github.com/openpmix/openpmix.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">12.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 PMIx
|
||||
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">PMIx 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">12.2.3. </span>Git branch scheme<a class="headerlink" href="#git-branch-scheme" title="Permalink to this heading"></a></h2>
|
||||
<p>Generally, PMIx has two types of branches in its Git repository:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">master</span></code>:</p>
|
||||
<ul class="simple">
|
||||
<li><p>All active development occurs on the <code class="docutils literal notranslate"><span class="pre">master</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 PMIx vMAJOR.MINOR series.</p></li>
|
||||
<li><p>Periodically, the PMIx community will make a new release
|
||||
branch, typically from <code class="docutils literal notranslate"><span class="pre">master</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 PMIx 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>
|
||||
<p>Once a bug is fixed or a new feature is implemented on <code class="docutils literal notranslate"><span class="pre">master</span></code>, it is
|
||||
cherry-picked over to the relevant release branch(es).</p>
|
||||
<div class="admonition attention">
|
||||
<p class="admonition-title">Attention</p>
|
||||
<p>It may seem odd to some, but the PMIx community
|
||||
development model does <em>not</em> PR bug fixes or new
|
||||
features directly to release branches. Instead,
|
||||
initial bug-fix / feature PRs are generally first made
|
||||
to <code class="docutils literal notranslate"><span class="pre">master</span></code>.</p>
|
||||
<p>This helps us ensure that future releases (with
|
||||
<code class="docutils literal notranslate"><span class="pre">master</span></code> as a Git ancestor) will contain the bug fix /
|
||||
feature.</p>
|
||||
</div>
|
||||
<p>For example:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>master
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>pull<span class="w"> </span>--rebase
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>pr/bug-fix
|
||||
|
||||
<span class="c1"># ... make changes / fix a bug / etc. ...</span>
|
||||
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>add<span class="w"> </span>...
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>commit<span class="w"> </span>-s<span class="w"> </span>...
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>push<span class="w"> </span>myfork
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>At this point, you go create a PR from your fork’s <code class="docutils literal notranslate"><span class="pre">pr/bug-fix</span></code>
|
||||
branch to the PMIx community GitHub repo <code class="docutils literal notranslate"><span class="pre">master</span></code> branch. Work
|
||||
with the community to get the PR completed and merged. Then you can
|
||||
open a new PR to cherry pick the Git commits from that bug fix to each
|
||||
of the relevant release branches.</p>
|
||||
<p>Depending on how far the release branch has diverged from <code class="docutils literal notranslate"><span class="pre">master</span></code>,
|
||||
there may be some porting effort involved in the cherry-pick.</p>
|
||||
<p>For example, if your bug fix on <code class="docutils literal notranslate"><span class="pre">master</span></code> is comprised of a single Git
|
||||
commit hash <code class="docutils literal notranslate"><span class="pre">123abc</span></code>:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Fetch all upstream git activity, including the merge of the "master" PR.</span>
|
||||
shell$<span class="w"> </span>get<span class="w"> </span>fetch<span class="w"> </span>--all
|
||||
|
||||
<span class="c1"># Check out the target release branch, and advance to the most recent commit.</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>v5.0.x
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>pull<span class="w"> </span>--rebase
|
||||
|
||||
<span class="c1"># Make a branch for your bug fix</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>pr/v5.0.x/bug-fix
|
||||
<span class="c1"># Cherry pick the commit from the "master" branch</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>cherry-pick<span class="w"> </span>-x<span class="w"> </span>123abc
|
||||
<span class="c1"># Push to your fork</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>push<span class="w"> </span>myfork
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The PMIx development community <em>requires</em> adding the following
|
||||
line to the commit message of cherry-picked commits on release
|
||||
branches:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>(cherry picked from commit [git_hash_of_original_commit])
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Note the use of the <code class="docutils literal notranslate"><span class="pre">-x</span></code> option to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">cherry-pick</span></code>.
|
||||
This option automatically adds the <code class="docutils literal notranslate"><span class="pre">(cherry</span> <span class="pre">picked</span> <span class="pre">from</span>
|
||||
<span class="pre">...)</span></code> line to your commit message.</p>
|
||||
</div>
|
||||
<div class="tip admonition">
|
||||
<p class="admonition-title">Rationale</p>
|
||||
<p>Git does not actually store any meta data about Git cherry-picks in
|
||||
the commit. Having a standardized text line containing the source
|
||||
Git commit hash in the commit messages helps the PMIx
|
||||
development community track where commits came from on release
|
||||
branches, and therefore allows us to check whether all relevant
|
||||
commits have been ported to a given release branch.</p>
|
||||
</div>
|
||||
<p>Once your commits are ready and pushed up to your fork, make a PR to
|
||||
the target release branch.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>A GitHub PR CI job checks all commits on release branches
|
||||
for the <code class="docutils literal notranslate"><span class="pre">(cherry</span> <span class="pre">picked</span> <span class="pre">from...)</span></code> line. It will also
|
||||
ensure that the Git hash cited in that line actually
|
||||
exists on the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch.</p>
|
||||
<p>This check ensures that commits are not made to release
|
||||
branches before their corresponding <code class="docutils literal notranslate"><span class="pre">master</span></code> PR was
|
||||
merged.</p>
|
||||
</div>
|
||||
<p>All this being said, sometimes there is a need for a non-cherry-picked
|
||||
commit on a release branch. E.g., sometimes a release branch has
|
||||
diverged so much that the bug no longer exists on <code class="docutils literal notranslate"><span class="pre">master</span></code>. It would
|
||||
therefore not make sense — or even be impossible — to
|
||||
commit the bug fix in question to <code class="docutils literal notranslate"><span class="pre">master</span></code>.</p>
|
||||
<p>In such cases, make a regular PR to the target branch (with commits
|
||||
that do <em>not</em> include <code class="docutils literal notranslate"><span class="pre">(cherry</span> <span class="pre">picked</span> <span class="pre">from</span> <span class="pre">...)</span></code> lines). In the PR
|
||||
description, add a line with the following token:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>bot:notacherrypick
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This tells the GitHub CI job that this PR contains commits that are
|
||||
not cherry-picked from <code class="docutils literal notranslate"><span class="pre">master</span></code>.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">bot:notacherrypick</span></code> should only be used when
|
||||
absolutely necessary. It is not a license to avoid
|
||||
the process of PR’ing to <code class="docutils literal notranslate"><span class="pre">master</span></code> first.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="ci-testing">
|
||||
<h2><span class="section-number">12.2.4. </span>CI (testing)<a class="headerlink" href="#ci-testing" title="Permalink to this heading"></a></h2>
|
||||
<p>The PMIx community generally runs a bunch of tests on each PR
|
||||
(Continuous Integration / CI). These tests are a mixture of
|
||||
GitHub Actions and other CI systems (e.g., Jenkins). Examples
|
||||
include (but are not limited to):</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p>Check each Git commit for bozo email addresses</p></li>
|
||||
<li><p>Check that each Git commit contains a <code class="docutils literal notranslate"><span class="pre">Signed-off-by</span></code> line</p></li>
|
||||
<li><p>Check that commits on release branches contain a cherry-pick
|
||||
notice</p></li>
|
||||
<li><p>Build and publish the docs</p></li>
|
||||
<li><p>Build PMIx in a variety of environments and run sanity tests
|
||||
with that installation</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
</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="12.1. Prerequisites" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="compiler-pickyness.html" class="btn btn-neutral float-right" title="12.3. Compiler Pickyness by Default" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx 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,360 @@
|
||||
<!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>12.9. Manually installing the GNU Autootools — OpenPMIx 5.0.5 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.10. Installing and running Sphinx (building the OpenPMIx docs)" href="sphinx.html" />
|
||||
<link rel="prev" title="12.8. Internal frameworks" href="frameworks.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.9. Manually installing the GNU Autootools</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#use-a-package-manager">12.9.1. Use a package manager</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#autotools-versions">12.9.2. Autotools versions</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#checking-your-versions">12.9.3. Checking your versions</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#installing-the-gnu-autotools-from-source">12.9.4. Installing the GNU Autotools from source</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#build-and-install-ordering">12.9.5. Build and install ordering</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.9. </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">12.9. </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 PMIx from a Git clone. End
|
||||
users installing an PMIx 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">12.9.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">12.9.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 PMIx
|
||||
from its repository sources (users who download PMIx tarballs do
|
||||
not need these tools - they are only required for developers working
|
||||
on the internals of PMIx itself):</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>Version</p></th>
|
||||
<th class="head"><p>URL</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p>GNU m4</p></td>
|
||||
<td><p>1.4.17</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>2.69</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>1.15</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>2.4.6</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>
|
||||
<tr class="row-even"><td><p>Flex</p></td>
|
||||
<td><p>2.5.35</p></td>
|
||||
<td><p><a class="reference external" href="https://sourceforge.net/projects/flex/">https://sourceforge.net/projects/flex/</a></p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Sphinx</p></td>
|
||||
<td><p>4.2.0</p></td>
|
||||
<td><p><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></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The above table lists the versions that are used to make official
|
||||
release PMIx 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 this point: the core PMIx developers typically
|
||||
use very, very recent versions of the GNU tools. There are known bugs
|
||||
in older versions of the GNU tools that PMIx no longer compensates
|
||||
for (it seemed senseless to indefinitely support patches for ancient
|
||||
versions of Autoconf, for example).</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 above. This is because such older versions still make
|
||||
usable PMIx builds on many platforms - especially Linux on x86_64
|
||||
with GNU compilers - and are convenient for developers whose Linux
|
||||
distribution may not have as recent as the versions listed above (but are
|
||||
recent enough to produce a working version for their platform).</p>
|
||||
<p>To be clear: the versions listed above are required to support a wide
|
||||
variety of platforms and environments, and are used to make the official
|
||||
release tarballs. When building PMIx, YMMV when using
|
||||
versions older than those listed above — 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 above.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Sphinx was only recently added to the list of required tools
|
||||
to generate the documentation. It is not required for PMIx
|
||||
versions prior to v4.2.3.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="checking-your-versions">
|
||||
<h2><span class="section-number">12.9.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">12.9.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 PMIx has no specific m4
|
||||
requirements; it is only listed here because Autoconf requires minimum
|
||||
versions of GNU m4. Hence, you may or may not <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">12.9.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="frameworks.html" class="btn btn-neutral float-left" title="12.8. Internal frameworks" 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="12.10. Installing and running Sphinx (building the OpenPMIx 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 2014-2025, The OpenPMIx 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>
|
||||
216
macx64/mpi/openmpi/share/doc/pmix/html/developers/index.html
Normal file
216
macx64/mpi/openmpi/share/doc/pmix/html/developers/index.html
Normal file
@@ -0,0 +1,216 @@
|
||||
<!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>12. Developer’s guide — OpenPMIx 5.0.5 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.1. Prerequisites" href="prerequisites.html" />
|
||||
<link rel="prev" title="11.5. Building fully-static PMIx applications" href="../building-apps/building-static-apps.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">12. Developer’s guide</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </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">12. </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 PMIx 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> PMIx, 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">12.1. Prerequisites</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html#compilers">12.1.1. Compilers</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html#gnu-autotools">12.1.2. GNU Autotools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html#perl">12.1.3. Perl</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html#flex">12.1.4. Flex</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html#sphinx-and-therefore-python">12.1.5. Sphinx (and therefore Python)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html#github">12.2.1. GitHub</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html#git-commits-open-source-contributor-s-declaration">12.2.2. Git commits: open source / contributor’s declaration</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html#git-branch-scheme">12.2.3. Git branch scheme</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html#ci-testing">12.2.4. CI (testing)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html#modular-component-architecture-mca">12.6.1. Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html#required-3rd-party-libraries">12.6.2. Required 3rd party libraries</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="source-code.html">12.7. Source code</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html#code-style">12.7.1. Code style</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html#tree-layout">12.7.2. Tree layout</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html#symbol-visibility">12.7.3. Symbol Visibility</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html#framework-notes">12.8.1. Framework notes</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html#mca-parameter-notes">12.8.2. MCA parameter notes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html#use-a-package-manager">12.9.1. Use a package manager</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html#autotools-versions">12.9.2. Autotools versions</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html#checking-your-versions">12.9.3. Checking your versions</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html#installing-the-gnu-autotools-from-source">12.9.4. Installing the GNU Autotools from source</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html#build-and-install-ordering">12.9.5. Build and install ordering</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html#installing-python">12.10.1. Installing Python</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html#installing-sphinx">12.10.2. Installing Sphinx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html#running-sphinx">12.10.3. Running Sphinx</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#whitespace-and-indenting">12.11.1. Whitespace and indenting</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#fixed-width-font">12.11.2. Fixed width font</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#italics">12.11.3. Italics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#boldface">12.11.4. Boldface</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#chapter-and-section-delimiters">12.11.5. Chapter and section delimiters</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#multi-line-code-fixed-width-font">12.11.6. Multi-line code/fixed-width font</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#un-numbered-bullets">12.11.7. Un-numbered bullets</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#numbered-bullets">12.11.8. Numbered bullets:</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#comments">12.11.9. Comments</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#including-files">12.11.10. Including files</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#hyperlinks-to-urls">12.11.11. Hyperlinks to URLs</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#hyperlinks-to-anchors">12.11.12. Hyperlinks to anchors</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#hyperlinks-to-other-rst-pages">12.11.13. Hyperlinks to other (RST) pages</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#macros">12.11.14. Macros</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html#brightly-colored-boxes">12.11.15. Brightly-colored boxes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="../building-apps/building-static-apps.html" class="btn btn-neutral float-left" title="11.5. Building fully-static PMIx applications" 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="12.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 2014-2025, The OpenPMIx 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,272 @@
|
||||
<!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>12.1. Prerequisites — OpenPMIx 5.0.5 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.2. GitHub, Git, and related topics" href="git-github.html" />
|
||||
<link rel="prev" title="12. 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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.1. Prerequisites</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#compilers">12.1.1. Compilers</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#gnu-autotools">12.1.2. GNU Autotools</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#perl">12.1.3. Perl</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#flex">12.1.4. Flex</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#sphinx-and-therefore-python">12.1.5. Sphinx (and therefore Python)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.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">12.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">12.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">12.1.2. </span>GNU Autotools<a class="headerlink" href="#gnu-autotools" title="Permalink to this heading"></a></h2>
|
||||
<p>When building OpenPMIx 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 OpenPMIx
|
||||
from distribution tarballs. OpenPMIx 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">12.1.3. </span>Perl<a class="headerlink" href="#perl" title="Permalink to this heading"></a></h2>
|
||||
<p>OpenPMIx 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 OpenPMIx’s Perl scripts.</p>
|
||||
</div>
|
||||
<div class="section" id="flex">
|
||||
<h2><span class="section-number">12.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 OpenPMIx, 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 OpenPMIx. We suggest that you use
|
||||
v2.5.35 at the earliest.</p>
|
||||
<p>For now, OpenPMIx 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 OpenPMIx 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">12.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 OpenPMIx distribution tarballs contain pre-built HTML
|
||||
documentation and man pages. This means that – similar to the GNU
|
||||
Autotools – end users do not need to have Sphinx installed, but will
|
||||
still have both the HTML documentation and man pages installed as part
|
||||
of the normal configure / build / install process.</p>
|
||||
<p>However, the HTML documentation and man pages are <em>not</em> stored in OpenPMIx’s
|
||||
Git repository; only the ReStructred Text source code of the
|
||||
documentation is in the Git repository. Hence, if you are building
|
||||
OpenPMIx from a Git clone, you will need Sphinx (and some Python
|
||||
modules) in order to build the HTML documentation and man pages.</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 OpenPMIx from a Git clone and
|
||||
unexpectedly did not have the man pages installed, it is
|
||||
likely that you do not have Sphinx and/or the required
|
||||
Python modules available.</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="12. 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="12.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 2014-2025, The OpenPMIx 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,564 @@
|
||||
<!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>12.11. ReStructured Text for those who know Markdown — OpenPMIx 5.0.5 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="13. Contributing to OpenPMIx" href="../contributing.html" />
|
||||
<link rel="prev" title="12.10. Installing and running Sphinx (building the OpenPMIx 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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.11. ReStructured Text for those who know Markdown</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#whitespace-and-indenting">12.11.1. Whitespace and indenting</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#fixed-width-font">12.11.2. Fixed width font</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#italics">12.11.3. Italics</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#boldface">12.11.4. Boldface</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#chapter-and-section-delimiters">12.11.5. Chapter and section delimiters</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#multi-line-code-fixed-width-font">12.11.6. Multi-line code/fixed-width font</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#un-numbered-bullets">12.11.7. Un-numbered bullets</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#numbered-bullets">12.11.8. Numbered bullets:</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#comments">12.11.9. Comments</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#including-files">12.11.10. Including files</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#hyperlinks-to-urls">12.11.11. Hyperlinks to URLs</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#hyperlinks-to-anchors">12.11.12. Hyperlinks to anchors</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#hyperlinks-to-other-rst-pages">12.11.13. Hyperlinks to other (RST) pages</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#macros">12.11.14. Macros</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#brightly-colored-boxes">12.11.15. Brightly-colored boxes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.11. </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">12.11. </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">12.11.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">12.11.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">12.11.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">12.11.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">12.11.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 OpenPMIx 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">12.11.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>pmix-<version>.tar.bz2
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>pmix-<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>pmix-<version>.tar.bz2
|
||||
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>pmix-<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">12.11.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">12.11.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">12.11.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">12.11.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">12.11.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">12.11.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">12.11.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 OpenPMIx git tree.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="macros">
|
||||
<h2><span class="section-number">12.11.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 OpenPMIx-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 OpenPMIx 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 OpenPMIx 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 OpenPMIx version
|
||||
number or series when referring to the current
|
||||
version or series. It can be appropriate to
|
||||
hard-code an “x.y.0” version to denote a
|
||||
generational epoch, but in most other cases, you
|
||||
probably want to use one of the macros.</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">12.11.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="12.10. Installing and running Sphinx (building the OpenPMIx 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="13. Contributing to OpenPMIx" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx 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,378 @@
|
||||
<!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>12.7. Source code — OpenPMIx 5.0.5 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.8. Internal frameworks" href="frameworks.html" />
|
||||
<link rel="prev" title="12.6. OpenPMIx terminology" href="terminology.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.7. Source code</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#code-style">12.7.1. Code style</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#all-languages">12.7.1.1. All languages</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#c-c">12.7.1.2. C / C++</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#shell-scripting">12.7.1.3. Shell scripting</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#m4">12.7.1.4. m4</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#tree-layout">12.7.2. Tree layout</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#symbol-visibility">12.7.3. Symbol Visibility</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.7. </span>Source code</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/source-code.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="source-code">
|
||||
<h1><span class="section-number">12.7. </span>Source code<a class="headerlink" href="#source-code" title="Permalink to this heading"></a></h1>
|
||||
<div class="section" id="code-style">
|
||||
<h2><span class="section-number">12.7.1. </span>Code style<a class="headerlink" href="#code-style" title="Permalink to this heading"></a></h2>
|
||||
<p>We intentionally do not have too many code conventions in the PMIx
|
||||
code base.</p>
|
||||
<div class="section" id="all-languages">
|
||||
<h3><span class="section-number">12.7.1.1. </span>All languages<a class="headerlink" href="#all-languages" title="Permalink to this heading"></a></h3>
|
||||
<ul class="simple">
|
||||
<li><p>4 space tabs. No more, no less.</p></li>
|
||||
<li><p><strong>NEVER</strong> use actual tab characters; always use spaces. Both emacs
|
||||
and vim have secret mojo that can automatically use spaces when you
|
||||
hit the <code class="docutils literal notranslate"><span class="pre"><TAB></span></code> key. This makes the code look the same in every
|
||||
browser, regardless of individual tab display settings.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="c-c">
|
||||
<h3><span class="section-number">12.7.1.2. </span>C / C++<a class="headerlink" href="#c-c" title="Permalink to this heading"></a></h3>
|
||||
<ul>
|
||||
<li><p>When comparing constants for equality or inequality, always put the
|
||||
constant on the left. This is defensive programming: if you have a
|
||||
typo in the test and miss a <code class="docutils literal notranslate"><span class="pre">!</span></code> or <code class="docutils literal notranslate"><span class="pre">=</span></code>, you’ll get a compiler error.
|
||||
For example:</p>
|
||||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* Do this */</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nb">NULL</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">foo</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="cm">/* Because if you have a typo (i.e., = instead of ==), this will</span>
|
||||
<span class="cm"> be a compile error rather than a subtle bug */</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nb">NULL</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">foo</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>More defensive programming: <em>always</em> include blocks in curly braces
|
||||
<code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">}</span></code>, even if they are only one line long. For example:</p>
|
||||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* Do this */</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">whatever</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">OMPI_SUCCESS</span><span class="p">;</span>
|
||||
<span class="p">}</span>
|
||||
|
||||
<span class="cm">/* Not this */</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">whatever</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">OMPI_SUCCESS</span><span class="p">;</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>PMIx requires a C99-compliant compiler.</p>
|
||||
<ul class="simple">
|
||||
<li><p>C++-style comments are now allowed (and preferred).</p></li>
|
||||
<li><p>C99-style mixing declarations are allow allowable (and preferred).</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><p><strong>ALWAYS</strong> include <code class="docutils literal notranslate"><span class="pre">pmix_config.h</span></code> as your first #include file.
|
||||
There are very, very few cases where
|
||||
this is not true (E.g., some bizarre Windows scenarios). But in
|
||||
99.9999% of cases, this file should be included <strong>first</strong> so that it
|
||||
can affect system-level #include files if necessary.</p></li>
|
||||
<li><p>Filenames and symbols must follow the <strong>prefix rule</strong> (see [e-mail
|
||||
thread](<a class="reference external" href="http://www.open-mpi.org/community/lists/devel/2009/07/6389.php">http://www.open-mpi.org/community/lists/devel/2009/07/6389.php</a>)):</p>
|
||||
<ul class="simple">
|
||||
<li><p>Filenames must be prefixed with <code class="docutils literal notranslate"><span class="pre"><framework>_<component></span></code>.</p></li>
|
||||
<li><p>Public symbols must be prefixed in components with
|
||||
<code class="docutils literal notranslate"><span class="pre">pmix_<framework>_<component></span></code>. When in doubt about
|
||||
whether a symbol is public, be safe and add the prefix.</p></li>
|
||||
<li><p>Non-public symbols must be declared <code class="docutils literal notranslate"><span class="pre">static</span></code> or otherwise made to
|
||||
not appear in the global scope.</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><p><strong>ALWAYS</strong> #define macros, even for logical values.</p>
|
||||
<ul>
|
||||
<li><p>The GNU Way is to <code class="docutils literal notranslate"><span class="pre">#define</span></code> a macro when it is “true” and to
|
||||
<code class="docutils literal notranslate"><span class="pre">#undef</span></code> it when it is “false”.</p></li>
|
||||
<li><p>In PMIx, we <strong>always</strong> <code class="docutils literal notranslate"><span class="pre">#define</span></code> a logical macro to be
|
||||
either 0 or 1 – we never <code class="docutils literal notranslate"><span class="pre">#undef</span></code> it.</p></li>
|
||||
<li><p>The reason for this is defensive programming: if you are only
|
||||
checking if a preprocessor macro is defined (via <code class="docutils literal notranslate"><span class="pre">#ifdef</span> <span class="pre">FOO</span></code> or
|
||||
<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">defined(FOO)</span></code>), you will get no warning when compiling if
|
||||
you accidentally misspell the macro name. However, if you use the
|
||||
logic test <code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">FOO</span></code> with an undefined macro (e.g., because you
|
||||
misspelled it), you’ll get a compiler warning or error.</p>
|
||||
<div class="tip admonition">
|
||||
<p class="admonition-title">Rationale</p>
|
||||
<p>Misspelled macro names can be tremendously difficult to find
|
||||
when they are buried in thousands of lines of code; we will
|
||||
take all the help from the preprocessor/compiler that we can
|
||||
get!</p>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* GNU Way - you will get no warning from the compiler if you</span>
|
||||
<span class="cm"> misspell "FOO"; the test will simply be false */</span>
|
||||
<span class="cp">#ifdef FOO</span>
|
||||
<span class="p">...</span>
|
||||
<span class="cp">#else</span>
|
||||
<span class="p">...</span>
|
||||
<span class="cp">#endif</span>
|
||||
|
||||
<span class="cm">/* PMIx Way - you will get a warning from the compiler if you</span>
|
||||
<span class="cm"> misspell "FOO"; the result of the test is a different value</span>
|
||||
<span class="cm"> than whether you spelled the macro name right or not */</span>
|
||||
<span class="cp">#if FOO</span>
|
||||
<span class="p">...</span>
|
||||
<span class="cp">#else</span>
|
||||
<span class="p">...</span>
|
||||
<span class="cp">#endif</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="shell-scripting">
|
||||
<h3><span class="section-number">12.7.1.3. </span>Shell scripting<a class="headerlink" href="#shell-scripting" title="Permalink to this heading"></a></h3>
|
||||
<p>Please read some of the existing shell code in the source code tree
|
||||
and try to use a similar style.</p>
|
||||
<ul>
|
||||
<li><p>Always enclose evaluated shell variables in quotes to ensure that
|
||||
multi-token values are handled properly.</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is bad</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="nv">$foo</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>bar<span class="p">;</span><span class="w"> </span><span class="k">then</span>
|
||||
|
||||
<span class="c1"># This is good</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="s2">"</span><span class="nv">$foo</span><span class="s2">"</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"bar"</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<ul>
|
||||
<li><p>The one exception to this is that when doing an assignment to a
|
||||
shell variable from another shell variable, it is not necessary to
|
||||
use quotes on the right hand side:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is harmless, but unnecessary</span>
|
||||
<span class="nv">foo</span><span class="o">=</span><span class="s2">"</span><span class="nv">$bar</span><span class="s2">"</span>
|
||||
|
||||
<span class="c1"># This is actually sufficient, even for multi-token values of $bar</span>
|
||||
<span class="nv">foo</span><span class="o">=</span><span class="nv">$bar</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><p>Do not use the <code class="docutils literal notranslate"><span class="pre">==</span></code> operator for <code class="docutils literal notranslate"><span class="pre">test</span></code> — this is a GNU
|
||||
extension and can cause portability problems on BSD systems.
|
||||
Instead, use the single <code class="docutils literal notranslate"><span class="pre">=</span></code> operator.</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is bad</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="s2">"</span><span class="nv">$foo</span><span class="s2">"</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s2">"bar"</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
|
||||
|
||||
<span class="c1"># This is good</span>
|
||||
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="s2">"</span><span class="nv">$foo</span><span class="s2">"</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"bar"</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="m4">
|
||||
<h3><span class="section-number">12.7.1.4. </span>m4<a class="headerlink" href="#m4" title="Permalink to this heading"></a></h3>
|
||||
<p>We do not have specific coding style guidelines for m4 (the language
|
||||
used to create the <code class="docutils literal notranslate"><span class="pre">configure</span></code> script). Please read some of the
|
||||
existing m4 code in the source code tree and try to use a similar
|
||||
style.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="tree-layout">
|
||||
<h2><span class="section-number">12.7.2. </span>Tree layout<a class="headerlink" href="#tree-layout" title="Permalink to this heading"></a></h2>
|
||||
<p>There are a few notable top-level directories in the source
|
||||
tree:</p>
|
||||
<ul class="simple">
|
||||
<li><p>The main PMIx source is under the <code class="docutils literal notranslate"><span class="pre">src</span></code> directory</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">config</span></code>: M4 scripts supporting the top-level <code class="docutils literal notranslate"><span class="pre">configure</span></code> script</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">etc</span></code>: Some miscellaneous text files</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">docs</span></code>: Source code for PMIx documentation</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">examples</span></code>: Trivial example programs</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">include</span></code>: The public PMIx headers</p></li>
|
||||
</ul>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">src</span></code> directory generates a top-level library named <code class="docutils literal notranslate"><span class="pre">libpmix</span></code>.
|
||||
It can be built as either a static or shared library. The directory
|
||||
structure under it includes:</p>
|
||||
<ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">class</span></code>: C++-like “classes” (using the OPAL class system)
|
||||
specific to this project</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">include</span></code>: Top-level internal include files</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">mca</span></code>: MCA frameworks and components specific to PMIx</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">runtime</span></code>: Startup and shutdown of PMIx at runtime</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">tools</span></code>: Executables specific to PMIx</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">util</span></code>: Random utility code</p></li>
|
||||
</ul>
|
||||
<p>The layout of the <code class="docutils literal notranslate"><span class="pre">mca</span></code> tree is strictly defined to be of the
|
||||
form:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>mca/FRAMEWORK/COMPONENT
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>To be explicit: it is forbidden to have a directory under the <code class="docutils literal notranslate"><span class="pre">mca</span></code>
|
||||
tree that does not meet this template (with the exception of <code class="docutils literal notranslate"><span class="pre">base</span></code>
|
||||
directories, explained below). Hence, only framework and component
|
||||
code can be in the <code class="docutils literal notranslate"><span class="pre">mca</span></code> tree.</p>
|
||||
<p>That is, framework and component names must be valid directory names
|
||||
(and C variables; more on that later). For example, the CLIENT PTL
|
||||
component is located in <code class="docutils literal notranslate"><span class="pre">mca/ptl/client/</span></code>.</p>
|
||||
<p>The name <code class="docutils literal notranslate"><span class="pre">base</span></code> is reserved; there cannot be a framework or component
|
||||
named <code class="docutils literal notranslate"><span class="pre">base</span></code>. Directories named <code class="docutils literal notranslate"><span class="pre">base</span></code> are reserved for the
|
||||
implementation of the MCA and frameworks. Here are a few examples (as
|
||||
of the v5.0.x source tree):</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Main implementation of the MCA</span>
|
||||
mca/base
|
||||
|
||||
<span class="c1"># Implementation of the ptl framework</span>
|
||||
mca/ptl/base
|
||||
|
||||
<span class="c1"># Implementation of the client component of the ptl framework</span>
|
||||
mca/ptl/client
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Under these mandated directories, frameworks and/or components may have
|
||||
arbitrary directory structures, however.</p>
|
||||
</div>
|
||||
<div class="section" id="symbol-visibility">
|
||||
<h2><span class="section-number">12.7.3. </span>Symbol Visibility<a class="headerlink" href="#symbol-visibility" title="Permalink to this heading"></a></h2>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">PMIX_EXPORT</span></code> macro provides a method to annotate symbols to indicate
|
||||
their intended visibility when compiling dynamically shared object files
|
||||
(e.g., <code class="docutils literal notranslate"><span class="pre">libpmix.so</span></code>).</p>
|
||||
<p>The macro expands to the appropriate compiler and platform flags for marking
|
||||
whether a symbol should be explicitly made public in the PMIx
|
||||
library namespace.
|
||||
The <code class="docutils literal notranslate"><span class="pre">PMIX_EXPORT</span></code> attribute is used to declare that a symbol is to be
|
||||
visible outside of the PMIx DSO’s scope.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is entirely related to dynamic library compilation and does not
|
||||
apply to static compilation.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="terminology.html" class="btn btn-neutral float-left" title="12.6. OpenPMIx terminology" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="frameworks.html" class="btn btn-neutral float-right" title="12.8. Internal frameworks" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx 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>
|
||||
379
macx64/mpi/openmpi/share/doc/pmix/html/developers/sphinx.html
Normal file
379
macx64/mpi/openmpi/share/doc/pmix/html/developers/sphinx.html
Normal file
@@ -0,0 +1,379 @@
|
||||
<!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>12.10. Installing and running Sphinx (building the OpenPMIx docs) — OpenPMIx 5.0.5 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.11. ReStructured Text for those who know Markdown" href="rst-for-markdown-expats.html" />
|
||||
<link rel="prev" title="12.9. 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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#installing-python">12.10.1. Installing Python</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#installing-sphinx">12.10.2. Installing Sphinx</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#install-sphinx-in-a-python-virtual-environment">12.10.2.1. Install Sphinx in a Python virtual environment</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#install-sphinx-globally">12.10.2.2. Install Sphinx globally</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#install-sphinx-locally">12.10.2.3. Install Sphinx locally</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#running-sphinx">12.10.3. Running Sphinx</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#sphinx-execution-time">12.10.3.1. Sphinx execution time</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#checking-sphinx-html-links">12.10.3.2. Checking Sphinx HTML links</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#viewing-docs-locally">12.10.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">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.10. </span>Installing and running Sphinx (building the OpenPMIx 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-openpmix-docs">
|
||||
<span id="developers-installing-sphinx-label"></span><h1><span class="section-number">12.10. </span>Installing and running Sphinx (building the OpenPMIx docs)<a class="headerlink" href="#installing-and-running-sphinx-building-the-openpmix-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 OpenPMIx code base itself.
|
||||
End users who install a binary OpenPMIx package or build from an
|
||||
official OpenPMIx distribution tarball do not need to have Sphinx
|
||||
installed.</p>
|
||||
<div class="section" id="installing-python">
|
||||
<h2><span class="section-number">12.10.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">12.10.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">12.10.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 OpenPMIx 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 OpenPMIx
|
||||
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_OpenPMIx_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">12.10.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_OpenPMIx_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 OpenPMIx 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">12.10.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_OpenPMIx_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 OpenPMIx 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">12.10.3. </span>Running Sphinx<a class="headerlink" href="#running-sphinx" title="Permalink to this heading"></a></h2>
|
||||
<p>OpenPMIx’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 OpenPMIx 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 OpenPMIx distribution tarballs. Meaning: if you
|
||||
download an official distribution OpenPMIx tarball,
|
||||
the pre-built HTML and man page files are included
|
||||
in the tarball.</p>
|
||||
<p>Sphinx is a requirement for <em>developers</em> who want to build
|
||||
the OpenPMIx docs. End users do <em>not</em> need to have Sphinx
|
||||
available to build OpenPMIx or have its docs installed from
|
||||
an official distribution tarball.</p>
|
||||
</div>
|
||||
<div class="section" id="sphinx-execution-time">
|
||||
<h3><span class="section-number">12.10.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 OpenPMIx (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">12.10.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">12.10.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>./PMIx_Abort.3
|
||||
</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/pmix/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/pmix/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>PMIx_Abort
|
||||
</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="12.9. 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="12.11. 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 2014-2025, The OpenPMIx 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,192 @@
|
||||
<!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>12.6. OpenPMIx terminology — OpenPMIx 5.0.5 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.7. Source code" href="source-code.html" />
|
||||
<link rel="prev" title="12.5. Building PMIx" href="building-pmix.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">
|
||||
OpenPMIx
|
||||
</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="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</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="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="git-github.html">12.2. GitHub, Git, and related topics</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.6. OpenPMIx terminology</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#modular-component-architecture-mca">12.6.1. Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#required-3rd-party-libraries">12.6.2. Required 3rd party libraries</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</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">OpenPMIx</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">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.6. </span>OpenPMIx terminology</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/terminology.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="openpmix-terminology">
|
||||
<h1><span class="section-number">12.6. </span>OpenPMIx terminology<a class="headerlink" href="#openpmix-terminology" title="Permalink to this heading"></a></h1>
|
||||
<p>OpenPMIx is a medium-sized project containing a number of different sub-systems and
|
||||
a relatively big code base. Let’s first cover some fundamental
|
||||
terminology in order to make the rest of the discussion easier.</p>
|
||||
<p>First, note that you will see <code class="docutils literal notranslate"><span class="pre">OpenPMIx</span></code> frequently referred to
|
||||
as just <code class="docutils literal notranslate"><span class="pre">PMIx</span></code>. While there is a separate PMIx Standard, there
|
||||
are (as of this writing) no alternative implementations of that
|
||||
Standard. In fact, the Standard post-dates the library by several
|
||||
years, and often lags behind the library in terms of new definitions.
|
||||
Thus, it is customary to refer to the library as just <code class="docutils literal notranslate"><span class="pre">PMIx</span></code> and
|
||||
drop the longer name - at least, until some other implementation
|
||||
arises (which many consider unlikely).</p>
|
||||
<div class="section" id="modular-component-architecture-mca">
|
||||
<h2><span class="section-number">12.6.1. </span>Modular Component Architecture (MCA)<a class="headerlink" href="#modular-component-architecture-mca" title="Permalink to this heading"></a></h2>
|
||||
<p><a class="reference internal" href="../mca.html#label-mca"><span class="std std-ref">See this section</span></a> for a discussion of the Modular
|
||||
Component Architecture (MCA). Seriously. Go read it now. From
|
||||
reading that section, you should understand the following terms before
|
||||
continuing reading these docs:</p>
|
||||
<ul class="simple">
|
||||
<li><p>Framework</p></li>
|
||||
<li><p>Component</p></li>
|
||||
<li><p>Module</p></li>
|
||||
<li><p>Parameters (variables)</p></li>
|
||||
</ul>
|
||||
<p>Frameworks, components, and modules can be dynamic or static. That is,
|
||||
they can be available as plugins or they may be compiled statically
|
||||
into libraries (e.g., <code class="docutils literal notranslate"><span class="pre">libpmix</span></code>).</p>
|
||||
<p>In PMIx, <code class="docutils literal notranslate"><span class="pre">configure</span></code> defaults to:</p>
|
||||
<ul class="simple">
|
||||
<li><p>Building <code class="docutils literal notranslate"><span class="pre">libpmix</span></code> as a dynamic library</p></li>
|
||||
<li><p>Linking all components directly into the <code class="docutils literal notranslate"><span class="pre">libpmix</span></code> libraries
|
||||
(vs. compiling them as independent DSOs)</p></li>
|
||||
</ul>
|
||||
<p>These defaults can be modified by <a class="reference internal" href="../installing-pmix/configure-cli-options/index.html"><span class="doc">command line
|
||||
arguments to configure</span></a>.</p>
|
||||
</div>
|
||||
<div class="section" id="required-3rd-party-libraries">
|
||||
<h2><span class="section-number">12.6.2. </span>Required 3rd party libraries<a class="headerlink" href="#required-3rd-party-libraries" title="Permalink to this heading"></a></h2>
|
||||
<p>Note that PMIx uses two third-party libraries for core
|
||||
functionality:</p>
|
||||
<ul class="simple">
|
||||
<li><p>Libevent or Libev</p></li>
|
||||
<li><p>Hardware Locality (“hwloc”)</p></li>
|
||||
</ul>
|
||||
<p>These are discussed in detail in the <a class="reference internal" href="../installing-pmix/required-support-libraries.html#label-install-required-support-libraries"><span class="std std-ref">required support libraries
|
||||
section</span></a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="building-pmix.html" class="btn btn-neutral float-left" title="12.5. Building PMIx" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="source-code.html" class="btn btn-neutral float-right" title="12.7. Source code" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx 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