第9章属性机制

课程目录第9章属性机制

属性机制：理解CMake的属性（Properties）系统

CMake的属性系统，说白了就是一套“贴标签”的机制。你可以给目标、目录、源文件甚至测试用例贴上各种属性标签，然后CMake根据这些标签来决定怎么编译、怎么链接。

我刚开始接触CMake时，总觉得属性这东西可有可无。直到有一次，我需要给某个库单独设置C++标准，而其他目标保持不变。折腾了半天全局变量，最后发现一个set_property就搞定了。嗯，从那以后我再也不敢小看属性系统了。

属性到底是什么？

属性就是CMake内部维护的键值对。每个属性都有一个名字和一个值。你可以把它想象成对象的成员变量——只不过这个对象可能是目标、目录、源文件，甚至是整个工程。

举个例子：

# 给一个目标设置属性
set_property(TARGET myapp PROPERTY CXX_STANDARD 17)

# 读取这个属性
get_property(standard TARGET myapp PROPERTY CXX_STANDARD)
message("C++标准: ${standard}")

这里CXX_STANDARD就是属性名，17就是属性值。简单吧？

属性的作用域

属性不是随便乱贴的。CMake把属性分成了几个作用域：

作用域	适用对象	典型用途
GLOBAL	整个工程	全局编译选项、全局定义
DIRECTORY	当前CMakeLists.txt所在目录	目录级别的编译选项
TARGET	单个目标（库、可执行文件）	目标特定的编译/链接选项
SOURCE	单个源文件	源文件级别的编译选项
TEST	测试用例	测试超时、环境变量

我个人习惯是：能用TARGET级别的，绝不用GLOBAL。为什么？因为TARGET级别的属性只影响一个目标，不会污染其他目标。你想想看，如果全局改了CXX_STANDARD，所有目标都得跟着变，这多危险。

set_property 的完整用法

set_property的语法其实很灵活：

set_property(<作用域> <对象列表>
             PROPERTY <属性名> [APPEND] [APPEND_STRING] <值>)

几个关键点：

作用域：GLOBAL、DIRECTORY、TARGET、SOURCE、TEST
对象列表：目标名、目录路径、源文件路径等
APPEND：追加到已有值后面（列表形式）
APPEND_STRING：以字符串形式追加

来看个实际例子。我在项目中遇到过这样一个场景：一个库需要同时支持静态和动态编译，但两者的编译选项不同。

# 创建两个目标
add_library(mylib_static STATIC src/mylib.cpp)
add_library(mylib_shared SHARED src/mylib.cpp)

# 给静态库设置不同的编译选项
set_property(TARGET mylib_static PROPERTY COMPILE_DEFINITIONS
             "MYLIB_STATIC_BUILD")

# 给动态库设置导出宏
set_property(TARGET mylib_shared PROPERTY COMPILE_DEFINITIONS
             "MYLIB_SHARED_BUILD;MYLIB_EXPORTS")

# 追加方式：保留原有属性，再加新的
set_property(TARGET mylib_shared PROPERTY COMPILE_DEFINITIONS
             APPEND "EXTRA_FEATURE_ENABLED")

注意那个APPEND关键字。如果不加，COMPILE_DEFINITIONS会被完全覆盖。加了之后，新值会追加到原有值后面。这个细节坑过我好几次，你一定要注意。

get_property 的完整用法

有存就有取。get_property的语法：

get_property(<输出变量> <作用域> <对象>
             PROPERTY <属性名> [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])

几个变体：

SET：检查属性是否被设置过（返回TRUE/FALSE）
DEFINED：检查属性是否被定义（包括默认值）
BRIEF_DOCS：获取属性的简短文档
FULL_DOCS：获取属性的完整文档

# 获取目标的C++标准
get_property(cxx_std TARGET myapp PROPERTY CXX_STANDARD)
message("C++标准: ${cxx_std}")

# 检查属性是否被设置过
get_property(is_set TARGET myapp PROPERTY CXX_STANDARD SET)
if(is_set)
  message("CXX_STANDARD 被显式设置过")
else()
  message("CXX_STANDARD 使用的是默认值")
endif()

# 获取属性的文档（调试时很有用）
get_property(docs TARGET myapp PROPERTY CXX_STANDARD BRIEF_DOCS)
message("CXX_STANDARD 说明: ${docs}")

这里有个小技巧：用SET和DEFINED可以区分“用户没设置”和“用了默认值”。我在调试复杂项目时经常用这个来排查问题。

常用属性一览

CMake内置了上百个属性，但常用的其实就这些：

属性名	作用域	说明
CXX_STANDARD	TARGET	C++标准版本（11/14/17/20/23）
CXX_STANDARD_REQUIRED	TARGET	是否强制要求指定标准
COMPILE_DEFINITIONS	TARGET, DIRECTORY	编译宏定义
COMPILE_OPTIONS	TARGET, DIRECTORY	编译选项
LINK_LIBRARIES	TARGET	链接的库
INCLUDE_DIRECTORIES	TARGET, DIRECTORY	头文件搜索路径
OUTPUT_NAME	TARGET	输出文件名
FOLDER	TARGET	IDE中的文件夹分组

属性系统的核心逻辑

为了让你更直观地理解属性系统的工作方式，我画了一张图：

实战：精细控制目标行为

光说不练假把式。来看一个完整的例子，展示如何用属性系统精细控制目标行为。

# 一个复杂的库项目
cmake_minimum_required(VERSION 3.20)
project(PropertyDemo LANGUAGES CXX)

# 创建库目标
add_library(core STATIC
  src/core.cpp
  src/utils.cpp
  src/io.cpp
)

# 设置C++标准
set_property(TARGET core PROPERTY CXX_STANDARD 20)
set_property(TARGET core PROPERTY CXX_STANDARD_REQUIRED ON)

# 设置编译宏
set_property(TARGET core PROPERTY COMPILE_DEFINITIONS
  "CORE_LIBRARY"
  "USE_OPENSSL"
)

# 设置头文件搜索路径
set_property(TARGET core PROPERTY INCLUDE_DIRECTORIES
  ${CMAKE_CURRENT_SOURCE_DIR}/include
  ${CMAKE_CURRENT_SOURCE_DIR}/third_party
)

# 设置编译选项（针对特定平台）
if(WIN32)
  set_property(TARGET core PROPERTY COMPILE_OPTIONS
    "/W4" "/utf-8"
  )
else()
  set_property(TARGET core PROPERTY COMPILE_OPTIONS
    "-Wall" "-Wextra" "-Wpedantic"
  )
endif()

# 设置输出文件名
set_property(TARGET core PROPERTY OUTPUT_NAME "core_engine")

# 设置IDE文件夹
set_property(TARGET core PROPERTY FOLDER "Libraries")

# 创建可执行文件
add_executable(app main.cpp)
target_link_libraries(app PRIVATE core)

# 给可执行文件单独设置属性
set_property(TARGET app PROPERTY CXX_STANDARD 17)
set_property(TARGET app PROPERTY COMPILE_DEFINITIONS APPEND "APP_BUILD")

# 读取并打印属性
get_property(app_std TARGET app PROPERTY CXX_STANDARD)
get_property(core_std TARGET core PROPERTY CXX_STANDARD)
message("app C++标准: ${app_std}")
message("core C++标准: ${core_std}")

这个例子展示了几个关键点：

不同目标可以有完全不同的属性配置
属性可以按平台、按配置条件设置
APPEND关键字可以保留已有属性值
用get_property可以随时检查属性状态

核心原则：属性系统遵循“就近覆盖”原则。目标属性优先于目录属性，目录属性优先于全局属性。如果你在多个地方设置了同一个属性，最具体的那个会生效。

我的建议：尽量使用TARGET级别的属性。这样每个目标都是独立的，不会互相影响。如果你发现某个属性需要被多个目标共享，再考虑提升到DIRECTORY级别。

我曾经踩过的坑：有一次我同时用了set_property和target_compile_definitions来设置同一个目标的宏定义。结果发现后者覆盖了前者。后来才搞清楚：target_*系列命令内部也是调用set_property，但它们的调用顺序会影响最终结果。所以我的建议是：统一用一种方式，不要混用。

属性的继承与覆盖

属性的继承规则其实很简单：

全局属性：所有目录和目标都能看到
目录属性：当前目录及其子目录能看到
目标属性：只有该目标能看到

当同一个属性在多个层级被设置时：

# 全局设置
set_property(GLOBAL PROPERTY COMPILE_DEFINITIONS "GLOBAL_DEFINE")

# 目录设置（会覆盖全局）
set_property(DIRECTORY PROPERTY COMPILE_DEFINITIONS "DIR_DEFINE")

# 目标设置（会覆盖目录）
set_property(TARGET mylib PROPERTY COMPILE_DEFINITIONS "TARGET_DEFINE")

# 最终 mylib 的 COMPILE_DEFINITIONS 只有 "TARGET_DEFINE"
# 除非用了 APPEND

这里要注意：如果不加APPEND，子层级的设置会完全覆盖父层级的。加了APPEND才会合并。

总结

属性系统是CMake的“神经系统”。它让每个目标、每个目录、每个源文件都能有自己的配置。掌握了set_property和get_property，你就能精细控制构建过程的每一个细节。

我个人觉得，属性系统最大的价值在于“隔离”。每个目标独立配置，互不干扰。这在大型项目中尤其重要——你改了一个目标的属性，不会影响到其他几十个目标。

嗯，关于属性系统就讲这么多。记住：能用TARGET别用DIRECTORY，能用DIRECTORY别用GLOBAL。这个原则能帮你避免很多麻烦。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

属性机制：理解CMake的属性（Properties）系统

属性到底是什么？

属性的作用域

set_property 的完整用法

get_property 的完整用法

常用属性一览

属性系统的核心逻辑

实战：精细控制目标行为

属性的继承与覆盖

总结