[CMake] Adding Cmake version in online documentation

[Albrecht Schlosser]

On 08.11.2016 22:23 Eric Noulard wrote:
>
> 2016-11-08 20:26 GMT+01:00 Albrecht Schlosser <...>:
>
>     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...

okay...

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

Sure, I agree. Thanks for your elaborate comments.

> How can we document the changes ? Or better extract them from the code
> or documentation?

A simple comment like "since 3.5.0" for the _first_ appearance of a 
command would be very helpful. Added keywords could be commented as well.

I see that behavior changes would be more difficult to document, but 
documentation of policies seem to do a good job in their particular cases.