CMake Advanced Features

Once you have mastered the basics of CMake, advanced features can help you manage the build configuration of complex projects more flexibly.

This article covers six major topics: custom modules, multi-configuration builds, advanced package finding, custom build steps, cross-platform cross-compilation, and target property configuration.

Overall Content Overview:

Custom CMake Modules and Scripts

When multiple CMakeLists.txt files need to repeat the same logic, encapsulating this logic into custom modules can greatly reduce code redundancy.

The essence of custom modules and scripts is to extract commonly used CMake functions, macros, and configurations into separate files for reuse across multiple projects.

Custom CMake Modules

A custom module is a.cmakefile with .cmake as its extension, which defines CMake functions and macros that can be loaded via include().

Creation steps:

Custom module example — MyModule.cmake:

Load and use the module in CMakeLists.txt:

CMAKE_MODULE_PATHis the search path list used by CMake when looking for module files. CMake first searches the built-in module path, and if not found, searches the paths specified by CMAKE_MODULE_PATH.

Using Custom CMake Scripts

Custom scripts are similar to modules, but are typically used to perform configuration operations rather than define reusable functions.

Scripts can be loaded directly with include(), and CMake executes each command in them in order.

Create script file config.cmake:

Invoke the script in CMakeLists.txt:

# 使用绝对路径加载脚本
include(${CMAKE_SOURCE_DIR}/config.cmake)

Build Configurations and Targets

CMake supports managing multiple build configurations (such as Debug and Release) in the same project and defining multiple build targets.

Multi-Configuration Generators

Different CMake generators handle configurations differently.

Such as Visual Studio and XcodeMulti-configuration generatorsallow switching Debug/Release in the same build directory, while Unix Makefiles, etc.Single-configuration generatorsneed to determine the build type at the configuration stage.

Set default configuration in CMakeLists.txt:

# 仅对单配置生成器生效，多配置生成器会忽略此变量
set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Build type")

CMAKE_BUILD_TYPE is only effective for single-configuration generators. If you use Visual Studio, please switch configurations via cmake --build . --config Release or in the IDE.

Build Targets

Multiple build targets can be defined in a CMake project, and each target independently configures compilation options and link dependencies.

This allows you to produce multiple executables or multiple libraries in a single build.

Advanced Finding and Configuration

In addition to basic find_package usage, CMake also supports specifying components, precisely controlling versions, and passing build information through configuration file templates.

Advanced Usage of find_package

COMPONENTSThe keyword allows you to find only specific submodules of a library rather than the entire package.

This is very important for large libraries like Boost—importing on demand avoids linking unneeded components.

Specify search paths (for non-standard installation locations):

# 方式一：通过变量指定根目录
cmake .. -DBOOST_ROOT=/path/to/custom/boost

# 方式二：在 CMakeLists.txt 中预先设置
set(BOOST_ROOT "/path/to/custom/boost")
find_package(Boost REQUIRED COMPONENTS filesystem)

Configuration Files and Build Options

configure_file()The directive can inject the values of CMake variables into code files, enabling configuration information to be passed at compile time.

This is very useful when you need to compile information such as version numbers, build time, etc. into the program.

Create the configuration template file config.h.in:

Configure and generate the header file in CMakeLists.txt:

Use the generated configuration in source files:

// 在 main.cpp 中包含生成的配置文件
#include "config.h"

std::cout << "EXAMPLE Version: " << EXAMPLE_VERSION << std::endl;
std::cout << "Build Type: " << EXAMPLE_BUILD_TYPE << std::endl;

Generating Custom Build Steps

Besides standard compilation and linking, CMake allows you to insert custom operations into the build process, such as code generation, resource copying, and post-build notifications.

Custom Commands

add_custom_command()Used to define a custom command that is executed when a file needs to be updated.

The core concept of this command isdependency-driven— the command executes only when the OUTPUT file does not exist or the DEPENDS file has been updated.

Build-stage trigger command — executes after linking completes:

Custom Targets

add_custom_target()Defines a build target that does not produce an output file, usually used to group multiple custom commands together.

Unless the ALL keyword is used, custom targets will not execute in the default build; you need to explicitly specify the target name.

add_custom_command and add_custom_target differ: the former defines a rule for "how to generate files" and is triggered by dependencies; the latter defines an action target for "what to do" and needs to be explicitly invoked or runs automatically when ALL is used.

Cross-Platform and Cross-Compilation

One of CMake's core advantages is cross-platform support — the same CMakeLists.txt can generate corresponding build files on different operating systems and architectures.

Cross-Platform Builds

CMake automatically detects the compiler and system environment of the current platform and generates matching build files.

You can also explicitly specify target platform information via variables.

Cross-Compilation

Cross compilation refers to compiling programs that run on another architecture (such as ARM) on the current platform (such as x86_64 Linux).

CMake usesa toolchain file (Toolchain File)to specify the compiler, system information, and linker configuration required for cross compilation.

Create a toolchain file toolchain.cmake:

Cross-compile using the toolchain file:

# 配置时通过 -DCMAKE_TOOLCHAIN_FILE 指定工具链文件
mkdir build_arm && cd build_arm
cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain.cmake ..

# 使用生成的 Makefile 编译（将调用 ARM 交叉编译器）
make

The toolchain file must be specified when running cmake for the first time. If CMakeCache.txt already exists, you need to delete the build directory and reconfigure to switch toolchains.

Target Properties and Configuration

CMake allows fine-grained control of compile options, link options, and various properties on a per-target basis, which is the recommended practice in modern CMake.

Target Properties

set_target_properties()Used to set target-level properties, which affect the behavior of the compiler and linker.

In modern CMake, it is recommended to use target_compile_options(), target_compile_definitions(), and target_link_options() instead of set_target_properties(), because they support PUBLIC/PRIVATE/INTERFACE visibility control and make dependencies clearer.

Custom Compile and Link Options

Using the target series of commands allows more precise control over the propagation scope of options.

Notes

CMAKE_BUILD_TYPE is only valid for single-configuration generators.If the project needs to support both Makefile and Visual Studio, do not rely on the value of CMAKE_BUILD_TYPE. Use generator expressions$<$<CONFIG:Debug>:DEBUG_VALUE>to dynamically switch based on the actual configuration.

Prefer the target_xxx series of commands.Although set_target_properties is powerful, it lacks visibility control. In scenarios requiring PUBLIC/PRIVATE/INTERFACE semantics, it is better to use dedicated commands such as target_compile_options.

The toolchain file must be specified on the first cmake invocation.When cross-compiling, re-specifying the toolchain in a directory with an existing CMakeCache.txt may produce an incomplete configuration. Always configure cross-compilation in a clean build directory.

It is recommended to add a prefix to function names in custom modules.Avoid naming conflicts with CMake built-in commands or other modules. For example, use the project name as a prefix: myproject_set_warnings().