cmake-policies(7)

简介

CMake 中的策略用于跨多个版本保留向后兼容行为。如果引入一项新策略，较新版本的 CMake 将开始对向后兼容行为发出警告。可以请求显式启用 cmake_policy() 命令的 OLD（向后兼容）行为，以禁用警告。还可以要求对策略采用 NEW（不向后兼容）行为，也可以避免发出警告。还可以使用 CMAKE_POLICY_DEFAULT_CMP<NNNN> 变量通过命令行明确将每项策略设置为 NEW 或 OLD 行为。

策略是一种弃用机制，而不是可靠的功能切换。几乎不应该设置策略 OLD，但可以用来消除冻结或稳定的代码库的警告，也可以暂时用作更大迁移路径的一部分。每项策略的 OLD 行为都不理想，而且将在将来的版本中被错误情况取代。

如果用老版本的 CMake 构建项目时，cmake_minimum_required() 命令不止报告报错，还会将该 CMake 版本或更早版本中引入的所有策略设置为 NEW 行为。为管理那些策略，无需增加最低要求的 CMake 版本，可以采用 if(POLICY) 命令

if(POLICY CMP0990)
  cmake_policy(SET CMP0990 NEW)
endif()

这样一来，较新版本的 CMake（用户可能在使用，而且未发出兼容性警告）可以用 NEW 行为。

在某些情况下，策略的设置限定在其父作用域能不传播。例如，如果 include() 命令或 find_package() 命令读取的文件包含有 cmake_policy() 的使用情况，那么默认情况下，该策略设置不会影响调用者。这两个命令都接受一个可选项 NO_POLICY_SCOPE 关键字来控制这种行为。

CMAKE_MINIMUM_REQUIRED_VERSION 变量还可以用来确定是否报告那些弃用宏或函数的使用情况错误。

CMake 3.31 引入的策略

• CMP0180: project() 始终将 <PROJECT-NAME>_* 设置为常规变量。
• CMP0179: 链接行上静态库的重复删除会保留第一次出现。
• CMP0178: 测试命令行会保留空参数。
• CMP0177: install() DESTINATION 路径已规范化。
• CMP0176: execute_process() ENCODING 默认采用 UTF-8。
• CMP0175: add_custom_command() 会拒绝无效参数。
• CMP0174: cmake_parse_arguments(PARSE_ARGV) 会为单值关键字后空字符串定义一个变量。
• CMP0173: CMakeFindFrameworks 模块已删除。
• CMP0172: CPack 模块在 CPack WIX Generator 中默认启用机器安装。
• CMP0171: 'codegen' 是一个保留的目标名称。

CMake 3.30 引入的策略

• CMP0170: 强制执行 FETCHCONTENT_FULLY_DISCONNECTED 要求。
• CMP0169: FetchContent_Populate(depName) 单参数签名已弃用。
• CMP0168: FetchContent 通过子构建直接实现步骤，而不是通过子构建。
• CMP0167: FindBoost 模块已删除。
• CMP0166: TARGET_PROPERTY 会过渡性地评估静态库私有依赖项的链接属性。
• CMP0165: 不得在 project() 之前调用 enable_language()。
• CMP0164: 当平台不支持时，add_library() 会拒绝 SHARED 库。
• CMP0163: 现在所有目录都可以看到 GENERATED 源文件属性。
• CMP0162: Visual Studio 生成器默认添加 UseDebugLibraries 指示器。

CMake 3.29 引入的策略

• CMP0161: CPACK_PRODUCTBUILD_DOMAINS 默认值为 true。
• CMP0160: 更多只读目标属性现在会在尝试设置时出错。
• CMP0159：带有 REGEX 项的 file(STRINGS) 更新 CMAKE_MATCH_<n>。
• CMP0158：当进行交叉编译时，add_test() 仅尊重 CMAKE_CROSSCOMPILING_EMULATOR。
• CMP0157：一种抽象方法选择了 Swift 编译模式。
• CMP0156：基于链接器功能，消除链接行上的重复库项。

CMake 3.28 引入的策略

• CMP0155：当支持时，在具有至少 C++20 的目标中扫描 C++ 源代码以进行导入。
• CMP0154：默认情况下，使用文件集的目标中生成的文件是私有的。
• CMP0153：不应调用 exec_program 命令。
• CMP0152：在折叠 ../ 组件之前，file(REAL_PATH) 会解析符号链接。

CMake 3.27 引入的策略

• CMP0151：默认情况下，AUTOMOC include 目录是系统 include 目录。
• CMP0150：ExternalProject_Add 和 FetchContent_Declare 将相对 git 存储库路径视为相对于父项目远程路径。
• CMP0149：默认情况下，Visual Studio 生成器选择最新的 Windows SDK。
• CMP0148：已删除 FindPythonInterp 和 FindPythonLibs 模块。
• CMP0147：Visual Studio 生成器并行构建自定义命令。
• CMP0146：已删除 FindCUDA 模块。
• CMP0145：已删除 Dart 和 FindDart 模块。
• CMP0144：find_package 使用大写 PACKAGENAME_ROOT 变量。

CMake 3.26 引入的策略

• CMP0143：默认情况下，USE_FOLDERS 全局属性视为 ON。

CMake 3.25 引入的策略

• CMP0142：Xcode 生成器不会将配置文件后缀附加到库搜索路径。
• CMP0141：一种抽象方法选择了 MSVC 调试信息格式标志。
• CMP0140：return() 命令会检查其自变量。

CMake 3.24 引入的策略

• CMP0139：if() 命令支持使用 PATH_EQUAL 运算符进行路径比较。
• CMP0138：CheckIPOSupported 使用来自调用项目的标志。
• CMP0137：try_compile() 在项目模式中传递平台变量。
• CMP0136：一种抽象方法选择了 Watcom 运行时库标志。
• CMP0135：对于 URL 下载方法，默认情况下 ExternalProject 和 FetchContent 忽略归档中的时间戳。
• CMP0134：当无法使用“TARGET”视图时，回退到“HOST”Windows 注册表视图。
• CMP0133：CPack 模块在 CPack DragNDrop 生成器中默认禁用 SLA。
• CMP0132：不要在首次运行时设置编译器环境变量。
• CMP0131：LINK_LIBRARIES 支持 LINK_ONLY 生成器表达式。
• CMP0130：while() 诊断条件求值错误。

CMake 3.23 引入的策略

• CMP0129：MCST LCC 编译器的编译器 id 现为 LCC，而非 GNU。

CMake 3.22 引入的策略

• CMP0128：改进了对语言标准和扩展标志的选择。
• CMP0127：cmake_dependent_option() 支持完全的条件语法。

由CMake 3.21 引入的策略

• CMP0126: set(CACHE) 不会移除同名的普通变量。
• CMP0125: find_(path|file|library|program) 具有获取缓存变量的一致行为。
• CMP0124: foreach() 循环变量仅在循环作用域中可用。
• CMP0123: ARMClang cpu/arch 编译和链接标志必须显式设置。
• CMP0122: UseSWIG 使用 C# 语言的标准库命名约定。
• CMP0121: list 命令检测无效的索引。

由 CMake 3.20 引入的策略

• CMP0120: WriteCompilerDetectionHeader 模块已移除。
• CMP0119: LANGUAGE 源文件属性显式编译为语言。
• CMP0118: 生成的源可在目录间使用，无需手动标记。
• CMP0117: 默认情况下不会将 MSVC RTTI 标志 /GR 添加到 CMAKE_CXX_FLAGS。
• CMP0116: Ninja 生成器转换来自 add_custom_command() 的 DEPFILE。
• CMP0115: 源文件扩展名必须显式。

由 CMake 3.19 引入的策略

• CMP0114: ExternalProject 步骤目标完全采用其步骤。
• CMP0113: Makefile 生成器不会重复来自目标依赖项的自定义命令。
• CMP0112: 目标文件组件生成器表达式不添加目标依赖项。
• CMP0111: 生成期间会失败缺少其位置属性的导入目标。
• CMP0110: add_test() 支持测试名称中的任意字符。
• CMP0109: find_program() 需要执行权限，但不需要读取权限。

由 CMake 3.18 引入的策略

• CMP0108: 目标无法通过别名链接到自身。
• CMP0107: ALIAS 目标无法覆盖其他目标。
• CMP0106: Documentation 模块已移除。
• CMP0105: 设备链接步骤使用链接选项。
• CMP0104: 现在为 NVCC 检测 CMAKE_CUDA_ARCHITECTURES，不允许 CUDA_ARCHITECTURES 为空。
• CMP0103: 不允许使用没有 APPEND 的多个 export() 与相同的 FILE。

由 CMake 3.17 引入的策略

• CMP0102: 如果缓存条目不存在，mark_as_advanced() 不执行任何操作。
• CMP0101: target_compile_options 在所有作用域内都尊重 BEFORE 关键字。
• CMP0100: 允许 AUTOMOC 和 AUTOUIC 处理 .hh 头文件。
• CMP0099: 链接属性是静态库的私有依赖项中的传递属性。
• CMP0098: 执行时 FindFLEX 会在 CMAKE_CURRENT_BINARY_DIR 中运行 flex。

由 CMake 3.16 引入的策略

• CMP0097: 带有 GIT_SUBMODULES "" 的 ExternalProject_Add 不初始化子模块。
• CMP0096: project() 保留版本组件中的前导零。
• CMP0095: 在中间 CMake 安装脚本中对 RPATH 条目进行正确转义。

由 CMake 3.15 引入的策略

• CMP0094: FindPython3、FindPython2 和 FindPython 使用 LOCATION 查找策略。
• CMP0093: FindBoost 以 x.y.z 格式报告 Boost_VERSION。
• CMP0092: 默认情况下，CMake_{C,CXX}_FLAGS 中不包含 MSVC 警告标志。
• CMP0091: MSVC 运行时库标志由一个抽象选定。
• CMP0090: 默认情况下 export(PACKAGE) 不会填充程序包注册表。
• CMP0089: 基于 IBM Clang 的 XL 编译器的编译器 ID 现在是 XLClang。

由 CMake 3.14 引入的策略

• CMP0088: 执行时 FindBISON 会在 CMAKE_CURRENT_BINARY_DIR 中运行 bison。
• CMP0087: install(SCRIPT | CODE) 支持生成器表达式。
• CMP0086：UseSWIG 通过 -module 标志尊守 SWIG_MODULE_NAME。
• CMP0085：IN_LIST 生成器表达式处理空列表项。
• CMP0084：FindQt 模块不存在于 find_package()。
• CMP0083：链接可执行文件时添加 PIE 选项。
• CMP0082：add_subdirectory() 中的安装规则与调用方中的规则交错。

CMake 3.13 引入的策略

• CMP0081：链接目录目标属性中不允许存在相对路径。
• CMP0080：BundleUtilities 无法在配置时间内包含。
• CMP0079：target_link_libraries 允许与其他目录中的目标一起使用。
• CMP0078：UseSWIG 生成标准的目标名称。
• CMP0077：optioon() 尊守正常变量。
• CMP0076：target_sources() 命令将相对路径转换为绝对路径。

CMake 3.12 引入的策略

• CMP0075：包含文件检查宏尊守 CMAKE_REQUIRED_LIBRARIES。
• CMP0074：find_package 使用 PackageName_ROOT 变量。
• CMP0073：不生成传统 _LIB_DEPENDS 缓存条目。

CMake 3.11 引入的策略

• CMP0072：FindOpenGL 在默认情况下优先选择 GLVND（如果可用）。

CMake 3.10 引入的策略

• CMP0071：允许 AUTOMOC 和 AUTOUIC 处理 GENERATED 文件。
• CMP0070：为相对路径定义 file(GENERATE) 行为。

CMake 3.9 引入的策略

• CMP0069：在启用时强制执行 INTERPROCEDURAL_OPTIMIZATION。
• CMP0068：macOS 上的 RPATH 设置不影响 install_name。

CMake 3.8 引入的策略

• CMP0067：在 try_compile() source-file 签名中尊守语言标准。

CMake 3.7 引入的策略

• CMP0066：在 try_compile() source-file 签名中尊守每个配置的标志。

CMake 3.4 引入的策略

• CMP0065：不向没有 ENABLE_EXPORTS 目标属性的可执行文件添加导出符号的标志。
• CMP0064：支持新的 TEST if() 运算符。

CMake 3.3 引入的策略

• CMP0063：尊守所有目标类型的可见性属性。
• CMP0062：拒绝将 export() 结果安装到。
• CMP0061：默认情况下，CTest 不会告诉 make 忽略错误 (-i)。
• CMP0060：即使在隐式目录中，也要通过完整路径链接库。
• CMP0059：不要将 DEFINITIONS 视为内置目录属性。
• CMP0058：Ninja 要求自定义命令副产品是显式的。
• CMP0057：支持新的 IN_LIST if() 运算符。

CMake 3.2 引入的策略

• CMP0056：在 try_compile() source-file 签名中尊守链接标志。
• CMP0055：对 break() 命令进行严格检查。

CMake 3.1 引入的策略

• CMP0054：如果未加引号，仅将 if() 参数解释为变量或关键字。
• CMP0053：简化变量引用和转义序列评估。
• CMP0052：拒绝已安装 INTERFACE_INCLUDE_DIRECTORIES 中的源和构建目录。
• CMP0051：在 SOURCE 目标属性中列出 TARGET_OBJECTS。

CMake 3.0 引入的策略

• CMP0050：不允许 add_custom_command SOURCE 签名。
• CMP0049：不要展开目标源条目中的变量。
• CMP0048：project() 命令管理 VERSION 变量。
• CMP0047：对 QNX 上的 qcc 驱动程序使用 QCC 编译器 ID。
• CMP0046：在 add_dependencies 中出现不存在的依赖项时出错。
• CMP0045：在 get_target_property 中出现不存在的目标时出错。
• CMP0044：大小写敏感的 Lang_COMPILER_ID 生成表达式。
• CMP0043：忽略 COMPILE_DEFINITIONS_Config 属性。
• CMP0042：MACOSX_RPATH 默认启用。
• CMP0041：生成表达式出现相对包含时出错。
• CMP0040：add_custom_command() 的 TARGET 签名中的目标必须存在。
• CMP0039：实用程序目标可能没有链接依赖项。
• CMP0038：目标可能不能直接链接到自身。
• CMP0037：目标名称不应保留，并且应匹配有效性模式。
• CMP0036：不应调用 build_name 命令。
• CMP0035：不应调用 variable_requires 命令。
• CMP0034：不应调用 utility_source 命令。
• CMP0033：不应调用 export_library_dependencies 命令。
• CMP0032：不应调用 output_required_files 命令。
• CMP0031：不应调用 load_command 命令。
• CMP0030：不应调用 use_mangled_mesa 命令。
• CMP0029：不应调用 subdir_depends 命令。
• CMP0028：目标名称中的双冒号表示 ALIAS 或 IMPORTED 目标。
• 具有缺失包含目录的有条件链接的导入目标。
• CMP0026：不允许使用 LOCATION 目标属性。
• CMP0025：Apple Clang 的编译器 ID 现在为 AppleClang。
• CMP0024：不允许包含导出结果。

CMake 2.8 引入的策略

• CMP0023：不能混合简单的和关键字的 target_link_libraries 签名。
• CMP0022：INTERFACE_LINK_LIBRARIES 定义了链接接口。
• CMP0021：INCLUDE_DIRECTORIES 目标属性中相对路径会产生致命错误。
• 在 Windows 上自动链接 Qt 可执行文件至 qtmain 目标。
• CMP0019：不要在包含和链接信息中重新展开变量。
• CMP0018：忽略 CMAKE_SHARED_LIBRARY_Lang_FLAGS 变量。
• CMP0017：从那里包含时，优先使用 CMake 模块目录中的文件。
• CMP0016：如果 target_link_libraries() 的唯一参数不是目标，则报告错误。
• CMP0015：link_directories() 处理相对于源目录的路径。
• CMP0014：输入目录必须有 CMakeLists.txt。
• CMP0013：不允许重复的二进制目录。
• CMP0012：if() 识别数字和布尔常量。

CMake 2.6 引入的策略

• CMP0011：包含的脚本会自动执行 cmake_policy PUSH 和 POP。
• CMP0010：变量引用语法错误会导致错误。
• CMP0009： 默认情况下，FILE GLOB_RECURSE 调用不应遵循符号链接。
• CMP0008： 根据完整路径链接的库必须具有有效的库文件名。
• CMP0007： list 命令不再忽略空元素。
• CMP0006： 安装 MACOSX_BUNDLE 目标需要 BUNDLE 目标。
• CMP0005： 预处理器定义值现在自动转义。
• CMP0004： 链接的库不得有前导或尾随空格。
• CMP0003： 通过完整路径链接的库不再产生链接器搜索路径。
• CMP0002： 逻辑目标名称在全球范围内必须是唯一的。
• CMP0001： 不应再使用 CMAKE_BACKWARDS_COMPATIBILITY。
• CMP0000： 必须指定所需的最低 CMake 版本。