using libtool for libraries, autotool versioning

http://sources.redhat.com/autobook/autobook/autobook_91.html

 

1. If you have changed any of the sources for this library, the revision number must be incremented.This is a new revision of the current interface.

2. If the interface has changed, then current must be incremented, andrevision reset to`0'. This is the first revision of a new interface.

3. If the new interface is a superset of the previous interface (that is, if the previous interface has not been broken by the changes in this new release), thenage must be incremented.This release is backwards compatible with the previous release.

4. If the new interface has removed elements with respect to the previous interface, then you have broken backward compatibility andage must be reset to`0'. This release has a new, but backwards incompatible interface.

For example, if the next release of the library included some new commands for an existing socket protocol, you would use-version-info 1:0:1.This is the first revision of a new interface. This release is backwards compatible with the previous release.

Later, you implement a faster way of handling part of the algorithm at the core of the library, and release it with-version-info 1:1:1.This is a new revision of the current interface.

Unfortunately the speed of your new implementation can only be fully exploited by changing the API to access the structures at a lower level, which breaks compatibility with the previous interface, so you release it as-version-info 2:0:0.This release has a new, but backwards incompatible interface.

 

 

http://nondot.org/sabre/Mirrored/libtool-2.1a/libtool_6.html

 

6.2 Libtool's versioning system

Libtool has its own formal versioning system. It is not as flexible as some, but it is definitely the simplest of the more powerful versioning systems.

Think of a library as exporting several sets of interfaces, arbitrarily represented by integers. When a program is linked against a library, it may use any subset of those interfaces.

Libtool's description of the interfaces that a program uses is simple: it encodes the least and the greatest interface numbers in the resulting binary (first-interface,last-interface).

The dynamic linker is guaranteed that if a library supports every interface number betweenfirst-interface andlast-interface, then the program can be relinked against that library.

Note that this can cause problems because libtool's compatibility requirements are actually stricter than is necessary.

Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that libtool is used to link`test' against`libhello'.

Libtool encodes the numbers 5 and 19 in `test', and the dynamic linker will only link`test' against libraries that supportevery interface between 5 and 19. So, the dynamic linker refuses to link`test' against`libhello'!

In order to eliminate this problem, libtool only allows libraries to declare consecutive interface numbers. So,`libhello' can declare at most that it supports interfaces 16 through 19. Then, the dynamic linker will link`test' against`libhello'.

So, libtool library versions are described by three integers:

current

The most recent interface number that this library implements.

revision

The implementation number of the current interface.

age

The difference between the newest and oldest interfaces that this library implements. In other words, the library implements all the interface numbers in the range from numbercurrent -age to current.

If two libraries have identical current and age numbers, then the dynamic linker chooses the library with the greaterrevision number.

6.3 Updating library version information

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 section4.2 Link mode).

This flag accepts an argument of the form `current[:revision[:age]]'. So, passing`-version-info 3:12:1' setscurrent to 3, revision to 12, andage to 1.

If either revision or age are omitted, they default to 0. Also note thatage must be less than or equal to thecurrent interface number.

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 incrementrevision (`c:r:a' becomes`c:r+1:a').
4. If any interfaces have been added, removed, or changed since the last update, incrementcurrent, and setrevision to 0.
5. If any interfaces have been added since the last public release, then incrementage.
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. Instead, use the`-release' flag (see section 6.4 Managing release information), but be warned that every release of your package will not be binary compatibility with any other release.