cmake_minimum_required必须位于CMakeLists.txt第一行，project紧随其后且必须在add_executable等命令之前；二者共同构成CMake解析起点，缺失或错序将导致策略冲突、目标注册失败或头文件路径失效。
cmake_minimum_required 和 project 必须放在最前面
这两个命令不是可选装饰，而是 CMake 解析的起点。如果 cmake_minimum_required 不在第一行，CMake 可能启用旧策略行为（比如对 target_include_directories 的处理不一致），导致依赖头文件时找不到符号；project 晚于其他命令（如 add_executable）会直接报错：Cannot add target "xxx" before project() is set。
常见错误现象：
- 执行
cmake ..报错：Parse error in CMakeLists.txt: cannot parse file（实际是策略冲突，但错误提示模糊） - 头文件路径生效但编译仍报
fatal error: xxx.hpp: No such file or directory，尤其在跨平台生成 Ninja/Visual Studio 时更易复现
正确写法示例：
cmake_minimum_required(VERSION 3.18) project(MyApp VERSION 1.2.0 LANGUAGES CXX)
注意：LANGUAGES CXX 显式声明语言比默认更安全——它禁用 C 编译器自动探测，避免某些嵌入式工具链误启 C 标准库链接。
add_executable / add_library 后必须用 target_* 系列命令配置目标
add_executable 和 add_library 只注册目标名和源文件，不自动设置头文件路径、宏定义或链接关系。直接写 add_executable(main main.cpp) 而不调用 target_include_directories 或 target_link_libraries，会导致编译失败或运行时符号缺失。
关键区别：
-
include_directories是全局作用域，影响所有后续目标，容易污染；target_include_directories作用于单个目标，支持PRIVATE/INTERFACE/PUBLIC作用域控制 -
add_definitions已被标记为 legacy，应改用target_compile_definitions，否则宏可能漏传给依赖它的下游目标 -
target_link_libraries必须在add_executable之后调用，且顺序影响链接器解析（例如main链接mylib，但mylib未定义时不会提前报错）
典型片段：
add_library(mylib STATIC mylib.cpp)
target_include_directories(mylib PUBLIC $<INSTALL_INTERFACE:include>)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE mylib)
target_compile_definitions(main PRIVATE APP_VERSION=\"${PROJECT_VERSION}\")install 和 CPack 打包前必须确认 INSTALL_INTERFACE 和 DESTINATION 一致性
install(TARGETS ... DESTINATION ...) 中的 DESTINATION 是相对于 CMAKE_INSTALL_PREFIX 的路径（默认 /usr/local），而 target_include_directories(... PUBLIC $<INSTALL_INTERFACE:include>) 中的 include 必须与实际安装后的头文件路径匹配。否则 find_package 或第三方项目引用你打包的库时会找不到头文件。
容易踩的坑：
- 写成
$<INSTALL_INTERFACE:inc>但install(DIRECTORY include/ DESTINATION include)—— 路径不一致，find_package失败 - 用
CPACK_GENERATOR "ZIP"但没设CPACK_PACKAGE_NAME，解压后目录名变成默认的MyProject-1.2.0-Linux，破坏预期结构 - 忘记
include(GNUInstallDirs)，直接硬编码DESTINATION bin，在 macOS 上可能装到/usr/local/bin而非/usr/local/bin（虽然一样，但不符合 FHS 规范）
推荐写法：
include(GNUInstallDirs)
install(TARGETS mylib
EXPORT MyLibTargets
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)
install(EXPORT MyLibTargets
FILE MyLibConfig.cmake
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyLib
)file(GLOB ...) 不适合生产环境，改用显式列表或 FetchContent
file(GLOB_RECURSE SOURCES CONFIGURE_DEPENDS src/*.cpp) 看起来省事，但 CMake 不会自动检测新增或删除的源文件——除非手动删掉 CMakeCache.txt 或 build/ 目录重来。CI 构建中极易漏编译新文件，调试时也难定位问题源头。
替代方案：
- 小项目：手写
set(SOURCES src/main.cpp src/utils.cpp)，清晰可控 - 中大型项目：用
FetchContent管理子模块或第三方依赖，比add_subdirectory更隔离 - 必须动态扫描时：仅限原型阶段，且加注释说明风险，例如
# WARNING: GLOB only for dev, not CI
真正可靠的自动化方式是结合 configure_file + list(APPEND ...) 动态生成源列表，但代价是复杂度上升——多数团队宁愿多敲几行 add_executable 参数。
