README: update for the new version numbering scheme
Этот коммит содержится в:
Jeff Squyres
родитель
83eec67952
Коммит
85f0fff189
231
README
231
README
@ -1364,81 +1364,89 @@ Open MPI Version Numbers and Binary Compatibility
|
|||||||
Open MPI has two sets of version numbers that are likely of interest
|
Open MPI has two sets of version numbers that are likely of interest
|
||||||
to end users / system administrator:
|
to end users / system administrator:
|
||||||
|
|
||||||
* Software version number
|
* Software version number
|
||||||
* Shared library version numbers
|
* Shared library version numbers
|
||||||
|
|
||||||
Both are described below, followed by a discussion of application
|
Both are predicated on Open MPI's definition of "backwards
|
||||||
binary interface (ABI) compatibility implications.
|
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 Y is backwards compatible with Open MPI version X
|
||||||
|
(where Y>X) if users can:
|
||||||
|
|
||||||
|
* Compile an MPI/OSHMEM application with version X, mpirun/oshrun it
|
||||||
|
with version Y, and get the same user-observable behavior.
|
||||||
|
* Invoke ompi_info with the same CLI options in versions X and Y and
|
||||||
|
get the same user-observable behavior.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
Software Version Number
|
Software Version Number
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
The version number of Open MPI distribution tarballs are the union of
|
Official Open MPI releases use the common "A.B.C" version identifier
|
||||||
several different values: major, minor, release, and an optional
|
format. Each of the three numbers has a specific meaning:
|
||||||
quantifier.
|
|
||||||
|
|
||||||
* Major: The major number is the first integer in the version string
|
* 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
|
Changes in the major number typically indicate a significant
|
||||||
significant change in the code base and/or end-user
|
change in the code base and/or end-user functionality, and also
|
||||||
functionality. The major number is always included in the version
|
indicate a break from backwards compatibility. Specifically: Open
|
||||||
number.
|
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
|
* Minor: The minor number is the second integer in the version
|
||||||
string (e.g., v1.2.3). Changes in the minor number typically
|
string (e.g., v2.5.3). Changes in the minor number indicate a
|
||||||
indicate a incremental change in the code base and/or end-user
|
user-observable change in the code base and/or end-user
|
||||||
functionality. The minor number is always included in the version
|
functionality. Backwards compatibility will still be preserved
|
||||||
number. Starting with Open MPI v1.3.0, the minor release number
|
with prior releases that have the same major version number (e.g.,
|
||||||
took on additional significance (see this wiki page for more
|
v2.5.3 is backwards compatible with v2.3.1).
|
||||||
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
|
* Release: The release number is the third integer in the version
|
||||||
string (e.g., v1.2.3). Changes in the release number typically
|
string (e.g., v4.3.0). Changes in the release number typically
|
||||||
indicate a bug fix in the code base and/or end-user
|
indicate a bug fix in the code base and/or end-user functionality.
|
||||||
functionality. If the release number is 0, it is omitted from the
|
For example, if there is a release that only contains bug fixes
|
||||||
version number (e.g., v1.2 has a release number of 0).
|
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).
|
||||||
|
|
||||||
* Quantifier: Open MPI version numbers sometimes have an arbitrary
|
* Quantifier: Open MPI version numbers sometimes have an arbitrary
|
||||||
string affixed to the end of the version number. Common strings
|
string affixed to the end of the version number. Common strings
|
||||||
include:
|
include:
|
||||||
|
|
||||||
o aX: Indicates an alpha release. X is an integer indicating
|
o aX: Indicates an alpha release. X is an integer indicating the
|
||||||
the number of the alpha release (e.g., v1.2.3a5 indicates the
|
number of the alpha release (e.g., v1.10.3a5 indicates the 5th
|
||||||
5th alpha release of version 1.2.3).
|
alpha release of version 1.10.3).
|
||||||
o bX: Indicates a beta release. X is an integer indicating
|
o bX: Indicates a beta release. X is an integer indicating the
|
||||||
the number of the beta release (e.g., v1.2.3b3 indicates the 3rd
|
number of the beta release (e.g., v1.10.3b3 indicates the 3rd
|
||||||
beta release of version 1.2.3).
|
beta release of version 1.10.3).
|
||||||
o rcX: Indicates a release candidate. X is an integer
|
o rcX: Indicates a release candidate. X is an integer indicating
|
||||||
indicating the number of the release candidate (e.g., v1.2.3rc4
|
the number of the release candidate (e.g., v1.10.3rc4 indicates
|
||||||
indicates the 4th release candidate of version 1.2.3).
|
the 4th release candidate of version 1.10.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
|
Nightly development snapshot tarballs use a different version number
|
||||||
values (and optional quantifiers) are reported in Open MPI nightly
|
scheme; they contain three distinct values:
|
||||||
snapshot tarballs, the filenames of these snapshot tarballs follow a
|
|
||||||
slightly different convention.
|
|
||||||
|
|
||||||
Specifically, the snapshot tarball filename contains three distinct
|
|
||||||
values:
|
|
||||||
|
|
||||||
* Most recent Git tag name on the branch from which the tarball was
|
|
||||||
created.
|
|
||||||
|
|
||||||
|
* 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
|
* An integer indicating how many Git commits have occurred since
|
||||||
that Git tag.
|
that Git tag.
|
||||||
|
|
||||||
* The Git hash of the tip of the branch.
|
* The Git hash of the tip of the branch.
|
||||||
|
|
||||||
For example, a snapshot tarball filename of
|
For example, a snapshot tarball filename of
|
||||||
@ -1458,25 +1466,6 @@ human-recognizable ordering for snapshot tarballs.
|
|||||||
Shared Library Version Number
|
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 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
|
The GNU Libtool official documentation details how the versioning
|
||||||
scheme works. The quick version is that the shared library versions
|
scheme works. The quick version is that the shared library versions
|
||||||
are a triple of integers: (current,revision,age), or "c:r:a". This
|
are a triple of integers: (current,revision,age), or "c:r:a". This
|
||||||
@ -1519,14 +1508,14 @@ Here's how we apply those rules specifically to Open MPI:
|
|||||||
* libmca_common_*
|
* libmca_common_*
|
||||||
|
|
||||||
3. The following libraries use a slightly modified version of the
|
3. The following libraries use a slightly modified version of the
|
||||||
above rules: rules 4, 5, and 6 only apply to the official MPI
|
above rules: rules 4, 5, and 6 only apply to the official MPI and
|
||||||
interfaces (functions, global variables). The rationale for this
|
OpenSHMEM interfaces (functions, global variables). The rationale
|
||||||
decision is that the vast majority of our users only care about
|
for this decision is that the vast majority of our users only care
|
||||||
the official/public MPI interfaces; we therefore want the .so
|
about the official/public MPI/OSHMEM interfaces; we therefore want
|
||||||
version number to reflect only changes to the official MPI API.
|
the .so version number to reflect only changes to the official
|
||||||
Put simply: non-MPI API / internal changes to the
|
MPI/OSHMEM APIs. Put simply: non-MPI/OSHMEM API / internal
|
||||||
MPI-application-facing libraries are irrelevant to pure MPI
|
changes to the MPI-application-facing libraries are irrelevant to
|
||||||
applications.
|
pure MPI/OSHMEM applications.
|
||||||
|
|
||||||
* libmpi
|
* libmpi
|
||||||
* libmpi_mpifh
|
* libmpi_mpifh
|
||||||
@ -1534,81 +1523,9 @@ Here's how we apply those rules specifically to Open MPI:
|
|||||||
* libmpi_usempi_ignore_tkr
|
* libmpi_usempi_ignore_tkr
|
||||||
* libmpi_usempif08
|
* libmpi_usempif08
|
||||||
* libmpi_cxx
|
* libmpi_cxx
|
||||||
|
* libmpi_java
|
||||||
Application Binary Interface (ABI) Compatibility
|
* liboshmem
|
||||||
------------------------------------------------
|
* liboshmem_java
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
* The Fortran ABI was inadvertantly changed between Open MPI v1.8.1
|
|
||||||
and v1.8.2 for users who built Open MPI with gfortran >= v4.9. In
|
|
||||||
particular, if an MPI application was built against Open MPI <=
|
|
||||||
v1.8.2 with gfotran >= v4.9, and the MPI application used
|
|
||||||
MPI_SIZEOF, it will not be ABI compatible with Open MPI v1.8.3. The
|
|
||||||
ABI incompatibility problem was fixed in v1.8.4.
|
|
||||||
|
|
||||||
* The 1.8 series suffered an inadvertent break in ABI compatibility
|
|
||||||
prior to release 1.8.5 due to a test that rejected TCP connections
|
|
||||||
from processes compiled against another version. The test
|
|
||||||
incorrectly checked all three parts of the version number, thus
|
|
||||||
preventing a process compiled against 1.8.3 from connecting to one
|
|
||||||
compiled against 1.8.4. This was fixed in 1.8.5, so ABI will be
|
|
||||||
maintained from there forward.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
NOTE: The 1.8 series suffered an inadvertent break in ABI compatibility
|
|
||||||
prior to release 1.8.5 due to a test that rejected TCP connections from
|
|
||||||
processes compiled against another version. The test incorrectly checked
|
|
||||||
all three parts of the version number, thus preventing a process compiled
|
|
||||||
against 1.8.3 from connecting to one compiled against 1.8.4. This was fixed
|
|
||||||
in 1.8.5, so ABI will be maintained from there forward.
|
|
||||||
|
|
||||||
===========================================================================
|
===========================================================================
|
||||||
|
|
||||||
|
|||||||
Загрузка…
x
Ссылка в новой задаче
Block a user