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 產生器指定一個 池。與 USES_TERMINAL 不相容，後者表示 console 池。使用未由 JOB_POOLS 定義的池會在建置時導致 Ninja 錯誤。

JOB_SERVER_AWARE

在版本 3.28 中新增。

指定命令是 GNU Make 工作伺服器感知的。

對於 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 多配置 產生器的跨配置功能。請參閱產生器文件以獲取更多資訊。

參見