[Telepathy] Libtool library versioning

[Sjoerd Simons]

Hi!

  As one of telepathy's friendly neighbourhood Debian maintainers i've noticed
  some errors in the versioning of various telepathy related libraries. This is
  probably due to a lack of knowledge in that area.

  Section 6 of the libtool manual has some good information about how it all
  works, especially 6.3 is a must-read [0].

  A short overview:

  libtool's -version-info argument takes CURRENT:REVISION:AGE. Where CURRENT
  is the current version of the interface. AGE indicate the number of older
  interfaces it's implementing and REVISION the revision of the current
  interface.

  So -version-info 8:2:3 says the current release is interface version 8,
  compatible with interface versions 5, 6 and 7 and that it's the third release
  with interface version 8. Resulting in the library name
  <my_library>.so.5.3.2, which is <my_library>.so.(CURRENT - AGE).AGE.REVISION

  The (CURRENT - AGE) number is what people usually mean when their talking
  about bumping the soname (and the definition i'll use in the rest of this
  mail). As in practise the linker will use the latest version of a library
  with a correct (CURRENT - AGE) value even though it might not be recent
  enough.

  When doing a new release of your library:
    If the source code was changed, but there were no interface changes:
      Increment REVISION.
    If there was a compatible interface change:
      Increment CURRENT and AGE. Set REVISION to 0
    If there was an incompatible interface change:
      Increment CURRENT. Set AGE and REVISION to 0

  Incompatible changes are changes to the size of public structs, removing
  public functions, adding arguments to public functions etc etc. About the
  only compatible change that one can do is adding new functions.

  In practise there is some pain for binary distributions involved when a
  library bumps it's soname. As all apps using the library will need to be
  recompiled (and maybe fixed) for them to be able to use the new version of
  the library (and for the distribution to be able to get rid of the old
  version). So please limit incompatible changes to libraries. Failing to bump
  a soname when needed results in even bigger issues though (like very nasty
  bugs turning up suddenly), so please err on the side of caution... Bumping
  sonames is not something to be ashamed of!

  Some good ways of avoiding unnecessary soname bumps:
    + Deprecate functions instead of removing them (especially when renaming).
      Using the gcc deprecated attribute helps here (G_GNUC_DEPRECATED for glib
      users)
    + Try to use private/opaque structures where possible. (For glib users,
      only put things in the object instance/class struct when really needed)

  Hopefully this helps to prevent library versioning errors in the future :)..
  Ofcourse always feel free to ask questions.

  Sjoerd
0: http://www.gnu.org/software/libtool/manual.html#Versioning
-- 
Chemist who falls in acid is absorbed in work.