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

[Brad King]

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.

-Brad