add_subdirectory是模块化构建的入口开关，它触发子目录CMakeLists.txt执行并使定义的目标进入父作用域；变量默认不跨作用域传递，需PARENT_SCOPE显式回传；头文件路径应优先用target_include_directories按依赖关系精确控制可见性；链接依赖必须通过target_link_libraries显式声明目标名，而非文件路径或隐式顺序。

直接说结论：靠 add_subdirectory 拆分职责，靠 include_directories 和 target_include_directories 控制头文件可见性，靠 target_link_libraries 显式声明模块依赖。硬写一堆 aux_source_directory 或全塞进根目录 CMakeLists.txt，迟早出链接错误或头文件找不到。

add_subdirectory 是模块化构建的入口开关

它不是“把子目录加进来”那么简单，而是触发子目录下 CMakeLists.txt 的执行，并让其定义的目标（add_library、add_executable）进入当前作用域。父目录能看见子目录里定义的 target 名，但不能直接访问子目录变量（除非用 set(... PARENT_SCOPE)）。

• 必须确保子目录存在且含有效的 CMakeLists.txt，否则 CMake configure 阶段直接报错：add_subdirectory given source directory "xxx" which is not a directory
• 路径是相对于当前 CMakeLists.txt 的，比如 add_subdirectory(src/utils)，不是 add_subdirectory(${PROJECT_SOURCE_DIR}/src/utils)
• 慎用 EXCLUDE_FROM_ALL：加了它，子目录里的 target 默认不会被 make 或 cmake --build . 构建，除非显式指定目标名，比如 cmake --build . --target utils_lib

头文件路径不能只靠 include_directories

include_directories 是全局作用域指令，它会让后续所有 add_executable 和 add_library 都自动带上这些路径——这在简单项目里省事，但在多模块项目里极易引发污染：比如 src/network 不该知道 src/gui 的私有头。

C++ Code Review Master

组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。

下载

• 优先用 target_include_directories(<target> PRIVATE|PUBLIC|INTERFACE <path>)</path></target>：PRIVATE 表示只本 target 编译时用；PUBLIC 表示本 target 编译用 + 链接它的 target 也能用；INTERFACE 表示只给链接者用（常用于头文件库）
• 路径尽量用相对 ${CMAKE_CURRENT_SOURCE_DIR} 或 ${PROJECT_SOURCE_DIR}，避免硬编码绝对路径
• 如果子模块 utils 提供了公共头 utils/Log.h，它自己的 CMakeLists.txt 应写：target_include_directories(utils PUBLIC $<INSTALL_INTERFACE:include> $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>)

链接依赖必须显式声明，不能靠“顺序”或“名字碰巧对上”

很多人以为只要先 add_library(utils ...) 再 add_executable(app ...)，然后 target_link_libraries(app utils) 就完事了——但若 utils 本身依赖 json 库，而 app 又没链接 json，编译器大概率报 undefined reference。

• target_link_libraries 的参数必须是已定义的 target 名（如 utils），不是文件名（如 libutils.a）或路径
• 若 utils 是 PUBLIC 依赖了 json，则 app 链接 utils 时会自动继承 json，无需重复写 target_link_libraries(app utils json)
• 跨目录链接时，确保子目录 CMakeLists.txt 中的 add_library 名和父目录 target_link_libraries 中写的名完全一致（大小写敏感）
• Windows 下若用 MSVC，静态库需注意 /MT vs /MD 运行时一致性，否则链接时报 LNK2038

外部构建目录（out-of-source）不是可选项

把 build/ 放在项目根目录下，而不是混在源码里，是避免污染和保证可重现性的底线。一旦你用 cmake .. 在源码目录里生成 Makefile，下次改 CMakeLists.txt 后再 make，旧中间文件可能残留导致奇怪行为。

• 标准流程是：mkdir build && cd build && cmake .. && cmake --build .
• PROJECT_BINARY_DIR 指向的就是这个 build/ 目录，而 PROJECT_SOURCE_DIR 永远指向根 CMakeLists.txt 所在位置，这两个变量别搞混
• 不要在 CMakeLists.txt 里写 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/bin) 这类反模式——输出路径应基于 PROJECT_BINARY_DIR，否则跨平台构建时 Windows 的 DLL 和 Linux 的 so 会乱套

最常被忽略的一点：CMake 的作用域不是“文件级”，而是“目录级”。每个 add_subdirectory 调用都开启一个新作用域，变量默认不向上穿透。你以为在子目录里 set(FOO bar) 后父目录能读到？不能。得加 PARENT_SCOPE。这点不厘清，find_package 结果传不上去、编译选项漏配置，问题就藏得很深。