Update and simplify SO versioning policy (#1498)

* Update and simplify SO versioning policy

This change retires the "libtool" versioning scheme and adopts a
policy of appending the ``MAJOR.MINOR.PATCH`` software release name to
the SONAME to form the real name of the shared library.

The SOVERSION is specified via the ``OPENEXR_LIB_SOVERSION`` setting
in ``CMakeLists.txt`` and is the single number that increments
whenever, and only when, the ABI changes in non-backwards-compatible
ways. In practice, this corresponds to major and minor releases.

The resulting real shared library file names look like, for example,
``libOpenEXR.so.31.3.2.0``, where ``libOpenEXR.so.31`` is the SONAME
and ``.3.2.0`` identifies the corresponding software release.

This naming scheme helps reinforce the correspondence between the
shared library's real file name and the software release it
corresponds to, moreso than would be indicated by a single increasing
number.

By OpenEXR project policy and discussion of the technical steering
committee, the additional versioning information in the libtool
versioning scheme is too confusing and error-prone to follow, without
offering additional practical benefit.

Documentation is in ``CMakeLists.txt`` and in ``docs/install.rst``.

Signed-off-by: Cary Phillips <[email protected]>

* remove reference to libtool

Signed-off-by: Cary Phillips <[email protected]>

---------

Signed-off-by: Cary Phillips <[email protected]>

CMakeLists.txt

@@ -34,28 +34,17 @@ set(OPENEXR_VERSION_RELEASE_TYPE "-dev" CACHE STRING "Extra version tag string f
 set(OPENEXR_VERSION ${OpenEXR_VERSION})
 set(OPENEXR_VERSION_API "${OpenEXR_VERSION_MAJOR}_${OpenEXR_VERSION_MINOR}")
 
-# Library/shared-object version using libtool versioning policy.
-# See https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
+# The SOVERSION (i.e. numerical component of SONAME) tracks the ABI
+# version. Increment this number whenever, and only when, the ABI changes in
+# non-backwards-compatible ways.
 #
-# Library API version (CMake's library VERSION attribute) is of the
-# form CURRENT.REVISION.AGE; the CMake SOVERSION attribute corresponds
-# to just CURRENT. These produce a .so and a symlink symlink, e.g.:
-# libOpenEXR-3_1.so.29 -> libOpenEXR-3_1.so.29.0.0
-#                    ^                       ^ ^ ^
-#                    |                       | | |
-#                    CURRENT                 | | AGE
-#                                            | REVISION 
-#                                            CURRENT
-# When updating:
-#   1. no API change: CURRENT.REVISION+1.AGE
-#   2. API added:     CURRENT+1.0.AGE+1
-#   3. API changed:   CURRENT+1.0.0
-#
-set(OPENEXR_LIBTOOL_CURRENT 29)
-set(OPENEXR_LIBTOOL_REVISION 0)
-set(OPENEXR_LIBTOOL_AGE 0)
-set(OPENEXR_LIB_VERSION "${OPENEXR_LIBTOOL_CURRENT}.${OPENEXR_LIBTOOL_REVISION}.${OPENEXR_LIBTOOL_AGE}")
-set(OPENEXR_LIB_SOVERSION ${OPENEXR_LIBTOOL_CURRENT})
+# The OpenEXR project policy is to append the library version 
+# "major.minor.patch" to the SONAME to form the real shared library name.  
+# For example, in "libOpenEXR.so.31.3.2.0", "libOpenEXR.so.31" is the SONAME
+# and ".3.2.0" identifies the corresponding library release.
+
+set(OPENEXR_LIB_SOVERSION 31)
+set(OPENEXR_LIB_VERSION "${OPENEXR_LIB_SOVERSION}.${OPENEXR_VERSION}") # e.g. "31.3.2.0"
 
 option(OPENEXR_INSTALL "Install OpenEXR libraries" ON)
 option(OPENEXR_INSTALL_TOOLS "Install OpenEXR tools" ON)
@@ -66,7 +55,6 @@ endif()
 include(cmake/LibraryDefine.cmake)
 include(cmake/OpenEXRSetup.cmake)
 add_subdirectory(cmake)
-
 message(STATUS "Configure ${OPENEXR_PACKAGE_NAME}, library API version: ${OPENEXR_LIB_VERSION}")
 
 # Hint: This can be set to enable custom find_package

docs/install.rst

@@ -130,33 +130,38 @@ can specify a local install directory to cmake via the
 Library Names
 -------------
 
-By default the installed libraries follow a pattern for how they are
-named. This is done to enable multiple versions of the library to be
-installed and targeted by different builds depending on the needs of
-the project. A simple example of this would be to have different
-versions of the library installed to allow for applications targeting
-different VFX Platform years to co-exist.
+By default, libraries are installed with the following names/symlinks:
 
-If you are building dynamic libraries, once you have configured, built,
-and installed the libraries, you should see the following pattern of
-symlinks and files in the install lib folder:
+.. code-block::
+
+    libOpenEXR.so -> libOpenEXR.so.31
+    libOpenEXR.so.$SOVERSION -> libOpenEXR.so.$SOVERSION.$RELEASE
+    libOpenEXR.so.$SOVERSION.$RELEASE (the shared object file)
+
+The ``SOVERSION`` number identifies the ABI version. Each OpenEXR
+release that changes the ABI in backwards-incompatible ways increases
+this number. By policy, this changes only for major and minor
+releases, never for patch releases. ``RELEASE`` is the
+``MAJOR.MINOR.PATCH`` release name. For example, the resulting shared
+library filename is ``libOpenEXR.so.31.3.2.0`` for OpenEXR release
+v3.2.0. This naming scheme reinforces the correspondence between the
+real filename of the ``.so`` and the release it corresponds to.
+
+Library Suffix
+~~~~~~~~~~~~~~
+
+The ``OPENEXR_LIB_SUFFIX`` CMake option designates a suffix for the
+library and appears between the library base name and the
+``.so``. This defaults to encode the major and minor version, as in
+``-3_1``:
 
 .. code-block::
 
     libOpenEXR.so -> libOpenEXR-3_1.so
     libOpenEXR-3_1.so -> libOpenEXR-3_1.so.30
-    libOpenEXR-3_1.so.30 -> libOpenEXR-3_1.so.30.3.0
-    libOpenEXR-3_1.so.30.3.0 (the shared object file)
+    libOpenEXR-3_1.so.30 -> libOpenEXR-3_1.so.30.3.2.0
+    libOpenEXR-3_1.so.30.3.2.0 (the shared object file)
     
-The ``-3_1`` suffix encodes the major and minor version, which can be
-configured via the ``OPENEXR_LIB_SUFFIX`` CMake setting. The ``30``
-corresponds to the so version, or in ``libtool`` terminology the
-``current`` shared object version; the `3` denotes the ``libtool``
-``revision``, and the ``0`` denotes the ``libtool`` ``age``. See the
-`libtool
-<https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html#Updating-version-info>`_
-documentation for more details.
-
 Imath Dependency
 ----------------