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() 的呼叫。*設定* 屬性時沒有繼承行為，因此將 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()

另請參閱