[gnutls-devel] symbol and library versioning

[Daniel P. Berrange]

On Thu, Aug 10, 2017 at 10:31:28AM +0200, Nikos Mavrogiannopoulos wrote:
> Hi,
>  With mind in the upcoming 3.6.0 release I tried to codify/clarify the
> library and symbol versioning rules that are considered best practice
> today.
> 
> The output is at:
> https://gitlab.com/gnutls/gnutls/blob/master/CONTRIBUTING.md#symbol-and-library-versioning
> 
> My take-away from it, is that the complexity of libtool rules is
> unnecessary and in fact all that is being used from it is the major
> soname version (thus the minor and patch versions set via libtool are
> being used by no software).

Yes, libtool versioning is not really useful, especially for a library
that intends to maintain API/ABI compat long term / forever.

> The versioning that matters is via the linker script, which is then
> used by packaging software like rpm (I guess possibly dpkg as well),
> to detect proper dependencies.
> 
> Did I miss something in that? Are there are best practices I missed,
> or any issues in the rules I set above?

I believe your backporting rule is a bad idea.

  "if symbol gnutls_xyz with version GNUTLS_3_6_3 is backported on 
   gnutls 3.3.15, it should use version GNUTLS_3_3_15."

This creates ABI breakage when you upgrade gnutls in the distro. eg

An application which links to your gnutls 3.3.15 version and uses
symbol gnutls_xyz will get a embedded symbol reference of
gnutls_xyz at GNUTLS_3_3_15.   When you then update to gnutls 3.6.3 in
the distro, the linker will be unable to resolve gnutls_xyz at GNUTLS_3_3_15,
because the library will now be exporting gnutls_xyz at GNUTLS_3_6_3
instead.

There's a few other options for backporting, but they are all awful
in their own ways:

  https://www.berrange.com/posts/2011/01/13/versioning-in-the-libvirt-library/

so for libvirt we simply refuse to ever backport public APIs to older
versions. Backports are for bug fixes only, never features.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|