CMake模块与find_package：内置模块与自定义Find模块

说到CMake的模块系统，我最早接触的时候其实挺懵的。那时候刚接手一个跨平台项目，要在Linux和Windows上分别链接不同的线程库。同事丢给我一句「用FindThreads啊」，我愣了半天——什么是Find模块？

后来我才明白，find_package 是CMake里最实用的功能之一。说白了，它就是帮你自动找到第三方库的头文件和库文件位置。你想想看，如果没有它，你得手动写一堆路径判断，不同操作系统还得分别处理，那代码得多难看。

内置模块：开箱即用的便利

CMake自带了几十个Find模块，放在 Modules/ 目录下。常用的有：

• FindThreads — 线程库查找
• FindOpenSSL — SSL加密库
• FindBoost — Boost库
• FindPython — Python解释器和库
• FindZLIB — 压缩库

使用方式很简单，一行命令搞定：

find_package(Threads REQUIRED)
find_package(OpenSSL REQUIRED)

加上 REQUIRED 表示这个库是必须的，找不到就报错。如果你希望找不到也能继续编译，可以不加它。

实战：FindThreads 使用示例

我记得有一次在嵌入式Linux上做多线程采集程序，需要链接pthread库。不同平台下线程库的名字不一样——Linux叫 pthread，Windows下是 pthreadVC2 或者直接用Windows API。手动处理这些差异？太累了。

用FindThreads就简单了：

cmake_minimum_required(VERSION 3.10)
project(ThreadDemo)

find_package(Threads REQUIRED)

add_executable(demo main.cpp)
target_link_libraries(demo PRIVATE Threads::Threads)

这里有个细节：Threads::Threads 是CMake提供的导入目标（Imported Target）。它不光帮你链接了正确的库，还自动设置了编译选项和宏定义。比如在Linux上，它会自动添加 -pthread 编译选项。

实战：FindOpenSSL 使用示例

做网络通信的项目，OpenSSL几乎是标配。但不同系统上OpenSSL的安装位置千差万别：

• Ubuntu上在 /usr/lib/x86_64-linux-gnu/
• macOS上可能在 /usr/local/opt/openssl/
• Windows上更是五花八门

用FindOpenSSL，这些差异都被隐藏了：

find_package(OpenSSL REQUIRED)

if(OPENSSL_FOUND)
    message("OpenSSL版本: ${OPENSSL_VERSION}")
    message("包含目录: ${OPENSSL_INCLUDE_DIR}")
endif()

target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto)
target_include_directories(myapp PRIVATE ${OPENSSL_INCLUDE_DIR})

嗯，这里要注意：虽然 OpenSSL::SSL 和 OpenSSL::Crypto 是导入目标，但 OPENSSL_INCLUDE_DIR 仍然是一个普通变量。我建议你优先使用导入目标，只有在需要手动指定包含目录时才用变量。

编写自定义Find模块

内置模块虽然多，但总有覆盖不到的时候。比如我做过一个项目，要用到某家芯片厂商的私有SDK，那肯定没有现成的Find模块。这时候就得自己写了。

一个标准的Find模块长这样：

# FindMySDK.cmake
# 查找MySDK库

# 查找头文件
find_path(MYSDK_INCLUDE_DIR
    NAMES mysdk.h
    PATHS /usr/local/include
          /opt/mysdk/include
)

# 查找库文件
find_library(MYSDK_LIBRARY
    NAMES mysdk libmysdk
    PATHS /usr/local/lib
          /opt/mysdk/lib
)

# 处理找到/未找到的情况
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(MySDK
    REQUIRED_VARS MYSDK_INCLUDE_DIR MYSDK_LIBRARY
    VERSION_VAR MYSDK_VERSION
)

# 创建导入目标
if(MYSDK_FOUND AND NOT TARGET MySDK::MySDK)
    add_library(MySDK::MySDK UNKNOWN IMPORTED)
    set_target_properties(MySDK::MySDK PROPERTIES
        IMPORTED_LOCATION "${MYSDK_LIBRARY}"
        INTERFACE_INCLUDE_DIRECTORIES "${MYSDK_INCLUDE_DIR}"
    )
endif()

# 导出变量供调用方使用
mark_as_advanced(MYSDK_INCLUDE_DIR MYSDK_LIBRARY)

这个模块的核心逻辑其实就三步：

1. 查找 — 用 find_path 和 find_library 定位文件
2. 验证 — 用 find_package_handle_standard_args 检查是否找到
3. 导出 — 创建导入目标，暴露给调用方

自定义模块的搜索路径

你写好的Find模块放在哪里？CMake默认会在 CMAKE_MODULE_PATH 指定的路径下搜索。所以你需要：

# 在CMakeLists.txt开头设置
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/Modules")

# 然后就可以用了
find_package(MySDK REQUIRED)

我个人习惯把自定义Find模块放在项目根目录下的 cmake/Modules/ 文件夹里，这样结构清晰，也方便其他开发者理解。

模块编写避坑指南

写自定义模块时，有几个地方容易出问题：

• 命名规范：Find模块的文件名必须和 find_package 的参数一致。比如 find_package(MySDK) 对应 FindMySDK.cmake，大小写敏感。
• 变量作用域：在Find模块中设置的变量（如 MYSDK_FOUND）会自动传递到调用方的作用域。但用 set(... PARENT_SCOPE) 也可以手动控制。
• 版本检查：如果库有版本信息，记得实现 VERSION_VAR 支持。这样用户可以用 find_package(MySDK 2.0 EXACT) 来指定版本。

知识体系总览

下面这张图总结了CMake模块系统的核心逻辑：

从图中可以看到，find_package 会根据模块类型走不同的分支。内置模块直接使用，自定义模块则需要先设置 CMAKE_MODULE_PATH。最终都会生成导入目标和变量，供你的项目使用。

总结

CMake的模块系统，说白了就是帮你省去手动查找库的麻烦。内置模块覆盖了大部分常见库，开箱即用。遇到冷门库，自己写个Find模块也不复杂——记住那三步：查找、验证、导出。

我在项目中见过不少开发者，明明可以用 find_package 却偏要手写路径，结果换台机器就编译不过。其实你花半小时写好一个Find模块，整个团队都能受益。嗯，这就是工程化的思维。

---

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