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