libtool: Updating version info
1
1 7.3 Updating library version information
1 ========================================
1
1 If you want to use libtool's versioning system, then you must specify
1 the version information to libtool using the '-version-info' flag during
1 link mode (⇒Link mode).
1
1 This flag accepts an argument of the form 'CURRENT[:REVISION[:AGE]]'.
1 So, passing '-version-info 3:12:1' sets CURRENT to 3, REVISION to 12,
1 and AGE to 1.
1
1 If either REVISION or AGE are omitted, they default to 0. Also note
1 that AGE must be less than or equal to the CURRENT interface number.
1
1 Here are a set of rules to help you update your library version
1 information:
1
1 1. Start with version information of '0:0:0' for each libtool library.
1
1 2. Update the version information only immediately before a public
1 release of your software. More frequent updates are unnecessary,
1 and only guarantee that the current interface number gets larger
1 faster.
1
1 3. If the library source code has changed at all since the last
1 update, then increment REVISION ('C:R:A' becomes 'C:r+1:A').
1
1 4. If any interfaces have been added, removed, or changed since the
1 last update, increment CURRENT, and set REVISION to 0.
1
1 5. If any interfaces have been added since the last public release,
1 then increment AGE.
1
1 6. If any interfaces have been removed or changed since the last
1 public release, then set AGE to 0.
1
1 *_Never_* try to set the interface numbers so that they correspond to
1 the release number of your package. This is an abuse that only fosters
1 misunderstanding of the purpose of library versions. Instead, use the
1 '-release' flag (⇒Release numbers), but be warned that every
1 release of your package will not be binary compatible with any other
1 release.
1
1 The following explanation may help to understand the above rules a
1 bit better: consider that there are three possible kinds of reactions
1 from users of your library to changes in a shared library:
1
1 1. Programs using the previous version may use the new version as
1 drop-in replacement, and programs using the new version can also
1 work with the previous one. In other words, no recompiling nor
1 relinking is needed. In this case, bump REVISION only, don't touch
1 CURRENT nor AGE.
1
1 2. Programs using the previous version may use the new version as
1 drop-in replacement, but programs using the new version may use
1 APIs not present in the previous one. In other words, a program
1 linking against the new version may fail with "unresolved symbols"
1 if linking against the old version at runtime: set REVISION to 0,
1 bump CURRENT and AGE.
1
1 3. Programs may need to be changed, recompiled, and relinked in order
1 to use the new version. Bump CURRENT, set REVISION and AGE to 0.
1
1 In the above description, _programs_ using the library in question may
1 also be replaced by other libraries using it.
1