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