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 <aconole@redhat.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>

11 files changed, 147 insertions, 6 deletions

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
 <https://www.python.org/dev/peps/pep-0008/>`__ 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 <libopenvswitch-abi>`
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 = \