[cmake-developers] CMake vs libtool versioning of shared libraries

Ben Boeckel ben.boeckel at kitware.com
Thu Dec 15 14:28:13 EST 2016


On Thu, Dec 15, 2016 at 14:08:35 -0500, Brad King wrote:
> On 12/15/2016 01:57 PM, Kim Walisch wrote:
> > Lets suppose I do not want to stick to my previous libtool versioning
> > but instead version my library according to cmake best practices. How
> > should I set VERSION and SOVERSION given my API version is 3.5 and my
> > old ABI version 4:7:0. By browsing a few CMakeLists.txt on GitHub of
> > other projects it seems to me that most of these projects set VERSION
> > to the project/API version (e.g. 3.5) and the SOVERSION to the
> > project/API major version (e.g 3).
> 
> The VERSION is only for human reference and so can be the project
> version or anything else.  The SOVERSION is what provides the
> API version level.  A binary linked to your library will at runtime
> look for "libfoo.so.$soversion", and any file the dynamic loader
> can find with that name is considered acceptable.  Therefore the
> SOVERSION should be used for API versioning.  If you remove an
> API then the soversion should be changed.
> 
> The project version and API version don't have to be related,
> but it is a common convention depending on API stability.

Note that this is actually ABI compatibility, not API (i.e.,
source-level) compatibility.

Adding virtual methods, reordering struct members, changing struct
sizes, etc. all require a SOVERSION bump upon release, but are not
necessarily API breaks. KDE has a list of things which change the ABI
for C++ here:

    https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B

It does not look to have been updated for C++11, so things which affect
`auto` deduction may also cause ABI incompatibilities.

--Ben


More information about the cmake-developers mailing list