File: libtool.info,  Node: Updating version info,  Next: Release numbers,  Prev: Libtool versioning,  Up: Versioning

7.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 (*note 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:

  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 increment REVISION (‘C:R:A’ becomes ‘C:r+1:A’).

  4. If any interfaces have been added, removed, or changed since the
     last update, increment CURRENT, and set REVISION to 0.

  5. If any interfaces have been added since the last public release,
     then increment AGE.

  6. 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 (*note Release numbers::), 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:

  1. 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.

  2. 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.

  3. 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.