Modern CMake for C++/

...

/

CMake Language Syntax

CMake Language Syntax

Learn about the syntax of comments, commands, and command arguments in the CMake language.

We'll cover the following...

Comments

Just like in C++, there are two kinds of comments: single-line comments and bracket (multiline) comments. But unlike in C++, bracket comments can be nested. Let's have a look at the syntax of both kinds of comments in the following code snippet:

Press + to interact
# single-line comments start with a hash sign "#"
# they can be placed on an empty line 
message("Hi"); # or after a command like here.
#[=[
    bracket comment
    #[[
        nested bracket comment
    #]]
#]=]

Bracket (multiline) comments get their name from their symbol—they start with an opening square bracket ([), any number of equal (=) signs, and another square bracket: [=[. To close a bracket comment, use the same number of equal signs and reverse the brackets like so: ]=].

Prepending opening bracket tokens with # is optional and allows us to quickly disable a multiline comment by adding another # to the first line of the bracket comment like so:

Press + to interact
##[=[ this is a single-line comment now
    no longer commented
    #[[
        still, a nested comment
    #]]
#]=] this is a single-line comment now

That's a nifty trick, but when and how should we use comments in our CMake file? Since writing listfiles is essentially programming, it is a good idea to bring our best coding practices to them as well. Code that follows such practices is often called clean—a term used over the years by software development gurus like Robert C. Martin, Martin Fowler, and many other authors. What's considered helpful and harmful is often heavily disputed and, as you might guess, comments have not been left out of these debates.

Everything should be judged on a case-by-case basis, but generally agreed-upon guidelines say that good comments provide at least one of the following:

  • Information: They can untangle complexities such as regex patterns or formatting strings.

  • Intent: They can explain the intent of the code when it is unobvious from the implementation or interface.

  • Clarification: They can explain concepts that can't be easily refactored or changed.

  • Warnings of consequences: They can provide warnings, especially around code that can break other things.

  • Amplification: They can underline the ...