[CMake] Adding Cmake version in online documentation

[Nils Gladitz]

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(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.

>
>>> 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

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