C/C 项目越写越多之后手搓 Makefile 是迟早会让人崩溃的缩进要用 Tab 不能用空格、一个目标依赖写错就静默不重编、跨平台换个编译器又要改一遍规则。我当年从一屋子 .mk 文件里爬出来的时候第一个想法就是——这活儿必须交给工具。而目前最主流的选择就是 CMake。这篇文章想聊的是在 Shell 命令行环境下把 CMake 从安装、写 CMakeLists.txt、到生成构建系统、再到排错和调试的一次完整走通。内容是基础向但我会把每个环节背后为什么这么做也讲清楚适合刚接触 CMake、或者已经被各种网上片段教程绕晕的人。如果你之前只听过 Makefile 和 CMake 的区别或者下载了 CMake 却不知道第一步敲什么命令那这篇文章基本可以当一份操作地图用。我尽量把所有代码块都保持成直接能在 Ubuntu 这类 Linux 终端里跑的状态Windows 下用 VS Code CMake Tools 的场景我也会专门提到。1. 为什么是 CMake从手写 Makefile 到构建系统的分水岭1.1 Makefile 的真实痛点先回到一个根本问题我们为什么需要 CMake很多人第一次接触 C/C 构建都是从 Makefile 开始的。Makefile 本身不复杂规则就是目标、依赖、命令三件套。但项目一旦多起来问题就来了。头文件路径要一条条写-I第三方库要手动指定-L和-lDebug 和 Release 两种编译选项意味着你要维护两套规则。更麻烦的是平台差异Linux 上 gcc 能用Windows 上可能要切到 MSVC而 MSVC 的命令行参数风格和 gcc 完全不一样。你写的 Makefile 越通用条件分支就越复杂最后变成一份谁都不敢动的祖传脚本。我见过不少团队里的 Makefile 是从某个开源项目复制过来改的里面留着别人项目的路径、注释、甚至废弃变量。这不是他们不认真而是 Makefile 本身就没有给你提供抽象的能力——它只是一个规则执行器而不是一个项目描述器。1.2 CMake 不是编译器也不是 Make三个角色的分工要理解 CMake先得把几个角色分清楚。编译器Compiler负责把源代码变成目标文件比如 gcc、clang、MSVC。构建工具Build Tool负责根据依赖关系决定先编译哪个文件、哪些文件需要重新编译比如 make、ninja。而 CMake 是一个构建系统生成器它不做编译也不自己管依赖调度它的工作是读取 CMakeLists.txt 里你对项目的描述然后生成一份当前平台、当前编译器可用的构建系统文件。换句话说你写 CMakeLists.txt 是在描述项目而不是在写执行步骤。你说我有一个可执行程序叫 demo它由 main.c 和 utils.c 组成CMake 就会根据你当前的环境生成对应的 Makefile、Ninja 文件或者 Visual Studio 工程。换平台之后同一份 CMakeLists.txt 可以重新生成不需要你改构建规则。这个抽象层就是 CMake 最大的价值项目描述与底层构建工具解耦。1.3 Makefile 和 CMake 到底有什么区别用一个生活类比Makefile 相当于你直接给搬家工人画了一张家具摆放图每件家具搬到哪、怎么摆都要标清楚CMake 是你只告诉搬家公司我有一张桌子、两把椅子、一个书架剩下怎么装车、怎么搬运、怎么上楼由搬家公司根据你家楼层和楼道宽度自己决定。区别还可以列成一张表对比项MakefileCMake CMakeLists.txt定位直接描述构建规则描述项目结构生成构建规则跨平台基本绑定某类构建工具可在 Linux/Windows/macOS 生成对应工程依赖查找手动写路径和链接参数find_package 自动探测编译选项管理手动维护多套规则按构建类型集中配置第三方库集成痛苦核心优势所以当你看到项目里有CMakeLists.txt而不是 Makefile 时心里就该知道这个项目的构建逻辑是写在描述层里的比直接看 Makefile 要更容易读懂、更容易维护。2. 在 Shell 里装好工具链CMake 安装与命令行基本功2.1 Ubuntu 上装 CMake 3.16 的两条路先解决怎么拥有 CMake的问题。Ubuntu 上最省事的方式是 apt 直接装命令很简单sudo apt update sudo apt install cmake但 apt 仓库里的版本往往偏老。如果你希望装到某个特定版本比如网上教程常提到的 3.16或者你编译的某个库要求最低 CMake 版本那 apt 就不一定行了。我自己遇到过一次项目要求 3.16 以上但 Ubuntu 自带源只有 3.10一跑 configure 就报CMake 3.16 or higher is required。这时候有两条路。第一条是使用 Kitware 官方维护的 apt 仓库安装最新版 CMake。步骤大概是添加 GPG key、添加源、再 apt install。这种方式适合长期使用、想跟随官方更新的场景。第二条是源码编译安装。去 cmake.org 下载源码包或者用 wget 拉对应版本的 tar.gz然后tar -zxvf cmake-3.16.0.tar.gz cd cmake-3.16.0 ./bootstrap make -j$(nproc) sudo make install源码编译 CMake 的好处是版本绝对可控缺点是需要几分钟编译时间。而且要注意bootstrap 阶段 CMake 还没有生成最终的构建系统它本身也需要一个 C 编译器在场所以你得确保 gcc/g 已经装好。另外装完之后建议cmake --version确认一下版本如果发现还是旧版多半是/usr/local/bin和/usr/bin的 PATH 顺序问题which cmake看一下路径就能定位。2.2 第一次在 Shell 里跑通 CMake用 HelloWorld 验证装好之后先在终端里验证工具链是否完整。写一个最简单的 C 文件// hello.c #include stdio.h int main(void) { printf(Hello CMake\n); return 0; }再写一个最小的 CMakeLists.txtcmake_minimum_required(VERSION 3.10) project(Hello) add_executable(hello hello.c)然后在 Shell 里执行cmake -S . -B build cmake --build build ./build/hello解释一下这两条命令。-S .表示源目录是当前目录-B build表示构建目录是 build 文件夹。CMake 会在 build 目录里生成 Makefile 和一堆中间文件但绝不污染你的源码目录。这也是 CMake 官方推荐的外部构建方式——所有构建产物集中在一个目录里想清理直接rm -rf build就行源码始终干净。cmake --build build则是编译构建目录里的工程的命令它内部会自动调用 make 或者 ninja。第一次跑通之后你就掌握了 CMake 的最小闭环configure生成构建系统和 build编译。后面所有复杂操作都在这两个动作上扩展。2.3 cmake 命令行三件套-S -B --build 与缓存清理实际项目里我们不会只配一次。当你改了 CMakeLists.txt 里的选项或者想切换编译类型就必须重新 configure。而 CMake 会把上次配置的结果缓存到 build 目录下的CMakeCache.txt里很多设置项第一次生成后就固定下来了。最常见的操作循环是cmake -S . -B build -DCMAKE_BUILD_TYPERelease cmake --build build-D用来定义缓存变量。CMAKE_BUILD_TYPE是最常用的一个它决定编译优化级别Debug 会加-g和较低的优化Release 会加-O3。如果你改了个-D选项发现没生效可以先看一眼 CMakeCache.txt确认变量确实写进去了。如果某次配置出现诡异问题我的习惯是直接删掉 build 目录重新来rm -rf build cmake -S . -B build这招能解决八成我怎么改了没用的困惑。CMakeCache.txt 和生成的 Makefile 都是机器产生的不值得去手工修删掉重建是最可靠的恢复手段。2.4 CMake GUI什么时候值得打开图形界面热词里有cmake gui说明不少人想知道它到底干嘛用的。CMake 官方提供了一个图形界面程序叫 cmake-guiLinux 下安装后可以用cmake-gui启动。上面可以可视化管理 CMake 缓存变量尤其是那些从命令行敲起来很拗口的路径选项。但我的个人看法是日常开发没必要开 cmake-gui。它的价值主要在 Windows 上第一次接入一个老项目时可以用图形界面把源码目录、构建目录、Generator 选好比较直观。真正的高频操作还是命令行里那几条命令。你也可以把 cmake-gui 当成一个缓存变量浏览器当你不知道项目里有哪些可配置项时打开看一眼比翻文档快得多。3. 从零写 CMakeLists.txt一份能跑的工程是怎么长出来的3.1 最小单文件工程一个 CMake 工程的核心就是 CMakeLists.txt。别看网上各种语法花哨本质上就那么几类语句。先看最基本的骨架cmake_minimum_required(VERSION 3.10) project(MyApp LANGUAGES C CXX) add_executable(myapp main.cpp)cmake_minimum_required声明的是最低支持的 CMake 版本如果本机 CMake 比这个低configure 阶段就会直接报错。project里可以声明工程名和用到的语言我建议把 LANGUAGES 显式写出来避免 CMake 去探测不必要的语言编译器。add_executable则是把源码文件组装成可执行程序。如果工程需要多个源文件不用一个个列可以用file(GLOB)或者直接全部写进去add_executable(myapp main.cpp src/utils.cpp src/network.cpp )这里有个小争议很多人推荐避免用 GLOB 自动收集源文件因为 CMake 不会每次自动检测新添加的文件。我的习惯是源文件不多时全部显式列出来这也算是在 CMakeLists.txt 里留了一份项目结构清单新同事看起来一目了然。3.2 加头文件路径、编译选项与标准版本稍微像个样子的项目头文件不会都和源文件放一起。这时候用target_include_directoriesadd_executable(myapp main.cpp) target_include_directories(myapp PRIVATE include)PRIVATE表示这个头文件路径只对 myapp 自己可见。如果编译一个静态库给别人用公开头文件路径就传给PUBLIC这样使用者不用再额外配置 include 路径。C/C 标准版本也建议在 CMake 里统一设置不要靠每个人手动加-stdc11set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON)CMAKE_CXX_STANDARD_REQUIRED ON的意思是如果编译器不支持 C17直接报错而不是降级悄悄编译。这个特性我强烈建议打开否则可能 CI 里编译好好的本地编译器版本老一点就编译出一些语法兼容问题非常隐蔽。链接第三方库时用target_link_librariestarget_link_libraries(myapp PRIVATE pthread)在 Linux 下链接 pthread 库是老项目里经常看到的操作。到了 CMake 新版本很多链路已经被更抽象的 Find 模块包装好了但理解-l参数如何映射到 CMake 的 target 名依然很重要。3.3 多目录多模块顶层 CMakeLists 与 add_subdirectory项目一大单目录肯定装不下。热词里就有qt cmake多模块顶层cmaelists说明很多人卡在多模块组织上。多模块工程的核心思路是顶层一个 CMakeLists.txt负责描述全局配置和子模块组合每个子模块一个 CMakeLists.txt负责描述自己这个模块的源文件与目标。顶层示例cmake_minimum_required(VERSION 3.16) project(BigApp LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_subdirectory(core) add_subdirectory(gui) add_subdirectory(app)core 子模块里的 CMakeLists.txt 可以写add_library(core STATIC src/engine.cpp src/io.cpp ) target_include_directories(core PUBLIC include)app 子模块需要链接 coreadd_executable(app main.cpp) target_link_libraries(app PRIVATE core)这里最值得理解的是PUBLIC的传递性。core 的 include 目录声明成 PUBLIC 后app 链接 core 时自动就能找到 core 的头文件不需要在 app 里再写一遍 include 路径。这就是 CMake 对比 Makefile 的一个核心优势依赖信息跟着 target 走而不是靠全局变量到处传。顶层 CMakeLists.txt 不要写太多逻辑它更像一个组装清单。各模块独立开发、独立构建也能被其他工程复用。3.4 Qt/OpenCV 这种大体量依赖怎么接进来第三方大型库的接入是 CMake 另一个高价值场景。以 Qt 为例新版 Qt 6 配合 CMake 的写法是cmake_minimum_required(VERSION 3.16) project(QtDemo LANGUAGES CXX) find_package(Qt6 REQUIRED COMPONENTS Widgets) qt_standard_project_setup() qt_add_executable(QtDemo main.cpp ) target_link_libraries(QtDemo PRIVATE Qt6::Widgets)find_package做的事情是在系统里寻找 Qt6 的 Config 文件。它找到之后CMake 会导入一系列 target比如Qt6::Widgets然后你只需要在target_link_libraries里引用这个 target 即可Qt 头文件路径、动态库路径、编译选项全都被 CMake 接管。OpenCV 也是同样的套路find_package(OpenCV REQUIRED) add_executable(display image.cpp) target_link_libraries(display PRIVATE ${OpenCV_LIBS})不过 OpenCV 的路径在有些系统里 CMake 探测不到会报Could not find OpenCV。解决办法最常用的是用-DCMAKE_PREFIX_PATH告诉 CMake 去哪个目录找cmake -S . -B build -DCMAKE_PREFIX_PATH/path/to/opencv/installation这个CMAKE_PREFIX_PATH是个全局搜索路径很多 find_package 都会使用它。比单独设置像Qt5_DIR、OpenCV_DIR这样的具体变量更省事。4. 生成器选哪个Unix Makefiles 与 Ninja 的实战对比4.1 生成器是什么CMake 与构建后端的关系前面说过CMake 生成构建系统文件。它默认在 Linux 上生成的是 Unix Makefiles也就是说cmake --build背后实际调用的是 make。但 CMake 不止能生成 Makefile它还支持 Ninja、Visual Studio 工程、Xcode 工程等。选择生成器的命令是-Gcmake -S . -B build -G Ninja这就让 CMake 生成一份build.ninja文件之后cmake --build build内部就会调用 ninja 而不是 make。4.2 Ninja 和 Make 的实际差异从增量编译速度说起Ninja 的设计目标很纯粹让增量编译尽可能快。它的构建文件不像 Makefile 那样是人类可读的规则集而是为机器执行优化过的扁平结构。实际体验上比较大的项目我用 Ninja 和 Make 对比过全量编译时间差别不大但增量编译差异明显。改一个头文件之后Make 往往会多检查不少隐式依赖而 Ninja 的依赖管理更精确等编译的时间短很多。另一个体感差异是输出信息Ninja 默认输出简洁出错时又会给出足够上下文不会像某些 Makefile 那样刷几千行make[1]: Entering directory。Ninja 还能配合ninja -t targets查看所有构建目标比如列出build.ninja里说有哪些可执行文件可以构建调试构建目标命名比 make 方便。4.3 跨平台工程怎么选生成器我自己在 Linux 上的选择是普通小工程无所谓默认 Unix Makefiles 就行中等以上规模的工程、或者需要频繁改代码重编的场景优先 Ninja。Windows 下如果用 Visual StudioCMake 还能直接生成.sln工程完全接入 MSVC 的 IDE 体验用 VS Code 的话CMake Tools 插件底层也能选 Ninja 作为生成器。热词里出现了ninja cmake学习cmake ninja说明 Ninja 已经是现代 CMake 工作流里绕不开的搭档。有一点要注意Ninja 需要单独安装Ubuntu 下是sudo apt install ninja-build装完确认版本ninja --version然后再用-G Ninja配置。如果忘了装CMake 会提示找不到 ninja这个报错本身也说得挺清楚。5. 报错现场还原CMake 最经典的几个翻车点与排查思路5.1 CMakeDetermineCompilerID.cmake:9编译器没有被找到热词里有条很典型的报错cmake error at /usr/share/cmake-4.2/modules/cmakedeterminecompilerid.cmake:9。这个错误我看到过很多新手问其实它跟这个文件本身没什么关系。CMakeDetermineCompilerID.cmake是 CMake 在 configure 阶段用来探测编译器身份的脚本。它会在/usr/share/cmake-4.x/modules/这样的目录下被调用第 9 行附近报错通常意味着 CMake 尝试编译一个测试程序来确认编译器类型时失败了。换句话说问题出在编译器上而不是 CMake 上。排查顺序我建议是gcc --version g --version which gcc compgen -c | grep g如果 gcc 没装sudo apt install build-essential装一下。如果装了但 CMake 找不到检查是否设置了环境变量CC、CXX指向了不存在的路径echo $CC $CXX有些开发者之前在环境变量里设置了旧的交叉编译器路径换个项目后忘了清掉CMake 就会拿一个不存在的编译器去探测自然报错。解决办法是unset CC CXX或者重新指向正确的编译器。还有一种情况是系统里装的是新版本 CMake但编译器版本太老两者兼容性出问题。这也能解释为什么很多人升级 CMake 后突然冒出这个报错。5.2 Qt5Config.cmake not found依赖包路径没告诉 CMake另一个高频报错是CMake Error at C:/Qt/qt5.9.4/5.9.4/msvc2017_64/lib/cmake/Qt5/Qt5Config.cmake这个报错的本质是find_package(Qt5)找到了一些 Qt 相关痕迹但最终导入失败。通常是下面几种情况第一你根本没安装 Qt5或者安装的 Qt 版本和 CMake 要求不匹配。第二明明安装了但 CMake 不知道去哪里找。Windows 上最常见的就是安装路径比较深CMake 默认搜索路径覆盖不到。解决办法是指定Qt5_DIR或者用CMAKE_PREFIX_PATHcmake -S . -B build -DCMAKE_PREFIX_PATHC:/Qt/qt5.9.4/5.9.4/msvc2017_64注意路径要精确到 Qt 的根目录那一层让 CMake 能在下面继续找到lib/cmake/Qt5/Qt5Config.cmake。这个报错还提示了另一个常识find_package不是在系统里漫无目的地搜它有一套自己的搜索规则优先级是指定的-D变量 CMAKE_PREFIX_PATH 系统默认路径。所以排查依赖问题时从CMakeCache.txt里看Qt5_DIR到底被设成了什么值往往能直接定位出错原因。5.3 源码编译第三方库失败以 OpenCV 为例的通用排查法热词里有opencv cmake编译步骤不少人是想自己从源码编译 OpenCV。标准步骤大概是这样git clone https://github.com/opencv/opencv.git cd opencv mkdir build cd build cmake -D CMAKE_BUILD_TYPERelease \ -D CMAKE_INSTALL_PREFIX/usr/local .. make -j$(nproc) sudo make install看着简单但实际编译时可能因为缺少系统依赖而中断。常见的一种是Cant find missing dependency或者某个模块编译时报头文件缺失。通用的排查逻辑是先把报错信息里提到的模块名记下来然后用包管理器搜索对应的开发包比如sudo apt search name sudo apt install name-dev对于 OpenCV 这种大型库我建议编译时先不开所有扩展模块比如禁用不需要的 contrib 模块等基础版本通过后再按需开启。编译大型第三方库时make -j$(nproc)虽然快但遇到编译错误时人肉读长日志会很痛苦。建议第一次编译先make -j2确认没大问题后再放满核心数去编。另外一个从失败中恢复的小技巧编译中断后不要直接删 build 目录。先看清中断时的进度如果只是某个模块失败可以重新运行 cmake 关闭该模块然后继续 make。只有 CMake 配置阶段改动了关键选项才值得彻底重来。6. 往前再走一步VS Code 里调试 CMake 项目甚至 STM32 也能用6.1 CMake Tools 插件让 IDE 和命令行共用一套构建命令行跑通 CMake 之后很多人的下一个需求是在 VS Code 里写代码、一键编译、还能断点调试源码。热词里vscode cmake 调试源代码vscode 使用cmake开发 stm32都指向这个方向。VS Code 里装一个 CMake Tools 扩展就够了。它会自动识别项目根目录的 CMakeLists.txt然后提供几个常用操作配置、构建、调试。配置阶段你可以指定生成器、构建目录和缓存变量这些设置会存到.vscode/settings.json里{ cmake.sourceDirectory: ${workspaceFolder}, cmake.buildDirectory: ${workspaceFolder}/build, cmake.generator: Ninja, cmake.configureEnvironment: { CMAKE_PREFIX_PATH: /path/to/library } }CMake Tools 的好处是你在插件里点的Build和你在命令行里敲cmake --build build本质上是完全同一套构建逻辑。不会出现 IDE 里能编、命令行里编不了或者反过来这种割裂问题。6.2 配置 gdb/lldb 调试launch.json 与 CMake Tools 的衔接要在 VS Code 里真正打断点调试需要配置调试器。Linux 上一般用 gdb安装sudo apt install gdb然后创建一个.vscode/launch.json{ version: 0.2.0, configurations: [ { name: CMake Debug, type: cppdbg, request: launch, program: ${command:cmake.launchTargetPath}, args: [], cwd: ${workspaceFolder}, miDebuggerPath: /usr/bin/gdb, preLaunchTask: build } ] }${command:cmake.launchTargetPath}会自动解析成 CMake Tools 当前构建目标的可执行文件路径这样你切换构建目标后不需要手动改 launch.json。调试的关键点是编译时必须带调试信息。也就是说 configure 时要保证CMAKE_BUILD_TYPEDebug或者至少编译选项里有-g。很多人的困惑是我打断点怎么不生效排查第一步永远都是先确认 build 目录里的目标文件是 Debug 构建而不是在源码里找问题。还有一种更顺滑的做法是直接用 CMake Tools 的调试按钮它内部会自动把当前目标、构建目录和调试器串起来launch.json 都不用手写。不过我建议还是理解一遍配置逻辑因为一旦项目涉及嵌入式交叉编译默认配置就不够用了。6.3 嵌入式特供用 CMake 管 STM32 的交叉编译工具链我没想到第一次接触 CMake 的嵌入式场景就留下这么深的印象。STM32 的官方 SDK 很多示例工程还停留在 Keil 或者手动 Makefile 的世界里但在 VS Code CMake 的组合下用 GCC 交叉编译链同样可以搭建一套完整的开发流程。核心在工具链文件。新建一个stm32-toolchain.cmakeset(CMAKE_SYSTEM_NAME Generic) set(CMAKE_SYSTEM_PROCESSOR arm) set(TOOLCHAIN_PREFIX arm-none-eabi-) set(CMAKE_C_COMPILER ${TOOLCHAIN_PREFIX}gcc) set(CMAKE_CXX_COMPILER ${TOOLCHAIN_PREFIX}g) set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)最后一行CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY特别重要默认情况下 CMake 在 configure 阶段会尝试编译并链接一个可执行文件但嵌入式交叉编译环境里没有可执行文件这一说也不能在主机上运行目标机的程序。设置成 STATIC_LIBRARY 后CMake 就只做编译链接成静态库的探测不会去尝试运行目标文件。然后在配置时指定工具链文件cmake -S . -B build -DCMAKE_TOOLCHAIN_FILEstm32-toolchain.cmake之后可以用 OpenOCD 配合 VS Code 插件烧录和调试。CMake 在这里承担的角色跟桌面端完全一样描述模块、管理编译选项、组织源文件。区别只是编译器换成了 arm-none-eabi-gcc链接脚本和启动文件需要额外加入工程。这个场景说明 CMake 并不只是Linux 下 C 开发者的玩具。任何需要跨平台、多配置、严肃管理 C/C 代码的场合它都能成为构建层的中枢。说点个人体会。CMake 刚上手的时候很容易被它又一套语法劝退但真正用起来之后你会发现它的核心其实非常朴素用声明式的方式描述项目让构建细节交给工具。我踩过最大的坑反而是自作聪明地修改 build 目录里的生成文件或者手动清掉 CMakeCache 的部分条目——这些操作几乎都会让状态变得不可预测。与其研究那些高级技巧不如老老实实记清楚-S、-B、--build这三个动作的含义再理解find_package和 target 传递依赖这两件事就已经能从入门走到够用的水平了。最后分享一个小技巧每次拿到一个新的 CMake 项目我都会先跑一遍cmake -S . -B build然后立刻去看build/compile_commands.json这个文件前提是配置时开启了CMAKE_EXPORT_COMPILE_COMMANDS。里面记录了每个源文件实际用到的完整编译命令。你看到它在就说明 CMake 对工具链的理解是对的这个文件在 VS Code 里用 clangd 做代码提示时也是核心依赖。构建系统的玄学问题九成都能在这里找到答案。
