Question

NOTE : 此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-7/recipe-05 中找到。该示例在 CMake 3.5 版（或更高版本) 中是有效的，并且已经在 GNU/Linux、macOS 和 Windows 上进行过测试。

我们已经提到模块包含不应该用作函数调用，因为模块可能被包含多次。本示例中，我们将编写我们自己的“包含保护”机制，如果多次包含一个模块，将触发警告。内置的 include_guard 命令从 3.10 版开始可以使用，对于 C/C++头文件，它的行为就像 #pragma 一样。对于当前版本的 CMake，我们将演示如何重新定义函数和宏，并且展示如何检查 CMake 版本，对于低于 3.10 的版本，我们将使用定制的“包含保护”机制。

准备工作

这个例子中，我们将使用三个文件:

.
├── cmake
│     ├── custom.cmake
│     └── include_guard.cmake
└── CMakeLists.txt

custom.cmake 模块包含以下代码:

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

我们稍后会对 cmake/include_guard.cmake 进行讨论。

具体实施

我们对三个 CMake 文件的逐步分解:

1. 示例中，我们不会编译任何代码，因此我们的语言要求是 NONE :

   cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
   project(recipe-05 LANGUAGES NONE)

2. 定义一个 include_guard 宏，将其放在一个单独的模块中:

   # (re)defines include_guard
   include(cmake/include_guard.cmake)

3. cmake/include_guard.cmake 文件包含以下内容（稍后将详细讨论):

   macro(include_guard)
     if (CMAKE_VERSION VERSION_LESS "3.10")
       # for CMake below 3.10 we define our
       # own include_guard(GLOBAL)
       message(STATUS "calling our custom include_guard")
   ​
       # if this macro is called the first time
       # we start with an empty list
       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})
       else()
       # for CMake 3.10 or higher we augment
       # the built-in include_guard
       message(STATUS "calling the built-in include_guard")
   ​
       _include_guard(${ARGV})
     endif()
   endmacro()

4. 主 CMakeLists.txt 中，我们模拟了两次包含自定义模块的情况:

   include(cmake/custom.cmake)
   include(cmake/custom.cmake)

5. 最后，使用以下命令进行配置:

   $ mkdir -p build
   $ cd build
   $ cmake ..

6. 使用 CMake 3.10 及更高版本的结果如下:

   -- calling the built-in include_guard
   -- custom.cmake is included and processed
   -- calling the built-in include_guard

7. 使用 CMake 得到 3.10 以下的结果如下:

   - calling our custom include_guard
   -- custom.cmake is included and processed
   -- calling our custom include_guard
   CMake Warning at cmake/include_guard.cmake:7 (message):
   module
   /home/user/example/cmake/custom.cmake
   processed more than once
   Call Stack (most recent call first):
   cmake/custom.cmake:1 (include_guard)
   CMakeLists.txt:12 (include)

工作原理

include_guard 宏包含两个分支，一个用于 CMake 低于 3.10，另一个用于 CMake 高于 3.10:

macro(include_guard)
  if (CMAKE_VERSION VERSION_LESS "3.10")
      # ...
  else()
      # ...
  endif()
endmacro()

如果 CMake 版本低于 3.10，进入第一个分支，并且内置的 include_guard 不可用，所以我们自定义了一个:

message(STATUS "calling our custom include_guard")
​
# if this macro is called the first time
# we start with an empty list
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})

如果第一次调用宏，则 included_modules 变量没有定义，因此我们将其设置为空列表。然后检查 ${CMAKE_CURRENT_LIST_FILE} 是否是 included_modules 列表中的元素。如果是，则会发出警告；如果没有，我们将 ${CMAKE_CURRENT_LIST_FILE} 追加到这个列表。CMake 输出中，我们可以验证自定义模块的第二个包含确实会导致警告。

CMake 3.10 及更高版本的情况有所不同；在这种情况下，存在一个内置的 include_guard ，我们用自己的宏接收到参数并调用它:

macro(include_guard)
  if (CMAKE_VERSION VERSION_LESS "3.10")
      # ...
  else()
      message(STATUS "calling the built-in include_guard")
​
      _include_guard(${ARGV})
  endif()
endmacro()

这里， _include_guard(${ARGV}) 指向内置的 include_guard 。本例中，使用自定义消息(“调用内置的 include_guard ”) 进行了扩展。这种模式为我们提供了一种机制，来重新定义自己的或内置的函数和宏，这对于调试或记录日志来说非常有用。

NOTE : 这种模式可能很有用，但是应该谨慎使用，因为 CMake 不会对重新定义的宏或函数进行警告。