If you want to use libtool’s versioning system, then you must specify
the version information to libtool using the -version-info flag
during link mode (see Link mode).
This flag accepts an argument of the form
‘current[:revision[:age]]’. So, passing
-version-info 3:12:1 sets current to 3, revision to
12, and age to 1.
If either revision or age are omitted, they default to 0.
Also note that age must be less than or equal to the current
interface number.
Here are a set of rules to help you update your library version
information:
- Start with version information of ‘0:0:0’ for each libtool library.
- 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.
- If the library source code has changed at all since the last update,
then increment revision (‘c:r:a’ becomes
‘c:r+1:a’).
- If any interfaces have been added, removed, or changed since the last
update, increment current, and set revision to 0.
- If any interfaces have been added since the last public release, then
increment age.
- If any interfaces have been removed or changed 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.
Instead, use the -release flag (see Managing release information), but be
warned that every release of your package will not be binary compatible
with any other release.
The following explanation may help to understand the above rules a bit
better: consider that there are three possible kinds of reactions from
users of your library to changes in a shared library:
- Programs using the previous version may use the new version as
drop-in replacement, and programs using the new version can also work
with the previous one. In other words, no recompiling nor relinking
is needed. In this case, bump revision only, don’t touch
current nor age.
- Programs using the previous version may use the new version as
drop-in replacement, but programs using the new version may use APIs not
present in the previous one. In other words, a program linking against
the new version may fail with “unresolved symbols” if linking against
the old version at runtime: set revision to 0, bump current
and age.
- Programs may need to be changed, recompiled, and relinked in order to use
the new version. Bump current, set revision and age
to 0.
In the above description, programs using the library in question
may also be replaced by other libraries using it.