CMake实战：从构建逻辑到嵌入式交叉编译的跨平台实践

1. 为什么你的项目需要一个像样的构建系统先说个我自己的经历。早几年带一个跨平台C库Windows、Linux、macOS三端都要出包还牵扯到几个闭源SDK和一堆开源依赖。最开始用的是手写Makefile加一堆批处理脚本每次加一个源文件、换一台机器、切一套编译器都要花大把时间在构建配置上。后来有一位同事提议引入CMake我一开始是抗拒的觉得这玩意又要学一套语法折腾成本不低。但真正用顺手之后才发现之前的抗拒纯粹是因为没理解CMake解决的核心问题——它把“构建逻辑”从“具体平台和编译器”中剥离出来。打个比方你写代码时用printf不会为Linux和Windows分别写一套输出实现因为标准库帮你屏蔽了底层差异。CMake做的其实是构建层面的“标准库”。你告诉它“我需要一个可执行文件它链接了哪些库、依赖哪些头文件、用哪些编译选项”剩下的事——是用Visual Studio还是GCC、是生成Makefile还是Ninja、是静态库还是动态库——都由CMake在配置阶段统一处理。所以这篇东西不是给你念CMake手册而是我把它用在真实项目里、踩过各种版本坑、从Ubuntu到Windows、从纯本地构建到交叉编译之后沉淀下来的一套实战打法。如果你正在做C/C项目、还没认真用CMake或者已经在用但总觉得配置乱成一团这篇应该对你有用。2. CMakeLists.txt的书写逻辑从能跑到会跑很多初学者的CMakeLists.txt长这样一股脑把所有源文件塞进一个变量搞一堆include_directories和link_directories全局设置最后生成一个target。这种写法在小项目里能跑通但项目一膨胀、模块一多问题就全来了头文件搜索路径互相污染、链接顺序莫名其妙出错、想单独给某个模块加编译选项发现全局都被影响了。2.1 先忘掉全局设置记住target这个核心现代CMake3.12以上我建议直接按这个版本来最核心的思想是target。一个target就是一个库或者一个可执行文件它自带自己的头文件目录、编译选项、链接库以及这些信息的传递规则。cmake_minimum_required(VERSION 3.16) project(MyProject LANGUAGES CXX) add_library(core STATIC src/core.cpp src/parser.cpp ) target_include_directories(core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include ) target_compile_features(core PUBLIC cxx_std_17)这里target_include_directories(core PUBLIC ...)里的PUBLIC很关键。它表示core库自己编译时能看到include目录任何链接core库的目标也能看到。如果是PRIVATE那只有core自己能看到如果是INTERFACE那就是“只给使用方看自己不看”——适合纯头文件库。用这套写法你不需要在顶层到处include_directories每个模块自己管好自己使用方自动获得所需头文件路径。这就是为什么很多现代CMake项目看起来“干净”因为信息传递是靠target之间的依赖关系自动完成的而不是全局变量。2.2 查找依赖find_package的正确姿势项目一旦用到第三方库最忌讳的做法是手写link_directories(/usr/local/lib)再去target_link_libraries(myapp opencv_core ...)。正确做法是让CMake去“找”这个库找到之后用target方式链接。find_package(OpenCV REQUIRED COMPONENTS core imgproc) target_link_libraries(myapp PRIVATE ${OpenCV_LIBS})find_package背后有两套机制一套是找CMake自带的Find模块比如FindOpenSSL.cmake另一套是找库作者提供的Config文件比如OpenCVConfig.cmake。前者通常只告诉你“头文件在哪、库文件在哪”后者能给你提供target比如opencv_core这种。我在实际项目里的经验是能找Config包就用Config包因为它的target定义往往更完整依赖关系也更清晰。很多现代C库fmt、spdlog、nlohmann_json等安装后都会带上Config文件直接用就行find_package(fmt REQUIRED) target_link_libraries(myapp PRIVATE fmt::fmt)2.3 处理选项和平台差异用option和生成器表达式真实项目离不开平台差异。跨平台代码最常见的处理方式是用option给用户一个开关再配合预处理器宏option(ENABLE_TESTS Build unit tests ON) if(ENABLE_TESTS) enable_testing() add_subdirectory(tests) endif()平台差异用WIN32、UNIX、APPLE这些CMake内置变量判断if(WIN32) target_compile_definitions(app PRIVATE _CRT_SECURE_NO_WARNINGS) target_link_libraries(app PRIVATE ws2_32) else() target_link_libraries(app PRIVATE pthread) endif()编译选项层面的差异化可以借助生成器表达式generator expression比如常见的Debug和Release用不同优化级别target_compile_options(app PRIVATE $$CONFIG:Debug:-O0 -g $$CONFIG:Release:-O3 -DNDEBUG )生成器表达式之所以强是因为它在生成阶段才求值所以能根据构建类型、编译器、平台动态调整。刚开始用会觉得难读但在跨平台和CI场景里几乎离不了。2.4 推荐的基本目录结构我比较推荐的项目结构是project/ ├── CMakeLists.txt # 顶层负责全局配置和add_subdirectory ├── cmake/ # 自己的CMake模块、工具链文件 ├── include/mylib/ # 对外头文件 ├── src/ # 源文件 ├── tests/ # 测试代码 ├── examples/ # 示例程序 └── tools/ # 辅助工具顶层CMakeLists.txt只做几件事指定版本、项目名、全局编译标准、添加子目录。不要把具体的编译逻辑全堆在顶层子目录各管各的。这样做的好处是你想把某个模块单独拿到另一个项目里复用直接把整个目录拷过去就行它的CMakeLists.txt是自洽的。3. 版本选择和工具链Ubuntu降级、Cygwin、VS生成器这些坑热搜词里好几个都在问cmake版本的事这正好击中了我以前踩过的坑。CMake的版本直接影响语法支持和新功能选错了版本有的CMakeLists.txt直接报错有的虽然能过但行为不一样。3.1 Ubuntu上的CMake版本管理Ubuntu系统自带的apt源里CMake版本往往偏旧比如20.04源里是3.16.322.04源里是3.22。某些项目比如老旧的嵌入式工具链恰好要求用特定版本。需要降级或指定版本的场景我建议不要折腾系统包管理器直接用官方提供的安装脚本或者下载二进制包# 下载指定版本的预编译二进制 wget https://github.com/Kitware/CMake/releases/download/v3.16.3/cmake-3.16.3-linux-x86_64.tar.gz tar -xzf cmake-3.16.3-linux-x86_64.tar.gz sudo mv cmake-3.16.3-linux-x86_64 /opt/cmake-3.16.3 sudo ln -s /opt/cmake-3.16.3/bin/cmake /usr/local/bin/cmake这样切版本就是改个软链接的事不影响系统里其他依赖cmake的软件。为什么不用apt直接装因为apt会把cmake装到/usr/bin其他软件可能依赖那个版本你强行降级容易把系统搞坏。另外提醒一句不要忽略cmake --version的确认。很多“莫名其妙”的报错最后发现是终端里PATH指向的cmake版本和你以为的版本不一样。配置项目前先看一眼版本能省大量排查时间。3.2 Cygwin下的CMake使用在Windows上使用Cygwin环境跑CMake有一个很典型的坑CMake可能会识别到Windows原生的Visual Studio生成器而不是Cygwin的GCC工具链。因为CMake默认会探测系统里可用的生成器装了VS的机器上它会优先选择VS。解决办法是显式指定生成器和工具链cmake -G Unix Makefiles -DCMAKE_C_COMPILERgcc -DCMAKE_CXX_COMPILERg ..在Cygwin里用Unix Makefiles生成器会比默认的生成器更符合预期因为Cygwin本身模拟的就是Unix环境。如果遇到CMAKE_C_COMPILER检测不通过可以先echo $PATH确认Cygwin的gcc在PATH里。有段时间我用Cygwin构建一个依赖pthread的项目还额外需要在CMakeLists.txt里显式find_package(Threads REQUIRED)再链接Threads::ThreadsCygwin的pthread支持和Linux还是有点差别。3.3 Visual Studio生成器不匹配热搜里那个“generator: Visual Studio 16 2019 does not match the generator”是CMake的经典报错。它背后是因为你之前用某个生成器配置过build目录里面缓存了生成器信息第二次换生成器跑同一个目录CMake检测到不一致就直接拒绝继续。解决办法很简单换生成器就换个build目录或者把旧build目录删掉。rm -rf build cmake -S . -B build -G Visual Studio 17 2022 -A x64我现在的习惯是每个构建配置一独立目录build/ ├── vs2022-x64/ ├── mingw-x64/ └── ninja-release/这样互不干扰切换配置不用清缓存。CMake本身是支持多构建目录的用好这个特性比反复删build目录舒服得多。3.4 MSVC下指定编码方式通过cmake直接写/utf-8在Windows上保证MSVC能正确处理带BOM的UTF-8源码文件或者不带BOM的UTF-8if(MSVC) target_compile_options(mylib PRIVATE /utf-8) endif()/utf-8不仅告诉编译器源文件是UTF-8还告诉它执行字符集也用UTF-8。这能避免一类特别隐蔽的问题源码里写了中文注释或者中文字符串字面量Linux上GCC默认按UTF-8处理没事Windows上MSVC默认按本地区域代码页处理于是出现“在Linux上好好的拿到Visual Studio里就编译警告C4819或者字符串乱码”。加了这个选项源码层面的编码问题基本能一劳永逸地解决。如果你的源文件是GBK/GB2312编码那还是要先转成UTF-8再处理CMake的/utf-8救不了非UTF-8源文件。4. 交叉编译与嵌入式场景STM32 VSCode CMake热搜词里STM32和CMake占了很大篇幅说明嵌入式方向也越来越多人在用CMake做构建了。以前STM32开发基本都是Keil或STM32CubeIDE一把梭图形界面点一点生成工程。但这种方式在多人协作、持续集成场景下很麻烦——每个人的IDE版本、环境变量、编译选项都可能不一致构建过程不可复现。CMake加交叉编译工具链正好能解决这个问题。4.1 从CubeMX生成的代码里集成CMake新版STM32CubeMX可以直接生成CMake工程生成后目录大概是这样的project/ ├── CMakeLists.txt ├── Core/ ├── Drivers/ └── ...它会自动写好启动文件、链接脚本、芯片型号定义。不过生成出来的CMakeLists.txt偏基础如果项目要拆模块我一般会在其基础上再整理。一个典型的STM32 CMakeLists.txt核心部分长这样project(stm32_demo LANGUAGES C ASM) set(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_ASM_COMPILER ${TOOLCHAIN_PREFIX}gcc) add_executable(${PROJECT_NAME}.elf Core/Src/main.c Core/Src/stm32f4xx_it.c Core/Src/system_stm32f4xx.c startup_stm32f407xx.s ) target_include_directories(${PROJECT_NAME}.elf PRIVATE Core/Inc Drivers/STM32F4xx_HAL_Driver/Inc Drivers/CMSIS/Device/ST/STM32F4xx/Include ) target_link_options(${PROJECT_NAME}.elf PRIVATE -T STM32F407VGTx_FLASH.ld -Wl,--gc-sections )这里最关键的几个点set(CMAKE_SYSTEM_NAME Generic)告诉CMake这不是在普通操作系统上编译不进行系统库探测。交叉编译器用arm-none-eabi-前缀那套这个要单独安装常见的是gcc-arm-none-eabi或者arm-gnu-toolchain。链接脚本.ld文件通过target_link_options传进去。汇编启动文件用.s后缀CMake会通过ASM语言自动选择编译器。4.2 工具链文件的正确使用方式上面那种把编译器写死在CMakeLists.txt里的方式对于纯嵌入式项目是够用的。但如果同一份代码要同时构建host版本做单元测试又要构建嵌入式版本烧到板子里更好的做法是把交叉编译参数单独抽成一个工具链文件arm-none-eabi.cmakeset(CMAKE_SYSTEM_NAME Generic) set(CMAKE_SYSTEM_PROCESSOR arm) set(CMAKE_C_COMPILER arm-none-eabi-gcc) set(CMAKE_CXX_COMPILER arm-none-eabi-g) set(CMAKE_ASM_COMPILER arm-none-eabi-gcc) set(CMAKE_EXE_LINKER_FLAGS --specsnano.specs --specsnosys.specs CACHE INTERNAL )使用时cmake -S . -B build/f407 -DCMAKE_TOOLCHAIN_FILEtoolchains/arm-none-eabi.cmake构建host版本时不加工具链文件即可两份构建目录互不干扰。这正是CMake“同一套源码、多目标构建”的典型场景。4.3 VSCode里使用CMake插件配置STM32项目VSCode配合ms-vscode.cmake-tools插件是现在比较主流的嵌入式开发方式。插件会读取你项目里的CMakeLists.txt自动生成compile_commands.json如果开启了CMAKE_EXPORT_COMPILE_COMMANDS代码补全和跳转就是基于这个文件工作的。在.vscode/settings.json里我一般会这样配置{ cmake.configureOnOpen: true, cmake.generator: Ninja, cmake.buildDirectory: ${workspaceFolder}/build/${buildType}, cmake.configureArgs: [ -DCMAKE_TOOLCHAIN_FILE${workspaceFolder}/toolchains/arm-none-eabi.cmake, -DCMAKE_EXPORT_COMPILE_COMMANDSON ], cmake.debugConfig: { cortex-debug.armToolchainPath: /opt/gcc-arm-none-eabi/bin } }几个实际体验用Ninja生成器比用Unix Makefiles更快增量编译尤其明显。开了CMAKE_EXPORT_COMPILE_COMMANDS后C/C插件的智能感知会更准确。因为交叉编译不会在宿主上运行程序调试需要用cortex-debug插件配合OpenOCD或J-Link。这也是为什么cmake-tools和cortex-debug插件常常是配套出现的。还有个容易漏的地方cortex-debug需要知道工具链路径如果arm-none-eabi-gdb不在系统PATH里就得在settings.json里显式指出来。不然调试时会出现“启动OpenOCD成功但无法连接gdb”的报错。4.4 嵌入式项目的编译选项细节嵌入式编译的坑主要在链接阶段。比如ARM芯片的启动文件需要-nostartfiles某些库函数需要--specsnano.specs来减少体积。这些选项在CMake里要放在target_link_options而不是target_compile_options因为它们是给链接器的。我常用的嵌入式C编译选项target_compile_options(${PROJECT_NAME}.elf PRIVATE -mcpucortex-m4 -mthumb -mfloat-abihard -mfpufpv4-sp-d16 -Os -ffunction-sections -fdata-sections -Wall )如果CMakeLists.txt里忘了加-mcpu和-mthumb链接出来的程序烧到板子上几乎必然跑不起来而且没有任何提示。遇到“程序下载成功但没反应”先检查这几个选项是不是匹配你的芯片。芯片型号不对、浮点单元类型不对这类问题排查起来相当费时间。5. 把CMake工程变成可安装的产物spec、deb与打包实践很多教程讲到add_executable和target_link_libraries就结束了但真实项目里还差最后一步——发布。你辛苦写好的库总得让同事或者用户能方便地安装、可以被其他项目find_package找到而CMake的install规则和CPack就是干这个的。5.1 install规则的正确写法install规则决定了“安装到系统里”之后是什么样子。对于库项目核心是装头文件和库文件。以我的习惯install(TARGETS mylib EXPORT MyLibTargets LIBRARY DESTINATION lib ARCHIVE DESTINATION lib RUNTIME DESTINATION bin INCLUDES DESTINATION include ) install(DIRECTORY include/ DESTINATION include) install(EXPORT MyLibTargets FILE MyLibConfig.cmake NAMESPACE MyLib:: DESTINATION lib/cmake/MyLib )这里有几个点要拆开说EXPORT MyLibTargets把target的定义导出到一个文件中其他项目通过find_package(MyLib)就能拿到MyLib::mylib这个target继续享受target的信息传递特性。NAMESPACE MyLib::是给target加前缀这是现代CMake的规范做法避免不同库的target重名冲突。FILE MyLibConfig.cmake是最终生成的配置文件名字。用户在你的项目里写find_package(MyLib)CMake会在lib/cmake/MyLib目录下找MyLibConfig.cmake。装完之后你在另一个项目里就可以这样用find_package(MyLib REQUIRED) target_link_libraries(app PRIVATE MyLib::mylib)头文件路径、编译选项这些都不用手动指定因为它们在MyLib的target定义里已经记录好了。5.2 用CPack制作deb包热搜词里有“cmake 制作 deb”这其实是CPack的活。CPack是CMake自带的打包工具能生成deb、rpm、tar.gz、zip、NSIS安装包等多种格式。在CMakeLists.txt里加上include(CPack) set(CPACK_PACKAGE_NAME myapp) set(CPACK_PACKAGE_VERSION 1.0.0) set(CPACK_PACKAGE_CONTACT meexample.com) set(CPACK_GENERATOR DEB) set(CPACK_DEBIAN_PACKAGE_MAINTAINER meexample.com) set(CPACK_DEBIAN_PACKAGE_DEPENDS libc6 ( 2.31))然后cpack -G DEB它会根据你之前定义的install规则自动把文件打进去。比如可执行文件装在/usr/bin库文件装在/usr/lib。这里有个我踩过的坑CPack的deb包默认依赖meta信息不完整装上之后可能因为缺少libc6依赖而安装失败。所以CPACK_DEBIAN_PACKAGE_DEPENDS最好显式声明。如果你的程序还依赖其他库可以用dpkg-shlibdeps去分析实际依赖再手动填进去。另外一个常见需求是把CMake工程打包成tar.gz给用户直接解压用set(CPACK_GENERATOR TGZ) cpack这时候所有文件会按install规则的DESTINATION路径打包对于不想污染用户系统的便携版软件来说很实用。5.3 版本号和包名的管理技巧版本号建议不要硬编码在多个地方而是在顶层CMakeLists.txt定义一个缓存变量set(VERSION_MAJOR 1) set(VERSION_MINOR 4) set(VERSION_PATCH 2) set(PROJECT_VERSION_STR ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}) project(myapp VERSION ${PROJECT_VERSION_STR})这样project()里的VERSION会影响CPack包的版本号、生成的Config文件版本号以及${PROJECT_VERSION}变量。只用改一处其他地方自动同步。同时注意project(myapp VERSION 1.4.2)要求CMake 3.0以上这在现在不是问题但如果你的CI里还在用特别老的CMake就需要注意了。6. 老项目的CMake渐进式改造思路最后一个部分聊聊怎么把存量老项目改造成CMake。很多团队不是不想用CMake而是项目已经跑了很多年直接推到重来不现实。我的经验是不需要一步到位可以渐进式迁移。6.1 以编译单元为单位逐个迁移如果现在用的是Visual Studio的.vcxproj或者手写Makefile不要试图一次性把所有模块搬完。选一个依赖最少的模块先迁移把它编译成一个静态库然后在原来的构建系统里链接这个库而不是直接编译它的源码。比如你原来在Makefile里OBJS main.o module_a.o module_b.o改为CMake构建module_aadd_library(module_a STATIC src/module_a.cpp) target_include_directories(module_a PUBLIC include)然后在Makefile里把module_a.o替换成链接libmodule_a.a。等所有模块都迁移完了再删掉Makefile整体切换。这样做的最大好处是每个阶段都有能跑的版本不会出现“改造到一半项目编不过”的情况。6.2 利用include_external_msproject和add_custom_target做桥接如果项目里还有Visual Studio工程暂时没法迁移可以在CMakeLists.txt里用include_external_msproject(old_module old_module.vcxproj)这让CMake能感知到旧的VS工程并在生成VS解决方案时一起构建。虽然跨平台能力受限但至少让团队在向CMake迁移的过程中不用丢掉还没迁移完的部分。对于更复杂的旧构建步骤比如调用代码生成器、从IDL生成代码可以用add_custom_target和add_custom_command把它们融入CMake的构建图add_custom_command( OUTPUT generated/config.h COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/tools/gen_config.py ${CMAKE_CURRENT_SOURCE_DIR}/config.in ${CMAKE_CURRENT_BINARY_DIR}/generated/config.h DEPENDS config.in tools/gen_config.py ) add_custom_target(generate_config DEPENDS generated/config.h)这样生成的config.h会作为依赖参与后续编译只要源文件有变化、或者生成脚本有更新CMake会重新触发生成。用它来桥接老构建系统里的“自定义步骤”很顺手。6.3 define_property和全局缓存变量的替代老项目里常常能看到一堆全局宏定义散落在各处比如-DUSE_OLD_API。迁移到CMake后建议把这些宏也按target收敛if(USE_OLD_API) target_compile_definitions(${PROJECT_NAME} PUBLIC USE_OLD_API) endif()这样能清楚看到这个宏影响了谁而不是全项目一刀切。如果某些宏影响了多个target再考虑用add_compile_definitions做全局设置但尽量少用保持target的自包含性。迁移期间你会被迫理清很多历史遗留的“全局变量”这本身对项目健康度来说就是一件好事。7. 最后我在实际项目里沉淀的几条建议文章写到这按惯例应该收个尾。不写总结了就说说这几年用CMake下来我自己认为最值得记住的几条经验。第一现代CMake的核心是target思维不是语法。一旦理解了一个target自带头文件目录、编译选项、链接库和传递规则写出来的CMakeLists.txt自然就清晰了。语法可以查文档思维方式需要在实际项目中练。第二不要在build目录上吝啬硬盘空间。多建几个build目录Debug、Release、不同编译器、不同工具链用的时候按需选择出问题的时候直接删掉重建比反复配置同一个目录省心得多。CMake的构建目录设计就是为多配置并行准备的。第三工具链和平台相关的东西单独拎出来。工具链文件、编译选项里的平台差异分支最好集中管理不要散落在各个子目录的CMakeLists.txt里。我现在的做法是项目根目录下放一个cmake/文件夹里面全是工具链文件和我们自己写的Find模块。这样团队新成员上手时看这一个目录就能明白整个项目是怎么跨平台的。第四善用CMAKE_EXPORT_COMPILE_COMMANDS。开了这个选项之后构建目录下会生成compile_commands.json里面记录了每个源文件的完整编译命令。VSCode的clangd插件、各种静态分析工具都能直接使用它做代码跳转、错误提示的准确率高很多。特别是嵌入式交叉编译场景IDE如果不认识你的工具链智能提示经常失效但有了这个文件就相当于告诉IDE“按这些命令来理解你的代码”。第五遇到项目相关的问题先看版本再看缓存最后看语法。这是我从无数个“CMake报错”中总结出的排查优先级。版本不匹配会导致行为差异缓存残留会导致配置混乱语法错误反而是最少见的。如果构建出现诡异现象先cmake --version确认版本再rm -rf build清理缓存重来大部分问题都能解决。CMake这玩意说难不难说简单也不简单。真正把它用好的关键从来不在记住多少条命令而在于理解它替我们抽象了什么、解决了什么。希望这篇基于实战经验的分享能让你少踩几个我当年踩过的坑。