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 產生器中啟用每個機器的安裝。
• CMP0171：'codegen' 是保留的目標名稱。

CMake 3.30 引入的政策

• CMP0170：強制執行 FETCHCONTENT_FULLY_DISCONNECTED 要求。
• CMP0169：FetchContent_Populate(depName) 單一參數簽名已棄用。
• CMP0168：FetchContent 直接實作步驟，而不是透過子組建。
• CMP0167：FindBoost 模組已移除。
• CMP0166：TARGET_PROPERTY 以遞移方式評估靜態程式庫的私有相依性的連結屬性。
• CMP0165：enable_language() 必須在 project() 之前呼叫。
• 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 包含目錄預設為系統包含目錄。
• 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：ExternalProject 和 FetchContent 預設會針對 URL 下載方法忽略封存中的時間戳記。
• CMP0134：當「目標」檢視無法使用時，回復為「主機」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 對於 csharp 語言使用標準函式庫命名慣例。
• CMP0121：list 命令會偵測無效索引。

CMake 3.20 導入的策略

• CMP0120：WriteCompilerDetectionHeader 模組已移除。
• CMP0119：LANGUAGE 原始檔屬性會明確地編譯為該語言。
• CMP0118：GENERATED 來源可以在目錄之間使用，而無需手動標記。
• 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：CMAKE_CUDA_ARCHITECTURES 現在會為 NVCC 偵測，不允許空的 CUDA_ARCHITECTURES。
• CMP0103：不允許在沒有 APPEND 的情況下，針對同一個 FILE 多次使用 export()。

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：RPATH 條目會在中間 CMake 安裝指令碼中正確逸出。

CMake 3.15 導入的策略

• CMP0094：FindPython3、FindPython2 和 FindPython 使用 LOCATION 作為查找策略。
• CMP0093：FindBoost 以 x.y.z 格式報告 Boost_VERSION。
• CMP0092：MSVC 警告旗標預設不在 CMAKE_{C,CXX}_FLAGS 中。
• 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：LINK_DIRECTORIES 目標屬性不允許使用相對路徑。
• CMP0080：BundleUtilities 無法在設定時包含。
• CMP0079：target_link_libraries 允許與其他目錄中的目標一起使用。
• CMP0078：UseSWIG 會產生標準目標名稱。
• CMP0077：option() 會遵循一般的變數。
• CMP0076：target_sources() 命令會將相對路徑轉換為絕對路徑。

CMake 3.12 導入的策略

• CMP0075：Include 檔案檢查巨集會遵循 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() 原始檔簽名中遵循語言標準。

CMake 3.7 導入的策略

• CMP0066：在 try_compile() 原始檔簽名中遵循每個設定的旗標。

CMake 3.4 導入的策略

• CMP0065：如果沒有 ENABLE_EXPORTS 目標屬性，則不要將旗標新增至從可執行檔匯出符號。
• CMP0064：支援新的 TEST if() 運算子。

CMake 3.3 導入的策略

• CMP0063：遵循所有目標類型的可見性屬性。
• CMP0062：不允許 install() export() 結果。
• CMP0061：CTest 預設不會告訴 make 忽略錯誤 (-i)。
• CMP0060：即使在隱含目錄中，也會透過完整路徑連結函式庫。
• CMP0059：不要將 DEFINITIONS 視為內建目錄屬性。
• CMP0058：Ninja 要求自訂命令副產品必須明確。
• CMP0057：支援新的 IN_LIST if() 運算子。

CMake 3.2 導入的策略

• CMP0056：在 try_compile() 原始檔簽名中遵循連結旗標。
• CMP0055：嚴格檢查 break() 命令。

CMake 3.1 導入的策略

• CMP0054：僅在未加引號時，將 if() 引數解譯為變數或關鍵字。
• CMP0053：簡化變數參考和逸出序列求值。
• CMP0052：拒絕安裝的 INTERFACE_INCLUDE_DIRECTORIES 中的來源和建置目錄。
• CMP0051：在 SOURCES 目標屬性中列出 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 目標。
• CMP0027：有條件連結的匯入目標遺失包含目錄。
• CMP0026：不允許使用 LOCATION 目標屬性。
• CMP0025：Apple Clang 的編譯器 ID 現在是 AppleClang。
• CMP0024：不允許包含匯出結果。

CMake 2.8 導入的策略

• CMP0023：純文字和關鍵字 target_link_libraries 簽名不能混合使用。
• CMP0022：INTERFACE_LINK_LIBRARIES 定義連結介面。
• CMP0021：在 INCLUDE_DIRECTORIES 目標屬性中使用相對路徑會發生嚴重錯誤。
• CMP0020：自動將 Qt 可執行檔連結至 Windows 上的 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 DESTINATION。
• CMP0005：預處理器定義值現在會自動進行跳脫處理。
• CMP0004：連結的函式庫不能包含前導或尾隨的空白。
• CMP0003：透過完整路徑連結的函式庫不再產生連結器搜尋路徑。
• CMP0002：邏輯目標名稱必須是全域唯一的。
• CMP0001：不應再使用 CMAKE_BACKWARDS_COMPATIBILITY。
• CMP0000：必須指定最小要求的 CMake 版本。