| Message ID | 20170517233724.18489-1-joe@ovn.org |
|---|---|
| State | Accepted |
| Headers | show |
Hi Joe, Joe Stringer <joe@ovn.org> writes: > The current intent for Open vSwitch is to maintain libopenvswitch ABI > stability for minor versions, for example each release within the 2.7.z > series. According to the following documentation, no changes to exported > headers should be made. > > http://docs.openvswitch.org/en/latest/internals/contributing/libopenvswitch-abi/ > > However, it is occasionally necessary to make changes to > {include/openvswitch,lib}/*.h headers to fix issues within a given > release series. The current libtool tagging mechanism in the build > system does not allow for this without creating a conflict between the > libtool 'current' version and the next minor release of OVS. > > This patch modifies libopenvswitch build to include the MAJOR.MINOR > release version in the libX name, and include the libtool CURRENT and > OVS MICRO release in the libtool versioning tags to indicate library > stability. The resulting format is "libfoo-X.Y.so.CURRENT.0.Z" for OVS > release "X.Y.Z". > > Developers should still attempt to avoid introducing ABI-breaking changes > within a particular OVS-X.Y release series, but if this is not possible > this patch introduced a mechanism to allow an ABI-breaking fix to be > introduced. In such a case, developers may update the libtool CURRENT > version to indicate this breakage to library users. > > Signed-off-by: Joe Stringer <joe@ovn.org> > Acked-by: Ben Pfaff <blp@ovn.org> > --- Acked-by: Aaron Conole <aconole@redhat.com>
On 18 May 2017 at 09:11, Aaron Conole <aconole@redhat.com> wrote: > Hi Joe, > > Joe Stringer <joe@ovn.org> writes: > >> The current intent for Open vSwitch is to maintain libopenvswitch ABI >> stability for minor versions, for example each release within the 2.7.z >> series. According to the following documentation, no changes to exported >> headers should be made. >> >> http://docs.openvswitch.org/en/latest/internals/contributing/libopenvswitch-abi/ >> >> However, it is occasionally necessary to make changes to >> {include/openvswitch,lib}/*.h headers to fix issues within a given >> release series. The current libtool tagging mechanism in the build >> system does not allow for this without creating a conflict between the >> libtool 'current' version and the next minor release of OVS. >> >> This patch modifies libopenvswitch build to include the MAJOR.MINOR >> release version in the libX name, and include the libtool CURRENT and >> OVS MICRO release in the libtool versioning tags to indicate library >> stability. The resulting format is "libfoo-X.Y.so.CURRENT.0.Z" for OVS >> release "X.Y.Z". >> >> Developers should still attempt to avoid introducing ABI-breaking changes >> within a particular OVS-X.Y release series, but if this is not possible >> this patch introduced a mechanism to allow an ABI-breaking fix to be >> introduced. In such a case, developers may update the libtool CURRENT >> version to indicate this breakage to library users. >> >> Signed-off-by: Joe Stringer <joe@ovn.org> >> Acked-by: Ben Pfaff <blp@ovn.org> >> --- > > Acked-by: Aaron Conole <aconole@redhat.com> I appreciate the review on this work Aaron, thanks! Applied to branch-2.7.
diff --git a/Documentation/internals/contributing/libopenvswitch-abi.rst b/Documentation/internals/contributing/libopenvswitch-abi.rst index 845d90898859..8fa24db964cd 100644 --- a/Documentation/internals/contributing/libopenvswitch-abi.rst +++ b/Documentation/internals/contributing/libopenvswitch-abi.rst @@ -87,16 +87,18 @@ ABI Policy ---------- Open vSwitch will export the ABI version at the time of release, such that the -library name will be the major version, and the rest of the release version -information will be conveyed with a libtool interface version. +library name will be the major.minor version, and the rest of the release +version information will be conveyed with a libtool interface version. The intent is for Open vSwitch to maintain an ABI stability for each minor revision only (so that Open vSwitch release 2.5 carries a guarantee for all -2.5.ZZ micro-releases). This means that any porting effort to stable branches -must take not to disrupt the existing ABI. Each new 'minor-level' release -bumps the libtool 'current' version, which informs the linker of a backwards -incompatible interface, signaling that libraries exposed by Open vSwitch 2.6 -will not maintain ABI stability with Open vSwitch 2.5. +2.5.ZZ micro-releases). This means that any porting effort to stable branches +must take not to disrupt the existing ABI. + +In the event that a bug must be fixed in a backwards-incompatible way, +developers must bump the libtool 'current' version to inform the linker of the +ABI breakage. This will signal that libraries exposed by the subsequent release +will not maintain ABI stability with the previous version. Coding ------- diff --git a/m4/openvswitch.m4 b/m4/openvswitch.m4 index 07c61911aac9..435f8923f7be 100644 --- a/m4/openvswitch.m4 +++ b/m4/openvswitch.m4 @@ -610,9 +610,9 @@ AC_DEFUN([OVS_LIBTOOL_VERSIONS], OVS_MAJOR=`echo "$PACKAGE_VERSION" | sed -e 's/[[.]].*//'` OVS_MINOR=`echo "$PACKAGE_VERSION" | sed -e "s/^$OVS_MAJOR//" -e 's/^.//' -e 's/[[.]].*//'` OVS_MICRO=`echo "$PACKAGE_VERSION" | sed -e "s/^$OVS_MAJOR.$OVS_MINOR//" -e 's/^.//' -e 's/[[^0-9]].*//'` - OVS_LT_RELINFO="-release $OVS_MAJOR" - OVS_LT_VERINFO="-version-info $OVS_MINOR:$OVS_MICRO" + OVS_LT_RELINFO="-release $OVS_MAJOR.$OVS_MINOR" + OVS_LT_VERINFO="-version-info $LT_CURRENT:$OVS_MICRO" OVS_LTINFO="$OVS_LT_RELINFO $OVS_LT_VERINFO" - AC_MSG_RESULT([libX-$OVS_MAJOR.so.$OVS_MINOR.0.$OVS_MICRO)]) + AC_MSG_RESULT([libX-$OVS_MAJOR.$OVS_MINOR.so.$LT_CURRENT.0.$OVS_MICRO)]) AC_SUBST(OVS_LTINFO) ])
The current intent for Open vSwitch is to maintain libopenvswitch ABI stability for minor versions, for example each release within the 2.7.z series. According to the following documentation, no changes to exported headers should be made. http://docs.openvswitch.org/en/latest/internals/contributing/libopenvswitch-abi/ However, it is occasionally necessary to make changes to {include/openvswitch,lib}/*.h headers to fix issues within a given release series. The current libtool tagging mechanism in the build system does not allow for this without creating a conflict between the libtool 'current' version and the next minor release of OVS. This patch modifies libopenvswitch build to include the MAJOR.MINOR release version in the libX name, and include the libtool CURRENT and OVS MICRO release in the libtool versioning tags to indicate library stability. The resulting format is "libfoo-X.Y.so.CURRENT.0.Z" for OVS release "X.Y.Z". Developers should still attempt to avoid introducing ABI-breaking changes within a particular OVS-X.Y release series, but if this is not possible this patch introduced a mechanism to allow an ABI-breaking fix to be introduced. In such a case, developers may update the libtool CURRENT version to indicate this breakage to library users. Signed-off-by: Joe Stringer <joe@ovn.org> Acked-by: Ben Pfaff <blp@ovn.org> --- .../internals/contributing/libopenvswitch-abi.rst | 16 +++++++++------- m4/openvswitch.m4 | 6 +++--- 2 files changed, 12 insertions(+), 10 deletions(-)