Re: libtool versioning

[Jef Driesen]

On 03/05/10 20:00, Ralf Wildenhues wrote:
> Hello Jef,
>
> * Jef Driesen wrote on Mon, May 03, 2010 at 09:08:14AM CEST:
> > On 02/05/10 03:33, Bob Friesenhahn wrote:
> > > On Sun, 2 May 2010, Jef Driesen wrote:
> > >
> > > > I'm trying to understand the libtool current:revision:age versioning scheme.
> > > > I think I understand how it works, but I noticed that filename of the shared
> > > > library seems to get different numbers (current-age.age.revision). Is that
> > > > expected?
> > >
> > > The filename generation is dependent on the OS.  It is usually best
> > > not to pay any attention to the filenames at all unless you are
> > > switching from some other existing numbering scheme and need to avoid
> > > a collision.  I keep these notes in my configure script (taken from
> > > various libtool related documentation) so that I remember how things
> > > work:
> >
> > The reason why I found the filename confusing, is because in the
> > article I was looking at, they make it look like the libtool version
> > c:r:a ends up in the filename as "libfoo.so.c.r.a".
> >
> > http://www.freesoftwaremagazine.com/books/agaal/building_shared_libraries_once_using_autotools
>
> I'm adding John in Cc:, he should be able to say more about this.
>
> > I have seen this a couple of other places as well.
>
> Like, the GNU Libtool manual?  Have you looked there?

Yes, I have read the libtool manual, but it doesn't contain much info 
about the resulting filename. Most of the info is about the c:r:a scheme 
for input, not the output.

> > As a newbe to the
> > libtool versionning scheme, it took me a while to figure out what
> > was really going on. Very confusing.
> >
> > > # Here are a set of rules to help you update your library version
> > > # information:
> > > #
> > > #  1. Start with version information of `0:0:0' for each libtool library.
> > > #  2. Update the version information only immediately before a public
> > > #     release of your software. More frequent updates are unnecessary, and
> > > #     only guarantee that the current interface number gets larger faster.
> > > #  3. If the library source code has changed at all since the last update,
> > > #     then increment revision (`c:r:a' becomes `c:r+1:a').
> > > #  4. If any interfaces have been added, removed, or changed since the last
> > > #     update, increment current, and set revision to 0.
> > > #  5. If any interfaces have been added since the last public release, then
> > > #     increment age.
> > > #  6. If any interfaces have been removed since the last public release,
> > > #     then set age to 0.
> >
> > Shouldn't step #6 included "changed" as well as "removed"? If you
> > change the interface (for example modifying function parameters),
> > backwards compatibility is broken too. But only "removed" is listed
> > here.
>
> Well, it is listed in step 4 already.

Sure, but if interfaces have been changed, but not removed, the 
algorithm stops at step #4, and you get:

c+1:0:a

But if an interface has been removed, you have to apply #6 and get:

c+1:0:O

But in both situations backwards compatibility has been broken. So I 
would think you have to apply step #6 in both cases.

> > Personally, I think the last three steps are easier to understand
> > when written as if cases, rather than steps:
> >
> > 1. Interface unchanged: C:R+1:A
> > 2. Interface changed in a backwards compatible way: C+1:0:A+1
> > 3. Interface changed and backwards compatibility is broken: C+1:0:0
>
> The git master version of Libtool is hopefully a bit easier to
> understand, it has an alternate description added, which is similar to
> yours:
> <http://git.savannah.gnu.org/cgit/libtool.git/commit/?id=7890173078d185548f1f058322d8ddc3b18cfc81>

I find this a more intuitive description. I'm sure others will 
appreciate it too!