第七章：头文件与路径管理——target_include_directories() 与 include_directories()
头文件路径管理，说白了就是告诉编译器：「嘿，我的头文件藏在这儿呢！」。很多新手在 CMake 里栽跟头，十有八九都是路径没搞对。我自己刚用 CMake 那会儿，就因为这个折腾了一整个下午——明明代码写得没问题，编译就是报找不到头文件。后来才发现，原来是路径传递的继承关系没搞清楚。
这一章，咱们就把头文件路径这件事彻底讲明白。
7.1 两种添加头文件路径的方式
CMake 提供了两个核心命令来管理头文件搜索路径：include_directories() 和 target_include_directories()。它们有什么区别？
| 命令 | 作用范围 | 推荐使用 |
|---|---|---|
include_directories() |
全局（当前 CMakeLists.txt 及所有子目录） | ❌ 不推荐 |
target_include_directories() |
仅对指定目标生效 | ✅ 强烈推荐 |
嗯，这里要注意：include_directories() 是「老式」写法，它会污染整个构建树。你想想看，一个库的头文件路径，凭什么要让所有目标都看到？这不合理。
核心原则：能用 target_include_directories() 就别用 include_directories()。这是现代 CMake 的共识。
7.2 target_include_directories() 详解
这个命令的完整签名是这样的：
target_include_directories(<target>
<INTERFACE|PUBLIC|PRIVATE>
<dir1> [<dir2> ...]
)三个关键字决定了路径的「可见范围」：
- PRIVATE：路径只对当前目标可见。其他依赖这个目标的目标，看不到这些路径。
- INTERFACE：路径不对当前目标可见，但会传递给依赖它的目标。
- PUBLIC：PRIVATE + INTERFACE 的结合体。当前目标能看到，依赖它的目标也能看到。
我在项目中遇到过这样一个场景：写了一个内部工具库，它的头文件路径只应该被库本身使用，对外暴露的只有接口头文件。这时候，内部路径用 PRIVATE，对外接口路径用 PUBLIC，就非常清晰。
我的习惯：拿不准的时候，先用 PUBLIC。等代码稳定了，再回头优化成 PRIVATE 或 INTERFACE。别一开始就过度设计。
7.3 路径的传递与继承
这是最容易踩坑的地方。我画了一张图，帮你理清路径是怎么传递的：
看到了吗？B 链接了 A，所以 B 能看到 A 的 PUBLIC 路径。但 B 自己的 PRIVATE 路径，C 是看不到的。C 链接了 B，但只能看到 B 的 INTERFACE 路径和 A 传递过来的 PUBLIC 路径。
我曾经踩过的坑：在一个大型项目中，我把所有头文件路径都设成了 PRIVATE，结果链接的时候，依赖库死活找不到头文件。排查了半天才发现——PRIVATE 不会传递啊！后来改成 PUBLIC 才解决。
7.4 实战：一个完整的例子
咱们来看一个实际项目结构：
my_project/
├── CMakeLists.txt
├── src/
│ ├── main.cpp
│ └── CMakeLists.txt
├── lib/
│ ├── math/
│ │ ├── CMakeLists.txt
│ │ ├── include/
│ │ │ └── math/
│ │ │ └── add.h
│ │ └── src/
│ │ └── add.cpp
│ └── utils/
│ ├── CMakeLists.txt
│ ├── include/
│ │ └── utils/
│ │ └── print.h
│ └── src/
│ └── print.cpp
顶层的 CMakeLists.txt：
cmake_minimum_required(VERSION 3.16)
project(MyProject VERSION 1.0)
add_subdirectory(lib/math)
add_subdirectory(lib/utils)
add_subdirectory(src)
lib/math/CMakeLists.txt：
add_library(math STATIC
src/add.cpp
)
target_include_directories(math
PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}/include
)
lib/utils/CMakeLists.txt：
add_library(utils STATIC
src/print.cpp
)
target_include_directories(utils
PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}/include
)
target_link_libraries(utils PUBLIC math)
src/CMakeLists.txt：
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE utils)
这里有个巧妙的设计：utils 用 PUBLIC 链接了 math，所以 my_app 在链接 utils 时，自动就能找到 math 的头文件路径。这就是路径传递的魅力。
小技巧：用 ${CMAKE_CURRENT_SOURCE_DIR} 而不是硬编码路径。这样你的 CMakeLists.txt 移到任何位置都能正常工作。
7.5 include_directories() 的遗留问题
虽然我不推荐用 include_directories()，但老项目里经常见到。它的行为很简单：
include_directories(/path/to/include)
这行代码之后，所有在这个 CMakeLists.txt 及其子目录中定义的目标，都能找到 /path/to/include 下的头文件。听起来很方便？但问题也在这里——
- 你没法控制哪些目标能看到这个路径
- 子目录会被「传染」，可能引入意外的依赖
- 大型项目中，你根本不知道某个头文件是从哪来的
我记得有一次接手一个遗留项目，整个 CMakeLists.txt 里全是 include_directories()，足足有二十多个路径。想删一个，又怕哪个地方依赖它。最后花了整整两天才理清楚。
我的建议：新项目一律用 target_include_directories()。老项目如果允许，逐步迁移过来。别给自己挖坑。
7.6 路径的最佳实践
总结几条我这些年积累的经验：
- 用相对路径，别用绝对路径：
${CMAKE_CURRENT_SOURCE_DIR}/include比/home/user/project/include靠谱一万倍。 - 路径要精确：只添加你真正需要的目录。别图省事把整个项目根目录加进去。
- 利用生成器表达式：比如
$<BUILD_INTERFACE:...>和$<INSTALL_INTERFACE:...>，可以区分构建时和安装后的路径。 - 保持目录结构一致：头文件放在
include/<模块名>/下，源文件放在src/下。这样路径管理会清晰很多。
嗯，路径管理这件事，说白了就是「谁需要什么，就给什么」。别多给，也别少给。多给了，编译变慢，还可能引入奇怪的冲突；少给了，编译报错，还得回头排查。
掌握了 target_include_directories() 和路径传递的规则，你的 CMake 项目就已经迈出了现代化管理的第一步。剩下的，就是在实践中慢慢体会了。
公众号：蓝海资料掘金营，微信 deep3321