diff options
author | Nikos Mavrogiannopoulos <nmav@redhat.com> | 2017-08-09 09:40:03 +0200 |
---|---|---|
committer | Nikos Mavrogiannopoulos <nmav@redhat.com> | 2017-08-09 16:25:33 +0200 |
commit | 05cb9df82c9dfea8f0508d532ab7c79b51efa960 (patch) | |
tree | f9a795d9c327dd397704d524a6b7c8a605283235 | |
parent | 80db34b6191f2c76a605e216798d96767571efc1 (diff) | |
download | gnutls-05cb9df82c9dfea8f0508d532ab7c79b51efa960.tar.gz |
CONTRIBUTING.md: added section on symbol versioning
Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>
-rw-r--r-- | CONTRIBUTING.md | 45 | ||||
-rw-r--r-- | m4/hooks.m4 | 3 |
2 files changed, 48 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3bf37b354..b423ad5cb3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -174,6 +174,51 @@ The NDEBUG macro is not used in GnuTLS compilation, so the assert() macros are always active. +# Symbol and library versioning + + The library uses the libtool versioning system, which in turn +results to a soname bump on incompatible changes. That is described +in [hooks.m4](m4/hooks.m4). Despite its complexity that system is +only sufficient to distinguish between versions of the library that +have broke ABI (i.e., soname bump occurred). + +Today however, soname versioning isn't sufficient. Symbol versioning +as provided by [libgnutls.map](lib/libgnutls.map) have several +advantages. + * they allow for symbol clashing between different gnutls library + versions being in the same address space. + * they allow installers to detect the library version used for + an application utilizing a specific symbol + * the allow introducing multiple versions of a symbol a la libc, + keeping the semantics of old functions while introducing new. + +As such for every symbol introduced on a particular version, we +create an entry in libgnutls.map based on the version and containing +the new symbols. For example, if in version 3.6.3 we introduce symbol +```gnutls_xyz```, the entry would be: + +GNUTLS_3_6_2 { + global: + gnutls_xyz; +} GNUTLS_3_6_1; + +where ```GNUTLS_3_6_1``` is the last version that symbols were introduced, +and indicates a dependency of 3.6.2 to symbols of 3.6.1. + +Note that when the soname version is bumped, i.e., the ABI is broken +all the previous symbol versions should be combined into a single. For +example on the 3.4.0 soname bump, all symbols were put under the +GNUTLS_3_4 version. + +Backporting new symbols to an old version which is soname compatible +is not allowed (can cause quite some problems). Backporting symbols +to an incompatible soname version is allowed, but must ensure that +the symbol version used for the backported symbol version is distinct from +the original library symbol version. E.g., 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. + + # Auto-generated files: Several parts of the documentation and the command line tools parameters files (.def) are auto-generated. Normally when introducing new functions, diff --git a/m4/hooks.m4 b/m4/hooks.m4 index c549ea16d2..9cb3e7d4e1 100644 --- a/m4/hooks.m4 +++ b/m4/hooks.m4 @@ -38,6 +38,9 @@ AC_DEFUN([LIBGNUTLS_HOOKS], # Library code modified: REVISION++ # Interfaces changed/added/removed: CURRENT++ REVISION=0 # Interfaces added: AGE++ + # + add new version symbol in libgnutls.map, see Symbol and library versioning + # in CONTRIBUTION.md for more info. + # # Interfaces removed: AGE=0 (+bump all symbol versions in .map) AC_SUBST(LT_CURRENT, 53) AC_SUBST(LT_REVISION, 0) |