5、CMake进阶:库类型(STATIC/SHARED/INTERFACE)、依赖管理、find_package机制

好,咱们继续往下走。上一章我们把CMake的基础语法和项目结构捋了一遍。这一章,咱们要聊点真正有实战价值的东西——库的类型、依赖怎么管,还有那个让无数人头疼的find_package。

说实话,我见过太多项目,CMakeLists.txt写得跟意大利面条似的。库类型乱用,依赖关系一团糟,最后编译报错都找不到北。嗯,咱们今天就把这些坑填上。

5.1 库的三种类型:STATIC、SHARED、INTERFACE

先问个问题:你写了一个模块,别人要用,你给人家什么?

答案无非三种:编译好的静态库(.a或.lib)、动态库(.so或.dll),或者干脆就是一堆头文件。CMake里对应的就是STATIC、SHARED和INTERFACE。

5.1.1 STATIC库:简单粗暴,但小心体积

静态库说白了就是把目标文件打包。链接时直接塞进可执行文件里。好处是部署简单,一个二进制文件搞定。坏处?你想想看,每个用到这个库的可执行文件都拷贝一份,磁盘和内存都浪费。

我个人习惯:工具类、算法库这种频繁被调用的,用静态库。但如果是大型项目,比如有几十个可执行文件,我会慎重——编译一次,硬盘能少好几个G。

add_library(my_math STATIC
    src/add.cpp
    src/sub.cpp
)
target_include_directories(my_math PUBLIC include)

注意那个PUBLIC。我见过有人写成PRIVATE,结果外部调用方死活找不到头文件。嗯,这里要记住:PUBLIC的意思是“我自己用,我的依赖方也能用”。

5.1.2 SHARED库:灵活,但小心DLL Hell

动态库是运行时加载的。多个程序可以共享同一份代码。更新库时,只要接口不变,替换文件就行。

但我在项目中遇到过一个大坑:Windows下,动态库的导出符号必须显式声明。你辛辛苦苦写了个类,编译成DLL,结果别人链接时报“无法解析的外部符号”。为什么?因为你忘了加__declspec(dllexport)。

CMake里生成动态库很简单:

add_library(my_network SHARED
    src/tcp_client.cpp
    src/http_parser.cpp
)
target_compile_definitions(my_network PRIVATE MY_NETWORK_EXPORTS)

那个MY_NETWORK_EXPORTS宏,就是用来控制导出声明的。在头文件里这样写:

#ifdef MY_NETWORK_EXPORTS
#define MY_NETWORK_API __declspec(dllexport)
#else
#define MY_NETWORK_API __declspec(dllimport)
#endif

class MY_NETWORK_API TcpClient {
    // ...
};

我曾经因为忘了加这个宏,调试了整整一个下午。最后发现是CMake里少写了一行target_compile_definitions。你说冤不冤?

5.1.3 INTERFACE库:纯头文件库的救星

INTERFACE库很有意思。它不编译任何源文件,只传递依赖关系。说白了,就是个“虚拟库”。

什么时候用?比如你写了个模板库,或者一个只有头文件的工具集。用INTERFACE库,可以让调用方自动获得所有头文件路径和编译选项。

add_library(my_template INTERFACE)
target_include_directories(my_template INTERFACE include)
target_compile_features(my_template INTERFACE cxx_std_17)

调用方只需要:

target_link_libraries(my_app PRIVATE my_template)

所有头文件路径、C++标准要求,自动继承。干净利落。

我的建议:如果你的库只有头文件,别犹豫,用INTERFACE。别学某些项目,硬生生写个空cpp文件进去,就为了生成一个静态库。那是脱裤子放屁。

5.2 依赖管理:别让依赖变成噩梦

大型项目最怕什么?依赖地狱。A依赖B,B依赖C,C又依赖A的不同版本。我曾经在一个遗留项目里见过,同一个第三方库被链接了三个不同版本,编译倒是过了,运行时直接崩溃。

5.2.1 显式声明依赖

CMake里管理依赖,核心就是target_link_libraries。记住一个原则:谁依赖谁,就在谁的target上声明。

add_library(module_a STATIC a.cpp)
add_library(module_b STATIC b.cpp)
target_link_libraries(module_b PRIVATE module_a)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE module_b)

这样,my_app只需要链接module_b,CMake会自动把module_a也带上。而且PRIVATE关键字保证了module_a的头文件不会泄露给my_app——如果my_app真的需要module_a的头文件,那就应该显式声明。

注意:别滥用PUBLIC。我见过有人图省事,所有依赖都写成PUBLIC。结果一个底层库的头文件泄露到顶层,改个接口,整个项目都要重新编译。那叫一个酸爽。

5.2.2 依赖传递的控制

CMake的依赖传递有三个关键字:PRIVATE、PUBLIC、INTERFACE。怎么选?

关键字 对当前target 对依赖当前target的target
PRIVATE 需要头文件和链接 不传递
PUBLIC 需要头文件和链接 传递头文件和链接
INTERFACE 不需要 传递头文件和链接

举个例子:module_b内部用了module_a,但对外接口不暴露module_a的类型,那就用PRIVATE。如果module_b的某个函数参数是module_a的类型,那就得用PUBLIC。

5.3 find_package机制:找到你的“包”

终于说到find_package了。这玩意儿,说简单也简单,说复杂能写一本书。我尽量用大白话讲清楚。

5.3.1 两种模式:Module模式和Config模式

find_package有两种工作方式:

  • Module模式:CMake自带一堆FindXXX.cmake脚本,比如FindBoost.cmake、FindOpenSSL.cmake。它会去系统路径里找库。
  • Config模式:库自己提供了XXXConfig.cmake或xxx-config.cmake文件。这种更可靠,因为库的作者最清楚怎么找到它自己。

CMake会先尝试Module模式,找不到再尝试Config模式。你也可以强制指定:

find_package(Boost REQUIRED)          # 先Module,再Config
find_package(OpenCV CONFIG REQUIRED)  # 强制Config模式

5.3.2 实战:找OpenCV

假设你装了OpenCV,想用CMake找到它:

find_package(OpenCV REQUIRED
    COMPONENTS core imgproc highgui
)

if(OpenCV_FOUND)
    include_directories(${OpenCV_INCLUDE_DIRS})
    target_link_libraries(my_app ${OpenCV_LIBS})
endif()

但这里有个坑:OpenCV_LIBS这个变量,不同版本可能不一样。我建议用更现代的方式:

find_package(OpenCV REQUIRED COMPONENTS core imgproc)
target_link_libraries(my_app PRIVATE OpenCV::core OpenCV::imgproc)

这种OpenCV::core的写法,是CMake的“导入目标”(Imported Target)。它自动包含了头文件路径、链接库、甚至编译选项。干净、安全、可移植。

核心原则:能用导入目标,就别用变量。变量是CMake 2.x时代的产物,导入目标才是现代CMake的推荐做法。

5.3.3 自己写Config文件

如果你自己写了一个库,想让别人用find_package找到它,那就得提供XXXConfig.cmake文件。

CMake提供了install(EXPORT)机制,可以自动生成:

add_library(my_lib STATIC src/my_lib.cpp)
target_include_directories(my_lib PUBLIC include)

install(TARGETS my_lib
    EXPORT MyLibTargets
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    INCLUDES DESTINATION include
)

install(EXPORT MyLibTargets
    FILE MyLibConfig.cmake
    NAMESPACE MyLib::
    DESTINATION lib/cmake/MyLib
)

这样,别人安装你的库后,就可以这样用:

find_package(MyLib REQUIRED)
target_link_libraries(my_app PRIVATE MyLib::my_lib)

我曾经在一个开源项目里看到,作者手动写了一个FindXXX.cmake,写了三百多行,各种路径判断、版本检测。其实用install(EXPORT),十行代码搞定。嗯,有时候我们就是喜欢把事情搞复杂。

5.3.4 常见问题与避坑

  • 找不到包? 设置CMAKE_PREFIX_PATH,告诉CMake去哪找。
  • 版本不对? 用find_package(XXX 3.0 EXACT)强制版本。
  • 组件缺失? 检查COMPONENTS拼写,我犯过这种低级错误。
  • Config文件冲突? 系统装了多个版本?用find_package(XXX CONFIG PATHS /custom/path)指定路径。
我曾经踩过的坑:有一次,find_package找到了一个旧版本的库,但系统里明明装了新版。查了半天,发现是CMAKE_PREFIX_PATH里有个路径指向了旧版本的安装目录。CMake按路径顺序查找,先找到的就用了。从那以后,我每次都会用message(STATUS "Found XXX: ${XXX_DIR}")确认一下找到的是哪个版本。

5.4 小结

这一章我们聊了:

  • 三种库类型:STATIC(静态库)、SHARED(动态库)、INTERFACE(纯头文件库)
  • 依赖管理:PRIVATE、PUBLIC、INTERFACE的用法和区别
  • find_package:Module模式 vs Config模式,以及如何自己写Config文件

说实话,这些内容看起来简单,但真正用好,需要在实际项目中反复打磨。我见过太多项目,CMakeLists.txt写得乱七八糟,最后编译不过,大家互相甩锅。其实,只要遵循“显式声明依赖”、“用导入目标”、“避免全局变量”这几个原则,大部分问题都能避免。

下一章,咱们聊聊测试框架和持续集成。嗯,那又是另一个故事了。