7. 2.3 编译与链接控制

导语

在前面的章节中，我们已经学会了如何创建目标（Target）以及如何管理项目的源文件。如果说创建目标是在搭骨架、源文件管理是在填血肉，那么本节要讲解的编译与链接控制，就是为这个项目注入灵魂的关键一步。

在 Modern CMake 的范式中，我们不再使用全局的 add_definitions、add_compile_options 或 link_libraries 这些”大锅饭”式的命令，而是将编译定义、编译选项、链接选项统统绑定到具体的目标上，通过 PRIVATE、PUBLIC、INTERFACE 三种可见性精准控制它们的传播范围。本节将系统讲解这些命令的用法、编译器差异处理、循环依赖解决以及 C++ 标准的声明方式。

编译定义：target_compile_definitions

在 C/C++ 项目中，预处理器宏定义（Macro Definitions）是控制条件编译的常用手段。Modern CMake 使用 target_compile_definitions 命令为目标添加宏定义，彻底替代了旧式的 add_definitions。

基础语法与传播机制

target_compile_definitions(<target>
  <INTERFACE|PUBLIC|PRIVATE> [items1...]
  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]
)

三者的语义与前文介绍的保持一致：

• PRIVATE：仅当前目标自身编译时使用，不传递给依赖本目标的其他目标。
• PUBLIC：当前目标和所有链接了本目标的目标都会使用。
• INTERFACE：仅传递给链接了本目标的目标，当前目标自身编译时不用。

实战示例

假设我们有一个多版本号控制的场景：

# 库目标
add_library(my_lib STATIC src/my_lib.cpp)

# 库内部使用 PRIVATE，消费者不需要知道内部调试宏
target_compile_definitions(my_lib PRIVATE INTERNAL_DEBUG=1)

# 库的接口头文件中使用了 API_VERSION，消费者编译时也需要知道
target_compile_definitions(my_lib PUBLIC API_VERSION=2024)

# 可执行文件
add_executable(app main.cpp)
target_link_libraries(app PRIVATE my_lib)

# app 会自动继承 API_VERSION=2024，但不会继承 INTERNAL_DEBUG

在 C++ 代码中，你可以这样使用：

#include <iostream>

int main() {
#ifdef API_VERSION
    std::cout << "API Version: " << API_VERSION << std::endl;
#endif

#ifdef INTERNAL_DEBUG
    // 这行在 app 的 main.cpp 中不可见，因为 INTERNAL_DEBUG 是 PRIVATE 的
    std::cout << "Debug mode" << std::endl;
#endif
    return 0;
}

编译选项：target_compile_options

不同的编译器（GCC、Clang、MSVC）拥有各自的警告和优化选项。Modern CMake 推荐使用 target_compile_options 将编译器标志绑定到目标，而非全局设置。

基本用法

add_executable(demo demo.cpp)

# 为 demo 添加编译警告
target_compile_options(demo PRIVATE
  -Wall        # GCC/Clang：开启所有常见警告
  -Wextra      # 开启额外警告
  -Wpedantic   # 严格执行标准
)

编译器特定选项处理

上述示例在 MSVC 编译器下会报错，因为 MSVC 不认识 -Wall 这种 GCC 风格的参数。为了保证跨平台，我们必须针对编译器做条件处理。

方案一：使用 if 条件判断

add_executable(demo demo.cpp)

if (CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
  target_compile_options(demo PRIVATE
    -Wall -Wextra -Wpedantic -Werror
  )
elseif (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
  target_compile_options(demo PRIVATE
    /W4 /WX
  )
endif()

方案二：使用生成器表达式（推荐）

生成器表达式（Generator Expressions）可以在生成构建系统时动态计算，写法更加紧凑现代：

add_executable(demo demo.cpp)

target_compile_options(demo PRIVATE
  # GCC 和 Clang 的选项
  $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wall -Wextra -Wpedantic -Werror>
  
  # MSVC 的选项
  $<$<CXX_COMPILER_ID:MSVC>:/W4 /WX>
)

注意生成器表达式的语法规则：$<条件:真值>。当条件成立时，整个表达式会被替换为冒号后的内容。

条件添加选项：生成器表达式的深度应用

生成器表达式不仅能根据编译器类型做选择，还能根据构建配置（Debug/Release）、目标属性等条件动态调整选项。

根据构建类型配置选项

很多时候，我们希望 Debug 模式开启全调试信息并关闭优化，而 Release 模式开启最高优化：

add_executable(calc calc.cpp)

target_compile_options(calc PRIVATE
  # Debug 配置下
  $<$<CONFIG:Debug>:-O0 -g3>
  
  # Release 配置下
  $<$<CONFIG:Release>:-O3 -DNDEBUG>
  
  # RelWithDebInfo 配置下
  $<$<CONFIG:RelWithDebInfo>:-O2 -g -DNDEBUG>
)

为接口库统一编译警告（最佳实践）

在多目标项目中，为了统一所有目标的警告级别，可以创建一个 INTERFACE 库来打包这些配置：

add_library(project_warnings INTERFACE)

target_compile_options(project_warnings INTERFACE
  $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:
    -Wall -Wextra -Wpedantic -Wshadow -Wnon-virtual-dtor
  >
  $<$<CXX_COMPILER_ID:MSVC>:
    /W4 /permissive-
  >
)

# 所有其他目标链接这个接口库即可继承警告配置
add_executable(app1 main1.cpp)
target_link_libraries(app1 PRIVATE project_warnings)

add_executable(app2 main2.cpp)
target_link_libraries(app2 PRIVATE project_warnings)

链接选项：target_link_options

CMake 3.13 引入了 target_link_options，专门用于控制链接器标志（Linker Flags）。在此之前，人们往往被迫通过 target_link_libraries 传递链接器标志，这是一种不正规的权宜之计。

基础语法

target_link_options(<target>
  <INTERFACE|PUBLIC|PRIVATE> [items1...]
  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]
)

实战示例：链接时优化与特定段控制

add_executable(my_app main.cpp)

# 开启链接时优化（LTO），需要同时配合编译选项
include(CheckIPOSupported)
check_ipo_supported(RESULT ipo_supported)
if(ipo_supported)
  set_property(TARGET my_app PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
endif()

# 传递链接器标志：丢弃未使用的段（GCC/Clang）
target_link_options(my_app PRIVATE
  $<$<CXX_COMPILER_ID:GNU,Clang>:-Wl,--gc-sections>
  $<$<CXX_COMPILER_ID:MSVC>:/OPT:REF>
)

需要注意，链接器标志的语法在不同平台和工具链下差异极大。GCC/Clang 通常需要通过 -Wl, 前缀将选项传递给链接器，而 MSVC 则使用 / 风格。

链接库：target_link_libraries

target_link_libraries 是 CMake 中最常用的命令之一，它不仅用于连接外部依赖库，也用于连接项目内部的其他目标，并在此过程中自动传播 INTERFACE 和 PUBLIC 的编译定义、头文件路径以及链接选项。

连接多种类型的库

add_executable(app main.cpp)

# 1. 链接本项目内的其他目标
target_link_libraries(app PRIVATE my_lib)

# 2. 链接外部已安装的库（通过 find_package 找到的）
target_link_libraries(app PRIVATE Boost::filesystem OpenSSL::SSL)

# 3. 链接系统库或全路径库文件
target_link_libraries(app PRIVATE /usr/lib/x86_64-linux-gnu/libpthread.so)

# 4. 链接 CMake 未知但链接器认识的库名（-lxxx 风格）
target_link_libraries(app PRIVATE -ldl)

PRIVATE / PUBLIC / INTERFACE 在链接中的意义

假设存在三个目标：app → libB → libA。

• 如果 libB PUBLIC libA，则 app 在链接时会自动链接 libA，且能使用 libA 的 INTERFACE 头文件。
• 如果 libB PRIVATE libA，则 app 不会自动链接 libA，libA 对 app 不可见。
• 如果 libB INTERFACE libA，则 libB 自身不链接 libA，但 app 链接 libB 时会自动链接 libA。

链接顺序与循环依赖解析

传统 Unix 链接器（如 GNU ld）采用从左到右的单向解析策略。如果库 A 依赖库 B，而库 B 又依赖库 A，就会形成循环依赖（Circular Dependency）。

问题复现

假设 libmath 和 libutils 互相引用对方的符号：

add_library(math STATIC math.cpp)
add_library(utils STATIC utils.cpp)

# 错误示范：简单双向链接在某些链接器下会失败
target_link_libraries(math PRIVATE utils)
target_link_libraries(utils PRIVATE math)

add_executable(main main.cpp)
target_link_libraries(main PRIVATE math)

在某些严格链接器环境下，上述代码可能导致 “undefined reference” 错误。

解决方案一：重复链接（传统做法）

通过 CMake 的链接组（Link Group）让链接器反复扫描：

# GCC/Clang 可以使用 --start-group 和 --end-group
target_link_libraries(main PRIVATE
  -Wl,--start-group
  math
  utils
  -Wl,--end-group
)

解决方案二：使用 OBJECT 库避免循环（推荐）

如果两个库高度耦合，可以考虑将它们都改为 OBJECT 库，统一链接到最终目标中：

add_library(math_obj OBJECT math.cpp)
add_library(utils_obj OBJECT utils.cpp)

add_executable(main main.cpp)
target_link_libraries(main PRIVATE math_obj utils_obj)

解决方案三：CMake 3.13+ 的 LINK_INTERFACE_MULTIPLICITY

如果你明确知道某个接口库需要被链接多次才能解析所有符号，可以设置该属性：

set_target_properties(math PROPERTIES LINK_INTERFACE_MULTIPLICITY 3)

特殊需求：Whole-archive 全符号链接

静态库默认是按需链接的：链接器只会提取被实际引用的目标文件。这在某些场景下会导致问题，例如：

• 工厂模式或插件系统中，对象在全局构造函数中自动注册自身，但代码中没有显式引用该符号。
• 反射系统、单元测试框架（如自动发现的测试用例）。

各平台 Whole-archive 写法

不同平台、不同链接器的语法完全不同，需要借助生成器表达式做平台适配：

add_library(plugins STATIC plugin_a.cpp plugin_b.cpp)

add_executable(host_app main.cpp)

# 方式1：通过 target_link_options（CMake 3.13+ 推荐）
target_link_options(host_app PRIVATE
  # Linux/GCC
  $<$<PLATFORM_ID:Linux>:-Wl,--whole-archive plugins -Wl,--no-whole-archive>
  
  # macOS
  $<$<PLATFORM_ID:Darwin>:-Wl,-force_load,$<TARGET_FILE:plugins>>
  
  # Windows/MSVC
  $<$<PLATFORM_ID:Windows>:/WHOLEARCHIVE:plugins>
)

需要注意的是，Linux 下 --whole-archive 是链接器状态开关，后面必须跟 --no-whole-archive 恢复，否则可能导致系统库也被全量链接，产生冲突。

在 target_link_libraries 中传递（兼容旧版 CMake）

如果项目要求兼容 CMake 3.12 或更早版本，可以通过 target_link_libraries 直接传递链接器标志字符串：

if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
  target_link_libraries(host_app PRIVATE
    -Wl,--whole-archive
    plugins
    -Wl,--no-whole-archive
  )
elseif(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
  target_link_libraries(host_app PRIVATE
    -Wl,-force_load,$<TARGET_FILE:plugins>
  )
endif()

编译特性声明：target_compile_features

在 Modern CMake 中，不要直接使用全局变量 CMAKE_CXX_STANDARD 来强制 C++ 标准。相反，应该使用 target_compile_features 声明目标所需要的语言特性（Features）。

为什么使用特性而非直接指定标准？

• 精确表达需求：直接声明”我需要 lambda”、”我需要可变参数模板”等，而非笼统的”C++14″。
• 自动推导标准版本：编译器会根据所需特性自动开启对应的最小标准（如 -std=c++14）。
• 传播性：PUBLIC 特性会自动传递给消费者，让消费者也使用兼容的编译模式。

特性声明示例

add_library(network_lib STATIC socket.cpp)

target_compile_features(network_lib PUBLIC
  cxx_std_17           # 声明需要完整的 C++17 支持
  cxx_lambda_init_captures
  cxx_constexpr
)

CMake 官方为 C++11/14/17/20/23 都定义了完整的特性列表，你可以在 cmake --help-property CMAKE_CXX_KNOWN_FEATURES 中查看所有支持的特性名称。

C++ 标准指定：cxx_std_XX 元特性

如果你不想逐条列出语言特性，而希望直接声明目标依赖某个 C++ 标准版本，CMake 提供了元特性（Meta-Features）：

• c_std_99, c_std_11, c_std_17（C 语言）
• cxx_std_11, cxx_std_14, cxx_std_17, cxx_std_20, cxx_std_23（C++ 语言）

完整项目配置示例

cmake_minimum_required(VERSION 3.14)
project(ModernCppDemo CXX)

# 可执行文件
add_executable(demo src/main.cpp src/core.cpp)

# 明确要求 C++20
target_compile_features(demo PRIVATE cxx_std_20)

# 如果编译器不支持 C++20，CMake 会在配置阶段报错，而不是在编译阶段给出晦涩错误
set_target_properties(demo PROPERTIES
  CXX_STANDARD_REQUIRED ON   # 强制要求，不允许回退到更低版本
  CXX_EXTENSIONS OFF         # 禁用编译器私有扩展（如 gnu++20），严格使用标准 c++20
)

如果你设置 CXX_STANDARD_REQUIRED OFF（默认值），当编译器不支持 C++20 时，CMake 会静默回退到 C++17 或更低，这通常会导致编译错误。因此建议始终显式开启 CXX_STANDARD_REQUIRED ON。

接口库统一标准（最佳实践）

对于多目标的大型项目，可以创建一个接口库来统一 C++ 标准：

add_library(cpp_std INTERFACE)
target_compile_features(cpp_std INTERFACE cxx_std_20)
set_target_properties(cpp_std PROPERTIES
  CXX_STANDARD_REQUIRED ON
  CXX_EXTENSIONS OFF
)

# 所有目标统一链接
add_executable(app_a a.cpp)
add_executable(app_b b.cpp)
target_link_libraries(app_a PRIVATE cpp_std)
target_link_libraries(app_b PRIVATE cpp_std)

小结

本节我们深入探讨了 Modern CMake 对编译和链接过程的精细化控制，核心要点如下：

1. target_compile_definitions：为目标添加宏定义，替代旧式 add_definitions。
2. target_compile_options：绑定编译器标志，结合生成器表达式可实现跨平台编译器适配。
3. target_link_options（CMake 3.13+）：专门处理链接器标志，避免向 target_link_libraries 滥发标志。
4. target_link_libraries：链接依赖的核心命令，理解 PRIVATE/PUBLIC/INTERFACE 的传播机制是避免依赖混乱的关键。
5. 链接顺序与循环依赖：了解链接器解析顺序，善用 OBJECT 库或链接组解决循环依赖。
6. Whole-archive：在工厂模式、插件系统中，使用平台特定的链接器标志强制全量链接静态库符号。
7. target_compile_features：通过声明语言特性或 cxx_std_XX 元特性来管理 C++ 标准，取代全局变量设置。

掌握了这些工具，你就能够写出既能在 GCC/Clang 下顺利通过，又能在 MSVC 下无警告编译的健壮 CMake 脚本。下一节，我们将继续深入构建类型与配置，探索 Debug、Release 以及自定义配置类型的奥秘。