When (if ever) is it okay to use whitespace / indentation in CMake generator expressions? - cmake

Question

The CMake documentation on generator expressions is fairly clear that "A common mistake is to try to split a generator expression across multiple lines with indenting". Here is the example they give:
# WRONG: New lines and spaces all treated as argument separators, so the
# generator expression is split and not recognized correctly.
target_compile_definitions(tgt PRIVATE
$<$<AND:
$<CXX_COMPILER_ID:GNU>,
$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>
>:HAVE_5_OR_LATER>
)
My experience is that using multiple lines with indenting works exactly as I'd hope. For example, the following code produces the exact results I would naively expect with the use of whitespace and indentation:
target_compile_options(common_interface INTERFACE
$<$<CXX_COMPILER_ID:MSVC>:
/W4 # Turn on warnings
/WX # Turn warnings into errors
>
$<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:
-Wall # Turn on warnings
-Wextra # Turn on warnings
-Werror # Turn warnings into errors
>
)
As I understand the CMake documentation, each line here would be added as a separate compile option (e.g., $<$<CXX_COMPILER_ID:MSVC>:), but that is clearly not the case since the generated build files show the flags come through correctly.
My questions are:
What am I missing? Is the issue only with certain types of expressions (e.g., logical operators)? Has the behavior changed and the documentation is out of date? or maybe the documentation needs to be enhanced to clarify the restrictions and expected behavior?
Is it safe to continue using whitespace and indentation in some circumstances?
My suspicion is that the resulting true_string (or false_string in $<IF:condition,true_string,false_string>) of a conditional expression may contain whitespace, but the other arguments of an expression cannot be broken.

Answer 1

Tsyvarev's comments to the question are on the money, but I'll give a more formal answer as both one of the CMake maintainers and the author of the generator expression documentation you linked to. The TLDR version is "The docs describe what you can rely on. Don't rely on implementation details that are outside that and which may change.".
The documentation makes clear where you are required to use quoting to ensure robust behavior. Splitting a genex across multiple lines or whitespace has never been officially supported. Sometimes it might appear to work, but that is by coincidence, not by design. Just because you found a case that happens to work in some range of CMake versions, you shouldn't assume that is supported behavior, especially when the documentation now explicitly calls that out as unsupported. There is no promise that such unsupported behavior will continue to work in future releases.
To be absolutely clear, the direct answers to your questions are:
What am I missing? Is the issue only with certain types of expressions (e.g., logical operators)? Has the behavior changed and the documentation is out of date? or maybe the documentation needs to be enhanced to clarify the restrictions and expected behavior?
The documentation is up to date, and I don't know how to make things clearer than what the existing documentation already says. You're asking about things that go directly against that documentation. The aspects you're asking about are not things we intend to document because they are specifically not intended to be supported behavior! Furthermore, CMake's behavior in this area may well have changed over different versions, but it has never been promised to be stable, since it has never been part of CMake's documented API.
Is it safe to continue using whitespace and indentation in some circumstances?
No. The current documentation should make it very clear what's safe and what isn't. If you're asking if something that contradicts that documentation is safe, well, it should hopefully be clear that my answer is still "No". ;)
Footnote
People failing to quote their generator expressions has been one of the most frequently reported problems (or more accurately, the cause of reported problems) in the CMake forums and issue tracker. It kept biting people over and over, to the point where I wrote a Quoting In CMake blog article about quoting in general and I also added the Whitespace And Quoting section to the generator expressions manual in the official CMake docs (that update appeared with CMake 3.24).