CMake 属性之目录属性

【写在前面】

CMake 的目录属性是指在特定目录（及其子目录）范围内有效的设置。

这些属性不同于全局变量或目标（Target）属性，它们提供了一种机制，允许开发者为项目中的不同部分定义不同的构建行为。

通过目录属性，你可以指定编译器选项、包含路径、预处理定义等，而无需在每个目标或文件中重复这些设置。

【正文开始】

CMake 目录范围的属性有( CMake 3.30 )：

ADDITIONAL_CLEAN_FILES
BINARY_DIR
BUILDSYSTEM_TARGETS
CACHE_VARIABLES
CLEAN_NO_CUSTOM
CMAKE_CONFIGURE_DEPENDS
COMPILE_DEFINITIONS
COMPILE_OPTIONS
DEFINITIONS
EXCLUDE_FROM_ALL
IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
IMPORTED_TARGETS
INCLUDE_DIRECTORIES
INCLUDE_REGULAR_EXPRESSION
LABELS
LINK_DIRECTORIES
LINK_OPTIONS
LISTFILE_STACK
MACROS
PARENT_DIRECTORY
RULE_LAUNCH_COMPILE
RULE_LAUNCH_CUSTOM
RULE_LAUNCH_LINK
SOURCE_DIR
SUBDIRECTORIES
SYSTEM
TESTS
TEST_INCLUDE_FILES
VARIABLES
VS_GLOBAL_SECTION_POST_<section>
VS_GLOBAL_SECTION_PRE_<section>
VS_STARTUP_PROJECT

定义目录属性：

define_property( <DIRECTORY>PROPERTY <name> [INHERITED][BRIEF_DOCS <brief-doc> [docs...]][FULL_DOCS <full-doc> [docs...]][INITIALIZE_FROM_VARIABLE <variable>])
在范围内定义一个属性，用于 set_property() 和 get_property() 命令。它主要用于定义属性的初始化或继承方式。从历史上看，该命令还将文档与属性相关联，但这不再被视为主要用例。

示例：

# 定义一个名为 CURRENT_DIRECTORY 的目录属性
define_property(DIRECTORY # 目录属性的名称PROPERTY CURRENT_DIRECTORY# 简短的文档说明BRIEF_DOCS "The current directory"# 详细的文档说明FULL_DOCS "The current directory"
)

设置目录属性：

set_property(<[DIRECTORY <dirs> ...] [TARGET_DIRECTORY <targets> ...]>[APPEND] [APPEND_STRING]PROPERTY <name> [<value1> ...])
在范围的零个或多个对象上设置一个属性。

DIRECTORY 范围默认为当前目录，但其他目录（已由 CMake 处理）可以按完整路径或相对路径命名。相对路径被视为相对于当前源目录。另请参阅 set_directory_properties() 命令。

在 3.19 版本加入: <dir> 可以引用一个二进制目录。

如果给出 APPEND 选项，列表将附加到任何现有的属性值（除了忽略和不附加空值）。如果给出 APPEND_STRING 选项，字符串将作为字符串附加到任何现有属性值，即它会产生更长的字符串而不是字符串列表。当使用 APPEND 或 APPEND_STRING 以及定义为支持 INHERITED 行为的属性时（请参阅 :command:define_property），在找到要附加到的初始值时不会发生继承。如果该属性尚未在指定范围内直接设置，则该命令的行为就好像没有给出 APPEND 或 APPEND_STRING 一样。

示例：

# 设置当前目录属性为当前源代码目录
set_property(DIRECTORY PROPERTY CURRENT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})

其中，有一个专用于设置目录属性的命令：

set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
在键值对中设置当前目录及其子目录的属性。

另请参阅 set_property(DIRECTORY) 命令。

获取目录属性：

get_property(<[DIRECTORY <dir> | TARGET_DIRECTORY <target>]>PROPERTY <name>[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
从范围内的一个对象获取一个属性。

DIRECTORY 作用域默认为当前目录，但另一个目录（已由 CMake 处理）可能由完整或相对路径命名为“<dir>”。相对路径被视为相对于当前源目录。另请参阅 get_directory_property() 命令。

在 3.19 版本加入: <dir> 可以引用一个二进制目录。

如果给出了 SET 选项，变量将被设置为一个布尔值，指示该属性是否已被设置。如果给出了 DEFINED 选项，变量将被设置为一个布尔值，指示该属性是否已被定义，例如使用 define_property 命令。如果给出了``BRIEF_DOCS`` 或``FULL_DOCS``，那么该变量将被设置为一个字符串，其中包含所请求属性的文档。如果为尚未定义的属性请求文档，则返回“NOTFOUND”。

示例：

# 获取当前目录属性
get_property(CURRENT_DIR DIRECTORY PROPERTY CURRENT_DIRECTORY)

其中，有一个专用于获取目录属性的命令：

get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
将目录范围的属性存储在命名的``<variable>``中。

DIRECTORY 参数指定从中检索属性值的另一个目录，而不是当前目录。相对路径被视为相对于当前源目录。 CMake 必须已经知道该目录，或者通过调用 add_subdirectory 添加它或者是顶级目录。

在 3.19 版本加入: <dir> 可以引用一个二进制目录。

如果没有为指定的目录范围定义该属性，则返回一个空字符串。对于 INHERITED 属性，如果在指定的目录范围内找不到该属性，则搜索将链接到父范围，如 define_property() 命令所述。
get_directory_property(<variable> [DIRECTORY <dir>]DEFINITION <var-name>)
从目录中获取变量定义。这种形式对于从另一个目录获取变量定义很有用。

示例：

# 添加预处理定义，定义宏TEST_DEFINED的值为1
add_compile_definitions(TEST_DEFINED=1)# 获取当前目录的属性COMPILE_DEFINITIONS，即定义的宏
get_directory_property(DEFS COMPILE_DEFINITIONS) # 打印获取到的定义信息
message("DEFS: ${DEFS}")

最后完整测试一遍：

# 要求 CMake 最低版本为 3.16
cmake_minimum_required(VERSION 3.16)# 定义一个名为 CURRENT_DIRECTORY 的目录属性
define_property(DIRECTORY # 目录属性的名称PROPERTY CURRENT_DIRECTORY# 简短的文档说明BRIEF_DOCS "The current directory"# 详细的文档说明FULL_DOCS "The current directory"
)# 设置当前目录属性为当前源代码目录
set_property(DIRECTORY PROPERTY CURRENT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})# 获取当前目录属性
get_property(CURRENT_DIR DIRECTORY PROPERTY CURRENT_DIRECTORY)# 打印当前目录信息
message("CURRENT_DIR: ${CURRENT_DIR}")# 添加预处理定义，定义宏TEST_DEFINED的值为1
add_compile_definitions(TEST_DEFINED=1)# 获取当前目录的属性COMPILE_DEFINITIONS，即定义的宏
get_directory_property(DEFS COMPILE_DEFINITIONS) # 打印获取到的定义信息
message("DEFS: ${DEFS}")# 将库目录链接到当前目录下的lib目录
link_directories(${CMAKE_CURRENT_SOURCE_DIR}/lib)# 获取链接目录属性
get_property(LINK_DIR DIRECTORY PROPERTY LINK_DIRECTORIES)# 获取源目录属性
get_property(S_DIR DIRECTORY PROPERTY SOURCE_DIR)# 打印链接目录和源目录信息
message("LINK_DIR: ${LINK_DIR} S_DIR: ${S_DIR}")# 设置当前目录及其子目录的编译器标志  
set_directory_properties(PROPERTIES COMPILE_FLAGS "-Wall -Wextra")# 获取当前目录的编译标志
get_directory_property(COMPILE_FLAGS COMPILE_FLAGS)# 打印获取到的编译标志信息
message("COMPILE_FLAGS: ${COMPILE_FLAGS}")

CMake 输出如下：