[prev in list] [next in list] [prev in thread] [next in thread]
List: cmake
Subject: Re: [CMake] Providing multiple different MAJOR API versions with write_basic_package_version_file
From: Craig Scott <craig.scott () crascit ! com>
Date: 2019-12-28 12:26:47
Message-ID: CA+dygY=gt6459ZyOgUs2YbO3So6+5VN3ApSTJBrHOnPGZj=d6A () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
On Mon, Nov 4, 2019 at 10:54 PM Philip Van Hoof <philip@codeminded.be>
wrote:
> Hello,
>
> After Craig's very interesting presentation at CppCon 2019* I learned a
> bunch of new things which I of course immediately wanted to try out**.
>
> I read about the write_basic_package_version_file which is in
> CMakePackageConfigHelpers. Craig also mentioned in the presentation
> that you can have a so called API-version in the target's name. And
> that for example Qt does this (Qt5Core, which has the MAJOR number 5 in
> its target name).
>
> For my target name I prefer to have the API version after a dash, like
> how GLib and DBus packages do it: libglib-2.0.so.0.6200.1 on current
> Ubuntu, for example in /usr/lib/x86_64-linux-gnu.
>
Understand that from CMake's point of view, the library name is then
glib-2.0 and the fact that it contains numbers that look like a version of
some kind is completely irrelevant (to CMake). You could just as well have
called it glib-specialsauce. Putting an API version into the library name
is *changing* the library name to something else. This is particularly
inconvenient for projects using find_package() to find your library, since
they have to specify the exact API version now because you've included it
in the library name. glib-2.0 is a completely different library to glib-2.1,
for example. It might be more precise, but it is less convenient to
consume. You could potentially remove that inconvenience by naming the
config package file glibConfig.cmake instead of glib-2.0Config.cmake, then
place it under an API-versioned directory that find_package() would search
in, but that would seem to remove the very advantage you are trying to gain
by putting the API version in the library name. The consuming project would
effectively be able to ignore the API version if you did this.
>
> I wonder what that means for the <filename> property of
> write_basic_package_version_file. In the autotools and meson world, the
> usage of pkg-config files seems to indicate that the same filename
> naming scheme applies to the .pc file:
>
> /usr/lib/x86_64-linux-gnu/pkgconfig/glib-2.0.pc
>
> This allows me to distinguish between older MAJOR API versions of GLib
> and newer MAJOR API versions of it, using FindPkgConfig***
>
> Supposedly something similar is possible with find_package's .cmake
> files as installed by write_basic_package_version_file?
>
As above, you are creating an entirely different library by putting the API
version in its base name. So your call to find_package() would be looking
for that API-specific name and your package version file would have to
match that expected name too.
>
> How do I provide a PackageNameConfigVersion.cmake for major version 1.0
> and 2.0 (the equivalent of PackageName-1.0.pc and PackageName-2.0.pc in
> the pkgconfig directory)?
>
Since from CMake's perspective they are two completely different libraries,
you'd end up with PackageName-1.0ConfigVersion.cmake and
PackageName-2.0ConfigVersion.cmake as the file names.
>
> Kind regards,
>
> Philip
>
> * https://www.youtube.com/watch?v=m0DwB4OvDXk
> **
> https://github.com/pvanhoof/dir-examples/commit/523cab5edaff99acba037218d5b95227cb2487a9
> *** https://cmake.org/cmake/help/v3.15/module/FindPkgConfig.html
I've debated whether to express my own opinion on this, but in this case
I'll risk it. I personally find that putting an API version in the name of
the library itself to be an annoyance. I'm typically interested in the ABI
versioning, and I take on the responsibility of understanding how that maps
to the API. If semantic versioning is being followed for the ABI
versioning, then this mapping is typically trivial. To me, any gains from
making the API version explicit in the library name are less significant
than the negative impact on the ease of consuming that library and the
added "scare factor" of an overly complicated versioning system. Versioning
is already complex enough for most users, if we can avoid making it more
so, then users will likely appreciate that.
It may be instructive to note that there were changes in CMake 3.14 to
support Qt being found without the API version being specified as part of
the package name (i.e. as find_package(Qt)). See policy CMP0084
<https://cmake.org/cmake/help/latest/policy/CMP0084.html> for some brief
background.
--
Craig Scott
Melbourne, Australia
https://crascit.com
Get the hand-book for every CMake user: Professional CMake: A Practical
Guide <https://crascit.com/professional-cmake/>
Consulting services (CMake, C++, build/release processes):
https://crascit.com/services
[Attachment #5 (text/html)]
<div dir="ltr"><div><br></div><div class="gmail_quote"><div dir="ltr" \
class="gmail_attr">On Mon, Nov 4, 2019 at 10:54 PM Philip Van Hoof <<a \
href="mailto:philip@codeminded.be">philip@codeminded.be</a>> \
wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">Hello,<br>
<br>
After Craig's very interesting presentation at CppCon 2019* I learned a<br>
bunch of new things which I of course immediately wanted to try out**.<br>
<br>
I read about the write_basic_package_version_file which is in<br>
CMakePackageConfigHelpers. Craig also mentioned in the presentation<br>
that you can have a so called API-version in the target's name. And<br>
that for example Qt does this (Qt5Core, which has the MAJOR number 5 in<br>
its target name).<br>
<br>
For my target name I prefer to have the API version after a dash, like<br>
how GLib and DBus packages do it: libglib-2.0.so.0.6200.1 on current<br>
Ubuntu, for example in \
/usr/lib/x86_64-linux-gnu.<br></blockquote><div><br></div><div>Understand that from \
CMake's point of view, the library name is then <font \
face="monospace">glib-2.0</font> and the fact that it contains numbers that look like \
a version of some kind is completely irrelevant (to CMake). You could just as well \
have called it <font face="monospace">glib-specialsauce</font>. Putting an API \
version into the library name is <i>changing</i> the library name to something else. \
This is particularly inconvenient for projects using <font \
face="monospace">find_package()</font> to find your library, since they have to \
specify the exact API version now because you've included it in the library name. \
<font face="monospace">glib-2.0</font> is a completely different library to <font \
face="monospace">glib-2.1</font>, for example. It might be more precise, but it is \
less convenient to consume. You could potentially remove that inconvenience by naming \
the config package file <font face="monospace">glibConfig.cmake</font> instead of \
<font face="monospace">glib-2.0Config.cmake</font>, then place it under an \
API-versioned directory that <font face="monospace">find_package()</font> would \
search in, but that would seem to remove the very advantage you are trying to gain by \
putting the API version in the library name. The consuming project would effectively \
be able to ignore the API version if you did this.</div><div><br></div><div> \
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
<br>
I wonder what that means for the <filename> property of<br>
write_basic_package_version_file. In the autotools and meson world, the<br>
usage of pkg-config files seems to indicate that the same filename<br>
naming scheme applies to the .pc file: <br>
<br>
/usr/lib/x86_64-linux-gnu/pkgconfig/glib-2.0.pc<br>
<br>
This allows me to distinguish between older MAJOR API versions of GLib<br>
and newer MAJOR API versions of it, using FindPkgConfig***<br>
<br>
Supposedly something similar is possible with find_package's .cmake<br>
files as installed by \
write_basic_package_version_file?<br></blockquote><div><br></div><div>As above, you \
are creating an entirely different library by putting the API version in its base \
name. So your call to find_package() would be looking for that API-specific name and \
your package version file would have to match that expected name too.</div><div> \
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
<br>
How do I provide a PackageNameConfigVersion.cmake for major version 1.0<br>
and 2.0 (the equivalent of PackageName-1.0.pc and PackageName-2.0.pc in<br>
the pkgconfig directory)?<br></blockquote><div><br></div><div>Since from CMake's \
perspective they are two completely different libraries, you'd end up with <font \
face="monospace">PackageName-1.0ConfigVersion.cmake</font> and <font \
face="monospace">PackageName-2.0ConfigVersion.cmake</font> as the file \
names.</div><div><br></div><div> </div><blockquote class="gmail_quote" \
style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
<br>
Kind regards,<br>
<br>
Philip<br>
<br>
* <a href="https://www.youtube.com/watch?v=m0DwB4OvDXk" rel="noreferrer" \
target="_blank">https://www.youtube.com/watch?v=m0DwB4OvDXk</a><br>
** <a href="https://github.com/pvanhoof/dir-examples/commit/523cab5edaff99acba037218d5b95227cb2487a9" \
rel="noreferrer" target="_blank">https://github.com/pvanhoof/dir-examples/commit/523cab5edaff99acba037218d5b95227cb2487a9</a><br>
*** <a href="https://cmake.org/cmake/help/v3.15/module/FindPkgConfig.html" \
rel="noreferrer" target="_blank">https://cmake.org/cmake/help/v3.15/module/FindPkgConfig.html</a></blockquote><div><br></div><div><br></div><div>I've \
debated whether to express my own opinion on this, but in this case I'll risk it. \
I personally find that putting an API version in the name of the library itself to be \
an annoyance. I'm typically interested in the ABI versioning, and I take on the \
responsibility of understanding how that maps to the API. If semantic versioning is \
being followed for the ABI versioning, then this mapping is typically trivial. To me, \
any gains from making the API version explicit in the library name are less \
significant than the negative impact on the ease of consuming that library and the \
added "scare factor" of an overly complicated versioning system. Versioning \
is already complex enough for most users, if we can avoid making it more so, then \
users will likely appreciate that.</div><div><br></div><div>It may be instructive to \
note that there were changes in CMake 3.14 to support Qt being found without the API \
version being specified as part of the package name (i.e. as <font \
face="monospace">find_package(Qt)</font>). See <a \
href="https://cmake.org/cmake/help/latest/policy/CMP0084.html">policy CMP0084</a> for \
some brief background.</div><div><br></div></div>-- <br><div dir="ltr" \
class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div \
dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr">Craig \
Scott<br><div>Melbourne, Australia</div><div><a href="https://crascit.com" \
target="_blank">https://crascit.com</a><br></div><div><br></div><div>Get the \
hand-book for every CMake user: <a href="https://crascit.com/professional-cmake/" \
target="_blank">Professional CMake: A Practical Guide</a><br></div><div>Consulting \
services (CMake, C++, build/release processes): <a \
href="https://crascit.com/services" \
target="_blank">https://crascit.com/services</a></div></div></div></div></div></div></div></div></div></div></div></div>
--
Powered by kitware.com/cmake
Kitware offers various services to support the CMake community. For more information \
on each offering, please visit https://cmake.org/services
Visit other Kitware open-source projects at https://www.kitware.com/platforms
Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake
This mailing list is deprecated in favor of https://discourse.cmake.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic