Re: .so versions

[Murray Cumming <murrayc murrayc com>]

On Thu, 2007-05-17 at 13:42 -0400, Behdad Esfahbod wrote:
> On Thu, 2007-05-17 at 18:26 +0100, Sergey Udaltsov wrote:
> > Could anyone please comment on the question of the shared library versions:
> > 
> > http://www.advogato.org/person/svu/diary.html?start=95
> 
> 
> Most modules I know use libtool versioning.  yes.
> 
> Here is the bits from Pango for example:
> 
> dnl The triplet 
> m4_define([pango_version_major], [1])
> m4_define([pango_version_minor], [17])
> m4_define([pango_version_micro], [0])
> m4_define([pango_version],
>           [pango_version_major.pango_version_minor.pango_version_micro])
> dnl The X.Y in -lpango-X.Y line. This is expected to stay 1.0 until Pango 2.
> m4_define([pango_api_version], [1.0])
> dnl Number of releases since we've added interfaces
> m4_define([pango_interface_age], [0])
> dnl Number of releases since we've broken binary compatibility.
> m4_define([pango_binary_age],
>           [m4_eval(100 * pango_version_minor + pango_version_micro)])
> dnl Module API version.  This should be stepped up when a change causes
> dnl older modules to not work with new pango.
> m4_define([pango_module_version], [1.6.0])
> 
> ...
> 
> dnl libtool versioning
> m4_define([lt_current], [m4_eval(100 * pango_version_minor + pango_version_micro - pango_interface_age)])
> m4_define([lt_revision], [pango_interface_age])
> m4_define([lt_age], [m4_eval(pango_binary_age - pango_interface_age)])
> VERSION_INFO="lt_current():lt_revision():lt_age()"
> 
> ...
> 
> LIBRARY_LIBTOOL_OPTIONS="-version-info $VERSION_INFO"
[snip]

Sorry for the late reply. I'm bringing this up again after a mistake was
apparently made in the --version-info for the latest cairomm release.

I find this very easy to get wrong, and I've never understood what
relation the resulting .so.x.y.z has to the --version-info that I
provided.

For instance, 
a --version-info of 1.0.0 will produce a .so.1.0.0
but a --version-info of 1.1.1 will produce a .so.0.1.1
and a --version-info of 2.1.1 will produce a .so.1.1.1
(Yes, these might not be sensible changes one after the other, in any 
situation.)

These numbers are obviously not a simple mapping. Whenever people talk
about .so version numbering and how they should change between versions,
I never know whether they are talking about the version in the library
filename, or the version in the configure.ac.

Furthermore, even when trying to do exactly the right thing by those
awkward --version-info rules, people still complain sometimes when the
wrong number is increased, causing a relink to be necessary even though
I've only added API.

I've stopped changing the --version-info in gtkmm at all since a couple
of years ago to avoid problems, but I'd really like a simple set of
instructions about what to do in our most common cases, with examples of
actual --version-info numbers before and after.

For instance:

a) releasing a stable 2.4.4 tarball version, after the previous stable
2.4.3 tarball version, with no API additions or API changes.

b) releasing an unstable 2.5.1 tarball version, after the previous
stable 2.4.x tarball versions, with API additions.

c) releasing an unstable 2.5.2 tarball version, after the previous
unstable 2.5.1 tarball version, with both API changes and API additions.

d) releasing an unstable 2.5.2 tarball version, after the previous
unstable 2.5.1 tarball version, with API changes.

e) releasing an unstable 2.5.2 tarball version, after the previous
unstable 2.5.1 tarball version, with both API changes and API additions.


-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com