FindPackageHandleStandardArgs¶

此模块提供的命令旨在用于实现 find_package(<PackageName>) 调用的查找模块（Find Modules）中。

在 CMake 查找模块中加载此模块，使用

FindFoo.cmake¶

include(FindPackageHandleStandardArgs)

命令¶

本模块提供以下命令

find_package_handle_standard_args()
find_package_check_version()

find_package_handle_standard_args¶

处理 find_package() 的 REQUIRED、QUIET 及与版本相关的参数。

共有两种函数签名

find_package_handle_standard_args(
  <PackageName>
  (DEFAULT_MSG|<custom-failure-message>)
  <required-vars>...
)

find_package_handle_standard_args(
  <PackageName>
  [REQUIRED_VARS <required-vars>...]
  [VERSION_VAR <version-var>]
  [HANDLE_VERSION_RANGE]
  [HANDLE_COMPONENTS]
  [CONFIG_MODE]
  [NAME_MISMATCHED]
  [REASON_FAILURE_MESSAGE <reason-failure-message>]
  [FAIL_MESSAGE <custom-failure-message>]
  [FOUND_VAR <result-var>] # Deprecated
)

如果 <required-vars>... 中列出的所有变量都包含有效结果（例如有效的文件路径）并且满足任何可选约束，则此命令将 <PackageName>_FOUND 变量设置为 TRUE，否则设置为 FALSE。根据结果以及是否向 find_package() 调用传递了 REQUIRED 和/或 QUIET 选项，可能会显示成功或失败的消息。

参数为

<PackageName>: 包的名称。例如，按照 Find<PackageName>.cmake 查找模块文件名中的写法。
(DEFAULT_MSG|<custom-failure-message>): 在简单签名中，这指定了失败消息。使用 DEFAULT_MSG 可请求计算默认消息（推荐）。在完整签名中无效。
REQUIRED_VARS <required-vars>...: 指定此包所需的变量。它们可能会在生成的失败消息中被提及，以要求用户设置缺失的变量值。因此，这些变量通常应该是缓存条目，如 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。该命令将自动检查是否找到了包配置文件。
NAME_MISMATCHED: 在 3.17 版本中添加。

指示 <PackageName> 与 CMAKE_FIND_PACKAGE_NAME 变量的值不匹配。这通常是一个错误并会引发警告，但在用于大型包的组件时可能是故意的。
REASON_FAILURE_MESSAGE <reason-failure-message>: 3.16 版新增。

指定失败原因的自定义消息，该消息将附加到默认生成的消息之后。
FAIL_MESSAGE <custom-failure-message>: 指定自定义失败消息，而不是使用默认生成的消息。不推荐使用。
FOUND_VAR <result-var>: 3.3 版本后弃用: 不再建议使用此选项。

指定 <PackageName>_FOUND 或 <PACKAGENAME>_FOUND 作为结果变量。此选项仅为与旧版本 CMake 的向后兼容性而存在，现已被忽略。无论是否使用此选项，两种名称的结果变量现在总是会被设置，以保持兼容性。

注意

如果 <PackageName> 与调用模块的 CMAKE_FIND_PACKAGE_NAME 不匹配，则会给出不匹配的警告。如果使用旧签名，可以设置 FPHSA_NAME_MISMATCHED 变量来绕过该警告；如果使用新签名，则可以使用 NAME_MISMATCHED 参数。为了避免强制调用者要求使用更新版本的 CMake，当在新签名中未传递 NAME_MISMATCHED 参数时，如果定义了该变量，其值将被使用（但同时使用两者是一个错误）。

find_package_check_version¶

3.19 版本新增。

检查给定的版本是否符合 find_package() 的版本相关参数。

find_package_check_version(
  <version>
  <result-var>
  [HANDLE_VERSION_RANGE]
  [RESULT_MESSAGE_VARIABLE <message-var>]
)

参数为

<version>: 要检查的版本字符串。
<result-var>: 用于保存检查结果的布尔值的变量名。
HANDLE_VERSION_RANGE: 如果指定了版本范围，则启用对版本范围的处理。如果不使用此选项，当指定了版本范围时，将显示开发人员警告。
RESULT_MESSAGE_VARIABLE <message-var>: 指定一个变量以获取描述检查结果的消息。

示例¶

示例：完整签名¶

使用 find_package_handle_standard_args() 完整签名的示例

FindLibArchive.cmake¶

include(FindPackageHandleStandardArgs)
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_handle_standard_args() 完整签名的示例

FindAutomoc4.cmake¶

find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)

include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Automoc4 CONFIG_MODE)

在这种情况下，FindAutomoc4.cmake 模块包装了对 find_package(Automoc4 NO_MODULE) 的调用，并为 automoc4 添加了一个额外的搜索目录。然后，对 find_package_handle_standard_args() 的调用会生成适当的成功/失败消息。

示例：简单签名¶

使用 find_package_handle_standard_args() 简单签名的示例

FindLibXml2.cmake¶

include(FindPackageHandleStandardArgs)
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-vars>... 中指定的第一个必需变量的内容。在重复运行 CMake 时，同一消息将不会再次打印。

示例：版本检查¶

find_package_check_version() 的使用示例

FindFoo.cmake¶

include(FindPackageHandleStandardArgs)
find_package_check_version(
  1.2.3
  result
  HANDLE_VERSION_RANGE
  RESULT_MESSAGE_VARIABLE reason
)
if(result)
  message(STATUS "${reason}")
else()
  # Logic when version check is not successful.
  message(WARNING "${reason}")
endif()

另请参阅¶

关于如何编写查找模块的详细信息，请参阅查找模块（Find Modules）。

FindPackageHandleStandardArgs¶

命令¶

示例¶

示例：完整签名¶

示例：简单签名¶

示例：版本检查¶

另请参阅¶

目录

上一主题

下一主题

本页