CMake中add_custom_command用法详解

add_custom_command 是 CMake 中用于在构建过程中添加自定义命令的工具。它通常用于生成文件或在构建特定目标前后执行操作。其行为和执行时机取决于具体使用场景。

---

主要用法

add_custom_command 有两种典型用法：

1. 生成文件（Generating Files）

用于生成一个或多个文件，通常与 add_custom_target 或目标依赖结合使用。

add_custom_command(
  OUTPUT output_file         # 生成的输出文件
  COMMAND command [args...]  # 执行的命令
  DEPENDS depend_files...    # 依赖的文件或目标
  COMMENT "message"          # 可选，构建时的提示信息
)

• 执行时机：当 output_file 不存在，或其 DEPENDS 中的文件被修改时，命令会自动执行。
• 示例：生成源代码文件：

  add_custom_command(
    OUTPUT generated.cpp
    COMMAND generator_tool input.txt generated.cpp
    DEPENDS input.txt
  )
  add_executable(my_app generated.cpp)  # 依赖 generated.cpp
  

2. 构建事件（Build Events）

附加到某个目标（如可执行文件或库）的构建阶段，在构建前/后执行命令。

add_custom_command(
  TARGET target             # 目标名称（如可执行文件）
  PRE_BUILD | PRE_LINK | POST_BUILD
  COMMAND command [args...] # 执行的命令
  COMMENT "message"         # 可选，构建时的提示信息
)

• 执行时机：
  • PRE_BUILD：在编译目标源文件之前执行（某些生成器如 Visual Studio 支持）。
  • PRE_LINK：在编译源文件后、链接目标前执行。
  • POST_BUILD：在目标构建完成后执行。
• 示例：构建完成后复制文件：

  add_executable(my_app main.cpp)
  add_custom_command(
    TARGET my_app
    POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:my_app> /path/to/destination/
  )
  

---

关键注意事项

1. 生成文件的依赖链
   如果其他目标依赖 add_custom_command 生成的 OUTPUT 文件（如 generated.cpp），CMake 会自动确保该命令在编译依赖它的目标前执行。

2. 与 add_custom_target 的区别

   • add_custom_target 定义一个始终执行的虚拟目标（通过 make my_target 手动触发）。
   • add_custom_command 仅在需要生成文件或响应构建事件时触发。

3. 跨平台兼容性
   使用 ${CMAKE_COMMAND} -E 调用跨平台友好的命令（如文件操作），避免直接使用 cp 或 mv 等系统命令。

---

总结：执行时机

• 生成文件模式：当 OUTPUT 文件不存在，或 DEPENDS 的文件被修改时自动执行。
• 构建事件模式：在目标构建的指定阶段（如 POST_BUILD）无条件执行。

合理使用 add_custom_command 可以实现文件生成、后处理、资源嵌入等灵活操作，确保构建流程的自动化。