[CMake] Adding Cmake version in online documentation

[Craig Scott]

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