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