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
325
326
327
328
329
330
331
332
333
334
335
336
337
|
<!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>7. Version numbers and compatibility — Open MPI 5.0.8 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="8. The Modular Component Architecture (MCA)" href="mca.html" />
<link rel="prev" title="6. Validating your installation" href="validate.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">
Open MPI
</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="installing-open-mpi/index.html">4. Building and installing Open MPI</a></li>
<li class="toctree-l1"><a class="reference internal" href="features/index.html">5. Open MPI-specific features</a></li>
<li class="toctree-l1"><a class="reference internal" href="validate.html">6. Validating your installation</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">7. Version numbers and compatibility</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#backward-compatibility">7.1. Backward Compatibility</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#open-mpi-ompi-series-mca-parameter-compatibility">7.1.1. Open MPI v5.0.x MCA parameter compatibility</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#software-version-number">7.2. Software Version Number</a></li>
<li class="toctree-l2"><a class="reference internal" href="#shared-library-version-number">7.3. Shared Library Version Number</a></li>
<li class="toctree-l2"><a class="reference internal" href="#api-and-abi-compatibility">7.4. API and ABI Compatibility</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#open-mpi-ompi-series-abi-compatibility">7.4.1. Open MPI v5.0.x ABI compatibility</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="mca.html">8. The Modular Component Architecture (MCA)</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-apps/index.html">9. Building MPI applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="launching-apps/index.html">10. Launching MPI applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="tuning-apps/index.html">11. Run-time operation and tuning MPI applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="app-debug/index.html">12. Debugging Open MPI Parallel Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="developers/index.html">13. Developer’s guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">14. Contributing to Open MPI</a></li>
<li class="toctree-l1"><a class="reference internal" href="license/index.html">15. License</a></li>
<li class="toctree-l1"><a class="reference internal" href="history.html">16. History of Open MPI</a></li>
<li class="toctree-l1"><a class="reference internal" href="man-openmpi/index.html">17. Open MPI manual pages</a></li>
<li class="toctree-l1"><a class="reference internal" href="man-openshmem/index.html">18. OpenSHMEM 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">Open MPI</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">7. </span>Version numbers and compatibility</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/version-numbering.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="version-numbers-and-compatibility">
<span id="version-numbers-section-label"></span><h1><span class="section-number">7. </span>Version numbers and compatibility<a class="headerlink" href="#version-numbers-and-compatibility" title="Permalink to this heading"></a></h1>
<p>Open MPI has two sets of version numbers that are likely of interest
to end users / system administrators:</p>
<ol class="arabic simple">
<li><p>Software version number</p></li>
<li><p>Shared library version numbers</p></li>
</ol>
<p>Both are predicated on Open MPI’s definition of “backward compatibility.”</p>
<div class="section" id="backward-compatibility">
<h2><span class="section-number">7.1. </span>Backward Compatibility<a class="headerlink" href="#backward-compatibility" title="Permalink to this heading"></a></h2>
<p>Open MPI version Y is backward compatible with Open MPI version X
(where Y>X) if users can:</p>
<ul class="simple">
<li><p>Compile an MPI/OpenSHMEM application with version X,
<code class="docutils literal notranslate"><span class="pre">mpirun</span></code>/<code class="docutils literal notranslate"><span class="pre">oshrun</span></code> it with version Y, and get the same
user-observable behavior.</p></li>
<li><p>Invoke <code class="docutils literal notranslate"><span class="pre">ompi_info</span></code> with the same CLI options in versions X and Y and
get the same user-observable behavior.</p></li>
</ul>
<p>Note that this definition encompasses several things:</p>
<ul class="simple">
<li><p>Application Binary Interface (ABI)</p></li>
<li><p>MPI / OpenSHMEM run time system</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mpirun</span></code> / <code class="docutils literal notranslate"><span class="pre">oshrun</span></code> command line options</p></li>
<li><p>MCA parameter names / values / meanings</p></li>
</ul>
<p>However, this definition only applies when the same version of Open
MPI is used with all instances of the runtime and MPI / OpenSHMEM
processes in a single MPI job. If the versions are not exactly the
same everywhere, Open MPI is not guaranteed to work properly in any
scenario.</p>
<p>Backward compatibility tends to work best when user applications are
dynamically linked to one version of the Open MPI / OSHMEM libraries,
and can be updated at run time to link to a new version of the Open
MPI / OSHMEM libraries.</p>
<p>For example, if an MPI / OSHMEM application links statically against
the libraries from Open MPI vX, then attempting to launch that
application with <code class="docutils literal notranslate"><span class="pre">mpirun</span></code> / <code class="docutils literal notranslate"><span class="pre">oshrun</span></code> from Open MPI vY is not guaranteed to
work (because it is mixing vX and vY of Open MPI in a single job).</p>
<p>Similarly, if using a container technology that internally bundles all
the libraries from Open MPI vX, attempting to launch that container
with <code class="docutils literal notranslate"><span class="pre">mpirun</span></code> / <code class="docutils literal notranslate"><span class="pre">oshrun</span></code> from Open MPI vY is not guaranteed to work.</p>
<div class="section" id="open-mpi-ompi-series-mca-parameter-compatibility">
<h3><span class="section-number">7.1.1. </span>Open MPI v5.0.x MCA parameter compatibility<a class="headerlink" href="#open-mpi-ompi-series-mca-parameter-compatibility" title="Permalink to this heading"></a></h3>
<p>Several MCA parameters have been deprecated in Open MPI v5.0.x, please
see this <a class="reference internal" href="mca.html#label-mca-backward-compat"><span class="std std-ref">table</span></a> for the full list.</p>
</div>
</div>
<div class="section" id="software-version-number">
<h2><span class="section-number">7.2. </span>Software Version Number<a class="headerlink" href="#software-version-number" title="Permalink to this heading"></a></h2>
<p>Official Open MPI releases use the common “A.B.C” version identifier
format. Each of the three numbers has a specific meaning:</p>
<ul>
<li><p>Major: The major number is the first integer in the version string
Changes in the major number typically indicate a significant
change in the code base and/or end-user functionality, and also
indicate a break from backward compatibility. Specifically: Open
MPI releases with different major version numbers are not
backward compatibale with each other.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>This rule does not extend to versions prior to
v1.10.0. Specifically: v1.10.x is not guaranteed to be backward
compatible with other v1.x releases.</p>
</div>
</li>
<li><p>Minor: The minor number is the second integer in the version string.
Changes in the minor number indicate a user-observable change in the
code base and/or end-user functionality. Backward compatibility
will still be preserved with prior releases that have the same major
version number (e.g., v2.5.3 is backward compatible with v2.3.1).</p></li>
<li><p>Release: The release number is the third integer in the version
string. Changes in the release number typically indicate a bug fix
in the code base and/or end-user functionality. For example, if
there is a release that only contains bug fixes and no other
user-observable changes or new features, only the third integer will
be increased (e.g., from v4.3.0 to v4.3.1).</p></li>
</ul>
<p>The “A.B.C” version number may optionally be followed by a quantifier
string:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">aX</span></code>: Indicates an alpha release. X is an integer indicating the
number of the alpha release (e.g., v1.10.3a5 indicates the 5th alpha
release of version 1.10.3).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">bX</span></code>: Indicates a beta release. X is an integer indicating the
number of the beta release (e.g., v1.10.3b3 indicates the 3rd beta
release of version 1.10.3).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">rcX</span></code>: Indicates a release candidate. X is an integer indicating
the number of the release candidate (e.g., v1.10.3rc4 indicates the
4th release candidate of version 1.10.3).</p></li>
</ul>
<p>Nightly development snapshot tarballs use a different version number
scheme; they contain three distinct values:</p>
<ul class="simple">
<li><p>The git branch name from which the tarball was created.</p></li>
<li><p>The date/timestamp, in <code class="docutils literal notranslate"><span class="pre">YYYYMMDDHHMM</span></code> format.</p></li>
<li><p>The hash of the git commit from which the tarball was created.</p></li>
</ul>
<p>For example, a snapshot tarball filename of
<code class="docutils literal notranslate"><span class="pre">openmpi-v2.x-201703070235-e4798fb.tar.bz2</span></code> indicates that this tarball
was created from the v2.x branch, on March 7, 2017, at 2:35am GMT,
from git hash e4798fb.</p>
</div>
<div class="section" id="shared-library-version-number">
<h2><span class="section-number">7.3. </span>Shared Library Version Number<a class="headerlink" href="#shared-library-version-number" title="Permalink to this heading"></a></h2>
<p>The <a class="reference external" href="https://www.gnu.org/software/libtool/manual/">GNU Libtool official documentation</a> details how the
versioning scheme works. The quick version is that the shared library
versions are a triple of integers: (current,revision,age), or
<code class="docutils literal notranslate"><span class="pre">c:r:a</span></code>. This triple is not related to the Open MPI software
version number. There are six simple rules for updating the values
(taken almost verbatim from the Libtool docs):</p>
<ol class="arabic simple">
<li><p>Start with version information of <code class="docutils literal notranslate"><span class="pre">0:0:0</span></code> for each shared library.</p></li>
<li><p>Update the version information only immediately before a public
release of your software. More frequent updates are unnecessary,
and only guarantee that the current interface number gets larger
faster.</p></li>
<li><p>If the library source code has changed at all since the last
update, then increment revision (<code class="docutils literal notranslate"><span class="pre">c:r:a</span></code> becomes <code class="docutils literal notranslate"><span class="pre">c:r+1:a</span></code>).</p></li>
<li><p>If any interfaces have been added, removed, or changed since the
last update, increment current, and set revision to 0.</p></li>
<li><p>If any interfaces have been added since the last public release,
then increment age.</p></li>
<li><p>If any interfaces have been removed since the last public release,
then set age to 0.</p></li>
</ol>
<p>Here’s how we apply those rules specifically to Open MPI:</p>
<ol class="arabic">
<li><p>The above rules do not apply to MCA components (a.k.a. “plugins”);
MCA component <code class="docutils literal notranslate"><span class="pre">.so</span></code> versions stay unspecified.</p></li>
<li><p>The above rules apply exactly as written to the following libraries
starting with Open MPI version v1.5:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">libopen-pal</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">libmca_common_*</span></code></p></li>
</ul>
</div></blockquote>
</li>
<li><p>The following libraries use a slightly modified version of the
above rules: rules 4, 5, and 6 only apply to the official MPI and
OpenSHMEM interfaces (functions, global variables). The rationale
for this decision is that the vast majority of our users only care
about the official/public MPI/OpenSHMEM interfaces; we therefore
want the <code class="docutils literal notranslate"><span class="pre">.so</span></code> version number to reflect only changes to the
official MPI/OpenSHMEM APIs. Put simply: non-MPI/OpenSHMEM API /
internal changes to the MPI-application-facing libraries are
irrelevant to pure MPI/OpenSHMEM applications.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">libmpi</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">libmpi_mpifh</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">libmpi_usempi_tkr</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">libmpi_usempi_ignore_tkr</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">libmpi_usempif08</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">libmpi_cxx</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">libmpi_java</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">liboshmem</span></code></p></li>
</ul>
</li>
</ol>
</div>
<div class="section" id="api-and-abi-compatibility">
<h2><span class="section-number">7.4. </span>API and ABI Compatibility<a class="headerlink" href="#api-and-abi-compatibility" title="Permalink to this heading"></a></h2>
<p>Open MPI provides the following Application Programming Interface
(API) and Application Binary Interface (ABI) compatibility guarantees
for applications:</p>
<ol class="arabic simple">
<li><p>Open MPI is source code compatible (i.e., API compatible) across all
versions. This means that you can compile and link your compliant MPI
application against <a class="reference internal" href="release-notes/mpi.html#release-notes-mpi-standard-conformance-label"><span class="std std-ref">any version of Open MPI that supports the version
of the MPI standard</span></a> to
which your application was written.</p></li>
<li><p>Open MPI provided forward application binary interface (ABI)
compatibility within a major series for MPI applications starting
with v1.3.2. Prior to that version, no ABI guarantees were
provided.</p></li>
<li><p>Open MPI reserves the right to break ABI compatibility at new major
release series.</p></li>
</ol>
<div class="section" id="open-mpi-ompi-series-abi-compatibility">
<h3><span class="section-number">7.4.1. </span>Open MPI v5.0.x ABI compatibility<a class="headerlink" href="#open-mpi-ompi-series-abi-compatibility" title="Permalink to this heading"></a></h3>
<p>The Open MPI v5.0.x series shared libraries are ABI compatible
with Open MPI v4.0.x and v4.1.x, with a few exceptions for Fortran.</p>
<ul class="simple">
<li><p>If your Fortran application was compiled in such a way that the size
of an integer in C is different than the size of an integer in
Fortran, you will need to rebuild and relink your application
against Open MPI v5.0.x.</p></li>
<li><p>There are also Fortran API changes involving intents and
<code class="docutils literal notranslate"><span class="pre">ASYNCHRONOUS</span></code>, and some interfaces changed from named to unnamed.
These may require changes to an application’s source code, followed
by recompilation and relinking.</p></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="validate.html" class="btn btn-neutral float-left" title="6. Validating your installation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="mca.html" class="btn btn-neutral float-right" title="8. The Modular Component Architecture (MCA)" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2003-2025, The Open MPI Community.
<span class="lastupdated">Last updated on 2025-05-30 16:41:43 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>
|
