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 predicated on Open MPI's definition of "backwards
compatibility."

NOTE: The version numbering conventions were changed with the release
      of v1.10.0.  Most notably, Open MPI no longer uses an "odd/even"
      release schedule to indicate feature development vs. stable
      releases.  See the README in releases prior to v1.10.0 for more
      information (e.g.,
      https://github.com/open-mpi/ompi-release/blob/v1.8/README#L1392-L1475).

Backwards Compatibility
-----------------------

Open MPI version vY is backwards compatible with Open MPI version vX
(where Y>X) if users can:

  * Users can compile a correct MPI / OSHMEM program with vX
  * Run it with the same CLI options and MCA parameters using vX or vY
  * The job executes correctly

Note that this definition encompasses several things:

  * Application Binary Interface (ABI)
  * MPI / OSHMEM run time system
  * mpirun / oshrun command line options
  * MCA parameter names / values / meanings

However, this definition only applies when the same version of Open
MPI is used with all instances of the runtime and MPI / OSHMEM
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.

Software Version Number
-----------------------

Official Open MPI releases use the common "A.B.C" version identifier
format.  Each of the three numbers has a specific meaning:

  * 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 backwards compatibility.  Specifically: Open
    MPI releases with different major version numbers are not
    backwards compatibile with each other.

    CAVEAT: This rule does not extend to versions prior to v1.10.0.
            Specifically: v1.10.x is not guaranteed to be backwards
            compatible with other v1.x releases.

  * 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.  Backwards
    compatibility will still be preserved with prior releases that
    have the same major version number (e.g., v2.5.3 is backwards
    compatible with v2.3.1).

  * 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).

The "A.B.C" version number may optionally be followed by a Quantifier:

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

    o aX: 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).
    o bX: 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).
    o rcX: 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).

Nightly development snapshot tarballs use a different version number
scheme; they contain three distinct values:

   * The most recent Git tag name on the branch from which the tarball
     was created.
   * 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
-----------------------------

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

 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
    https://svn.open-mpi.org/trac/ompi/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 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/OSHMEM interfaces; we therefore want
    the .so version number to reflect only changes to the official
    MPI/OSHMEM APIs.  Put simply: non-MPI/OSHMEM API / internal
    changes to the MPI-application-facing libraries are irrelevant to
    pure MPI/OSHMEM applications.

    * libmpi
    * libmpi_mpifh
    * libmpi_usempi_tkr
    * libmpi_usempi_ignore_tkr
    * libmpi_usempif08
    * libmpi_cxx
    * libmpi_java
    * liboshmem
    * liboshmem_java