How to build fully correctly versioned shared object files with cmake

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

How to build fully correctly versioned shared object files with cmake

Philip Van Hoof
Hello everyone,

I noticed that it sometimes happens that I find a package for a shared
object file(s) (or DLLs, on platforms like Windows) that have a build
set up using cmake, that doesn't set everything that should be set.

Usually as packagers of various popular open source softwares correct
enthusiasts' attempts at understanding the sometimes bizarre
complexities of for example autotools, but (although it's all less
complicated) also cmake, it ends up somewhat right. Somewhat. I noticed
that especially in corporate world, things tend to go spectacularly
wrong. Almost without exception.

In particular am I concerned about ABI versioning of shared object
files so that they are easy to package and distribute by various
operating systems (like, among others, Linux distributions). But also
API versioning of development files (compiler header files and pkg-
config) and installing to the right installation paths.

I wanted to invite the community to scrutinize some equivalent examples
that I made for autotools (with libtool), qmake, cmake and meson.

https://github.com/pvanhoof/dir-examples/

In particular I wanted to invite the cmake community to take a look at
this example:

https://github.com/pvanhoof/dir-examples/tree/master/cmake-example

The idea is that the examples are as correct as possible. That means
the examples should simple and educational. Easing (some amount) of
platform independence (ie. supporting Windows) and packaging.

ps. I don't think CC-ing a huge amount of mailing lists is necessarily
a good idea. So feel free to forward to the appropriate people.

ps. I attached no license to the examples yet. Perhaps I should attach
one? My goal would be that as much entities could copy and use it.
Including for, indeed, non-free purposes (as much as they want).


Kind regards,

Philip Van Hoof
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: How to build fully correctly versioned shared object files with cmake

Hendrik Sattler


Am 6. August 2018 20:27:23 MESZ schrieb Philip Van Hoof <[hidden email]>:

>Hello everyone,
>
>I noticed that it sometimes happens that I find a package for a shared
>object file(s) (or DLLs, on platforms like Windows) that have a build
>set up using cmake, that doesn't set everything that should be set.
>
>Usually as packagers of various popular open source softwares correct
>enthusiasts' attempts at understanding the sometimes bizarre
>complexities of for example autotools, but (although it's all less
>complicated) also cmake, it ends up somewhat right. Somewhat. I noticed
>that especially in corporate world, things tend to go spectacularly
>wrong. Almost without exception.
>
>In particular am I concerned about ABI versioning of shared object
>files so that they are easy to package and distribute by various
>operating systems (like, among others, Linux distributions). But also
>API versioning of development files (compiler header files and pkg-
>config) and installing to the right installation paths.
>
>I wanted to invite the community to scrutinize some equivalent examples
>that I made for autotools (with libtool), qmake, cmake and meson.
>
>https://github.com/pvanhoof/dir-examples/
>
>In particular I wanted to invite the cmake community to take a look at
>this example:
>
>https://github.com/pvanhoof/dir-examples/tree/master/cmake-example
>
>The idea is that the examples are as correct as possible. That means
>the examples should simple and educational. Easing (some amount) of
>platform independence (ie. supporting Windows) and packaging.

Is there ANY reason to use libtool library versioning? It might surprise people but it really is not any kind of standard.

Just change the SOVERSION when you make incompatible ABI changes and a normal library VERSION. There's really not more to it, especially nothing like the sick results that libtool produces, sometimes.

The difficult thing is to realize the need for such a change. But there are tools that can help.

>ps. I don't think CC-ing a huge amount of mailing lists is necessarily
>a good idea. So feel free to forward to the appropriate people.
>
>ps. I attached no license to the examples yet. Perhaps I should attach
>one? My goal would be that as much entities could copy and use it.
>Including for, indeed, non-free purposes (as much as they want).
>
>
>Kind regards,
>
>Philip Van Hoof
--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: How to build fully correctly versioned shared object files with cmake

Philip Van Hoof
On Mon, 2018-08-06 at 21:54 +0200, Hendrik Sattler wrote:

Hello Hendrik,

> > https://github.com/pvanhoof/dir-examples/tree/master/cmake-example
> >
> > The idea is that the examples are as correct as possible. That
> > means the examples should simple and educational. Easing (some
> > amount) of platform independence (ie. supporting Windows) and
> > packaging.
>
> Is there ANY reason to use libtool library versioning? It might
> surprise people but it really is not any kind of standard.

Right, I got a similar remark from the meson people. And I guess people
who are used to qmake will probably also rightfully wonder about this.

The reason is that I wanted to create four examples with identical
method of doing versioning, and that I wanted to refer to the autotools
mythbusters and official libtool documentation for the time being.

        For the time being until there is a sort of community consensus
(crossing multiple popular build environments), and that this gets
documented somewhat 'officially'. Right now, GNU kinda sets the de
facto standard and GNU (fortunately or unfortunately) utilizes libtool
and autotools (a lot). (Please don't read that as me saying that's a
good thing, as I'm not saying that).

I did however tried to make it easy to change the variable fabrication
at the root of the projects (the cmake-example/CMakeLists.txt).

For the cmake example you could take these (which admittedly are not
necessarily easy to understand, but, documented):

set(CMAKE_EXAMPLE_CURRENT_VERSION 3)
set(CMAKE_EXAMPLE_REVISION_VERSION 0)
set(CMAKE_EXAMPLE_AGE_VERSION 1)

math(EXPR CMAKE_EXAMPLE_SOVERSION "${CMAKE_EXAMPLE_CURRENT_VERSION} -
      ${CMAKE_EXAMPLE_AGE_VERSION}")

set(CMAKE_EXAMPLE_VERSION
  ${CMAKE_EXAMPLE_SOVERSION}.
    ${CMAKE_EXAMPLE_AGE_VERSION}.
    ${CMAKE_EXAMPLE_REVISION_VERSION})


And replace them with these (or something like these):

set(CMAKE_EXAMPLE_SOVERSION "2")
set(CMAKE_EXAMPLE_VERSION "2.1.0")

> Just change the SOVERSION when you make incompatible ABI changes and
> a normal library VERSION. There's really not more to it, especially
> nothing like the sick results that libtool produces, sometimes.

nod.

However. I'm not sure about trying to explain different versioning
style for equivalent examples (and in my examples I also include a
autotools one - unfortunately, or fortunately for people who are
converting from a autotools to a cmake, for example. Which is also
among the educational purposes of the examples).

I guess I could document it a little bit better in README.md ...

If people have suggestions? Just, however, let's try to keep it easy
for people coming from libtool-world. A lot of people do.

> The difficult thing is to realize the need for such a change. But
> there are tools that can help.

nod. I tried to explain the necessity in README.md.

I think it would be helpful to mention the tools, though. Suggestions
are welcome.

Thanks,

Kind regards,

Philip Van Hoof

--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: How to build fully correctly versioned shared object files with cmake

Alexander Neundorf
In reply to this post by Hendrik Sattler
On 2018 M08 6, Mon 21:54:33 CEST Hendrik Sattler wrote:
> Am 6. August 2018 20:27:23 MESZ schrieb Philip Van Hoof
<[hidden email]>:

> >Hello everyone,
> >
> >I noticed that it sometimes happens that I find a package for a shared
> >object file(s) (or DLLs, on platforms like Windows) that have a build
> >set up using cmake, that doesn't set everything that should be set.
> >
> >Usually as packagers of various popular open source softwares correct
> >enthusiasts' attempts at understanding the sometimes bizarre
> >complexities of for example autotools, but (although it's all less
> >complicated) also cmake, it ends up somewhat right. Somewhat. I noticed
> >that especially in corporate world, things tend to go spectacularly
> >wrong. Almost without exception.
> >
> >In particular am I concerned about ABI versioning of shared object
> >files so that they are easy to package and distribute by various
> >operating systems (like, among others, Linux distributions). But also
> >API versioning of development files (compiler header files and pkg-
> >config) and installing to the right installation paths.
> >
> >I wanted to invite the community to scrutinize some equivalent examples
> >that I made for autotools (with libtool), qmake, cmake and meson.
> >
> >https://github.com/pvanhoof/dir-examples/
> >
> >In particular I wanted to invite the cmake community to take a look at
> >this example:
> >
> >https://github.com/pvanhoof/dir-examples/tree/master/cmake-example
> >
> >The idea is that the examples are as correct as possible. That means
> >the examples should simple and educational. Easing (some amount) of
> >platform independence (ie. supporting Windows) and packaging.
>
> Is there ANY reason to use libtool library versioning? It might surprise
> people but it really is not any kind of standard.
>
> Just change the SOVERSION when you make incompatible ABI changes and a
> normal library VERSION. There's really not more to it, especially nothing
> like the sick results that libtool produces, sometimes.

I agree.
I would recommend
Major version  = SO version, increase it if you break ABI compatibility
Minor version: increase it if you add ABI compatible features
Patch version: increase it for bug fix releases.

Alex

--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: How to build fully correctly versioned shared object files with cmake

Philip Van Hoof
In reply to this post by Hendrik Sattler
Alexander Neundorf wrote:

> On Mon, 2018-08-06 at 21:54 +0200, Hendrik Sattler wrote:
> > Is there ANY reason to use libtool library versioning? It might
> > surprise people but it really is not any kind of standard.
> > 
> > Just change the SOVERSION when you make incompatible ABI changes
> > and a normal library VERSION. There's really not more to it,
> > especially nothing like the sick results that libtool produces,
> > sometimes.

> I agree.

> I would recommend
> Major version  = SO version, increase it if you break ABI
> compatibility
> Minor version: increase it if you add ABI compatible features
> Patch version: increase it for bug fix releases.
>
> Alex

Ok, I added this note to README.md, cmake, meson and qmake examples:

# When you don't care about compatibility with libtool's -version-info,
then you can take the following rules for VERSION in cmake, meson and
qmake:

# * SOVERSION = Major version
# * Major version: increase it if you break ABI compatibility
# * Minor version: increase it if you add ABI compatible features
# * Patch version: increase it for bug fix releases.

https://github.com/pvanhoof/dir-examples/commit/02a9a2d23ddf3627f87dd7a1af74b42603c4f890

(Because yes, you're right that libtool's -version-info is just
pointlessly complicated and messy for people who don't need to care)

Kind regards,

Philip Van Hoof

--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: How to build fully correctly versioned shared object files with cmake

Hendrik Sattler
In reply to this post by Alexander Neundorf


Am 6. August 2018 22:29:21 MESZ schrieb Alexander Neundorf <[hidden email]>:

>On 2018 M08 6, Mon 21:54:33 CEST Hendrik Sattler wrote:
>> Am 6. August 2018 20:27:23 MESZ schrieb Philip Van Hoof
><[hidden email]>:
>> >Hello everyone,
>> >
>> >I noticed that it sometimes happens that I find a package for a
>shared
>> >object file(s) (or DLLs, on platforms like Windows) that have a
>build
>> >set up using cmake, that doesn't set everything that should be set.
>> >
>> >Usually as packagers of various popular open source softwares
>correct
>> >enthusiasts' attempts at understanding the sometimes bizarre
>> >complexities of for example autotools, but (although it's all less
>> >complicated) also cmake, it ends up somewhat right. Somewhat. I
>noticed
>> >that especially in corporate world, things tend to go spectacularly
>> >wrong. Almost without exception.
>> >
>> >In particular am I concerned about ABI versioning of shared object
>> >files so that they are easy to package and distribute by various
>> >operating systems (like, among others, Linux distributions). But
>also
>> >API versioning of development files (compiler header files and pkg-
>> >config) and installing to the right installation paths.
>> >
>> >I wanted to invite the community to scrutinize some equivalent
>examples
>> >that I made for autotools (with libtool), qmake, cmake and meson.
>> >
>> >https://github.com/pvanhoof/dir-examples/
>> >
>> >In particular I wanted to invite the cmake community to take a look
>at
>> >this example:
>> >
>> >https://github.com/pvanhoof/dir-examples/tree/master/cmake-example
>> >
>> >The idea is that the examples are as correct as possible. That means
>> >the examples should simple and educational. Easing (some amount) of
>> >platform independence (ie. supporting Windows) and packaging.
>>
>> Is there ANY reason to use libtool library versioning? It might
>surprise
>> people but it really is not any kind of standard.
>>
>> Just change the SOVERSION when you make incompatible ABI changes and
>a
>> normal library VERSION. There's really not more to it, especially
>nothing
>> like the sick results that libtool produces, sometimes.
>
>I agree.
>I would recommend
>Major version  = SO version, increase it if you break ABI compatibility
>Minor version: increase it if you add ABI compatible features
>Patch version: increase it for bug fix releases.

Right. See http://semver.org

A  tool to check is e.g. the abi compliance checker.

It may be worth to mention that project version and library version may differ but that it also might confuse people.


--

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake