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项目开始:

  1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
  3. project(recipe-06 LANGUAGES NONE)
  5. macro(custom_include_guard)
  6.   if(NOT DEFINED included_modules)
  7.       set(included_modules)
  8.   endif()
  10.   if ("${CMAKE_CURRENT_LIST_FILE}" IN_LIST included_modules)
  11.       message(WARNING "module ${CMAKE_CURRENT_LIST_FILE} processed more than once")
  12.   endif()
  14.   list(APPEND included_modules ${CMAKE_CURRENT_LIST_FILE})
  15. endmacro()
  17. include(cmake/custom.cmake)
  19. message(STATUS "list of all included modules: ${included_modules}")

这段代码定义了一个自定义的”包含保护”机制，包括一个自定义模块(与前一个示例中的模块相同)，并打印所有包含模块的列表。对于CMake 3.10或更高版本有内置的include_guard。但是，不能简单地删除custom_include_guard和${included_modules}，而是使用一个“废弃”警告来弃用宏和变量。某个时候，可以将该警告转换为FATAL_ERROR，使代码停止配置，并迫使开发人员对代码进行修改，切换到内置命令。

具体实施

“废弃”函数、宏和变量的方法如下:

  1. 首先，定义一个函数，我们将使用它来弃用一个变量:

    1. function(deprecate_variable _variable _access)
    2.   if(_access STREQUAL "READ_ACCESS")
    3.       message(DEPRECATION "variable ${_variable} is deprecated")
    4.   endif()
    5. endfunction()

  2. 然后，如果CMake的版本大于3.9，我们重新定义custom_include_guard并将variable_watch附加到included_modules中:

    1. if (CMAKE_VERSION VERSION_GREATER "3.9")
    2.   # deprecate custom_include_guard
    3.   macro(custom_include_guard)
    4.     message(DEPRECATION "custom_include_guard is deprecated - use built-in include_guard instead")
    5.     _custom_include_guard(${ARGV})
    6.   endmacro()
    8.   # deprecate variable included_modules
    9.   variable_watch(included_modules deprecate_variable)
    10. endif()

  3. CMake3.10以下版本的项目会产生以下结果:

    1. $ mkdir -p build
    2. $ cd build
    3. $ cmake ..
    5. -- custom.cmake is included and processed
    6. -- list of all included modules: /home/user/example/cmake/custom.cmake

  4. CMake 3.10及以上将产生预期的“废弃”警告:

    1. CMake Deprecation Warning at CMakeLists.txt:26 (message):
    2. custom_include_guard is deprecated - use built-in include_guard instead
    3. Call Stack (most recent call first):
    4. cmake/custom.cmake:1 (custom_include_guard)
    5. CMakeLists.txt:34 (include)
    6. -- custom.cmake is included and processed
    7. CMake Deprecation Warning at CMakeLists.txt:19 (message):
    8. variable included_modules is deprecated
    9. Call Stack (most recent call first):
    10. CMakeLists.txt:9999 (deprecate_variable)
    11. CMakeLists.txt:36 (message)
    12. -- list of all included modules: /home/user/example/cmake/custom.cmake

工作原理

弃用函数或宏相当于重新定义它，如前面的示例所示，并使用DEPRECATION打印消息:

  1. macro(somemacro)
  2.   message(DEPRECATION "somemacro is deprecated")
  3.   _somemacro(${ARGV})
  4. endmacro()

可以通过定义以下变量来实现对变量的弃用:

  1. function(deprecate_variable _variable _access)
  2.   if(_access STREQUAL "READ_ACCESS")
  3.       message(DEPRECATION "variable ${_variable} is deprecated")
  4.   endif()
  5. endfunction()

然后，这个函数被添加到将要“废弃”的变量上:

  1. variable_watch(somevariable deprecate_variable)

如果在本例中${included_modules}是读取 (READ_ACCESS)，那么deprecate_variable函数将发出带有DEPRECATION的消息。