5.6 探究编译和链接命令

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_compilecheck_cxx_source_compiles,并比较这两个命令的工作方式:

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

    1. cmake_minimum_required(VERSION 3.9 FATAL_ERROR)
    2. project(recipe-06 LANGUAGES CXX)
    3. set(CMAKE_CXX_STANDARD 11)
    4. set(CMAKE_CXX_EXTENSIONS OFF)
    5. set(CMAKE_CXX_STANDARD_REQUIRED ON)
  2. 查找编译器支持的OpenMP:

    1. find_package(OpenMP)
    2. if(OpenMP_FOUND)
    3. # ... <- the steps below will be placed here
    4. else()
    5. message(STATUS "OpenMP not found: no test for taskloop is run")
    6. endif()
  3. 如果找到OpenMP,再检查所需的特性是否可用。为此,设置了一个临时目录,try_compile将在这个目录下来生成中间文件。我们把它放在前面步骤中引入的if语句中:

    1. 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即可。如果编译成功,则任务循环特性可用,我们为用户打印一条消息:

    1. try_compile(
    2. omp_taskloop_test_1
    3. ${_scratch_dir}
    4. SOURCES
    5. ${CMAKE_CURRENT_SOURCE_DIR}/taskloop.cpp
    6. LINK_LIBRARIES
    7. OpenMP::OpenMP_CXX
    8. )
    9. message(STATUS "Result of try_compile: ${omp_taskloop_test_1}")
  5. 要使用check_cxx_source_compiles函数,需要包含CheckCXXSourceCompiles.cmake模块文件。其他语言也有类似的模块文件,C(CheckCSourceCompiles.cmake)和Fortran(CheckFortranSourceCompiles.cmake):

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

    1. file(READ ${CMAKE_CURRENT_SOURCE_DIR}/taskloop.cpp _snippet)
  7. 我们设置了CMAKE_REQUIRED_LIBRARIES。这对于下一步正确调用编译器是必需的。注意使用导入的OpenMP::OpenMP_CXX目标,它还将设置正确的编译器标志和包含目录:

    1. set(CMAKE_REQUIRED_LIBRARIES OpenMP::OpenMP_CXX)
  8. 使用代码片段作为参数,调用check_cxx_source_compiles函数。检查结果将保存到omp_taskloop_test_2变量中:

    1. check_cxx_source_compiles("${_snippet}" omp_taskloop_test_2)
  9. 调用check_cxx_source_compiles并向用户打印消息之前,我们取消了变量的设置:

    1. unset(CMAKE_REQUIRED_LIBRARIES)
    2. message(STATUS "Result of check_cxx_source_compiles: ${omp_taskloop_test_2}"
  10. 最后,进行测试:

    1. $ mkdir -p build
    2. $ cd build
    3. $ cmake ..
    4. -- ...
    5. -- Found OpenMP_CXX: -fopenmp (found version "4.5")
    6. -- Found OpenMP: TRUE (found version "4.5")
    7. -- Result of try_compile: TRUE
    8. -- Performing Test omp_taskloop_test_2
    9. -- Performing Test omp_taskloop_test_2 - Success
    10. -- Result of check_cxx_source_compiles: 1

工作原理

try_compilecheck_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.logCMakeError.log文件会提供一些线索。它们记录了CMake运行的操作的标准输出和标准错误。如果怀疑结果有误,应该通过搜索保存编译检查结果的变量集来检查前者。如果你怀疑有误报,你应该检查后者。

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

  1. 运行CMake,不使用--debug-trycompile,将运行所有try_compile命令,并清理它们的执行目录和文件。

  2. 从CMake缓存中删除保存检查结果的变量。缓存保存到CMakeCache.txt文件中。要清除变量的内容,可以使用-U的CLI开关,后面跟着变量的名称,它将被解释为一个全局表达式,因此可以使用*?

    1. $ cmake -U <variable-name>
  3. 再次运行CMake,使用--debug-trycompile。只有清除缓存的检查才会重新运行。这次不会清理执行目录和文件。

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