[CMake] Adding Cmake version in online documentation

[Nils Gladitz]

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

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