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"