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>

3 files changed, 124 insertions, 0 deletions

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.