FeatureSummary¶

用於產生已啟用/停用功能的摘要的函式。

這些函式可用於產生建置樹的已啟用和停用套件和/或功能的摘要，例如

-- The following features have been enabled:

 * Example, usage example

-- The following OPTIONAL packages have been found:

 * LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org>
   Enables HTML-import in MyWordProcessor
   Enables odt-export in MyWordProcessor
 * PNG, image library, <http://www.libpng.org/pub/png/>
   Enables saving screenshots

-- The following OPTIONAL packages have not been found:

 * Lua, the Lua scripting language, <https://lua.dev.org.tw>
   Enables macros in MyWordProcessor
 * OpenGL, Open Graphics Library

全域屬性¶

FeatureSummary_PKG_TYPES¶

在 3.8 版本中新增。

此全域屬性定義以分號分隔的清單，其中包含 FeatureSummary 模組使用的套件類型。

此清單中的順序很重要，清單中的第一個套件類型的重要性最低，而最後一個的重要性最高。套件的類型只能變更為重要性更高的類型。

預設套件類型為 RUNTIME、OPTIONAL、RECOMMENDED 和 REQUIRED，其重要性等級為 RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED。

FeatureSummary_REQUIRED_PKG_TYPES¶

在 3.8 版本中新增。

此全域屬性定義以分號分隔的清單，其中包含被視為必要的套件類型。

如果未找到這些類別中的一個或多個套件，當呼叫 feature_summary() 命令並啟用 FATAL_ON_MISSING_REQUIRED_PACKAGES 選項時，CMake 將中止。

此全域屬性的預設值為 REQUIRED。

FeatureSummary_DEFAULT_PKG_TYPE¶

在 3.8 版本中新增。

此全域屬性定義預設套件類型。

當呼叫 feature_summary() 命令，且使用者未明確設定某些套件的類型時，其類型將設定為此值。

此值必須是 FeatureSummary_PKG_TYPES 全域屬性中定義的類型之一。

此全域屬性的預設值為 OPTIONAL。

FeatureSummary_<TYPE>_DESCRIPTION¶

在 3.9 版本中新增。

可以為每個套件 <TYPE> 定義此全域屬性，以設定將在 feature_summary() 命令的輸出標題中使用的字串。例如

The following <FeatureSummary_<TYPE>_DESCRIPTION> have been found:

如果未設定，則會使用預設字串 <TYPE> packages。

函式¶

feature_summary¶

feature_summary([FILENAME <file>]
                [APPEND]
                [VAR <variable_name>]
                [INCLUDE_QUIET_PACKAGES]
                [FATAL_ON_MISSING_REQUIRED_PACKAGES]
                [DESCRIPTION <description> | DEFAULT_DESCRIPTION]
                [QUIET_ON_EMPTY]
                WHAT (ALL
                     | PACKAGES_FOUND | PACKAGES_NOT_FOUND
                     | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
                     | ENABLED_FEATURES | DISABLED_FEATURES)
               )

此函式可用於列印專案的已啟用或停用套件和功能的相關資訊。依預設，只會列印功能/套件的名稱及其指定的必要版本。使用 set_package_properties() 新增更多實用資訊，例如各個套件的首頁 URL 或其在專案中的用途。

選項包括

WHAT

這是唯一必要的選項。它指定將列印哪些資訊

ALL: 列印所有內容。
ENABLED_FEATURES: 已啟用的所有功能清單。
DISABLED_FEATURES: 已停用的所有功能清單。
PACKAGES_FOUND: 已找到的所有套件清單。
PACKAGES_NOT_FOUND: 未找到的所有套件清單。

對於 FeatureSummary_PKG_TYPES 全域屬性定義的每個套件類型 <TYPE>，也可以使用以下資訊

<TYPE>_PACKAGES_FOUND: 僅已找到的 <TYPE> 類型套件的清單。
<TYPE>_PACKAGES_NOT_FOUND: 僅未找到的 <TYPE> 類型套件的清單。

在 3.1 版本中變更：WHAT 選項現在是多值關鍵字，因此可以組合這些值，但 ALL 值除外，以便自訂輸出。例如

feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)

FILENAME <file>

如果提供此選項，則資訊會列印到此檔案中，而不是終端機。相對 <file> 路徑會被解釋為相對於目前的原始碼目錄 (即 CMAKE_CURRENT_SOURCE_DIR)。

APPEND

如果提供此選項，則輸出會附加到 FILENAME 選項提供的 <file>，否則如果檔案已存在，則會覆寫該檔案。

VAR <variable_name>

如果提供此選項，則資訊會儲存在指定的變數 <variable_name> 中，而不是終端機。

DESCRIPTION <description>

將列印在實際內容上方的描述或標題。如果沒有此選項，如果僅要求一個套件類型，則不會列印標題，除非使用此選項明確設定自訂字串，或使用 DEFAULT_DESCRIPTION 選項輸出所要求類型的預設標題。

DEFAULT_DESCRIPTION

在 3.9 版本中新增。

要列印在內容上方的預設描述或標題，與可自訂的 DESCRIPTION <description> 相反。

INCLUDE_QUIET_PACKAGES

如果提供此選項，則也會列出使用 find_package(... QUIET) 搜尋的套件。依預設，它們會被略過。

FATAL_ON_MISSING_REQUIRED_PACKAGES

如果提供此選項，如果標記為 FeatureSummary_REQUIRED_PKG_TYPES 全域屬性中列出的套件類型之一的套件未找到，則 CMake 將中止並顯示嚴重錯誤。

可以修改 FeatureSummary_DEFAULT_PKG_TYPE 全域屬性，以變更使用者未明確指派時指派的預設套件類型。

QUIET_ON_EMPTY: 在 3.8 版本中新增。

如果提供此選項，當僅要求一個套件類型，且未找到屬於該類別的套件時，則不會列印任何輸出 (包括 DESCRIPTION)，也不會將其新增至 FILENAME 或 VAR 變數。

範例 1，將所有內容附加到檔案

include(FeatureSummary)
feature_summary(WHAT ALL
                FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)

範例 2，將已啟用的功能列印到變數 enabledFeaturesText 中，包括 QUIET 套件

include(FeatureSummary)
feature_summary(WHAT ENABLED_FEATURES
               INCLUDE_QUIET_PACKAGES
               DESCRIPTION "Enabled Features:"
               VAR enabledFeaturesText)
message(STATUS "${enabledFeaturesText}")

範例 3，新增自訂套件類型，且僅列印非空的類別

include(FeatureSummary)
set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
find_package(FOO)
set_package_properties(FOO PROPERTIES TYPE BUILD)
feature_summary(WHAT BUILD_PACKAGES_FOUND
                DESCRIPTION "Build tools found:"
                QUIET_ON_EMPTY)
feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
                DESCRIPTION "Build tools not found:"
                QUIET_ON_EMPTY)

set_package_properties¶

set_package_properties(<name> PROPERTIES
                       [URL <url>]
                       [DESCRIPTION <description>]
                       [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
                       [PURPOSE <purpose>]
                      )

使用此函式設定和提供有關名為 <name> 的套件的資訊，然後可以使用 feature_summary() 命令顯示這些資訊。可以直接在對應的 Find 模組中執行此操作，或在使用模組的專案中，在叫用 find_package() 呼叫之後執行。在 find_package() 命令之後，會自動判斷可以設定資訊的功能。

URL <url>: 這應該是套件的首頁，或類似的內容。理想情況下，這已直接在 Find 模組中設定。
DESCRIPTION <description>: 簡短描述套件的用途，最多一句話。理想情況下，這已直接在 Find 模組中設定。
TYPE <type>: 使用專案對該套件具有何種依賴性類型。預設值為 OPTIONAL。在這種情況下，它是一個專案在建置時可用時可以使用的套件，但即使沒有它也可以運作。RECOMMENDED 類似於 OPTIONAL，即，如果套件不存在，專案仍會建置，但產生的二進位檔的功能將受到嚴重限制。如果 REQUIRED 套件在建置時不可用，則專案甚至可能無法建置。這可以與 feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES) 命令選項結合使用。最後，RUNTIME 套件是在建置期間完全沒有使用的套件，但執行產生的二進位檔實際上需要該套件。因此，如果缺少此類套件，專案仍然可以建置，但稍後可能無法運作。如果針對具有不同 TYPE 的相同套件多次呼叫 set_package_properties()，則 TYPE 只會變更為較高的 TYPE (RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED)，較低的 TYPE 會被忽略。TYPE 屬性是專案特定的，因此無法由 Find 模組設定，但必須在專案中設定。可以透過設定 FeatureSummary_PKG_TYPES 全域屬性來變更接受的類型。
PURPOSE <purpose>: 這描述了此套件在專案中啟用的功能，即，它告訴使用者他們在產生的二進位檔中獲得的功能。如果多次針對套件呼叫 set_package_properties()，則所有 PURPOSE 屬性都會附加到專案中套件的用途清單中。與 TYPE 屬性一樣，PURPOSE 屬性也是專案特定的，因此無法由 Find 模組設定，但必須在專案中設定。

設定套件資訊的範例

include(FeatureSummary)
find_package(LibXml2)
set_package_properties(LibXml2 PROPERTIES
                       DESCRIPTION "XML library"
                       URL "http://xmlsoft.org")
# or
set_package_properties(LibXml2 PROPERTIES
                       TYPE RECOMMENDED
                       PURPOSE "Enables HTML-import in MyWordProcessor")
# or
set_package_properties(LibXml2 PROPERTIES
                       TYPE OPTIONAL
                       PURPOSE "Enables odt-export in MyWordProcessor")

find_package(DBUS)
set_package_properties(DBUS PROPERTIES
  TYPE RUNTIME
  PURPOSE "Necessary to disable the screensaver during a presentation")

add_feature_info¶

add_feature_info(<name> <enabled> <description>)

使用此函式新增有關以給定 <name> 識別的功能的資訊。<enabled> 包含此功能是否已啟用。它可以是變數或條件清單。<description> 是描述功能的文字。可以使用 feature_summary() 分別針對 ENABLED_FEATURES 和 DISABLED_FEATURES 顯示資訊。

在 3.8 版本中變更：<enabled> 可以是條件清單。

在 4.0 版本中變更：<enabled> 現在支援完整的條件語法。請參閱政策 CMP0183。

設定功能資訊的範例

include(FeatureSummary)

option(WITH_FOO "Help for foo" ON)
add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")

根據條件清單設定功能資訊的範例

option(WITH_FOO "Help for foo" ON)
option(WITH_BAR "Help for bar" OFF)
add_feature_info(
  FooBar
  "WITH_FOO;NOT WITH_BAR"
  "this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF"
)

根據完整條件語法設定功能資訊的範例

與以分號分隔的條件清單不同，這允許使用完整的條件語法作為 if 子句引數，例如使用括號和類似方式對條件進行分組。

option(WITH_FOO "Help for foo" ON)
option(WITH_BAR "Help for bar" ON)
option(WITH_BAZ "Help for baz" OFF)
add_feature_info(
  FooBarBaz
  "WITH_FOO AND (WITH_BAR OR WITH_BAZ)"
  "this feature is enabled when the entire condition is true"
)

已棄用的函式¶

提供以下舊版和已棄用的函式，以與先前的 CMake 版本向後相容

set_package_info¶

自 3.8 版本起已棄用。

set_package_info(<name> <description> [ <url> [<purpose>] ])

設定有關套件 <name> 的資訊，然後可以透過 feature_summary() 顯示這些資訊。可以直接在 Find 模組中執行此操作，或在使用 FeatureSummary 模組的專案中，在 find_package() 呼叫之後執行。可以設定資訊的功能由 find_package() 命令自動新增。

此函式已棄用。請改用 set_package_properties() 和 add_feature_info() 函式。

set_feature_info¶

自 3.8 版本起已棄用。

set_feature_info(<name> <description> [<url>])

與以下功能相同

set_package_info(<name> <description> [<url>])

print_enabled_features¶

自 3.8 版本起已棄用。

print_enabled_features()

與以下功能相同

feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")

print_disabled_features¶

自 3.8 版本起已棄用。

print_disabled_features()

與以下功能相同

feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")

FeatureSummary¶

全域屬性¶

函式¶

已棄用的函式¶

目錄

上一主題

下一主題

本頁