接口库（Interface Library）：纯头文件库的最佳实践

说到接口库，我得先坦白一件事。刚接触CMake那会儿，我总觉得这玩意儿有点多余——不就是个库吗？怎么还分接口不接口的？后来在一个大型项目中，我负责维护一套数学工具库，全是模板代码，头文件里塞得满满当当。编译一次要等十分钟，改一行代码就得重编整个项目。嗯，那时候我才意识到，纯头文件库的管理，真不是随便扔几个头文件就能搞定的。

什么是接口库？

接口库，说白了就是一个“虚拟”的库。它不编译任何源文件，不生成任何二进制产物。它的作用只有一个：传递依赖关系和编译选项。

你想想看，纯头文件库（header-only library）没有 .cpp 文件，那 CMake 的 add_library 怎么处理？直接写 add_library(my_library header.hpp) ？这样确实能行，但 CMake 会认为这是个“对象库”或者“普通库”，会尝试去找源文件。如果找不到，就会报错。

接口库就是专门解决这个问题的。用 INTERFACE 关键字声明，CMake 就知道：这是个纯头文件库，别编译它，只管传递它的头文件路径和依赖就行。

声明一个接口库

语法其实很简单。我习惯这样写：

add_library(my_math INTERFACE)

target_include_directories(my_math
    INTERFACE
        ${CMAKE_CURRENT_SOURCE_DIR}/include
)

target_compile_features(my_math
    INTERFACE
        cxx_std_17
)

注意看，这里所有的关键字都是 INTERFACE。这意味着这些设置只对“链接了这个库的目标”生效，对接口库本身没有任何影响——因为它压根不需要编译。

接口库的典型应用场景

我在项目中遇到过三种最常见的场景：

1. 纯模板库：比如 Eigen、nlohmann/json、spdlog（header-only 模式）
2. 编译选项封装：把一堆编译警告、优化选项打包成一个接口库，方便复用
3. 依赖聚合：把多个库的依赖关系集中管理，避免重复写 target_link_libraries

举个例子，假设你有一个模板数学库，结构是这样的：

project/
├── CMakeLists.txt
├── include/
│   └── math/
│       ├── vector.hpp
│       ├── matrix.hpp
│       └── quaternion.hpp
└── examples/
    └── main.cpp

CMakeLists.txt 可以这样写：

add_library(math_tools INTERFACE)

target_include_directories(math_tools
    INTERFACE
        ${CMAKE_CURRENT_SOURCE_DIR}/include
)

target_link_libraries(math_tools
    INTERFACE
        Eigen3::Eigen
        fmt::fmt
)

add_executable(demo examples/main.cpp)
target_link_libraries(demo PRIVATE math_tools)

这样，demo 这个可执行文件就能自动获得 math_tools 的头文件路径，以及 Eigen 和 fmt 的依赖。是不是清爽多了？

接口库的依赖传递机制

这里有个关键点，我当年踩过坑。接口库的依赖传递是“透传”的。什么意思呢？

假设你有三个库：A（接口库）、B（普通库）、C（可执行文件）。

add_library(A INTERFACE)
target_link_libraries(A INTERFACE B)

add_library(B STATIC b.cpp)
target_link_libraries(B PUBLIC some_dep)

add_executable(C main.cpp)
target_link_libraries(C PRIVATE A)

这时候，C 会获得 A 的所有接口属性，包括 A 传递过来的 B 的依赖。但注意，只有 PUBLIC 和 INTERFACE 的依赖才会传递，PRIVATE 的不会。

接口库的常见陷阱

另一个常见问题是：接口库的 INTERFACE_INCLUDE_DIRECTORIES 路径写错了。因为接口库本身不编译，所以路径错误不会在配置阶段暴露，直到链接的目标编译时才会报找不到头文件。排查起来挺头疼的。

我的建议是：写完接口库后，立刻写一个简单的测试目标链接它，验证路径和依赖是否正确。别等到项目大了再查。

接口库 vs 其他库类型

库类型	是否编译	生成产物	适用场景
STATIC	是	.a / .lib	有源文件的静态库
SHARED	是	.so / .dll	动态库
OBJECT	是	.o / .obj	对象文件集合
INTERFACE	否	无	纯头文件库、编译选项封装

看到没？接口库是唯一一个不产生任何二进制产物的。它就像个“标签”，把一堆编译设置贴上去，然后让其他目标继承。

接口库的最佳实践总结

做了这么多年 CMake，我总结了几条接口库的使用原则：

• 命名清晰：接口库的名字最好带上 _interface 或者 _headers 后缀，一看就知道是纯头文件库
• 版本管理：接口库也可以设置版本号，用 write_basic_package_version_file 生成版本文件
• 安装支持：接口库同样可以 install，把头文件和 CMake 配置文件一起安装
• 测试覆盖：每个接口库至少有一个测试目标，验证头文件能正常包含

接口库的知识体系

下面这张图，是我梳理的接口库核心逻辑。你看一眼就能明白它在整个 CMake 体系中的位置：

接口库就像个“信息中转站”。左边是你要传递的各种配置，右边是受益的目标。它自己不生产代码，只是代码的搬运工。嗯，这个比喻挺贴切的。

---

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