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

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-03/recipe-10 中找到，包含一个C的示例。该示例在CMake 3.5版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

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

如何实施

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

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

   cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
   
   project(recipe-10 LANGUAGES C)
   
   set(CMAKE_C_STANDARD 99)
   set(CMAKE_C_EXTENSIONS OFF)
   set(CMAKE_C_STANDARD_REQUIRED ON)

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

   list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR})

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

   find_package(ZeroMQ REQUIRED)

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

   add_executable(hwserver hwserver.c)
   target_include_directories(hwserver
     PRIVATE
         ${ZeroMQ_INCLUDE_DIRS}
     )
   target_link_libraries(hwserver
     PRIVATE
         ${ZeroMQ_LIBRARIES}
     )

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

   add_executable(hwclient hwclient.c)
   target_include_directories(hwclient
     PRIVATE
         ${ZeroMQ_INCLUDE_DIRS}
     )
   target_link_libraries(hwclient
     PRIVATE
         ${ZeroMQ_LIBRARIES}
     )

此示例的主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作为环境变量，我们也会进行检查了:

   if(NOT ZeroMQ_ROOT)
       set(ZeroMQ_ROOT "$ENV{ZeroMQ_ROOT}")
   endif()

2. 然后，搜索系统上zmq.h头文件的位置。这是基于_ZeroMQ_ROOT变量和find_path命令进行的:

   if(NOT ZeroMQ_ROOT)
       find_path(_ZeroMQ_ROOT NAMES include/zmq.h)
   else()
       set(_ZeroMQ_ROOT "${ZeroMQ_ROOT}")
   endif()
   
   find_path(ZeroMQ_INCLUDE_DIRS NAMES zmq.h HINTS ${_ZeroMQ_ROOT}/include)

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

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

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

   if(ZeroMQ_FIND_VERSION_COUNT GREATER 2)
       set(ZeroMQ_VERSION "${ZeroMQ_VERSION_MAJOR}.${ZeroMQ_VERSION_MINOR}.${ZeroMQ_VERSION_PATCH}")
   else()
       set(ZeroMQ_VERSION "${ZeroMQ_VERSION_MAJOR}.${ZeroMQ_VERSION_MINOR}")
   endif()

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

   if(NOT ${CMAKE_C_PLATFORM_ID} STREQUAL "Windows")
     find_library(ZeroMQ_LIBRARIES
       NAMES
           zmq
       HINTS
         ${_ZeroMQ_ROOT}/lib
         ${_ZeroMQ_ROOT}/lib/x86_64-linux-gnu
       )
   else()
     find_library(ZeroMQ_LIBRARIES
       NAMES
           libzmq
         "libzmq-mt-${ZeroMQ_VERSION_MAJOR}_${ZeroMQ_VERSION_MINOR}_${ZeroMQ_VERSION_PATCH}"
         "libzmq-${CMAKE_VS_PLATFORM_TOOLSET}-mt-${ZeroMQ_VERSION_MAJOR}_${ZeroMQ_VERSION_MINOR}_${ZeroMQ_VERSION_PATCH}"
         libzmq_d
         "libzmq-mt-gd-${ZeroMQ_VERSION_MAJOR}_${ZeroMQ_VERSION_MINOR}_${ZeroMQ_VERSION_PATCH}"
         "libzmq-${CMAKE_VS_PLATFORM_TOOLSET}-mt-gd-${ZeroMQ_VERSION_MAJOR}_${ZeroMQ_VERSION_MINOR}_${ZeroMQ_VERSION_PATCH}"
       HINTS
           ${_ZeroMQ_ROOT}/lib
       )
   endif()

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

   include(FindPackageHandleStandardArgs)
   
   find_package_handle_standard_args(ZeroMQ
     FOUND_VAR
         ZeroMQ_FOUND
     REQUIRED_VARS
     ZeroMQ_INCLUDE_DIRS
     ZeroMQ_LIBRARIES
     VERSION_VAR
     ZeroMQ_VERSION
     )

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。这些命令的签名如下:

   find_path(<VAR> NAMES name PATHS paths)

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

4. 初步搜索的结果中，可以提取版本号。示例中，ZeroMQ头文件包含库版本，可以使用字符串操作和正则表达式提取库版本信息。

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，如本节的示例所示。

4. 如果这些都不可行，那么编写自己的find模块。

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

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

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

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

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

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

在第10章中将讨论，如何使用前面讨论中概述的第一种方法，使第三方应用程序，找到自己的包：为项目提供自己的CMake查找文件。