功能概要¶

生成启用/禁用功能摘要的函数。

这些函数可用于为构建树生成启用和禁用包和/或功能的摘要，例如：

-- 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., <http://www.lua.org>
   * 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 定义需要哪些包类型。

如果未找到此类别中的一个或多个包，CMake 将在启用“FATAL_ON_MISSING_REQUIRED_PACKAGES”选项的情况下调用 feature_summary() 时中止。

此全局属性的默认值为“REQUIRED”。

FeatureSummary_DEFAULT_PKG_TYPE¶

全局属性 FeatureSummary_DEFAULT_PKG_TYPE 定义了哪种包类型是默认类型。在调用 feature_summary() 时，如果用户没有明确设置包类型，包将被分配到这个类别。

该值必须是 FeatureSummary_PKG_TYPES 全局属性中定义的类型之一，除非为所有包都设置了包类型。

此全局属性的默认值为 OPTIONAL。

FeatureSummary_<TYPE>_DESCRIPTION¶

在 3.9 版本加入.

可以为每种类型定义全局属性 FeatureSummary_<TYPE>_DESCRIPTION，以便在输出字符串中使用包类型时将类型名称替换为指定的字符串。

如果未设置，则使用字符串“<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)
               )

feature_summary() 宏可用于打印有关启用或禁用的包或项目功能的信息。默认情况下，仅打印功能/包的名称以及指定时所需的版本。使用 set_package_properties() 添加更多有用的信息，例如各个包的下载 URL 或它们在项目中的用途。

WHAT 选项是唯一的强制选项。您可以在此处指定要打印的信息：

全部: 打印一切
ENABLED_FEATURES: 已启用的所有功能的列表
DISABLED_FEATURES: 禁用的所有功能的列表
PACKAGES_FOUND: 已找到的所有包的列表
PACKAGES_NOT_FOUND: 未找到的所有包的列表

对于由 FeatureSummary_PKG_TYPES 全局属性定义的每个包类型``<TYPE>``，还可以使用以下信息：

<TYPE>_PACKAGES_FOUND: 仅那些已找到类型为 <TYPE> 的包
<TYPE>_PACKAGES_NOT_FOUND: 仅那些尚未找到类型为 <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_package() 之后使用该模块的项目中完成。可以设置信息的特性由 find_package() 命令自动添加。

网址<网址>: 这应该是包的主页，或类似的东西。理想情况下，这已直接在查找模块中设置。
描述<描述>: 简短描述那个包是什么，最多一句话。理想情况下，这已直接在查找模块中设置。
类型<类型>: 什么类型的依赖项在该包上有使用项目。默认为“可选”。在这种情况下，它是一个包，在构建时可用时可供项目使用，但它也可以在没有时使用。 RECOMMENDED 类似于 OPTIONAL，即如果包不存在，项目将构建，但生成的二进制文件的功能将受到严重限制。如果在构建时“REQUIRED”包不可用，项目甚至可能无法构建。这可以与 feature_summary() 的 FATAL_ON_MISSING_REQUIRED_PACKAGES 参数结合使用。最后，RUNTIME 包是在构建过程中实际上根本不使用的包，但实际运行生成的二进制文件是必需的。所以如果缺少这样的包，项目仍然可以构建，但以后可能无法运行。如果 set_package_properties() 对具有不同类型的同一个包多次调用，TYPE 只会更改为更高的类型（RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED），较低的类型将被忽略. TYPE 属性是项目特定的，因此不能通过 Find-module 设置，但必须在项目中设置。可以通过设置 FeatureSummary_PKG_TYPES 全局属性来更改接受的类型。
目的<目的>: 这描述了这个包在项目中启用了哪些功能，即它告诉用户他在生成的二进制文件中获得了哪些功能。如果为包多次调用 set_package_properties()，所有 PURPOSE 属性将附加到项目中包的用途列表。与 TYPE 属性一样，PURPOSE 属性也是项目特定的，因此不能由 Find-module 设置，但必须在项目中设置。

设置包信息的示例：

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

使用此宏添加有关具有给定的“<name>”的功能的信息。 <enabled> 包含此功能是否启用。它可以是变量或条件列表。 <description> 是描述特征的文本。可以分别使用 feature_summary() 为 ENABLED_FEATURES` 和 DISABLED_FEATURES 显示信息。

在 3.8 版本发生变更: <enabled> 可以是条件列表。

设置功能信息的示例：

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_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:")

功能概要¶

全球资产¶

功能¶

遗留宏¶

目录

上一主题

下一主题

本页