多目录CMake项目应让根目录CMakeLists.txt仅作入口路由表，只执行cmake_minimum_required、project和add_subdirectory；所有构建逻辑下沉至各子目录CMakeLists.txt，确保目标自包含、头路径作用域正确、跨目录链接显式声明，并坚持外置build目录。
直接用 add_subdirectory()，别在根目录写一堆 add_executable() 或 add_library() —— 这是多目录项目崩得最频繁的根源。
根目录 CMakeLists.txt 只干三件事
它不是“总调度中心”，而是“入口路由表”。所有构建逻辑必须下沉到子目录，否则很快会失控。
-
cmake_minimum_required(VERSION 3.15)—— 版本太低（比如2.8）会导致PUBLIC/INTERFACE作用域失效，链接失败时查不出原因 -
project(MyApp LANGUAGES CXX)—— 必须显式声明语言，否则某些平台（如 macOS + Clang）可能默认禁用 C++17 特性 -
add_subdirectory(src)、add_subdirectory(third_party)、add_subdirectory(tests)—— 路径必须存在且含有效的CMakeLists.txt，顺序无关，但依赖关系要靠后续target_link_libraries()显式表达
子目录 CMakeLists.txt 必须自包含
每个子目录的 CMakeLists.txt 要能独立定义目标、头路径和依赖，不能指望父目录“帮它补全”。常见错误是子目录里用了未定义的 target_link_libraries(mylib PRIVATE other_target)，而 other_target 其实还没被声明或没被父目录引入。
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 用
add_library(mycore STATIC)或add_executable(cli)定义目标，源文件路径用相对当前子目录的写法（如Logger.cpp），别写../src/Logger.cpp - 头文件路径用
target_include_directories(mycore PUBLIC $<INSTALL_INTERFACE:include>)，PUBLIC表示该路径既供自己用，也传递给链接它的目标；PRIVATE则只内部用 - 跨目录链接必须显式写
target_link_libraries(cli PRIVATE mycore)，CMake 不会自动推导依赖链
常见错误：include could not find load file 和 undefined reference
这两个报错几乎都指向同一个问题：目标没注册进构建系统，或注册了但没被正确链接。
-
include could not find load file: XXXConfig.cmake—— 本质是子目录提前执行了find_package(XXX)，但XXX对应的 target 还没通过add_subdirectory()注册进来。解决方法：把find_package()移到依赖它的子目录里，或确保add_subdirectory(xxx)在所有用到它的指令之前 -
undefined reference to 'xxx::func()'—— 大概率是target_link_libraries(app PRIVATE xxx)漏写了，或者写了但xxx是个INTERFACE库却没提供实现；也可能是子目录用了add_library(xxx INTERFACE)却忘了用target_sources(xxx INTERFACE ...)声明头文件
build 目录必须外置，且不放任何源码
每次 mkdir build && cd build && cmake .. 是铁律。把 build 放进源码树里，或在源码目录下直接 cmake .，会导致生成的 CMakeCache.txt、compile_commands.json 污染 git 状态，更严重的是：不同配置（Debug/Release）的中间文件混在一起，CMake 会误判依赖并跳过重编译。
- 推荐命令流：
mkdir -p build && cd build && cmake -DCMAKE_BUILD_TYPE=Debug .. && make -j4 - 如果用了
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)，生成的compile_commands.json会放在build/下，VS Code 或 clangd 才能准确定位头文件和符号 -
build目录里绝对不要手动改任何文件——CMake 生成的东西，只靠重跑cmake更新
真正容易被忽略的点是：子目录的 target_include_directories() 作用域一旦设错（比如该用 PUBLIC 却写了 PRIVATE），下游目标就找不到头文件，但编译器报错位置往往在调用处而非声明处，排查路径会绕远。
