第30章 CMake高级技巧

课程目录第30章 CMake高级技巧

30、CMake高级技巧：自定义模块、生成器表达式高级用法、策略管理、CMake语言扩展、社区最佳实践

说实话，到了这个阶段，你已经不是新手了。前面那些基础语法、变量作用域、目标属性，你都能熟练运用。但真正让CMake变得强大的，是它那些「藏得比较深」的特性。今天我就把这些压箱底的东西翻出来，跟你好好聊聊。

自定义模块：别重复造轮子

我刚开始写CMake时，每个项目都从头写一遍FindXXX.cmake。后来发现，很多逻辑其实是通用的。比如查找某个库、检查编译器特性、设置编译选项——这些完全可以封装成模块。

CMake的模块查找路径是这样的：

# 优先查找 CMAKE_MODULE_PATH
list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake/Modules")
# 然后才是 CMake 内置模块路径
include(FindPackageHandleStandardArgs)

我自己写模块时，习惯遵循这个模板：

# cmake/Modules/FindMyLib.cmake
# 模块名：FindMyLib
# 功能：查找 MyLib 库

# 先检查是否已经找到
if(MyLib_FOUND)
    return()
endif()

# 查找头文件
find_path(MyLib_INCLUDE_DIR
    NAMES mylib.h
    PATHS /usr/include /usr/local/include
)

# 查找库文件
find_library(MyLib_LIBRARY
    NAMES mylib
    PATHS /usr/lib /usr/local/lib
)

# 处理找到/未找到的情况
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(MyLib
    REQUIRED_VARS MyLib_LIBRARY MyLib_INCLUDE_DIR
)

if(MyLib_FOUND)
    set(MyLib_INCLUDE_DIRS ${MyLib_INCLUDE_DIR})
    set(MyLib_LIBRARIES ${MyLib_LIBRARY})
    
    # 创建导入目标，方便现代CMake使用
    if(NOT TARGET MyLib::MyLib)
        add_library(MyLib::MyLib UNKNOWN IMPORTED)
        set_target_properties(MyLib::MyLib PROPERTIES
            IMPORTED_LOCATION "${MyLib_LIBRARY}"
            INTERFACE_INCLUDE_DIRECTORIES "${MyLib_INCLUDE_DIR}"
        )
    endif()
endif()

# 标记为高级缓存变量
mark_as_advanced(MyLib_INCLUDE_DIR MyLib_LIBRARY)

我的习惯：模块文件命名一定要遵循 Find<PackageName>.cmake 的格式。这样 cmake 才能自动识别。另外，尽量创建 IMPORTED 目标，这是现代 CMake 的通行做法。

生成器表达式：编译时的「动态计算」

生成器表达式这东西，我第一次接触时觉得挺绕。说白了，它就是在生成构建系统时才计算的表达式。普通变量在 configure 阶段就确定了，但生成器表达式可以延迟到生成阶段。

来看几个我常用的场景：

# 场景1：不同配置用不同编译选项
target_compile_definitions(myapp PRIVATE
    $<$<CONFIG:Debug>:DEBUG_MODE>
    $<$<CONFIG:Release>:NDEBUG>
)

# 场景2：根据平台选择源文件
target_sources(myapp PRIVATE
    $<$<PLATFORM_ID:Linux>:linux_specific.cpp>
    $<$<PLATFORM_ID:Windows>:win_specific.cpp>
)

# 场景3：链接时只对特定目标生效
target_link_libraries(myapp PRIVATE
    $<$<TARGET_EXISTS:some_lib>:some_lib>
)

生成器表达式支持嵌套，这是它的精髓：

# 复杂嵌套：Debug模式下且是Linux平台，才添加某个flag
target_compile_options(myapp PRIVATE
    $<$<AND:$<CONFIG:Debug>,$<PLATFORM_ID:Linux>>:-fsanitize=address>
)

我曾经踩过的坑：生成器表达式不能用在 file(WRITE) 或 message() 这类命令中。因为它们只在生成阶段计算，而 file/message 在配置阶段就执行了。结果就是，你看到的 message 打印出来的是空字符串，或者直接报错。

策略管理：版本升级的「安全带」

CMake 每个新版本都会引入一些破坏性变更。比如 3.0 版本后，target_link_libraries 的行为变了。如果你不处理，旧项目在新版 CMake 下可能编译不过。

策略管理就是干这个的：

# 设置 CMake 最低版本
cmake_minimum_required(VERSION 3.10)

# 显式设置策略
if(POLICY CMP0077)
    cmake_policy(SET CMP0077 NEW)  # 使用新行为
endif()

# 或者更激进一点：全部使用最新策略
cmake_policy(VERSION 3.20)

我个人建议的做法是：

# 在项目根 CMakeLists.txt 开头
cmake_minimum_required(VERSION 3.16)

# 只对已知有问题的策略做显式设置
if(POLICY CMP0074)
    cmake_policy(SET CMP0074 NEW)  # find_package 使用 _ROOT
endif()

# 其他策略保持默认，让 CMake 自己决定

策略	影响	我的建议
CMP0077	option() 是否覆盖缓存变量	设为 NEW，更直观
CMP0074	find_package 是否使用 <PackageName>_ROOT	设为 NEW，方便环境变量控制
CMP0091	MSVC 运行时库选择	设为 NEW，使用 CMAKE_MSVC_RUNTIME_LIBRARY

CMake语言扩展：写你自己的「方言」

CMake 的函数和宏，其实可以玩出很多花样。我见过有人用 CMake 写了一个完整的测试框架，虽然我不推荐这么做，但有些扩展确实很实用。

比如，我写了一个「简易的依赖注入」函数：

# 定义一个「注册组件」的宏
macro(register_component name)
    # 创建一个接口库作为组件容器
    add_library(${name} INTERFACE)
    
    # 遍历传入的源文件
    foreach(src ${ARGN})
        target_sources(${name} INTERFACE ${src})
    endforeach()
    
    # 记录已注册的组件
    set_property(GLOBAL APPEND PROPERTY REGISTERED_COMPONENTS ${name})
endmacro()

# 使用示例
register_component(logger logger.cpp logger.h)
register_component(database database.cpp database.h)

# 然后可以批量处理所有组件
get_property(all_components GLOBAL PROPERTY REGISTERED_COMPONENTS)
foreach(comp ${all_components})
    message(STATUS "Registered component: ${comp}")
endforeach()

核心思路：CMake 的宏和函数本质上是文本替换。宏不创建作用域，函数创建作用域。利用这个特性，你可以实现很多「元编程」效果。但别过度设计，CMake 终究不是通用编程语言。

社区最佳实践：那些「过来人」的经验

做了这么多年 CMake，我总结了几条铁律：

永远使用现代 CMake：target_xxx 命令优先，别再用 add_definitions 这种全局命令了。你想想看，全局命令就像全局变量，项目大了根本管不住。
最小化全局作用域：能用 target_xxx 就别用全局的。每个目标只暴露它需要的接口，这是封装性的体现。
版本声明要明确：cmake_minimum_required 写清楚，别偷懒写个 2.8。我见过太多项目因为版本不匹配，在新环境上编译失败。
测试你的 CMake 脚本：用 CTest 或者手动测试不同配置。我曾经因为一个路径写死，导致 Linux 上编译通过，Windows 上直接报错。
文档化你的模块：每个 FindXXX.cmake 文件开头写清楚用法、参数、返回值。别人（包括未来的你）会感谢你的。

这里有个我常用的项目结构模板：

my_project/
├── CMakeLists.txt          # 根构建文件
├── cmake/
│   ├── Modules/            # 自定义模块
│   │   ├── FindMyLib.cmake
│   │   └── Utils.cmake
│   └── toolchains/         # 工具链文件
│       └── arm-gcc.cmake
├── src/
│   ├── CMakeLists.txt
│   └── main.cpp
├── tests/
│   ├── CMakeLists.txt
│   └── test_main.cpp
└── docs/
    └── build_guide.md

嗯，说到工具链文件，我再补充一句。交叉编译时，工具链文件里别写死路径，用变量代替：

# toolchains/arm-gcc.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

# 用变量，别写死
set(TOOLCHAIN_PREFIX arm-linux-gnueabihf)
set(CMAKE_C_COMPILER ${TOOLCHAIN_PREFIX}-gcc)
set(CMAKE_CXX_COMPILER ${TOOLCHAIN_PREFIX}-g++)

# 设置 sysroot
set(CMAKE_SYSROOT /path/to/sysroot)

这样别人拿到你的工具链文件，只需要改 TOOLCHAIN_PREFIX 和 CMAKE_SYSROOT 就能用，不用满文件找路径。

最后一个小建议：多看看 CMake 官方模块的源码，比如 FindBoost.cmake、FindOpenSSL.cmake。这些是社区公认的最佳实践范本。我早期很多写法都是从那里学来的。

好了，这一章的内容就这些。高级技巧说到底，是为了让构建系统更健壮、更可维护。别为了炫技而用复杂特性，实用才是硬道理。

📚 课程目录

30、CMake高级技巧：自定义模块、生成器表达式高级用法、策略管理、CMake语言扩展、社区最佳实践

自定义模块：别重复造轮子

生成器表达式：编译时的「动态计算」

策略管理：版本升级的「安全带」

CMake语言扩展：写你自己的「方言」

社区最佳实践：那些「过来人」的经验