[X2Go-Commits] [libx2goclient] 67/132: configure.ac: rework library versioning system.

[git-admin at x2go.org]

This is an automated email from the git hooks/post-receive script.

x2go pushed a commit to branch master
in repository libx2goclient.

commit 50cfbc8fa4d458decc4ccdd644a25364d79ec4fc
Author: Mihai Moldovan <ionic at ionic.de>
Date:   Sat May 29 05:57:17 2021 +0200

    configure.ac: rework library versioning system.
    
    Further investigation revealed that glib's library versioning system
    really isn't as good as I initially thought and, additionally, it was
    changed later on when switching from autotools to meson.
    
    The actual rationale has been given in the long comment already, but
    here comes a more in-depth explanation: libtool explicitly mentions that
    coupling package version and libtool version numbers is a mistake. The
    libtool version triplet should be updated according to specific rules,
    which do not match a steadily increasing package version number. For
    instance, if the actual interface didn't change at all, only the
    revision is to be increased, but within the glib scheme, current would
    also be increased regardless.
    
    A better inspiration for handling this is the libnl project, which
    correctly decouples both version structures and copies a bit of
    documentation from libtool explaining the updating rules.
    
    We'll follow the same path, which is a bit less convenient, since it
    requires to update the libtool version triplet manually, but more
    correct.
---
 configure.ac | 103 +++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 61 insertions(+), 42 deletions(-)

diff --git a/configure.ac b/configure.ac
index eae65e3..00c36a6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,51 +1,78 @@
 AC_PREREQ([2.64])
 
-# We'll mostly adopt the glib versioning scheme here, because it generally
-# makes sense.
-# In contrast to glib's scheme, we'll not differentiate between stable and
-# unstable versions, though.
+# Originally, I thought about using the old glib versioning scheme here, which
+# was used with the previous autotools setup.
+
+# However, while this scheme is convenient to use, because it updates the
+# libtool version triplet automatically based upon the package version, it's
+# not actually semantically correct, since the libtool version triplet update
+# rules are complicated and tied to the actual changes in the interface.
+
+# Thus, we'll go for a scheme in which package and libtool versions are
+# completely decoupled. There are other projects doing the same thing, and the
+# project that I'd like to highlight as an inspiration for this is libnl.
+
+# Regarding the libtool version triplet, the following information is copied
+# from libtool's documentation:
+#
+# libtool library versions are described by three integers:
+#   - current: The most recent interface number that this library implements.
+#   - revision: The implementation number of the current interface.
+#   - age: The difference between the newest and oldest interfaces that this
+#          library implements. In other words, the library implements all the
+#          interface numbers in the range from number current - age to
+#          current.
+# If two libraries have identical current and age numbers, then the dynamic
+# linker chooses the library with the greater revision number.
 #
-# Making releases:
-#   either
-#     libx2goclient_minor_version += 1;
-#     libx2goclient_micro_version  = 0;
-#     libx2goclient_interface_age += 1;
-#   or
-#     libx2goclient_micro_version += 1;
-#     libx2goclient_interface_age += 1;
-#     libx2goclient_binary_age += 1;
-# if any functions have been added, set libx2goclient_interface_age to 0.
-# if backwards compatibility has been broken,
-# set libx2goclient_binary_age _and_ libx2goclient_interface_age to 0, while
-# increasing libx2goclient_major_version and resetting
-# libx2goclient_minor_version and libx2goclient_micro_version to 0.
+# If either revision or age are omitted, they default to 0. Also note that age
+# must be less than or equal to the current interface number.
 #
-# remember to add a LIBX2GOCLIENT_VERSION_xxx macro every time the minor
-# version is bumped, as well as the LIBX2GOCLIENT_DEPRECATED_IN and
-# LIBX2GOCLIENT_AVAILABLE_IN macros for that version - see FIXMEversion.h for
-# further information.
+# Here are a set of rules to help you update your library version information:
+#   (1) Start with version information of '0:0:0' for each libtool library.
+#   (2) Update the version information only immediately before a public
+#       release of your software. More frequent updates are unnecessary, and
+#       only guarantee that the current interface number gets larger faster.
+#   (3) If the library source code has changed at all since the last update,
+#       then increment revision ('c:r:a' becomes 'c:r+1:a').
+#   (4) If any interfaces have been added, removed, or changed since the last
+#       update, increment current, and set revision to 0.
+#   (5) If any interfaces have been added since the last public release, then
+#       increment age.
+#   (6) If any interfaces have been removed or changed since the last public
+#       release, then set age to 0.
 #
-# in easier to understand terms:
+# The following explanation may help to understand the above rules a bit
+# better: consider that there are three possible kinds of reactions from users
+# of your library to changes in a shared library:
 #
-# <mclasen> on the stable branch, interface age == micro
-# [for libx2goclient] on minor releases, reset
-#                     interface age = micro version = 0
+#   (1) Programs using the previous version may use the new version as drop-in
+#       replacement, and programs using the new version can also work with the
+#       previous one. In other words, no recompiling nor relinking is needed.
+#       In this case, bump revision only, don’t touch current nor age.
+#   (2) Programs using the previous version may use the new version as drop-in
+#       replacement, but programs using the new version may use APIs not
+#       present in the previous one. In other words, a program linking against
+#       the new version may fail with "unresolved symbols" if linking against
+#       the old version at runtime: set revision to 0, bump current and age.
+#   (3) Programs may need to be changed, recompiled, and relinked in order to
+#       use the new version. Bump current, set revision and age to 0.
 
 m4_define([libx2goclient_major_version], [0])
 m4_define([libx2goclient_minor_version], [0])
 m4_define([libx2goclient_micro_version], [0])
-m4_define([libx2goclient_interface_age], [0])
-m4_define([libx2goclient_binary_age],
-          [m4_eval(100 * libx2goclient_minor_version + libx2goclient_micro_version)])
 m4_define([libx2goclient_version],
           [libx2goclient_major_version.libx2goclient_minor_version.libx2goclient_micro_version])
 
-# libtool version related macros
+# Libtool version related macros.
+# See above for an explanation of how to handle these values.
+# Note that we won't use libx2goclient_lt_release at all, since it makes any
+# new release binary incompatible to previous ones, but we'll keep it for
+# reference.
 m4_define([libx2goclient_lt_release], [libx2goclient_major_version.libx2goclient_minor_version])
-m4_define([libx2goclient_lt_current],
-          [m4_eval(100 * libx2goclient_minor_version + libx2goclient_micro_version - libx2goclient_interface_age)])
-m4_define([libx2goclient_lt_revision], [libx2goclient_interface_age])
-m4_define([libx2goclient_lt_age], [m4_eval(libx2goclient_binary_age - libx2goclient_interface_age)])
+m4_define([libx2goclient_lt_current], [0])
+m4_define([libx2goclient_lt_revision], [0])
+m4_define([libx2goclient_lt_age], [0])
 m4_define([libx2goclient_lt_current_minus_age],
           [m4_eval(libx2goclient_lt_current - libx2goclient_lt_age)])
 
@@ -74,16 +101,12 @@ AC_SUBST(ACLOCAL_AMFLAGS, "\${ACLOCAL_FLAGS}")
 LIBX2GOCLIENT_MAJOR_VERSION=libx2goclient_major_version
 LIBX2GOCLIENT_MINOR_VERSION=libx2goclient_minor_version
 LIBX2GOCLIENT_MICRO_VERSION=libx2goclient_micro_version
-LIBX2GOCLIENT_INTERFACE_AGE=libx2goclient_interface_age
-LIBX2GOCLIENT_BINARY_AGE=libx2goclient_binary_age
 LIBX2GOCLIENT_VERSION=libx2goclient_version
 
 AC_SUBST(LIBX2GOCLIENT_MAJOR_VERSION)
 AC_SUBST(LIBX2GOCLIENT_MINOR_VERSION)
 AC_SUBST(LIBX2GOCLIENT_MICRO_VERSION)
 AC_SUBST(LIBX2GOCLIENT_VERSION)
-AC_SUBST(LIBX2GOCLIENT_INTERFACE_AGE)
-AC_SUBST(LIBX2GOCLIENT_BINARY_AGE)
 
 AC_DEFINE(LIBX2GOCLIENT_MAJOR_VERSION, [libx2goclient_major_version],
 	  [Define to the major libx2goclient version])
@@ -91,10 +114,6 @@ AC_DEFINE(LIBX2GOCLIENT_MINOR_VERSION, [libx2goclient_minor_version],
 	  [Define to the minor libx2goclient version])
 AC_DEFINE(LIBX2GOCLIENT_MICRO_VERSION, [libx2goclient_micro_version],
 	  [Define to the micro libx2goclient version])
-AC_DEFINE(LIBX2GOCLIENT_INTERFACE_AGE, [libx2goclient_interface_age],
-	  [Define to the libx2goclient interface age])
-AC_DEFINE(LIBX2GOCLIENT_BINARY_AGE, [libx2goclient_binary_age],
-	  [Define to the libx2goclient binary age])
 
 # libtool versioning
 LT_RELEASE=libx2goclient_lt_release

--
Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/libx2goclient.git