CMake I add_custom_command命令详解（构建）

add_custom_command(OUTPUT output1 [output2 ...]
                   COMMAND command1 [ARGS] [args1...]
                   [COMMAND command2 [ARGS] [args2...] ...]
                   [MAIN_DEPENDENCY depend]
                   [DEPENDS [depends...]]
                   [BYPRODUCTS [files...]]
                   [IMPLICIT_DEPENDS <lang1> depend1
                                    [<lang2> depend2] ...]
                   [WORKING_DIRECTORY dir]
                   [COMMENT comment]
                   [DEPFILE depfile]
                   [JOB_POOL job_pool]
                   [VERBATIM] [APPEND] [USES_TERMINAL]
                   [COMMAND_EXPAND_LISTS])
OUTPUT：指定命令预期生成的输出文件。3.20版本以后，输出参数可使用一组受限的生成器表达式。
COMMAND：指定生成时要执行的命令行。
MAIN_DEPENDENCY：指定命令的主输入源文件。类似于DEPENDS。
DEPENDS：指定命令所依赖的文件。
BYPRODUCTS：指定命令预期生成的文件，但其修改时间可能比依赖项的新，也可能不比依赖项的新。
IMPLICIT_DEPENDS：请求扫描输入文件的隐式依赖项。此选项不能与DEPFILE选项同时指定。
WORKING_DIRECTORY：指定在何处执行命令。
COMMENT：指定在生成时执行命令之前显示的消息。
DEPFILE：指定保存自定义命令依赖项的depfile。它通常由自定义命令本身发出。仅当生成器支持此关键字时，才能使用此关键字。
JOB_POOL：为Ninja生成器指定一个池。
VERBATIM：对于构建工具，命令的所有参数都将被正确转义，以便被调用的命令接收到的每个参数不变。请注意，在add_custom_command甚至看到参数之前，CMake语言处理器仍然使用一级转义。建议使用VERBATIM，因为它可以保证正确的行为。如果不指定VERBATIM，则行为是依赖于平台的，因为CMake没有针对于特定工具中特殊字符的保护措施。
APPEND：将COMMAND和DEPENDS 附加到第一个指定输出的自定义命令。
USES_TERMINAL：如果可能，该命令将被授予直接访问终端的权限。
COMMAND_EXPAND_LISTS：命令参数中的列表将展开，包括使用生成器表达式创建的列表。

add_custom_command 有两个限制：

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

第二个限制，可以使用 add_dependencies 来避免。不过，规避这两个限制的正确方法是使用 add_custom_target 命令。

2.执行没有输出的自定义操作

向目标（如库或可执行文件）添加自定义命令。这对于在构建目标之前或之后执行操作非常有用。该命令成为目标的一部分，仅在构建目标本身时执行。如果目标已生成，则不会执行该命令。

add_custom_command(TARGET <target>
                   PRE_BUILD | PRE_LINK | POST_BUILD
                   COMMAND command1 [ARGS] [args1...]
                   [COMMAND command2 [ARGS] [args2...] ...]
                   [BYPRODUCTS [files...]]
                   [WORKING_DIRECTORY dir]
                   [COMMENT comment]
                   [VERBATIM] [USES_TERMINAL]
                   [COMMAND_EXPAND_LISTS])
TARGET：由 add_executable 或 add_library 生成的目标文件名称；
PRE_BUILD | PRE_LINK | POST_BUILD：分别表示编译之前执行命令，链接之前执行命令，生成目标文件后执行命令；
COMMAND：需要执行的命令；
BYPRODUCTS：指定命令预期生成的文件，但其修改时间可能比依赖项的新，也可能不比依赖项的新。
WORKING_DIRECTORY：指定在何处执行命令。
COMMENT：指定在生成时执行命令之前显示的消息。
VERBATIM：对于构建工具，命令的所有参数都将被正确转义，以便被调用的命令接收到的每个参数不变。请注意，在add_custom_command甚至看到参数之前，CMake语言处理器仍然使用一级转义。建议使用VERBATIM，因为它可以保证正确的行为。如果不指定VERBATIM，则行为是依赖于平台的，因为CMake没有针对于特定工具中特殊字符的保护措施。
USES_TERMINAL：如果可能，该命令将被授予直接访问终端的权限。
COMMAND_EXPAND_LISTS：命令参数中的列表将展开，包括使用生成器表达式创建的列表。

补充：

PRE_BUILD：在执行与目标相关的任何其他规则之前执行的命令。

PRE_LINK：使用此选项，命令在编译目标之后，调用链接器或归档器之前执行。Visual Studio 7或更高版本之外的生成器中使用 PRE_BUILD 将被解释为 PRE_LINK 。

POST_BUILD：如前所述，这些命令将在执行给定目标的所有规则之后运行。

二、应用

1.执行有输出文件的自定义操作

下面的例子实现的是：声明自定义命令来提取wrap_BLAS_LAPACK.tar.gz压缩包，并更新提取文件的时间戳。

#声明一个变量 wrap_BLAS_LAPACK_sources来保存wrap_BLAS_LAPACK.tar.gz 压缩包文件的名称
set(wrap_BLAS_LAPACK_sources
  ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.hpp
  ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxBLAS.cpp
  ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.hpp
  ${CMAKE_CURRENT_BINARY_DIR}/wrap_BLAS_LAPACK/CxxLAPACK.cpp
  )

#当目标wrap_BLAS_LAPACK_sources 被新生成时，执行COMMAND 后面的命令
add_custom_command(
  OUTPUT
    ${wrap_BLAS_LAPACK_sources}
  COMMAND #在构建时提取打包文件
    ${CMAKE_COMMAND} -E tar xzf ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
  COMMAND #更新提取文件的时间戳
    ${CMAKE_COMMAND} -E touch ${wrap_BLAS_LAPACK_sources}
  WORKING_DIRECTORY #指定在何处执行命令
    ${CMAKE_CURRENT_BINARY_DIR}
  DEPENDS #列出了自定义命令的依赖项
    ${CMAKE_CURRENT_SOURCE_DIR}/wrap_BLAS_LAPACK.tar.gz
  COMMENT #在构建时打印状态消息
    "Unpacking C++ wrappers for BLAS/LAPACK"
  VERBATIM #告诉CMake为生成器和平台生成正确的命令，从而确保完全独立。
  )

2.执行没有输出的自定义操作

使用 add_custom_command 的第二种方式，在构建目标之前打印目标的链接：

add_executable(example "")

target_sources(example
  PRIVATE
    example.f90
  )

add_custom_command(
  TARGET
    example
  PRE_LINK
  COMMAND
    ${PYTHON_EXECUTABLE}
      ${CMAKE_CURRENT_SOURCE_DIR}/echo-file.py
      ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/example.dir/link.txt
  COMMENT
    "link line:"
  VERBATIM
  )

PRE_LINK 命令将 ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/example.dir/link.txt 的内容打印到屏幕上：

link line:
/usr/bin/f95 -O3 -DNDEBUG -O3 CMakeFiles/example.dir/example.f90.o -o example