5.3 构建时运行自定义命令:Ⅰ. 使用add_custom_command

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

项目的构建目标取决于命令的结果,这些命令只能在构建系统生成完成后的构建执行。CMake提供了三个选项来在构建时执行自定义命令:

  1. 使用add_custom_command编译目标,生成输出文件。
  2. add_custom_target的执行没有输出。
  3. 构建目标前后,add_custom_command的执行可以没有输出。

这三个选项强制执行特定的语义,并且不可互换。接下来的三个示例将演示具体的用法。

准备工作

我们将重用第3章第4节中的C++示例,以说明如何使用add_custom_command的第一个选项。代码示例中,我们了解了现有的BLAS和LAPACK库,并编译了一个很小的C++包装器库,以调用线性代数的Fortran实现。

我们将把代码分成两部分。linear-algebra.cpp的源文件与第3章、第4章没有区别,并且将包含线性代数包装器库的头文件和针对编译库的链接。源代码将打包到一个压缩的tar存档文件中,该存档文件随示例项目一起提供。存档文件将在构建时提取,并在可执行文件生成之前,编译线性代数的包装器库。

具体实施

CMakeLists.txt必须包含一个自定义命令,来提取线性代数包装器库的源代码:

  1. 从CMake最低版本、项目名称和支持语言的定义开始:

    1. cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
    2. project(recipe-03 LANGUAGES CXX Fortran)
  2. 选择C++11标准:

    1. set(CMAKE_CXX_STANDARD 11)
    2. set(CMAKE_CXX_EXTENSIONS OFF)
    3. set(CMAKE_CXX_STANDARD_REQUIRED ON)
  3. 然后,在系统上查找BLAS和LAPACK库:

    1. find_package(BLAS REQUIRED)
    2. find_package(LAPACK REQUIRED)
  4. 声明一个变量wrap_BLAS_LAPACK_sources来保存wrap_BLAS_LAPACK.tar.gz压缩包文件的名称:

    1. set(wrap_BLAS_LAPACK_sources
    2. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.hpp
    3. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.cpp
    4. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.hpp
    5. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.cpp
    6. )
  5. 声明自定义命令来提取wrap_BLAS_LAPACK.tar.gz压缩包,并更新提取文件的时间戳。注意这个wrap_BLAS_LAPACK_sources变量的预期输出:

    1. add_custom_command(
    2. OUTPUT
    3. ${wrap_BLAS_LAPACK_sources}
    4. COMMAND
    5. ${CMAKE_COMMAND} -E tar xzf ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
    6. COMMAND
    7. ${CMAKE_COMMAND} -E touch ${wrap_BLAS_LAPACK_sources}
    8. WORKING_DIRECTORY
    9. ${CMAKE_CURRENT_BINARY_DIR}
    10. DEPENDS
    11. ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
    12. COMMENT
    13. "Unpacking C++ wrappers for BLAS/LAPACK"
    14. VERBATIM
    15. )
  6. 接下来,添加一个库目标,源文件是新解压出来的:

    1. add_library(math "")
    2. target_sources(math
    3. PRIVATE
    4. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.cpp
    5. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.cpp
    6. PUBLIC
    7. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.hpp
    8. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.hpp
    9. )
    10. target_include_directories(math
    11. INTERFACE
    12. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK
    13. )
    14. target_link_libraries(math
    15. PUBLIC
    16. ${LAPACK_LIBRARIES}
    17. )
  7. 最后,添加linear-algebra可执行目标。可执行目标链接到库:

    1. add_executable(linear-algebra linear-algebra.cpp)
    2. target_link_libraries(linear-algebra
    3. PRIVATE
    4. math
    5. )
  8. 我们配置、构建和执行示例:

    1. $ mkdir -p build
    2. $ cd build
    3. $ cmake ..
    4. $ cmake --build .
    5. $ ./linear-algebra 1000
    6. C_DSCAL done
    7. C_DGESV done
    8. info is 0
    9. check is 4.35597e-10

工作原理

让我们来了解一下add_custom_command的使用:

  1. add_custom_command(
  2. OUTPUT
  3. ${wrap_BLAS_LAPACK_sources}
  4. COMMAND
  5. ${CMAKE_COMMAND} -E tar xzf ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
  6. COMMAND
  7. ${CMAKE_COMMAND} -E touch ${wrap_BLAS_LAPACK_sources}
  8. WORKING_DIRECTORY
  9. ${CMAKE_CURRENT_BINARY_DIR}
  10. DEPENDS
  11. ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
  12. COMMENT
  13. "Unpacking C++ wrappers for BLAS/LAPACK"
  14. VERBATIM
  15. )

add_custom_command向目标添加规则,并通过执行命令生成输出。add_custom_command中声明的任何目标,即在相同的CMakeLists.txt中声明的任何目标,使用输出的任何文件作为源文件的目标,在构建时会有规则生成这些文件。因此,源文件生成在构建时,目标和自定义命令在构建系统生成时,将自动处理依赖关系。

我们的例子中,输出是压缩tar包,其中包含有源文件。要检测和使用这些文件,必须在构建时提取打包文件。通过使用带有-E标志的CMake命令,以实现平台独立性。下一个命令会更新提取文件的时间戳。这样做是为了确保没有处理陈旧文件。WORKING_DIRECTORY可以指定在何处执行命令。示例中,CMAKE_CURRENT_BINARY_DIR是当前正在处理的构建目录。DEPENDS参数列出了自定义命令的依赖项。例子中,压缩的tar是一个依赖项。CMake使用COMMENT字段在构建时打印状态消息。最后,VERBATIM告诉CMake为生成器和平台生成正确的命令,从而确保完全独立。

我们来仔细看看这用使用方式和打包库的创建:

  1. add_library(math "")
  2. target_sources(math
  3. PRIVATE
  4. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.cpp
  5. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.cpp
  6. PUBLIC
  7. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.hpp
  8. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.hpp
  9. )
  10. target_include_directories(math
  11. INTERFACE
  12. ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK
  13. )
  14. target_link_libraries(math
  15. PUBLIC
  16. ${LAPACK_LIBRARIES}
  17. )

我们声明一个没有源的库目标,是因为后续使用target_sources填充目标的源。这里实现了一个非常重要的目标,即让依赖于此目标的目标,了解需要哪些目录和头文件,以便成功地使用库。C++源文件的目标是PRIVATE,因此只用于构建库。因为目标及其依赖项都需要使用它们来成功编译,所以头文件是PUBLIC。包含目录使用target_include_categories指定,其中wrap_BLAS_LAPACK声明为INTERFACE,因为只有依赖于math目标的目标需要它。

add_custom_command有两个限制:

  • 只有在相同的CMakeLists.txt中,指定了所有依赖于其输出的目标时才有效。
  • 对于不同的独立目标,使用add_custom_command的输出可以重新执行定制命令。这可能会导致冲突,应该避免这种情况的发生。

第二个限制,可以使用add_dependencies来避免。不过,规避这两个限制的正确方法是使用add_custom_target命令,我们将在下一节的示例中详细介绍。