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>
可以是条件列表。设置功能信息的示例
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:")