7、CMake模块与find_package：include()、find_package()机制、编写自定义Find模块
好，咱们今天聊聊CMake里的模块机制。说实话，这玩意儿刚接触时我也觉得有点绕，但用熟了就会发现——它其实是CMake最优雅的设计之一。
你想想看，一个项目往往要依赖几十个第三方库。每个库的头文件在哪？库文件在哪？要不要加特定宏？如果每个项目都手写这些配置，那不得累死？CMake的模块系统就是来解决这个问题的。
7.1 include()：模块加载的基本方式
include()是CMake里最直接的代码复用手段。它的作用很简单：把另一个文件里的内容，原封不动地“粘贴”到当前位置执行。
# 加载一个.cmake文件
include(SomeModule)
# 或者指定路径
include(/path/to/MyCustomModule.cmake)我个人习惯把通用函数、宏定义、工具函数都放到单独的.cmake文件里，然后用include()引入。这样主CMakeLists.txt会清爽很多。
7.2 find_package()：自动发现依赖库
find_package()才是今天的重头戏。它做的事情，说白了就是：帮你去系统里“找”一个库，找到后把它的头文件路径、库文件路径、编译选项等设置好。
find_package(OpenCV REQUIRED)
find_package(Boost COMPONENTS filesystem system REQUIRED)
find_package(CURL QUIET)这里有几个关键参数：
- REQUIRED：找不到就报错，直接终止配置
- QUIET：找不到也别嚷嚷，安静点
- COMPONENTS：指定需要库的哪些组件
- MODULE：强制使用Find模块模式（后面会讲）
find_package()有两种工作模式：模块模式和配置模式。
模块模式
CMake会在CMAKE_MODULE_PATH里找Find<PackageName>.cmake文件。找到了就执行它，由这个Find模块负责定位库。
配置模式
CMake会找<PackageName>Config.cmake或<lower-case-package-name>-config.cmake。这个文件通常由库的安装包自带。
MODULE关键字强制只用模块模式。
7.3 编写自定义Find模块
好，到了实战环节。假设你公司内部有个老库叫FooLib，没有提供CMake配置文件。这时候就得自己写个FindFooLib.cmake。
我曾经在一个嵌入式项目里干过这事。那个库的安装路径五花八门，有的在/opt，有的在/usr/local，还有的直接放在项目目录下。不写个Find模块，每次配置都得手动设路径，太痛苦了。
一个标准的Find模块长这样：
# FindFooLib.cmake
# 查找FooLib库的CMake模块
# 先找头文件
find_path(FooLib_INCLUDE_DIR
NAMES foo.h
PATHS /usr/include /usr/local/include /opt/FooLib/include
)
# 再找库文件
find_library(FooLib_LIBRARY
NAMES foo FooLib
PATHS /usr/lib /usr/local/lib /opt/FooLib/lib
)
# 处理找到的结果
if(FooLib_INCLUDE_DIR AND FooLib_LIBRARY)
set(FooLib_FOUND TRUE)
set(FooLib_INCLUDE_DIRS ${FooLib_INCLUDE_DIR})
set(FooLib_LIBRARIES ${FooLib_LIBRARY})
# 如果是共享库，可能还需要添加运行时路径
if(WIN32)
set(FooLib_RUNTIME_DIR "${FooLib_LIBRARY_DIR}")
endif()
else()
set(FooLib_FOUND FALSE)
if(FooLib_FIND_REQUIRED)
message(FATAL_ERROR "FooLib not found!")
endif()
endif()
# 导出为高级变量（在cmake-gui中默认隐藏）
mark_as_advanced(FooLib_INCLUDE_DIR FooLib_LIBRARY)然后在你项目的CMakeLists.txt里：
# 告诉CMake去哪里找自定义Find模块
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules")
# 使用自定义模块
find_package(FooLib REQUIRED)
# 使用找到的库
target_include_directories(myapp PRIVATE ${FooLib_INCLUDE_DIRS})
target_link_libraries(myapp PRIVATE ${FooLib_LIBRARIES})set(FooLib_FOUND TRUE)，但忘了检查实际路径是否有效。结果CMake报告找到了，编译时却报头文件缺失。所以一定要在find_path和find_library之后再做判断，别想当然。
7.4 知识体系总览
下面这张图帮你理清整个模块系统的脉络：
7.5 模块模式 vs 配置模式：怎么选？
| 对比维度 | 模块模式（Find模块） | 配置模式（Config文件） |
|---|---|---|
| 谁提供 | 使用者（项目开发者） | 库的维护者 |
| 适用场景 | 老旧库、内部库、没有CMake支持的库 | 现代库、已安装的第三方库 |
| 灵活性 | 高，可以自定义查找逻辑 | 低，按库作者预设的方式暴露 |
| 维护成本 | 需要自己写和维护 | 库升级时自动更新 |
| 典型例子 | FindBoost（早期版本）、FindCUDA | OpenCVConfig.cmake、PkgConfig |
我个人建议：如果库本身提供了Config文件，优先用配置模式。只有那些“老古董”库，才需要自己写Find模块。嗯，当然，如果你在公司里需要统一管理多个项目的依赖，写一套自定义Find模块也是值得的。
7.6 实战建议
最后分享几个我在项目中积累的经验：
- 路径搜索顺序要合理：先搜标准路径，再搜用户自定义路径，最后搜环境变量。别把顺序搞反了。
- 善用
find_package的版本检查：find_package(FooLib 2.0 EXACT)可以精确控制版本，避免API不兼容。 - 导出IMPORTED目标：现代CMake更推荐用
add_library(FooLib::FooLib UNKNOWN IMPORTED)的方式暴露库，而不是设置一堆变量。这样更符合“现代CMake”的哲学。 - 别忘了
mark_as_advanced：把内部查找路径标记为高级变量，避免普通用户被一堆内部变量吓到。
find_package支持了CONFIG和MODULE关键字的同时使用。比如find_package(FooLib CONFIG)会强制只用配置模式。这个特性在排查问题时特别有用。
好了，关于CMake模块和find_package的机制，今天就聊到这儿。记住一句话：模块系统是CMake的“插件机制”，用好它，你的项目配置会变得异常灵活。下次遇到找不到库的问题，先别急着硬编码路径——写个Find模块，一劳永逸。