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()