[CMake] Adding Cmake version in online documentation

[Albrecht Schlosser]

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

Basically that's a floating target. We need to evaluate this from time 
to time and maybe adjust the required version.

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

Yep, that's simple, of course. But if there is a (new) command you want 
to use it would be interesting to know the CMake version it was 
introduced to _decide_ if you can or want to do without it or raise the 
required version. I'm sure that we will raise the required version when 
CMake gets (or got) a new feature we need to use. But we need the facts 
to decide...

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

Thanks for this, I appreciate your help.

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

As I said: this is a floating target. Since this version is so old we 
may decide to require a more recent version in the near future, but 
likely not yet 3.7 ;-)

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

I think these two are the only special cases, and they are used for new 
features we use if available with a fallback (or not at all) if the 
CMake version is older.

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

I'm not very familiar with CMake policies. Maybe I need some more RTFM.

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

Good point, thanks for this as well. But as I said before, these 
constructs are only exceptions.

BTW: Thanks to all CMake devs for this great tool!