[CMake] Adding Cmake version in online documentation

[Ruslan Baratov]

On 09-Nov-16 19:51, Nils Gladitz wrote:
> 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.
>From documentation
(https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html):

    The |cmake_minimum_required(VERSION)| command implicitly invokes the
    |cmake_policy(VERSION)|
    <https://cmake.org/cmake/help/latest/command/cmake_policy.html#command:cmake_policy>
    command


So this macro do implicitly invokes the cmake_policy comand:

    macro(printvar a)
      cmake_policy(VERSION 3.0)
      message("Variable a: ${a}")
    endmacro()

Can we said that 'printvar' affect behaviour? Sure! But what is the
point of this statement in the scope of this discussion?

So similar to your statement:

    Strictly speaking cmake_minimum_required(VERSION) is not about command
    availability but rather about behavior (cmake policies).


I can say now:

    Strictly speaking 'printvar' is not about printing variable but
    rather about behavior (cmake policies).

It's hard to argue with this...

>
>>
>>>
>>> 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.
I said that "most of them will be about bugs in my code", so not all of
them about bugs. However you said "warnings aren't meant to indicate
errors" - this statement is wrong, and I have proved it with the link.
The statement that "policies is all about behaviour" is 50% of what I'm
trying to say here.

> When maintainers get this warning they are informed that their code
> will break as soon as they increase their minimum required version.
No, it will not break always because they can control it with policies,
in our case setting policy to OLD will do the trick.

>
> 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.
And why behaviour changed? Because the way how variables interpreted
before CMP0054 was confusing, dangerous and depend on the value of
unrelated variables from the current scope.

>
>> 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.
Originally you said that "Given your second example you likely shouldn't
be touching the policy at all". I describe the example when it make
sense and provide the reasons. If you're not interested about warnings
and your users doesn't report the problems they see, then yes, probably
it's fine for you to not to touch the policies.

>
>>>>> 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(fooVERSION 1.2.3)
>>     cmake_policy(SET CMP0038 OLD) # Do not remove this!
>>     add_library(foofoo.cpp)
>>     target_link_libraries(foofoo)
>>
>> 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.
If you're talking about CMP0054, cmake_minimum_required(VERSION 2.8) and
running it with CMake 3.2 then yes, all it does is only 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.
>> 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.
So what is the deal here? You don't like the word "fix"? Okay, reread it
with 's/fix/apply migration/g'. My point here was about that you can
control different kind of warnings instead of blindly ignoring everything.

>
>>
>> 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.
You can use it like this and it will work, however it doesn't make
sense. What is the point of not using any feature from 3.1 and have
`cmake_minimum_required(VERSION 3.1)`? Why not to set it to
`cmake_minimum_required(VERSION 2.8)` and add some policy modification
commands? Documentation is our friend
(https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html):

    To manage policies without increasing the minimum required CMake
    version, the |if(POLICY)|
    <https://cmake.org/cmake/help/latest/command/if.html#command:if>command
    may be used

    if(POLICYCMP0990)
       cmake_policy(SET CMP0990 NEW)
    endif()


>
>> 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.
>
So can you show an example of "valid" use of `cmake_policy` command?

Ruslo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/cmake/attachments/20161109/a6221a63/attachment-0001.html>