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.ac.cn>
   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 软件包是在构建期间实际上根本不使用的软件包，但是运行生成的二进制文件所必需的软件包。因此，如果缺少这样的软件包，项目仍然可以构建，但以后可能无法工作。如果为同一软件包多次调用 set_package_properties() 并使用不同的 TYPE，则 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¶

全局属性¶

函数¶

已弃用的函数¶

目录

上一主题

下一主题

本页