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¶

命令¶

示例¶

示例：完整签名¶

示例：简单签名¶

示例：检查版本¶

另请参阅¶

目录

上一主题

下一主题

本页