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

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文件:

声明一个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)

将当前源目录CMAKE_CURRENT_SOURCE_DIR，添加到CMake将查找模块的路径列表CMAKE_MODULE_PATH中。这样CMake就可以找到，我们自定义的FindZeroMQ.cmake模块:
```
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
```
现在FindZeroMQ.cmake模块是可用的，可以通过这个模块来搜索项目所需的依赖项。由于我们没有使用QUIET选项来查找find_package，所以当找到库时，状态消息将自动打印:
```
find_package(ZeroMQ REQUIRED)
```

我们继续添加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}
  )

最后，我们对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节中做的那样。

FindZeroMQ.cmake中，检查了ZeroMQ_ROOT变量是否设置。此变量可用于ZeroMQ库的检测，并引导到自定义安装目录。用户可能设置了ZeroMQ_ROOT作为环境变量，我们也会进行检查了:
```
if(NOT ZeroMQ_ROOT)
    set(ZeroMQ_ROOT "$ENV{ZeroMQ_ROOT}")
endif()
```

然后，搜索系统上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)

如果成功找到头文件，则将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)

然后，为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()

使用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()

最后，包含了标准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通常遵循特定的模式:

检查用户是否为所需的包提供了自定义位置。
使用find_家族中的命令搜索所需包的必需组件，即头文件、库、可执行程序等等。我们使用find_path查找头文件的完整路径，并使用find_library查找库。CMake还提供find_file、find_program和find_package。这些命令的签名如下:
```
find_path(<VAR> NAMES name PATHS paths)
```
如果搜索成功，<VAR>将保存搜索结果；如果搜索失败，则会设置为<VAR>-NOTFOUND。NAMES和PATHS分别是CMake应该查找的文件的名称和搜索应该指向的路径。
初步搜索的结果中，可以提取版本号。示例中，ZeroMQ头文件包含库版本，可以使用字符串操作和正则表达式提取库版本信息。
最后，调用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的手册页面。

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

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

如何实施

工作原理

更多信息