FindPackageHandleStandardArgs

此模块提供应该用于 查找模块 中的函数，实现 find_package(<PackageName>) 调用。

find_package_handle_standard_args

此命令处理 REQUIRED、QUIET 以及 find_package() 的版本相关参数。它还设置 <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>]
  )

<PackageName>_FOUND 变量将被设置为 TRUE，如果所有变量 <required-var>... 都是有效的且任何可选约束均已满足；否则将被设置为 FALSE。根据结果以及是否已将 REQUIRED 和/或 QUIET 选项提供给 find_package() 调用，可能会显示成功或失败消息。

选项为

(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

启用处理包组件。在这种情况下，此命令将报告找到了哪些组件以及哪些组件丢失，以及<PackageName>_FOUND变量将设置为FALSE（如果缺少任何必需组件（即find_package()的OPTIONAL_COMPONENTS选项之后未列出的组件））。

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_LIBRARY 和 LIBXML2_INCLUDE_DIR 均有效，则 LibXml2 包将被视为已找到。同时，LibXml2_FOUND 也被设置为 TRUE。如果未找到并且使用了 REQUIRED，则将会失败并显示 message(FATAL_ERROR)，而不管是否使用了 QUIET。如果找到了，将会报告成功，包括第一个 <required-var> 的内容。对于重复的 CMake 运行，相同的报告将会在第二次及之后不再打印。

备注

如果对于调用模块而言，<PackageName> 与 CMAKE_FIND_PACKAGE_NAME 不匹配，则会发出警告，表示不匹配。如果使用旧签名并且使用新签名的 NAME_MISMATCHED 参数，则可以设置 FPHSA_NAME_MISMATCHED 变量以绕过警告。为避免强迫调用方要求使用 CMake 的更新版本，当未为新签名传递 NAME_MISMATCHED 参数时，将会使用变量的值（但同时使用两者会出错）。

全签名的示例

find_package_handle_standard_args(LibArchive
  REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
  VERSION_VAR LibArchive_VERSION)

在此情况下，如果 LibArchive_LIBRARY 和 LibArchive_INCLUDE_DIR 均有效，则 LibArchive 包将被视为已找到。此外，将会使用 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 中添加。

helper 函数，可用于检查 <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()