add_subdirectory 是 CMake 唯一支持真正作用域隔离的子目录构建方式；include 仅做内容粘贴，导致变量和 target 混杂、链接属性失控，而 add_subdirectory 启动新作用域，保障模块化可控性。
直接用 add_subdirectory，别想绕开它——这是 CMake 唯一支持的、能真正隔离作用域并构建子目录目标的标准方式。
为什么不能用 include 替代 add_subdirectory
include 只是把另一个 CMakeLists.txt 文件的内容“粘贴”进当前作用域，所有变量、target 定义都混在一起，根本起不到模块隔离效果。比如你在 src/utils/CMakeLists.txt 里写了 add_library(utils ...)，用 include(src/utils/CMakeLists.txt) 后，这个 utils 库就和顶层定义的 target 处于同一作用域，target_link_libraries 看起来能用，但一旦你加了 PRIVATE 或 INTERFACE，链接属性就全乱套了。
而 add_subdirectory 会启动一个新的作用域，子目录中定义的变量默认不可被父目录读取，target_link_libraries 也只允许链接当前作用域或上层作用域中定义的目标（不能反向跨级引用），这才是可控的模块化。
add_subdirectory 的三个参数怎么填才不踩坑
-
source_dir必须存在且含CMakeLists.txt；相对路径是相对于当前CMakeLists.txt所在目录，不是源码根目录 -
binary_dir几乎不用显式指定——除非你要把构建产物强制落到某个非镜像路径（比如把third_party/openssl的构建输出统一放到build/external/openssl） -
EXCLUDE_FROM_ALL要慎用：加了它，子目录里的add_executable或add_library默认不会被make或cmake --build .构建，除非被其他 target 显式依赖（比如target_link_libraries(myapp PRIVATE openssl)会触发 openssl 构建）
子目录里怎么暴露头文件和链接接口
子目录的 CMakeLists.txt 必须主动导出自己的接口，否则上层根本不知道怎么用它：
- 用
target_include_directories(mylib PUBLIC include)把头文件路径设为PUBLIC，这样上层target_link_libraries(myapp PRIVATE mylib)后，myapp就能自动找到#include "mylib.h" - 不要在子目录里写
include_directories(include)—— 这是全局污染，对依赖它的 target 没有约束力 - 如果子目录只提供头文件（如
fmt这类 header-only 库），仍需定义一个INTERFACElibrary：add_library(fmt INTERFACE)，再配target_include_directories(fmt INTERFACE include)
常见错误现象和对应检查点
编译时报 Cannot find source file 或 target_link_libraries called with incorrect number of arguments，大概率是下面这几个地方错了：
- 子目录下漏了
CMakeLists.txt，或者文件名拼错成CMakeList.txt或cmakelists.txt - 上层
add_subdirectory(foo)，但实际路径是src/foo，没写对相对路径 - 子目录中用了
add_executable，但上层没通过target_link_libraries或add_dependencies建立依赖关系，又没加EXCLUDE_FROM_ALL，导致构建时找不到入口 - 头文件路径写成
#include "../include/mylib.h"，但子目录的target_include_directories没设对，或设成了PRIVATE而不是PUBLIC
最易被忽略的是作用域边界：子目录里的 set(MY_VAR "value") 在父目录里完全不可见，别指望靠变量传递配置；要用 option()、cache 变量，或通过 configure_file() 生成头文件来透出编译期常量。
