[CMake] Adding Cmake version in online documentation

[Ruslan Baratov]

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

>> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/cmake/attachments/20161109/e262e155/attachment-0001.html>