CMake Conditionals and Loops

The if() command can also perform comparisons and use logical operators.

Numeric Comparison

EQUAL, LESS, LESS_EQUAL, GREATER, and GREATER_EQUAL interpret our variable as a number, and then behaves in the same way as the C++ operators ==, <, <=, >, and >=.

String Comparison

Variations of these operators that perform string-based comparisons are available in the form of STREQUAL, STRLESS, STRLESS_EQUAL, STRGREATER, and STRGREATER_EQUAL. These perform lexographic (alphabetic) comparisons - for example, "Apple" STRLESS "Banana" is true, as "Apple" is before "Banana" alphabetically.

Version Comparison

For strings representing versions, such as "2.1.9" and "3.2", the operators VERSION_EQUAL, VERSION_LESS, VERSION_LESS_EQUAL, VERSION_GREATER, and VERSION_GREATER_EQUAL are available. "2.9" VERSION_LESS "2.10" is true, as "2.9" is an older version than "2.10".

Logical Operators, Parentheses, and Inversion

We have the usual suite of boolean tools for creating compound expressions:

• AND and OR can be used to combine booleans to create more complex expressions
• We can use () for grouping expressions to control the order of operations
• The NOT keyword behaves in the same way as the C++ ! operator, inverting a true expression to be false, or false to be true.

Here's a more complex example that combines a few of these techniques:

1set(MODE "Debug")
2set(OPTIMIZATION_LEVEL 2)
3
4if((MODE STREQUAL "Debug") AND (OPTIMIZATION_LEVEL LESS 3))
5  message(STATUS "Debug mode with low optimization.")
6endif()

One of the most common uses of if() is to handle platform differences. CMake provides several variables that identify the operating system, such as WIN32, APPLE, and UNIX.

Let's imagine our GreeterLib needs a platform-specific implementation file to get some system information. Our project structure might look like this:

1greeter/
2├─ include/
3│  └─ greeter/
4│     └─ Greeter.h
5├─ src/
6│  ├─ Greeter.cpp
7│  ├─ platform_win.cpp
8│  └─ platform_nix.cpp
9└─ CMakeLists.txt

Our greeter/CMakeLists.txt can use if() to select the correct source file at configure time:

1cmake_minimum_required(VERSION 3.16)
2
3# Start with the common source files
4set(LIB_SOURCES src/Greeter.cpp)
5
6# Conditionally add the platform-specific file
7if(WIN32) 
8  message(STATUS "Using platform_win.cpp")  
9  list(APPEND LIB_SOURCES src/platform_win.cpp) 
10else() 
11  message(STATUS "Using platform_nix.cpp")  
12  list(APPEND LIB_SOURCES src/platform_nix.cpp) 
13endif() 
14
15add_library(GreeterLib ${LIB_SOURCES})
16
17target_include_directories(GreeterLib PUBLIC
18  ${CMAKE_CURRENT_SOURCE_DIR}/include
19)
20
21target_compile_features(GreeterLib PUBLIC cxx_std_20)

1cmake ..

1-- Using platform_win.cpp
2-- Configuring done (0.1s)
3-- Generating done (0.1s)
4-- Build files have been written to: D:/projects/cmake/build

This is the essence of writing portable build scripts. You describe the components you need for each platform, and if() lets you assemble them correctly. When you configure this project on Windows, WIN32 is true, and platform_win.cpp is added. On Linux or macOS, WIN32 is false, and platform_nix.cpp is added instead.

A particularly useful comparison operator is IN_LIST. It provides a clean and readable way to check if a specific item is present within a list. This is often more convenient than using list(FIND) and checking the index.

The syntax is straightforward:

1if(<item> IN_LIST <list_variable>)
2  # ...
3endif()

Let's see a quick example:

1set(ADMIN_USERS "alice" "bob" "charlie")
2set(CURRENT_USER "bob")
3
4if(CURRENT_USER IN_LIST ADMIN_USERS)
5  message(STATUS "User '${CURRENT_USER}' has admin privileges.")
6else()
7  message(STATUS "User '${CURRENT_USER}' is a standard user.")
8endif()

When configured, this script will check if the value of CURRENT_USER exists in the ADMIN_USERS list and print the appropriate message.

1-- User 'bob' has admin privileges.

While if() lets us make decisions, foreach() lets us perform repetitive tasks. It's the primary looping construct in CMake and is almost always used to iterate over the elements of a list.

Basic Syntax

The most common form of the foreach() loop is:

1foreach(loop_variable IN LISTS list_variable)
2  # Commands to execute for each item
3  # Use ${loop_variable} to access the current item
4endforeach()

Let's see it in action with a simple list of strings:

1set(FRUITS Apples Bananas Cherries)
2
3foreach(fruit IN LISTS FRUITS)
4  message(STATUS "I am eating ${fruit}!")
5endforeach()

When you run this, CMake will execute the message() command three times, each time with the fruit variable set to the next item in the FRUITS list.

1-- I am eating Apples!
2-- I am eating Bananas!
3-- I am eating Cherries!

Multiple Lists

As the IN LISTS syntax might suggest, we can provide multiple lists to this construct:

1set(FRUITS Apples Bananas Cherries)
2set(VEGETABLES Onions Carrots)
3
4foreach(food IN LISTS FRUITS VEGETABLES)
5  message(STATUS "I am eating ${food}!")
6endforeach()

A great use case for foreach() is to apply a common configuration to multiple targets without repeating yourself. This follows the DRY (Don't Repeat Yourself) principle and makes your build scripts much more maintainable.

In the following example, we define a TARGETS_TO_UPDATE list with the names of targets we want to apply some common configuration to. We apply this configuration using a foreach() block:

1cmake_minimum_required(VERSION 3.16)
2
3project(Greeter VERSION "1.0")
4
5add_subdirectory(app)
6add_subdirectory(greeter)
7
8# Define a list of all targets in our project
9set(TARGETS_TO_UPDATE 
10  GreeterLib 
11  GreeterApp 
12) 
13
14# Loop over the list and apply common settings
15foreach(target IN LISTS TARGETS_TO_UPDATE) 
16  message(STATUS "Applying common settings to ${target}") 
17  target_compile_features(${target} PUBLIC cxx_std_20) 
18endforeach()

1-- Applying common settings to GreeterLib
2-- Applying common settings to GreeterApp

With this structure, if we add a new target to our project, we only need to add its name to the TARGETS_TO_UPDATE list. It will automatically receive all the common settings, ensuring consistency and saving us from copy-pasting code.

A small flaw here is that we need to know the names of our targets (GreeterLib and GreeterApp) even though those are set in the deeper CMakeList.txt files we're loading using add_subdirectory().

We'll soon learn techniques that will unlock better ways of doing this.

While iterating over lists is the most common use case, foreach() has other forms that can be useful for different scenarios.

Iterating an Inline List

This variant allows you to iterate directly over a set of items provided as arguments to the command, without needing to create a list variable first. It's useful for short, hardcoded collections.

1# No list variable is created beforehand
2foreach(fruit IN ITEMS "Apple" "Banana" "Cherry")
3  message(STATUS "Fruit of the day: ${fruit}")
4endforeach()

This is functionally equivalent to creating a list first (set(FRUITS "A" "B" "C")) but can be more concise for simple cases.

1-- Fruit of the day: Apple
2-- Fruit of the day: Banana
3-- Fruit of the day: Cherry

Iterating from 0 to stop

This foreach(i RANGE n) form iterates over integers from 0 up to (and including) the stop value. It's a convenient way to create a classic for loop. Our variable (which we've called i, in this example) adopts the current iteration number:

1# Loop from 0 to 4
2foreach(i RANGE 4)
3  message(STATUS "Creating temporary file: temp_${i}.txt")
4endforeach()

This will execute the loop body five times, with the i variable taking on the values 0, 1, 2, 3, and 4.

1-- Creating temporary file: temp_0.txt
2-- Creating temporary file: temp_1.txt
3-- Creating temporary file: temp_2.txt
4-- Creating temporary file: temp_3.txt
5-- Creating temporary file: temp_4.txt

Iterating from start to stop

The foreach(i RANGE start stop step) syntax is the most flexible range-based loop, allowing you to specify a starting value and an ending value. We can optionally provide a step value to set how much our variable should be incremented on each iteration, or we can omit that argument to use the default value of 1.

1# Loop from 2 to 10, incrementing by 2 each time
2foreach(num RANGE 2 10 2)
3  message(STATUS "Even number: ${num}")
4endforeach()

This loop will execute with num having the values 2, 4, 6, 8, and 10.

1-- Even number: 2
2-- Even number: 4
3-- Even number: 6
4-- Even number: 8
5-- Even number: 10

Control flow commands transform your CMakeLists.txt from a simple declaration into a powerful script. They allow you to handle complexity, reduce redundancy, and create builds that can adapt to different environments and configurations.

• Conditionals with if(): The if() , elseif(), else(), and endif() blocks are our primary tool for decision-making. You can test variables, compare strings and numbers, and check for platform-specific details like if(WIN32).
• Loops with foreach(): The foreach() and endforeach() block lets you iterate over items in a list. It's perfect for applying the same commands to multiple targets or files, keeping your scripts clean and maintainable.

You now have the core language tools to write sophisticated build scripts. You can create variables, manage persistent options with the cache, group data in lists, and control the flow of execution with conditionals and loops.