7.3 编写函数来测试和设置编译器标志

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

前两个示例中，我们使用了宏。本示例中，将使用一个函数来抽象细节并避免代码重复。我们将实现一个接受编译器标志列表的函数。该函数将尝试用这些标志逐个编译测试代码，并返回编译器理解的第一个标志。这样，我们将了解几个新特性：函数、列表操作、字符串操作，以及检查编译器是否支持相应的标志。

准备工作

按照上一个示例的推荐，我们将在( set_compiler_flag.cmake ) 模块中定义函数，然后调用函数。该模块包含以下代码，我们将在后面详细讨论:

include(CheckCCompilerFlag)
include(CheckCXXCompilerFlag)
include(CheckFortranCompilerFlag)
function(set_compiler_flag _result _lang)
  # build a list of flags from the arguments
  set(_list_of_flags)
  # also figure out whether the function
  # is required to find a flag
  set(_flag_is_required FALSE)
  foreach(_arg IN ITEMS ${ARGN})
      string(TOUPPER "${_arg}" _arg_uppercase)
      if(_arg_uppercase STREQUAL "REQUIRED")
          set(_flag_is_required TRUE)
      else()
          list(APPEND _list_of_flags "${_arg}")
      endif()
  endforeach()
​
  set(_flag_found FALSE)
  # loop over all flags, try to find the first which works
  foreach(flag IN ITEMS ${_list_of_flags})
      unset(_flag_works CACHE)
      if(_lang STREQUAL "C")
          check_c_compiler_flag("${flag}" _flag_works)
      elseif(_lang STREQUAL "CXX")
          check_cxx_compiler_flag("${flag}" _flag_works)
      elseif(_lang STREQUAL "Fortran")
          check_Fortran_compiler_flag("${flag}" _flag_works)
      else()
          message(FATAL_ERROR "Unknown language in set_compiler_flag: ${_lang}")
          endif()
​
    # if the flag works, use it, and exit
    # otherwise try next flag
    if(_flag_works)
      set(${_result} "${flag}" PARENT_SCOPE)
      set(_flag_found TRUE)
      break()
    endif()
  endforeach()
​
  # raise an error if no flag was found
  if(_flag_is_required AND NOT _flag_found)
      message(FATAL_ERROR "None of the required flags were supported")
  endif()
endfunction()

具体实施

展示如何在 CMakeLists.txt 中使用 set_compiler_flag 函数:

1. 定义最低 CMake 版本、项目名称和支持的语言（本例中是 C 和 C++):

   cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
   project(recipe-03 LANGUAGES C CXX)

2. 显示包含 set_compiler_flag.cmake :

   include(set_compiler_flag.cmake)

3. 测试 C 标志列表:

   set_compiler_flag(
     working_compile_flag C REQUIRED
     "-foo" # this should fail
     "-wrong" # this should fail
     "-wrong" # this should fail
     "-Wall" # this should work with GNU
     "-warn all" # this should work with Intel
     "-Minform=inform" # this should work with PGI
     "-nope" # this should fail
     )
   ​
   message(STATUS "working C compile flag: ${working_compile_flag}")

4. 测试 C++标志列表:

   set_compiler_flag(
     working_compile_flag CXX REQUIRED
     "-foo" # this should fail
     "-g" # this should work with GNU, Intel, PGI
     "/RTCcsu" # this should work with MSVC
     )
   ​
   message(STATUS "working CXX compile flag: ${working_compile_flag}")

5. 现在，我们可以配置项目并验证输出。只显示相关的输出，相应的输出可能会因编译器的不同而有所不同:

   $ mkdir -p build
   $ cd build
   $ cmake ..
   ​
   -- ...
   -- Performing Test _flag_works
   -- Performing Test _flag_works - Failed
   -- Performing Test _flag_works
   -- Performing Test _flag_works - Failed
   -- Performing Test _flag_works
   -- Performing Test _flag_works - Failed
   -- Performing Test _flag_works
   -- Performing Test _flag_works - Success
   -- working C compile flag: -Wall
   -- Performing Test _flag_works
   -- Performing Test _flag_works - Failed
   -- Performing Test _flag_works
   -- Performing Test _flag_works - Success
   -- working CXX compile flag: -g
   -- ...

工作原理

这里使用的模式是:

1. 定义一个函数或宏，并将其放入模块中
2. 包含模块
3. 调用函数或宏

从输出中，可以看到代码检查列表中的每个标志。一旦检查成功，它就打印成功的编译标志。看看 set_compiler_flag.cmake 模块的内部，这个模块又包含三个模块:

include(CheckCCompilerFlag)
include(CheckCXXCompilerFlag)
include(CheckFortranCompilerFlag)

这都是标准的 CMake 模块，CMake 将在 ${CMAKE_MODULE_PATH} 中找到它们。这些模块分别提供 check_c_compiler_flag 、 check_cxx_compiler_flag 和 check_fortran_compiler_flag 宏。然后定义函数:

function(set_compiler_flag _result _lang)
    ...
endfunction()

set_compiler_flag 函数需要两个参数， _result (保存成功编译标志或为空字符串) 和 _lang (指定语言:C、C++或 Fortran)。

我们也能这样调用函数:

set_compiler_flag(working_compile_flag C REQUIRED "-Wall" "-warn all")

这里有五个调用参数，但是函数头只需要两个参数。这意味着 REQUIRED 、 -Wall 和 -warn all 将放在 ${ARGN} 中。从 ${ARGN} 开始，我们首先使用 foreach 构建一个标志列表。同时，从标志列表中过滤出 REQUIRED ，并使用它来设置 _flag_is_required :

# build a list of flags from the arguments
set(_list_of_flags)
# also figure out whether the function
# is required to find a flag
set(_flag_is_required FALSE)
foreach(_arg IN ITEMS ${ARGN})
  string(TOUPPER "${_arg}" _arg_uppercase)
  if(_arg_uppercase STREQUAL "REQUIRED")
      set(_flag_is_required TRUE)
  else()
      list(APPEND _list_of_flags "${_arg}")
  endif()
endforeach()

现在，我们将循环 ${_list_of_flags} ，尝试每个标志，如果 _flag_works 被设置为 TRUE ，我们将 _flag_found 设置为 TRUE ，并中止进一步的搜索:

set(_flag_found FALSE)
# loop over all flags, try to find the first which works
foreach(flag IN ITEMS ${_list_of_flags})
​
  unset(_flag_works CACHE)
  if(_lang STREQUAL "C")
      check_c_compiler_flag("${flag}" _flag_works)
  elseif(_lang STREQUAL "CXX")
      check_cxx_compiler_flag("${flag}" _flag_works)
  elseif(_lang STREQUAL "Fortran")
      check_Fortran_compiler_flag("${flag}" _flag_works)
  else()
      message(FATAL_ERROR "Unknown language in set_compiler_flag: ${_lang}")
  endif()
​
  # if the flag works, use it, and exit
  # otherwise try next flag
  if(_flag_works)
      set(${_result} "${flag}" PARENT_SCOPE)
      set(_flag_found TRUE)
      break()
  endif()
endforeach()

unset(_flag_works CACHE) 确保 check_*_compiler_flag 的结果，不会在使用 _flag_works result 变量时，使用的是缓存结果。

如果找到了标志，并且 _flag_works 设置为 TRUE ，我们就将 _result 映射到的变量:

set(${_result} "${flag}" PARENT_SCOPE)

这需要使用 PARENT_SCOPE 来完成，因为我们正在修改一个变量，希望打印并在函数体外部使用该变量。请注意，如何使用 ${_result} 语法解引用，从父范围传递的变量 _result 的值。不管函数的名称是什么，这对于确保工作标志被设置非常有必要。如果没有找到任何标志，并且该标志设置了 REQUIRED ，那我们将使用一条错误消息停止配置:

# raise an error if no flag was found
if(_flag_is_required AND NOT _flag_found)
    message(FATAL_ERROR "None of the required flags were supported")
endif()

更多信息

我们也可以使用宏来完成这个任务，而使用函数可以对范围有更多的控制。我们知道函数只能可以修改结果变量。

另外，需要在编译和链接时设置一些标志，方法是为 check_<lang>_compiler_flag 函数设置 CMAKE_REQUIRED_FLAGS 。如第 5 章，第 7 节中讨论的那样，Sanitizer 就是这种情况。