3.10 检测外部库:Ⅱ. 自定义find模块

    此示例补充了上一节的示例，我们将展示如何编写一个模块来定位系统上的ZeroMQ消息库，以便能够在非Unix操作系统上检测该库。我们重用服务器-客户端示例代码。

    这是一个C项目，使用C99标准，并逐步构建CMakeLists.txt文件:

    1. 声明一个C项目，并要求符合C99标准:

    2. 将当前源目录CMAKE_CURRENT_SOURCE_DIR，添加到CMake将查找模块的路径列表CMAKE_MODULE_PATH中。这样CMake就可以找到，我们自定义的FindZeroMQ.cmake模块:

      1. list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR})

    3. 现在FindZeroMQ.cmake模块是可用的，可以通过这个模块来搜索项目所需的依赖项。由于我们没有使用QUIET选项来查找find_package，所以当找到库时，状态消息将自动打印:

      1. find_package(ZeroMQ REQUIRED)

    4. 我们继续添加hwserver可执行目标。头文件包含目录和链接库是使用find_package命令成功后，使用ZeroMQ_INCLUDE_DIRS和ZeroMQ_LIBRARIES变量进行指定的:

      1. add_executable(hwserver hwserver.c)
      2. target_include_directories(hwserver
      3.   PRIVATE
      4.       ${ZeroMQ_INCLUDE_DIRS}
      5.   )
      6. target_link_libraries(hwserver
      7.   PRIVATE
      8.       ${ZeroMQ_LIBRARIES}
      9.   )

    5. 最后，我们对hwclient可执行目标执行相同的操作:

    此示例的主CMakeLists.txt在使用FindZeroMQ.cmake时，与前一个示例中使用的CMakeLists.txt不同。这个模块使用find_path和find_library CMake内置命令，搜索ZeroMQ头文件和库，并使用find_package_handle_standard_args设置相关变量，就像我们在第3节中做的那样。

    1. FindZeroMQ.cmake中，检查了ZeroMQ_ROOT变量是否设置。此变量可用于ZeroMQ库的检测，并引导到自定义安装目录。用户可能设置了ZeroMQ_ROOT作为环境变量，我们也会进行检查了:

      1. if(NOT ZeroMQ_ROOT)
      2.     set(ZeroMQ_ROOT "$ENV{ZeroMQ_ROOT}")
      3. endif()
      1. if(NOT ZeroMQ_ROOT)
      2.     find_path(_ZeroMQ_ROOT NAMES include/zmq.h)
      3. else()
      4.     set(_ZeroMQ_ROOT "${ZeroMQ_ROOT}")
      5. endif()

    3. 如果成功找到头文件，则将ZeroMQ_INCLUDE_DIRS设置为其位置。我们继续通过使用字符串操作和正则表达式，寻找相应版本的ZeroMQ库:

      1. set(_ZeroMQ_H ${ZeroMQ_INCLUDE_DIRS}/zmq.h)
      3. function(_zmqver_EXTRACT _ZeroMQ_VER_COMPONENT _ZeroMQ_VER_OUTPUT)
      4. set(CMAKE_MATCH_1 "0")
      5. set(_ZeroMQ_expr "^[ \\t]*#define[ \\t]+${_ZeroMQ_VER_COMPONENT}[ \\t]+([0-9]+)$")
      6. file(STRINGS "${_ZeroMQ_H}" _ZeroMQ_ver REGEX "${_ZeroMQ_expr}")
      7. string(REGEX MATCH "${_ZeroMQ_expr}" ZeroMQ_ver "${_ZeroMQ_ver}")
      8. set(${_ZeroMQ_VER_OUTPUT} "${CMAKE_MATCH_1}" PARENT_SCOPE)
      9. endfunction()
      11. _zmqver_EXTRACT("ZMQ_VERSION_MAJOR" ZeroMQ_VERSION_MAJOR)
      12. _zmqver_EXTRACT("ZMQ_VERSION_MINOR" ZeroMQ_VERSION_MINOR)
      13. _zmqver_EXTRACT("ZMQ_VERSION_PATCH" ZeroMQ_VERSION_PATCH)

    4. 然后，为find_package_handle_standard_args准备ZeroMQ_VERSION变量:

    5. 使用find_library命令搜索ZeroMQ库。因为库的命名有所不同，这里我们需要区分Unix的平台和Windows平台:

      1. if(NOT ${CMAKE_C_PLATFORM_ID} STREQUAL "Windows")
      2.   find_library(ZeroMQ_LIBRARIES
      3.     NAMES
      4.         zmq
      5.     HINTS
      6.       ${_ZeroMQ_ROOT}/lib
      7.       ${_ZeroMQ_ROOT}/lib/x86_64-linux-gnu
      8.     )
      9. else()
      10.   find_library(ZeroMQ_LIBRARIES
      11.     NAMES
      12.         libzmq
      13.       "libzmq-${CMAKE_VS_PLATFORM_TOOLSET}-mt-${ZeroMQ_VERSION_MAJOR}_${ZeroMQ_VERSION_MINOR}_${ZeroMQ_VERSION_PATCH}"
      14.       libzmq_d
      15.       "libzmq-mt-gd-${ZeroMQ_VERSION_MAJOR}_${ZeroMQ_VERSION_MINOR}_${ZeroMQ_VERSION_PATCH}"
      16.       "libzmq-${CMAKE_VS_PLATFORM_TOOLSET}-mt-gd-${ZeroMQ_VERSION_MAJOR}_${ZeroMQ_VERSION_MINOR}_${ZeroMQ_VERSION_PATCH}"
      17.     HINTS
      18.         ${_ZeroMQ_ROOT}/lib
      19.     )
      20. endif()

    6. 最后，包含了标准FindPackageHandleStandardArgs.cmake，并调用相应的CMake命令。如果找到所有需要的变量，并且版本匹配，则将ZeroMQ_FOUND变量设置为TRUE:

      1. include(FindPackageHandleStandardArgs)
      4.   FOUND_VAR
      5.       ZeroMQ_FOUND
      6.   REQUIRED_VARS
      7.   ZeroMQ_INCLUDE_DIRS
      8.   ZeroMQ_LIBRARIES
      9.   VERSION_VAR
      10.   ZeroMQ_VERSION
      11.   )

    NOTE:刚才描述的FindZeroMQ.cmake模块已经在 https://github.com/zeromq/azmq/blob/master/config/FindZeroMQ.cmake 上进行了修改。

    find-module通常遵循特定的模式:

    1. 检查用户是否为所需的包提供了自定义位置。

    2. 使用find_家族中的命令搜索所需包的必需组件，即头文件、库、可执行程序等等。我们使用find_path查找头文件的完整路径，并使用find_library查找库。CMake还提供find_file、find_program和find_package。这些命令的签名如下:

      1. find_path(<VAR> NAMES name PATHS paths)

    3. 如果搜索成功，<VAR>将保存搜索结果；如果搜索失败，则会设置为<VAR>-NOTFOUND。NAMES和PATHS分别是CMake应该查找的文件的名称和搜索应该指向的路径。

    5. 最后，调用find_package_handle_standard_args命令。处理find_package命令的REQUIRED、QUIET和版本参数，并设置ZeroMQ_FOUND变量。

    NOTE:任何CMake命令的完整文档都可以从命令行获得。例如，cmake --help-command find_file将输出find_file命令的手册页。对于CMake标准模块的手册，可以在CLI使用--help-module看到。例如，cmake --help-module FindPackageHandleStandardArgs将输出FindPackageHandleStandardArgs.cmake的手册页面。

    总而言之，有四种方式可用于找到依赖包:

    1. 使用由包供应商提供CMake文件<package>Config.cmake ，<package>ConfigVersion.cmake和<package>Targets.cmake，通常会在包的标准安装位置查找。
    2. 无论是由CMake还是第三方提供的模块，为所需包使用find-module。
    3. 使用pkg-config，如本节的示例所示。

    这四种可选方案按相关性进行了排序，每种方法也都有其挑战。

    目前，并不是所有的包供应商都提供CMake的Find文件，不过正变得越来越普遍。因为导出CMake目标，使得第三方代码很容易使用它所依赖的库和/或程序附加的依赖。

    从一开始，Find-module就一直是CMake中定位依赖的主流手段。但是，它们中的大多数仍然依赖于设置依赖项使用的变量，比如Boost_INCLUDE_DIRS、PYTHON_INTERPRETER等等。这种方式很难在第三方发布自己的包时，确保依赖关系被满足。

    使用pkg-config的方法可以很好地进行适配，因为它已经成为Unix系统的标准。然而，也由于这个原因，它不是一个完全跨平台的方法。此外，如CMake文档所述，在某些情况下，用户可能会意外地覆盖检测包，并导致pkg-config提供不正确的信息。

    最后的方法是编写自己的查找模块脚本，就像本示例中那样。这是可行的，并且依赖于FindPackageHandleStandardArgs.cmake。然而，编写一个全面的查找模块脚本绝非易事；有需要考虑很多可能性，我们在Unix和Windows平台上，为查找ZeroMQ库文件演示了一个例子。

    所有软件开发人员都非常清楚这些问题和困难，正如CMake邮件列表上讨论所示: 。在Unix包开发人员中是可以接受的，但是它不能很容易地移植到非Unix平台。CMake配置文件功能强大，但并非所有软件开发人员都熟悉CMake语法。公共包规范项目是统一用于包查找的pkg-config和CMake配置文件方法的最新尝试。您可以在项目的网站上找到更多信息: https://mwoehlke.github.io/cps/