libtool: Release numbers

1 
1 7.4 Managing release information
1 ================================
1 
1 Often, people want to encode the name of the package release into the
1 shared library so that it is obvious to the user what package their
1 programs are linked against.  This convention is used especially on
1 GNU/Linux:
1 
1      trick$ ls /usr/lib/libbfd*
1      /usr/lib/libbfd.a           /usr/lib/libbfd.so.2.7.0.2
1      /usr/lib/libbfd.so
1      trick$
1 
1    On 'trick', '/usr/lib/libbfd.so' is a symbolic link to
1 'libbfd.so.2.7.0.2', which was distributed as a part of
1 'binutils-2.7.0.2'.
1 
1    Unfortunately, this convention conflicts directly with libtool's idea
1 of library interface versions, because the library interface rarely
1 changes at the same time that the release number does, and the library
1 suffix is never the same across all platforms.
1 
1    So, to accommodate both views, you can use the '-release' flag to set
1 release information for libraries for which you do not want to use
1 '-version-info'.  For the 'libbfd' example, the next release that uses
1 libtool should be built with '-release 2.9.0', which will produce the
1 following files on GNU/Linux:
1 
1      trick$ ls /usr/lib/libbfd*
1      /usr/lib/libbfd-2.9.0.so     /usr/lib/libbfd.a
1      /usr/lib/libbfd.so
1      trick$
1 
1    In this case, '/usr/lib/libbfd.so' is a symbolic link to
1 'libbfd-2.9.0.so'.  This makes it obvious that the user is dealing with
1 'binutils-2.9.0', without compromising libtool's idea of interface
1 versions.
1 
1    Note that this option causes a modification of the library name, so
1 do not use it unless you want to break binary compatibility with any
1 past library releases.  In general, you should only use '-release' for
1 package-internal libraries or for ones whose interfaces change very
1 frequently.
1