define_property

定义和记录自定义属性。

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 - 与全局命名空间关联。

• DIRECTORY - 与一个目录关联。

• TARGET - 与一个目标关联。

• SOURCE - 与一个源文件关联。

• TEST - 与使用 add_test() 命令命名的测试关联。

• VARIABLE - 文档化一个 CMake 语言变量。

• CACHED_VARIABLE - 文档化一个 CMake 缓存变量。

请注意，与 set_property() 和 get_property() 不同，不需要给出实际的作用域；只有作用域类型是重要的。

必需的 PROPERTY 选项后面直接跟着要定义的属性的名称。

如果提供了 INHERITED 选项，那么当命令给定作用域中请求的属性未设置时，get_property() 命令将向上链接到下一个更高一级的作用域。

• DIRECTORY 作用域会链接到其父目录的作用域，并继续向上遍历父目录，直到找到已设置属性的目录，或者没有更多父目录。如果在顶层目录仍未找到，它将链接到 GLOBAL 作用域。

• TARGET、SOURCE 和 TEST 属性会链接到 DIRECTORY 作用域，包括根据需要向上链接目录等。

请注意，这种作用域链接行为仅适用于调用 get_property()、get_directory_property()、get_target_property()、get_source_file_property() 和 get_test_property() 的调用。在设置属性时没有继承行为，因此使用 APPEND 或 APPEND_STRING 配合 set_property() 命令在计算要附加的内容时不会考虑继承的值。

BRIEF_DOCS 和 FULL_DOCS 选项后面跟着要与属性关联的字符串，作为其简短和完整的文档。CMake 不使用此文档，除非通过 get_property() 命令的相应选项使其可供项目使用。

3.23 版本已更改： BRIEF_DOCS 和 FULL_DOCS 选项是可选的。

3.23 版本已添加： INITIALIZE_FROM_VARIABLE 选项指定了一个属性应从中初始化的变量。它只能与目标属性一起使用。<variable> 名称必须以属性名结尾，并且不得以 CMAKE_ 或 _CMAKE_ 开头。属性名必须至少包含一个下划线。建议属性名具有项目特定的前缀。

属性重定义

一旦为特定类型的作用域定义了一个属性，就不能重新定义它。尝试通过调用 define_property() 并使用相同的 प्रकारचे作用域和属性名称来重新定义现有属性将被静默忽略。为两种不同的作用域类型定义相同的属性名称是有效的。

get_property() 可用于确定某个属性是否已为特定类型的作用域定义，如果是，则检查其定义。例如：

# Initial definition
define_property(TARGET PROPERTY MY_NEW_PROP
  BRIEF_DOCS "My new custom property"
)

# Later examination
get_property(my_new_prop_exists
  TARGET NONE
  PROPERTY MY_NEW_PROP
  DEFINED
)

if(my_new_prop_exists)
  get_property(my_new_prop_docs
    TARGET NONE
    PROPERTY MY_NEW_PROP
    BRIEF_DOCS
  )
  # ${my_new_prop_docs} is now set to "My new custom property"
endif()

另请参阅

• get_property()

• set_property()