add_subdirectory是CMake多目录项目模块化管理的核心机制，通过拆分子目录并递归执行其CMakeLists.txt，实现目标隔离、依赖显式声明与构建产物统一控制，而aux_source_directory仅扁平收集源文件，无法解决依赖顺序、头文件可见性及链接关系等本质问题。
多目录 C++ 项目必须用 add_subdirectory 拆分管理，硬塞进一个 CMakeLists.txt 是自找麻烦——编译慢、改一处牵全身、新人根本不敢动。
为什么不能只靠 aux_source_directory？
它只是递归收集源文件路径，不解决模块边界、头文件可见性、依赖顺序这些本质问题。比如 utils 用到了 core 的类，但 aux_source_directory 不知道这个依赖关系，链接时直接报 undefined reference。
-
aux_source_directory生成的变量是扁平字符串列表，无法表达“这个库要先编译，那个可执行文件要链接它” - 所有头文件搜索路径得手动拼接，
include_directories(${PROJECT_SOURCE_DIR}/core/include)这种写法在子目录变多后极易漏配或重复 - 构建产物（
.a、.so）默认散落在各子目录下，不利于统一安装或 CI 提取
add_subdirectory 怎么用才不出错？
关键不是加了就行，而是每个子目录的 CMakeLists.txt 必须明确导出自己的接口。父目录只负责组装，不越界干预。
- 子目录里用
target_include_directories(<target> PUBLIC ...)</target>声明哪些头文件路径对下游可见；用PRIVATE限定仅内部使用的头文件（比如core/internal/下的实现细节） - 子目录目标名（如
core_lib）必须全局唯一，避免target_link_libraries(app core_lib core_lib)这种重复链接导致的符号冲突 - 路径参数必须是相对路径，且相对于当前
CMakeLists.txt所在位置，比如根目录写add_subdirectory(src/core)，就不能在src/core/CMakeLists.txt里再写add_subdirectory(../utils)
输出目录和构建产物怎么统一管？
默认情况下，每个 add_subdirectory 会把产物扔在自己目录下，这是最常被忽略的混乱源头。
- 在根目录
CMakeLists.txt开头就设置：set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)、set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) - 不要在子目录里覆盖这些变量，否则不同模块产出位置不一致，
find_package或install就会失效 - 如果某个子目录只提供头文件（比如
include/），用install(DIRECTORY ... DESTINATION include)显式声明，而不是指望target_include_directories自动处理安装路径
真正难的不是写对第一行 add_subdirectory，而是每个子目录的 target_include_directories 范围是否划清、每个 target_link_libraries 是否只链接真正需要的 target——这些细节不抠准，项目一上规模，链接错误和头文件找不到就是常态。
