Open MPI logo

Open MPI: Version Number Methodology

  |   Home   |   Support   |   FAQ   |  
The following text is taken directly from the Open MPI README file in the development branch.

Open MPI Version Numbers and Binary Compatibility

Open MPI has two sets of version numbers that are likely of interest
to end users / system administrator:

    * Software version number
    * Shared library version numbers

Both are described below, followed by a discussion of application
binary interface (ABI) compatibility implications.

Software Version Number

The version number of Open MPI distribution tarballs are the union of
several different values: major, minor, release, and an optional

  * Major: The major number is the first integer in the version string
    (e.g., v1.2.3). Changes in the major number typically indicate a
    significant change in the code base and/or end-user
    functionality. The major number is always included in the version

  * Minor: The minor number is the second integer in the version
    string (e.g., v1.2.3). Changes in the minor number typically
    indicate a incremental change in the code base and/or end-user
    functionality. The minor number is always included in the version
    number. Starting with Open MPI v1.3.0, the minor release number
    took on additional significance (see this wiki page for more

    o Even minor release numbers are part of "super-stable"
      release series (e.g., v1.4.0). Releases in super stable series
      are well-tested, time-tested, and mature. Such releases are
      recomended for production sites. Changes between subsequent
      releases in super stable series are expected to be fairly small.
    o Odd minor release numbers are part of "feature" release
      series (e.g., 1.3.7). Releases in feature releases are
      well-tested, but they are not necessarily time-tested or as
      mature as super stable releases. Changes between subsequent
      releases in feature series may be large.

  * Release: The release number is the third integer in the version
    string (e.g., v1.2.3). Changes in the release number typically
    indicate a bug fix in the code base and/or end-user
    functionality. If the release number is 0, it is omitted from the
    version number (e.g., v1.2 has a release number of 0).

  * Quantifier: Open MPI version numbers sometimes have an arbitrary
    string affixed to the end of the version number. Common strings

    o aX: Indicates an alpha release. X is an integer indicating
      the number of the alpha release (e.g., v1.2.3a5 indicates the
      5th alpha release of version 1.2.3).
    o bX: Indicates a beta release. X is an integer indicating
      the number of the beta release (e.g., v1.2.3b3 indicates the 3rd
      beta release of version 1.2.3).
    o rcX: Indicates a release candidate. X is an integer
      indicating the number of the release candidate (e.g., v1.2.3rc4
      indicates the 4th release candidate of version 1.2.3).
    o Prior to October 2014, nightly snapshot tarballs would include a
      repository version number as well, such as r1234, indicating
      that that snapshot tarball was built at Subversion r1234).

Starting in October 2014, although the major, minor, and release
values (and optional quantifiers) are reported in Open MPI nightly
snapshot tarballs, the filenames of these snapshot tarballs follow a
slightly different convention.

Specifically, the snapshot tarball filename contains three distinct

   * Most recent Git tag name on the branch from which the tarball was

   * An integer indicating how many Git commits have occurred since
     that Git tag.

   * The Git hash of the tip of the branch.

For example, a snapshot tarball filename of
"openmpi-v1.8.2-57-gb9f1fd9.tar.bz2" indicates that this tarball was
created from the v1.8 branch, 57 Git commits after the "v1.8.2" tag,
specifically at Git hash gb9f1fd9.

Open MPI's Git master branch contains a single "dev" tag.  For
example, "openmpi-dev-8-gf21c349.tar.bz2" represents a snapshot
tarball created from the master branch, 8 Git commits after the "dev"
tag, specifically at Git hash gf21c349.

The exact value of the "number of Git commits past a tag" integer is
fairly meaningless; its sole purpose is to provide an easy,
human-recognizable ordering for snapshot tarballs.

Shared Library Version Number

Open MPI started using the GNU Libtool shared library versioning
scheme with the release of v1.3.2.

NOTE: Only official releases of Open MPI adhere to this versioning
      scheme. "Beta" releases, release candidates, and nightly
      tarballs, developer snapshots, and Subversion/Mercurial snapshot
      tarballs likely will all have arbitrary/meaningless shared
      library version numbers.

For deep voodoo technical reasons, only the MPI API libraries were
versioned until Open MPI v1.5 was released (i.e., libmpi*so -- or were not versioned until v1.5).
Please see for more

NOTE: This policy change will cause an ABI incompatibility between MPI
      applications compiled/linked against the Open MPI v1.4 series;
      such applications will not be able to upgrade to the Open MPI
      v1.5 series without re-linking.  Sorry folks!

The GNU Libtool official documentation details how the versioning
scheme works.  The quick version is that the shared library versions
are a triple of integers: (current,revision,age), or "c:r:a".  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):

 1. Start with version information of "0:0:0" for each shared library.

 2. 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

 3. If the library source code has changed at all since the last
    update, then increment revision ("c:r:a" becomes "c:r+1:a").

 4. If any interfaces have been added, removed, or changed since the
    last update, increment current, and set revision to 0.

 5. If any interfaces have been added since the last public release,
    then increment age.

 6. If any interfaces have been removed since the last public release,
    then set age to 0.

Here's how we apply those rules specifically to Open MPI:

 1. The above rules do not apply to MCA components (a.k.a. "plugins");
    MCA component .so versions stay unspecified.

 2. The above rules apply exactly as written to the following
    libraries starting with Open MPI version v1.5 (prior to v1.5,
    libopen-pal and libopen-rte were still at 0:0:0 for reasons
    discussed in bug ticket #2092

    * libopen-rte
    * libopen-pal
    * libmca_common_*

 3. The following libraries use a slightly modified version of the
    above rules: rules 4, 5, and 6 only apply to the official MPI
    interfaces (functions, global variables).  The rationale for this
    decision is that the vast majority of our users only care about
    the official/public MPI interfaces; we therefore want the .so
    version number to reflect only changes to the official MPI API.
    Put simply: non-MPI API / internal changes to the
    MPI-application-facing libraries are irrelevant to pure MPI

    * libmpi
    * libmpi_mpifh
    * libmpi_usempi_tkr
    * libmpi_usempi_ignore_tkr
    * libmpi_usempif08
    * libmpi_cxx

 4. Note, however, that can have its "revision" number
    incremented if libopen-rte or libopen-pal change (because these
    two libraries are wholly included in  Specifically:
    the revision will change, but since we have defined that the only
    relevant API interface in is the official MPI API,
    updates to libopen-rte and libopen-pal do not change the "current"
    or "age" numbers of

Application Binary Interface (ABI) Compatibility

Open MPI provided forward application binary interface (ABI)
compatibility for MPI applications starting with v1.3.2.  Prior to
that version, no ABI guarantees were provided.  

Starting with v1.3.2, Open MPI provides forward ABI compatibility in
all versions of a given feature release series and its corresponding
super stable series.  For example, on a single platform, an MPI
application linked against Open MPI v1.7.2 shared libraries can be
updated to point to the shared libraries in any successive v1.7.x or
v1.8 release and still work properly (e.g., via the LD_LIBRARY_PATH
environment variable or other operating system mechanism).

* A bug that causes an ABI compatibility issue was discovered after
  v1.7.3 was released.  The bug only affects users who configure their
  Fortran compilers to use "large" INTEGERs by default, but still have
  "normal" ints for C (e.g., 8 byte Fortran INTEGERs and 4 byte C
  ints).  In this case, the Fortran MPI_STATUS_SIZE value was computed

  Fixing this issue breakes ABI *only in the sizeof(INTEGER) !=
  sizeof(int) case*.  However, since Open MPI provides ABI guarantees
  for the v1.7/v1.8 series, this bug is only fixed if Open MPI is
  configured with the --enable-abi-breaking-fortran-status-i8-fix
  flag, which, as its name implies, breaks ABI.  For example:

    shell$ ./configure --enable-abi-breaking-fortran-status-i8-fix \
             CC=icc F77=ifort FC=ifort CXX=icpc \
             FFLAGS=i8 FCFLAGS=-i8 ...

* A second bug was discovered after v1.7.3 was released that causes
  ABI to be broken for gfortran users who are using the "mpi" Fortran
  module.  In short, for versions of gfortran that do not support
  "ignore TKR" functionality (i.e., gfortran <=v4.8), Open MPI was
  providing interfaces for MPI subroutines with choice buffers (e.g.,
  MPI_Send) in the Fortran mpi module.  The MPI-3.0 specification
  expressly states not to do this.  To be consistent with MPI-3, Open
  MPI v1.7.4 therefore removed all MPI interfaces with choice buffers
  from the no-ignore-TKR version of the Fortran mpi module, even
  though this breaks ABI between v1.7.3 and v1.7.4.  Affected users
  should be able to recompile their MPI applications with v1.7.4 with
  no changes.

  Other Fortran compilers that provide "ignore TKR" functionality are
  not affected by this change.

Open MPI reserves the right to break ABI compatibility at new feature
release series.  For example, the same MPI application from above
(linked against Open MPI v1.7.2 shared libraries) will likely *not*
work with Open MPI v1.9 shared libraries.