📚 课程目录第4章 CMake构建系统

4、CMake构建系统：CMakeLists.txt结构、编译选项配置、Debug/Release模式、安装路径

说到CMake，我最早接触它是给一个跨平台项目写构建脚本。说实话，那时候觉得Makefile挺好用的，干嘛非要再套一层？直到项目从Linux迁移到Windows，要同时支持VS和GCC，我才意识到CMake的威力——你只管写规则，它帮你生成各平台的工程文件。

对我们国密SDK来说，CMake更是必需品。为什么？

要兼容多种编译器（GCC、Clang、MSVC）
要支持静态库、动态库两种构建方式
要方便地切换Debug/Release模式
要控制安装路径，方便CI集成

这些需求，CMake都能优雅地解决。我个人习惯把CMakeLists.txt当作文档来写——结构清晰、注释明确，别人看一眼就知道这个项目怎么构建。

4.1 CMakeLists.txt 基本结构

一个规范的CMakeLists.txt，我一般分成四块：头部声明、选项配置、目标定义、安装规则。咱们来看个完整的例子：

# ============================================
# CMakeLists.txt - 国密SDK构建配置
# ============================================

# 头部：CMake版本和项目信息
cmake_minimum_required(VERSION 3.14)
project(GM_SDK VERSION 1.2.0 LANGUAGES C CXX)

# 选项：控制构建行为
option(BUILD_SHARED_LIBS "构建动态库" ON)
option(ENABLE_SM2 "启用SM2算法" ON)
option(ENABLE_SM3 "启用SM3算法" ON)
option(ENABLE_SM4 "启用SM4算法" ON)
option(ENABLE_TESTS "编译测试用例" OFF)

# 编译选项：语言标准和特性
set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 第三方库查找
find_package(OpenSSL REQUIRED)

# 源文件收集
file(GLOB_RECURSE GM_SRC
    "src/*.c"
    "src/*.cpp"
    "src/asm/*.S"
)

# 目标定义：核心库
add_library(${PROJECT_NAME}
    ${GM_SRC}
)

# 链接依赖
target_link_libraries(${PROJECT_NAME}
    PRIVATE OpenSSL::Crypto
)

# 安装规则
install(TARGETS ${PROJECT_NAME}
    EXPORT ${PROJECT_NAME}Targets
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

install(DIRECTORY include/
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

结构要点

区块	作用	我的建议
cmake_minimum_required + project	声明最低版本和项目元数据	版本号别写太高，3.14够用
option() 定义	控制特性开关	所有可配置项都用option暴露
编译标准设定	锁定C/C++标准	加REQUIRED防止编译器降级
目标生成	add_library / add_executable	静态库/动态库用同一个目标名
安装规则	install() 指令	用GNUInstallDirs模块

4.2 编译选项配置：精细控制每一行指令

编译选项这块，我踩过不少坑。最典型的一次是给SM2算法加汇编优化，编译参数没对齐，导致不同源文件用了不同的ABI，链接的时候报了一堆undefined reference。

从那以后，我总结出一套分层管理的做法：

# 全局编译选项（影响所有目标）
add_compile_options(-Wall -Wextra -Werror)
add_compile_options(-fPIC)

# Debug模式下加调试符号和地址消毒
set(CMAKE_C_FLAGS_DEBUG "-g -O0 -fsanitize=address")
set(CMAKE_CXX_FLAGS_DEBUG "-g -O0 -fsanitize=address")

# Release模式下开优化、去符号
set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG -flto")
set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG -flto")

# 针对特定目标的额外选项
target_compile_options(${PROJECT_NAME} PRIVATE
    $<$<BOOL:${ENABLE_SM2}>:-DSM2_ENABLED>
    $<$<BOOL:${ENABLE_SM3}>:-DSM3_ENABLED>
    $<$<BOOL:${ENABLE_SM4}>:-DSM4_ENABLED>
)

# 汇编器特殊处理（SM2的优化路径）
if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64")
    set_source_files_properties(
        src/asm/sm2_arm64.S
        PROPERTIES COMPILE_FLAGS "-march=armv8-a+crypto"
    )
endif()

你想想看，这样做的好处是什么？分层的配置可维护性极高。哪天想换个优化策略，改一个变量就行，不用满文件找编译选项。

个人习惯

我习惯用生成式表达式$<$<...>>来控制条件编译。这比if() ... endif()更紧凑，而且会在生成阶段才求值，避免缓存问题。

4.3 Debug/Release模式：不只是-O0和-O3的区别

很多人以为Debug就是不开优化加-g，Release就是开-O3。其实远不止这些。我给你列一个我项目里实际用到的配置表：

配置项	Debug	Release	为什么这么设？
优化等级	-O0	-O3 -flto	Debug要能单步跟踪，Release要极致性能
调试符号	-g	无（或-g1用于crash定位）	Release包体积小，但保留.gdb_index
断言	启用	禁用（-DNDEBUG）	Debug暴露问题，Release避免性能损耗
地址消毒	-fsanitize=address	关闭	ASan开销大，只用于调试
栈保护	-fstack-protector-strong	保持	安全性不能因为Release而放弃
符号可见性	-fvisibility=default	-fvisibility=hidden	Release只暴露API符号

这里有个细节要注意：-DNDEBUG会影响assert()宏，但不会影响你代码里自定义的GM_ASSERT。所以我通常再单独加一个-DGM_DEBUG来控制自己的调试宏：

# 自定义宏，用于国密SDK内部的调试日志
target_compile_definitions(${PROJECT_NAME} PRIVATE
    $<$<CONFIG:Debug>:GM_DEBUG_ENABLED>
)

踩坑提醒

我曾经在Release模式下忘了禁用ENABLE_TESTS的option()，结果测试代码里的静态函数全部被链接进了生产库。教训：一定要用target_compile_definitions配合生成式表达式做条件编译，别依赖源文件的#ifdef。

4.4 安装路径：让CI系统一眼找到

安装路径设置看似简单，但做不对会搞得CI脚本多出一堆硬编码。我推荐用GNUInstallDirs模块：

# 使用GNU标准目录布局
include(GNUInstallDirs)

# 现在可以安全地使用这些变量
# ${CMAKE_INSTALL_BINDIR}  -> bin
# ${CMAKE_INSTALL_LIBDIR}  -> lib 或 lib64 (自动适配)
# ${CMAKE_INSTALL_INCLUDEDIR} -> include

install(TARGETS ${PROJECT_NAME}
    EXPORT ${PROJECT_NAME}Targets
    # 动态库放lib
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    # 静态库放lib
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    # Windows上的DLL放bin
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

# 配置文件，方便其他项目find_package
install(EXPORT ${PROJECT_NAME}Targets
    FILE ${PROJECT_NAME}Targets.cmake
    NAMESPACE ${PROJECT_NAME}::
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}
)

实际使用的时候，用户通过-DCMAKE_INSTALL_PREFIX指定安装根目录。在CI系统里，我通常会设为项目下的install目录：

# CI脚本中的典型用法
cmake -B build -DCMAKE_INSTALL_PREFIX=$PWD/install -DCMAKE_BUILD_TYPE=Release
cmake --build build --target install

# 安装后结构
install/
├── bin/          # 可执行文件和DLL
├── lib/          # .so / .a / .lib
│   └── cmake/    # cmake配置文件
└── include/      # 头文件

最佳实践

我建议CMAKE_INSTALL_PREFIX在CI中用路径。曾经有同事用了相对路径，结果在不同工作目录下执行install，文件散落一地。从那以后我就养成了路径的习惯。

4.5 本章知识图谱

好了，上面讲的这些，我用一张图帮你串起来：

嗯，这张图基本把CMake构建系统的核心逻辑讲清楚了。你自己动手写CMakeLists.txt的时候，记住这个四步走：先搭结构、再配选项、选好模式、最后定出口。按这个顺序来，基本不会跑偏。