CMake 笔记 | [37] 使用废弃函数、宏和变量

注意
本文最后更新于 2024-02-01,文中内容可能已过时。

一、导言

导言
废弃是在不断发展的项目开发过程中一种重要机制,它向开发人员发出信号,表明将来某个函数、宏或变量将被删除或替换。在一段时间内,函数、宏或变量将继续可访问,但会发出警告,最终可能会上升为错误。

二、项目结构

1
2
3
4
.
├── cmake
│   └── custom_guard.cmake
└── CMakeLists.txt

项目结构:

https://gitee.com/jiangli01/tutorials/tree/master/cmake-tutorial/chapter7/06

三、相关源码

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
cmake_minimum_required(VERSION 3.10 FATAL_ERROR)

project(example 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()

function(deprecate_variable _variable _access)
  if(_access STREQUAL "READ_ACCESS")
    message(DEPRECATION "variable ${_variable} is deprecated")
  endif()
endfunction()

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()

include(cmake/custom_guard.cmake)

message(STATUS "list of all included modules: ${included_modules}")
引用
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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()

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

引用

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

1.定义一个函数,使用它来弃用一个变量

1
2
3
4
5
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中:

1
2
3
4
5
6
7
8
9
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()

cmake/custom_guard.cmake

1
2
3
custom_include_guard()

message(STATUS "custom.cmake is included and processed")

四、结果展示

1
2
3
$ mkdir -p build
$ cd build
$ cmake ..

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

1
2
-- custom_custom.cmake is included and processed
-- list of all included modules: /home/jiangli/repo/tutorials/cmake-tutorial/chapter7/06/cmake/custom.cmake

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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_guard.cmake:1 (custom_include_guard)
  CMakeLists.txt:34 (include)


-- custom_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/jiangli/repo/tutorials/cmake-tutorial/chapter7/06/cmake/custom_guard.cmake
-- Configuring done
-- Generating done
-- Build files have been written to: /home/jiangli/repo/tutorials/cmake-tutorial/chapter7/06/build
Buy me a coffee~
支付宝
微信
0%