先讲个故事。我最早写C的时候根本不碰CMake代码全靠IDE一键编译后来项目被丢到一台没有带界面的服务器上才发现自己连怎么把编译流程复现出来都搞不定。折腾了很久查了一堆资料才把CMake这套东西理清楚。这个东西其实不复杂但零散资料太多了新手很容易被绕晕。所以这篇东西我打算从为什么需要它开始讲把CMakeLists.txt的写法、常用配置、常用命令、还有那些容易踩的坑一次全部整理出来。适合刚接触C工程化的人也适合那些已经写了几年C但从来没有认真管过构建流程的朋友。看完之后至少你拿到一个陌生项目能看懂它的CMakeLists.txt在干什么自己新建项目时也能快速搭出一套干净、跨平台的构建方案。1. CMake到底在解决什么问题1.1 为什么C项目离不开一套构建脚本C和Python、Java这种自带包管理加解释器的语言不一样编译链接这一整套流程几乎没有唯一正确答案。同样是源代码在Linux上用GCC能编换到Windows上用某IDE又可能全报错同一台机器上编译器版本不同、链接库的顺序不同、宏定义不同最终产物也可能完全不一样。早期大家用Makefile来管但Makefile是Unix传统换到Windows要装各种兼容环境写起来又有Tab缩进那些糟心事。而且一个大型项目的Makefile写到最后基本变成了天书想加一个源文件得在十几个地方改。CMake就是来解决这个痛的。它不直接编译代码而是先读取你写的CMakeLists.txt生成一套当前平台能用的构建系统。在Linux上它可以生成Makefile或者Ninja构建文件在Windows上可以生成工程文件在macOS上可以生成Xcode工程。同一份CMakeLists.txt跨平台构建这才是它最大的价值。1.2 CMake、编译器、构建系统三者的关系这里很多人容易混淆。CMake不是编译器不是打包器也不是Make的替代品。它更像一个构建方案的调度员。你自己写CMakeLists.txt告诉它项目有哪些源文件、需要什么库、输出什么东西。CMake根据你本机环境生成对应的构建规则文件。然后你再去执行真正编译的那一步。比如在Linux上它生成Makefile你执行make或者执行cmake --build编译器才真正进场。我一般会强调一句话CMake负责生成make/ninja/IDE负责编译。所以排错的时候先分清楚是CMake配置错误还是实际编译错误。前者通常出现在cmake -S . -B build这一步后者出现在cmake --build build这一步。1.3 什么时候你值得认真学CMake如果你只是自己写着玩永远一个main.cpp编译命令行敲一下也能凑合。但只要有下面任何一个场景我建议你一定把CMake捡起来项目需要跨平台至少要在Linux和Windows上都编译过。项目引入了第三方库需要找头文件和库文件的位置。项目从一个人维护变成多人协作需要统一构建方式。项目要生成可安装的产物让别人能一键使用。你不想把编译过程写成一堆长长的shell命令丢给同事。我经手过一个项目一开始用手写Makefile维护到后面每加一个文件就要改Makefile还经常改错。后来花了个下午全部迁到CMake同样的项目构建脚本从两百多行压缩到几十行新增源文件甚至不用改构建配置。这种体验一旦试过就回不去了。2. 手把手写出第一个CMakeLists.txt2.1 最简工程单源文件怎么构建先从一个最直观的场景开始目录里就一个hello.cpp想编译成可执行文件。cmake_minimum_required(VERSION 3.20) project(hello LANGUAGES CXX) add_executable(hello hello.cpp)然后执行cmake -S . -B build cmake --build build第一行指定CMake最低版本第二行声明项目名称和语言第三行告诉CMake要生成一个可执行文件。这里有个细节executable后面的第一个参数hello是目标名它不一定等于输出文件名默认情况下CMake会用它作为输出文件名。你也可以改成别的名字add_executable(my_output_alias hello.cpp) set_target_properties(my_output_alias PROPERTIES OUTPUT_NAME hello)2.2 多源文件源文件列表怎么收集当源文件变多很多人第一反应是把文件全列出来add_executable(app main.cpp parser.cpp utils.cpp core.cpp)这种手写列表最直观也最好维护。对于大部分中小项目我推荐直接这么写因为每一次改动都是显式的git diff也清清楚楚。还有一种比较偷懒但常见的写法用aux_source_directory自动收集目录下所有cppaux_source_directory(src SRCS) add_executable(app ${SRCS})但这个方法在现在的CMake版本里已经不太推荐了因为它会把目录下所有源文件一股脑加进去假如目录里有些文件并不想参与编译你就得手动剔除挺麻烦。而且如果你的源文件分布在多个子目录还要多次调用。比上面更灵活的是file GLOBfile(GLOB_RECURSE SRCS CONFIGURE_DEPENDS src/*.cpp) add_executable(app ${SRCS})加上CONFIGURE_DEPENDS之后CMake会在每次构建时检查文件是否新增基本可以做到新增文件自动感知。但GLOB仍有个问题如果目录里有暂时不想编译的测试文件或者临时文件你得依赖命名规则来区分。我自己的习惯是源文件列表尽量手写、显式排列。工程太大的时候用add_subdirectory拆分子模块不让所有源文件堆在一个CMakeLists里。因为一个几千行的CMakeLists跟一个几千行的Makefile没什么区别都很难维护。2.3 头文件路径与宏定义编译时头文件搜索路径是刚需。假设代码里有include/和src/两个目录头文件在include/下编译目标app需要能看到它们include_directories(include) add_executable(app main.cpp src/parser.cpp)但include_directories是全局生效的新手上手这么写没问题项目变大之后还是建议换成target_include_directories效果只影响指定目标不会污染其他库add_executable(app src/main.cpp src/parser.cpp) target_include_directories(app PRIVATE include)宏定义也一样全局用add_compile_definitions局部用target_compile_definitionstarget_compile_definitions(app PRIVATE PROJECT_VERSION1.2.0)2.4 把代码拆成库真实项目很少只有一个可执行文件。一种正常的组织方式是把核心逻辑抽成静态库主程序只负责调用。比如目录结构mylib/ include/mylib/core.h src/core.cpp app/ main.cpp CMakeLists.txt顶层CMakeLists可以这样写cmake_minimum_required(VERSION 3.20) project(demo LANGUAGES CXX) add_library(mylib STATIC mylib/src/core.cpp) target_include_directories(mylib PUBLIC mylib/include) add_executable(app app/main.cpp) target_link_libraries(app PRIVATE mylib)这里最关键的其实是PUBLIC和PRIVATE的选择。mylib的头文件路径设为PUBLIC意思是谁链接mylib谁就能自动拿到include路径app不需要再重复设置include目录。PRIVATE则只对被设置的目标本身生效链接它的目标不会继承。这个机制很多人一开始没搞懂之后容易把include路径到处写导致构建系统一团乱麻。3. 常用配置逐项解析3.1 编译标准与编译类型现代C项目一般会把标准固定下来set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF)CMAKE_CXX_STANDARD是希望编译器按C20标准编译CMAKE_CXX_STANDARD_REQUIRED是强制要求编译器支持达不到直接报错。CMAKE_CXX_EXTENSIONS OFF是禁用编译器私有扩展比如GCC的-stdgnu20就带扩展。编译类型涉及一个很多人混淆的点。在Linux和macOS这类单配置生成器里编译类型是配置阶段就确定的cmake -S . -B build -DCMAKE_BUILD_TYPEReleaseDebug、Release、RelWithDebInfo、MinSizeRel这四个预设值影响的核心其实就是优化等级和是否生成调试信息。在Windows上如果用某IDE生成器它属于多配置生成器构建的时候才指定配置所以同样的cmake -DCMAKE_BUILD_TYPERelease不一定生效正确的做法是cmake --build build --config Release我见过不止一个人在Windows上用VS生成器的时候往CMAKE_BUILD_TYPE里传Debug结果发现变量好像没起作用其实就是这个原因。3.2 输出目录与常用变量默认情况下可执行文件会直接放在build目录下这个目录在大型项目里会积出几百个文件。我习惯把产物统一放到一个bin目录set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)RUNTIME指可执行文件Windows上的DLL也算LIBRARY指共享库so/dylibARCHIVE是静态库.a/.lib以及Windows上的导入库。另一个常用变量是CMAKE_BINARY_DIR它永远是当前构建目录的根路径也就是你执行cmake -B指定的目录。还有CMAKE_SOURCE_DIR是顶层CMakeLists.txt所在目录。区分这两个方向很重要很多人写路径习惯硬编码一换机器就崩。安装路径方面最常用的是CMAKE_INSTALL_PREFIXcmake -S . -B build -DCMAKE_INSTALL_PREFIX/opt/myapp这样后续执行cmake --install build文件会装到指定目录。3.3 find_package 与第三方库工程一旦引入第三方库最好别自己手写一堆绝对路径。CMake提供了find_package这套机制。最简单的例子是线程库find_package(Threads REQUIRED) target_link_libraries(app PRIVATE Threads::Threads)find_package有两种模式。MODULE模式找FindXXX.cmake模块CONFIG模式找第三方库自己安装的XXXConfig.cmake。REQUIRED表示找不到就直接报错我们项目一般都会加。还有一个细节有些库用find_package能找到目标但不会自动把它的依赖也给你串好。我自己常遇到的问题比如用某个库链接它之后还要求手动链接它的依赖库。遇到这种情况查一查它是否提供了IMPORTED目标IMPORTED目标一般会把依赖封装好直接链接一个目标名就完事。3.4 安装规则与导出配置可执行文件编出来还需要让别人安装。CMake安装配置核心是install命令install(TARGETS app RUNTIME DESTINATION bin) install(DIRECTORY include/ DESTINATION include)这样cmake --install build之后可执行文件会放到前缀目录的bin下头文件放到include下。如果还想生成一份供下游项目使用的CMake配置就得用exportinstall(TARGETS mylib EXPORT mylibTargets ARCHIVE DESTINATION lib) install(EXPORT mylibTargets NAMESPACE mylib:: DESTINATION lib/cmake/mylib)这套东西比较复杂但你的库如果打算给别人用这步早晚要啃。它能让你安装出的库被其他人的find_package直接找到。3.5 用CMakePresets统一配置项目到了团队协作阶段每个人都会敲各种参数我推荐用CMakePresets.json把这些参数固化下来。文件放在项目根目录{ version: 6, configurePresets: [ { name: linux-release, generator: Ninja, binaryDir: ${sourceDir}/build/release, cacheVariables: { CMAKE_BUILD_TYPE: Release } } ], buildPresets: [ { name: linux-release, configurePreset: linux-release } ] }之后所有人统一执行cmake --preset linux-release cmake --build --preset linux-release好处是少了记忆一堆-D参数的负担同事之间也不会再出现你那能编我咋编不过的争执。4. 常用命令速查与实战4.1 项目声明与目标创建命令再来看几个最核心的命令。cmake_minimum_required(VERSION 3.20)指定最低版本低于这个版本的CMake会直接拒绝处理。要放在CMakeLists.txt开头。project(name [VERSION x.y.z] [LANGUAGES C CXX])声明项目名、版本、语言。LANGUAGES不写的话CMake默认会检测并启用C和CXX但我习惯显式写避免某些环境意外启用Fortran之类自己不关心的语言。add_executable(name sources...)创建可执行目标add_library(name STATIC/SHARED/INTERFACE sources...)创建库目标。如果只想创建一个概念目标来聚合其他目标不需要源文件可以用INTERFACE库后面很多纯头文件库就喜欢这么干。4.2 目标属性配置命令target_系列命令是CMake新式写法的核心。它们都针对某个单独的目标而不是全局作用target_include_directories(target PUBLIC/PRIVATE dirs...)设置头文件搜索目录。target_compile_definitions(target PUBLIC/PRIVATE defs...)设置宏定义。target_compile_options(target PUBLIC/PRIVATE options...)设置编译选项。target_link_libraries(target PUBLIC/PRIVATE libs...)设置链接依赖。target_compile_features(target PUBLIC cxx_std_20)要求某个C特性用来按需提升标准。target_sources(target PRIVATE files...)往目标里追加源文件。PUBLIC和PRIVATE的区别我最开始总是记混。简单理解PUBLIC说明这个属性要对外可见别人链接你的时候会继承PRIVATE只对自身有效还有一个INTERFACE属性只对链入者有效自己不用。纯声明头文件库用INTERFACE最多。4.3 查找与引入外部依赖的命令find_package是引入第三方库的首选。find_path和find_library是一对更底层的命令用来手动定位头文件目录和库文件find_path(MYLIB_INCLUDE_DIR mylib/core.h) find_library(MYLIB_LIBRARY NAMES mylib)如果你用了pkg-configCMake也支持find_package(PkgConfig) pkg_check_modules(FOO REQUIRED foo1.0) target_link_libraries(app PRIVATE ${FOO_LIBRARIES}) target_include_directories(app PRIVATE ${FOO_INCLUDE_DIRS})这里有个小建议优先用find_package因为现在很多库都提供CMake包装目标直接链接目标名依赖关系比手动传变量清晰得多。4.4 自定义构建步骤命令有时候你需要在编译前生成代码、编译后拷贝文件、或者运行一个脚本。常见用add_custom_commandadd_custom_command(TARGET app POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/config/app.ini $TARGET_FILE_DIR:app/app.ini COMMENT Copying config file )这样可以保证可执行文件生成后立刻把配置文件拷到产物目录。如果按文件依赖触发用add_custom_command(OUTPUT ...)配合add_custom_targetadd_custom_command( OUTPUT ${CMAKE_BINARY_DIR}/generated.h COMMAND generator_tool --output ${CMAKE_BINARY_DIR}/generated.h DEPENDS generator_tool ) add_custom_target(gen DEPENDS ${CMAKE_BINARY_DIR}/generated.h)把这个gen目标加到主目标的DEPENDS里或者直接add_dependencies(app gen)。4.5 控制流与辅助命令CMake不是常规编程语言但它也有变量、函数、条件控制等。整理几个:set(VAR value)普通变量。set(VAR value CACHE BOOL description)缓存变量。unset(VAR)删除变量。list(APPEND list_name item)列表追加。message(STATUS message)输出信息。if() / elseif() / else() / endif()条件判断。foreach(variable IN ITEMS a b c)循环。function(func_name arg1 args...)自定义函数。option(OPT_NAME description ON)布尔选项。简单例子option(ENABLE_TESTS Enable tests ON) if(ENABLE_TESTS) add_subdirectory(tests) endif()这样别人可以用-DENABLE_TESTSOFF轻松关闭测试构建。5. 实操中容易踩的坑与排查思路5.1 链接顺序导致的undefined reference我第一次遇到这个坑真是欲哭无泪。代码在A机器上编得好好的换台机器就报undefined reference最后发现是库链接顺序问题。GNU链接器在解析符号时是严格从左到右扫描的。如果你写成target_link_libraries(app PRIVATE core net)core依赖netnet又缺符号时顺序必须保证依赖方在前被依赖方在后。有些经验会把所有库放在一行反复写两遍来缓解比如app PRIVATE core net core。与其这样不如把库拆成功能明确的模块并且尊重依赖顺序。另外如果你的一个库是动态库另一个是静态库动态库本身的依赖会被记录通常不需要手写顺序。但静态库的依赖则需要按依赖方向列清楚。5.2 头文件变更不触发重新编译这个坑很隐蔽。假设你写了一个库add_library(mylib STATIC mylib/src/core.cpp)但是你没有在源文件列表里面加上头文件。当include/下的头文件被修改后某些构建系统可能不会自动检测到头文件变动导致编译出的库还是旧的。解决方法之一是使用target_sources把头文件也加进去target_sources(mylib PRIVATE include/mylib/core.h)头文件参与目标依赖关系后变更时就能正确触发重编。这不是必须的但实际解决过后遗症。另一种情况是用了file(GLOB ...)收集源文件但没有加CONFIGURE_DEPENDS新建源文件后CMake根本不知道你执行构建它不会重新运行CMake然后你怎么编译都找不到新文件。排查方向就是看配置阶段是否重新运行不行就手动再执行一次cmake --build之前的cmake命令。5.3 多配置生成器与CMAKE_BUILD_TYPE前面提到过一次这里再强调如果你在Windows上用VS工程生成器CMAKE_BUILD_TYPE这个概念基本不适用。它是单配置生成器才有的概念。多配置生成器的构建类型是构建阶段选择的cmake --build build --config Debug/Release。所以写CMake的时候不要过度依赖CMAKE_BUILD_TYPE去判断当前处于什么模式。更通用的做法是用生成器表达式比如$ CONFIG:Debug 。很多新手在写配置文件拷贝逻辑时条件判断用if(CMAKE_BUILD_TYPE STREQUAL Debug)在多配置生成器下就会失灵。5.4 CMake缓存变量的坑CMake缓存特别容易让人迷惑。你设置了一个变量后面想再改发现怎么改都不生效。最常见的是编译器选择cmake -S . -B build -DCMAKE_C_COMPILERgcc后来想换clang又执行cmake -S . -B build -DCMAKE_C_COMPILERclang你会发现它没变。因为第一次配置时CMAKE_C_COMPILER已经写进CMakeCache.txt参数传入优先级不一定能覆盖缓存值。正确做法是先删掉build目录重新配置或者先cmake -E remove_directory build再执行。另一个常见现象是自定义缓存变量设置了之后修改otal CMakeLists.txt里的set默认值不会立即生效。缓存变量优先级高于普通set赋值所以你改来改去缓存里还是旧值。排错时优先打开CMakeCache.txt看一眼变量到底存成了什么。5.5 Windows下的DLL导出问题如果你在Windows上用共享库一般需要在代码层面处理__declspec(dllexport) / dllimport这种导出宏否则库编出来后外部根本找不到符号。有个省事的方案是设置set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)它会让CMake自动处理所有公开符号的导出特别适合跨平台项目的快速迭代。但这套机制在复杂项目里还是容易和库自身的宏设计冲突规范做法仍然是让每个导出接口具备明确的导出宏定义。5.6 代码编码问题另一个看起来不是CMake问题但经常被归到CMake上的坑Windows下源码文件是UTF-8结果在中文系统上编译之后界面显示乱码甚至编译器直接报C4819警告。可以尝试在编译选项里加上/utf-8if(MSVC) add_compile_options(/utf-8) endif()GCC/Clang这边一般默认能处理UTF-8但Windows上其它编辑器保存的GBK源码在Linux上也会出问题。源文件统一用UTF-8然后CMake层面做好编译器选项能省掉大把无意义的排查时间。5.7 静态库循环依赖项目模块一多静态库之间常常出现A依赖BB依赖A。链接阶段如果直接按顺序A、B必定有人缺符号。我见过很多团队在这上面硬压时间。常规解法是让B也反过来链接A甚至循环多写几次但因为链接器是按顺序扫描的这种写法容易碰运气。更干净的方式是合并成一个库或者把公用的底层部分抽成一个基础库C让A和B都依赖C。有同事的项目就是靠这一招从每小时改一次链接配置中解脱出来的。6. 我对CMake学习路径的几点体会我前后折腾CMake也有好几年了最后分享几个个人经验。第一学CMake不要一上来就背命令抓住目标这个概念就够了。目标就是可执行文件、库、自定义动作的统称。百分之八十的CMakeLists其实就是创建目标然后给目标设置属性再把目标互相链接起来。理解了这条主线很多命令都是围绕目标展开的。第二保持CMakeLists最小化。一个子目录一屏能看完是理想状态。不要把所有逻辑写在最顶层也不要动不动用GLOB把所有文件卷进来。明确列出源文件真的不麻烦反而能让你每次提交时多看一眼项目结构。第三异常情况多查CMakeCache.txt和生成器表达式文档。很多明明设置了怎么没生效的问题本质都是缓存变量或者生成器差异。学会了看缓存文件等于拿到了构建过程的X光片。第四多配置生成器和单配置生成器的区别一定要烂熟于心。我在Linux上用习惯之后切到Windows项目就常常忘记加--config参数构建出来一堆调试版本运行起来慢得离谱。最后如果你有机会看一些大型项目的CMakeLists花点时间琢磨他们的目录划分和target命名。很多时候CMake工程量失控不是因为语法不熟而是模块边界没画清楚。这一篇整理的都是日常最常用的东西。真踩到更冷门的坑多读官方文档配合CMakeCache.txt和生成器表达式排查大多数问题都有迹可循。你自己上手搭一个项目写坏三五次再改好这套工具基本就算真正掌握了。