target_include_directories用于为指定目标（如可执行文件或库）精确添加头文件搜索路径，避免全局污染；基本写法为target_include_directories( private|public|interface )，其中private仅当前目标有效、public双向生效、interface仅传递给依赖者。

target_include_directories 作用和基本写法

它不是给整个项目加头文件路径，而是专门给某个 target（比如可执行文件或库）指定编译时的 -I 路径。CMake 不会自动把 include/ 或 src/ 加进去，必须显式声明。

• 第一个参数是目标名，必须是已用 add_executable 或 add_library 创建过的
• 后续参数是路径，支持绝对路径、相对路径（相对于当前 CMakeLists.txt）、生成时变量（如 ${CMAKE_BINARY_DIR}）
• 推荐用 PRIVATE / PUBLIC / INTERFACE 限定作用域，避免污染其他 target

add_library(mylib src/mylib.cpp)
target_include_directories(mylib PRIVATE include)

PRIVATE/PUBLIC/INTERFACE 的区别和选哪个

这是最容易配错的地方：选错会导致头文件找不到，或者下游 target 意外继承了不该有的路径。

• PRIVATE：只影响该 target 编译，不传递给依赖它的 target
• PUBLIC：既影响自己，也传递给所有链接它的 target（适合库的 public headers）
• INTERFACE：只传递，不用于自身编译（比如只提供头文件的 header-only 库）

常见错误：

• 把库的头文件路径写成 PRIVATE → 下游链接这个库时找不到头文件
• 把内部实现头路径写成 PUBLIC → 外部 target 误用内部头，破坏封装

add_library(jsoncpp INTERFACE)
target_include_directories(jsoncpp INTERFACE ${JSONCPP_INCLUDE_DIRS})

路径里带 $<...> 表达式怎么写才安全

CMake 支持生成时求值的表达式，比如 $<include></include>，但写错会静默失效或报错。

Access global ocean tides model. Functions include tide height at a given date/time/location, tide extrema, and grid weather data.

访问全球海洋潮汐模型。功能包括查询指定日期、时间和地点的潮高、潮汐极值及格点天气数据。

下载

• 所有 $<...></...> 必须整体包裹在双引号里，否则 CMake 解析失败
• 常见组合：$<build_interface:></build_interface:>（构建时路径） + $<include></include>（安装后路径）
• 不要混用 ${...} 和 $<...></...> 在同一参数中，除非明确知道求值时机差异

target_include_directories(mylib PUBLIC
  "$<build_interface:>"
  "$<include>"
)</include></build_interface:>

和 include_directories() 的关键区别

include_directories() 是全局作用域，会影响当前 CMakeLists.txt 及其子目录里所有后续 target，极易造成路径泄漏。

• 已废弃倾向：CMake 官方文档明确建议用 target_include_directories() 替代
• 兼容性陷阱：如果项目里混用两者，include_directories() 的路径可能覆盖或干扰 target 级配置
• 跨目录问题：子目录 add_subdirectory() 中的 target 不会自动继承父目录的 include_directories()，但会继承通过 PUBLIC 传递的 target_include_directories()

真正需要“全局头路径”的场景极少，绝大多数情况应该绑定到具体 target。

路径拼接错误、作用域漏写、表达式没加引号——这三个点卡住的人最多。配完记得用 cmake --build . --verbose 看实际传给编译器的 -I 参数对不对。