FeatureSummary ¶

此模块提供了用于生成已启用/禁用功能的摘要的命令。

使用 CMake 加载此模块

include(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 选项的 FeatureSummary 命令时，CMake 将中止。

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

FeatureSummary_DEFAULT_PKG_TYPE¶

版本 3.8 新增。

此全局属性定义了默认包类型。

当调用 FeatureSummary 命令，并且用户未显式设置某些包的类型时，其类型将设置为此属性的值。

此值必须是 FeatureSummary_PKG_TYPES 全局属性中定义的类型之一。

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

FeatureSummary_<TYPE>_DESCRIPTION¶

版本 3.9 中添加。

此全局属性可以为每个包类型 <TYPE> 定义一个字符串，该字符串将用于 feature_summary() 命令的输出标题。例如：

The following <FeatureSummary_<TYPE>_DESCRIPTION> have been found:

如果未设置，则使用默认字符串 <TYPE> packages。

命令 ¶

本模块提供以下命令

feature_summary()
set_package_properties()
add_feature_info()

打印功能摘要 ¶

feature_summary¶

打印有关项目已启用或禁用包和功能的信息。

feature_summary(
  WHAT (ALL
    | PACKAGES_FOUND | PACKAGES_NOT_FOUND
    | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
    | ENABLED_FEATURES | DISABLED_FEATURES)
  [FILENAME <file>]
  [APPEND]
  [VAR <variable-name>]
  [INCLUDE_QUIET_PACKAGES]
  [FATAL_ON_MISSING_REQUIRED_PACKAGES]
  [DESCRIPTION <description> | DEFAULT_DESCRIPTION]
  [QUIET_ON_EMPTY]
)

此命令可用于打印有关项目已启用或禁用包和功能的信息。默认情况下，只打印功能/包的名称以及指定时所需的版本。使用 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> 中，而不是打印到终端。

INCLUDE_QUIET_PACKAGES

如果提供了此选项，则也会列出使用 find_package(... QUIET) 搜索的包。默认情况下它们会被跳过。

FATAL_ON_MISSING_REQUIRED_PACKAGES

如果提供了此选项，并且未找到在 FeatureSummary_REQUIRED_PKG_TYPES 全局属性中列出的包类型之一的包，CMake 将中止并显示致命错误。

DESCRIPTION <description>

将在实际内容上方打印的描述或标题。如果没有此选项，并且只请求了一种包类型，则不会打印标题，除非使用此选项或 DEFAULT_DESCRIPTION 选项明确设置了自定义字符串，后者为请求的类型输出默认标题。

DEFAULT_DESCRIPTION

版本 3.9 中添加。

与可自定义的 DESCRIPTION <description> 相对，这是将在内容上方打印的默认描述或标题。

QUIET_ON_EMPTY

版本 3.8 新增。

如果提供了此选项，当只请求了一种包类型，并且没有找到属于该类别的包时，则不会打印（包括 DESCRIPTION）任何输出，也不会将其添加到 FILENAME 或 VAR 变量中。

包属性 ¶

set_package_properties¶

设置包属性。

set_package_properties(
  <PackageName>
  PROPERTIES
    [URL <url>]
    [DESCRIPTION <description>]
    [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
    [PURPOSE <purpose>]
)

使用此命令配置和提供有关名为 <PackageName> 的包的信息，然后可以使用 feature_summary() 命令显示该信息。此命令可以直接在相应的Find 模块中调用，或在调用 find_package() 调用后，在项目中使用该模块时调用。可以设置信息的特征在调用 find_package() 命令后自动确定。

参数为

<PackageName>

包的名称。例如，在 find_package(<PackageName>) 参数中指定的名称。

PROPERTIES

指定要设置的属性。

URL <url>

这应该是包的主页，或类似内容。理想情况下，这应直接在Find 模块中设置。

DESCRIPTION <description>

关于该包是什么的简短描述，最多一句。理想情况下，这应直接在Find 模块中设置。

TYPE <type>

使用项目对该包的依赖类型。

默认 <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 <purpose>

这描述了该包在项目中启用了哪些功能，即它告诉用户在结果二进制文件中获得了什么功能。如果多次为包调用 set_package_properties()，所有 PURPOSE 属性都将被添加到项目包的目的列表中。与 TYPE 属性一样，PURPOSE 属性也是项目特定的，因此不能由Find 模块设置，而必须在项目中设置。

添加功能信息 ¶

add_feature_info¶

添加功能信息。

add_feature_info(<name> <condition> <description>)

使用此命令添加有关由给定 <name> 标识的功能的信息。

参数为

<name>

要添加的功能的标识名称。

<condition>

指定决定该功能是否启用或禁用的条件。

参数 <condition> 可以是：

单个条件（例如变量名）。
版本 3.8 中已添加：多个条件的分号分隔列表。
版本 4.0 中已添加： if(<condition>) 子句中使用的完整条件语法。请参阅策略 CMP0183。这允许使用完整的条件语法（例如使用括号分组条件等）。

<description>

描述该功能的文本。可以使用 feature_summary() 命令为 ENABLED_FEATURES 和 DISABLED_FEATURES 分别显示此信息。

已弃用的命令 ¶

为向后兼容以前的 CMake 版本，提供了以下旧版和已弃用的命令：

set_package_info¶

自版本 3.8 起已弃用：请改用 set_package_properties() 和 add_feature_info() 命令。

设置指定包的信息，然后可以通过 feature_summary() 显示。

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

<PackageName>: 包的名称。
<description>: 包的简短描述。
<url>: 包的主页。
<purpose>: 包的用途。

此命令可以直接在Find 模块中调用，或在调用 find_package() 命令后，在使用了 FeatureSummary 模块的项目中调用。可以设置信息的特征由 find_package() 命令自动添加。

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

示例 ¶

示例：将功能摘要附加到文件 ¶

在下面的示例中，功能摘要输出将被附加到指定文件，而不是打印到终端。

include(FeatureSummary)
feature_summary(WHAT ALL FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)

示例：将功能摘要存储在变量中 ¶

在下面的示例中，已启用功能的特征摘要被存储在指定的变量 enabledFeaturesText 中，包括 QUIET 包。

include(FeatureSummary)

feature_summary(
  WHAT ENABLED_FEATURES
  INCLUDE_QUIET_PACKAGES
  DESCRIPTION "Enabled Features:"
  VAR enabledFeaturesText
)

message(STATUS "${enabledFeaturesText}")

示例：添加自定义包类型 ¶

在下面的示例中，添加了一个自定义包类型，并且仅打印非空类别。

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
)

示例：设置包信息 ¶

为包设置信息的示例。

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

示例：打印功能摘要 ¶

在下面的示例中，此模块用于在配置结束时输出功能摘要。如果找不到任何必需的包，则在配置阶段结束时，处理将中止并显示错误消息。

cmake_minimum_required(VERSION 3.15)
project(Example)

add_library(example example.c)

include(FeatureSummary)

find_package(CURL)
set_package_properties(CURL PROPERTIES TYPE REQUIRED)
target_link_libraries(example PRIVATE CURL::libcurl)

find_package(LibXml2 QUIET)
set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED)
if(LibXml2_FOUND)
  target_link_libraries(example PRIVATE LibXml2::LibXml2)
endif()

feature_summary(
  WHAT ALL
  INCLUDE_QUIET_PACKAGES
  DESCRIPTION "Feature summary:"
  FATAL_ON_MISSING_REQUIRED_PACKAGES
)

示例：设置功能信息 ¶

设置功能的示例信息。

include(FeatureSummary)

option(WITH_FOO "Help for foo" ON)

add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")

基于条件列表设置功能信息的示例。

include(FeatureSummary)

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 子句参数。

include(FeatureSummary)

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

FeatureSummary ¶

全局属性 ¶

命令 ¶

打印功能摘要 ¶

包属性 ¶

添加功能信息 ¶

已弃用的命令 ¶

示例 ¶

示例：将功能摘要附加到文件 ¶

示例：将功能摘要存储在变量中 ¶

示例：添加自定义包类型 ¶

示例：设置包信息 ¶

示例：打印功能摘要 ¶

示例：设置功能信息 ¶

目录

上一主题

下一主题

本页