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.ac.cn>
   * Enables macros in MyWordProcessor
Foo, Foo provides cool stuff.

全局属性¶

FeatureSummary_PKG_TYPES¶

全局属性 FeatureSummary_PKG_TYPES 定义 FeatureSummary 所用软件包的类型。

此列表中的顺序非常重要，列表中的第一个软件包类型是最不重要的，最后一个是最重要的。软件包的类型只能更改为较高的类型。

默认软件包类型为 CONFIG、RUNTIME、OPTIONAL、RECOMMENDED 和 REQUIRED，其重要性为 CONFIG < RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED。

FeatureSummary_REQUIRED_PKG_TYPES¶

全局属性 FeatureSummary_REQUIRED_PKG_TYPES 定义哪些软件包类型是必需的。

如果有此类别中的某个或多个软件包尚未找到，则在 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 是唯一强制选项。在此指定要打印哪些信息：

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 版中更改：除了 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 模块中设置此主页。
说明 <说明>: 简短介绍此软件包，最多一个句子。理想情况下，它已直接在查找模块中设置。
类型 <类型>: 该软件包对使用该项目的依赖类型。默认值为 OPTIONAL。在这种情况下，它是一个软件包，可在构建时由项目使用，但也可以在没有该软件包时使用。 RECOMMENDED 类似于 OPTIONAL，即，如果项目中不存在该软件包，项目仍将构建，但生成的二进制文件的某些功能将受到严重限制。如果 REQUIRED 软件包在构建时不可用，项目甚至可能无法构建。这可以与 feature_summary() 的 FATAL_ON_MISSING_REQUIRED_PACKAGES 参数结合使用。最后，RUNTIME 软件包在构建过程中实际上根本不会使用，但实际运行生成的二进制文件却需要此软件包。因此，如果缺少此类软件包，项目仍然可以构建，但以后可能无法运行。如果对同一个软件包使用 set_package_properties() 调用多次，且 TYPE 各不相同，则 TYPE 仅更改为较高的 TYPE（RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED），忽略较低的 TYPE。 TYPE 属性特定于项目，因此无法由查找模块设置，但必须在项目中设置。可接受的类型可以通过设置 FeatureSummary_PKG_TYPES 全局属性进行更改。
用途 <用途>: 它描述了此软件包在项目中启用了哪些功能，即告诉用户在生成的二进制文件中他获得哪些功能。如果为一个软件包多次调用 set_package_properties()，则所有 PURPOSE 属性都将附加到项目中该软件包的用途列表中。与 TYPE 属性一样，PURPOSE 属性也特定于项目，因此无法由查找模块设置，但必须在项目中设置。

设置软件包信息的示例

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

FeatureSummary¶

全局属性¶

函数¶

旧版宏¶

目录

上一个主题

下一个主题

此页面