CMake中FindPackageHandleStandardArgs.cmake文件的作用和用法

前言

FindPackageHandleStandardArgs.cmake 是 CMake 内置的一个模块，它用于定义一个宏，可以用于在找到一个包之后，对其进行一些标准化的处理,它通常用于在CMake中查找和配置外部库或工具包。
find_package_handle_standard_args并不会去特定的路径查找文件，它只是一个CMake宏，用于在CMake中处理和验证找到的包。
实际上，find_package_handle_standard_args通常是在find_package命令中调用的。find_package命令会去指定的路径查找包的配置文件，在找到文件后，它会调用find_package_handle_standard_args来处理和验证找到的包。
在CMake中，每个包都有一个配置文件，用于描述包的信息和依赖项。这些配置文件通常位于预定义的路径下，例如CMAKE_MODULE_PATH或CMAKE_PREFIX_PATH，也可以在find_package命令中通过指定PATHS参数来指定包的路径。
当find_package命令找到包的配置文件时，它会将配置文件中定义的变量和选项导入到CMake中，并调用find_package_handle_standard_args来处理和验证找到的包。因此，find_package_handle_standard_args并不是用来查找包的工具，它只是用来处理和验证找到的包的工具。

FindPackageHandleStandardArgs命令

该命令处理Find_Package()的必需参数、安静参数和与版本相关的参数。它还设置_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>]
 )

• options
  

(DEFAULT_MSG|<custom-failure-message>)
In the simple signature this specifies the failure message. Use DEFAULT_MSG to ask for a default message to be computed (recommended). Not valid in the full signature.
FOUND_VAR <result-var>
Deprecated since version 3.3.
Specifies either <PackageName>_FOUND or <PACKAGENAME>_FOUND as the result variable. This exists only for compatibility with older versions of CMake and is now ignored. Result variables of both names are always set for compatibility.
REQUIRED_VARS <required-var>...
Specify the variables which are required for this package. These may be named in the generated failure message asking the user to set the missing variable values. Therefore these should typically be cache entries such as FOO_LIBRARY and not output variables like FOO_LIBRARIES.
Changed in version 3.18: If HANDLE_COMPONENTS is specified, this option can be omitted.
VERSION_VAR <version-var>
Specify the name of a variable that holds the version of the package that has been found. This version will be checked against the (potentially) specified required version given to the find_package() call, including its EXACT option. The default messages include information about the required version and the version which has been actually found, both if the version is ok or not.
HANDLE_VERSION_RANGE
New in version 3.19.
Enable handling of a version range, if one is specified. Without this option, a developer warning will be displayed if a version range is specified.
HANDLE_COMPONENTS
Enable handling of package components. In this case, the command will report which components have been found and which are missing, and the <PackageName>_FOUND variable will be set to FALSE if any of the required components (i.e. not the ones listed after the OPTIONAL_COMPONENTS option of find_package()) are missing.
CONFIG_MODE
Specify that the calling find module is a wrapper around a call to find_package(<PackageName> NO_MODULE). This implies a VERSION_VAR value of <PackageName>_VERSION. The command will automatically check whether the package configuration file was found.
REASON_FAILURE_MESSAGE <reason-failure-message>
New in version 3.16.
Specify a custom message of the reason for the failure which will be appended to the default generated message.
FAIL_MESSAGE <custom-failure-message>
Specify a custom failure message instead of using the default generated message. Not recommended.
NAME_MISMATCHED
New in version 3.17.
Indicate that the <PackageName> does not match ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and raises a warning, but it may be intentional for usage of the command for components of a larger package.

用法和示例

使用FindPackageHandleStandardArgs.cmake时，需要提供以下参数：
PACKAGE_NAME：要查找的包的名称。
DEFAULT_MSG：如果找不到包时要显示的默认消息。
CONDITION：一个布尔表达式，用于确定是否找到了包。如果条件为真，则FindPackageHandleStandardArgs.cmake将返回TRUE。
REQUIRED_VARS：一个包含所需变量的列表。如果这些变量未定义，则FindPackageHandleStandardArgs.cmake将返回FALSE。

**它通常在编写自己的xxx.cmake会被用到 ，至于怎么编写，可以查看我的这篇博客：编写属于自己的Findxxx.cmake文件

下面是FindPackageHandleStandardArgs.cmake的示例用法：
find_package_handle_standard_args(MyPackage REQUIRED_VARS MY_PACKAGE_INCLUDE_DIRS MY_PACKAGE_LIBRARIES)
在这个例子中，我们要查找名为MyPackage的包，并验证MY_PACKAGE_INCLUDE_DIRS和MY_PACKAGE_LIBRARIES这两个变量是否定义。

• 如果这两个变量未定义，则FindPackageHandleStandardArgs.cmake将返回FALSE。
• 如果找到了包并且所有必需的变量都已定义，则FindPackageHandleStandardArgs.cmake将返回TRUE，并将输出一个消息，指示已找到包。
• 如果找不到包，则FindPackageHandleStandardArgs.cmake将显示DEFAULT_MSG中指定的默认消息，并返回FALSE。

在CMake中使用FindPackageHandleStandardArgs.cmake可以帮助简化外部库或工具包的配置过程，减少手动编写配置脚本的工作量。

FindPackageHandleStandardArgs搜索路径

FindPackageHandleStandardArgs宏本身不会搜索路径，它只是用于处理标准的查找参数并输出查找失败消息和查找提示。路径搜索是由find_package命令完成的，该命令在调用FindPackageHandleStandardArgs宏之前会搜索一系列指定的路径。

find_package()命令首先会在模块路径中寻找一个事先编译好的Find.cmake文件，而且一般官方给出了很多，不需要自己编写这是查找库的一个典型方式。 如果Module模式搜索失败，没有找到对应的Find.cmake文件，则转入Config模式进行。

在find_package命令中的路径搜索顺序

1. 检查是否定义了指定库的导入目录变量，例如_DIR。
2. 检查环境变量，例如_ROOT。
3. 搜索系统路径，例如/usr/include和/usr/lib。
4. 搜索用户指定的路径，例如CMAKE_PREFIX_PATH和CMAKE_MODULE_PATH。

当找到指定库的头文件和库文件时，find_package会定义一系列变量来描述找到的库，例如_FOUND、_INCLUDE_DIRS和_LIBRARIES。然后，FindPackageHandleStandardArgs宏将使用这些变量来判断查找是否成功，并输出查找提示（如果有）。

运用场景

在 CMake 中，通常使用 find_package 命令来查找并加载所需的外部依赖库，该命令通常会在系统上查找特定的文件或库，或者在预定义的路径中查找这些文件或库。一旦找到了库，那么通常需要对其进行一些配置，比如设置头文件路径、库文件路径、编译选项等。
这时候就可以使用 FindPackageHandleStandardArgs.cmake 宏来进行标准化处理。该宏的作用是：根据找到的库的信息，判断库是否存在、是否可用、是否满足要求，如果符合要求，就将该库的相关信息（包括头文件路径、库文件路径等）传递给 find_package 命令调用方，并设置变量 _FOUND。如果库不符合要求，则给出错误提示。
使用 FindPackageHandleStandardArgs.cmake 的好处在于它可以避免在不同系统、不同版本的库中进行不必要的配置，并能够将配置信息统一化，减少重复代码。同时，使用该宏可以使得查找和配置外部库更加可靠和可移植。

在CMake中，find_package命令的使用方式有多种，其中一种常见的方式是使用预定义的Find模块，例如FindBoost.cmake、FindOpenCV.cmake等。这些Find模块通常已经包含了适当的逻辑来查找并验证库，并在找到库后设置相关的变量和宏。
在这种情况下，find_package命令会直接调用相应的Find模块来查找库，而不会调用FindPackageHandleStandardArgs命令。
然而，对于某些库，可能没有预定义的Find模块可用，或者需要自定义查找逻辑。在这种情况下，用户可以编写自己的Find模块，并在其中调用FindPackageHandleStandardArgs命令来验证库的可用性。