What is the difference between #cmakedefine and #define when used within the context of an input file to configure_file? - cmake

Question

Background
I'm running through the CMake tutorial and found the solution for TODO #10, i.e:
TutorialConfig.h.in
#define Tutorial_VERSION_MAJOR #Tutorial_VERSION_MAJOR#
#define Tutorial_VERSION_MINOR #Tutorial_VERSION_MINOR#
seems to conflict with the manual for the configure_file command
configure_file(
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
FILE_PERMISSIONS ...]
[COPYONLY] [ESCAPE_QUOTES] [#ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an file to an file and substitutes variable
values referenced as #VAR# or ${VAR} in the input file content. Each
variable reference will be replaced with the current value of the
variable, or the empty string if the variable is not defined.
Furthermore, input lines of the form
#cmakedefine VAR ...
will be replaced with either
#define VAR ...
or
/* #undef VAR */
depending on whether VAR is set in CMake to any value not considered a
false constant by the if() command. The "..." content on the line
after the variable name, if any, is processed as above.
in that the #cmakedefine preprocessor directive should be used in the input file an turned into a #define directive in the output file rather than what is done in the solution (using the #define directive in the input file). I tried using the #cmakedefine directive before looking at the solution and it resulted in an undefined _VERSION_MINOR i.e. here is the generated header file:
TutorialConfig.h
#define Tutorial_VERSION_MAJOR 1
/* #undef Tutorial_VERSION_MINOR */
whereas when I use the #define directive within the input file (TutorialConfig.h.in), both Tutorial_VERSION_MAJOR and Tutorial_VERSION_MINOR are defined in the generated header file. i.e.
TutorialConfig.h
#define Tutorial_VERSION_MAJOR 1
#define Tutorial_VERSION_MINOR 0
So what is the difference here and why would one properly grab the defined Tutorial_VERSION_MINOR and another not? Is there specific documentation regarding the #cmakedefine and #cmakedefine01 directives other than what is shown in the configure_file documentation?
Based on a comment received highlighting the following text from the configure_file documentation:
"[...] depending on whether VAR is set in CMake to any value not considered a false constant by the if() command".
I'm wondering if the only difference between using the #cmakedefine and #define directives is just that the #cmakedefine one goes through an if() statement and thus any value of 0 would result in the output header file showing an undefined variable rather than a string of 0 as intended.
cmake version 3.22.1
Minimal Working Example
A full working minimal example below or alternatively can be found here:
tutorial.cxx
#include <cstdlib>
#include <iostream>
#include <string>
#include "TutorialConfig.h"
int main()
{
std::cout << "Version: " << Tutorial_VERSION_MAJOR << "." << Tutorial_VERSION_MINOR << std::endl;
return 0;
}
TutorialConfig.h.in
#define Tutorial_VERSION_MAJOR #Tutorial_VERSION_MAJOR#
#define Tutorial_VERSION_MINOR #Tutorial_VERSION_MINOR#
CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(Tutorial
VERSION 1.0)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)
configure_file(TutorialConfig.h.in
TutorialConfig.h
#ONLY)
add_executable(Tutorial
tutorial.cxx)
target_include_directories(Tutorial
PUBLIC
${PROJECT_BINARY_DIR})
Steps to reproduce this:
from the directory containing the above 3 files (e.g. Step1) make a build directory with mkdir build
cd build
cmake ..
make
./Tutorial and note it prints Version: 1.0 as expected
cd ..
change the #define directives in TutorialConfig.h.in to #cmakedefine, i.e.
TutorialConfig.h.in:
#cmakedefine Tutorial_VERSION_MAJOR #Tutorial_VERSION_MAJOR#
#cmakedefine Tutorial_VERSION_MINOR #Tutorial_VERSION_MINOR#
repeat steps 2-4 and note the compile error:
Step1/tutorial.cxx:8:64: error: ‘Tutorial_VERSION_MINOR’ was not declared in this scope; did
you mean ‘Tutorial_VERSION_MAJOR’?
8 | std::cout << "Version: " << Tutorial_VERSION_MAJOR << "." << Tutorial_VERSION_MINOR << std::endl;
| ^~~~~~~~~~~~~~~~~~~~~~
| Tutorial_VERSION_MAJOR

Answer 1

As Friedrich already mentioned in the comments, CMake is doing exactly what it's documented to do.
You wrote:
project(Tutorial
VERSION 1.0)
, so in the following
#cmakedefine Tutorial_VERSION_MINOR #Tutorial_VERSION_MINOR#
, for the first "Tutorial_VERSION_MINOR", CMake looks at what the value of that CMake variable is, and sees that it is a value considered false by the if() command. Yes- Tutorial_VERSION_MINOR is a CMake variable. See the <PROJECT_NAME>_VERSION_MINOR docs. The specific docs that say 0 is considered as a falsy value in the if() command docs is under the "basic expressions" section:
False if the constant is 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, the empty string, or ends in the suffix -NOTFOUND. Named boolean constants are case-insensitive.
And as the documentation you linked states, #cmakedefine VAR ... is replaced with /* #undef VAR */ when "VAR is set in CMake to any value considered a false constant by the if() command."
seems to conflict with the manual for the configure_file command [...] in that the #cmakedefine preprocessor directive should be used in the input file an turned into a #define directive in the output file rather than what is done in the solution (using the #define directive in the input file)
uhh no. The tutorial just uses the approach that will actually work here. This kind of scenario where you want to create a macro definition with the same name as a CMake variable where the CMake variable might be a CMake-falsy value is the weakness scenario of #cmakedefine that one can avoid by instead using #define and configure_file's variable substitution facilities- namely #VAR# and ${VAR}.
There's nothing special about #define with respect to configure_file. It just treats it like any other text. #cmakedefine, #cmakedefine01 and variable substitution with #VAR# and ${VAR} are the only things configure_file does special things for.