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 新增。

此全局属性定义了被视为必需的包类型的分号分隔列表。

如果这些类别中的一个或多个包未找到，当调用带有 FATAL_ON_MISSING_REQUIRED_PACKAGES 选项的 feature_summary() 命令时，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_package() 后在使用该模块的项目中执行。可以设置信息的功能在 find_package() 命令后自动确定。

URL <url>: 这应该是包的主页，或类似的东西。理想情况下，这应该已直接在查找模块中设置。
DESCRIPTION <description>: 对包的简短描述，最多一句话。理想情况下，这应该已直接在查找模块中设置。
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 属性是项目特定的，因此它不能由查找模块设置，但必须在项目中设置。可以通过设置 FeatureSummary_PKG_TYPES 全局属性来更改接受的类型。
PURPOSE <purpose>: 这描述了此包在项目中启用的功能，即它告诉用户在生成二进制文件中获得哪些功能。如果对一个包多次调用 set_package_properties()，则所有 PURPOSE 属性将附加到项目中的包用途列表中。与 TYPE 属性一样，PURPOSE 属性也是项目特定的，因此它不能由查找模块设置，但必须在项目中设置。

设置包信息的示例

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_package() 后在使用 FeatureSummary 模块的项目中完成。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¶

全局属性¶

函数¶

已弃用函数¶

目录

上一主题

下一主题

本页