As our CMakeLists.txt scripts grow, they risk becoming cluttered and repetitive, just like C++ code without functions. We've seen how target_compile_features and target_include_directories need to be applied to multiple targets. Copying and pasting this logic is not a scalable solution.

The answer, just as in any good programming language, is to modularize our code. CMake provides several mechanisms for this, allowing us to package reusable logic into self-contained units.

This lesson will introduce the three main tools for achieving modularity in CMake:

Functions: To encapsulate logic into reusable commands with their own private scope.
Macros: A simpler alternative to functions that operates in the caller's scope.
Modules: Separate .cmake files that can be loaded into our project to provide functions and macros that can be shared across multiple scripts.

Creating Reusable Logic with Functions

A CMake function is the primary way to bundle a sequence of commands into a single, new command that you can call repeatedly. It's the direct equivalent of a function in C++ or other programming languages.

The basic syntax is:

1function(<FunctionName> [arg1 arg2 ...])
2  # Commands to be executed
3  # Arguments are available as ${arg1}, ${arg2}, etc.
4endfunction()

Let's create a practical example. In our current project, we have to set the C++ standard for every library and executable we create. This is a perfect candidate for a helper function.

Let's create a setup_target() function in our root CMakeLists.txt that takes a target name as an argument and applies our standard C++20 configuration to it.

CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2
3project(Greeter VERSION "1.0")
4
5# Define a reusable function
6function(setup_target target_name) 
7  message(STATUS "Setting C++20 standard for target: ${target_name}") 
8  target_compile_features(${target_name} PUBLIC cxx_std_20) 
9endfunction() 
10
11add_subdirectory(greeter)
12add_subdirectory(app)

This setup_target() function is now available at any point in this CMakeLists.txt file below where it is defined. Bearing in mind how scoping rules work, it will also be available in any "child" CMakeLists.txt file loaded through the add_subdirectory() command.

Let's use this to replace the target_compile_features() calls in our other CMakeLists.txt files with calls to our new function.

greeter/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2add_library(GreeterLib src/Greeter.cpp)
3
4setup_target(GreeterLib) 
5
6target_include_directories(GreeterLib PUBLIC
7  "${CMAKE_CURRENT_SOURCE_DIR}/include"
8)

app/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2add_executable(GreeterApp src/main.cpp)
3
4setup_target(GreeterApp) 
5
6target_link_libraries(GreeterApp GreeterLib)

1cmake ..

1-- Setting C++20 standard for target: GreeterApp
2-- Setting C++20 standard for target: GreeterLib
3-- Configuring done (0.8s)
4-- Generating done (0.1s)
5-- Build files have been written to: D:/Projects/cmake/build

This is already much cleaner. If we decide to move to C++23, we only need to change it in one place: inside our setup_target() function.

Parsing Function Arguments

Beyond simple named arguments, CMake provides several special variables inside a function to handle arguments:

ARGC: The total count of arguments passed.
ARGV: A list of all arguments passed.
ARGN: A list of all arguments after the last named argument. This allows us to replicate the behavior of variadic functions within CMake. Variadic functions are those that accept an unknown number of arguments.

1cmake_minimum_required(VERSION 3.16)
2
3function(handle_list arg1 arg2)
4  message("I was called with ${ARGC} arguments")
5  message("The named parameters are ${arg1} and ${arg2}")
6  message("The additional unnamed parameters are ${ARGN}")
7  message("All parameters: ${ARGV}")
8endfunction()
9
10handle_list(Apple Banana Cherry Potato)

1I was called with 4 arguments
2The named parameters are Apple and Banana
3The additional unnamed parameters are Cherry;Potato
4All parameters: Apple;Banana;Cherry;Potato

For creating functions that take optional keyword arguments, like the PUBLIC argument in a function like target_include_directories(MyTarget PUBLIC ...), the modern approach is to use the cmake_parse_arguments() command.

We will explore this command in a later lesson.

Macro vs. Function: The Scope Difference

At first glance, a CMake macro looks identical to a function. The definition syntax is nearly the same:

1macro(<MacroName> [arg1 arg2 ...])
2  # Commands to be executed
3endmacro()

However, there is one fundamental difference: scope.

A function creates a new scope. Variables defined inside a function are local to that function and are destroyed when the function returns. They do not affect the caller's scope.
A macro does not create a new scope. When you call a macro, its code is effectively expanded and executed directly in the caller's scope. Any variables set or modified inside a macro will alter the state of the calling CMakeLists.txt.

A Demonstration of Scope

Let's see this with a simple experiment:

1cmake_minimum_required(VERSION 3.16)
2
3function(scope_test_func)
4  set(TEST_VAR "Set inside function")
5  message("Inside function: TEST_VAR is ${TEST_VAR}")
6endfunction()
7
8macro(scope_test_macro)
9  set(TEST_VAR "Set inside macro")
10  message("Inside macro: TEST_VAR is ${TEST_VAR}")
11endmacro()
12
13# Call the function and check the variable
14scope_test_func()
15message("After function call: TEST_VAR is '${TEST_VAR}'")
16
17# Call the macro and check the variable
18scope_test_macro()
19message("After macro call: TEST_VAR is '${TEST_VAR}'")

When we configure this project, the output shows the difference:

1Inside function: TEST_VAR is Set inside function
2After function call: TEST_VAR is ''
3Inside macro: TEST_VAR is Set inside macro
4After macro call: TEST_VAR is 'Set inside macro'

The variable set by the function vanished as soon as the function finished. The variable set by the macro persisted and overwrote any existing variable in the parent scope.

When to Use Which?

The scoping behavior dictates the use case:

Use functions by default. Their isolated scope makes them safer and more predictable. They prevent accidental modification of variables in the parent scope, which is a common source of hard-to-find bugs. Functions are for encapsulating a logical sequence of operations.
Use macros only when you explicitly need to modify the parent scope. They are useful for creating short, utility "commands" that need to return a value by setting a variable for the caller.

Modern CMake best practice strongly favors functions over macros.

Returning Values from Functions

CMake functions do not support "returning" values in the traditional sense, but we can accomplish something similar by using a set() command with the PARENT_SCOPE option.

Below, we define a function that accepts the name of an output variable, and then sets a variable with that name in the scope where the function was called:

1function(get_full_name output_var first last)
2  set(${output_var} "${first} ${last}" PARENT_SCOPE)
3endfunction()
4
5get_full_name(my_name "John" "Doe")
6# my_name is now "John Doe"

The PARENT_SCOPE option only allows us to set or update variables in the immediate parent scope - it doesn't let us directly update values in grandparent scopes, or any further up the hierarchy.

So, for example, if we were to call get_full_name() from a CMakeLists.txt file loaded by add_subdirectory(), the invocation would set the variable within the scope of that CMakeLists.txt file, not the file where the function was defined.

In the next chapter, we'll introduce properties, which give us some alternative options over where we store our variable data.

Including External CMake Modules

As our collection of helper functions and macros grows, we don't want to clutter our top-level CMakeLists.txt with them. The solution is to move them into separate files called modules and bring them into our project when needed.

The `include()` Command

The include() command tells CMake to find a .cmake file and execute it in the current scope, much like #include in C++. Once the module is included, all functions and macros defined within it become available for use.

Let's refactor our project by moving our setup_target() function into its own module.

Step 1: Create the Module File

It's a common convention to place project-specific modules in a cmake/ directory at the project root.

cmake/TargetHelpers.cmake

1# This file contains helper functions for setting up targets.
2function(setup_target target_name)
3  message(STATUS
4    "Setting C++20 standard for: ${target_name}"
5  )
6  target_compile_features(${target_name} PUBLIC cxx_std_20)
7endfunction()

Step 2: Include the Module

Now, in our root CMakeLists.txt, we can remove the function definition:

CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2
3project(Greeter VERSION "1.0")
4
5function(setup_target target_name) 
6  message(STATUS
7    "Setting C++20 standard for: ${target_name}"
8  ) 
9  target_compile_features(${target_name} PUBLIC cxx_std_20) 
10endfunction() 
11
12add_subdirectory(greeter)
13add_subdirectory(app)

Instead, files that need this function can load it in using an include() command:

greeter/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2include(../cmake/TargetHelpers.cmake)
3
4add_library(GreeterLib src/Greeter.cpp)
5setup_target(GreeterLib)
6target_include_directories(GreeterLib PUBLIC
7  "${CMAKE_CURRENT_SOURCE_DIR}/include"
8)

app/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2include(../cmake/TargetHelpers.cmake)
3
4add_executable(GreeterApp src/main.cpp)
5setup_target(GreeterApp)
6target_link_libraries(GreeterApp GreeterLib)

The behavior is identical, but our root CMakeLists.txt is now cleaner and is back to remaining focused on the high-level project details.

Setting `CMAKE_MODULE_PATH`

When you call include() (or find_package(), which we'll cover later), CMake searches for the specified module in a list of predefined locations. You can add your own directories to this search path by modifying the CMAKE_MODULE_PATH variable.

It's a common pattern to add your project's cmake directory to this path:

CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
3
4project(Greeter VERSION "1.0")
5
6add_subdirectory(greeter)
7add_subdirectory(app)

This means that our modules can now be imported just using their name - we no longer need to provide the path and file extension. For example:

app/CMakeLists.txt

1cmake_minimum_required(VERSION 3.16)
2include(../cmake/TargetHelpers.cmake)
3include(TargetHelpers)
4
5add_executable(GreeterApp src/main.cpp)
6setup_target(GreeterApp)
7target_link_libraries(GreeterApp GreeterLib)

Third-Party Modules

Our own projects aren't the only source of modules - we don't need to write everything ourselves. As with most ecosystems, there is a large community of third-party libraries that people have already created to solve a wide range of problems.

Much like C++ includes a standard library of useful utilities, CMake itself comes with a large collection of utility modules that provide helpful functions and macros for common tasks. You just need to include() them to use their features.

A simple example is the CMakePrintHelpers module. We've already learned how to print variables using the message() command. This works, but if you want to inspect several variables, the code can get repetitive:

1message("VAR1 = ${VAR1}")
2message("VAR2 = ${VAR2}")
3message("VAR3 = ${VAR3}")

The CMakePrintHelpers module offers a more convenient way to do this with its cmake_print_variables() function.

Let's see how to use it. First, we include() the module. Then, we can call the function it provides, passing the names of all the variables we want to inspect.

1cmake_minimum_required(VERSION 3.16)
2
3# Include the standard CMake module
4include(CMakePrintHelpers) 
5
6set(MY_STRING "Hello")
7set(MY_LIST "a;b;c")
8set(MY_BOOL ON)
9
10# Use the function from the module to print the variables
11cmake_print_variables(MY_STRING MY_LIST MY_BOOL)

When we configure this project, cmake_print_variables() gives us a clean, formatted output showing the name and value of each variable we requested:

1-- MY_STRING="Hello"
2-- MY_LIST="a;b;c"
3-- MY_BOOL="ON"

This is much cleaner and more readable than writing multiple message() calls.

Many common problems, from finding specific compilers to interacting with version control systems, already have solutions in the form of a standard module. You can see the full list of official modules on the CMake site. The awesome-cmake repository on GitHub curates a list of the best community-built resources.

Summary

Modularizing your CMake code is helpful for creating clean, scalable, and maintainable build systems. Just as you refactor C++ code to avoid repetition, you should refactor your complex CMakeLists.txt files.

Functions for Reusable Logic: Use function() to encapsulate sequences of commands. They are the preferred tool because their private scope prevents unintended side effects.
Macros for Scope Modification: Use macro() sparingly, and only when you have a clear need to set or modify a variable in the calling scope.
Modules for Sharing Code: Move your helper functions and macros into separate .cmake files.
include() to Load Modules: Use the include() command to bring your helper modules into a CMakeLists.txt, making their functions available for use.

Modularizing CMake Code

Creating Reusable Logic with Functions

CMakeLists.txt

greeter/CMakeLists.txt

app/CMakeLists.txt

Macro vs. Function: The Scope Difference

A Demonstration of Scope

When to Use Which?

Returning Values from Functions

Including External CMake Modules

The `include()` Command

cmake/TargetHelpers.cmake

CMakeLists.txt

greeter/CMakeLists.txt

app/CMakeLists.txt

Setting `CMAKE_MODULE_PATH`

CMakeLists.txt

app/CMakeLists.txt

Third-Party Modules

Summary

Managing C++ Projects Using CMake

Modularizing CMake Code

Creating Reusable Logic with Functions

CMakeLists.txt

greeter/CMakeLists.txt

app/CMakeLists.txt

Macro vs. Function: The Scope Difference

A Demonstration of Scope

When to Use Which?

Returning Values from Functions

Including External CMake Modules

The include() Command

cmake/TargetHelpers.cmake

CMakeLists.txt

greeter/CMakeLists.txt

app/CMakeLists.txt

Setting CMAKE_MODULE_PATH

CMakeLists.txt

app/CMakeLists.txt

Third-Party Modules

Summary

The `include()` Command

Setting `CMAKE_MODULE_PATH`