Open MPI logo

Open MPI: Version Number Methodology

  |   Home   |   Support   |   FAQ   |  
The following text is taken directly from the Open MPI README file on the Subversion development trunk.



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

Open MPI's version numbers are the union of several different values:
major, minor, release, and an optional quantifier.

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

  * 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
    details):

    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
    include:

    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 rV or hgV: Indicates the Subversion / Mercurial repository
      number string that the release was made from (V is usually an
      integer for Subversion releases and usually a string for
      Mercurial releases). Although all official Open MPI releases are
      tied to a single, specific Subversion or Mercurial repository
      number (which can be obtained from the ompi_info command), only
      some releases have the Subversion / Mercurial repository number
      in the version number. Development snapshot tarballs, for
      example, have the Subversion repository included in the version
      to reflect that they are a development snapshot of an upcoming
      release (e.g., v1.2.3r1234 indicates a development snapshot of
      version 1.2.3 corresponding to Subversion repository number
      1234). 

    Quantifiers may be mixed together -- for example v1.2.3rc7r2345
    indicates a development snapshot of an upcoming 7th release
    candidate for version 1.2.3 corresponding to Subversion repository
    number 2345.

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 --
libopen-rte.so or libopen-pal.so were not versioned until v1.5).
Please see https://svn.open-mpi.org/trac/ompi/ticket/2092 for more
details.

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

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

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

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

  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.