From cb991590239e1709f20ce3fc992a7b2f8cda5dc0 Mon Sep 17 00:00:00 2001 From: Aaron Conole Date: Mon, 16 Jan 2017 14:06:27 -0500 Subject: [PATCH] libX: add new release / version info tags This commit uses the $PACKAGE_VERSION automake variable to construct a release and version info combination which sets the library name to be: libfoo-$(OVS_MAJOR_VERSION).so.$(OVS_MINOR_VERSION).0.$(OVS_MICRO_VERSION) where formerly, it was always: libfoo.so.1.0.0 This allows releases of Open vSwitch libraries to reflect which specific versions they came with, and sets up a psuedo ABI-versioning scheme. In this fashion, future releases of Open vSwitch could be installed alongside older releases, allowing 3rd party utilities linked against previous versions to continue to function. ex: $ ldd /path/to/utility linux-vdso.so.1 (0x00007ffe92cf6000) libopenvswitch-2.so.6 => /lib64/libopenvswitch-2.so.6 (0x00007f733b7a3000) libssl.so.10 => /lib64/libssl.so.10 (0x00007f733b530000) ... Note the library name and version information. Signed-off-by: Aaron Conole Signed-off-by: Ben Pfaff --- Documentation/automake.mk | 1 + .../internals/contributing/coding-style.rst | 6 + .../internals/contributing/index.rst | 1 + .../contributing/libopenvswitch-abi.rst | 117 ++++++++++++++++++ configure.ac | 1 + lib/automake.mk | 4 +- m4/openvswitch.m4 | 15 +++ ofproto/automake.mk | 2 +- ovn/lib/automake.mk | 2 +- ovsdb/automake.mk | 2 +- vtep/automake.mk | 2 +- 11 files changed, 147 insertions(+), 6 deletions(-) create mode 100644 Documentation/internals/contributing/libopenvswitch-abi.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 9dda5430d..25c14be57 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -83,6 +83,7 @@ EXTRA_DIST += \ Documentation/internals/contributing/coding-style.rst \ Documentation/internals/contributing/coding-style-windows.rst \ Documentation/internals/contributing/documentation-style.rst \ + Documentation/internals/contributing/libopenvswitch-abi.rst \ Documentation/internals/contributing/submitting-patches.rst \ Documentation/requirements.txt diff --git a/Documentation/internals/contributing/coding-style.rst b/Documentation/internals/contributing/coding-style.rst index e62f5e343..4694b2363 100644 --- a/Documentation/internals/contributing/coding-style.rst +++ b/Documentation/internals/contributing/coding-style.rst @@ -640,3 +640,9 @@ Python When introducing new Python code, try to follow Python's `PEP 8 `__ style. Consider running the ``pep8`` or ``flake8`` tool against your code to find issues. + +Libraries +--------- + +When introducing a new library, follow +:doc:`Open vSwitch Library ABI guide ` diff --git a/Documentation/internals/contributing/index.rst b/Documentation/internals/contributing/index.rst index 2cbe62562..4b6a9899d 100644 --- a/Documentation/internals/contributing/index.rst +++ b/Documentation/internals/contributing/index.rst @@ -34,3 +34,4 @@ The below guides provide information on contributing to Open vSwitch itself. coding-style coding-style-windows documentation-style + libopenvswitch-abi diff --git a/Documentation/internals/contributing/libopenvswitch-abi.rst b/Documentation/internals/contributing/libopenvswitch-abi.rst new file mode 100644 index 000000000..845d90898 --- /dev/null +++ b/Documentation/internals/contributing/libopenvswitch-abi.rst @@ -0,0 +1,117 @@ +.. + Copyright (c) 2017 Red Hat, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +=================================== +Open vSwitch Library ABI Updates +=================================== + +This file describes the manner in which the Open vSwitch shared library +manages different ABI and API revisions. This document aims to describe +the background, goals, and concrete mechanisms used to export code-space +functionality so that it may be shared between multiple applications. + +.. _definitions: + +Definitions +----------- + +.. csv-table:: Definitions for terms appearing in this document + :header: "Term", "Definition" + + "ABI", "Abbreviation of Application Binary Interface" + "API", "Abbreviation of Application Programming Interface" + "Application Binary Interface", "The low-level runtime interface exposed + by an object file." + "Application Programming Interface", "The source-code interface descriptions + intended for use in multiple translation units when compiling." + "Code library", "A collection of function implementations and definitions + intended to be exported and called through a well-defined interface." + "Shared Library", "A code library which is imported at run time." + +.. _overview: + +Overview +---------- + +C and C++ applications often use 'external' functionality, such as printing +specialized data types or parsing messages, which has been exported for common +use. There are many possible ways for applications to call such external +functionality, for instance by including an appropriate inline definition which +the compiler can emit as code in each function it appears. One such way of +exporting and importing such functionality is through the use of a library +of code. + +When a compiler builds object code from source files to produce object code, +the results are binary data arranged with specific calling conventions, +alignments, and order suitable for a run-time environment or linker. This +result defines a specific ABI. + +As library of code develops and its exported interfaces change over time, the +resulting ABI may change as well. Therefore, care must be taken to ensure the +changes made to libraries of code are effectively communicated to applications +which use them. This includes informing the applications when incompatible +changes are made. + +The Open vSwitch project exports much of its functionality through multiple +such libraries of code. These libraries are intended for multiple applications +to import and use. As the Open vSwitch project continues to evolve and change, +its exported code will evolve as well. To ensure that applications linking to +these libraries are aware of these changes, Open vSwitch employs libtool +version stamps. + +.. _policies: + +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. + +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. + +Coding +------- + +At build time, if building shared libraries by passing the `--enable-shared` +arguments to `./configure`, version information is extracted from +the ``$PACKAGE_VERSION`` automake variable and formatted into the appropriate +arguments. These get exported for use in Makefiles as ``$OVS_LTINFO``, and +passed to each exported library along with other ``LDFLAGS``. + +Therefore, when adding a new library to the build system, these version flags +should be included with the ``$LDFLAGS`` variable. Nothing else needs to be +done. + +Changing an exported function definition (from a file in, for instance +`lib/*.h`) is only permitted from minor release to minor release. Likewise +changes to library data structures should only occur from minor release to +minor release. diff --git a/configure.ac b/configure.ac index a9ae2a11a..7c729ef49 100644 --- a/configure.ac +++ b/configure.ac @@ -131,6 +131,7 @@ OVS_CHECK_ATOMIC_ALWAYS_LOCK_FREE(8) OVS_CHECK_POSIX_AIO OVS_CHECK_PTHREAD_SET_NAME OVS_CHECK_LINUX_HOST +OVS_LIBTOOL_VERSIONS AX_FUNC_POSIX_MEMALIGN OVS_CHECK_INCLUDE_NEXT([stdio.h string.h]) diff --git a/lib/automake.mk b/lib/automake.mk index 88344a310..b03dd2d19 100644 --- a/lib/automake.mk +++ b/lib/automake.mk @@ -15,7 +15,7 @@ lib_libopenvswitch_la_LIBADD += ${PTHREAD_LIBS} endif lib_libopenvswitch_la_LDFLAGS = \ - -version-info $(LT_CURRENT):$(LT_REVISION):$(LT_AGE) \ + $(OVS_LTINFO) \ -Wl,--version-script=$(top_builddir)/lib/libopenvswitch.sym \ $(AM_LDFLAGS) @@ -328,7 +328,7 @@ CLEANFILES += $(nodist_lib_libopenvswitch_la_SOURCES) lib_LTLIBRARIES += lib/libsflow.la lib_libsflow_la_LDFLAGS = \ - -version-info $(LT_CURRENT):$(LT_REVISION):$(LT_AGE) \ + $(OVS_LTINFO) \ -Wl,--version-script=$(top_builddir)/lib/libsflow.sym \ $(AM_LDFLAGS) lib_libsflow_la_SOURCES = \ diff --git a/m4/openvswitch.m4 b/m4/openvswitch.m4 index 6515ed7bb..07c61911a 100644 --- a/m4/openvswitch.m4 +++ b/m4/openvswitch.m4 @@ -601,3 +601,18 @@ AC_DEFUN([OVS_CHECK_PRAGMA_MESSAGE], [AC_DEFINE(HAVE_PRAGMA_MESSAGE,1,[Define if compiler supports #pragma message directive])]) ]) + +dnl OVS_LIBTOOL_VERSIONS sets the major, minor, micro version information for +dnl OVS_LTINFO variable. This variable locks libtool information for shared +dnl objects, allowing multiple versions with different ABIs to coexist. +AC_DEFUN([OVS_LIBTOOL_VERSIONS], + [AC_MSG_CHECKING(linker output version information) + 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_LTINFO="$OVS_LT_RELINFO $OVS_LT_VERINFO" + AC_MSG_RESULT([libX-$OVS_MAJOR.so.$OVS_MINOR.0.$OVS_MICRO)]) + AC_SUBST(OVS_LTINFO) + ]) diff --git a/ofproto/automake.mk b/ofproto/automake.mk index 1c111945b..aa94e6d86 100644 --- a/ofproto/automake.mk +++ b/ofproto/automake.mk @@ -7,7 +7,7 @@ lib_LTLIBRARIES += ofproto/libofproto.la ofproto_libofproto_la_LDFLAGS = \ - -version-info $(LT_CURRENT):$(LT_REVISION):$(LT_AGE) \ + $(OVS_LTINFO) \ -Wl,--version-script=$(top_builddir)/ofproto/libofproto.sym \ $(AM_LDFLAGS) ofproto_libofproto_la_SOURCES = \ diff --git a/ovn/lib/automake.mk b/ovn/lib/automake.mk index 7f26de2a5..b86237eb7 100644 --- a/ovn/lib/automake.mk +++ b/ovn/lib/automake.mk @@ -1,6 +1,6 @@ lib_LTLIBRARIES += ovn/lib/libovn.la ovn_lib_libovn_la_LDFLAGS = \ - -version-info $(LT_CURRENT):$(LT_REVISION):$(LT_AGE) \ + $(OVS_LTINFO) \ -Wl,--version-script=$(top_builddir)/ovn/lib/libovn.sym \ $(AM_LDFLAGS) ovn_lib_libovn_la_SOURCES = \ diff --git a/ovsdb/automake.mk b/ovsdb/automake.mk index 099ed3ceb..81695f1a0 100644 --- a/ovsdb/automake.mk +++ b/ovsdb/automake.mk @@ -1,7 +1,7 @@ # libovsdb lib_LTLIBRARIES += ovsdb/libovsdb.la ovsdb_libovsdb_la_LDFLAGS = \ - -version-info $(LT_CURRENT):$(LT_REVISION):$(LT_AGE) \ + $(OVS_LTINFO) \ -Wl,--version-script=$(top_builddir)/ovsdb/libovsdb.sym \ $(AM_LDFLAGS) ovsdb_libovsdb_la_SOURCES = \ diff --git a/vtep/automake.mk b/vtep/automake.mk index 4e284d382..02024eb7b 100644 --- a/vtep/automake.mk +++ b/vtep/automake.mk @@ -14,7 +14,7 @@ vtep/vtep-idl.ovsidl: $(VTEP_IDL_FILES) # libvtep lib_LTLIBRARIES += vtep/libvtep.la vtep_libvtep_la_LDFLAGS = \ - -version-info $(LT_CURRENT):$(LT_REVISION):$(LT_AGE) \ + $(OVS_LTINFO) \ -Wl,--version-script=$(top_builddir)/vtep/libvtep.sym \ $(AM_LDFLAGS) nodist_vtep_libvtep_la_SOURCES = \ -- 2.39.2