Update NEWS and README to describe the ABI changes and our version
numbering schemes. This commit was SVN r22703.
Этот коммит содержится в:
Jeff Squyres
родитель
99ee62771d
Коммит
3d04940921
5
NEWS
5
NEWS
@ -8,7 +8,7 @@ Copyright (c) 2004-2008 High Performance Computing Center Stuttgart,
|
||||
University of Stuttgart. All rights reserved.
|
||||
Copyright (c) 2004-2006 The Regents of the University of California.
|
||||
All rights reserved.
|
||||
Copyright (c) 2006-2009 Cisco Systems, Inc. All rights reserved.
|
||||
Copyright (c) 2006-2010 Cisco Systems, Inc. All rights reserved.
|
||||
Copyright (c) 2006 Voltaire, Inc. All rights reserved.
|
||||
Copyright (c) 2006 Sun Microsystems, Inc. All rights reserved.
|
||||
Use is subject to license terms.
|
||||
@ -32,6 +32,9 @@ Trunk (not on release branches yet)
|
||||
1.5
|
||||
---
|
||||
|
||||
- Updated shared library versioning scheme and linking style of MPI
|
||||
applications. ABI has been broken from the v1.4 series; see the
|
||||
README file for more details.
|
||||
- Added "knem" support (direct process-to-process copying for shared
|
||||
memory message passing). See http://runtime.bordeaux.inria.fr/knem/
|
||||
and the README file for more details.
|
||||
|
||||
185
README
185
README
@ -950,6 +950,191 @@ Open MPI executables.
|
||||
|
||||
===========================================================================
|
||||
|
||||
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 meaningless shared library version
|
||||
numbers.
|
||||
|
||||
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_f77
|
||||
* libmpi_f90
|
||||
* 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.
|
||||
|
||||
NOTE: Prior to v1.3.2, subtle and strange failures are almost
|
||||
guaranteed to occur if applications were compiled and linked
|
||||
against shared libraries from one version of Open MPI and then
|
||||
run with another. The Open MPI team strongly discourages making
|
||||
any ABI assumptions before v1.3.2.
|
||||
|
||||
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.3.2 shared libraries can be
|
||||
updated to point to the shared libraries in any successive v1.3.x or
|
||||
v1.4 release and still work properly (e.g., via the LD_LIBRARY_PATH
|
||||
environment variable or other operating system mechanism).
|
||||
|
||||
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.3.2 shared libraries) will *not* work with
|
||||
Open MPI v1.5 shared libraries.
|
||||
|
||||
===========================================================================
|
||||
|
||||
Checking Your Open MPI Installation
|
||||
-----------------------------------
|
||||
|
||||
|
||||
Загрузка…
x
Ссылка в новой задаче
Block a user