Language Basics

Single Line Comments

  • Like in C++ (well, approximately 🤨)

  • Single-line comments

# message("hello")

message("hello")     # comment

Multiline Comments (“Bracketed Comments”)

  • Start with a hash (“#”), two opening square brackets (“[“), interleaved with any number of equal signs (“=”)

  • Closed with the same pattern, only with closing square brackets (“]”)

#[[
message("this message is commented out")
#]]

  • Nesting of comments possible by varying the number of equal signs

#[[
message("this message is commented out")

#[==[
message("this message is commented out too")
#]==]

#]]

  • Trick: turning multiline nested comments into live code - comment out the comment

##[[         # <--- this is now a single-line comment
message("this message is not commented out anymore")

#[==[
message("this message is still commented out")
#]==]

#]]         # <--- this is now a single-line comment (it lacks its opening counterpart)

Command Execution

  • Command names are case insensitive (arguments are just strings, so sensitivity depends upon what the command wants from them)

  • Arguments are separated by whitespaces

  • Example: command message invoked with two arguments

message("hello" world)
MESSAGE("hello" world)   # same
Message("hello" world)   # same

outputs

...
helloworld
helloworld
helloworld
...

Commands: String Evaluation, And Quoting

  • When are aruments quoted?

  • ⟶ when you want evaluation

  • ⟶ interpolation of variables into them

Different argument type

  • Bracketed arguments

  • Quoted arguments

  • Unquoted arguments

Commands: Bracketed Arguments

  • Passing multiline strings into commands

  • Much like multiline comments

  • Of limited use - pre-formatted text blocks, at most

message([[this is line 1
this is line 2]]
)

# same -->
message([==[this is line 1
this is line 2]==])

  • No string interpolation occurs

bracket-no-evaluate.cmake <code/commands/bracket-no-evaluate.cmake>
set(some_variable "value")

message([[the variable
${some_variable} is not interpolated]])

$ cmake -P bracket-no-evaluate.cmake
the variable
${some_variable} is not interpolated

Commands: Quoted Arguments

  • C-like escape chararcters

    quoted-c-escapes.cmake (download)
    message("*** A Clike linefeed (\\n): >>>\n    separate line\n<<<")
message("*** A C-like double-quote escape: \"")

    $ cmake -P quoted-c-escapes.cmake
*** A Clike linefeed (\n): >>>
    separate line
<<<
*** A C-like double-quote escape: "

  • Multiline strings

    multiline-strings.cmake (download)
    message("This is a multiline string
Second line")

    $ cmake -P multiline-strings.cmake
This is a multiline string
Second line

  • Variable expansion

    variable-expansion.cmake (download)
    set(some_variable "value")
message("Here is the content of \"some_variable\": >>>${some_variable}<<<")

    $ cmake -P variable-expansion.cmake
Here is the content of "some_variable": >>>value<<<

Commands: Unquoted Arguments

Attention

Always Quote Arguments

  • Unquoted arguments, if used correctly, can save a few keystrokes

  • It’s just hard to use unquoted arguments correctly

  • ⟶ Try to always quote your arguments!

  • Correct usage example

    unquoted-arguments-correct.cmake (download)
    set(some_variable "some value")
message(some_variable)
message(${some_variable})
message("${some_variable}")     # <--- MUCH preferred

    $ cmake -P unquoted-arguments-correct.cmake
some_variable
some value
some value

  • List confusion

    Lists are strings that are separated by ; ⟶ what if a string contains ;?

    unquoted-arguments-list.cmake (download)
    set(some_variable "undesired;hello;world")
message(some_variable)
message(${some_variable})
message("${some_variable}")     # <--- MUCH preferred

    $ cmake -P unquoted-arguments-list.cmake
some_variable
undesiredhelloworld
undesired;hello;world