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    = associated with the global namespace
DIRECTORY = associated with one directory
TARGET    = associated with one target
SOURCE    = associated with one source file
TEST      = associated with a test named with add_test
VARIABLE  = documents a CMake language variable
CACHED_VARIABLE = documents a CMake cache variable

请注意，与 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() 的调用。在设置属性时没有继承行为，因此当 set_property() 命令与 APPEND 或 APPEND_STRING 配合使用时，在整理要附加的内容时不会考虑继承值。

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

另请参阅