FeatureSummary¶

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

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

-- The following OPTIONAL packages have been found:
LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
   * Enables HTML-import in MyWordProcessor
   * Enables odt-export in MyWordProcessor
PNG, A PNG image library., <http://www.libpng.org/pub/png/>
   * Enables saving screenshots
-- The following OPTIONAL packages have not been found:
Lua51, The Lua scripting language., <https://lua.dev.org.tw>
   * Enables macros in MyWordProcessor
Foo, Foo provides cool stuff.

全域屬性¶

FeatureSummary_PKG_TYPES¶

全域屬性 FeatureSummary_PKG_TYPES 定義 FeatureSummary 使用的套件類型。

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

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

FeatureSummary_REQUIRED_PKG_TYPES¶

全域屬性 FeatureSummary_REQUIRED_PKG_TYPES 定義哪些套件類型是必要的。

如果在這些類別中找到一個或多個套件，則在啟用「FATAL_ON_MISSING_REQUIRED_PACKAGES」選項的情況下呼叫 feature_summary() 時，CMake 將會中止。

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

FeatureSummary_DEFAULT_PKG_TYPE¶

全域屬性 FeatureSummary_DEFAULT_PKG_TYPE 定義哪個套件類型是預設類型。當呼叫 feature_summary() 時，如果使用者未明確設定套件類型，則該套件將被指派到此類別。

此值必須是 FeatureSummary_PKG_TYPES 全域屬性中定義的類型之一，除非為所有套件設定了套件類型。

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

FeatureSummary_<TYPE>_DESCRIPTION¶

在 3.9 版本中新增。

可以為每個類型定義全域屬性 FeatureSummary_<TYPE>_DESCRIPTION，以便在輸出字串中使用套件類型時，將類型名稱取代為指定的字串。

如果未設定，則會使用字串「<TYPE> 套件」。

函式¶

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

可以使用 feature_summary() 巨集來列印專案的已啟用或停用套件或功能的相關資訊。預設情況下，只會列印功能/套件的名稱，以及指定時所需的版本。使用 set_package_properties() 來新增更多有用的資訊，例如個別套件的下載 URL 或它們在專案中的用途。

WHAT 選項是唯一強制性的選項。您可以在此處指定將列印的資訊

全部: 列印所有內容
已啟用功能: 所有已啟用功能的清單
已停用功能: 所有已停用功能的清單
已找到的套件: 所有已找到套件的清單
未找到的套件: 所有未找到套件的清單

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

已找到的 <TYPE> 套件: 僅那些已找到且類型為 <TYPE> 的套件
未找到的 <TYPE> 套件: 僅那些未找到且類型為 <TYPE> 的套件

在 3.1 版中變更：除了 ALL 值之外，這些值可以組合以自訂輸出。例如

feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)

如果提供 FILENAME，則會將資訊列印到此檔案中。如果使用 APPEND，則會將其附加到此檔案，否則如果檔案已存在，則會覆寫該檔案。如果使用 VAR 選項，則資訊會「列印」到指定的變數中。如果未使用 FILENAME，則會將資訊列印到終端機。使用 DESCRIPTION 選項可以設定描述或標題，其將列印在實際內容上方。如果只要求一種套件類型，則不會列印標題，除非使用 DESCRIPTION 來使用自訂字串，或使用 DEFAULT_DESCRIPTION 來使用所要求類型的預設標題來明確設定標題。如果提供 INCLUDE_QUIET_PACKAGES，則也會列出已使用 find_package(... QUIET) 搜尋的套件。預設情況下，會跳過這些套件。如果提供 FATAL_ON_MISSING_REQUIRED_PACKAGES，如果未找到標記為 FeatureSummary_REQUIRED_PKG_TYPES 全域屬性中列出的套件類型之一的套件，CMake 將會中止。FeatureSummary_REQUIRED_PKG_TYPES 全域屬性的預設值為 REQUIRED。

在 3.9 版中新增：DEFAULT_DESCRIPTION 選項。

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

在 3.8 版中新增：如果使用 QUIET_ON_EMPTY 選項，如果只要求一種套件類型，且未找到屬於該類別的套件，則不會列印任何輸出（包括 DESCRIPTION）或將輸出新增至 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> ]
                      )

使用此巨集來設定有關具名套件的資訊，然後可以透過 FEATURE_SUMMARY() 顯示該資訊。這可以直接在 Find 模組中或在使用 find_package() 呼叫之後使用模組的專案中完成。可以使用 find_package() 命令自動新增可設定資訊的功能。

URL <url>: 這應該是套件的首頁，或類似的頁面。理想情況下，這應該直接在 Find 模組中設定。
DESCRIPTION <描述>: 簡短描述該套件是什麼，最多一句話。理想情況下，這應該直接在 Find 模組中設定。
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 <目的>: 這描述了這個套件在專案中啟用了哪些功能，也就是說，它告訴使用者在產生的二進制檔案中得到了哪些功能。如果針對一個套件多次呼叫 set_package_properties()，所有 PURPOSE 屬性都會附加到專案中套件的目的清單中。與 TYPE 屬性一樣，PURPOSE 屬性也是專案特定的，因此不能由 Find 模組設定，而必須在專案中設定。

設定套件資訊的範例

find_package(LibXml2)
set_package_properties(LibXml2 PROPERTIES
                       DESCRIPTION "A XML processing 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>)

使用此巨集來新增有關具有指定 <名稱> 的功能資訊。<已啟用> 包含此功能是否已啟用。它可以是一個變數或一組條件。<描述> 是描述該功能的文字。可以使用 feature_summary() 分別顯示 ENABLED_FEATURES 和 DISABLED_FEATURES 的資訊。

變更於 3.8 版: <已啟用> 可以是一組條件。

設定功能資訊的範例

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

舊版巨集¶

提供以下巨集是為了與先前的 CMake 版本相容

set_package_info¶

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

使用此巨集設定有關指定名稱套件的資訊，然後可以透過 feature_summary() 顯示。這可以直接在 Find 模組中完成，也可以在使用模組的專案中，在呼叫 find_package() 之後完成。可以使用 find_package() 命令自動新增可設定資訊的功能。

set_feature_info¶

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

功能與此相同

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

print_enabled_features¶

print_enabled_features()

功能與此相同

feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")

print_disabled_features¶

print_disabled_features()

功能與此相同

feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")

FeatureSummary¶

全域屬性¶

函式¶

舊版巨集¶

目錄

上一主題

下一主題

本頁