[CMake] Adding Cmake version in online documentation

[Nils Gladitz]

On 08.11.2016 20:26, Albrecht Schlosser wrote:
> On 08.11.2016 15:22 Nils Gladitz wrote:
>
>> 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.
>

If you are intending to keep the required version as low as possible 
you'll already have a justification / reason for doing so.
I can only assume that the reason is that you need to support ancient 
platforms which ship equally ancient versions of CMake and you don't 
want to bother your users to build or install custom newer versions of 
CMake.

It doesn't matter what your reasons or justifications for it are (though 
I would hope they are valid and verified) but you have to decide on a 
minimum version that you can life with in the end.

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

At this point you only have to refer to the documentation that actually 
corresponds to the version you decided to require.
You'll only find commands and behaviours in that documentation that'll 
actually be available in your minimum version.
You will not find commands or behaviours that are unavailable in your 
version so you will not be tempted to use them nor will you have to 
asses them individually for their availability.

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

I think the git tag creation dates should roughly equate release dates:
     https://cmake.org/gitweb?p=cmake.git;a=tags

> Note: currently we have cmake_minimum_required(VERSION 2.6.3) (sic!), 
> but we also have conditional code for some higher CMake versions:

2.6.3's tag e.g. "Sat, 21 Feb 2009 19:43:45 +0000 (14:43 -0500)" would 
be over 7 years old now.

>
> if(CMAKE_VERSION VERSION_GREATER 2.8.4) ...
> if(NOT CMAKE_VERSION VERSION_LESS 3.0.0) ...
>

There are exceptions to every rule but I'd personally avoid or at least 
try to minimize such constructs if possible.

CMake's policy mechanism tries hard to preserve old behaviours so that 
existing projects depending on those old behaviours don't break with new 
versions of CMake.
Given your minimum required version CMake 3.7 will still mostly try to 
behave like 2.6.3.

With constructs like these this is no longer the case and you need an 
increasing number of CMake versions to get proper coverage.
Developers that use one specific version of CMake can not longer be 
reasonably confident that their CMake script changes also work on other 
versions of CMake covered by distinct version specific conditionals.

Nils