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()