libtool: Libtool versioning

1 
1 7.2 Libtool's versioning system
1 ===============================
1 
1 Libtool has its own formal versioning system.  It is not as flexible as
1 some, but it is definitely the simplest of the more powerful versioning
1 systems.
1 
1    Think of a library as exporting several sets of interfaces,
1 arbitrarily represented by integers.  When a program is linked against a
1 library, it may use any subset of those interfaces.
1 
1    Libtool's description of the interfaces that a program uses is
1 simple: it encodes the least and the greatest interface numbers in the
1 resulting binary (FIRST-INTERFACE, LAST-INTERFACE).
1 
1    The dynamic linker is guaranteed that if a library supports _every_
1 interface number between FIRST-INTERFACE and LAST-INTERFACE, then the
1 program can be relinked against that library.
1 
1    Note that this can cause problems because libtool's compatibility
1 requirements are actually stricter than is necessary.
1 
1    Say 'libhello' supports interfaces 5, 16, 17, 18, and 19, and that
1 libtool is used to link 'test' against 'libhello'.
1 
1    Libtool encodes the numbers 5 and 19 in 'test', and the dynamic
1 linker will only link 'test' against libraries that support _every_
1 interface between 5 and 19.  So, the dynamic linker refuses to link
1 'test' against 'libhello'!
1 
1    In order to eliminate this problem, libtool only allows libraries to
1 declare consecutive interface numbers.  So, 'libhello' can declare at
1 most that it supports interfaces 16 through 19.  Then, the dynamic
1 linker will link 'test' against 'libhello'.
1 
1    So, libtool library versions are described by three integers:
1 
1 CURRENT
1      The most recent interface number that this library implements.
1 
1 REVISION
1      The implementation number of the CURRENT interface.
1 
1 AGE
1      The difference between the newest and oldest interfaces that this
1      library implements.  In other words, the library implements all the
1      interface numbers in the range from number 'CURRENT - AGE' to
1      'CURRENT'.
1 
1    If two libraries have identical CURRENT and AGE numbers, then the
1 dynamic linker chooses the library with the greater REVISION number.
1