Adding Cmake version in online documentation

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

Adding Cmake version in online documentation

Louis-Paul CORDIER

Hi,

This is a feature proposal for the documentation. Cmake is making use of cmake_minimum_required() command, that is very useful. Unfortunately it is very hard to identify commands that will work without browsing all version of cmake documentation for a given command.

That said, adding a "since version" number for a feature/command would be great, like cplusplus.com does (example here: http://www.cplusplus.com/reference/unordered_map/unordered_map/?kw=unordered_map)

For instance, the command

list(FILTER ...)

has been introduced in Cmake 3.6. Why not adding

list(FILTER ...) (since 3.6)

?
--

Best Regards/
Louis-Paul CORDIER


--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Michael Jackson
+1
--
Mike Jackson  [[hidden email]]


Louis-Paul CORDIER wrote:

> Hi,
>
> This is a feature proposal for the documentation. Cmake is making use of
> cmake_minimum_required() command, that is very useful. Unfortunately it
> is very hard to identify commands that will work without browsing all
> version of cmake documentation for a given command.
>
> That said, adding a "since version" number for a feature/command would
> be great, like cplusplus.com does (example here:
> http://www.cplusplus.com/reference/unordered_map/unordered_map/?kw=unordered_map)
>
> For instance, the command
>
> list(FILTER ...)
>
> has been introduced in Cmake 3.6. Why not adding
>
> list(FILTER ...) (since 3.6)
>
> ?
> --
>
> *Best Regards/
> Louis-Paul CORDIER
> *
>
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Nils Gladitz-2
In reply to this post by Louis-Paul CORDIER
On 11/08/2016 10:57 AM, Louis-Paul CORDIER wrote:

> Hi,
>
> This is a feature proposal for the documentation. Cmake is making use
> of cmake_minimum_required() command, that is very useful.
> Unfortunately it is very hard to identify commands that will work
> without browsing all version of cmake documentation for a given command.
>

This has been brought up for discussion more than once e.g.:
     https://public.kitware.com/Bug/view.php?id=15517
     https://public.kitware.com/Bug/view.php?id=15222
     http://public.kitware.com/pipermail/cmake/2016-April/063306.html

Personally I still don't think this needs change.
You don't have to browse all versions of the documentation ... you only
have to work with the documentation that matches the version you
declared in cmake_minimum_required().

Nils
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Dvir Yitzchaki
But how do you know which version to declare on cmake_minimum_required?
If this feature will be added it won't be far from writing a script that scans the commands you use and outputs the first appropriate version.

Regards,

Dvir    

-----Original Message-----
From: CMake [mailto:[hidden email]] On Behalf Of Nils Gladitz
Sent: Tuesday, November 08, 2016 3:37 PM
To: Louis-Paul CORDIER <[hidden email]>; Cmake Mailing List <[hidden email]>
Subject: Re: [CMake] Adding Cmake version in online documentation

On 11/08/2016 10:57 AM, Louis-Paul CORDIER wrote:

> Hi,
>
> This is a feature proposal for the documentation. Cmake is making use
> of cmake_minimum_required() command, that is very useful.
> Unfortunately it is very hard to identify commands that will work
> without browsing all version of cmake documentation for a given command.
>

This has been brought up for discussion more than once e.g.:
     https://public.kitware.com/Bug/view.php?id=15517
     https://public.kitware.com/Bug/view.php?id=15222
     http://public.kitware.com/pipermail/cmake/2016-April/063306.html

Personally I still don't think this needs change.
You don't have to browse all versions of the documentation ... you only
have to work with the documentation that matches the version you
declared in cmake_minimum_required().

Nils
--

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:
http://public.kitware.com/mailman/listinfo/cmake
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Nils Gladitz-2
On 11/08/2016 03:11 PM, Dvir Yitzchaki wrote:

> But how do you know which version to declare on cmake_minimum_required?
> If this feature will be added it won't be far from writing a script that scans the commands you use and outputs the first appropriate version.
>

Strictly speaking cmake_minimum_required(VERSION) is not about command
availability but rather about behavior (cmake policies).
CMake does not diagnose or prevent use of commands that were introduced
after the current policy version.

No automation can detect which behaviors you might expect or require
based on the commands you are using.

I'd start by requesting the highest possible version I could justify
(e.g. based on availability on target platforms and user convenience)
and then start from there.
For existing projects policy warnings help migrating to newer behaviors
and versions as they become available / justifiable.

Nils
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

CMake mailing list
In reply to this post by Dvir Yitzchaki
On 08-Nov-16 22:11, Dvir Yitzchaki wrote:
> But how do you know which version to declare on cmake_minimum_required?
I do hit this too. This would be a very useful feature. Sometimes I have
to manually "scan" the docs to figure out some simple facts about newly
introduces variables/commands.


On 08-Nov-16 22:22, Nils Gladitz wrote:

> On 11/08/2016 03:11 PM, Dvir Yitzchaki wrote:
>
>> But how do you know which version to declare on cmake_minimum_required?
>> If this feature will be added it won't be far from writing a script
>> that scans the commands you use and outputs the first appropriate
>> version.
>>
>
> Strictly speaking cmake_minimum_required(VERSION) is not about command
> availability but rather about behavior (cmake policies).
Except it's exactly opposite :) `cmake_minimum_required` is about new
features/commands, and policies is about behavior. If you have command
`if(IN_LIST)` since 3.3 you can't manipulate policies in such way that
it will work with CMake 2.8. However if you have warning about policy
CMP0054 (since CMake 3.2) you can set policy to old without changing
`cmake_minimum_required` (hence without forcing your CMake 2.8 users to
upgrade to CMake 3.2).

Ruslo
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Nils Gladitz-2
On 11/08/2016 04:17 PM, Ruslan Baratov wrote:

> On 08-Nov-16 22:22, Nils Gladitz wrote:
>> Strictly speaking cmake_minimum_required(VERSION) is not about command
>> availability but rather about behavior (cmake policies).
> Except it's exactly opposite :) `cmake_minimum_required` is about new
> features/commands, and policies is about behavior.

I don't agree and you can not separate the two.
cmake_minimum_required() initializes the policies based on the given
version.

>   If you have command
> `if(IN_LIST)` since 3.3 you can't manipulate policies in such way that
> it will work with CMake 2.8. However if you have warning about policy
> CMP0054 (since CMake 3.2) you can set policy to old without changing
> `cmake_minimum_required` (hence without forcing your CMake 2.8 users to
> upgrade to CMake 3.2).

Coincidentally I implemented both of those policies :)

Given your second example you likely shouldn't be touching the policy at
all.

A policy warning does not force your users to use a new CMake version.
In fact all that setting it to OLD does is suppress the warning.
CMake will use the old behavior in either case.

The warnings guide developers when they do bump their
cmake_minimum_required(VERSION).
By just suppressing it behavior changes might go unnoticed when the bump
does happen.

Nils
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Albrecht Schlosser
In reply to this post by Nils Gladitz-2
On 08.11.2016 15:22 Nils Gladitz wrote:
> On 11/08/2016 03:11 PM, Dvir Yitzchaki wrote:
>
>> But how do you know which version to declare on cmake_minimum_required?
>> If this feature will be added it won't be far from writing a script
>> that scans the commands you use and outputs the first appropriate
>> version.

I'd also like such an addition to the documentation for reasons
discussed below.

> Strictly speaking cmake_minimum_required(VERSION) is not about command
> availability but rather about behavior (cmake policies).
[...]
> I'd start by requesting the highest possible version I could justify
> (e.g. based on availability on target platforms and user convenience)
> and then start from there.

And that's exactly the (my) point. How can I find out the "highest
possible version I could justify"?

I'm a developer of a public GUI library (FLTK). In this position you
don't know anything about the availability of CMake versions on your
target platforms. Our intention is to keep cmake_minimum_required() as
low as possible.

That said, whenever you change a CMakeLists.txt file you should be aware
if the commands you use are compatible with the CMake version you
"require". There should be an easy way to find out in which version a
particular CMake command has been introduced. Only with this information
you can decide if you should use this fine command or better find
another way to do the task you're going to do.

I'd like to have a list of release dates (I'm not sure if there is one)
as well as the exact version a feature was introduced to write
CMakeLists.txt files that run on really old CMake versions.

Note: currently we have cmake_minimum_required(VERSION 2.6.3) (sic!),
but we also have conditional code for some higher CMake versions:

if(CMAKE_VERSION VERSION_GREATER 2.8.4) ...
if(NOT CMAKE_VERSION VERSION_LESS 3.0.0) ...

I'd appreciate such additions very much to be able to write more
portable CMake files. TIA.

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Eric Noulard


2016-11-08 20:26 GMT+01:00 Albrecht Schlosser <[hidden email]>:
On 08.11.2016 15:22 Nils Gladitz wrote:
On 11/08/2016 03:11 PM, Dvir Yitzchaki wrote:

But how do you know which version to declare on cmake_minimum_required?
If this feature will be added it won't be far from writing a script
that scans the commands you use and outputs the first appropriate
version.

I'd also like such an addition to the documentation for reasons discussed below.


I think the need is recognized by most CMake user but...
 


Strictly speaking cmake_minimum_required(VERSION) is not about command
availability but rather about behavior (cmake policies).
[...]
I'd start by requesting the highest possible version I could justify
(e.g. based on availability on target platforms and user convenience)
and then start from there.

And that's exactly the (my) point. How can I find out the "highest possible version I could justify"?

I'm a developer of a public GUI library (FLTK). In this position you don't know anything about the availability of CMake versions on your target platforms. Our intention is to keep cmake_minimum_required() as low as possible.

That said, whenever you change a CMakeLists.txt file you should be aware if the commands you use are compatible with the CMake version you "require". There should be an easy way to find out in which version a particular CMake command has been introduced. Only with this information you can decide if you should use this fine command or better find another way to do the task you're going to do.

I'd like to have a list of release dates (I'm not sure if there is one) as well as the exact version a feature was introduced to write CMakeLists.txt files that run on really old CMake versions

Some time ago people came up (dig the ML for the related discussion) with compatibility matrix idea:

And it finally ends with cmake 3.0.0
 
Note that this is far more complicated than simply listing when one command appears because some command may get more options, or change their default semantic
(using POLICY etc..) so the feature granularity leads to question like

When did the 'string' cmake command support the UUID argument ?

Before which version of CMake does get_target_property accept  non-existent target argument without issuing any error or warning ?
(see POLICY CMP0045)

So basically, tracking all kind of behavior change is not as easy as it seems.

How can we document the changes ? Or better extract them from the code or documentation?

--
Eric

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Craig Scott-3
Rather than trying to do everything, perhaps there's value in tackling this in stages. At a high level, simply knowing in which CMake version a particular command, property, variable or module was added is a good start. From there, if a command, etc. gained new options, then a note could be added with the text specific to that option to indicate when it was added. Obviously the more fine grained you go, the more time consuming and onerous it would become, but how about just starting with the coarse level? That already provides a big improvement over the current alternative of wading through past versions of documentation and/or source code.

I'd also recommend that such version details be part of the actual CMake docs. While the separate compatibility matrix on the wiki is/was a useful resource, by not having it part of the CMake sources/docs, it is inherently a separate effort to try to keep it up to date with each CMake release. Making it part of CMake itself would seem to encourage documenting version details as part of the same merge requests, etc. that add/change things.

I'll go out on a limb here and suggest that if a clear guideline was given for how version details should be documented, then the community itself would likely work towards populating that information over time. I don't think there is a (realistic) expectation that Kitware would do all the heavy lifting here.



On Wed, Nov 9, 2016 at 8:23 AM, Eric Noulard <[hidden email]> wrote:


2016-11-08 20:26 GMT+01:00 Albrecht Schlosser <[hidden email]>:
On 08.11.2016 15:22 Nils Gladitz wrote:
On 11/08/2016 03:11 PM, Dvir Yitzchaki wrote:

But how do you know which version to declare on cmake_minimum_required?
If this feature will be added it won't be far from writing a script
that scans the commands you use and outputs the first appropriate
version.

I'd also like such an addition to the documentation for reasons discussed below.


I think the need is recognized by most CMake user but...
 


Strictly speaking cmake_minimum_required(VERSION) is not about command
availability but rather about behavior (cmake policies).
[...]
I'd start by requesting the highest possible version I could justify
(e.g. based on availability on target platforms and user convenience)
and then start from there.

And that's exactly the (my) point. How can I find out the "highest possible version I could justify"?

I'm a developer of a public GUI library (FLTK). In this position you don't know anything about the availability of CMake versions on your target platforms. Our intention is to keep cmake_minimum_required() as low as possible.

That said, whenever you change a CMakeLists.txt file you should be aware if the commands you use are compatible with the CMake version you "require". There should be an easy way to find out in which version a particular CMake command has been introduced. Only with this information you can decide if you should use this fine command or better find another way to do the task you're going to do.

I'd like to have a list of release dates (I'm not sure if there is one) as well as the exact version a feature was introduced to write CMakeLists.txt files that run on really old CMake versions

Some time ago people came up (dig the ML for the related discussion) with compatibility matrix idea:

And it finally ends with cmake 3.0.0
 
Note that this is far more complicated than simply listing when one command appears because some command may get more options, or change their default semantic
(using POLICY etc..) so the feature granularity leads to question like

When did the 'string' cmake command support the UUID argument ?

Before which version of CMake does get_target_property accept  non-existent target argument without issuing any error or warning ?
(see POLICY CMP0045)

So basically, tracking all kind of behavior change is not as easy as it seems.

How can we document the changes ? Or better extract them from the code or documentation?

--
Eric

--

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:
http://public.kitware.com/mailman/listinfo/cmake



--
Craig Scott
Melbourne, Australia

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Nils Gladitz-2
In reply to this post by Albrecht Schlosser
On 08.11.2016 20:26, Albrecht Schlosser wrote:

> On 08.11.2016 15:22 Nils Gladitz wrote:
>
>> Strictly speaking cmake_minimum_required(VERSION) is not about command
>> availability but rather about behavior (cmake policies).
> [...]
>> I'd start by requesting the highest possible version I could justify
>> (e.g. based on availability on target platforms and user convenience)
>> and then start from there.
>
> And that's exactly the (my) point. How can I find out the "highest
> possible version I could justify"?
>
> I'm a developer of a public GUI library (FLTK). In this position you
> don't know anything about the availability of CMake versions on your
> target platforms. Our intention is to keep cmake_minimum_required() as
> low as possible.
>

If you are intending to keep the required version as low as possible
you'll already have a justification / reason for doing so.
I can only assume that the reason is that you need to support ancient
platforms which ship equally ancient versions of CMake and you don't
want to bother your users to build or install custom newer versions of
CMake.

It doesn't matter what your reasons or justifications for it are (though
I would hope they are valid and verified) but you have to decide on a
minimum version that you can life with in the end.

> That said, whenever you change a CMakeLists.txt file you should be
> aware if the commands you use are compatible with the CMake version
> you "require". There should be an easy way to find out in which
> version a particular CMake command has been introduced. Only with this
> information you can decide if you should use this fine command or
> better find another way to do the task you're going to do.

At this point you only have to refer to the documentation that actually
corresponds to the version you decided to require.
You'll only find commands and behaviours in that documentation that'll
actually be available in your minimum version.
You will not find commands or behaviours that are unavailable in your
version so you will not be tempted to use them nor will you have to
asses them individually for their availability.

>
> I'd like to have a list of release dates (I'm not sure if there is
> one) as well as the exact version a feature was introduced to write
> CMakeLists.txt files that run on really old CMake versions.
>

I think the git tag creation dates should roughly equate release dates:
     https://cmake.org/gitweb?p=cmake.git;a=tags

> Note: currently we have cmake_minimum_required(VERSION 2.6.3) (sic!),
> but we also have conditional code for some higher CMake versions:

2.6.3's tag e.g. "Sat, 21 Feb 2009 19:43:45 +0000 (14:43 -0500)" would
be over 7 years old now.

>
> if(CMAKE_VERSION VERSION_GREATER 2.8.4) ...
> if(NOT CMAKE_VERSION VERSION_LESS 3.0.0) ...
>

There are exceptions to every rule but I'd personally avoid or at least
try to minimize such constructs if possible.

CMake's policy mechanism tries hard to preserve old behaviours so that
existing projects depending on those old behaviours don't break with new
versions of CMake.
Given your minimum required version CMake 3.7 will still mostly try to
behave like 2.6.3.

With constructs like these this is no longer the case and you need an
increasing number of CMake versions to get proper coverage.
Developers that use one specific version of CMake can not longer be
reasonably confident that their CMake script changes also work on other
versions of CMake covered by distinct version specific conditionals.

Nils
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Albrecht Schlosser
In reply to this post by Eric Noulard
On 08.11.2016 22:23 Eric Noulard wrote:
>
> 2016-11-08 20:26 GMT+01:00 Albrecht Schlosser <...>:
>
>     I'd also like such an addition to the documentation for reasons
>     discussed below.
>
>
>
> I think the need is recognized by most CMake user but...

okay...

>         Strictly speaking cmake_minimum_required(VERSION) is not about
>         command
>         availability but rather about behavior (cmake policies).
>
>     [...]
>
>         I'd start by requesting the highest possible version I could justify
>         (e.g. based on availability on target platforms and user
>         convenience)
>         and then start from there.
>
>
>     And that's exactly the (my) point. How can I find out the "highest
>     possible version I could justify"?
>
>     I'm a developer of a public GUI library (FLTK). In this position you
>     don't know anything about the availability of CMake versions on your
>     target platforms. Our intention is to keep cmake_minimum_required()
>     as low as possible.
>
>     That said, whenever you change a CMakeLists.txt file you should be
>     aware if the commands you use are compatible with the CMake version
>     you "require". There should be an easy way to find out in which
>     version a particular CMake command has been introduced. Only with
>     this information you can decide if you should use this fine command
>     or better find another way to do the task you're going to do.
>
>     I'd like to have a list of release dates (I'm not sure if there is
>     one) as well as the exact version a feature was introduced to write
>     CMakeLists.txt files that run on really old CMake versions
>
>
> Some time ago people came up (dig the ML for the related discussion)
> with compatibility matrix idea:
> https://cmake.org/Wiki/CMake_Version_Compatibility_Matrix
> http://public.kitware.com/pipermail/cmake/2010-December/041202.html
>
> And it finally ends with cmake 3.0.0
> http://public.kitware.com/pipermail/cmake/2015-March/059983.html
>
> Note that this is far more complicated than simply listing when one
> command appears because some command may get more options, or change
> their default semantic
> (using POLICY etc..) so the feature granularity leads to question like
>
> When did the 'string' cmake command support the UUID argument ?
>
> Before which version of CMake does get_target_property
> accept  non-existent target argument without issuing any error or warning ?
> (see POLICY CMP0045)
>
> So basically, tracking all kind of behavior change is not as easy as it
> seems.

Sure, I agree. Thanks for your elaborate comments.

> How can we document the changes ? Or better extract them from the code
> or documentation?

A simple comment like "since 3.5.0" for the _first_ appearance of a
command would be very helpful. Added keywords could be commented as well.

I see that behavior changes would be more difficult to document, but
documentation of policies seem to do a good job in their particular cases.

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Albrecht Schlosser
In reply to this post by Nils Gladitz-2
On 08.11.2016 23:01 Nils Gladitz wrote:

> On 08.11.2016 20:26, Albrecht Schlosser wrote:
>>
>> I'm a developer of a public GUI library (FLTK). In this position you
>> don't know anything about the availability of CMake versions on your
>> target platforms. Our intention is to keep cmake_minimum_required() as
>> low as possible.
>>
>
> If you are intending to keep the required version as low as possible
> you'll already have a justification / reason for doing so.
> I can only assume that the reason is that you need to support ancient
> platforms which ship equally ancient versions of CMake and you don't
> want to bother your users to build or install custom newer versions of
> CMake.
>
> It doesn't matter what your reasons or justifications for it are (though
> I would hope they are valid and verified) but you have to decide on a
> minimum version that you can life with in the end.

Basically that's a floating target. We need to evaluate this from time
to time and maybe adjust the required version.

>> That said, whenever you change a CMakeLists.txt file you should be
>> aware if the commands you use are compatible with the CMake version
>> you "require". There should be an easy way to find out in which
>> version a particular CMake command has been introduced. Only with this
>> information you can decide if you should use this fine command or
>> better find another way to do the task you're going to do.
>
> At this point you only have to refer to the documentation that actually
> corresponds to the version you decided to require.
> You'll only find commands and behaviours in that documentation that'll
> actually be available in your minimum version.

Yep, that's simple, of course. But if there is a (new) command you want
to use it would be interesting to know the CMake version it was
introduced to _decide_ if you can or want to do without it or raise the
required version. I'm sure that we will raise the required version when
CMake gets (or got) a new feature we need to use. But we need the facts
to decide...

>> I'd like to have a list of release dates (I'm not sure if there is
>> one) as well as the exact version a feature was introduced to write
>> CMakeLists.txt files that run on really old CMake versions.
>>
>
> I think the git tag creation dates should roughly equate release dates:
>     https://cmake.org/gitweb?p=cmake.git;a=tags

Thanks for this, I appreciate your help.

>> Note: currently we have cmake_minimum_required(VERSION 2.6.3) (sic!),
>> but we also have conditional code for some higher CMake versions:
>
> 2.6.3's tag e.g. "Sat, 21 Feb 2009 19:43:45 +0000 (14:43 -0500)" would
> be over 7 years old now.

As I said: this is a floating target. Since this version is so old we
may decide to require a more recent version in the near future, but
likely not yet 3.7 ;-)

>> if(CMAKE_VERSION VERSION_GREATER 2.8.4) ...
>> if(NOT CMAKE_VERSION VERSION_LESS 3.0.0) ...
>
> There are exceptions to every rule but I'd personally avoid or at least
> try to minimize such constructs if possible.

I think these two are the only special cases, and they are used for new
features we use if available with a fallback (or not at all) if the
CMake version is older.

> CMake's policy mechanism tries hard to preserve old behaviours so that
> existing projects depending on those old behaviours don't break with new
> versions of CMake.
> Given your minimum required version CMake 3.7 will still mostly try to
> behave like 2.6.3.

I'm not very familiar with CMake policies. Maybe I need some more RTFM.

> With constructs like these this is no longer the case and you need an
> increasing number of CMake versions to get proper coverage.
> Developers that use one specific version of CMake can not longer be
> reasonably confident that their CMake script changes also work on other
> versions of CMake covered by distinct version specific conditionals.

Good point, thanks for this as well. But as I said before, these
constructs are only exceptions.

BTW: Thanks to all CMake devs for this great tool!

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

CMake mailing list
In reply to this post by Nils Gladitz-2
On 09-Nov-16 06:01, Nils Gladitz wrote:

> On 08.11.2016 20:26, Albrecht Schlosser wrote:
>
>>
>> I'd like to have a list of release dates (I'm not sure if there is
>> one) as well as the exact version a feature was introduced to write
>> CMakeLists.txt files that run on really old CMake versions.
>>
>
> I think the git tag creation dates should roughly equate release dates:
>     https://cmake.org/gitweb?p=cmake.git;a=tags 

What about the future releases? There was a page
https://cmake.org/Bug/changelog_page.php before but it's no longer valid
as far as I understand.

Ruslo
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

CMake mailing list
In reply to this post by Nils Gladitz-2
On 08-Nov-16 23:33, Nils Gladitz wrote:
On 11/08/2016 04:17 PM, Ruslan Baratov wrote:

On 08-Nov-16 22:22, Nils Gladitz wrote:
Strictly speaking cmake_minimum_required(VERSION) is not about command
availability but rather about behavior (cmake policies).
Except it's exactly opposite :) `cmake_minimum_required` is about new
features/commands, and policies is about behavior.

I don't agree and you can not separate the two.
cmake_minimum_required() initializes the policies based on the given version.
So what? From the user's perspective the "initialization of policies" is like a syntactic sugar so you don't have to write endless `cmake_policy(SET CMP00xx NEW)`. Nothing to do how to deal with them further.


  If you have command
`if(IN_LIST)` since 3.3 you can't manipulate policies in such way that
it will work with CMake 2.8. However if you have warning about policy
CMP0054 (since CMake 3.2) you can set policy to old without changing
`cmake_minimum_required` (hence without forcing your CMake 2.8 users to
upgrade to CMake 3.2).

Coincidentally I implemented both of those policies :)

Given your second example you likely shouldn't be touching the policy at all.
I have to. If my code use features from CMake 2.8 I do set `cmake_minimum_required(VERSION 2.8)`. But some users may have CMake 3.2 installed. Do they must downgrade CMake? Of course not. But if I'm not touching policies there will be warnings around. If I'm good developer I will investigate the root of the warnings and fix them. Actually most of them will be about bugs in my code or dangerous behavior, so it does improve 2.8 too.


A policy warning does not force your users to use a new CMake version.
Well that's what I said.

In fact all that setting it to OLD does is suppress the warning.
It's better than emitting zillion of warnings to the output, right? You can suppress one type and fix another, set TODOs, etc.

CMake will use the old behavior in either case.

The warnings guide developers when they do bump their cmake_minimum_required(VERSION).
By just suppressing it behavior changes might go unnoticed when the bump does happen.
There are 3 components in the equation: the **real** CMake version, the version in `cmake_minimum_required` and the default policies for such version. Can you provide an example of what you mean?

Ruslo

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Nils Gladitz-2
On 09.11.2016 04:29, Ruslan Baratov wrote:
On 08-Nov-16 23:33, Nils Gladitz wrote:
On 11/08/2016 04:17 PM, Ruslan Baratov wrote:

Except it's exactly opposite :) `cmake_minimum_required` is about new
features/commands, and policies is about behavior.

I don't agree and you can not separate the two.
cmake_minimum_required() initializes the policies based on the given version.
So what? From the user's perspective the "initialization of policies" is like a syntactic sugar so you don't have to write endless `cmake_policy(SET CMP00xx NEW)`. Nothing to do how to deal with them further.

You can't simultaneously argue that cmake_minimum_required() isn't about policies (behaviours) and at the same time syntactic sugar for those very same policies.



  If you have command
`if(IN_LIST)` since 3.3 you can't manipulate policies in such way that
it will work with CMake 2.8. However if you have warning about policy
CMP0054 (since CMake 3.2) you can set policy to old without changing
`cmake_minimum_required` (hence without forcing your CMake 2.8 users to
upgrade to CMake 3.2).

Coincidentally I implemented both of those policies :)

Given your second example you likely shouldn't be touching the policy at all.
I have to. If my code use features from CMake 2.8 I do set `cmake_minimum_required(VERSION 2.8)`. But some users may have CMake 3.2 installed. Do they must downgrade CMake? Of course not. But if I'm not touching policies there will be warnings around. If I'm good developer I will investigate the root of the warnings and fix them. Actually most of them will be about bugs in my code or dangerous behavior, so it does improve 2.8 too.

Policy warnings aren't meant to indicate errors in your code but changes in behaviour that will happen if you were to increase your minimum required version.
As such they can often be worked around by using behaviour that is consistent between versions but they are not meant to indicate errors to be fixed.

Instead they are meant to encourage you to embrace the new behaviours and abandon the old (which will require porting work) since the old are by definition deprecated and may be removed in the future (though so far CMake has been very conservative about this).



A policy warning does not force your users to use a new CMake version.
Well that's what I said.

You said you are not forcing your users to upgrade by setting a policy to OLD.
Which implied that not setting the policy to OLD would force your users to upgrade ... which it doesn't.


In fact all that setting it to OLD does is suppress the warning.
It's better than emitting zillion of warnings to the output, right? You can suppress one type and fix another, set TODOs, etc.

Policy warnings are intended to encourage you to switch to new behaviours since the old ones are deprecated.
In actively maintained projects they are not meant to be suppressed.


CMake will use the old behavior in either case.

The warnings guide developers when they do bump their cmake_minimum_required(VERSION).
By just suppressing it behavior changes might go unnoticed when the bump does happen.
There are 3 components in the equation: the **real** CMake version, the version in `cmake_minimum_required` and the default policies for such version. Can you provide an example of what you mean?

    cmake_minimum_required(VERSION 3.0)

    set(ONE 1)

    if(1 STREQUAL "ONE")
        message("FOO")
    else()
        message("BAR")
    endif()

This code was designed for 3.0 (as indicated by the cmake_minimum_required(VERSION)) and is meant to output "FOO".
When you use CMake 3.0 that is the behaviour you get (without warnings).
When you use CMake >= 3.1 the behaviour of the code itself is still the same but you will get a CMP0054 warning telling you that the behaviour that you currently depend on in if() has been deprecated.

Now you decide to bump your minimum required version from 3.0 to 3.1 and ignore or suppress the policy warning from before:

    cmake_minimum_required(VERSION 3.1)

    set(ONE 1)

    if(1 STREQUAL "ONE")
        message("FOO")
    else()
        message("BAR)
    endif()

Now when you use CMake >= 3.1 to run this code you will not get any more warnings but it will also no longer behave like it used to.

It will output "BAR" instead of "FOO".


Nils


--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Nils Gladitz-2
In reply to this post by CMake mailing list
On 09.11.2016 03:47, Ruslan Baratov wrote:
> On 09-Nov-16 06:01, Nils Gladitz wrote:
>> I think the git tag creation dates should roughly equate release dates:
>>      https://cmake.org/gitweb?p=cmake.git;a=tags
> What about the future releases? There was a page
> https://cmake.org/Bug/changelog_page.php before but it's no longer valid
> as far as I understand.

https://gitlab.kitware.com/cmake/cmake/milestones

I wouldn't consider those dates to be anything but very rough estimates
though.

Nils
--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

CMake mailing list
In reply to this post by Nils Gladitz-2
On 09-Nov-16 16:22, Nils Gladitz wrote:
On 09.11.2016 04:29, Ruslan Baratov wrote:
On 08-Nov-16 23:33, Nils Gladitz wrote:
On 11/08/2016 04:17 PM, Ruslan Baratov wrote:

Except it's exactly opposite :) `cmake_minimum_required` is about new
features/commands, and policies is about behavior.

I don't agree and you can not separate the two.
cmake_minimum_required() initializes the policies based on the given version.
So what? From the user's perspective the "initialization of policies" is like a syntactic sugar so you don't have to write endless `cmake_policy(SET CMP00xx NEW)`. Nothing to do how to deal with them further.

You can't simultaneously argue that cmake_minimum_required() isn't about policies (behaviours) and at the same time syntactic sugar for those very same policies.
You're playing with words instead of using arguments.




  If you have command
`if(IN_LIST)` since 3.3 you can't manipulate policies in such way that
it will work with CMake 2.8. However if you have warning about policy
CMP0054 (since CMake 3.2) you can set policy to old without changing
`cmake_minimum_required` (hence without forcing your CMake 2.8 users to
upgrade to CMake 3.2).

Coincidentally I implemented both of those policies :)

Given your second example you likely shouldn't be touching the policy at all.
I have to. If my code use features from CMake 2.8 I do set `cmake_minimum_required(VERSION 2.8)`. But some users may have CMake 3.2 installed. Do they must downgrade CMake? Of course not. But if I'm not touching policies there will be warnings around. If I'm good developer I will investigate the root of the warnings and fix them. Actually most of them will be about bugs in my code or dangerous behavior, so it does improve 2.8 too.

Policy warnings aren't meant to indicate errors in your code but changes in behaviour that will happen if you were to increase your minimum required version.
Policy CMP0038 doesn't agree with you: https://cmake.org/cmake/help/latest/policy/CMP0038.html

As such they can often be worked around by using behaviour that is consistent between versions but they are not meant to indicate errors to be fixed.

Instead they are meant to encourage you to embrace the new behaviours and abandon the old (which will require porting work) since the old are by definition deprecated and may be removed in the future (though so far CMake has been very conservative about this).



A policy warning does not force your users to use a new CMake version.
Well that's what I said.

You said you are not forcing your users to upgrade by setting a policy to OLD.
Yes, like this:

cmake_minimum_required(VERSION 2.8)
project(foo)

if(POLICY CMP0038)
  cmake_policy(SET CMP0038 OLD)
endif()
Now CMake 3.0 users will not see the warning and CMake 2.8 users **don't have to upgrade**.

Which implied that not setting the policy to OLD would force your users to upgrade ... which it doesn't.
No, it doesn't imply this :) Not setting policy to OLD in this case produce warnings that I have to deal with.



In fact all that setting it to OLD does is suppress the warning.
Actually this statement is wrong. Take a look at this example:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.0)
project(foo VERSION 1.2.3)
cmake_policy(SET CMP0038 OLD) # Do not remove this!
add_library(foo foo.cpp)
target_link_libraries(foo foo)
if you remove `cmake_policy(SET CMP0038 OLD)` this example will produce **error**. It may happens when you want to use new **feature** `project(VERSION)` from 3.0, hence you set `cmake_minimum_required(VERSION 3.0)` and simultaneously you have code which produce warning about CMP0038. By setting `cmake_policy(SET CMP0038 OLD)` you suppress the error, i.e. change **behaviour**.

It's better than emitting zillion of warnings to the output, right? You can suppress one type and fix another, set TODOs, etc.

Policy warnings are intended to encourage you to switch to new behaviours since the old ones are deprecated.
In actively maintained projects they are not meant to be suppressed.
Why not? If you're not planning to fix them right now? I'm not saying you have to ignore them, you have to do fixes, but why not suppress and say work on other fixes?



CMake will use the old behavior in either case.

The warnings guide developers when they do bump their cmake_minimum_required(VERSION).
By just suppressing it behavior changes might go unnoticed when the bump does happen.
There are 3 components in the equation: the **real** CMake version, the version in `cmake_minimum_required` and the default policies for such version. Can you provide an example of what you mean?

    cmake_minimum_required(VERSION 3.0)

    set(ONE 1)

    if(1 STREQUAL "ONE")
        message("FOO")
    else()
        message("BAR")
    endif()

This code was designed for 3.0 (as indicated by the cmake_minimum_required(VERSION)) and is meant to output "FOO".
When you use CMake 3.0 that is the behaviour you get (without warnings).
When you use CMake >= 3.1 the behaviour of the code itself is still the same but you will get a CMP0054 warning telling you that the behaviour that you currently depend on in if() has been deprecated.

Now you decide to bump your minimum required version from 3.0 to 3.1 and ignore or suppress the policy warning from before:

    cmake_minimum_required(VERSION 3.1)

    set(ONE 1)

    if(1 STREQUAL "ONE")
        message("FOO")
    else()
        message("BAR)
    endif()

Now when you use CMake >= 3.1 to run this code you will not get any more warnings but it will also no longer behave like it used to.

It will output "BAR" instead of "FOO".

And this code will produce "FOO":

cmake_minimum_required(VERSION 3.1)

cmake_policy(SET CMP0054 OLD) # behave like 3.0

set(ONE 1)

if(1 STREQUAL "ONE")
  message("FOO")
else()
  message("BAR")
endif()
In this example by `cmake_minimum_required(VERSION 3.1)` you telling user that you're planning to use some **feature** from CMake 3.1. This feature may be about interpreting differently `if(1 STREQUAL "ONE")` and `if(1 STREQUAL ONE)` or may be about anything else. Note that CMake 3.0 **has no such feature** and commands  `if(1 STREQUAL "ONE")` /`if(1 STREQUAL ONE)` is same for him always. Policy CMP0054 is about **behaviour**: "how we really should interpret `if(1 STREQUAL "ONE")`"? Yes, `cmake_minimum_required(VERSION 3.1)` set the policy **implicitly** to NEW. But you can control it yourself, like set it to NEW explicitly (which make no sense here but can be done), or set it to OLD.

Ruslo

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

CMake mailing list
In reply to this post by Nils Gladitz-2
On 09-Nov-16 16:22, Nils Gladitz wrote:

> On 09.11.2016 03:47, Ruslan Baratov wrote:
>> On 09-Nov-16 06:01, Nils Gladitz wrote:
>>> I think the git tag creation dates should roughly equate release dates:
>>>      https://cmake.org/gitweb?p=cmake.git;a=tags
>> What about the future releases? There was a page
>> https://cmake.org/Bug/changelog_page.php before but it's no longer valid
>> as far as I understand.
>
> https://gitlab.kitware.com/cmake/cmake/milestones
>
> I wouldn't consider those dates to be anything but very rough
> estimates though.
>
> Nils

Ok, thanks. At least something :)

Ruslo

--

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:
http://public.kitware.com/mailman/listinfo/cmake
Reply | Threaded
Open this post in threaded view
|

Re: Adding Cmake version in online documentation

Nils Gladitz-2
In reply to this post by CMake mailing list
On 09.11.2016 12:04, Ruslan Baratov wrote:
On 09-Nov-16 16:22, Nils Gladitz wrote:
On 09.11.2016 04:29, Ruslan Baratov wrote:
On 08-Nov-16 23:33, Nils Gladitz wrote:
On 11/08/2016 04:17 PM, Ruslan Baratov wrote:

Except it's exactly opposite :) `cmake_minimum_required` is about new
features/commands, and policies is about behavior.

I don't agree and you can not separate the two.
cmake_minimum_required() initializes the policies based on the given version.
So what? From the user's perspective the "initialization of policies" is like a syntactic sugar so you don't have to write endless `cmake_policy(SET CMP00xx NEW)`. Nothing to do how to deal with them further.

You can't simultaneously argue that cmake_minimum_required() isn't about policies (behaviours) and at the same time syntactic sugar for those very same policies.
You're playing with words instead of using arguments.

There was no word play involved.
You say cmake_minimum_required() is not about behaviour yet it initializes all policies which are purely about behaviour.



Policy warnings aren't meant to indicate errors in your code but changes in behaviour that will happen if you were to increase your minimum required version.
Policy CMP0038 doesn't agree with you: https://cmake.org/cmake/help/latest/policy/CMP0038.html
 
No policies are still primarily about behaviour changes. That is true for CMP0038 as well.

The old behaviour is to ignore this issue in user code. The new behaviour is to produce an error.
When maintainers get this warning they are informed that their code will break as soon as they increase their minimum required version.

The same is true for CMP0054. The policy warning did find many errors in user code but the warning is primarily about the change in behaviour.

Yes, like this:

cmake_minimum_required(VERSION 2.8)
project(foo)

if(POLICY CMP0038)
  cmake_policy(SET CMP0038 OLD)
endif()
Now CMake 3.0 users will not see the warning and CMake 2.8 users **don't have to upgrade**.

Yes but I don't see what point you are trying to make ... they didn't have to upgrade without the explicit policy set either.
And the policy warnings aren't meant for users they are meant for maintainers.

In fact all that setting it to OLD does is suppress the warning.
Actually this statement is wrong. Take a look at this example:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.0)
project(foo VERSION 1.2.3)
cmake_policy(SET CMP0038 OLD) # Do not remove this!
add_library(foo foo.cpp)
target_link_libraries(foo foo)
if you remove `cmake_policy(SET CMP0038 OLD)` this example will produce **error**. It may happens when you want to use new **feature** `project(VERSION)` from 3.0, hence you set `cmake_minimum_required(VERSION 3.0)` and simultaneously you have code which produce warning about CMP0038. By setting `cmake_policy(SET CMP0038 OLD)` you suppress the error, i.e. change **behaviour**.

You took this out of context. I was talking about your second example about CMP0054 which was unset by cmake_minimum_required(VERSION 2.8) and then explicitly set to OLD by you.
In this new case you have a policy that is initialized to NEW by cmake_minimum_required(VERSION 3.0) and then set to OLD by you.

Policies are not meant to be feature toggles. You are explicitly asking CMake to use deprecated behaviour (that should no longer be used and might be removed in the future) over new behaviour.


It's better than emitting zillion of warnings to the output, right? You can suppress one type and fix another, set TODOs, etc.

Policy warnings are intended to encourage you to switch to new behaviours since the old ones are deprecated.
In actively maintained projects they are not meant to be suppressed.
Why not? If you're not planning to fix them right now? I'm not saying you have to ignore them, you have to do fixes, but why not suppress and say work on other fixes?

Like I said policies are not primarily about fixing code. They are about migrating to new behaviours introduced by new versions of CMake.


And this code will produce "FOO":

cmake_minimum_required(VERSION 3.1)

cmake_policy(SET CMP0054 OLD) # behave like 3.0

set(ONE 1)

if(1 STREQUAL "ONE")
  message("FOO")
else()
  message("BAR")
endif()
In this example by `cmake_minimum_required(VERSION 3.1)` you telling user that you're planning to use some **feature** from CMake 3.1.

Again I disagree. cmake_minimum_required(VERSION 3.1) tells CMake to behave like 3.1. It does not indicate that you want to use any 3.1 specific features.

This feature may be about interpreting differently `if(1 STREQUAL "ONE")` and `if(1 STREQUAL ONE)` or may be about anything else. Note that CMake 3.0 **has no such feature** and commands  `if(1 STREQUAL "ONE")` /`if(1 STREQUAL ONE)` is same for him always. Policy CMP0054 is about **behaviour**: "how we really should interpret `if(1 STREQUAL "ONE")`"? Yes, `cmake_minimum_required(VERSION 3.1)` set the policy **implicitly** to NEW. But you can control it yourself, like set it to NEW explicitly (which make no sense here but can be done), or set it to OLD.

Again policies are not meant to be feature toggles.
You can do a lot of things and there may be valid use cases but in general policies are not meant to be used this way.
This is made explicit in CMake's documentation on policies.
They exist to preserve backwards compatibility not to pick and choose behaviours.

Nils


--

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:
http://public.kitware.com/mailman/listinfo/cmake
12