You can find the code files that are present in this chapter on GitHub at https://github.com/PacktPublishing/Modern-CMake-for-Cpp-2E/tree/main/examples/ch02.

To build the examples provided in this book, always use the recommended commands:

cmake -B <build tree> -S <source tree>
cmake --build <build tree>

Be sure to replace the placeholders <build tree> and <source tree> with appropriate paths. As a reminder: build tree is the path to the target/output directory and source tree is the path at which your source code is located.

Composing CMake code is very much like writing in any other imperative language: lines are executed from top to bottom and from left to right, occasionally stepping into an included file or a called function. The starting point of execution is determined by the mode (see the Mastering the command line section in Chapter 1, First Steps with CMake), either from the root file of the source tree (CMakeLists.txt) or a .cmake script file provided as an argument to cmake.

Since CMake scripts offer extensive support for the CMake language, except for project-related features, we will utilize them to practice CMake syntax in this chapter. Once we become proficient in composing simple listfiles, we can advance to creating actual project files, which we will cover in Chapter 4, Setting Up Your First CMake Project.

As a reminder, scripts can be run with the following command: cmake -P script.cmake.

Variables in CMake are a surprisingly complex subject. Not only are there three categories of variables – normal, cache, and environment – but they also reside in different variable scopes, with specific rules on how one scope affects the other. Very often, a poor understanding of these rules becomes a source of bugs and headaches. I recommend you study this section with care and make sure you understand all of the concepts before moving on.

Let’s start with some key facts about variables in CMake:

• Variable names are case-sensitive and can include almost any character.
• All variables are stored internally as strings, even if some commands can interpret them as values of other data types (even lists!).

The basic variable manipulation commands are set() and unset(), but there are other commands that can alter variable values, such as string() and list().

To declare a normal variable, we simply call set(), providing...

To store a list, CMake concatenates all elements into a string, using a semicolon, ;, as a delimiter: a;list;of;5;elements. You can escape a semicolon in an element with a backslash, like so: a\;single\;element.

To create a list, we can use the set() command:

set(myList a list of five elements)

Because of how lists are stored, the following commands will have exactly the same effect:

set(myList "a;list;of;five;elements")
set(myList a list "of;five;elements")

CMake automatically unpacks lists in unquoted arguments. By passing an unquoted myList reference, we effectively send more arguments to the command:

message("the list is:" ${myList})

The message() command will receive six arguments: “the list is:", “a", “list", “of", “five", and “elements". This may have unintended consequences, as the output will be printed without any additional spaces...

The CMake language wouldn’t be complete without control structures! Like everything else, they are provided in the form of a command, and they come in three categories: conditional blocks, loops, and command definitions. Control structures are executed in scripts and during buildsystem generation for projects.

Conditional blocks

The only conditional block supported in CMake is the humble if() command. All conditional blocks have to be closed with an endif() command, and they may have any number of elseif() commands and one optional else() command in this order:

if(<condition>)
  <commands>
elseif(<condition>) # optional block, can be repeated
  <commands>
else()              # optional block
  <commands>
endif()

As in many other imperative languages, the if()-endif() block controls which sets of commands will be executed:

• If the <condition> expression specified in the if...

CMake offers many scripting commands that allow you to work with variables and the environment. Some of them have been extensively covered in the Appendix: for example, list(), string(), and file(). Others, such as find_file(), find_package(), and find_path(), fit better in chapters that talk about their respective subjects. In this section, we will provide a brief overview of the common commands that are useful in most situations:

• message()
• include()
• include_guard()
• file()
• execute_process()

Let’s get to it.

The message() command

We already know and love our trusty message() command, which prints text to standard output. However, there’s a lot more to it than meets the eye. By providing a MODE argument, you can customize the behavior of the command like so: message(<MODE> "text to print").

The recognized modes are as follows:

• FATAL_ERROR: This stops...

This chapter opened the door to actual programming with CMake – you’re now able to write great, informative comments and utilize built-in commands, and you understand how to correctly provide all kinds of arguments to them. This knowledge alone will help you understand the unusual syntax of CMake listfiles that you might have seen in projects created by others. We have covered variables in CMake – specifically, how to reference, set, and unset normal, cache, and environment variables. We delved into how file and directory variable scopes work, how to create them, and what issues we might encounter and how to solve them. We also covered lists and control structures. We examined the syntax of conditions, their logical operations, the evaluation of unquoted arguments, as well as strings and variables. We learned how to compare values, do simple checks, and examine the state of the files in the system. This allows us to write conditional blocks and while loops...

For more information on the topics covered in this chapter, you can refer to the following links:

• Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin): https://amzn.to/3cm69DD
• Refactoring: Improving the Design of Existing Code (Martin Fowler): https://amzn.to/3cmWk8o
• Which comments in your code ARE GOOD? (Rafał Świdzinski): https://youtu.be/4t9bpo0THb8
• What’s the CMake syntax to set and use variables? (StackOverflow): https://stackoverflow.com/questions/31037882/whats-the-cmake-syntax-to-set-and-use-variables

Join our community on Discord

Join our community’s Discord space for discussions with the author and other readers:

https://discord.com/invite/vXN53A7ZcA