[CMake] Adding Cmake version in online documentation

Wed Nov 9 07:48:55 EST 2016

Oops, totally forgot to mention the crux: I happened to be the guy who
apparently was the first to start using continue() - so by the time my
college got to me, we quickly found out the issue. But before the college
hit the problem, I didn't have the vaguest clue that I was typing code that
would require an update of the minimum cmake version.

Honestly, the fact that we don't have some strict policy in our team for
setting version of 3rd parties like CMake, leading to different developers
ending up with different versions, is questionable, yes, of course. It is
the reality however, and my feeling is this is the reality for many more
teams.

Given the copious amount of traffic this issue has generated on this
thread, and in the past(!), it seems no more than reasonable that at least
*something* should happen. I do assume user feedback plays an important
role in deciding where to go with CMake development?

Sincerely,
Jakob

On Wed, Nov 9, 2016 at 1:38 PM, Jakob van Bethlehem <
jsvanbethlehem at gmail.com> wrote:

> +1 for me too - sometime ago a college of mine spend quite some time to
> figure why he couldn't bootstrap our application - turns out he was using
> an (old) CMake version which didn't know about the 'continue' command. The
> error-messages coming out of CMake sometimes help, but more often don't
> really give the correct hint, unless you happen to be one of the local
> CMake gurus.
>
> Sincerely,
> Jakob
>
>
> On Tue, Nov 8, 2016 at 10:33 PM, Craig Scott <craig.scott at crascit.com>
> wrote:
>
>> 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 <eric.noulard at gmail.com>
>> wrote:
>>
>>>
>>>
>>> 2016-11-08 20:26 GMT+01:00 Albrecht Schlosser <AlbrechtS.fltk at online.de>
>>> :
>>>
>>>> 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:
>>> 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.
>>>
>>> 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
>> https://crascit.com
>>
>> --
>>
>> 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
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/cmake/attachments/20161109/f63896cf/attachment.html>