6.1 配置时生成源码

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

代码生成在配置时发生，例如：CMake可以检测操作系统和可用库；基于这些信息，我们可以定制构建的源代码。本节和下面的章节中，我们将演示如何生成一个简单源文件，该文件定义了一个函数，用于报告构建系统配置。

准备工作

此示例的代码使用Fortran和C语言编写，第9章将讨论混合语言编程。主程序是一个简单的Fortran可执行程序，它调用一个C函数print_info()，该函数将打印配置信息。值得注意的是，在使用Fortran 2003时，编译器将处理命名问题(对于C函数的接口声明)，如示例所示。我们将使用的example.f90作为源文件:

  1. program hello_world
  3.   implicit none
  5.   interface
  6.       subroutine print_info() bind(c, name="print_info")
  7.       end subroutine
  8.   end interface
  10.   call print_info()
  12. end program

C函数print_info()在模板文件print_info.c.in中定义。在配置时，以@开头和结尾的变量将被替换为实际值:

  1. #include <stdio.h>
  2. #include <unistd.h>
  4. void print_info(void)
  5. {
  6.   printf("\n");
  7.   printf("Configuration and build information\n");
  8.   printf("-----------------------------------\n");
  9.   printf("\n");
  10.   printf("Who compiled | %s\n", "@_user_name@");
  11.   printf("Compilation hostname | %s\n", "@_host_name@");
  12.   printf("Fully qualified domain name | %s\n", "@_fqdn@");
  13.   printf("Operating system | %s\n",
  14.          "@_os_name@, @_os_release@, @_os_version@");
  15.   printf("Platform | %s\n", "@_os_platform@");
  16.   printf("Processor info | %s\n",
  17.          "@_processor_name@, @_processor_description@");
  18.   printf("CMake version | %s\n", "@CMAKE_VERSION@");
  19.   printf("CMake generator | %s\n", "@CMAKE_GENERATOR@");
  20.   printf("Configuration time | %s\n", "@_configuration_time@");
  21.   printf("Fortran compiler | %s\n", "@CMAKE_Fortran_COMPILER@");
  22.   printf("C compiler | %s\n", "@CMAKE_C_COMPILER@");
  23.   printf("\n");
  25.   fflush(stdout);
  26. }

具体实施

在CMakeLists.txt中，我们首先必须对选项进行配置，并用它们的值替换print_info.c.in中相应的占位符。然后，将Fortran和C源代码编译成一个可执行文件:

  1. 声明了一个Fortran-C混合项目:

    1. cmake_minimum_required(VERSION 3.10 FATAL_ERROR)
    2. project(recipe-01 LANGUAGES Fortran C)

  2. 使用execute_process为项目获取当且使用者的信息:

    1. execute_process(
    2.   COMMAND
    3.       whoami
    4.   TIMEOUT
    5.       1
    6.   OUTPUT_VARIABLE
    7.       _user_name
    8.   OUTPUT_STRIP_TRAILING_WHITESPACE
    9.   )

  3. 使用cmake_host_system_information()函数(已经在第2章第5节遇到过)，可以查询很多系统信息:

    1. # host name information
    2. cmake_host_system_information(RESULT _host_name QUERY HOSTNAME)
    3. cmake_host_system_information(RESULT _fqdn QUERY FQDN)
    5. # processor information
    6. cmake_host_system_information(RESULT _processor_name QUERY PROCESSOR_NAME)
    7. cmake_host_system_information(RESULT _processor_description QUERY PROCESSOR_DESCRIPTION)
    9. # os information
    10. cmake_host_system_information(RESULT _os_name QUERY OS_NAME)
    11. cmake_host_system_information(RESULT _os_release QUERY OS_RELEASE)
    12. cmake_host_system_information(RESULT _os_version QUERY OS_VERSION)
    13. cmake_host_system_information(RESULT _os_platform QUERY OS_PLATFORM)

  4. 捕获配置时的时间戳，并通过使用字符串操作函数:

    1. string(TIMESTAMP _configuration_time "%Y-%m-%d %H:%M:%S [UTC]" UTC)

  5. 现在，准备好配置模板文件print_info.c.in。通过CMake的configure_file函数生成代码。注意，这里只要求以@开头和结尾的字符串被替换:

    1. configure_file(print_info.c.in print_info.c @ONLY)

  6. 最后，我们添加一个可执行目标，并定义目标源：

    1. add_executable(example "")
    2. target_sources(example
    3.   PRIVATE
    4.     example.f90
    5.     ${CMAKE_CURRENT_BINARY_DIR}/print_info.c
    6.   )

  7. 下面是一个输出示例：

    1. $ mkdir -p build
    2. $ cd build
    3. $ cmake ..
    4. $ cmake --build .
    5. $ ./example
    7. Configuration and build information
    8. -----------------------------------
    9. Who compiled | somebody
    10. Compilation hostname | laptop
    11. Fully qualified domain name | laptop
    12. Operating system | Linux, 4.16.13-1-ARCH, #1 SMP PREEMPT Thu May 31 23:29:29 UTC 2018
    13. Platform | x86_64
    14. Processor info | Unknown P6 family, 2 core Intel(R) Core(TM) i5-5200U CPU @ 2.20GHz
    15. CMake version | 3.11.3
    16. CMake generator | Unix Makefiles
    17. Configuration time | 2018-06-25 15:38:03 [UTC]
    18. Fortran compiler | /usr/bin/f95
    19. C compiler | /usr/bin/cc

工作原理

configure_file命令可以复制文件，并用变量值替换它们的内容。示例中，使用configure_file修改模板文件的内容，并将其复制到一个位置，然后将其编译到可执行文件中。如何调用configure_file:

  1. configure_file(print_info.c.in print_info.c @ONLY)

第一个参数是模板的名称为print_info.c.in。CMake假设输入文件的目录，与项目的根目录相对；也就是说，在${CMAKE_CURRENT_SOURCE_DIR}/print_info.c.in。我们选择print_info.c，作为第二个参数是配置文件的名称。假设输出文件位于相对于项目构建目录的位置：${CMAKE_CURRENT_BINARY_DIR}/print_info.c。

输入和输出文件作为参数时，CMake不仅将配置@VAR@变量，还将配置${VAR}变量。如果${VAR}是语法的一部分，并且不应该修改(例如在shell脚本中)，那么就很不方便。为了在引导CMake，应该将选项@ONLY传递给configure_file的调用，如前所述。

更多信息

注意，用值替换占位符时，CMake中的变量名应该与将要配置的文件中使用的变量名完全相同，并放在@之间。可以在调用configure_file时定义的任何CMake变量。我们的示例中，这包括所有内置的CMake变量，如CMAKE_VERSION或CMAKE_GENERATOR。此外，每当修改模板文件时，重新生成代码将触发生成系统的重新生成。这样，配置的文件将始终保持最新。

TIPS:通过使用CMake --help-variable-list，可以从CMake手册中获得完整的内部CMake变量列表。

NOTE:file(GENERATE…)为提供了一个有趣的替代configure_file，这是因为file允许将生成器表达式作为配置文件的一部分进行计算。但是，每次运行CMake时，file(GENERATE…)都会更新输出文件，这将强制重新构建依赖于该输出的所有目标。详细可参见https://crascit.com/2017/04/18/generated-sources-in-cmake-build 。