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

如果所有变量 <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_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 中添加。

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