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
的手册页面。
更多信息
总而言之,有四种方式可用于找到依赖包:
- 使用由包供应商提供 CMake 文件
<package>Config.cmake
,<package>ConfigVersion.cmake
和<package>Targets.cmake
,通常会在包的标准安装位置查找。 - 无论是由 CMake 还是第三方提供的模块,为所需包使用
find-module
。 - 使用
pkg-config
,如本节的示例所示。 - 如果这些都不可行,那么编写自己的
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 查找文件。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论