CMake Basics

CMake is a cross-platform build system generator tool used to manage the compilation process of C/C++ projects.

By writing CMakeLists.txt configuration files, you can define the project's build rules, dependencies, and compilation options. CMake automatically generates the corresponding platform build files (such as Makefile on Unix or Visual Studio solution on Windows).

CMakeLists.txt File

CMakeLists.txt is the core configuration file of CMake. Every CMake project requires at least one CMakeLists.txt file.

CMake reads the commands in the file to understand the project structure, source file list, and compilation requirements.

Basic Syntax

CMakeLists.txt consists of a series of CMake commands, each in the format:Command name (argument list)。

Below are the most commonly used commands and their examples when building CMake projects.

Specify the minimum CMake version:

Define the project name and language:

Add an executable:

Add a library:

Link libraries to a target:

Set variables:

Specify the header file path for the target:

Set installation rules:

Conditional statements:

Custom commands:

Complete Example

Below is a complete CMakeLists.txt example that uses several of the above directives.

The typical commands to build this project are as follows:

# 在项目根目录下创建 build 目录（推荐外部构建）
$ mkdir build && cd build

# 生成构建文件
$ cmake ..

# 编译项目
$ cmake --build .

# 安装到系统目录（可选）
$ cmake --install .

Variables and Cache

CMake uses variables to store and pass configuration information. Variables can be defined and used in CMakeLists.txt.

Variables are divided into two categories:Normal variablesandCache variables, and their scopes and lifetimes differ.

Normal Variables

Normal variables are defined in CMakeLists.txt, and their scope is the current directory and its subdirectories.

Normal variables are recalculated on each CMake run and are not persisted.

Cache Variables

Cache variables are stored in the CMakeCache.txt file and retain their values across multiple CMake runs.

Cache variables are often used to let users customize build settings during the CMake configuration stage, such as toggling features or specifying installation paths.

Cache variable values are persistent. If you modify the default value of a cache variable in CMakeLists.txt, you need to delete CMakeCache.txt or re-run cmake for the new default to take effect.

Users can modify cache variables via command-line-Dparameters:

# 在 cmake 命令中通过 -D 修改缓存变量
$ cmake .. -DMY_INSTALL_PATH=/opt/example -DENABLE_LOGGING=OFF

Header File Search Paths

In CMake, there are two ways to specify the paths where the compiler looks for header files:include_directories()andtarget_include_directories()。

Understanding the difference between the two is very important for writing clean, maintainable CMake projects.

Comparison of include_directories and target_include_directories

Both can add header file search paths for the compiler, but they differ in scope and level of control.

Meaning of PUBLIC / PRIVATE / INTERFACE

target_include_directories()The key advantage is that the propagation of header file paths can be precisely controlled via visibility keywords.

Finding Libraries and Packages

Many projects depend on external libraries (such as Boost, OpenCV). CMake providesfind_package()commands to automatically detect and configure these external dependencies.

find_package Command

find_package()It searches for libraries installed on the system and sets the corresponding variables (such as header file paths, library file paths, and library target names).

Using the Found Library

find_package()On success, the following are typically provided for use:

Strongly recommended to useImported targetsmethod (e.g., Boost::Boost) rather than manually piecing together header and library paths. Imported targets automatically handle all compilation and linking options, reducing configuration errors.

Example of Using a Third-Party Library

Below is a complete example showing how to introduce and use the Boost library in a CMake project.

Notes

Prefer the target_xxx family of commands.include_directories() and link_directories() are global commands that easily cause path pollution. In large projects, always use target_include_directories() and target_link_libraries(); they make dependencies clearer and easier to maintain.

Always specify the C++ standard.If CMAKE_CXX_STANDARD is not set, the compiler will use the default standard (usually C++98 or C++14, depending on the compiler version). It is recommended to also set CMAKE_CXX_STANDARD_REQUIRED to ON, so that the build fails immediately if the compiler does not support the specified standard.

Understand the difference between PUBLIC / PRIVATE / INTERFACE.Misusing these keywords is the most common pitfall for CMake beginners. Simple way to remember: needed by both self and consumers → PUBLIC; needed only by self → PRIVATE; needed only by consumers (e.g., header-only libraries) → INTERFACE.

Default values of cache variables are not updated automatically.After changing the default value of set(... CACHE ...) in CMakeLists.txt, the existing CMakeCache.txt will not be overwritten. You need to delete the CMakeCache.txt in the build directory, or the entire build directory, and re-run cmake.