我最早接触 CMake 的时候说实话挺抗拒的。平时顺手就能编译的小项目非要弄一个 CMakeLists.txt还要学一堆命令语法总觉得是在给简单事情加负担。直到后来开始接手多模块、跨平台的项目才意识到 CMake 的价值——它解决的根本就不是“编译”问题而是“构建工程如何组织、依赖如何管理、项目如何在不同环境里复现”的问题。这篇内容就围绕 CMake 构建使用展开把我从零开始梳理的使用路线、踩过的坑、排查过的报错一次性讲清楚适合刚入门 CMake 的人通读也适合已经能跑通简单构建、但还被多目录和依赖问题卡住的朋友查漏补缺。1. CMake 到底解决了什么问题1.1 CMake 和 Makefile 的区别很多人问 CMake 和 Makefile 的区别最简单的理解是Makefile 是给 make 这个工具用的构建脚本它描述的是“哪个文件依赖哪个文件、用什么命令把它们变成目标文件”而 CMake 本身并不直接编译代码它生成的是“构建系统文件”这个构建系统文件可以是 Makefile也可以是 Visual Studio 的 .sln还可以是 Ninja 的 build.ninja。也就是说CMake 比 Makefile 高了一层抽象。你写 CMakeLists.txt描述工程结构和构建要求然后 CMake 根据你当前的操作系统、编译器、生成器产出一套对应的原生构建配置。这样同一份 CMakeLists.txt在 Linux 上生成 Makefile在 Windows 上生成 Visual Studio 工程不用改逻辑。举一个直观的例子。一个简单的 Makefile 通常会写死编译器gcc -o app main.c。换到 MSVC 环境下这套写法基本失效你得另写一份。但 CMake 里你只需要写add_executable(app main.c)它会根据当前环境自动选择编译器。这就是“一次编写多环境复用”的意义。当然实际工程没有这么无脑还涉及平台判断、编译器特性检测但是抽象层级的好处就在这——你不需要为每个平台单独维护一套规则。1.2 CMake 的核心思想目标是第一公民CMake 从 3.0 版本开始设计思路发生了很大变化。早期版本大家习惯写全局变量、全局 include 路径日子久了经常出现“一个变量改了整个工程行为变了”的诡异现象。现在的现代 CMake 更强调 target目标所有依赖关系都挂在 target 上。什么叫 target可执行文件是 target静态库是 target动态库也是 target。add_executable和add_library就是在创建 target。创建完之后你可以给这个 target 设置头文件搜索路径、编译选项、链接库、宏定义。别的 target 依赖它时这些属性还能通过target_link_libraries传递。这种设计的好处是依赖关系不再靠“全局路径”来维系而是通过 target 之间的显式链接。工程大了以后这种清晰度能救命。我见过一个旧项目十几个目录共用一个全局include_directories后来新同事加了个同名头文件整个编译链被污染查了整整一天。如果用现代 CMake 的 target 方式组织这个问题根本不会出现。明白了这一点后面学语法会顺畅很多因为你知道每个命令在表达什么不是“往全局塞配置”而是“给某个目标补充信息”。2. 从零准备环境安装、下载与第一个项目2.1 各平台安装 CMake 的方式在 Linux 上CMake 的安装最稳妥的方式是用包管理器但版本往往偏老。比如 Ubuntu 18.04 自带的 CMake 还停留在 3.10 左右老版本对现代 CMake 语法支持不完整很多项目会直接报语法错误。如果遇到这种情况不要纠结直接装新版本。推荐用 pip 安装的方式简单粗暴pip install cmake装完以后检查版本cmake --versionpip 装的 CMake 基本能跟着官方更新走省去手动编译的麻烦。如果你不想用 pip也可以去 CMake 官网下载预编译的二进制包或者用 apt 的kitware-archive源后者是官方维护的 apt 仓库。Windows 上最省心的是去官网下载 Windows 版安装包安装时勾选“Add CMake to the system PATH”。还有个下载镜像的小技巧官网慢的时候可以用国内镜像源具体域名自己搜一下就能找到速度会快不少。装完之后建议在命令行里先敲一遍cmake --version确认环境变量生效别等到项目构建时才发现问题。macOS 用户一般直接用 Homebrewbrew install cmake。2.2 第一个 CMakeLists.txt创建一个测试目录里面放一个main.c#include stdio.h int main(void) { printf(cmake build demo\n); return 0; }然后在同目录创建CMakeLists.txtcmake_minimum_required(VERSION 3.16) project(CmakeDemo C) add_executable(cmake_demo main.c)接着在终端执行cmake -S . -B build cmake --build build-S .指定源码目录-B build指定构建目录。这两行命令的含义是先让 CMake 读取源码里的 CMakeLists.txt在 build 目录里生成构建系统文件再让 CMake 调用底层工具make 或 MSVC完成实际编译。如果一切正常build目录下会出现可执行文件Linux/macOS 下是cmake_demoWindows 下是cmake_demo.exe。运行一下就能看到输出。这里有个新手很容易犯的误区直接在源码目录执行cmake .然后make。这样做会在源码目录里生成一大堆中间文件污染源码。用-B指定独立的 build 目录删除整个 build 目录就可以干净重来这个习惯必须从第一天养成。2.3 命令行还是 CMake GUIWindows 上很多人习惯用 CMake GUI界面长这样上面两栏选源码路径和构建路径中间一大片红色选项框点 Configure 之后会让选生成器再用 Generate 生成工程文件。GUI 的优点是直观适合不熟悉命令行的场景尤其是配合 Visual Studio 的时候先生成 .sln再用 VS 打开。但我个人还是建议把命令行作为主要操作方式。原因很实际命令行可以写进脚本、记录到文档里一键执行GUI 操作步骤很难复现别人拿到你的工程还得自己点一遍。而且报错信息在命令行里更完整排查起来更方便。如果你是纯 Windows 开发者完全可以这样配合用命令行执行cmake -S . -B build生成 VS 工程然后用 Visual Studio 打开 build 目录里的.sln文件继续开发。这样既保留了 VS 的调试体验又让构建配置的逻辑收敛在 CMakeLists.txt 里。3. CMakeLists.txt 核心语法拆解3.1 工程声明cmake_minimum_required 与 project每个 CMakeLists.txt 开头基本固定是这两行cmake_minimum_required(VERSION 3.16) project(MyProject C CXX)cmake_minimum_required指定 CMake 的最低版本目的是防止老版本 CMake 遇到不认识的命令时报出一些莫名其妙的错误。版本号不要太保守也别太激进主流 Linux 发行版的 CMake 版本如果普遍在 3.16 以上就写 3.16除非你明确用了更高版本才有的特性才往上调。project命令除了声明项目名字还可以指定项目用到的语言。这里的语言参数会影响 CMake 去检测对应编译器。例如一个纯 C 项目可以写project(MyProject C)如果混用 C 和 C 就写project(MyProject C CXX)。把不用的语言关掉能减少不必要的配置检查加快 configure 速度。3.2 add_executable 与 add_library一切围绕目标创建可执行文件add_executable(app main.c utils.c)创建库add_library(core STATIC core.c) add_library(shared_math SHARED math.c)STATIC表示静态库SHARED表示动态库。还有一个常用模式是OBJECT库它只编译不打包生成的 .o 文件供其他目标引用在某些需要把同一批源文件拼到多个目标里的场景很好用能避免源文件被重复编译。在写add_executable时有一个小习惯值得养成把源文件列表单独用变量定义而不是全堆在命令里。例如set(CORE_SOURCES src/core.c src/parser.c src/utils.c ) add_library(core STATIC ${CORE_SOURCES})这样后面如果要用条件判断往列表里追加文件操作会非常方便不然你只能去改 add_library 那行。3.3 set、option 与缓存变量set命令用来定义变量set(CMAKE_C_STANDARD 11) set(BUILD_SHARED_LIBS ON)变量在 CMake 里本质是字符串列表也是字符串加分隔符。用${VAR}引用变量用if(DEFINED VAR)来检查变量是否被定义。option专用于定义开关型变量option(ENABLE_TESTS build unit tests ON)这样用户就能在 configure 阶段用命令行覆盖cmake -S . -B build -DENABLE_TESTSOFF这种设计把工程的“可配置项”暴露出来比直接改 CMakeLists.txt 优雅得多。还有一类缓存变量写起来有点坑。set(FOO bar CACHE STRING description)它会写入 CMakeCache.txt下次 configure 时如果用户没有在命令行重新指定缓存里的值会继续生效。新手经常遇到的问题就是改了源码里的set(FOO ...)重新构建却发现行为没变原因就是缓存变量还残留着旧值。解决办法是删掉 build 目录重新 configure或者用cmake -U FOO删掉缓存项。3.4 if/else 与循环让构建逻辑活起来CMake 的if语法接近传统语言if(CMAKE_CXX_COMPILER_ID MATCHES MSVC) message(STATUS using MSVC) elseif(CMAKE_CXX_COMPILER_ID MATCHES GNU) message(STATUS using GCC) else() message(STATUS unknown compiler) endif()注意 CMake 的if对变量名做了一些“智能”处理比如if(MSVC)会隐式检查名为 MSVC 的变量是否为真这在老代码里很常见但阅读性不好。更明确的写法是if(CMAKE_CXX_COMPILER_ID MATCHES ...)或者if(DEFINED ...)。循环用得没那么频繁但foreach和list(APPEND)配合起来很好用foreach(src IN LISTS CORE_SOURCES) message(STATUS source: ${src}) endforeach()这些语法本身不难难的是知道“什么时候该用条件判断”。一个典型场景是Windows 下需要链接 ws2_32 库Linux 下不需要。这时候条件判断就必不可少了if(WIN32) target_link_libraries(app ws2_32) endif()4. 多目录工程的构建组织4.1 add_subdirectory 与顶层/子层分工工程一复杂所有代码堆在根目录肯定不行。常见的组织方式是顶层CMakeLists.txt负责整体配置然后通过add_subdirectory引入子目录。每个子目录有自己的CMakeLists.txt只管自己目录下的内容。目录结构示意project/ ├── CMakeLists.txt ├── src/ │ ├── CMakeLists.txt │ └── main.c └── libs/ ├── CMakeLists.txt └── core.c顶层 CMakeLists.txtcmake_minimum_required(VERSION 3.16) project(MyProject C) set(CMAKE_C_STANDARD 11) add_subdirectory(src) add_subdirectory(libs)子目录里的 CMakeLists.txt 照常定义自己的 target。这种方式的好处是每个目录的职责边界清楚不会出现一个超大 CMakeLists.txt 里堆几千行、找一条配置翻半天的情况。4.2 依赖关系的显式表达子目录里创建的 target 在add_subdirectory之后对顶层可见。比如libs/CMakeLists.txt定义了一个库add_library(core STATIC core.c)那么src/CMakeLists.txt里可以这样引用add_executable(app main.c) target_link_libraries(app PRIVATE core) target_include_directories(app PRIVATE ${PROJECT_SOURCE_DIR}/libs)target_link_libraries(app PRIVATE core)这行的作用不只是链接它还会把 core 的接口属性比如 public 的头文件路径、编译选项传递到 app 上。这里的关键字PRIVATE有三种取值含义如下关键字传递范围PRIVATE仅当前目标使用不传递PUBLIC当前目标和依赖当前目标的目标都能使用INTERFACE当前目标自身不用只传递给依赖者实际项目里最常见的选择是 PRIVATE。比如 app 依赖 corecore 依赖一个第三方库 pthread那 pthread 链接选项写成 PRIVATE表示“只有 core 内部需要”没必要传染给 app。如果你把接口头文件路径写错了作用域最典型的症状是“编译自己通过链接别人的目标时报头文件找不到”。4.3 Debug/Release 与多配置生成器单配置生成器Makefile、Ninja需要通过CMAKE_BUILD_TYPE指定构建类型cmake -S . -B build -DCMAKE_BUILD_TYPERelease注意这个变量必须在 configure 阶段设定不能等到 build 阶段再改。常见的取值是 Debug、Release、RelWithDebInfo、MinSizeRel。Visual Studio 属于多配置生成器不需要CMAKE_BUILD_TYPE而是在cmake --build build --config Release这一步选择配置。这就带来一个差异如果你在 VS 生成器下写set(CMAKE_BUILD_TYPE Release)它其实不会生效因为 VS 工程里所有配置都生成了最终用哪个配置取决于你 build 时传入的--config。理解这个差异很重要。我见过有人从 Linux 切到 Windows 后发现 Debug 和 Release 的宏定义不对折腾很久最后才发现是CMAKE_BUILD_TYPE这条经验在 VS 工程里根本不管用。4.4 编译选项、宏定义与栈大小设置给目标追加编译选项target_compile_options(app PRIVATE -Wall -Wextra)给目标追加宏定义target_compile_definitions(app PRIVATE DEBUG_MODE1)Windows 下的 MSVC 编译选项和 GCC 不一样需要条件判断。如果项目只在 Windows MSVC 环境下跑直接写target_compile_options(app PRIVATE /W4)栈大小设置的实质是给链接器传参数。MSVC 下设置栈大小可以用target_link_optionstarget_link_options(app PRIVATE /STACK:8388608)这里 8388608 对应 8MB是十进制字节数。GCC/Clang 下对应的是-Wl,-z,stack-size8388608或写链接脚本。很多递归算法程序跑着就崩溃不是代码问题而是栈空间不够这种“设置栈大小”的需求在 Visual Studio 工程里通常去属性页里改但在 CMake 里就归target_link_options管。5. 第三方依赖管理find_package 与 FetchContent5.1 find_package 的基本逻辑find_package是使用第三方库最正统的方式。以常见库为例find_package(OpenSSL REQUIRED) target_link_libraries(app PRIVATE OpenSSL::SSL OpenSSL::Crypto)REQUIRED表示这个库必须找到找不到就报错并停止 configure。不带REQUIRED的话找不到也继续走后面代码里你需要自己判断这个包是否存在。注意 find_package 找到的并不一定是系统里的库它背后是一系列查找规则先看CMAKE_PREFIX_PATH指定的路径再看系统默认路径。如果你的库装到了非标准位置需要这样指定cmake -S . -B build -DCMAKE_PREFIX_PATH/opt/mylib这是 find_package 最常见的坑之一明明装了库却报告找不到。原因就是前缀路径没配。5.2 报错The following variables are used in this project这实际上是 CMake 在发现某些变量被使用但值为空或 NOTFOUND 时打印的提示。完整的报错信息长这样CMake Error: The following variables are used in this project, but they are set to NOTFOUND.这条报错背后往往是某个 find_package 或 find_path 没有真正找到目标路径。例如 header-only 的库通常会用一个变量记录头文件路径如果没找到变量值为XXX_INCLUDE_DIR-NOTFOUNDCMake 就会报这个错。排查思路分三步看完整报错里到底是哪个变量 NOTFOUND记下来。回到 CMakeLists.txt 里搜这个变量是在哪里赋值的。如果是find_path或find_package得到的说明查找路径没覆盖到实际安装位置。手动用-DCMAKE_PREFIX_PATH指一下路径或者检查环境变量再重新 configure。这个报错还有一个常见来源你在 CMakeLists.txt 里用${FOO}引用了某个从未被定义的变量虽然 CMake 不会直接说变量不存在但某些工具会把它视为 NOTFOUND。所以检查时也顺便确认变量名有没有拼错。5.3 FetchContent直接拉源码构建依赖有些库没有提供 CMake 配置文件或者版本老到没有 find_package 支持这时候可以考虑FetchContentinclude(FetchContent) FetchContent_Declare( nlohmann_json GIT_REPOSITORY https://github.com/nlohmann/json.git GIT_TAG v3.11.2 ) FetchContent_MakeAvailable(nlohmann_json) target_link_libraries(app PRIVATE nlohmann_json::nlohmann_json)FetchContent 会在 configure 阶段把源码 clone 到本地并直接作为子项目加入构建。这个机制非常适合现代 C 项目的依赖管理但代价是首次构建耗时明显增加而且需要网络能访问到对应仓库。实际使用中有两个问题要提前防版本别用main或master分支必须固定 tag 或 commit hash否则不同时间拉到的代码不一样构建可复现性直接没了。国内网络访问 GitHub 时clone 可能会超时。解决办法是配置FETCHCONTENT_CMAKES_CMAKE_GIT_REPOSITORY或换成镜像仓库地址这个根据实际情况调整。依赖三方的选择原则我讲一句能用find_package优先find_package它走的是系统已安装的库性能和稳定性都更有保障项目里离散的小依赖才考虑用 FetchContent 锁版本。6. 高频报错与构建排查实录6.1 文件为什么还在被编译不参与构建的几种可能有朋友问“某个源文件已经从 add_executable 里移除了构建时还提示它在编译”这种诡异情况我遇到过几次根因基本都是这三个之一找到了旧构建目录。你改了 CMakeLists.txt但 build 目录里的构建系统文件没有重新生成。cmake --build不会自动感知 CMakeLists.txt 里改动这种情况它只会根据 make 依赖关系去部分重跑。改动较深时最稳妥的办法是删掉 build 目录重新 configure。文件被别的目标引用了。你只把它从一个 target 的源文件列表里移除但另一个 target 还在编译它这是最常见的情况。有第三方目录通过 FetchContent 或 add_subdirectory 引入了同一份源文件你在项目里看到的是自己目录里的副本构建的其实是依赖目录里的副本。排查方法在构建输出里找编译命令看它到底在编译哪个路径的文件跟着路径追。6.2 构建缓存残留导致的问题CMakeCache.txt 是 configure 阶段生成的缓存文件里面记录了之前所有的变量值。很多人遇到“改了选项没生效”“改了路径没生效”的问题先别怀疑语法先确认是不是缓存作祟。最彻底的办法是删掉 build 目录重新构建。如果你不想全删也可以指定重新 configure 时覆盖某个变量cmake -S . -B build -DFOObar但如果变量类型是缓存变量或内部变量你得记得用-U FOO先把旧缓存删掉。这个坑在 CI 环境里不明显因为 CI 一般每次都是全新目录反而是本地开发时一个 build 目录用很久问题就来了。我现在个人的习惯是遇到和配置相关的问题二话不说先删 build 目录。虽然重新 configure 花一点时间但至少能排除一个最大的干扰项。6.3 找不到头文件、找不到库的常规解法“fatal error: xxx.h: No such file or directory”基本都能归到路径问题上。顺序排查库安装了吗系统里有没有对应文件。find_package找到变量了吗可以写一行message(STATUS xxx path: ${XXX_INCLUDE_DIR})打印出来确认。target_include_directories 有没有加对路径故意多检查几遍路径拼接${PROJECT_SOURCE_DIR}拼错一个目录层是常见错误。如果是编译过但后来找不到可能是库里用了相对路径换个构建目录就废了。6.4 路径带空格与中文目录的坑Windows 下工程路径带空格的场景非常多。大部分情况下 CMake 能处理但到了某些第三方库或生成规则那里就会出问题。尽量避免把项目放进C:\Users\张三\My Project\这种路径如果绕不开记得在字符串里用引号保护target_include_directories(app PRIVATE ${PROJECT_SOURCE_DIR}/include)CMakeLists.txt 里尽可能给路径加引号不要裸写。这个毛病养成习惯后能省掉很多莫名其妙的“构建失败”。7. 工程化落地从玩具项目到真实项目7.1 用 CMakePresets.json 统一构建配置一个工程如果只是自己本地跑命令行参数随便敲没问题。可一旦要分享给同事或者要上 CI各种-D参数就会变成巨大的心智负担。CMake 3.19 开始正式支持CMakePresets.json可以在项目根目录固化配置。简单的示例{ version: 3, configurePresets: [ { name: dev, displayName: Dev Build, generator: Ninja, binaryDir: ${sourceDir}/build/dev, cacheVariables: { CMAKE_BUILD_TYPE: Debug, CMAKE_EXPORT_COMPILE_COMMANDS: ON } } ], buildPresets: [ { name: dev, configurePreset: dev } ] }保存之后直接cmake --preset dev cmake --build --preset dev别人拿到工程不需要理解复杂的参数一条命令就复现了构建环境。这个文件强烈建议提交到版本库。7.2 导出 compile_commands.json 方便编辑器与排查给 configure 命令加一个变量cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDSON构建目录里会生成compile_commands.json它记录每个源文件的精确编译命令。这东西有两大用途让 clangd、VS Code 的 C/C 插件直接读取得到准确的语法提示和跳转不用手动配置 include 路径。排查诡异编译问题时可以精确看到编译命令里实际包含了哪些宏、哪些头文件路径比瞎猜强太多。Principal一个习惯几乎所有项目我都会开启它属于低投入高回报的配置。7.3 Visual Studio 配合 CMake 的日常开发流在 Windows 上用 Visual Studio 做 CMake 项目有几种打开方式可以选择。一种是先cmake -S . -B build生成.sln然后打开它。这种方式适合历史项目IC 体验和普通 VS 项目完全一致。另一种方式是 Visual Studio 自带的“打开文件夹”功能直接打开源码目录VS 会自己扫描 CMakeLists.txt 并配置。这种方式不用手写-B参数VS 会管理一套缓存目录用起来最省心。缺点是它生成的构建目录不在你的工程目录内找日志文件时需要去 VS 的配置里看实际构建路径。两种方式我都用过。如果你要兼顾命令行脚本更推荐第一种生成 .sln 后既能继续用 VS 开发也能在命令行里cmake --build build --config Release完成打包构建二者互不干扰。7.4 交叉编译与嵌入式场景的构建思路碰到 RK3566 之类的嵌入式板子构建系统本身没折腾明白最后发现缺 WiFi 驱动之类的硬件支持这种情况我见得太多了。交叉编译的核心不是 CMake 有什么特殊命令而是告诉它“我不要用本机的编译器我要用目标平台的编译器”。最标准的做法是设置编译器相关变量cmake -S . -B build \ -DCMAKE_SYSTEM_NAMELinux \ -DCMAKE_C_COMPILERaarch64-linux-gnu-gcc \ -DCMAKE_CXX_COMPILERaarch64-linux-gnu-g \ -DCMAKE_SYSROOT/path/to/sysrootCMAKE_SYSROOT指定目标平台的头文件和库所在目录避免 CMake 探测到主机系统的库导致链接出一堆 x86 的目标文件。交叉编译里遇到的所谓“没有 WiFi 驱动”往往只是根文件系统里缺驱动模块跟 CMake 本身没什么关系。你只需要保证跨编译的产物正确驱动模块是作为内核模块或系统包单独处理的不要混在一起排查。交叉编译建议用 toolchain 文件而不是每次敲一堆-D# toolchain-arm64.cmake set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g) set(CMAKE_SYSROOT /path/to/sysroot)配置时一行搞定cmake -S . -B build -DCMAKE_TOOLCHAIN_FILEtoolchain-arm64.cmake这样做的优势很明显toolchain 文件可以放进版本库团队里谁都能复用同时避免把一堆敏感参数写进命令行历史。8. 一些真实踩坑后的经验总结第一次自己手写 CMakeLists.txt 是在一个只有三个源文件的小工具上当时觉得“搞这么复杂干嘛”。后来这个工具慢慢长到 40 多个目录、上百个 target我回头看那个最初的简单配置发现用 CMake 的最大好处不是第一次构建多顺利而是每一次改动都有迹可循依赖关系在 target 上清楚挂着构建选项固化在预设文件里删掉 build 目录就能得到和 CI 完全一致的构建环境。这里分享几个从实际操作里沉淀下来的习惯不算什么高深技巧但能直接降低日常使用成本。第一所有路径都写带引号的形式不要裸写。第二源文件列表尽量收敛在目录各自的 CMakeLists.txt 里不要让顶层的 list 越来越长。第三日常开发用 Debug 构建出包用 Release 构建两个构建目录分开这样出了问题能最快定位是逻辑问题还是优化引入的问题。第四遇到任何和“配置没生效”“编译用的还是旧文件”相关的怪问题先把 build 目录删了再说这类问题里有一半只是缓存在作怪。关于 CMake 的版本升级建议保持关注大版本更新但也不用跟得太快。真正影响日常使用的是那些现代 CMake 的 target 模型和 preset 能力早点学会直接用比看一遍语法说明有用得多。说白了CMake 不是一门需要背的语言它是一个帮你想清楚工程依赖关系、再把这种关系稳定复现出来的工具。用熟之后你会发现项目结构是什么样的构建系统几乎就是照着那个结构映射过去的到时候 CMakeLists.txt 写起来就跟记笔记一样自然。
