[ILUG-BOM] libtool versioning

[Philip Tellis]

I'd spoken about libtool versioning at a lug meet a long time ago.  This 
will just be few lines on it.

libtool libraries on linux are of the form:

libname.so.X.Y.Z

where 'name' is the name of the library, and X, Y and Z are whole 
numbers.

Let's deal with Y first since that's the easiest.

When a library author increments the Y number by 1, it signifies an 
internal change in the library that does not affect users of the 
library.  These would generally be things like changing an algorithm or 
variable names or documentation, but not touching the API.

Now the other two.

The first number - X - is the library version.  A library author 
increments this number by one when any of the following occurs:

  - A new feature (including API) was added
  - An existing feature (including API) was dropped
  - An existing feature (including API) was changed

Of the above, the first is backwards compatible, the second is not, and 
the third may be (using default values for new parameters for example).

For case 3, the new library may be source compatible but not binary 
compatible, suggesting that any code that uses the library must be 
recompiled to work, but not rewritten.  For case 2, any code that used 
the dropped feature must be rewritten.

For all three cases, code that uses the library may need to be 
recompiled even if it doesn't make use of the changed features because 
the virtual pointer table may have changed (specific to Compiled OO 
languages).

libtool versioning helps tell library users what to do.

Everytime X is incremented, it suggests that code may have to be 
rewritten or recompiled.  To identify which, we look at the last digit - 
Z.

The number Z is the library API's age, ie, how far back is it 
compatible.

So, a few examples.

You compile against:  libfoo.so.3.0.0


New version released: libfoo.so.3.1.0
Action needed:        none

New version released: libfoo.so.4.0.1
Action needed:        may need recompile/relink  (4-1 == 3)

New version released: libfoo.so.5.0.2
Action needed:        may need recompile/relink  (5-2 == 3)

New version released: libfoo.so.4.0.0
Action needed:        may need rewrite/recompile (4-0 > 3)

Let the major library version number that we compiled against be M.
In the above cases, to determine whether a recompile is required or a 
rewrite is required, we check that X-Z <= M <= X

Here's something that I use to remind me:
# +1 :  0 : +1   == new interface that does not break old one.
# +1 :  0 :  0   == removed/changed an interface. Breaks old apps.
#  ? : +1 :  ?   == internal changes that doesn't break anything.

Finished :)

For more information, run "info libtool"

-- 
Real Users are afraid they'll break the machine -- but they're never
afraid to break your face.