CMake 属性之全局属性

【写在前面】

        CMake 的全局属性是指在 CMake 配置过程中，对整个项目范围生效的设置。

        这些属性不同于目标 ( Target ) 属性或目录 ( Directory ) 属性，后者仅对特定的目标或目录生效。

---

【正文开始】

        CMake 全局范围的属性有( CMake 3.30 )：

• ALLOW_DUPLICATE_CUSTOM_TARGETS
• AUTOGEN_SOURCE_GROUP
• AUTOGEN_TARGETS_FOLDER
• AUTOMOC_SOURCE_GROUP
• AUTOMOC_TARGETS_FOLDER
• AUTORCC_SOURCE_GROUP
• AUTOUIC_SOURCE_GROUP
• CMAKE_C_KNOWN_FEATURES
• CMAKE_CUDA_KNOWN_FEATURES
• CMAKE_CXX_KNOWN_FEATURES
• CMAKE_HIP_KNOWN_FEATURES
• CMAKE_ROLE
• DEBUG_CONFIGURATIONS
• DISABLED_FEATURES
• ECLIPSE_EXTRA_CPROJECT_CONTENTS
• ECLIPSE_EXTRA_NATURES
• ENABLED_FEATURES
• ENABLED_LANGUAGES
• FIND_LIBRARY_USE_LIB32_PATHS
• FIND_LIBRARY_USE_LIB64_PATHS
• FIND_LIBRARY_USE_LIBX32_PATHS
• FIND_LIBRARY_USE_OPENBSD_VERSIONING
• GENERATOR_IS_MULTI_CONFIG
• GLOBAL_DEPENDS_DEBUG_MODE
• GLOBAL_DEPENDS_NO_CYCLES
• INSTALL_PARALLEL
• IN_TRY_COMPILE
• JOB_POOLS
• PACKAGES_FOUND
• PACKAGES_NOT_FOUND
• PREDEFINED_TARGETS_FOLDER
• PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE
• REPORT_UNDEFINED_PROPERTIES
• RULE_LAUNCH_COMPILE
• RULE_LAUNCH_CUSTOM
• RULE_LAUNCH_LINK
• RULE_MESSAGES
• TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
• TARGET_MESSAGES
• TARGET_SUPPORTS_SHARED_LIBS
• USE_FOLDERS
• XCODE_EMIT_EFFECTIVE_PLATFORM_NAME

        定义全局属性：

define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                 TEST | VARIABLE | CACHED_VARIABLE>
                 PROPERTY <name> [INHERITED]
                 [BRIEF_DOCS <brief-doc> [docs...]]
                 [FULL_DOCS <full-doc> [docs...]]
                 [INITIALIZE_FROM_VARIABLE <variable>])

在范围内定义一个属性，用于 set_property() 和 get_property() 命令。它主要用于定义属性的初始化或继承方式。从历史上看，该命令还将文档与属性相关联，但这不再被视为主要用例。

        示例： 

# 定义一个名为 GLOBAL_PROPERTY_TEST 的全局属性
define_property(GLOBAL 
    # 全局属性的名称
    PROPERTY GLOBAL_PROPERTY_TEST
    # 简短的文档说明
    BRIEF_DOCS "A global property test"
    # 完整的文档说明
    FULL_DOCS "A global property test"
)

         设置全局属性：    

set_property(<GLOBAL                      |
              DIRECTORY [<dir>]           |
              TARGET    [<target1> ...]   |
              SOURCE    [<src1> ...]
                        [DIRECTORY <dirs> ...]
                        [TARGET_DIRECTORY <targets> ...] |
              INSTALL   [<file1> ...]     |
              TEST      [<test1> ...]     |
              CACHE     [<entry1> ...]    >
             [APPEND] [APPEND_STRING]
             PROPERTY <name> [<value1> ...])

在范围的零个或多个对象上设置一个属性。

GLOBAL 范围是唯一的，不接受名称。

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

        示例：

# 设置全局属性 GLOBAL_PROPERTY_TEST 为 ON
set_property(GLOBAL PROPERTY GLOBAL_PROPERTY_TEST ON)

         获取全局属性：

get_property(<variable>
             <GLOBAL             |
              DIRECTORY [<dir>]  |
              TARGET    <target> |
              SOURCE    <source>
                        [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
              INSTALL   <file>   |
              TEST      <test>   |
              CACHE     <entry>  |
              VARIABLE           >
             PROPERTY <name>
             [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])

从范围内的一个对象获取一个属性。

GLOBAL 范围是唯一的，不接受名称。

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

        示例：

# 获取全局属性 GLOBAL_PROPERTY_TEST 的值，并将结果存储在变量 IS_GLOBAL 中
get_property(IS_GLOBAL GLOBAL PROPERTY GLOBAL_PROPERTY_TEST)

        其中，有一个专用于获取 CMake 全局属性命令：

get_cmake_property(<var> <property>)

从 CMake 实例获取全局属性。 <property> 的值存储在变量``<var>`` 中。如果未找到该属性，<var> 将被设置为 NOTFOUND。有关可用属性，请参阅 cmake-properties(7) 手册。

除了全局属性，此命令（出于历史原因）还支持 VARIABLES 和 MACROS 目录属性。它还支持一个特殊的 COMPONENTS 全局属性，该属性列出了提供给 install() 命令的组件。

         示例：

# 获取当前 CMake 角色，并将结果存储在变量 ROLE 中
get_cmake_property(ROLE CMAKE_ROLE)

        最后完整测试一遍：

# 要求 CMake 最低版本为 3.16
cmake_minimum_required(VERSION 3.16)

# 定义一个名为 GLOBAL_PROPERTY_TEST 的全局属性
define_property(GLOBAL 
    # 全局属性的名称
    PROPERTY GLOBAL_PROPERTY_TEST
    # 简短的文档说明
    BRIEF_DOCS "A global property test"
    # 完整的文档说明
    FULL_DOCS "A global property test"
)

# 设置全局属性 GLOBAL_PROPERTY_TEST 为 ON
set_property(GLOBAL PROPERTY GLOBAL_PROPERTY_TEST ON)

# 获取全局属性 GLOBAL_PROPERTY_TEST 的值，并将结果存储在变量 IS_GLOBAL 中
get_property(IS_GLOBAL GLOBAL PROPERTY GLOBAL_PROPERTY_TEST)

# 打印变量 IS_GLOBAL 的值，用于确认全局属性是否已设置
message("IS_GLOBAL: ${IS_GLOBAL}")

# 获取当前 CMake 角色，并将结果存储在变量 ROLE 中
get_cmake_property(ROLE CMAKE_ROLE)

# 打印变量 ROLE 的值，用于显示当前 CMake 角色
message("ROLE: ${ROLE}")

         CMake 输出如下：

---

【结语】

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

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