Question

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

生成构建系统期间最常见的操作，是试图评估在哪种系统上构建项目。这意味着要找出哪些功能工作，哪些不工作，并相应地调整项目的编译。使用的方法是查询依赖项是否被满足的信号，或者在代码库中是否启用工作区。接下来的几个示例，将展示如何使用 CMake 执行这些操作。我们将特别讨论以下事宜:

1. 如何确保代码能成功编译为可执行文件。
2. 如何确保编译器理解相应的标志。
3. 如何确保特定代码能成功编译为运行可执行程序。

准备工作

示例将展示如何使用来自对应的 Check<LANG>SourceCompiles.cmake 标准模块的 check_<lang>_source_compiles 函数，以评估给定编译器是否可以将预定义的代码编译成可执行文件。该命令可帮助你确定:

• 编译器支持所需的特性。
• 链接器工作正常，并理解特定的标志。
• 可以使用 find_package 找到的包含目录和库。

本示例中，我们将展示如何检测 OpenMP 4.5 标准的循环特性，以便在 C++可执行文件中使用。使用一个 C++源文件，来探测编译器是否支持这样的特性。CMake 提供了一个附加命令 try_compile 来探究编译。本示例将展示，如何使用这两种方法。

TIPS : 可以使用 CMake 命令行界面来获取关于特定模块( cmake --help-module <module-name> ) 和命令( cmake --help-command <command-name> ) 的文档。示例中， cmake --help-module CheckCXXSourceCompiles 将把 check_cxx_source_compiles 函数的文档输出到屏幕上，而 cmake --help-command try_compile 将对 try_compile 命令执行相同的操作。

具体实施

我们将同时使用 try_compile 和 check_cxx_source_compiles ，并比较这两个命令的工作方式:

1. 创建一个 C++11 工程：

   cmake_minimum_required(VERSION 3.9 FATAL_ERROR)
   project(recipe-06 LANGUAGES CXX)
   set(CMAKE_CXX_STANDARD 11)
   set(CMAKE_CXX_EXTENSIONS OFF)
   set(CMAKE_CXX_STANDARD_REQUIRED ON)

2. 查找编译器支持的 OpenMP：

   find_package(OpenMP)
   ​
   if(OpenMP_FOUND)
       # ... <- the steps below will be placed here
   else()
       message(STATUS "OpenMP not found: no test for taskloop is run")
   endif()

3. 如果找到 OpenMP，再检查所需的特性是否可用。为此，设置了一个临时目录， try_compile 将在这个目录下来生成中间文件。我们把它放在前面步骤中引入的 if 语句中:

   set(_scratch_dir ${CMAKE_CURRENT_BINARY_DIR}/omp_try_compile)

4. 调用 try_compile 生成一个小项目，以尝试编译源文件 taskloop.cpp 。编译成功或失败的状态，将保存到 omp_taskloop_test_1 变量中。需要为这个示例编译设置适当的编译器标志、包括目录和链接库。因为使用导入的目标 OpenMP::OpenMP_CXX ，所以只需将 LINK_LIBRARIES 选项设置为 try_compile 即可。如果编译成功，则任务循环特性可用，我们为用户打印一条消息:

   try_compile(
     omp_taskloop_test_1
         ${_scratch_dir}
     SOURCES
         ${CMAKE_CURRENT_SOURCE_DIR}/taskloop.cpp
     LINK_LIBRARIES
         OpenMP::OpenMP_CXX
     )
   message(STATUS "Result of try_compile: ${omp_taskloop_test_1}")

5. 要使用 check_cxx_source_compiles 函数，需要包含 CheckCXXSourceCompiles.cmake 模块文件。其他语言也有类似的模块文件，C( CheckCSourceCompiles.cmake ) 和 Fortran( CheckFortranSourceCompiles.cmake ):

   include(CheckCXXSourceCompiles)

6. 我们复制源文件的内容，通过 file(READ ...) 命令读取内容到一个变量中，试图编译和连接这个变量:

   file(READ ${CMAKE_CURRENT_SOURCE_DIR}/taskloop.cpp _snippet)

7. 我们设置了 CMAKE_REQUIRED_LIBRARIES 。这对于下一步正确调用编译器是必需的。注意使用导入的 OpenMP::OpenMP_CXX 目标，它还将设置正确的编译器标志和包含目录:

   set(CMAKE_REQUIRED_LIBRARIES OpenMP::OpenMP_CXX)

8. 使用代码片段作为参数，调用 check_cxx_source_compiles 函数。检查结果将保存到 omp_taskloop_test_2 变量中:

   check_cxx_source_compiles("${_snippet}" omp_taskloop_test_2)

9. 调用 check_cxx_source_compiles 并向用户打印消息之前，我们取消了变量的设置:

   unset(CMAKE_REQUIRED_LIBRARIES)
   message(STATUS "Result of check_cxx_source_compiles: ${omp_taskloop_test_2}"

10. 最后，进行测试：

    $ mkdir -p build
    $ cd build
    $ cmake ..
    ​
    -- ...
    -- Found OpenMP_CXX: -fopenmp (found version "4.5")
    -- Found OpenMP: TRUE (found version "4.5")
    -- Result of try_compile: TRUE
    -- Performing Test omp_taskloop_test_2
    -- Performing Test omp_taskloop_test_2 - Success
    -- Result of check_cxx_source_compiles: 1

工作原理

try_compile 和 check_cxx_source_compiles 都将编译源文件，并将其链接到可执行文件中。如果这些操作成功，那么输出变量 omp_task_loop_test_1 (前者) 和 omp_task_loop_test_2 (后者) 将被设置为 TRUE 。然而，这两个命令实现的方式略有不同。 check_<lang>_source_compiles 命令是 try_compile 命令的简化包装。因此，它提供了一个接口:

1. 要编译的代码片段必须作为 CMake 变量传入。大多数情况下，这意味着必须使用 file(READ ...) 来读取文件。然后，代码片段被保存到构建目录的 CMakeFiles/CMakeTmp 子目录中。
2. 微调编译和链接，必须通过设置以下 CMake 变量进行:
   • CMAKE_REQUIRED_FLAGS：设置编译器标志。
   • CMAKE_REQUIRED_DEFINITIONS：设置预编译宏。
   • CMAKE_REQUIRED_INCLUDES：设置包含目录列表。
   • CMAKE_REQUIRED_LIBRARIES：设置可执行目标能够连接的库列表。
3. 调用 check_<lang>_compiles_function 之后，必须手动取消对这些变量的设置，以确保后续使用中，不会保留当前内容。

NOTE : 使用 CMake 3.9 中可以对于 OpenMP 目标进行导入，但是目前的配置也可以使用 CMake 的早期版本，通过手动为 check_cxx_source_compiles 设置所需的标志和库: set(CMAKE_REQUIRED_FLAGS ${OpenMP_CXX_FLAGS}) 和 set(CMAKE_REQUIRED_LIBRARIES ${OpenMP_CXX_LIBRARIES}) 。

TIPS : Fortran 下，CMake 代码的格式通常是固定的，但也有意外情况。为了处理这些意外，需要为 check_fortran_source_compiles 设置 -ffree-form 编译标志。可以通过 set(CMAKE_REQUIRED_FLAGS “-ffree-form") 实现。

这个接口反映了：测试编译是通过，在 CMake 调用中直接生成和执行构建和连接命令来执行的。

命令 try_compile 提供了更完整的接口和两种不同的操作模式:

1. 以一个完整的 CMake 项目作为输入，并基于它的 CMakeLists.txt 配置、构建和链接。这种操作模式提供了更好的灵活性，因为要编译项目的复杂度是可以选择的。
2. 提供了源文件，和用于包含目录、链接库和编译器标志的配置选项。

因此， try_compile 基于在项目上调用 CMake，其中 CMakeLists.txt 已经存在（在第一种操作模式中)，或者基于传递给 try_compile 的参数动态生成文件。

更多信息

本示例中概述的类型检查并不总是万无一失的，并且可能产生假阳性和假阴性。作为一个例子，可以尝试注释掉包含 CMAKE_REQUIRED_LIBRARIES 的行。运行这个例子仍然会报告“成功”，这是因为编译器将忽略 OpenMP 的 pragma 字段。

当返回了错误的结果时，应该怎么做？构建目录的 CMakeFiles 子目录中的 CMakeOutput.log 和 CMakeError.log 文件会提供一些线索。它们记录了 CMake 运行的操作的标准输出和标准错误。如果怀疑结果有误，应该通过搜索保存编译检查结果的变量集来检查前者。如果你怀疑有误报，你应该检查后者。

调试 try_compile 需要一些注意事项。即使检查不成功，CMake 也会删除由该命令生成的所有文件。幸运的是， debug-trycompile 将阻止 CMake 进行删除。如果你的代码中有多个 try_compile 调用，一次只能调试一个:

1. 运行 CMake，不使用 --debug-trycompile ，将运行所有 try_compile 命令，并清理它们的执行目录和文件。
2. 从 CMake 缓存中删除保存检查结果的变量。缓存保存到 CMakeCache.txt 文件中。要清除变量的内容，可以使用 -U 的 CLI 开关，后面跟着变量的名称，它将被解释为一个全局表达式，因此可以使用 * 和 ? ：

   $ cmake -U <variable-name>

3. 再次运行 CMake，使用 --debug-trycompile 。只有清除缓存的检查才会重新运行。这次不会清理执行目录和文件。

TIPS : try_compile 提供了灵活和干净的接口，特别是当编译的代码不是一个简短的代码时。我们建议在测试编译时，小代码片段时使用 check_<lang>_source_compile 。其他情况下，选择 try_compile 。