FindPackageHandleStandardArgs

此模块提供旨在用于执行 find_package(<PackageName>) 调用的 Find Modules 中的函数。

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``否则。可能会根据结果以及是否为 find_package 调用提供了 ``REQUIRED 和/或 QUIET 选项来显示成功或失败消息。

选项是：

(DEFAULT_MSG|<自定义失败消息>)

在简单签名中，这指定了失败消息。使用 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) 的调用的包装器。这意味着 <PackageName>_VERSION 的 VERSION_VAR 值。该命令将自动检查是否找到包配置文件。

REASON_FAILURE_MESSAGE <原因失败消息>

在 3.16 版本加入.

指定失败原因的自定义消息，该消息将附加到默认生成的消息中。

FAIL_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，它将失败并显示一条消息（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 版本加入.

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