新项目起步，cmake_minimum_required(VERSION 3.10) 是安全下限，但推荐写 3.17 或 3.20；低于 3.10 的版本已淘汰，缺失 target_compile_features 等关键特性，且主流系统默认不再提供。
cmake_minimum_required 版本选 3.10 还是更高？
直接说结论：新项目起步，cmake_minimum_required(VERSION 3.10) 是安全下限，但推荐写 3.17 或 3.20。低于 3.10 的版本（如 2.8/3.5）已淘汰，语法陈旧、缺失关键特性（比如 target_compile_features、现代依赖传递方式），且主流发行版默认不再提供。
常见错误现象：Unknown CMake command "target_link_libraries" 或 target_include_directories not found——本质是用了现代写法但 CMake 版本太低；或者反过来，用 include_directories() 全局污染，导致多 target 时头文件路径混乱。
- Ubuntu 22.04+/CentOS 9+/macOS Homebrew 默认装的是 3.22+，无需降级
- 若团队或 CI 必须兼容旧环境（如 CentOS 7），最低可退到
3.12，但需手动规避generator expressions在条件判断中的高级用法 -
project()中显式声明LANGUAGES CXX比隐式更可靠，避免 CMake 自动探测失败
add_executable 里该写相对路径还是绝对路径？
必须写相对路径，且以 CMAKE_CURRENT_SOURCE_DIR 为基准。CMake 不接受 /home/user/project/src/main.cpp 这类绝对路径——它会报错 file path is absolute，或静默忽略导致链接失败。
典型使用场景：多级目录结构下，子目录的 CMakeLists.txt 调用 add_executable 时，源文件路径相对于当前 CMakeLists.txt 所在目录，不是项目根目录。
- 正确写法：
add_executable(app src/main.cpp include/app.h)（当前CMakeLists.txt在src/目录下） - 错误写法：
add_executable(app ${CMAKE_SOURCE_DIR}/src/main.cpp)——虽然能跑，但破坏了子目录的独立性，add_subdirectory(src)会失效 - 大型项目中，建议用
set集中管理源文件列表，例如：set(APP_SOURCES main.cpp utils/log.cpp)，再传给add_executable
为什么 build 目录一定要和源码目录分开？
因为 CMake 设计哲学就是「out-of-source build」，混在一起会导致：git 脏、清理困难、多构建配置冲突（比如 debug/release 同时存在）、IDE 索引异常。这不是建议，是硬性约束。
容易踩的坑：cd /path/to/src && cmake . ——这会把所有中间文件（CMakeCache.txt、Makefile、对象文件）全塞进源码树，下次 git status 一堆红色，git clean -fdx 可能误删源码。
- 标准做法：建
build目录，cd build && cmake ..；想同时保留多个配置，就建build-debug、build-release - 现代写法可一步到位：
cmake -S . -B build（-S指源码目录，-B指构建目录），CMake 3.13+ 支持，比传统两步更健壮 - 某些 IDE（如 CLion）默认创建
cmake-build-debug，只要没手动改CMAKE_BINARY_DIR，就符合规范
第三方库找不到：find_package 和 target_link_libraries 怎么配对？
find_package(OpenCV REQUIRED) 成功后，不能直接 target_link_libraries(myapp opencv_core) ——这样链接的是系统全局库，不是 find_package 发现的那个。正确链法是 target_link_libraries(myapp ${OpenCV_LIBS}) 或更现代的 target_link_libraries(myapp OpenCV::opencv_core)。
根本原因：CMake 3.15+ 推广「imported target」模式，OpenCV::opencv_core 是一个逻辑目标，自带编译选项、头文件路径、依赖传递，而 ${OpenCV_LIBS} 只是字符串列表，不带元信息。
- 检查是否找到：运行
cmake ..后看输出是否有Found OpenCV:，没有就说明CMAKE_PREFIX_PATH没设对，或库没装 - 自定义库未提供
Config.cmake文件时，要用find_path+find_library手动拼，但务必用add_library(mylib IMPORTED)封装成 imported target，否则无法被target_link_libraries正确消费 -
REQUIRED不要乱加：有些库（如Threads）即使没写REQUIRED也能 fallback，加了反而让构建在无 pthread 环境中断
project() 前后、在 add_subdirectory() 内外、在不同 generator 下行为可能完全不同。最容易被忽略的是 CMAKE_CURRENT_SOURCE_DIR 和 CMAKE_SOURCE_DIR 的作用域差异，一不留神就让子模块的路径解析出错。 
