add_custom_target

新增一個沒有輸出的目標，使其永遠會被建置。

add_custom_target(Name [ALL] [command1 [args1...]]
                  [COMMAND command2 [args2...] ...]
                  [DEPENDS depend depend depend ...]
                  [BYPRODUCTS [files...]]
                  [WORKING_DIRECTORY dir]
                  [COMMENT comment]
                  [JOB_POOL job_pool]
                  [JOB_SERVER_AWARE <bool>]
                  [VERBATIM] [USES_TERMINAL]
                  [COMMAND_EXPAND_LISTS]
                  [SOURCES src1 [src2...]])

新增一個具有指定名稱的目標，該目標會執行指定的命令。此目標沒有輸出檔案，並且永遠被視為過時，即使命令嘗試建立一個與目標名稱相同的檔案。使用 add_custom_command() 命令來產生具有相依性的檔案。預設情況下，沒有任何東西依賴於自訂目標。使用 add_dependencies() 命令來新增與其他目標的相依性。

選項如下：

ALL

指示此目標應新增到預設建置目標中，以便每次都會執行它（命令不能被稱為 ALL）。

BYPRODUCTS

在版本 3.2 中新增。

指定命令預期產生的檔案，但這些檔案的修改時間在後續建置中可能會或可能不會更新。如果副產品名稱是相對路徑，它將相對於對應於當前原始碼目錄的建置樹目錄進行解釋。每個副產品檔案將自動標記 GENERATED 原始碼檔案屬性。

請參閱政策 CMP0058 以了解此功能背後的動機。

Ninja 產生器支援明確指定副產品，以告知 ninja 建置工具在副產品遺失時如何重新產生它們。當其他建置規則（例如，自訂命令）依賴於副產品時，這也很有用。Ninja 要求任何另一個規則依賴的產生檔案都必須有一個建置規則，即使只有順序相依性，以確保副產品在其依賴項建置之前可用。

Makefile 產生器 將在 make clean 期間移除 BYPRODUCTS 和其他 GENERATED 檔案。

在版本 3.20 中新增：BYPRODUCTS 的引數可以使用一組受限制的 產生器表達式。目標相依表達式 不允許使用。

在版本 3.28 中變更：在使用 檔案集合 的自訂目標中，副產品現在被視為私有的，除非它們在非私有的檔案集合中列出。請參閱政策 CMP0154。

COMMAND

指定在建置時要執行的命令列。如果指定多個 COMMAND，它們將按順序執行，但不一定組成一個有狀態的 shell 或批次指令碼。（要執行完整的指令碼，請使用 configure_file() 命令或 file(GENERATE) 命令來建立它，然後指定一個 COMMAND 來啟動它。）

如果 COMMAND 指定一個可執行目標名稱（由 add_executable() 命令建立），如果滿足以下任一條件，它將自動被建置時建立的可執行檔位置替換：

  • 目標未被交叉編譯（即 CMAKE_CROSSCOMPILING 變數未設定為 true）。

  • 在版本 3.6 中新增：目標正在被交叉編譯，並且提供了一個模擬器（即其 CROSSCOMPILING_EMULATOR 目標屬性已設定）。在這種情況下，CROSSCOMPILING_EMULATOR 的內容將被添加到命令的前面，在目標可執行檔的位置之前。

如果以上條件都不滿足，則假定命令名稱是在建置時在 PATH 上找到的程式。

COMMAND 的引數可以使用 產生器表達式。使用 TARGET_FILE 產生器表達式，在命令列的後面引用目標的位置（即作為命令引數，而不是作為要執行的命令）。

每當以下基於目標的產生器表達式之一用作要執行的命令或在命令引數中提到時，將自動添加目標級別的相依性，以便在建置此自訂目標之前建置提到的目標（請參閱政策 CMP0112）。

  • TARGET_FILE

  • TARGET_LINKER_FILE

  • TARGET_SONAME_FILE

  • TARGET_PDB_FILE

命令和引數是可選的，如果未指定，將建立一個空目標。

COMMENT

在建置時執行命令之前顯示給定的訊息。

在版本 3.26 中新增：COMMENT 的引數可以使用 產生器表達式。

DEPENDS

參考檔案和使用 add_custom_command() 命令呼叫在同一目錄（CMakeLists.txt 檔案）中建立的自訂命令的輸出。當建置目標時，它們將會更新。

在版本 3.16 中變更：如果任何相依性是同一目錄中目標或其任何建置事件的副產品，則會添加目標級別的相依性，以確保副產品在此目標建置之前可用。

使用 add_dependencies() 命令來新增對其他目標的相依性。

COMMAND_EXPAND_LISTS

在版本 3.8 中新增。

COMMAND 引數中的列表將被展開，包括使用 產生器表達式 建立的列表，允許 COMMAND 引數，例如 ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc 被正確展開。

JOB_POOL

在版本 3.15 中新增。

為 Ninja 產生器指定一個 pool。與 USES_TERMINAL 不相容，後者暗示 console pool。使用未由 JOB_POOLS 定義的 pool 會導致 ninja 在建置時發生錯誤。

JOB_SERVER_AWARE

在版本 3.28 中新增。

指定命令是 GNU Make job server 感知的。

對於 Unix Makefiles、MSYS Makefiles 和 MinGW Makefiles 產生器，這將在配方行前面新增 + 字首。有關更多資訊，請參閱 GNU Make 文件。

其他產生器會靜默忽略此選項。

SOURCES

指定要包含在自訂目標中的其他原始碼檔案。指定的原始碼檔案將新增到 IDE 專案檔案中，方便編輯，即使它們沒有建置規則。

VERBATIM

命令的所有引數都將為建置工具正確轉義，以便調用的命令接收每個未更改的引數。請注意，在 add_custom_target 甚至看到引數之前，CMake 語言處理器仍然使用一層轉義。VERBATIM 的使用是建議的，因為它可以實現正確的行為。當未給出 VERBATIM 時，行為是平台特定的，因為沒有針對工具特定特殊字元的保護。

USES_TERMINAL

在版本 3.2 中新增。

如果可能，命令將被授予直接訪問終端機的權限。使用 Ninja 產生器，這會將命令放置在 console pool 中。

WORKING_DIRECTORY

使用給定的當前工作目錄執行命令。如果它是相對路徑，它將相對於對應於當前原始碼目錄的建置樹目錄進行解釋。

在版本 3.13 中新增：WORKING_DIRECTORY 的引數可以使用 產生器表達式。

Ninja 多配置

在版本 3.20 中新增：add_custom_target 支援 Ninja 多配置 產生器的跨配置功能。有關更多資訊，請參閱產生器文件。

參見