libtool
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: libtool versioning and ABI


From: Charles Wilson
Subject: Re: libtool versioning and ABI
Date: Tue, 11 Aug 2009 16:45:58 -0400
User-agent: Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US; rv:1.8.1.22) Gecko/20090605 Thunderbird/2.0.0.22 Mnenhy/0.7.6.666

Michel Briand wrote:

> Thank you, but, sorry, I'm not convinced. Remember what I said a
> few mails ago: that's all of interface contract = same concept as
> your...
> 
> Does anyone uses "10" or "16" to refer to their ABI ? Hum... So those
> numbers have to be managed somewhere...

Yes.  Here are a few libraries on my linux box:

libalsa2-1.0.15-0.rc1.4mdv2008.0      ABI=2, pkgver=1.0.15
libamarok0-scripts-1.4.7-9mdv2008.0   ABI=0, pkgver=1.4.7
libamrnb2-6.1.0.3-1plf2008.0          ABI=2, pkgver=6.1.0.3
libao2-0.8.8-2mdv2008.0               ABI=2, pkgver=0.8.8
libapplewm7-1.0.0-5mdv2008.0          ABI=7, pkgver=1.0.0
libavformats51-0.4.9-3.pre1.8994.2plf2008.0
                                      ABI=51, pkgver=0.4.9
libavutil49-0.4.9-3.pre1.8994.2plf2008.0
                                      ABI=49, pkgver=0.4.9

and that's just the liba*'s. Managing those numbers is part of
maintaining a library, and you do it in the Makefile[.am],
documentation, and (.spec|.deb|pkglist).  It's just part of the job.

In case you're wondering, here's the contents of
libavformats51-0.4.9-3.pre1.8994.2plf2008.0:

/usr/lib/libavformat.so.51        << SONAME, S = 51
/usr/lib/libavformat.so.51.12.1   << derived from -version-info. None
                                     of these numbers has anything to
                                     do with "0.4.9".
The -version-info 63:1:12 is managed completely independently of the
decision-making process for "hey, should we call this release 0.4.9 or
2.7.1? (except, of course, for the politeness aspect that (a) totally
random version numbers are stupid and something only Microsoft
w95/w98/Me/2k/XP/Vista/7 does, not a FOSS thing, and (b) it's nice to
*increment* (net "set equal to a specific value") the major version
number of the package when the SONAME changes due to internal ABI breakage.

> If developers and users are ok with X.Y.Z then the CURRENT, REVISION
> and AGE is a different scheme to learn and to implement in the build
> system: that need to be managed in parallel.

Yes, that's exactly what were trying to help you understand.  With the
exception of the "niceness" aspect above, *package* numbers are
basically marketing, even in FOSS. However, library interface numbers
are wholly TECHNICAL. If you change the code in /this way/ then the
library interface changes /that way/, according to specific rules; these
rules may then also drive a change in the SONAME.

> That's to say that if dev
> makes some changes in ABI and bumps the version up (say X.Y.Z+1),
> someone has to think about the weird libtool thing and update the
> libtool's versioning, making substractions and the like...

No, you've got it exactly backwards.  (Now, what happens during ongoing
CVS/git/hg/bzr development is different; the "rules" only apply for
actual releases.  Otherwise you just get way too many version number
changes for no purpose.  The point of library versioning is to foster
interoperatability across compatible *public* interfaces of your library
to *outside* clients.  So, really, you basically apply the rules below
during the runup to an actual release.  But, in principle:

If a developer changes the ABI, then the -version-info does NOT change
as X.Y.Z+1.  The developer must modify the -version-info according to
these rules:

============== from libtool documentation ============

  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.

   *_Never_* try to set the interface numbers so that they correspond
to the release number of your package. This is an abuse that only
fosters misunderstanding of the purpose of library versions.

*[ed: Read that paragraph again.  Go ahead.  I'll wait here.]

============== from libtool documentation ============

Okay, so you've done all that.  And now your team decides that it's time
to cut a release.  You need to pick the *package* version number.  This
is marketing (modulo the "nice" bump-majver-if-abi-changed behavior).

Pick a number.  Increment X. Increment Y. Increment Z.  do whatever you
want. It's NOT a technical decision.

> And no matter the operating system : on most the .so will have no
> number at all.

No, that's wrong.  The .so is just the linktime pointer that is found
when you link some client using -lfoo.  It points to the actual library,
which is (as in the case above):

/usr/lib/libavformat.so.51

The clients actually record the SONAME (which has this single "major"
version number -- not to be confused with the source package X.Y.Z "X"
major version).  Take a look at the output of

ldd /bin/some-executable

You'll see that the library names are the ones like libfoo.so.7. NOT
libfoo.so.

> Crafted: yes, crafted. Since I use X.Y.Z as a comprehensive label for
> devs and users, 

This is your problem.  X.Y.Z is NOT SUPPOSED TO HAVE ANYTHING TO DO with
c:r:a. (except that it's nice to bump X to X+1 whenever you trigger rule
#4 but do not also simultaneously trigger rule #5. e.g. when the SONAME
changes).

I have to craft the C:R:A to reflect that...

No. You do not HAVE to do this.  You WANT to do this, because you refuse
to understand the difference between library/interface versioning, which
is a technically-driven requirement promoting consistent
interoperability between clients and (compatible VERSIONS of) a library
ABI, and package versioning, which is marketing.

> So any practical method ?

I give up.  I'm done with this thread.

--
Chuck







reply via email to

[Prev in Thread] Current Thread [Next in Thread]