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_
  
• VS_GLOBAL_SECTION_PRE_
  
• 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 输出如下：

---

【结语】

项目链接(多多star呀.._)：

Github 地址：https://github.com/mengps/LearnCMake