cmake_minimum_required 和 project 必须分别位于 CMakeLists.txt 第一行和第二行，顺序不可颠倒；前者指定最低 CMake 版本，后者定义项目名及语言，缺一不可。
cmake_minimum_required 和 project 必须放在最前面
几乎所有新手第一次写 CMakeLists.txt 都会卡在这一步：把 add_executable 写在最顶上，然后 cmake .. 报错说 “No cmake_minimum_required command is present”。CMake 要求第一行有效指令必须是 cmake_minimum_required，第二行通常是 project——这两条缺一不可，且顺序不能颠倒。
常见错误现象：
-
CMake Error: The source directory ".../hello" does not appear to contain CMakeLists.txt（其实是文件存在但语法不合法，CMake 直接跳过） -
CMake Error at CMakeLists.txt:1 (project): project command is not script mode compatible（版本太低或cmake_minimum_required缺失）
正确写法示例：
cmake_minimum_required(VERSION 3.10) project(hello LANGUAGES CXX) add_executable(hello src/main.cpp)
注意点：
-
VERSION 3.10是当前最稳妥的下限，低于它会导致LANGUAGES CXX不被识别 -
project的LANGUAGES CXX参数显式启用 C++ 支持，避免某些平台默认只开 C - 项目名
hello会自动定义变量PROJECT_NAME，后续可复用
源文件路径必须相对 CMakeLists.txt 所在目录
很多人把 main.cpp 放在 src/ 目录下，却在 CMakeLists.txt 里写 add_executable(hello main.cpp)，结果构建时报错 “file …/main.cpp does not exist”。CMake 中所有路径都是相对于 CMakeLists.txt 的位置解析的，不是相对于命令执行路径，也不是相对于构建目录。
典型结构和写法：
hello/ ├── CMakeLists.txt ← 这里是根 ├── src/ │ └── main.cpp ← 所以路径要写成 src/main.cpp
正确写法：
add_executable(hello src/main.cpp)
容易踩的坑：
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 误用绝对路径（
/home/user/src/main.cpp）——跨机器失效，且 CMake 会警告 - 用
./src/main.cpp——点号多余，CMake 不需要也不推荐 - 把
CMakeLists.txt放错位置（比如放在src/下）——导致project指令无法管理整个项目
构建目录必须与源码目录分离
直接在项目根目录下运行 cmake . 是危险操作。CMake 生成的中间文件（如 CMakeCache.txt、Makefile、编译器对象文件）会污染源码树，git 提交时容易误提交，清理也麻烦。官方推荐且绝大多数现代项目都采用 out-of-source 构建。
标准流程：
mkdir build && cd build-
cmake -S .. -B .（等价于旧写法cmake ..，但更明确） cmake --build .
关键说明：
-
-S ..表示源码在上级目录；-B .表示构建产物全放在当前build/目录 - 不要用
cmake .，它会让 CMake 在当前目录找CMakeLists.txt，而你很可能不在根目录 - Windows 用户如果用 Visual Studio 生成器，加
-G "Visual Studio 17 2022"即可，无需改路径逻辑
add_executable 之后没加头文件搜索路径会编译失败
当你引入 utils.h 并在 main.cpp 中 #include "utils.h"，而 utils.h 放在 include/ 目录下，cmake --build 会报错：fatal error: utils.h: No such file or directory。这是因为 C++ 编译器默认只查系统路径和当前源文件所在目录，不会自动递归扫描项目其他目录。
解决方法是用 target_include_directories 显式声明：
add_executable(hello src/main.cpp src/utils.cpp) target_include_directories(hello PRIVATE include)
注意参数含义：
-
PRIVATE表示该头文件路径只对hello自身有效，不传递给依赖它的其他 target - 路径
include是相对于CMakeLists.txt的，不是相对于src/ - 如果头文件在
src/下，写target_include_directories(hello PRIVATE src)即可
漏掉这步是多文件项目中最常被忽略的编译失败原因，尤其从单文件扩展过来时。
真正容易被忽略的不是语法，而是路径语义：CMake 的路径全是相对于 CMakeLists.txt，而编译器的 #include 路径又受 target_include_directories 控制——这两层“相对”必须对齐，否则就找不到头文件。
