CMake 常见陷阱与规避要点概述CMake 工程在规模变大、引入子目录与第三方依赖后容易出现「换环境失败」「链接缺符号」「找错头文件或库版本」等问题。多数来自变量与缓存、目标传播属性、路径与策略等规则使用不当。本文用示意表、流程图与正反代码汇总常见陷阱及规避方式便于自查与 Code Review。目录问题域总览1. 子目录 option 与父级 setCMP00772. add_subdirectory 与目标可见顺序3. target 命令作用域与第三方目标4. 普通变量与缓存变量混用5. 源码目录变量用错6. C 标准未贯通到各目标7. PUBLIC / PRIVATE / INTERFACE 误用8. file(GLOB) 与源文件列表9. 安装与 RPATH10. find_package 与路径11. cmake_minimum_required 与旧策略12. if() 对变量的判断13. 生成器表达式上下文速查总表参考资料免责声明问题域总览下面用一张分类示意把后文条目串起来非严格UML仅帮助建立心智模型┌─────────────────────────────────────┐ │ CMake 配置 / 生成 │ └─────────────────────────────────────┘ │ ┌───────────────┬─────────────────┼─────────────────┬───────────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │变量/缓存 │ │目标与依赖顺序 │ │传播属性 │ │路径与查找 │ │策略与语法 │ │§1 §4 §12 │ │§2 §3 §8 │ │§6 §7 │ │§5 §9 §10 │ │§11 §13 │ └──────────┘ └──────────────┘ └────────────┘ └────────────┘ └────────────┘问题域本文章节典型症状变量与缓存1、4、12开关改了不生效、option 盖掉 set、if 判断反常目标与顺序2、3、8目标不存在、第三方改不动、新增源文件不参与编译传播与标准6、7缺头文件、C 标准不一致路径与安装5、9、10include 指错、装完找不到 .so、链到错误版本库策略与表达式11、13与新版文档行为不一致、生成器表达式报错1. 子目录 option 与父级 setCMP00771.1 机制示意CMP0077 OLD顶层 CMakeLists.txt 子目录 CMakeLists.txt ┌──────────────────┐ ┌─────────────────────┐ │ set(ENABLE_X ON) │ ──────► │ 当前作用域 ENABLE_XON │ └────────┬─────────┘ └──────────┬──────────┘ │ add_subdirectory │ └────────────────────────────►│ option(ENABLE_X ... OFF) │ (OLD: 覆盖为 OFF) ▼ if(ENABLE_X) 为假 → 源文件未加入 → 链接缺符号1.2 策略对照表CMP0077子目录执行option(同名 …)时OLD可能清除/覆盖已存在的普通变量父级set(ON)失效NEW若普通变量已存在option()不修改1.3 代码示例易出问题写法子目录option(ENABLE_FEATURE Optional module OFF) if(ENABLE_FEATURE) target_sources(mylib PRIVATE optional.cc) endif()推荐写法 A子目录条件化 optionif(NOT DEFINED ENABLE_FEATURE) option(ENABLE_FEATURE Optional module OFF) endif() if(ENABLE_FEATURE) target_sources(mylib PRIVATE optional.cc) endif()推荐写法 B顶层CMake ≥ 3.13cmake_policy(SET CMP0077 NEW) add_subdirectory(third_party/mylib)2. add_subdirectory 与目标可见顺序2.1 依赖顺序示意错误顺序使用者先于被依赖者进入配置。add_subdirectory(app) # 内部 target_link_libraries(app PRIVATE core_lib) add_subdirectory(core) # 此处才 add_library(core_lib …) │ ▼ 配置失败Cannot specify link libraries for target app which is not built by this project. 或找不到目标 core_lib取决于写法推荐顺序add_subdirectory(core) # 先定义 core_lib add_subdirectory(app) # 再链接2.2 最小示例# 推荐 add_subdirectory(src/core) add_subdirectory(src/app) # app/CMakeLists.txt add_executable(app main.cc) target_link_libraries(app PRIVATE core_lib)3. target 命令作用域与第三方目标3.1 思路用 INTERFACE 库「包一层」第三方Foo::foo往往不应直接target_include_directories(Foo::foo …)。可封装为本地接口目标find_package(Foo REQUIRED CONFIG) add_library(foo_with_flags INTERFACE) target_link_libraries(foo_with_flags INTERFACE Foo::foo) target_include_directories(foo_with_flags INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/extra_wrappers) add_executable(app main.cc) target_link_libraries(app PRIVATE foo_with_flags)3.2 做法对照做法说明直接改 IMPORTED 目标属性常被 CMake 拒绝或升级第三方即失效INTERFACE包装只增不减适合追加 include、宏、额外依赖供应商文档推荐变量如Foo_DIR、-DCMAKE_PREFIX_PATH优先遵循4. 普通变量与缓存变量混用4.1 变量优先级示意CMakeCache.txt 中的 CACHE 项 │ │ 同名时option() / set(... CACHE) 参与「缓存」命名空间 ▼ 配置阶段读取顺序缓存变量与普通变量规则不同 │ ▼ 仅写 set(MYVAR ON) 往往改不动已存在的 CACHE{MYVAR}4.2 代码示例# 首次配置后 CMakeCache.txt 已有 BUILD_TESTSOFF # 此后在 CMakeLists 里写 set(BUILD_TESTS ON) # 通常无法改变缓存中的 BUILD_TESTS # 排查删除构建目录或命令行 # cmake -UBUILD_TESTS .. # 或显式写缓存慎用会进 ccmake set(BUILD_TESTS ON CACHE BOOL Build tests FORCE)4.3 建议用途建议用户可调选项option()或set(... CACHE BOOL ...)仅脚本内部传递普通变量名避免与 option 缓存同名CI 固定开关-DBUILD_TESTSON或干净构建目录5. 源码目录变量用错5.1 常用路径变量对照表变量含义典型误用CMAKE_SOURCE_DIR顶层源码根子项目里当「本项目根」PROJECT_SOURCE_DIR当前 project()对应源码根多 project 时需注意层级CMAKE_CURRENT_SOURCE_DIR当前 CMakeLists.txt所在目录最稳妥的「本目录」CMAKE_CURRENT_LIST_DIR当前列表文件目录含 fn 路径与上者多数情况一致5.2 示例# 子目录 libs/parser/CMakeLists.txt —— 应用当前目录或本项目根 target_include_directories(parser PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include) # 错误示例在子模块里写 # include_directories(${CMAKE_SOURCE_DIR}/include) # 可能指向顶层仓库的 include而非子模块自身6. C 标准未贯通到各目标6.1 全局 vs 每目标方式优点缺点set(CMAKE_CXX_STANDARD 17)全局写法简单部分OBJECT/INTERFACE目标或未继承target_compile_features(… cxx_std_17)明确、可审计需对每个目标写或使用函数封装6.2 推荐示例add_library(util STATIC util.cc) target_compile_features(util PUBLIC cxx_std_17) add_executable(app main.cc) target_link_libraries(app PRIVATE util) # 若 util 的 PUBLIC 接口头用了 C17app 也会带上相应标准通过使用要求传播7. PUBLIC / PRIVATE / INTERFACE 误用7.1 传播示意libA app ┌─────────────┐ ┌─────────┐ │ PUBLIC inc │────────►│ 编译 app │ 需要 A 的头文件 → 应用 PUBLIC │ PRIVATE inc│ ✗ │ 不应暴露 │ └─────────────┘ └─────────┘7.2 代码对比# 问题下游链接 mylib 时拿不到 API 头路径 target_include_directories(mylib PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include) # 修正对外 API 用 PUBLIC target_include_directories(mylib PUBLIC $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include $INSTALL_INTERFACE:include)关键字含义简述PRIVATE仅编译本目标INTERFACE仅影响依赖方常用于头文件库PUBLIC本目标 依赖方8. file(GLOB) 与源文件列表8.1 配置期 vs 构建期时间轴 ─────────────────────────────────────────► │ cmake 配置 │ ninja/make 编译 │ file(GLOB) 在此执行 │ │ 列表固定 │ 新增 .cc 不会触发重新 GLOB8.2 示例# 不推荐新增文件易遗漏除非每次重跑 cmake file(GLOB SRCS *.cc) # 折中目录变化时触发重新配置CMake 3.12 file(GLOB SRCS CONFIGURE_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/*.cc) add_library(box STATIC ${SRCS}) # 稳妥显式列表大型项目常用 set(SRCS box.cc io.cc) add_library(box STATIC ${SRCS})9. 安装与 RPATH9.1 运行时找库示意Linux安装前缀 /opt/myapp/ bin/app ──► 需找到 ../lib/libfoo.so lib/libfoo.so9.2 示例set(CMAKE_INSTALL_RPATH $ORIGIN/../lib) set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) # 或安装后针对目标 set_target_properties(app PROPERTIES INSTALL_RPATH $ORIGIN/../lib)场景思路同前缀可移植包$ORIGIN相对 RPATH系统包装入标准lib靠 ldconfig开发构建构建树 RPATH 通常已可用10. find_package 与路径10.1 搜索示意find_package(ZLIB CONFIG) │ ├─► CMAKE_PREFIX_PATH 中的 ZlibConfig.cmake ├─► CMAKE_MODULE_PATH 中的 FindZLIB.cmakeMODULE 模式 └─► 系统路径顺序影响「先到先用」10.2 示例list(APPEND CMAKE_PREFIX_PATH /opt/mydeps/zlib-build) find_package(ZLIB REQUIRED CONFIG) # 命令行等价 # cmake -DCMAKE_PREFIX_PATH/opt/mydeps/zlib-build ..11. cmake_minimum_required 与旧策略11.1 关系示意cmake_minimum_required(VERSION 3.16) │ ▼ 隐式将大量 Policy 设为 ≤3.16 时的默认多为 OLD 或 NEW因版本而异 │ ▼ 需要新语义时提升版本或 cmake_policy(SET CMPxxxx NEW)11.2 示例策略节选策略主题简述CMP0077option()与已有普通变量CMP0048project()无 VERSION 时警告CMP0167FetchContent_Populate等行为cmake_minimum_required(VERSION 3.20) # 或在不抬最低版本时单独开启 if(POLICY CMP0077) cmake_policy(SET CMP0077 NEW) endif()12. if() 对变量的判断12.1 未加引号时部分取值简表if(FOO)中 FOO 取值常表现为假0、OFF、FALSE、IGNORE、NOTFOUND、以-NOTFOUND结尾是空字符串是其他非空字符串多为真注意非 0/1 字符串12.2 稳妥写法示例if(DEFINED ENABLE_X AND ENABLE_X STREQUAL ON) # ... endif() # 或布尔语义 if(ENABLE_X) endif() # 需保证 ENABLE_X 仅为 ON/OFF 或 1/013. 生成器表达式上下文13.1 求值时机配置期configure 生成期generate │ │ │ 多数 $ 在此尚不可求值 │ ▼ ▼ add_subdirectory 顺序 写入 build.ninja / VS 工程时展开13.2 合法使用示例target_compile_definitions(app PRIVATE $$CONFIG:Debug:DEBUG_BUILD1) target_include_directories(app PRIVATE $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/inc)常见错误在message()或顶层字符串拼接中滥用$TARGET_FILE:…期望配置期得到路径——多数应在install(CODE)或add_custom_command等支持生成器表达式的上下文中使用。速查总表#陷阱一句话规避1option 盖掉父 setif(NOT DEFINED …) option …或 CMP0077 NEW2目标未定义就 link先add_subdirectory/定义库再链接3乱改第三方目标INTERFACE包装4改 CMakeLists 不生效查缓存同名-U或删 build5include 指错用CURRENT_SOURCE_DIR/PROJECT_SOURCE_DIR6标准不一致target_compile_features7下游缺头文件API 用PUBLICBUILD_INTERFACE8GLOB 漏新文件显式列表或CONFIGURE_DEPENDS9安装后缺 .soINSTALL_RPATH$ORIGIN10找错包版本CMAKE_PREFIX_PATH CONFIG 模式11旧策略行为提升minimum_required或cmake_policy12if 误判DEFINED/STREQUAL13生成器表达式报错仅用于支持的属性与命令参考资料CMake 官方文档CMake Policiescmake commands (option, target_*)Modern CMake社区英文免责声明本文基于常见工程经验整理示意图仅表达逻辑关系。CMake 行为随版本变化请以当前所用版本的官方文档为准。
CMake 常见陷阱与规避要点
发布时间：2026/7/6 9:45:13
CMake 常见陷阱与规避要点概述CMake 工程在规模变大、引入子目录与第三方依赖后容易出现「换环境失败」「链接缺符号」「找错头文件或库版本」等问题。多数来自变量与缓存、目标传播属性、路径与策略等规则使用不当。本文用示意表、流程图与正反代码汇总常见陷阱及规避方式便于自查与 Code Review。目录问题域总览1. 子目录 option 与父级 setCMP00772. add_subdirectory 与目标可见顺序3. target 命令作用域与第三方目标4. 普通变量与缓存变量混用5. 源码目录变量用错6. C 标准未贯通到各目标7. PUBLIC / PRIVATE / INTERFACE 误用8. file(GLOB) 与源文件列表9. 安装与 RPATH10. find_package 与路径11. cmake_minimum_required 与旧策略12. if() 对变量的判断13. 生成器表达式上下文速查总表参考资料免责声明问题域总览下面用一张分类示意把后文条目串起来非严格UML仅帮助建立心智模型┌─────────────────────────────────────┐ │ CMake 配置 / 生成 │ └─────────────────────────────────────┘ │ ┌───────────────┬─────────────────┼─────────────────┬───────────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │变量/缓存 │ │目标与依赖顺序 │ │传播属性 │ │路径与查找 │ │策略与语法 │ │§1 §4 §12 │ │§2 §3 §8 │ │§6 §7 │ │§5 §9 §10 │ │§11 §13 │ └──────────┘ └──────────────┘ └────────────┘ └────────────┘ └────────────┘问题域本文章节典型症状变量与缓存1、4、12开关改了不生效、option 盖掉 set、if 判断反常目标与顺序2、3、8目标不存在、第三方改不动、新增源文件不参与编译传播与标准6、7缺头文件、C 标准不一致路径与安装5、9、10include 指错、装完找不到 .so、链到错误版本库策略与表达式11、13与新版文档行为不一致、生成器表达式报错1. 子目录 option 与父级 setCMP00771.1 机制示意CMP0077 OLD顶层 CMakeLists.txt 子目录 CMakeLists.txt ┌──────────────────┐ ┌─────────────────────┐ │ set(ENABLE_X ON) │ ──────► │ 当前作用域 ENABLE_XON │ └────────┬─────────┘ └──────────┬──────────┘ │ add_subdirectory │ └────────────────────────────►│ option(ENABLE_X ... OFF) │ (OLD: 覆盖为 OFF) ▼ if(ENABLE_X) 为假 → 源文件未加入 → 链接缺符号1.2 策略对照表CMP0077子目录执行option(同名 …)时OLD可能清除/覆盖已存在的普通变量父级set(ON)失效NEW若普通变量已存在option()不修改1.3 代码示例易出问题写法子目录option(ENABLE_FEATURE Optional module OFF) if(ENABLE_FEATURE) target_sources(mylib PRIVATE optional.cc) endif()推荐写法 A子目录条件化 optionif(NOT DEFINED ENABLE_FEATURE) option(ENABLE_FEATURE Optional module OFF) endif() if(ENABLE_FEATURE) target_sources(mylib PRIVATE optional.cc) endif()推荐写法 B顶层CMake ≥ 3.13cmake_policy(SET CMP0077 NEW) add_subdirectory(third_party/mylib)2. add_subdirectory 与目标可见顺序2.1 依赖顺序示意错误顺序使用者先于被依赖者进入配置。add_subdirectory(app) # 内部 target_link_libraries(app PRIVATE core_lib) add_subdirectory(core) # 此处才 add_library(core_lib …) │ ▼ 配置失败Cannot specify link libraries for target app which is not built by this project. 或找不到目标 core_lib取决于写法推荐顺序add_subdirectory(core) # 先定义 core_lib add_subdirectory(app) # 再链接2.2 最小示例# 推荐 add_subdirectory(src/core) add_subdirectory(src/app) # app/CMakeLists.txt add_executable(app main.cc) target_link_libraries(app PRIVATE core_lib)3. target 命令作用域与第三方目标3.1 思路用 INTERFACE 库「包一层」第三方Foo::foo往往不应直接target_include_directories(Foo::foo …)。可封装为本地接口目标find_package(Foo REQUIRED CONFIG) add_library(foo_with_flags INTERFACE) target_link_libraries(foo_with_flags INTERFACE Foo::foo) target_include_directories(foo_with_flags INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/extra_wrappers) add_executable(app main.cc) target_link_libraries(app PRIVATE foo_with_flags)3.2 做法对照做法说明直接改 IMPORTED 目标属性常被 CMake 拒绝或升级第三方即失效INTERFACE包装只增不减适合追加 include、宏、额外依赖供应商文档推荐变量如Foo_DIR、-DCMAKE_PREFIX_PATH优先遵循4. 普通变量与缓存变量混用4.1 变量优先级示意CMakeCache.txt 中的 CACHE 项 │ │ 同名时option() / set(... CACHE) 参与「缓存」命名空间 ▼ 配置阶段读取顺序缓存变量与普通变量规则不同 │ ▼ 仅写 set(MYVAR ON) 往往改不动已存在的 CACHE{MYVAR}4.2 代码示例# 首次配置后 CMakeCache.txt 已有 BUILD_TESTSOFF # 此后在 CMakeLists 里写 set(BUILD_TESTS ON) # 通常无法改变缓存中的 BUILD_TESTS # 排查删除构建目录或命令行 # cmake -UBUILD_TESTS .. # 或显式写缓存慎用会进 ccmake set(BUILD_TESTS ON CACHE BOOL Build tests FORCE)4.3 建议用途建议用户可调选项option()或set(... CACHE BOOL ...)仅脚本内部传递普通变量名避免与 option 缓存同名CI 固定开关-DBUILD_TESTSON或干净构建目录5. 源码目录变量用错5.1 常用路径变量对照表变量含义典型误用CMAKE_SOURCE_DIR顶层源码根子项目里当「本项目根」PROJECT_SOURCE_DIR当前 project()对应源码根多 project 时需注意层级CMAKE_CURRENT_SOURCE_DIR当前 CMakeLists.txt所在目录最稳妥的「本目录」CMAKE_CURRENT_LIST_DIR当前列表文件目录含 fn 路径与上者多数情况一致5.2 示例# 子目录 libs/parser/CMakeLists.txt —— 应用当前目录或本项目根 target_include_directories(parser PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include) # 错误示例在子模块里写 # include_directories(${CMAKE_SOURCE_DIR}/include) # 可能指向顶层仓库的 include而非子模块自身6. C 标准未贯通到各目标6.1 全局 vs 每目标方式优点缺点set(CMAKE_CXX_STANDARD 17)全局写法简单部分OBJECT/INTERFACE目标或未继承target_compile_features(… cxx_std_17)明确、可审计需对每个目标写或使用函数封装6.2 推荐示例add_library(util STATIC util.cc) target_compile_features(util PUBLIC cxx_std_17) add_executable(app main.cc) target_link_libraries(app PRIVATE util) # 若 util 的 PUBLIC 接口头用了 C17app 也会带上相应标准通过使用要求传播7. PUBLIC / PRIVATE / INTERFACE 误用7.1 传播示意libA app ┌─────────────┐ ┌─────────┐ │ PUBLIC inc │────────►│ 编译 app │ 需要 A 的头文件 → 应用 PUBLIC │ PRIVATE inc│ ✗ │ 不应暴露 │ └─────────────┘ └─────────┘7.2 代码对比# 问题下游链接 mylib 时拿不到 API 头路径 target_include_directories(mylib PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include) # 修正对外 API 用 PUBLIC target_include_directories(mylib PUBLIC $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include $INSTALL_INTERFACE:include)关键字含义简述PRIVATE仅编译本目标INTERFACE仅影响依赖方常用于头文件库PUBLIC本目标 依赖方8. file(GLOB) 与源文件列表8.1 配置期 vs 构建期时间轴 ─────────────────────────────────────────► │ cmake 配置 │ ninja/make 编译 │ file(GLOB) 在此执行 │ │ 列表固定 │ 新增 .cc 不会触发重新 GLOB8.2 示例# 不推荐新增文件易遗漏除非每次重跑 cmake file(GLOB SRCS *.cc) # 折中目录变化时触发重新配置CMake 3.12 file(GLOB SRCS CONFIGURE_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/*.cc) add_library(box STATIC ${SRCS}) # 稳妥显式列表大型项目常用 set(SRCS box.cc io.cc) add_library(box STATIC ${SRCS})9. 安装与 RPATH9.1 运行时找库示意Linux安装前缀 /opt/myapp/ bin/app ──► 需找到 ../lib/libfoo.so lib/libfoo.so9.2 示例set(CMAKE_INSTALL_RPATH $ORIGIN/../lib) set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) # 或安装后针对目标 set_target_properties(app PROPERTIES INSTALL_RPATH $ORIGIN/../lib)场景思路同前缀可移植包$ORIGIN相对 RPATH系统包装入标准lib靠 ldconfig开发构建构建树 RPATH 通常已可用10. find_package 与路径10.1 搜索示意find_package(ZLIB CONFIG) │ ├─► CMAKE_PREFIX_PATH 中的 ZlibConfig.cmake ├─► CMAKE_MODULE_PATH 中的 FindZLIB.cmakeMODULE 模式 └─► 系统路径顺序影响「先到先用」10.2 示例list(APPEND CMAKE_PREFIX_PATH /opt/mydeps/zlib-build) find_package(ZLIB REQUIRED CONFIG) # 命令行等价 # cmake -DCMAKE_PREFIX_PATH/opt/mydeps/zlib-build ..11. cmake_minimum_required 与旧策略11.1 关系示意cmake_minimum_required(VERSION 3.16) │ ▼ 隐式将大量 Policy 设为 ≤3.16 时的默认多为 OLD 或 NEW因版本而异 │ ▼ 需要新语义时提升版本或 cmake_policy(SET CMPxxxx NEW)11.2 示例策略节选策略主题简述CMP0077option()与已有普通变量CMP0048project()无 VERSION 时警告CMP0167FetchContent_Populate等行为cmake_minimum_required(VERSION 3.20) # 或在不抬最低版本时单独开启 if(POLICY CMP0077) cmake_policy(SET CMP0077 NEW) endif()12. if() 对变量的判断12.1 未加引号时部分取值简表if(FOO)中 FOO 取值常表现为假0、OFF、FALSE、IGNORE、NOTFOUND、以-NOTFOUND结尾是空字符串是其他非空字符串多为真注意非 0/1 字符串12.2 稳妥写法示例if(DEFINED ENABLE_X AND ENABLE_X STREQUAL ON) # ... endif() # 或布尔语义 if(ENABLE_X) endif() # 需保证 ENABLE_X 仅为 ON/OFF 或 1/013. 生成器表达式上下文13.1 求值时机配置期configure 生成期generate │ │ │ 多数 $ 在此尚不可求值 │ ▼ ▼ add_subdirectory 顺序 写入 build.ninja / VS 工程时展开13.2 合法使用示例target_compile_definitions(app PRIVATE $$CONFIG:Debug:DEBUG_BUILD1) target_include_directories(app PRIVATE $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/inc)常见错误在message()或顶层字符串拼接中滥用$TARGET_FILE:…期望配置期得到路径——多数应在install(CODE)或add_custom_command等支持生成器表达式的上下文中使用。速查总表#陷阱一句话规避1option 盖掉父 setif(NOT DEFINED …) option …或 CMP0077 NEW2目标未定义就 link先add_subdirectory/定义库再链接3乱改第三方目标INTERFACE包装4改 CMakeLists 不生效查缓存同名-U或删 build5include 指错用CURRENT_SOURCE_DIR/PROJECT_SOURCE_DIR6标准不一致target_compile_features7下游缺头文件API 用PUBLICBUILD_INTERFACE8GLOB 漏新文件显式列表或CONFIGURE_DEPENDS9安装后缺 .soINSTALL_RPATH$ORIGIN10找错包版本CMAKE_PREFIX_PATH CONFIG 模式11旧策略行为提升minimum_required或cmake_policy12if 误判DEFINED/STREQUAL13生成器表达式报错仅用于支持的属性与命令参考资料CMake 官方文档CMake Policiescmake commands (option, target_*)Modern CMake社区英文免责声明本文基于常见工程经验整理示意图仅表达逻辑关系。CMake 行为随版本变化请以当前所用版本的官方文档为准。
 获取与实战)
