7.6 使用廢棄函數、宏和變量 · cmake-cookbook

# 7.6 使用廢棄函數、宏和變量 **NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-7/recipe-06 中找到。該示例在CMake 3.5版(或更高版本)中是有效的，并且已經在GNU/Linux、macOS和Windows上進行過測試。* “廢棄”是在不斷發展的項目開發過程中一種重要機制，它向開發人員發出信號，表明將來某個函數、宏或變量將被刪除或替換。在一段時間內，函數、宏或變量將繼續可訪問，但會發出警告，最終可能會上升為錯誤。 ## 準備工作我們將從以下CMake項目開始: ```cmake cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(recipe-06 LANGUAGES NONE) macro(custom_include_guard) if(NOT DEFINED included_modules) set(included_modules) endif() if ("${CMAKE_CURRENT_LIST_FILE}" IN_LIST included_modules) message(WARNING "module ${CMAKE_CURRENT_LIST_FILE} processed more than once") endif() list(APPEND included_modules ${CMAKE_CURRENT_LIST_FILE}) endmacro() include(cmake/custom.cmake) message(STATUS "list of all included modules: ${included_modules}") ``` 這段代碼定義了一個自定義的"包含保護"機制，包括一個自定義模塊(與前一個示例中的模塊相同)，并打印所有包含模塊的列表。對于CMake 3.10或更高版本有內置的`include_guard`。但是，不能簡單地刪除`custom_include_guard`和`${included_modules}`，而是使用一個“廢棄”警告來棄用宏和變量。某個時候，可以將該警告轉換為`FATAL_ERROR`，使代碼停止配置，并迫使開發人員對代碼進行修改，切換到內置命令。 ## 具體實施 “廢棄”函數、宏和變量的方法如下: 1. 首先，定義一個函數，我們將使用它來棄用一個變量: ```cmake function(deprecate_variable _variable _access) if(_access STREQUAL "READ_ACCESS") message(DEPRECATION "variable ${_variable} is deprecated") endif() endfunction() ``` 2. 然后，如果CMake的版本大于3.9，我們重新定義`custom_include_guard`并將`variable_watch`附加到`included_modules`中: ```cmake if (CMAKE_VERSION VERSION_GREATER "3.9") # deprecate custom_include_guard macro(custom_include_guard) message(DEPRECATION "custom_include_guard is deprecated - use built-in include_guard instead") _custom_include_guard(${ARGV}) endmacro() # deprecate variable included_modules variable_watch(included_modules deprecate_variable) endif() ``` 3. CMake3.10以下版本的項目會產生以下結果: ```shell $ mkdir -p build $ cd build $ cmake .. -- custom.cmake is included and processed -- list of all included modules: /home/user/example/cmake/custom.cmake ``` 4. CMake 3.10及以上將產生預期的“廢棄”警告: ```cmake CMake Deprecation Warning at CMakeLists.txt:26 (message): custom_include_guard is deprecated - use built-in include_guard instead Call Stack (most recent call first): cmake/custom.cmake:1 (custom_include_guard) CMakeLists.txt:34 (include) -- custom.cmake is included and processed CMake Deprecation Warning at CMakeLists.txt:19 (message): variable included_modules is deprecated Call Stack (most recent call first): CMakeLists.txt:9999 (deprecate_variable) CMakeLists.txt:36 (message) -- list of all included modules: /home/user/example/cmake/custom.cmake ``` ## 工作原理棄用函數或宏相當于重新定義它，如前面的示例所示，并使用`DEPRECATION`打印消息: ```cmake macro(somemacro) message(DEPRECATION "somemacro is deprecated") _somemacro(${ARGV}) endmacro() ``` 可以通過定義以下變量來實現對變量的棄用: ```cmake function(deprecate_variable _variable _access) if(_access STREQUAL "READ_ACCESS") message(DEPRECATION "variable ${_variable} is deprecated") endif() endfunction() ``` 然后，這個函數被添加到將要“廢棄”的變量上: ```cmake variable_watch(somevariable deprecate_variable) ``` 如果在本例中`${included_modules}`是讀取 (`READ_ACCESS`)，那么`deprecate_variable`函數將發出帶有`DEPRECATION`的消息。