FindPackageHandleStandardArgs

此模块提供了旨在用于实现 find_package(<PackageName>) 调用的 查找模块 中使用的函数。

find_package_handle_standard_args

此命令处理 find_package()REQUIREDQUIET 和版本相关的参数。它还会设置 <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_LIBRARYLIBXML2_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_LIBRARYLibArchive_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()