CMake深度解析：掌握add_custom_command，精通Makefile生成规则

1. CMake简介与基础知识
- 1.1 CMake的基本概念（CMake Basic Concepts）
- - 1.1.1 项目（Project）
  - 1.1.2 目标（Target）
  - 1.1.3 命令（Command）
  - 1.1.4 变量（Variable）
- 1.2 CMake的工作原理（How CMake Works）
- - 1.2.1 配置阶段（Configuration Phase）
  - 1.2.2 生成阶段（Generation Phase）
2. add_custom_command命令详解
- 2.1 add_custom_command命令的基本语法
- 2.2 add_custom_command命令的主要选项详解（Detailed Explanation of Main Options in add_custom_command）
- - 2.2.1 TARGET选项（TARGET Option）
  - - 使用方法
    - 注意事项
    - 实际应用
  - 2.2.2 PRE_BUILD、PRE_LINK 和 POST_BUILD选项（PRE_BUILD, PRE_LINK and POST_BUILD Options）
  - - PRE_BUILD（预构建）
    - PRE_LINK（链接前）
    - POST_BUILD（构建后）
  - 2.2.3 COMMAND选项（COMMAND Option）
  - - 2.2.3.1 COMMAND选项的基本用法
    - 2.2.3.2 COMMAND选项的高级用法
    - 2.2.3.3 COMMAND选项的注意事项
    - 2.2.3.4 COMMAND选项的实践应用
  - 2.2.4 DEPENDS选项详解
  - 2.2.5 BYPRODUCTS选项详解
  - 2.2.6 WORKING_DIRECTORY选项
  - - WORKING_DIRECTORY选项的基本用法
    - WORKING_DIRECTORY选项的实际应用
    - WORKING_DIRECTORY选项的注意事项
    - WORKING_DIRECTORY选项的高级应用
  - 2.2.7 COMMENT选项
  - - COMMENT选项的基本用法
    - COMMENT选项的高级用法
    - COMMENT选项的注意事项
  - 2.2.8 VERBATIM选项
  - - 2.2.8.1 VERBATIM选项的基本用法
    - 2.2.8.2 VERBATIM选项的作用
    - 2.2.8.3 VERBATIM选项的注意事项
    - 2.2.8.4 VERBATIM选项的实际应用示例
3. add_custom_command在实际项目中的应用
- 3.1 如何使用add_custom_command控制Makefile的生成（How to Control the Generation of Makefile with add_custom_command）
- 3.2 add_custom_command在大型项目中的应用案例
- - 3.2.1 案例一：自动生成代码
  - 3.2.2 案例二：自定义编译步骤
  - 3.2.3 案例三：自定义清理步骤
4. add_custom_command的高级应用
- 4.1 如何使用add_custom_command进行跨平台构建（How to Use add_custom_command for Cross-platform Build）
- 4.2 如何使用add_custom_command进行复杂的构建流程控制
5. add_custom_command的注意事项与最佳实践
- 5.1 add_custom_command的常见问题与解决方案（Common Problems and Solutions of add_custom_command）
- - 问题1：add_custom_command命令没有执行
  - 问题2：add_custom_command命令的执行顺序不正确
  - 问题3：add_custom_command命令的输出没有被正确处理
- 5.2 add_custom_command的最佳实践（Best Practices of add_custom_command）
- - 5.2.1 明确命令的执行时机（Specify the Execution Timing of the Command）
  - 5.2.2 使用DEPENDS选项管理依赖（Use DEPENDS Option to Manage Dependencies）
  - 5.2.3 使用VERBATIM选项控制命令参数的处理方式（Use VERBATIM Option to Control the Processing of Command Parameters）
  - 5.2.4 使用COMMENT选项提供有用的信息（Use COMMENT Option to Provide Useful Information）
  - 5.2.5 使用BYPRODUCTS选项管理副产品（Use BYPRODUCTS Option to Manage Byproducts）
  - 5.2.6 使用WORKING_DIRECTORY选项指定工作目录（Use WORKING_DIRECTORY Option to Specify Working Directory）

1. CMake简介与基础知识

1.1 CMake的基本概念（CMake Basic Concepts）

CMake（Cross-Platform Make）是一个跨平台的、开源的构建系统，它被广泛应用于各种大小的项目中。CMake使用一种名为 CMakeLists.txt 的文件来描述构建过程，这种文件的语法相对简单，但功能强大，可以满足各种复杂的构建需求。

CMake的主要概念包括以下几个部分：

1.1.1 项目（Project）

在CMake中，一个项目（Project）通常对应一个软件产品或库。每个项目都有一个名字，这个名字在整个CMake构建过程中都是唯一的。一个项目可以包含多个子项目（Subproject），子项目可以独立构建，也可以作为父项目的一部分构建。

1.1.2 目标（Target）

目标（Target）是CMake构建过程中的一个基本单位，它可以是一个可执行文件、一个库，或者一个自定义的命令。每个目标都有一个名字，这个名字在同一个项目中必须是唯一的。目标之间可以存在依赖关系，CMake会自动处理这些依赖关系，确保目标按照正确的顺序构建。

1.1.3 命令（Command）

命令（Command）是CMake的基本操作单位，每个命令都有一个名字和一组参数。CMake提供了大量的内置命令，这些命令可以用来定义目标、设置变量、控制流程等。用户也可以定义自己的命令，这就是我们今天主要讨论的 add_custom_command。

1.1.4 变量（Variable）

变量（Variable）是CMake中的一个重要概念，它可以用来保存各种类型的值，包括字符串、数字、列表等。变量的值可以在构建过程中动态改变，这使得CMake的构建过程具有很高的灵活性。

以上就是CMake的一些基本概念，理解这些概念对于深入理解CMake的工作原理和使用方法非常重要。在接下来的章节中，我们将深入探讨 add_custom_command 命令，以及如何利用.

1.2 CMake的工作原理（How CMake Works）

CMake的工作过程可以分为两个主要阶段：配置阶段和生成阶段。

1.2.1 配置阶段（Configuration Phase）

在配置阶段，CMake首先会读取 CMakeLists.txt 文件，解析其中的命令和变量。这个过程中，CMake会检查系统环境，确定编译器、库和工具的位置，以及其他的构建参数。这些信息会被保存在一个名为 CMakeCache.txt 的文件中，以便在后续的构建过程中使用。

配置阶段的主要任务是确定构建的目标和依赖关系。CMake会根据 CMakeLists.txt 文件中的命令，创建一系列的目标。每个目标都有一组源文件和一组依赖目标。CMake会检查这些源文件和依赖目标，确定目标的构建顺序。

1.2.2 生成阶段（Generation Phase）

在生成阶段，CMake会根据配置阶段得到的信息，生成实际的构建文件。这些构建文件可以是Makefile，也可以是其他的构建系统的配置文件，如Ninja、Visual Studio的项目文件等。

生成阶段的主要任务是将目标和依赖关系转化为具体的构建规则。CMake会为每个目标生成一组构建规则，这些规则描述了如何从源文件和依赖目标构建出目标。这些构建规则会被写入到构建文件中，供后续的构建过程使用。

以上就是CMake的工作原理的基本概述。理解这个过程对于理解CMake的工作方式和如何使用CMake进行项目构建非常重要。在接下来的章节中，我们将深入探讨 add_custom_command 命令，以及如何利用这个命令在CMake的构建过程中添加自定义的操作。

2. add_custom_command命令详解

2.1 add_custom_command命令的基本语法

在深入探讨add_custom_command命令之前，我们首先需要理解其基本的语法结构。在CMake中，add_custom_command命令的基本语法如下：

add_custom_command(
    OUTPUT output1 [output2 ...]
    COMMAND command1 [ARGS] [args1...]
    [COMMAND command2 [ARGS] [args2...] ...]
    [MAIN_DEPENDENCY depend]
    [DEPENDS [depends...]]
    [BYPRODUCTS [files...]]
    [WORKING_DIRECTORY dir]
    [COMMENT comment]
    [VERBATIM]
)

这个命令的主要作用是定义一条自定义的构建规则，这条规则可以在构建过程中执行一系列的命令。下面我们来详细解析这个命令的各个参数。

OUTPUT output1 [output2 ...]：这个参数用于指定自定义命令的输出文件。这些文件在构建过程中会被生成，如果这些文件不存在，那么CMake就会执行这条自定义命令。
COMMAND command1 [ARGS] [args1...]：这个参数用于指定要执行的命令。你可以提供任何有效的命令，包括系统命令、脚本，或者其他的构建工具。ARGS关键字后面可以跟随一系列的参数，这些参数会被传递给命令。
MAIN_DEPENDENCY depend：这个参数用于指定自定义命令的主要依赖。如果这个依赖的文件被修改，那么自定义命令就会被执行。
DEPENDS [depends...]：这个参数用于指定自定义命令的其他依赖。如果这些依赖的文件被修改，那么自定义命令也会被执行。
BYPRODUCTS [files...]：这个参数用于指定自定义命令的副产品。如果你指定了一个或多个文件作为副产品，那么这些文件将会被添加到构建系统的清理列表中。
WORKING_DIRECTORY dir：这个参数用于指定自定义命令的工作目录。如果你没有指定这个参数，那么自定义命令将会在当前的源码目录中执行。
COMMENT comment：这个参数用于指定一个注释，这个注释将会在执行自定义命令时被打印出来。
VERBATIM：这个参数用于控制命令参数的处理方式。如果你指定了VERBATIM，那么命令参数将会被按照字面意义处理，而不会被解析为变量或表达式。

2.2 add_custom_command命令的主要选项详解（Detailed Explanation of Main Options in add_custom_command）

2.2.1 TARGET选项（TARGET Option）

在CMake中，add_custom_command命令的TARGET选项是一个非常重要的参数。它的主要作用是指定一个目标，自定义命令将会在构建这个目标时被执行。这个目标可以是任何CMake支持的目标类型，包括库（Library）、可执行文件（Executable）、测试（Test）等。

使用方法

TARGET选项的使用方法非常简单。在add_custom_command命令中，我们只需要在TARGET后面添加我们想要指定的目标名称即可。例如：

add_custom_command(
    TARGET my_target
    COMMAND echo "This is a custom command for my_target."
)

在这个例子中，我们指定了my_target为目标，当我们构建my_target时，会执行echo "This is a custom command for my_target."这个命令。

注意事项

在使用TARGET选项时，有几点需要注意：

TARGET指定的目标必须是已经存在的目标。如果你试图指定一个不存在的目标，CMake会在配置阶段报错。
TARGET选项只能用在add_custom_command命令中，不能用在add_custom_target命令中。这是因为add_custom_target命令是用来创建一个新的目标的，而add_custom_command命令是用来给已经存在的目标添加自定义命令的。
TARGET选项指定的目标，必须是在add_custom_command命令之前定义的。如果你试图在add_custom_command命令之后定义目标，CMake会在配置阶段报错。

实际应用

在实际的项目中，TARGET选项常常被用来添加一些在构建过程中需要执行的额外命令。例如，我们可能需要在构建一个库之前，先生成一些需要的源代码；或者在构建一个可执行文件之后，复制一些资源文件到指定的目录。这些操作都可以通过TARGET选项和add_custom_command命令来实现。

总的来说，TARGET选项是add_custom_command命令中一个非常重要的选项，它让我们可以在构建过程中添加自定义的命令，从而使得构建过程更加灵活和可控。

2.2.2 PRE_BUILD、PRE_LINK 和 POST_BUILD选项（PRE_BUILD, PRE_LINK and POST_BUILD Options）

在CMake的add_custom_command命令中，PRE_BUILD、PRE_LINK和POST_BUILD是非常重要的选项，它们用于指定自定义命令在构建过程中的执行时机。理解这三个选项的含义和使用方法，对于我们精确控制构建过程具有重要意义。

PRE_BUILD（预构建）

PRE_BUILD选项表示在所有其他步骤之前执行自定义命令。这个选项非常适合用于执行一些预处理任务，例如清理上一次构建的残留文件，或者检查某些必要的条件是否满足。

例如，我们可以使用PRE_BUILD选项来确保在构建开始之前，输出目录是干净的：

add_custom_command(
    TARGET MyTarget
    PRE_BUILD
    COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_CURRENT_BINARY_DIR}/output
    COMMENT "Cleaning up the output directory before build"
)

在这个例子中，我们使用了CMake的remove_directory命令来删除输出目录。这个命令会在每次构建MyTarget目标之前执行。

PRE_LINK（链接前）

PRE_LINK选项表示在链接步骤之前执行自定义命令。这个选项通常用于执行一些需要在编译完成但链接未开始之前的任务，例如生成或更新一些需要链接的库文件。

例如，我们可以使用PRE_LINK选项来生成一个静态库：

add_custom_command(
    TARGET MyTarget
    PRE_LINK
    COMMAND ${CMAKE_AR} rcs libMyLib.a ${MY_LIB_OBJECTS}
    DEPENDS ${MY_LIB_OBJECTS}
    COMMENT "Creating static library libMyLib.a"
)

在这个例子中，我们使用了ar命令来创建一个静态库libMyLib.a。这个命令会在链接MyTarget目标之前执行。

POST_BUILD（构建后）

POST_BUILD选项表示在所有步骤之后执行自定义命令。这个选项通常用于执行一些后处理任务，例如复制生成的文件到指定的目录，或者执行一些测试和验证任务。

例如，我们可以使用POST_BUILD选项来复制生成的可执行文件到一个指定的目录：

add_custom_command(
    TARGET MyTarget
    POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:MyTarget> ${CMAKE_CURRENT_BINARY_DIR}/bin
    COMMENT "Copying the executable to the bin directory"
)

在这个例子中，我们使用了CMake的

copy命令来复制生成的可执行文件到bin目录。这个命令会在构建MyTarget目标之后执行。

以下表格对比了PRE_BUILD、PRE_LINK和POST_BUILD这三个选项的主要差异：

选项	执行时机	常见用途
PRE_BUILD（预构建）	在所有其他步骤之前	执行预处理任务，如清理上一次构建的残留文件，检查某些必要的条件是否满足
PRE_LINK（链接前）	在链接步骤之前	执行需要在编译完成但链接未开始之前的任务，如生成或更新一些需要链接的库文件
POST_BUILD（构建后）	在所有步骤之后	执行后处理任务，如复制生成的文件到指定的目录，执行一些测试和验证任务

总的来说，PRE_BUILD、PRE_LINK和POST_BUILD这三个选项为我们提供了在不同阶段插入自定义命令的能力，使我们能够更灵活地控制构建过程。在实际使用中，我们应根据实际需求选择合适的选项。

2.2.3 COMMAND选项（COMMAND Option）

在CMake的add_custom_command命令中，COMMAND选项是一个核心的组成部分，它用于指定我们想要执行的命令。这个命令可以是任何有效的命令，包括系统命令、脚本，或者其他的构建工具。下面我们将详细介绍COMMAND选项的使用方法和注意事项。

2.2.3.1 COMMAND选项的基本用法

COMMAND选项后面通常跟随着我们想要执行的命令，例如：

add_custom_command(
    TARGET myTarget
    POST_BUILD
    COMMAND echo "This is a custom command."
)

在这个例子中，我们在myTarget的构建过程中添加了一个自定义命令，这个命令会在所有步骤之后（POST_BUILD）执行，命令的内容是echo "This is a custom command."，这条命令会在终端打印出一段文字。

2.2.3.2 COMMAND选项的高级用法

COMMAND选项不仅可以执行简单的系统命令，还可以执行复杂的脚本或者其他构建工具。例如，我们可以使用COMMAND选项来执行一个Python脚本：

add_custom_command(
    TARGET myTarget
    POST_BUILD
    COMMAND python3 myScript.py
)

在这个例子中，我们在myTarget的构建过程中添加了一个自定义命令，这个命令会在所有步骤之后（POST_BUILD）执行，命令的内容是python3 myScript.py，这条命令会执行一个Python脚本。

2.2.3.3 COMMAND选项的注意事项

在使用COMMAND选项时，有一些需要注意的地方：

COMMAND选项后面的命令需要是有效的，否则CMake会在构建过程中报错。
如果COMMAND选项后面的命令需要接收参数，那么这些参数需要以空格分隔的形式提供，例如：

add_custom_command(
    TARGET myTarget
    POST_BUILD
    COMMAND echo "This is a custom command." > output.txt
)

在这个例子中，我们在myTarget的构建过程中添加了一个自定义命令，这个命令会在所有步骤之后（POST_BUILD）执行，命令的内容是echo "This is a custom command." > output.txt，这条命令会在终端打印出一段文字，并将这段文字重定向到output.txt文件中。

如果COMMAND选项后面的命令是一个路径，那么这个路径需要是绝对路径，否则CMake可能无法找到这个命令。

以上就是关于CMake的add_custom_command命令中`

COMMAND选项的详细介绍。在实际使用中，我们可以根据需要灵活地使用COMMAND选项，执行各种不同的命令，从而实现复杂的构建流程。

2.2.3.4 COMMAND选项的实践应用

在实际项目中，COMMAND选项的应用场景非常广泛。例如，我们可以使用COMMAND选项来执行一些预处理或后处理任务，如代码格式化、单元测试、文档生成等。下面是一个使用COMMAND选项进行单元测试的例子：

add_custom_command(
    TARGET myTarget
    POST_BUILD
    COMMAND ctest -R myTest
)

在这个例子中，我们在myTarget的构建过程中添加了一个自定义命令，这个命令会在所有步骤之后（POST_BUILD）执行，命令的内容是ctest -R myTest，这条命令会执行名为myTest的单元测试。

此外，COMMAND选项还可以用于执行一些复杂的构建任务，如调用其他构建工具、执行脚本等。这些高级用法可以帮助我们实现更复杂、更灵活的构建流程。

总的来说，COMMAND选项是add_custom_command命令中非常重要的一个选项，通过灵活地使用COMMAND选项，我们可以在CMake中实现各种复杂的构建任务。

2.2.4 DEPENDS选项详解

DEPENDS选项（DEPENDS Option）在add_custom_command命令中扮演着非常重要的角色。它用于指定自定义命令的依赖关系。在实际的编程过程中，我们经常会遇到一些任务需要在其他任务完成后才能进行，这就是所谓的依赖关系。在CMake中，我们可以通过DEPENDS选项来明确指定这种依赖关系。

DEPENDS选项接受一个或多个文件名作为参数。这些文件名代表了自定义命令的依赖。当这些文件被修改后，自定义命令才会被执行。这种机制保证了我们的构建过程是有效和准确的，只有当依赖的文件发生变化时，相关的构建任务才会被执行，从而避免了不必要的构建任务。

以下是一个使用DEPENDS选项的示例：

add_custom_command(
  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.cpp
  COMMAND generate_foo_cpp
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/foo.template
)

在这个示例中，我们定义了一个自定义命令，这个命令的任务是生成一个名为foo.cpp的文件。这个命令依赖于一个名为foo.template的文件，只有当foo.template文件被修改后，这个命令才会被执行。

这就是DEPENDS选项的基本用法和工作原理。在实际的项目中，我们可以根据需要灵活地使用DEPENDS选项，来控制我们的构建过程。

2.2.5 BYPRODUCTS选项详解

在CMake的add_custom_command命令中，BYPRODUCTS选项是一个非常重要的参数。它用于指定自定义命令的副产品。如果你指定了一个或多个文件作为副产品，那么这些文件将会被添加到构建系统的清理列表中。这意味着，当你执行清理操作时，这些被标记为副产品的文件也会被清理掉。

让我们通过一个具体的例子来理解BYPRODUCTS选项的作用。假设我们有一个自定义命令，它的任务是生成一些临时文件，这些临时文件在构建过程中会被使用，但是在构建完成后，这些文件就没有用处了。这时，我们就可以使用BYPRODUCTS选项来指定这些临时文件，这样在执行清理操作时，这些临时文件也会被清理掉。

以下是一个使用BYPRODUCTS选项的例子：

add_custom_command(
    OUTPUT output.txt
    COMMAND ${CMAKE_COMMAND} -E echo "Hello, World!" > output.txt
    BYPRODUCTS temp.txt
)

在这个例子中，我们的自定义命令会生成一个名为output.txt的文件，同时还会生成一个名为temp.txt的临时文件。我们使用BYPRODUCTS选项指定了temp.txt为副产品，这样在执行清理操作时，temp.txt也会被清理掉。

需要注意的是，BYPRODUCTS选项只能在add_custom_command命令中使用，不能在add_custom_target命令中使用。这是因为add_custom_target命令是用来定义一个目标的，而不是用来定义一个命令的。

总的来说，BYPRODUCTS选项是一个非常有用的工具，它可以帮助我们管理构建过程中生成的临时文件，使我们的构建环境保持整洁。

2.2.6 WORKING_DIRECTORY选项

WORKING_DIRECTORY选项是add_custom_command命令中的一个重要参数，它用于指定自定义命令的工作目录。在我们进行项目构建时，有时需要在特定的目录下执行某些命令，这时就可以利用WORKING_DIRECTORY选项来实现。

WORKING_DIRECTORY选项的基本用法

WORKING_DIRECTORY选项的基本用法如下：

add_custom_command(
    TARGET target
    COMMAND command
    WORKING_DIRECTORY dir
)

在这个例子中，dir就是我们指定的工作目录。当CMake执行到这个add_custom_command命令时，它会切换到dir目录下，然后在这个目录下执行command命令。

WORKING_DIRECTORY选项的实际应用

在实际的项目构建中，WORKING_DIRECTORY选项的应用非常广泛。例如，我们可能需要在项目的源代码目录下执行一些预处理命令，或者在构建目录下执行一些后处理命令。这时，我们就可以使用WORKING_DIRECTORY选项来指定这些命令的工作目录。

下面是一个实际的例子：

add_custom_command(
    TARGET my_target
    PRE_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/config.h.in ${CMAKE_BINARY_DIR}/config.h
    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
)

在这个例子中，我们在构建目标my_target之前，先执行了一个命令，这个命令是将config.h.in文件从源代码目录复制到构建目录。并且，我们指定了这个命令的工作目录为构建目录。

这样，无论我们在哪里执行构建命令，这个复制文件的操作都会在正确的目录下执行，保证了构建的正确性。

WORKING_DIRECTORY选项的注意事项

在使用WORKING_DIRECTORY选项时，有一些需要注意的地方：

WORKING_DIRECTORY选项指定的目录必须是存在的，否则CMake会报错。如果你不确定目录是否存在，可以使用file(MAKE_DIRECTORY dir)命令来确保目录的存在。
如果没有指定WORKING_DIRECTORY选项，那么默认的工作目录就是当前的CMakeLists.txt文件所在的目录。
WORKING_DIRECTORY选项只影响当前的add_custom_command命令，不会影响其他的命令或者CMakeLists.txt文件。

以上就是关于WORKING_DIRECTORY选项的详细介绍，希望对你有所帮助。在实际的项目

构建中，我们可以灵活地使用WORKING_DIRECTORY选项，来控制自定义命令的执行环境，从而提高构建的灵活性和可控性。

WORKING_DIRECTORY选项的高级应用

WORKING_DIRECTORY选项不仅可以用于指定命令的工作目录，还可以用于实现一些高级的构建策略。例如，我们可以利用WORKING_DIRECTORY选项来实现跨平台的构建。

在跨平台的构建中，我们可能需要在不同的平台上使用不同的工作目录。例如，我们可能需要在Windows平台上使用一个目录，而在Linux平台上使用另一个目录。这时，我们可以使用CMake的平台检测功能，结合WORKING_DIRECTORY选项，来实现这个需求。

下面是一个例子：

if(WIN32)
    set(dir ${CMAKE_SOURCE_DIR}/win)
else()
    set(dir ${CMAKE_SOURCE_DIR}/linux)
endif()

add_custom_command(
    TARGET my_target
    COMMAND command
    WORKING_DIRECTORY ${dir}
)

在这个例子中，我们首先检测了当前的平台。如果是Windows平台，那么我们就设置工作目录为win目录；否则，我们就设置工作目录为linux目录。然后，我们在add_custom_command命令中使用了这个工作目录。

这样，我们就可以在不同的平台上使用不同的工作目录，从而实现跨平台的构建。

以上就是关于WORKING_DIRECTORY选项的详细介绍，希望对你有所帮助。在实际的项目构建中，我们可以灵活地使用WORKING_DIRECTORY选项，来控制自定义命令的执行环境，从而提高构建的灵活性和可控性。

2.2.7 COMMENT选项

COMMENT选项在add_custom_command命令中起到了非常重要的作用。它的主要功能是为自定义命令提供注释，这些注释将在执行自定义命令时被打印出来。这对于理解和调试构建过程非常有帮助。

COMMENT选项的基本用法

COMMENT选项的基本用法非常简单。你只需要在add_custom_command命令中添加COMMENT选项，然后提供一个字符串作为参数。这个字符串就是你想要打印的注释。例如：

add_custom_command(
    TARGET my_target
    POST_BUILD
    COMMAND my_command
    COMMENT "正在执行 my_command..."
)

在这个例子中，每当my_target被构建，且在所有步骤之后，my_command命令就会被执行。同时，"正在执行 my_command…"这个注释也会被打印出来。

COMMENT选项的高级用法

虽然COMMENT选项的基本用法非常简单，但是你可以通过一些高级技巧来更好地利用它。

首先，你可以使用CMake的变量和表达式来动态生成注释。例如，你可以创建一个变量来存储命令的名称，然后在COMMENT选项中使用这个变量：

set(MY_COMMAND_NAME "my_command")

add_custom_command(
    TARGET my_target
    POST_BUILD
    COMMAND ${MY_COMMAND_NAME}
    COMMENT "正在执行 ${MY_COMMAND_NAME}..."
)

在这个例子中，${MY_COMMAND_NAME}会被替换为my_command，所以打印的注释将是"正在执行 my_command…"。

此外，你还可以使用if命令来根据条件改变注释。例如，你可以根据构建类型（如Debug或Release）来打印不同的注释：

add_custom_command(
    TARGET my_target
    POST_BUILD
    COMMAND my_command
    COMMENT $<$<CONFIG:Debug>:"正在执行 my_command (Debug模式)..."
            $<$<CONFIG:Release>:"正在执行 my_command (Release模式)...">
)

在这个例子中， $< CONF I G : De b ug > 和$ CONFIG:Release是CMake的生成表达式，它们会根据当前的构建类型来返回true或false。如果当前的构建类型是Debug，那么"正在执行 my_command (Debug模式)…"这个注释将被打印出来。如果当前的构建类型是Release，那么"正在执行 my_command (Release模式)…"这个注释将被打印出来。

COMMENT选项的注意事项

虽然COMMENT选项非常有用，但是在使用它

时，还需要注意一些事项。

首先，COMMENT选项的参数必须是一个字符串。如果你提供的参数不是字符串，CMake将会报错。

其次，COMMENT选项的参数不能包含换行符。如果你的注释需要跨多行，你可以使用多个COMMENT选项，每个选项对应一行注释。

最后，虽然COMMENT选项可以帮助你理解和调试构建过程，但是它并不能替代良好的文档和注释。你应该始终确保你的CMake脚本有足够的注释和文档，以便其他人（或者未来的你）能够理解它。

以上就是关于CMake中add_custom_command命令中COMMENT选项的详细介绍。希望这些信息能帮助你更好地理解和使用这个强大的构建工具。

下图是对本节内容的图形化总结：

在这里插入图片描述

2.2.8 VERBATIM选项

VERBATIM选项是add_custom_command命令中的一个重要参数，它的主要作用是控制命令参数的处理方式。当我们在add_custom_command中指定了VERBATIM选项后，命令参数将会被按照字面意义处理，而不会被解析为变量或表达式。

2.2.8.1 VERBATIM选项的基本用法

在CMake的add_custom_command命令中，VERBATIM选项的基本用法如下：

add_custom_command(
    TARGET target
    COMMAND command
    VERBATIM
)

在这个例子中，target是我们要构建的目标，command是我们要执行的命令。当我们在命令后面添加了VERBATIM选项后，CMake会按照字面意义来处理command中的参数，而不会将它们解析为变量或表达式。

2.2.8.2 VERBATIM选项的作用

VERBATIM选项的主要作用是防止命令参数的误解析。在CMake中，我们常常需要使用变量或表达式来动态地生成命令参数。然而，如果我们直接将这些变量或表达式写在命令参数中，CMake可能会在解析命令参数时将它们误解析为字面值，从而导致命令执行失败。

为了解决这个问题，CMake提供了VERBATIM选项。当我们在add_custom_command命令中指定了VERBATIM选项后，CMake会按照字面意义来处理命令参数，而不会将它们解析为变量或表达式。这样，我们就可以在命令参数中安全地使用变量和表达式了。

2.2.8.3 VERBATIM选项的注意事项

虽然VERBATIM选项可以帮助我们防止命令参数的误解析，但在使用它时，我们还需要注意以下几点：

VERBATIM选项只能用在add_custom_command命令中，不能用在其他命令中。
VERBATIM选项必须放在COMMAND选项之后，否则它将不会生效。
当我们在add_custom_command命令中指定了VERBATIM选项后，我们需要确保命令参数中不包含任何需要被解析的变量或表达式。否则，这些变量或表达式将会被按照字面意义处理，而不会被正确地解析。

以上就是关于CMake中add_custom_command命令中VERBATIM

选项的详细介绍。在实际的项目开发中，我们可以根据需要灵活地使用VERBATIM选项，以确保命令参数的正确解析，从而提高我们的构建效率和项目质量。

2.2.8.4 VERBATIM选项的实际应用示例

下面我们通过一个实际的应用示例来进一步理解VERBATIM选项的作用。

假设我们在一个CMake项目中，需要在构建过程中执行一个脚本，这个脚本需要接收一个参数，这个参数是一个文件的路径。我们可以使用add_custom_command命令来实现这个需求，代码如下：

add_custom_command(
    TARGET target
    COMMAND ${CMAKE_COMMAND} -E echo "Running script..."
    COMMAND python3 ${CMAKE_SOURCE_DIR}/script.py ${CMAKE_BINARY_DIR}/output.txt
    VERBATIM
)

在这个例子中，我们首先使用echo命令打印了一条消息，然后我们调用了python3来执行我们的脚本，脚本的路径是${CMAKE_SOURCE_DIR}/script.py，脚本的参数是${CMAKE_BINARY_DIR}/output.txt。我们在命令后面添加了VERBATIM选项，这样CMake就会按照字面意义来处理命令参数，而不会将${CMAKE_SOURCE_DIR}和${CMAKE_BINARY_DIR}解析为变量。

通过这个例子，我们可以看到，VERBATIM选项可以帮助我们在命令参数中安全地使用变量，从而提高我们的构建效率和项目质量。

以上就是关于CMake中add_custom_command命令中VERBATIM选项的详细介绍。希望这些内容能帮助你更好地理解和使用CMake。

3. add_custom_command在实际项目中的应用

3.1 如何使用add_custom_command控制Makefile的生成（How to Control the Generation of Makefile with add_custom_command）

在CMake中，add_custom_command命令是一个非常强大的工具，它可以让我们在构建过程中插入自定义的命令，从而实现对Makefile生成过程的精细控制。下面我们将详细介绍如何使用add_custom_command来控制Makefile的生成。

首先，我们需要理解add_custom_command的基本语法。这个命令的基本形式如下：

add_custom_command(
    TARGET target
    PRE_BUILD | PRE_LINK | POST_BUILD
    COMMAND command1 [ARGS] [args1...]
    [COMMAND command2 [ARGS] [args2...] ...]
    [WORKING_DIRECTORY dir]
    [COMMENT comment]
    [VERBATIM]
)

在这个命令中，TARGET选项用于指定一个目标，自定义命令将会在构建这个目标时被执行。COMMAND选项用于指定要执行的命令，你可以提供任何有效的命令，包括系统命令、脚本，或者其他的构建工具。WORKING_DIRECTORY选项用于指定自定义命令的工作目录。

接下来，我们来看一个具体的例子。假设我们有一个项目，其中包含一个C++源文件main.cpp，我们希望在编译这个文件之前，先执行一个自定义的命令，比如打印一条消息。我们可以使用add_custom_command来实现这个需求：

add_custom_command(
    TARGET my_target
    PRE_BUILD
    COMMAND echo "开始编译main.cpp..."
)

在这个例子中，我们指定了TARGET为my_target，这意味着自定义命令将会在构建my_target目标时被执行。我们使用了PRE_BUILD选项，这意味着自定义命令将会在其他所有步骤之前执行。我们的COMMAND是echo "开始编译main.cpp..."，这是一个简单的打印消息的命令。

当我们运行CMake并构建my_target目标时，我们会看到在编译main.cpp之前，控制台上打印出了我们的自定义消息。

通过这个例子，我们可以看到，add_custom_command命令为我们提供了一种强大的方式，来插入自定义的命令，并控制这些命令在构建过程中的执行时机。这使得我们可以实现对Makefile生成过程的精细控制，满足各种复杂的构建需求。

在实际使用中，add_custom_command命令的选项还有很多，比如DEPENDS、BYPRODUCTS、COMMENT和VERBATIM等，这些选项可以

提供更多的控制能力，使得我们可以更精细地控制自定义命令的行为。

例如，DEPENDS选项可以用来指定自定义命令的依赖。如果你指定了一个或多个文件作为依赖，那么只有当这些文件被修改后，自定义命令才会被执行。这可以用来实现增量构建，提高构建效率。

BYPRODUCTS选项可以用来指定自定义命令的副产品。如果你指定了一个或多个文件作为副产品，那么这些文件将会被添加到构建系统的清理列表中，当你执行清理操作时，这些文件将会被删除。

COMMENT选项可以用来指定一个注释，这个注释将会在执行自定义命令时被打印出来，这可以用来提供一些有用的信息，帮助我们理解构建过程。

VERBATIM选项可以用来控制命令参数的处理方式。如果你指定了VERBATIM，那么命令参数将会被按照字面意义处理，而不会被解析为变量或表达式。这可以避免一些常见的错误，比如参数中包含特殊字符或空格时的问题。

通过合理地使用这些选项，我们可以实现各种复杂的构建需求，从而更好地控制Makefile的生成。

在下一节中，我们将介绍如何在实际项目中使用add_custom_command命令。

3.2 add_custom_command在大型项目中的应用案例

在大型项目中，add_custom_command命令的应用通常更为复杂和多样。下面我们将通过几个实际的应用案例，来深入理解add_custom_command在实际项目中的应用。

3.2.1 案例一：自动生成代码

在许多大型项目中，我们可能需要根据一些模板或者规则来自动生成一部分代码。这种情况下，我们可以使用add_custom_command来实现。

假设我们有一个脚本generate_code.py，它可以根据template.txt来生成generated_code.cpp。我们可以使用如下的add_custom_command来实现这个功能：

add_custom_command(
  OUTPUT generated_code.cpp
  COMMAND python generate_code.py template.txt generated_code.cpp
  DEPENDS template.txt
  COMMENT "Generating code from template..."
  VERBATIM
)

在这个例子中，OUTPUT选项指定了生成的文件，COMMAND选项指定了生成这个文件的命令，DEPENDS选项指定了这个命令的依赖，COMMENT选项提供了一条在执行命令时打印的消息，VERBATIM选项保证了命令参数的字面意义。

3.2.2 案例二：自定义编译步骤

在一些复杂的项目中，我们可能需要在编译过程中插入一些自定义的步骤。例如，我们可能需要在链接之前运行一些工具来处理我们的对象文件。这种情况下，我们可以使用add_custom_command的PRE_LINK选项来实现。

假设我们有一个工具process_objects，它可以处理我们的对象文件。我们可以使用如下的add_custom_command来在链接之前运行这个工具：

add_custom_command(
  TARGET my_target
  PRE_LINK
  COMMAND process_objects $<TARGET_OBJECTS:my_target>
  COMMENT "Processing object files..."
  VERBATIM
)

在这个例子中，TARGET选项指定了我们要处理的目标，PRE_LINK选项指定了我们要在链接之前执行这个命令，COMMAND选项指定了我们要执行的命令，COMMENT选项提供了一条在执行命令时打印的消息，VERBATIM选项保证了命令参数的字面意义。

3.2.3 案例三：自定义清理步骤

在一些项目中，我们可能需要在清理过程中执行一些自定义的步骤。例如，我们可能

需要删除一些在构建过程中生成的临时文件。这种情况下，我们可以使用add_custom_command的BYPRODUCTS选项来实现。

假设我们在构建过程中生成了一些临时文件，我们可以使用如下的add_custom_command来在清理过程中删除这些文件：

add_custom_command(
  OUTPUT result.txt
  COMMAND generate_result --temp-file temp.txt result.txt
  BYPRODUCTS temp.txt
  COMMENT "Generating result and a temporary file..."
  VERBATIM
)

在这个例子中，OUTPUT选项指定了生成的文件，COMMAND选项指定了生成这个文件的命令，BYPRODUCTS选项指定了生成过程中的临时文件，COMMENT选项提供了一条在执行命令时打印的消息，VERBATIM选项保证了命令参数的字面意义。在清理过程中，temp.txt将会被删除。

以上就是add_custom_command在大型项目中的一些应用案例。通过这些案例，我们可以看到add_custom_command的强大和灵活，它可以帮助我们在构建过程中实现各种复杂的功能。

4. add_custom_command的高级应用

4.1 如何使用add_custom_command进行跨平台构建（How to Use add_custom_command for Cross-platform Build）

在现代的软件开发中，跨平台构建已经成为一种常态。CMake作为一种跨平台的构建工具，其强大的功能使得我们可以轻松地在不同的平台上进行构建。而add_custom_command命令则是我们实现跨平台构建的重要工具之一。

首先，我们需要理解的是，add_custom_command命令并不直接支持跨平台构建，但是它可以通过一些技巧来实现这一目标。具体来说，我们可以通过在COMMAND选项中使用不同的命令来实现在不同的平台上执行不同的操作。

例如，我们可以在Linux平台上使用shell命令，在Windows平台上使用cmd命令。这就需要我们在写CMake脚本时，对当前的操作系统进行判断，然后根据不同的操作系统，使用不同的命令。以下是一个简单的例子：

if(WIN32)
    add_custom_command(
        TARGET my_target
        POST_BUILD
        COMMAND cmd /c echo "This is Windows"
    )
elseif(UNIX)
    add_custom_command(
        TARGET my_target
        POST_BUILD
        COMMAND /bin/echo "This is Unix"
    )
endif()

在这个例子中，我们首先通过if命令判断当前的操作系统。如果是Windows，那么我们就使用cmd命令来输出一段信息；如果是Unix，那么我们就使用/bin/echo命令来输出一段信息。这样，我们就可以在不同的平台上执行不同的命令了。

但是，这种方法有一个问题，那就是我们需要为每一种可能的平台都写一段相应的代码。这不仅会使得我们的CMake脚本变得非常复杂，而且也会增加我们的工作量。因此，我们需要找到一种更好的方法来实现跨平台构建。

这就是CMake的生成器表达式（Generator Expressions）的用武之地。生成器表达式是CMake中的一种特殊语法，它允许我们在生成构建文件时，根据当前的环境进行动态的决策。通过使用生成器表达式，我们可以在一条add_custom_command命令中，同时处理多种不同的平台。

以下是一个使用生成器表达式的例子：

add_custom_command(
    TARGET my_target
    POST_BUILD
    COMMAND $<$<PLATFORM_ID:Windows>:cmd /c echo "This is Windows">
    COMMAND $<$<PLATFORM_ID:Linux>:/bin/echo "This is Linux">
)

在这个例子中，我们使用了两个生成器表达式。第一个生成器表达式 $<$ <PLATFORM_ID:Windows>:cmd /c echo “This is Windows”>会在当前的平台是

Windows时，执行cmd /c echo "This is Windows"命令；第二个生成器表达式 $<$ <PLATFORM_ID:Linux>:/bin/echo “This is Linux”>会在当前的平台是Linux时，执行/bin/echo "This is Linux"命令。这样，我们就可以在一条add_custom_command命令中，同时处理Windows和Linux两种平台了。

需要注意的是，生成器表达式在CMake脚本中的位置是有限制的。它只能在那些会在生成构建文件时进行解析的位置使用。这包括add_custom_command命令的COMMAND选项，以及一些其他的命令和选项。如果你在其他的位置使用生成器表达式，那么CMake可能会报错，或者不按照你的预期进行操作。

此外，生成器表达式的语法也是有一定的复杂性的。你需要花一些时间来熟悉和理解它。但是，一旦你掌握了生成器表达式，你就会发现它是一个非常强大的工具，可以帮助你更好地控制你的构建过程。

总的来说，add_custom_command命令是实现跨平台构建的一个重要工具。通过合理地使用COMMAND选项和生成器表达式，我们可以在不同的平台上执行不同的命令，从而实现真正的跨平台构建。

4.2 如何使用add_custom_command进行复杂的构建流程控制

在实际的软件开发过程中，我们可能会遇到一些复杂的构建需求，这时候我们就需要利用到add_custom_command的高级应用。下面我们将通过一个具体的例子来详细介绍如何使用add_custom_command进行复杂的构建流程控制。

假设我们有一个项目，项目中有一个源文件需要通过一个复杂的预处理步骤生成。这个预处理步骤包括：首先通过一个脚本将源文件转换为中间文件，然后再通过另一个脚本将中间文件转换为最终的源文件。这个过程可以通过add_custom_command来实现。

首先，我们需要定义一个add_custom_command，用于执行第一个脚本。这个add_custom_command的TARGET选项指定为中间文件，COMMAND选项指定为执行脚本的命令，DEPENDS选项指定为源文件。这样，当源文件被修改后，这个add_custom_command就会被执行，生成中间文件。

add_custom_command(
  OUTPUT intermediate_file
  COMMAND script1 source_file intermediate_file
  DEPENDS source_file
  COMMENT "Generating intermediate file from source file"
)

然后，我们再定义一个add_custom_command，用于执行第二个脚本。这个add_custom_command的TARGET选项指定为最终的源文件，COMMAND选项指定为执行脚本的命令，DEPENDS选项指定为中间文件。这样，当中间文件被修改后，这个add_custom_command就会被执行，生成最终的源文件。

add_custom_command(
  OUTPUT final_source_file
  COMMAND script2 intermediate_file final_source_file
  DEPENDS intermediate_file
  COMMENT "Generating final source file from intermediate file"
)

最后，我们需要在add_executable或者add_library命令中，将最终的源文件作为输入。这样，当我们执行构建命令时，CMake就会自动执行这两个add_custom_command，完成复杂的构建流程。

add_executable(my_program final_source_file other_source_files...)

以上就是如何使用add_custom_command进行复杂的构建流程控制的详细步骤。通过这个例子，我们可以看到，add_custom_command提供了非常强大的功能，可以帮助我们灵活地控制构建流程，满足各种复杂的构建需求。

5. add_custom_command的注意事项与最佳实践

5.1 add_custom_command的常见问题与解决方案（Common Problems and Solutions of add_custom_command）

在实际使用add_custom_command命令的过程中，我们可能会遇到一些问题。下面，我们将列举一些常见的问题，并提供相应的解决方案。

问题1：add_custom_command命令没有执行

这是使用add_custom_command时最常见的问题。你可能已经正确地设置了所有的参数，但是在构建过程中，你的自定义命令却没有被执行。

解决方案：首先，你需要确保你的目标（TARGET）是被构建的。如果你的目标没有被构建，那么与之相关的自定义命令也不会被执行。其次，你需要检查你的依赖（DEPENDS）。如果你的依赖没有被修改，那么自定义命令也不会被执行。最后，你需要检查你的命令（COMMAND）。如果你的命令无法正确执行，那么自定义命令也不会被执行。

问题2：add_custom_command命令的执行顺序不正确

在某些情况下，你可能需要控制自定义命令的执行顺序。然而，add_custom_command并不保证命令的执行顺序。

解决方案：你可以使用add_dependencies命令来控制自定义命令的执行顺序。这个命令可以让你指定一个或多个目标，这些目标必须在当前目标之前被构建。通过这种方式，你可以确保自定义命令的执行顺序。

问题3：add_custom_command命令的输出没有被正确处理

在使用add_custom_command时，你可能需要处理命令的输出。然而，add_custom_command并不直接支持这个功能。

解决方案：你可以使用OUTPUT选项来指定一个或多个输出文件。这些文件将会被添加到构建系统的输出列表中。然后，你可以使用其他的命令来处理这些输出文件。

以上就是在使用add_custom_command时可能遇到的一些问题，以及相应的解决方案。在实际使用中，你可能还会遇到其他的问题。这时，你可以参考CMake的官方文档，或者寻求社区的帮助。

5.2 add_custom_command的最佳实践（Best Practices of add_custom_command）

在实际的项目开发中，我们通常会遇到各种复杂的构建需求。这时，如何有效地使用add_custom_command命令就显得尤为重要。以下是一些关于add_custom_command的最佳实践，希望能帮助你更好地理解和使用这个命令。

5.2.1 明确命令的执行时机（Specify the Execution Timing of the Command）

在使用add_custom_command时，我们需要明确命令的执行时机。PRE_BUILD、PRE_LINK 和 POST_BUILD这三个选项可以帮助我们控制命令的执行时机。PRE_BUILD表示在其他所有步骤之前执行自定义命令，PRE_LINK表示在链接步骤之前执行自定义命令，POST_BUILD表示在所有步骤之后执行自定义命令。明确命令的执行时机，可以帮助我们更好地控制构建流程。

5.2.2 使用DEPENDS选项管理依赖（Use DEPENDS Option to Manage Dependencies）

DEPENDS选项可以帮助我们管理自定义命令的依赖。如果我们指定了一个或多个文件作为依赖，那么只有当这些文件被修改后，自定义命令才会被执行。这样，我们可以避免不必要的命令执行，提高构建效率。

5.2.3 使用VERBATIM选项控制命令参数的处理方式（Use VERBATIM Option to Control the Processing of Command Parameters）

在某些情况下，我们可能需要按照字面意义处理命令参数，而不是将其解析为变量或表达式。这时，我们可以使用VERBATIM选项。如果我们指定了VERBATIM，那么命令参数将会被按照字面意义处理。

5.2.4 使用COMMENT选项提供有用的信息（Use COMMENT Option to Provide Useful Information）

COMMENT选项可以帮助我们提供有用的信息。这个选项用于指定一个注释，这个注释将会在执行自定义命令时被打印出来。通过这个选项，我们可以为自定义命令提供一些有用的上下文信息，帮助我们更好地理解和调试构建过程。

以上就是关于add_custom_command的一些最佳实践。在实

际的项目开发中，我们需要根据具体的需求和环境，灵活地使用这些技巧和方法。同时，我们也需要不断地学习和实践，以提高我们使用CMake和add_custom_command的能力。

5.2.5 使用BYPRODUCTS选项管理副产品（Use BYPRODUCTS Option to Manage Byproducts）

在使用add_custom_command时，我们可能会生成一些副产品，例如临时文件、日志文件等。这些文件在构建过程中可能会被多次使用，但在构建完成后，我们可能就不再需要它们了。这时，我们可以使用BYPRODUCTS选项来管理这些副产品。如果我们指定了一个或多个文件作为副产品，那么这些文件将会被添加到构建系统的清理列表中。这样，我们就可以在构建完成后，自动清理这些不再需要的文件，从而节省磁盘空间。