[Telepathy] Libtool library versioning
sjoerd at luon.net
Sat Aug 11 05:28:16 PDT 2007
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 .
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
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
When doing a new release of your library:
If the source code was changed, but there were no interface changes:
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
+ 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.
Chemist who falls in acid is absorbed in work.
More information about the Telepathy