FindPackageHandleStandardArgs¶
此模块提供了旨在用于实现 find_package(<PackageName>)
调用的 查找模块 中使用的函数。
- find_package_handle_standard_args¶
此命令处理
find_package()
的REQUIRED
、QUIET
和版本相关的参数。它还会设置<PackageName>_FOUND
变量。如果列出的所有变量都包含有效结果(例如,有效的路径),则认为已找到该包。有两种签名
find_package_handle_standard_args(<PackageName> (DEFAULT_MSG|<custom-failure-message>) <required-var>... ) find_package_handle_standard_args(<PackageName> [FOUND_VAR <result-var>] [REQUIRED_VARS <required-var>...] [VERSION_VAR <version-var>] [HANDLE_VERSION_RANGE] [HANDLE_COMPONENTS] [CONFIG_MODE] [NAME_MISMATCHED] [REASON_FAILURE_MESSAGE <reason-failure-message>] [FAIL_MESSAGE <custom-failure-message>] )
如果
<required-var>...
中的所有变量都有效且任何可选约束都已满足,则<PackageName>_FOUND
变量将被设置为TRUE
,否则设置为FALSE
。根据结果以及是否为find_package()
调用提供了REQUIRED
和/或QUIET
选项,可能会显示成功或失败消息。选项包括
(DEFAULT_MSG|<custom-failure-message>)
在简单签名中,这指定了失败消息。使用
DEFAULT_MSG
来请求计算默认消息(推荐)。在完整签名中无效。FOUND_VAR <result-var>
自版本 3.3 起已弃用。
指定
<PackageName>_FOUND
或<PACKAGENAME>_FOUND
作为结果变量。这仅是为了兼容旧版本的 CMake,现在已被忽略。为了与此选项兼容,无论是否使用此选项,现在都会始终设置这两种名称的结果变量。REQUIRED_VARS <required-var>...
指定此包所需的变量。这些变量可以在生成的失败消息中命名,要求用户设置缺失的变量值。因此,它们通常应该是缓存条目,如
FOO_LIBRARY
,而不是像FOO_LIBRARIES
这样的输出变量。自版本 3.18 起已更改:如果指定了
HANDLE_COMPONENTS
,则可以省略此选项。VERSION_VAR <version-var>
指定一个变量的名称,该变量保存已找到的包的版本。此版本将根据传递给
find_package()
调用(包括其EXACT
选项)的(可能)指定的必需版本进行检查。默认消息将包含有关必需版本和实际找到的版本的信息,无论版本是否正确。HANDLE_VERSION_RANGE
3.19 版本新增。
如果指定了版本范围,则启用版本范围的处理。没有此选项,如果指定了版本范围,则会显示开发者警告。
HANDLE_COMPONENTS
启用组件的处理。在这种情况下,命令将报告哪些组件已找到,哪些组件丢失,并且如果任何必需的组件(即未在
find_package()
的OPTIONAL_COMPONENTS
选项后列出的组件)丢失,则<PackageName>_FOUND
变量将被设置为FALSE
。CONFIG_MODE
指定调用查找模块是
find_package(<PackageName> NO_MODULE)
的包装器。这表示VERSION_VAR
的值为<PackageName>_VERSION
。该命令将自动检查是否找到了包配置文件。REASON_FAILURE_MESSAGE <reason-failure-message>
3.16 版新增。
指定一个自定义的失败原因消息,该消息将被追加到默认生成的消息中。
FAIL_MESSAGE <custom-failure-message>
指定一个自定义的失败消息,而不是使用默认生成的。不推荐。
NAME_MISMATCHED
在 3.17 版本中添加。
指示
<PackageName>
与${CMAKE_FIND_PACKAGE_NAME}
不匹配。这通常是一个错误,会引发警告,但对于使用该命令作为更大包的组件可能是有意的。
简单签名示例
find_package_handle_standard_args(LibXml2 DEFAULT_MSG
LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
LibXml2
包被认为已找到,前提是 LIBXML2_LIBRARY
和 LIBXML2_INCLUDE_DIR
都有效。然后 LibXml2_FOUND
也被设置为 TRUE
。如果未找到且使用了 REQUIRED
,则会失败并显示 message(FATAL_ERROR)
,无论是否使用了 QUIET
。如果找到,则会报告成功,包括第一个 <required-var>
的内容。在重复运行 CMake 时,相同的消息将不再打印。
注意
如果调用模块的 <PackageName>
与 CMAKE_FIND_PACKAGE_NAME
不匹配,则会给出不匹配的警告。 FPHSA_NAME_MISMATCHED
变量可以设置为在旧签名中使用 NAME_MISMATCHED
参数来绕过警告,而在新签名中使用 NAME_MISMATCHED
参数来绕过警告。为了避免强制调用者要求更新版本的 CMake 以便使用,当未传递 NAME_MISMATCHED
参数(但同时使用两者是错误的)时,如果定义了该变量,则将使用该变量的值。
完整签名示例
find_package_handle_standard_args(LibArchive
REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
VERSION_VAR LibArchive_VERSION)
在这种情况下,LibArchive
包被认为已找到,前提是 LibArchive_LIBRARY
和 LibArchive_INCLUDE_DIR
都有效。通过使用 LibArchive_VERSION
中包含的版本,还将检查 LibArchive
的版本。由于没有给出 FAIL_MESSAGE
,将打印默认消息。
完整签名的另一个示例
find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
find_package_handle_standard_args(Automoc4 CONFIG_MODE)
在此示例中,FindAutmoc4.cmake
模块包装了对 find_package(Automoc4 NO_MODULE)
的调用,并为 automoc4
添加了一个额外的搜索目录。然后,find_package_handle_standard_args
的调用会生成一个正确的成功/失败消息。
- find_package_check_version¶
3.19 版本新增。
辅助函数,可用于检查
<version>
是否相对于find_package()
的版本相关参数有效。find_package_check_version(<version> <result-var> [HANDLE_VERSION_RANGE] [RESULT_MESSAGE_VARIABLE <message-var>] )
<result-var>
将包含一个布尔值,给出检查结果。选项包括
HANDLE_VERSION_RANGE
如果指定了版本范围,则启用版本范围的处理。没有此选项,如果指定了版本范围,则会显示开发者警告。
RESULT_MESSAGE_VARIABLE <message-var>
指定一个变量以获取描述检查结果的消息。
用法示例
find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
RESULT_MESSAGE_VARIABLE reason)
if(result)
message(STATUS "${reason}")
else()
message(FATAL_ERROR "${reason}")
endif()