CMakeLists.txt不是写完就能跑的配置文件，而是需经cmake生成构建系统后再由make编译的声明式逻辑；新手最常卡在路径、变量作用域和目标依赖关系三处，且cmake_minimum_required与project必须置于开头作为硬性启动条件。
直接说结论： CMakeLists.txt 不是“写完就能跑”的配置文件，它是一套声明式构建逻辑，必须配合 cmake 命令生成构建系统（如 Makefile），再由 make（或 ninja）真正编译。新手最常卡在路径、变量作用域和目标依赖关系这三处。
cmake_minimum_required 和 project 为什么必须放在最前面？
这两条不是可选装饰，而是 CMake 解析器的硬性启动条件。一旦顺序错位（比如把 add_executable 写在 project 前），CMake 会报错：CMake Error: PROJECT not set 或更模糊的 Unknown CMake command "add_executable"。
-
cmake_minimum_required(VERSION 3.10)告诉 CMake：“别用低于 3.10 的规则解析我”，避免因语法变更导致意外失败 -
project(myapp VERSION 1.0 LANGUAGES CXX)不仅设项目名，还隐式定义了${PROJECT_SOURCE_DIR}、${CMAKE_CXX_STANDARD}等关键变量——后续所有路径、标准、宏都依赖它 - 省略
LANGUAGES可能导致 C++ 文件被当 C 编译，引发std::string找不到等错误
add_executable 要求源文件路径必须显式列出或用 aux_source_directory？
不是必须用 aux_source_directory，而且它容易埋坑。CMake 默认不递归扫描子目录，也不自动识别新增文件。
CMake 4.3.2
下载
CMake 4.3.2 Windows x86_64 历史版本安装包，适合旧项目兼容、构建环境回退、CMakeLists.txt 迁移验证、Visual Studio/Ninja/Makefile 生成器测试和 C/C++ 项目维护。
-
add_executable(myapp main.cpp utils.cpp)—— 最安全：路径明确、顺序可控、IDE 可索引 -
aux_source_directory(${PROJECT_SOURCE_DIR} SRC_FILES)—— 仅适合扁平目录；若子目录有 .cpp，它不会进去找；且文件增删后，CMake cache 不自动更新，需手动cmake -P cmake_clean.cmake或删 build 目录 - 常见错误：
add_executable(myapp *.cpp)在 shell 层面展开，CMake 里是字面量，结果报错file *.cpp does not exist
include_directories 和 target_include_directories 有什么区别？
前者是全局作用域，后者绑定到具体目标（executable / library），推荐无脑用后者。
-
include_directories(${PROJECT_SOURCE_DIR}/include)让所有后续add_executable和add_library都能 include 这个路径——但若你有多个目标，其中某个不该访问该头文件，就失控了 -
target_include_directories(myapp PRIVATE ${PROJECT_SOURCE_DIR}/include)明确限定作用域：PRIVATE表示只供 myapp 自己用，不传递给依赖它的目标；换成PUBLIC才会透出 - 新手常误写成
target_include_directories(myapp ${PROJECT_SOURCE_DIR}/include)，漏掉PRIVATE关键字，CMake 会静默忽略，编译时才报fatal error: xxx.h: No such file or directory
为什么 build 目录不能和源码混在一起？
不是“不能”，而是 CMake 设计上默认污染源码树，而现代工程实践要求隔离。混放会导致 Git 脏、IDE 索引混乱、多构建配置冲突。
-
mkdir build && cd build && cmake ..是标准流程；cmake ..中的..指向含CMakeLists.txt的源码根目录 - 如果误在源码目录下直接运行
cmake .，CMake 会在源码目录生成CMakeCache.txt、CMakeFiles/等数十个文件，Git status 一眼望不到底 - 更隐蔽的问题：不同构建类型（Debug/Release）共用一个 cache，改
CMAKE_BUILD_TYPE后不清理 build 目录，旧编译选项可能残留
真正麻烦的从来不是语法本身，而是 CMake 的缓存机制和变量作用域——改了 CMakeLists.txt 却没清 cache，或者以为 set() 全局有效结果只在当前 scope 生效，这类问题比拼写错误更难定位。
