1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
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>5.1. Installation — OpenPMIx 5.0.8a1 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="5.2. Definitions" href="definitions.html" />
<link rel="prev" title="5. Building and installing PMIx" 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 current"><a class="reference internal" href="index.html">5. Building and installing PMIx</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">5.1. Installation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#developer-builds">5.1.1. Developer Builds</a></li>
<li class="toctree-l3"><a class="reference internal" href="#user-builds">5.1.2. User Builds</a></li>
<li class="toctree-l3"><a class="reference internal" href="#configure-options">5.1.3. <code class="docutils literal notranslate"><span class="pre">configure</span></code> options</a></li>
<li class="toctree-l3"><a class="reference internal" href="#building-static-libraries">5.1.4. Building Static Libraries</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="definitions.html">5.2. Definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="filesystem-requirements.html">5.3. Filesystem requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="vpath-builds.html">5.4. VPATH builds</a></li>
<li class="toctree-l2"><a class="reference internal" href="compilers-and-flags.html">5.5. Specifying compilers and flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="required-support-libraries.html">5.6. Required support libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="configure-cli-options/index.html">5.7. <code class="docutils literal notranslate"><span class="pre">configure</span></code> command line options</a></li>
<li class="toctree-l2"><a class="reference internal" href="configure-output-summary.html">5.8. <code class="docutils literal notranslate"><span class="pre">configure</span></code> output summary</a></li>
<li class="toctree-l2"><a class="reference internal" href="make-targets.html">5.9. <code class="docutils literal notranslate"><span class="pre">make</span></code> targets</a></li>
<li class="toctree-l2"><a class="reference internal" href="installation-location.html">5.10. Installation location</a></li>
<li class="toctree-l2"><a class="reference internal" href="packagers.html">5.11. Advice for packagers</a></li>
</ul>
</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"><a class="reference internal" href="../developers/index.html">12. Developer’s guide</a></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">5. </span>Building and installing PMIx</a></li>
<li class="breadcrumb-item active"><span class="section-number">5.1. </span>Installation</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/installing-pmix/quickstart.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="installation">
<span id="label-quickstart-building-pmix"></span><h1><span class="section-number">5.1. </span>Installation<a class="headerlink" href="#installation" title="Permalink to this heading"></a></h1>
<p>This file is a <em>very</em> short overview of building and installing the
PMIx library. Much more information is available in the <a class="reference external" href="https://pmix.org/support/how-to/">How-To
section on the PMIx web site</a>.</p>
<div class="section" id="developer-builds">
<h2><span class="section-number">5.1.1. </span>Developer Builds<a class="headerlink" href="#developer-builds" title="Permalink to this heading"></a></h2>
<p>If you have checked out a DEVELOPER’S COPY of PMIx (i.e., you checked
out from Git), you should read the <a class="reference internal" href="../developers/index.html"><span class="doc">Developer’s Guide</span></a> section before attempting to build PMIx. You
must then run:</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
shell$<span class="w"> </span>./autogen.pl
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">submodule</span> <span class="pre">update</span></code> is required as PMIx incorporates a submodule
to support its <cite>autoconf</cite> logic. You can, however, omit the explicit
submodule update step <cite>if</cite> you cloned the Git repository with the
<code class="docutils literal notranslate"><span class="pre">--recursive</span></code> flag.</p>
<p>You will need very recent versions of GNU Autoconf, Automake, and
Libtool. If <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code> fails, read the <a class="reference internal" href="../developers/index.html"><span class="doc">Developer’s Guide</span></a>. If anything else fails, read the
<a class="reference internal" href="../developers/index.html"><span class="doc">Developer’s Guide</span></a>. Finally, we suggest
reading the <a class="reference internal" href="../developers/index.html"><span class="doc">Developer’s Guide</span></a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Developer’s copies of OpenPMIx typically include a large
performance penalty at run-time because of extra debugging
overhead.</p>
</div>
</div>
<div class="section" id="user-builds">
<h2><span class="section-number">5.1.2. </span>User Builds<a class="headerlink" href="#user-builds" title="Permalink to this heading"></a></h2>
<p>Building PMIx is typically a combination of running <code class="docutils literal notranslate"><span class="pre">configure</span></code>
and <code class="docutils literal notranslate"><span class="pre">make</span></code>. Execute the following commands to install the PMIx
system from within the directory at the top of the tree:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>./configure<span class="w"> </span>--prefix<span class="o">=</span>/where/to/install
<span class="o">[</span>...lots<span class="w"> </span>of<span class="w"> </span>output...<span class="o">]</span>
shell$<span class="w"> </span>make<span class="w"> </span>all<span class="w"> </span>install
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This version of PMIx requires the following 3rd-party
packages to build and operate:</p>
<ul class="simple">
<li><p>either the <a class="reference external" href="https://libevent.org/">Libevent package</a> (any version
of Libevent greater than or equal to 2.0.21 is acceptable) or
the <a class="reference external" href="https://metacpan.org/dist/EV/view/libev/ev.pod">libev package</a>
(no minimum version has been identified).</p></li>
<li><p>the <a class="reference external" href="https://www.open-mpi.org/projects/hwloc/">HWLOC package</a> for providing
topology information to both the host environment (by
collecting local inventory for rollup) and local client
processes. Any version of HWLOC greater than 1.10 is
supported, although versions in the 2.x series are
recommended.</p></li>
</ul>
</div>
<p>Note that you must point <code class="docutils literal notranslate"><span class="pre">configure</span></code> at these packages if they are
in a non-standard location - libevent using the <code class="docutils literal notranslate"><span class="pre">--with-libevent=<dir></span></code>
option; libev using the <code class="docutils literal notranslate"><span class="pre">-with-libev=<dir></span></code> option, and HWLOC package
using the <code class="docutils literal notranslate"><span class="pre">--with-hwloc=<dir></span></code> option. In all cases,
PMIx will automatically detect these packages in standard locations
and use them unless otherwise specified using the
respective configure option.</p>
<p>If you need special access to install, then you can execute <code class="docutils literal notranslate"><span class="pre">make</span>
<span class="pre">all</span></code> as a user with write permissions in the build tree, and a
separate <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code> as a user with write permissions to the
install tree.</p>
<p>Compiling support for specific compilers and environments may require
additional command line flags when running <code class="docutils literal notranslate"><span class="pre">configure</span></code>. See the
<a class="reference internal" href="compilers-and-flags.html#install-configure-compilers-and-flags-label"><span class="std std-ref">compiler flags</span></a> entry
for more details.</p>
<p>Note that VPATH builds are fully supported. For example:</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-X.Y.Z.tar.gz
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>pmix-X.Y.Z
shell$<span class="w"> </span>mkdir<span class="w"> </span>build
shell$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>build
shell$<span class="w"> </span>../configure<span class="w"> </span>...your<span class="w"> </span>options...
<span class="o">[</span>...lots<span class="w"> </span>of<span class="w"> </span>output...<span class="o">]</span>
shell$<span class="w"> </span>make<span class="w"> </span>all<span class="w"> </span>install
</pre></div>
</div>
<p>Parallel builds are also supported (although some versions of <code class="docutils literal notranslate"><span class="pre">make</span></code>,
such as GNU make, will only use the first target listed on the command
line when executable parallel builds). For example (assume GNU make):</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>make<span class="w"> </span>-j<span class="w"> </span><span class="m">4</span><span class="w"> </span>all
<span class="o">[</span>...lots<span class="w"> </span>of<span class="w"> </span>output...<span class="o">]</span>
shell$<span class="w"> </span>make<span class="w"> </span>install
</pre></div>
</div>
<p>Parallel make is generally only helpful in the build phase; the
installation process is mostly serial and does not benefit much from
parallel make.</p>
</div>
<div class="section" id="configure-options">
<h2><span class="section-number">5.1.3. </span><code class="docutils literal notranslate"><span class="pre">configure</span></code> options<a class="headerlink" href="#configure-options" title="Permalink to this heading"></a></h2>
<p>There are many available options to <code class="docutils literal notranslate"><span class="pre">configure</span></code> (see <code class="docutils literal notranslate"><span class="pre">./configure</span> <span class="pre">--help</span></code>
for a full list); a summary of the more commonly used ones follows:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">--prefix=<directory></span></code>: Install PMIx into the base directory named
<code class="docutils literal notranslate"><span class="pre"><directory></span></code>. Hence, PMIx will place its executables in
<code class="docutils literal notranslate"><span class="pre"><directory>/bin</span></code>, its header files in <code class="docutils literal notranslate"><span class="pre"><directory>/include</span></code>,
its libraries in <code class="docutils literal notranslate"><span class="pre"><directory>/lib</span></code>, etc.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--disable-shared</span></code>: By default, <code class="docutils literal notranslate"><span class="pre">libpmix</span></code> is built as a shared
library. This switch disables this default; it is really only
useful when used with <code class="docutils literal notranslate"><span class="pre">--enable-static</span></code>. Specifically, this
option does <em>not</em> imply <code class="docutils literal notranslate"><span class="pre">--enable-static</span></code>; enabling static
libraries and disabling shared libraries are two independent
options.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--enable-static</span></code>: Build <code class="docutils literal notranslate"><span class="pre">libpmix</span></code> as a static library. Note
that this option does <em>not</em> imply <code class="docutils literal notranslate"><span class="pre">--disable-shared</span></code>; enabling
static libraries and disabling shared libraries are two independent
options. Please see the <a class="reference internal" href="#label-install-static-libraries"><span class="std std-ref">Building Static Libraries</span></a> section below for important
details on building PMIx as a static library.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--disable-show-load-errors-by-default</span></code>: Set the default value of
the <code class="docutils literal notranslate"><span class="pre">mca_base_component_show_load_errors</span></code> MCA variable: the
<code class="docutils literal notranslate"><span class="pre">--enable</span></code> form of this option sets the MCA variable to true, the
<code class="docutils literal notranslate"><span class="pre">--disable</span></code> form sets the MCA variable to false. The MCA
<code class="docutils literal notranslate"><span class="pre">mca_base_component_show_load_errors</span></code> variable can still be
overridden at run time via the usual MCA-variable-setting
mechanisms; this configure option simply sets the default value.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--disable</span></code> form of this option is intended for OpenPMIx
packagers who tend to enable support for many different types of
networks and systems in their packages. For example, consider a
packager who includes support for both the FOO and BAR networks in
their PMIx package, both of which require support libraries
(<code class="docutils literal notranslate"><span class="pre">libFOO.so</span></code> and <code class="docutils literal notranslate"><span class="pre">libBAR.so</span></code>). If an end user only has BAR
hardware, they likely only have <code class="docutils literal notranslate"><span class="pre">libBAR.so</span></code> available on their
systems – not <code class="docutils literal notranslate"><span class="pre">libFOO.so</span></code>. Disabling load errors by default will
prevent the user from seeing potentially confusing warnings about
the FOO components failing to load because <code class="docutils literal notranslate"><span class="pre">libFOO.so</span></code> is not
available on their systems.</p>
<p>Conversely, system administrators tend to build an OpenPMIx that is
targeted at their specific environment, and contains few (if any)
components that are not needed. In such cases, they might want
their users to be warned that the FOO network components failed to
load (e.g., if <code class="docutils literal notranslate"><span class="pre">libFOO.so</span></code> was mistakenly unavailable), and thus
some PMIx calls might unexpectedly return “not supported”.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">--with-platform=FILE</span></code>: Load configure options for the build from
<code class="docutils literal notranslate"><span class="pre">FILE</span></code>. Options on the command line that are not in <code class="docutils literal notranslate"><span class="pre">FILE</span></code> are
also used. Options on the command line and in <code class="docutils literal notranslate"><span class="pre">FILE</span></code> are replaced
by what is in <code class="docutils literal notranslate"><span class="pre">FILE</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--enable-python-bindings</span></code>:
Build the Python bindings for PMIx. Note the following packages
are required to be installed:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>Cython<span class="w"> </span>python3<span class="w"> </span>python3-devel
or...
shell$<span class="w"> </span>pip3<span class="w"> </span>install<span class="w"> </span>Cython
</pre></div>
</div>
</li>
</ul>
<p>Once OpenPMIx has been built and installed, it is safe to run <code class="docutils literal notranslate"><span class="pre">make</span>
<span class="pre">clean</span></code> and/or remove the entire build tree.</p>
<p>VPATH and parallel builds are fully supported.</p>
<p>Generally speaking, the only thing that users need to do to use OpenPMIx
is ensure that <code class="docutils literal notranslate"><span class="pre"><prefix>/lib</span></code> is in their <code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code>. Users may
need to ensure to set <code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code> in their shell setup files (e.g.,
<code class="docutils literal notranslate"><span class="pre">.bashrc</span></code>, <code class="docutils literal notranslate"><span class="pre">.cshrc</span></code>) so that non-interactive SSH-based logins will
be able to find the OpenPMIx library.</p>
</div>
<div class="section" id="building-static-libraries">
<span id="label-install-static-libraries"></span><h2><span class="section-number">5.1.4. </span>Building Static Libraries<a class="headerlink" href="#building-static-libraries" title="Permalink to this heading"></a></h2>
<p>PMIx depends on a number of external libraries for critical
functionality. Some of these libraries, such as <a class="reference external" href="https://www.open-mpi.org/projects/hwloc/">HWLOC</a>, can have dependencies on
a varying number of additional libraries (such as libpci or libudev).
While PMIx’s wrapper compiler will add the correct direct dependencies
for third party packages, it will frequently not pull in the right
sub-libraries. When linking against dyanamic library versions of
these dependencies, this is not a problem (and is preferred behavior
to avoid adding unnecessary indirect linking dependencies). However,
this does cause problems for building entirely static versions of
PMIx. It may be necessary in some circumstances to add these
dependencies via the <code class="docutils literal notranslate"><span class="pre">LIBS</span></code> environment variable (for building PMIx
binaries) or <code class="docutils literal notranslate"><span class="pre">--with-wrapper-libs=LIBS</span></code> for the wrapper compiler.</p>
</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="5. Building and installing PMIx" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="definitions.html" class="btn btn-neutral float-right" title="5.2. Definitions" 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, OpenPMIx Community.
<span class="lastupdated">Last updated on 2025-05-30 16:40:24 UTC.
</span></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>
|
