C++项目用CMake构建核心就三步：写对CMakeLists.txt、隔离构建目录、用cmake --build编译；最简配置仅三行——cmake_minimum_required(VERSION 3.10)、project(MyApp LANGUAGES CXX)、add_executable(MyApp src/main.cpp)，须严格匹配路径、显式声明语言、禁止源码目录内构建。
直接说结论：C++项目用 CMake 构建，核心就三步——写对 CMakeLists.txt、隔离构建目录、用 cmake --build 编译。不是“先学语法再动手”，而是从一个能跑的最小配置开始，边改边理解。
怎么写第一个能跑的 CMakeLists.txt
别一上来就抄几十行模板。最简可用的配置只有三行，放在项目根目录：
cmake_minimum_required(VERSION 3.10) project(MyApp LANGUAGES CXX) add_executable(MyApp src/main.cpp)
注意几个关键点：
-
cmake_minimum_required必须写，且版本别乱填低了——3.10是目前安全下限，低于它很多现代特性（比如target_compile_features）会不可用 -
project的LANGUAGES CXX显式声明只用 C++，避免 CMake 自动启用 C 编译器导致奇怪警告 -
add_executable的名字（MyApp）就是最终生成的可执行文件名，和源文件路径无关；路径必须写全，比如src/main.cpp，不能只写main.cpp（除非它就在同级） - 如果源文件不止一个，直接追加：
add_executable(MyApp src/main.cpp src/utils.cpp src/logger.cpp)
为什么一定要用独立的 build 目录
常见错误是直接在源码根目录运行 cmake .，结果满屏 CMakeCache.txt 和 CMakeFiles/ 污染源码树。这会导致：
立即学习“C++免费学习笔记（深入）”；
- Git 提交时误提交构建缓存，别人拉下来直接
cmake失败 - 切换
Debug/Release需要清缓存，rm -rf *容易误删源码 - IDE（如 CLion、VS Code）索引混乱，头文件跳转失效
正确做法是新建目录并指定源码位置：
mkdir build cd build cmake -S .. -B . -DCMAKE_BUILD_TYPE=Debug
其中 -S .. 指向源码根目录，-B . 表示当前目录为构建目录，-DCMAKE_BUILD_TYPE 控制编译类型——不传默认是 Debug，但显式写出来更可靠。
target_include_directories 和头文件路径怎么设
很多人卡在 fatal error: utils.h: No such file or directory，问题不在头文件没放对，而在 CMake 没告诉编译器去哪找。假设你的头文件在 include/ 目录下，别用全局 include_directories()（已过时），改用 target 级别命令：
add_executable(MyApp src/main.cpp src/utils.cpp) target_include_directories(MyApp PRIVATE include)
这里的关键是作用域修饰符：
-
PRIVATE：只对MyApp自己生效，下游 target 不继承——适合仅内部使用的头文件 -
PUBLIC：自己用 + 下游也自动获得该路径——适合库项目导出头文件时用 -
INTERFACE：自己不用，只提供给下游——比如一个纯头文件库（add_library(myheader INTERFACE)）
漏写修饰符或错用（比如该用 PUBLIC 却写了 PRIVATE）会导致下游链接时找不到头文件，尤其是多模块项目里跨目录引用时。
常见报错：undefined reference to `xxx` 怎么快速定位
这个错误几乎都发生在引入新源文件或第三方库之后，本质是链接阶段找不到符号定义。排查顺序很固定：
- 确认
.cpp文件是否真的加进了add_executable或add_library的参数列表里（不是只改了#include就完事） - 如果是自己写的库（比如
add_library(mylib STATIC src/utils.cpp)），必须显式链接：target_link_libraries(MyApp PRIVATE mylib)；光有add_subdirectory(lib)不等于自动链接 - 调用系统库（如
pthread）时，别写target_link_libraries(MyApp PRIVATE -lpthread)—— 这是 Unix 风格，Windows 上会崩；应统一用find_package(Threads REQUIRED)再target_link_libraries(MyApp PRIVATE Threads::Threads) - 检查函数声明和定义是否匹配：头文件里是
void foo();，实现文件里写成int foo() { return 0; }也会报这个错
最容易被忽略的是：CMake 不会自动扫描目录递归添加 .cpp 文件。你删了一个源文件，忘了从 add_executable 列表里去掉，它就真不会编译——但错误信息还是 undefined reference，容易误导人往链接方向猛查。
