What is the "VERSION" in "cmake_minimum_required(VERSION 3.10)”

Question

I know the meaning of below CMake statement:

cmake_minimum_required(VERSION 3.10)

I am just wondering what the VERSION part is syntactically?

Is it a unquoted argument? If it is an argument, there must be some other argument choices.

But according to here, it seems VERSION is the only choice for the cmake_minimum_required() command.

If so, why do we even need to specify this argument explicitly??

And according to here, this command sets the variable CMAKE_MINIMUM_REQUIRED_VERSION. Is there some kind of string concatenation here? So I can use set_minimum_required(XXX <some_value>) to sent an arbitrary variable with the name CMAKE_MINIMUM_REQUIRED_XXX to <some_value>?

ADD 1

I just tried with below statement in the CMakeLists.txt:

cmake_minimum_required(XXX 123)

And cmake complains that:

CMake Error at CMakeLists.txt:2 (cmake_minimum_required):
  cmake_minimum_required called with unknown argument "XXX".

So it seems to be an argument.

But according to here for the project() command, a similar VERSION string is designated as an option. Seems a bit inconsistent.

ADD 2

I just tried with below statement in the CMakeLists.txt:

cmake_minimum_required(3.10)

And cmake complains that:

CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  cmake_minimum_required called with unknown argument "3.10".

So it seems CMake relies on the VERSION part to properly interpret the "3.10" argument. So I guess the VERSION is also an option here.

And since there's another possible option FATAL_ERROR, it is necessary to have a VERSION option.

So to summarize my current understanding:

The essential paradigm of CMake language is:

CMake commands just manipulate variables based on arguments and options.

Some variables are required to be manipulated and some are optional.

• For required ones, their values are specified through arguments. (kind of like positional argument)

• For optional ones, their values are specified through argument following corresponding options. (kind of like named argument)

ADD 3

From here, for the VERSION in cmake_minimum_required():

The VERSION is a special keyword for this function. And the value of the version follows the keyword.

So here it is called keyword instead of option ...

Add 4

Some feelings about CMake...

Answer 1

I think the input to a CMake command can be classified as 3 types:

1. keyword argument (also called option)

2. positional argument

3. variable arguments (like ... in C)

For 1, Like the VERSION in cmake_minimum_required, whose value follows it immediately. It is called keyword or option.

For 2, Such argument has a formal name and is referenced through that name within the command body.

For 3, the argument can be referenced with ARGV, ARGN, ARGVC.

I also see marker argument somewhere. But I forget where. Horrible syntax...

ADD 1

OK I found the marker argument. It's in the book Mastering CMake by the CMake team:

...while the CMake official document says it's an option:

Search the paths specified by the PATHS option or in the short-hand version of the command. These are typically hard-coded guesses.

What a chaotic wording...

Answer 2

What is the "VERSION" in "cmake_minimum_required(VERSION 3.10)”

I am just wondering what the VERSION part is syntactically?

A string. VERSION. Nothing special.

Is it a unquoted argument?

Yes.

why do we even need to specify this argument explicitly??

To preserve forward compatibility. The idea is that maybe in the feature there will be cmake_minimum_required(DATE 2021-11-03) or similar, for example.

Is there some kind of string concatenation here?

No. It is set explicitly.

So I can use set_minimum_required(XXX <some_value>) to sent an arbitrary variable with the name CMAKE_MINIMUM_REQUIRED_XXX to <some_value>?

No.

Some variables are required to be manipulated and some are optional.

CMake argument parsing is really crude and simple. It's basically in shell pseudocode if $1 == "VERSION" then check_version($2) else error. How you call those strings is really up to your interpretation that depends on the context, in the context of cmake_minimum_required, sure VERSION is a "keyword". Or a "special required argument". Or similar.

All function arguments are strings, and functions compare them to other strings and execute logic upon that. There are no other variable types. Lists are strings, list elements are separated by ; character in a string.

And the implementation of cmake_minimum_required is here: https://gitlab.kitware.com/cmake/cmake/-/blob/master/Source/cmCMakeMinimumRequired.cxx#L29 . Funny, it looks like the parsing is in a loop, so doing cmake_minimum_required(VERSION VERSION VERSION VERSION 3.11) works as fine.