CMake 构建系统入门指南

一、为什么需要构建系统

将源代码转化为用户可实际使用的软件，远不止“编译”一步。完整流程通常涉及：编译器调用、链接器配置、头文件路径管理、库依赖解析、测试框架集成、安装打包等环节。当项目规模扩大、目标平台增多时，手工维护这些步骤的成本会急剧上升。

集成开发环境虽然能简化部分流程，但在跨平台开发、持续集成、服务器端构建等场景中，开发者往往无法依赖特定的 IDE 功能。此时，一套与平台无关、可脚本化、可版本控制的构建系统就成为刚需。

CMake 正是为此设计的开源跨平台自动化构建系统。它的核心思路是：不直接构建软件，而是根据源代码与构建参数（通常是 CMakeLists.txt），为目标平台生成本地构建环境所需的配置文件。

这一“生成器”定位带来两个关键优势：

• 平台原生：在 Linux/Unix 下生成 Makefile，在 Windows 下生成 Visual Studio 工程文件，开发者始终使用自己熟悉的原生构建工具。
• 跨平台一致：同一份 CMakeLists.txt 可在多个平台复用，极大降低移植成本。

与同类工具相比，CMake 对 Windows 平台的支持更为完善，同时在简单项目中保持易用性，在大型项目中又具备足够的组织能力。

二、一个最小可运行示例

先看一个最简单的 C++ 程序，功能是计算输入数字的平方根：

// example.cpp
#include <cmath>
#include <cstdlib>
#include <iostream>
#include <string>
int main(int argc, char* argv[]) {
    if (argc < 2) {
        std::cout << "Usage: " << argv[0] << " number" << std::endl;
        return 1;
    }
    const double inputValue = atof(argv[1]);
    const double outputValue = sqrt(inputValue);
    std::cout << "The square root of " << inputValue
              << " is " << outputValue << std::endl;
    return 0;
}

要构建它，只需在同目录下创建 CMakeLists.txt：

cmake_minimum_required(VERSION 3.10)
project(Example)
add_executable(example example.cpp)

这三行分别完成：

1. 声明最低 CMake 版本：避免因版本差异导致行为不一致。
2. 定义项目名称：同时会初始化一系列项目级变量。
3. 声明可执行目标：告诉 CMake 用 example.cpp 生成名为 example 的可执行文件。

标准构建流程如下：

mkdir build && cd build
cmake ..
cmake --build .

推荐使用“源外构建”（out-of-source build），即在与源码分离的目录中执行构建，保持源码目录整洁，也便于管理多套构建配置。

三、核心概念与常用语法

3.1 目标（Target）

CMake 以“目标”为组织核心。常见目标类型包括：

• add_executable()：可执行文件
• add_library()：库（静态库、动态库、接口库等）
• add_custom_target()：自定义任务

目标不仅是构建产物，也是属性（包含路径、编译选项、链接库）的载体。现代 CMake 提倡“以目标为中心”的写法，通过 target_* 系列命令传播使用要求，而非依赖全局变量。

3.2 变量与作用域

set(MY_VAR "value")          # 普通变量
set(MY_LIST a b c)           # 列表
list(APPEND MY_LIST d)       # 追加元素

变量存在目录级与函数级作用域。子目录通过 add_subdirectory() 引入时，会创建新的作用域，父目录变量默认可见，子目录修改变量不会影响父目录（除非使用 PARENT_SCOPE）。

3.3 条件与循环

if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    target_compile_definitions(app PRIVATE DEBUG_MODE)
endif()
foreach(src ${SOURCES})
    message(STATUS "Source: ${src}")
endforeach()

条件表达式支持比较、逻辑运算、文件存在性判断等，是编写可配置构建脚本的基础。

3.4 查找依赖

find_package(Threads REQUIRED)
target_link_libraries(app PRIVATE Threads::Threads)

find_package() 支持两种模式：Module 模式查找 FindXXX.cmake，Config 模式查找库自带的 XXXConfig.cmake。现代第三方库普遍提供 Config 文件，可直接导入目标，简化依赖管理。

四、从单文件到多目标项目

随着项目增长，通常需要拆分库与可执行文件：

cmake_minimum_required(VERSION 3.10)
project(MyApp CXX)
add_library(mylib STATIC
    src/mylib.cpp
)
target_include_directories(mylib PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)
add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE mylib)

关键点：

• PUBLIC 表示包含路径既用于编译 mylib 自身，也传递给链接它的目标。
• PRIVATE 表示链接关系不向使用者传播。
• INTERFACE 用于纯头文件库或仅需传播使用要求的场景。

这种“使用要求传播”机制，使依赖关系自动传递，避免手工维护全局包含路径与链接选项。

五、构建类型与编译选项

CMake 支持多种构建类型，常见的有：

构建类型	含义
Debug	调试信息，无优化
Release	优化，无调试信息
RelWithDebInfo	优化 + 调试信息
MinSizeRel	最小体积优化

可通过命令行指定：

cmake -DCMAKE_BUILD_TYPE=Release ..

也可针对目标设置编译特性：

target_compile_features(mylib PUBLIC cxx_std_17)

这比直接写 -std=c++17 更具可移植性，CMake 会根据编译器自动选择合适选项。

六、安装与导出

构建产物最终需要安装到系统或打包分发。CMake 提供 install() 命令：

install(TARGETS mylib myapp
    RUNTIME DESTINATION bin
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
)
install(DIRECTORY include/ DESTINATION include)

配合 export() 与配置文件生成，还能让其他项目通过 find_package() 直接使用你的库，形成完整的生态闭环。

七、进阶主题概览

• 生成器表达式：如 $<CONFIG:Debug>，在构建时根据配置动态求值，适合编写精细的条件逻辑。
• 函数与宏：封装重复逻辑，函数有独立作用域，宏则原地展开。
• 测试集成：通过 enable_testing() 与 add_test() 接入测试框架。
• 打包：结合 CPack 生成安装包或压缩包。
• 预设与工具链：使用 CMakePresets.json 统一管理常用配置，使用工具链文件实现交叉编译。

八、学习路径建议

1. 动手实践：从本文的最小示例开始，逐步添加库、依赖、安装规则。
2. 阅读官方文档：命令参考与变量说明是最权威的资料。
3. 研读成熟项目：选择一个结构清晰的开源项目，尝试理解其 CMakeLists.txt 的组织方式，例如从解析一个大型数学库的构建脚本入手，观察它如何管理可选依赖、平台差异与安装导出。
4. 持续重构：随着理解加深，将旧式全局变量写法逐步迁移到现代目标导向写法。

九、小结

CMake 的学习曲线主要来自其丰富的命令集与灵活的作用域规则，但核心思想并不复杂：以目标为中心，描述构建什么、依赖什么、如何传播使用要求。掌握这一主线后，再逐步深入生成器表达式、导出配置、交叉编译等进阶能力，就能从容应对从单文件工具到大型跨平台项目的各类构建需求。构建系统是工程能力的基础设施，值得投入时间系统学习。