返回介绍

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

发布于 2025-05-06 21:45:55 字数 7899 浏览 0 评论 0 收藏

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_DIRSZeroMQ_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_pathfind_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_filefind_programfind_package 。这些命令的签名如下:
    find_path(<VAR> NAMES name PATHS paths)
  3. 如果搜索成功, <VAR> 将保存搜索结果;如果搜索失败,则会设置为 <VAR>-NOTFOUNDNAMESPATHS 分别是 CMake 应该查找的文件的名称和搜索应该指向的路径。
  4. 初步搜索的结果中,可以提取版本号。示例中,ZeroMQ 头文件包含库版本,可以使用字符串操作和正则表达式提取库版本信息。
  5. 最后,调用 find_package_handle_standard_args 命令。处理 find_package 命令的 REQUIREDQUIET 和版本参数,并设置 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_DIRSPYTHON_INTERPRETER 等等。这种方式很难在第三方发布自己的包时,确保依赖关系被满足。

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

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

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

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

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。
列表为空,暂无数据
    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。