14、查找包：find_package详解。如何查找系统已安装的库（如Boost、OpenCV），理解MODULE与CONFIG模式的区别。

说实话，find_package 是 CMake 里最容易被误解的命令之一。我刚入行那会儿，总觉得它就是个「自动找库」的黑魔法——写一行 find_package(Boost)，然后就能用 Boost::filesystem 了。直到有一次在客户服务器上死活找不到 OpenCV，我才老老实实把它的两种工作模式搞明白。

今天咱们就把这块硬骨头啃下来。你想想看，一个命令凭什么既能找到系统里的 Boost，又能找到你自己编译的 OpenCV？秘密就在于它有两种模式：MODULE 模式 和 CONFIG 模式。

14.1 两种模式的核心区别

说白了，find_package 的工作流程是这样的：

  1. 先尝试 CONFIG 模式——找包自带的 <Package>Config.cmake 或 <lower-case-package>-config.cmake 文件。
  2. 如果没找到，且命令中没写 CONFIG 关键字，就回退到 MODULE 模式——找 CMake 自带的 Find<Package>.cmake 模块。

我个人的习惯是：能用 CONFIG 模式就别用 MODULE 模式。为什么？因为 CONFIG 模式是库的作者亲自写的，版本信息、依赖关系、目标定义都更准确。MODULE 模式是 CMake 社区维护的，有时候会滞后。

一句话总结：MODULE 模式是 CMake 帮你「猜」库在哪；CONFIG 模式是库自己告诉你「我在这」。

14.2 MODULE 模式：Find<Package>.cmake

MODULE 模式依赖的是 FindXXX.cmake 文件。这些文件通常放在 CMake 的安装目录下，比如 /usr/share/cmake-3.27/Modules/FindBoost.cmake。

它的工作方式是：通过搜索系统路径、环境变量、注册表等，尝试定位库的头文件和二进制文件。找到后，通常会设置一些变量，比如：

find_package(Boost REQUIRED COMPONENTS filesystem system)

# MODULE 模式下会设置这些变量
message(STATUS "Boost_INCLUDE_DIRS: ${Boost_INCLUDE_DIRS}")
message(STATUS "Boost_LIBRARIES: ${Boost_LIBRARIES}")
message(STATUS "Boost_VERSION: ${Boost_VERSION}")

# 然后你需要手动处理包含目录和链接
include_directories(${Boost_INCLUDE_DIRS})
target_link_libraries(myapp ${Boost_LIBRARIES})

嗯，这里要注意：MODULE 模式通常不创建 IMPORTED 目标。你得自己处理 include_directories 和 target_link_libraries。这在现代 CMake 里其实有点「过时」了。

我曾经踩过的坑：在 Ubuntu 18.04 上用 find_package(Boost)，结果找到的是系统自带的 1.65 版本。但我需要 1.71 的新特性。后来发现 MODULE 模式只会搜默认路径，不会看 BOOST_ROOT 环境变量——除非你显式设置 set(BOOST_ROOT /opt/boost-1.71)。

14.3 CONFIG 模式：<Package>Config.cmake

CONFIG 模式是 CMake 3.0 之后主推的方式。库的作者在安装时，会生成一个 <Package>Config.cmake 文件，里面包含了库的版本、依赖关系、以及 IMPORTED 目标。

拿 OpenCV 举例：

find_package(OpenCV REQUIRED CONFIG)

# CONFIG 模式下，直接使用 IMPORTED 目标
target_link_libraries(myapp PRIVATE opencv_core opencv_imgproc opencv_highgui)

# 不需要手动设置 include_directories，目标已经包含了头文件路径
# 不需要手动设置链接目录，目标已经包含了库路径

你看，代码干净多了。而且 opencv_core 这个目标自带所有属性：头文件路径、库文件路径、甚至编译选项。这就是「目标导向」的精髓。

小技巧：如果你不确定一个包是否支持 CONFIG 模式，可以试试 cmake --find-package -DNAME=OpenCV -DCOMPILER_ID=GNU -DLANGUAGE=CXX -DMODE=EXIST。或者直接看包安装目录下有没有 *.cmake 文件。

14.4 如何强制指定模式

有时候你需要明确告诉 CMake 用哪种模式：

# 强制 CONFIG 模式
find_package(OpenCV REQUIRED CONFIG)

# 强制 MODULE 模式
find_package(Boost REQUIRED MODULE)

# 先 CONFIG，找不到也不回退到 MODULE
find_package(OpenCV REQUIRED CONFIG NO_MODULE)

我个人建议：新项目一律用 CONFIG 模式。如果包不支持 CONFIG 模式（比如一些老旧的库），再考虑 MODULE 模式或者自己写 Find 模块。

14.5 查找路径的优先级

CMake 查找包的路径顺序是这样的：

  1. <Package>_DIR 或 <Package>_ROOT 变量指定的路径
  2. CMAKE_PREFIX_PATH 环境变量或 CMake 变量
  3. CMAKE_FRAMEWORK_PATH（macOS）
  4. 系统默认路径（/usr/lib、/usr/local/lib 等）

举个例子，如果你自己编译了 OpenCV 并安装到了 /opt/opencv-4.8：

# 方法1：设置变量
set(OpenCV_DIR /opt/opencv-4.8/lib/cmake/opencv4)
find_package(OpenCV REQUIRED CONFIG)

# 方法2：使用 CMAKE_PREFIX_PATH
list(APPEND CMAKE_PREFIX_PATH /opt/opencv-4.8)
find_package(OpenCV REQUIRED CONFIG)
重要：CMAKE_PREFIX_PATH 是全局的，会影响所有 find_package 调用。而 <Package>_DIR 只影响当前包。我一般用 CMAKE_PREFIX_PATH 来统一管理第三方库的安装根目录。

14.6 版本检测与组件选择

实际项目中，你经常需要指定版本和组件：

# 要求最低版本 1.70，且需要 filesystem 和 system 组件
find_package(Boost 1.70 REQUIRED COMPONENTS filesystem system)

# 精确版本范围（CMake 3.19+）
find_package(OpenCV 4.5...4.9 EXACT REQUIRED CONFIG)

# 可选组件
find_package(VTK REQUIRED COMPONENTS
    CommonCore
    FiltersCore
    OPTIONAL_COMPONENTS
        RenderingOpenGL2
)

版本检测在 CONFIG 模式下特别可靠，因为 <Package>ConfigVersion.cmake 文件里包含了精确的版本比较逻辑。MODULE 模式有时候只能拿到主版本号，细节版本可能缺失。

14.7 知识体系图

下面这张图帮你理清 find_package 的完整决策流程：

find_package 决策流程 find_package(<Package>) 存在 <Package>Config.cmake？ CONFIG 模式 使用 IMPORTED 目标 存在 Find<Package>.cmake？ MODULE 模式 设置变量 报错 / 跳过 优先 CONFIG 模式（库自描述）→ 回退 MODULE 模式（CMake 猜测） 推荐：新项目使用 CONFIG 模式 + IMPORTED 目标

14.8 实战建议

最后，分享几个我在项目中积累的经验：

  • 优先使用 CONFIG 模式：如果库支持，就用 CONFIG 关键字强制指定。这样代码更健壮，依赖关系更清晰。
  • 善用 CMAKE_PREFIX_PATH：在项目根目录的 CMakeLists.txt 开头设置这个变量，统一管理所有第三方库的路径。比每个包单独设 XXX_DIR 清爽得多。
  • 版本号别写死：除非你有特殊要求，否则用 find_package(XXX REQUIRED) 就够了。版本号写死了，换环境就容易出问题。
  • 调试时加 --debug-find：如果 find_package 找不到库，运行 cmake --debug-find .. 可以看到它搜索了哪些路径。这个参数救过我很多次。
我的习惯：在项目里建一个 cmake/ 目录，里面放一些自定义的 Find 模块。对于那些不支持 CONFIG 模式的旧库，自己写一个 Find 模块，封装成 IMPORTED 目标。这样项目里所有第三方库的使用方式就统一了。

好了，关于 find_package 的核心内容就这些。记住：CONFIG 模式是库自己告诉你它在哪，MODULE 模式是 CMake 帮你猜。能选前者就别用后者。下次遇到找不到库的问题，先想想是哪种模式，再对症下药。

公众号:蓝海资料掘金营，微信deep3321

← 上一章 📖 返回目录 下一章 →