cmake(1)

概要

Generate a Project Buildsystem
 cmake [<options>] -B <path-to-build> [-S <path-to-source>]
 cmake [<options>] <path-to-source | path-to-existing-build>

Build a Project
 cmake --build <dir> [<options>] [-- <build-tool-options>]

Install a Project
 cmake --install <dir> [<options>]

Open a Project
 cmake --open <dir>

Run a Script
 cmake [-D <var>=<value>]... -P <cmake-script-file>

Run a Command-Line Tool
 cmake -E <command> [<options>]

Run the Find-Package Tool
 cmake --find-package [<options>]

Run a Workflow Preset
 cmake --workflow <options>

View Help
 cmake --help[-<topic>]

描述

cmake 執行檔是跨平台建置系統產生器 CMake 的命令列介面。 上述概要列出了工具可以執行的各種動作，如下節所述。

要使用 CMake 建置軟體專案，請產生專案建置系統。 您可以選擇性地使用 cmake 來建置專案、安裝專案，或直接執行對應的建置工具（例如 make）。 cmake 也可用於檢視說明。

其他動作旨在供軟體開發人員在其 CMake 語言 中編寫腳本以支援其建置時使用。

對於可以代替 cmake 使用的圖形使用者介面，請參閱 ccmake 和 cmake-gui。 對於 CMake 測試和封裝功能的命令列介面，請參閱 ctest 和 cpack。

有關 CMake 的更多資訊，另請參閱本手冊末尾的連結。

CMake 建置系統簡介

建置系統描述如何使用建置工具自動化流程，從專案的原始碼建置其可執行檔和函式庫。 例如，建置系統可以是與命令列 make 工具一起使用的 Makefile，或是整合開發環境 (IDE) 的專案檔。 為了避免維護多個此類建置系統，專案可以使用以 CMake 語言 撰寫的檔案，以抽象方式指定其建置系統。 CMake 從這些檔案中透過稱為產生器的後端，為每位使用者在本機產生偏好的建置系統。

若要使用 CMake 產生建置系統，必須選取以下項目

原始碼樹狀目錄

包含專案提供的原始碼檔案的頂層目錄。 專案使用 cmake-language(7) 手冊中描述的檔案，以 CMakeLists.txt 頂層檔案開頭，指定其建置系統。 這些檔案指定建置目標及其相依性，如 cmake-buildsystem(7) 手冊中所述。

建置樹狀目錄

將儲存建置系統檔案和建置輸出成品（例如，可執行檔和函式庫）的頂層目錄。 CMake 將寫入 CMakeCache.txt 檔案，以將目錄識別為建置樹狀目錄，並儲存持續資訊，例如建置系統組態選項。

為了維護原始碼樹狀目錄的原始狀態，請使用單獨的專用建置樹狀目錄執行外部來源建置。 也支援將建置樹狀目錄放置在與原始碼樹狀目錄相同目錄中的內部來源建置，但不建議使用。

產生器

這會選擇要產生的建置系統種類。 請參閱 cmake-generators(7) 手冊，以取得所有產生器的文件。 執行 cmake --help 以查看本機可用的產生器清單。 您可以選擇性地使用下方的 -G 選項來指定產生器，或直接接受 CMake 為目前平台選擇的預設產生器。

當使用 命令列建置工具產生器 之一時，CMake 預期編譯器工具鏈所需的環境已在 shell 中設定。 當使用 IDE 建置工具產生器 之一時，則不需要特定的環境。

產生專案建置系統

執行具有以下命令簽章之一的 CMake，以指定原始碼和建置樹狀目錄，並產生建置系統

cmake [<選項>] -B <建置路徑> [-S <原始碼路徑>]

在 3.13 版本中新增。

使用 <建置路徑> 作為建置樹狀目錄，並使用 <原始碼路徑> 作為原始碼樹狀目錄。 指定的路徑可以是絕對路徑或相對於目前工作目錄的路徑。 原始碼樹狀目錄必須包含 CMakeLists.txt 檔案。 如果建置樹狀目錄尚不存在，將會自動建立。 例如

$ cmake -S src -B build

cmake [<選項>] <原始碼路徑>

使用目前工作目錄作為建置樹狀目錄，並使用 <原始碼路徑> 作為原始碼樹狀目錄。 指定的路徑可以是絕對路徑或相對於目前工作目錄的路徑。 原始碼樹狀目錄必須包含 CMakeLists.txt 檔案，且不得包含 CMakeCache.txt 檔案，因為後者會識別現有的建置樹狀目錄。 例如

$ mkdir build ; cd build
$ cmake ../src

cmake [<選項>] <現有建置路徑>

使用 <現有建置路徑> 作為建置樹狀目錄，並從其 CMakeCache.txt 檔案載入原始碼樹狀目錄的路徑，該檔案必須已由先前執行的 CMake 產生。 指定的路徑可以是絕對路徑或相對於目前工作目錄的路徑。 例如

$ cd build
$ cmake .

在所有情況下，<選項> 可以是零個或多個下方的選項。

上述指定原始碼和建置樹狀目錄的樣式可以混合使用。 使用 -S 或 -B 指定的路徑分別始終分類為原始碼或建置樹狀目錄。 使用純引數指定的路徑會根據其內容和先前給定的路徑類型進行分類。 如果僅給定一種路徑類型，則目前工作目錄 (cwd) 將用於另一種路徑類型。 例如

命令列	原始碼目錄	建置目錄
cmake -B build	cwd	build
cmake -B build src	src	build
cmake -B build -S src	src	build
cmake src	src	cwd
cmake build （現有）	已載入	build
cmake -S src	src	cwd
cmake -S src build	src	build
cmake -S src -B build	src	build

變更於 3.23 版本：當指定多個原始碼路徑時，CMake 會發出警告。 這從未正式記錄或支援過，但舊版本意外地接受多個原始碼路徑，並使用最後指定的路徑。 避免傳遞多個原始碼路徑引數。

產生建置系統後，可以使用對應的原生建置工具來建置專案。 例如，在使用 Unix Makefiles 產生器之後，可以直接執行 make

$ make
$ make install

或者，可以使用 cmake 來建置專案，方法是自動選擇並叫用適當的原生建置工具。

選項

-S <原始碼路徑>

要建置的 CMake 專案根目錄路徑。

-B <建置路徑>

CMake 將用作建置目錄根目錄的路徑。

如果目錄尚不存在，CMake 將會建立它。

-C <初始快取>

預先載入腳本以填入快取。

當 CMake 首次在空的建置樹狀目錄中執行時，它會建立 CMakeCache.txt 檔案，並以專案的可自訂設定填入該檔案。 此選項可用於指定檔案，從該檔案載入快取項目，然後再第一次傳遞專案的 CMake 清單檔案。 載入的項目優先於專案的預設值。 給定的檔案應為包含 set() 命令的 CMake 腳本，該命令使用 CACHE 選項，而不是快取格式檔案。

腳本中對 CMAKE_SOURCE_DIR 和 CMAKE_BINARY_DIR 的參考會評估為頂層原始碼和建置樹狀目錄。

-D <變數>:<類型>=<值>, -D <變數>=<值>

建立或更新 CMake CACHE 項目。

當 CMake 首次在空的建置樹狀目錄中執行時，它會建立 CMakeCache.txt 檔案，並以專案的可自訂設定填入該檔案。 此選項可用於指定優先於專案預設值的設定。 可以重複此選項以設定所需數量的 CACHE 項目。

如果給定 :<類型> 部分，則它必須是 set() 命令文件中針對其 CACHE 簽章指定的類型之一。 如果省略 :<類型> 部分，則如果項目不存在且沒有已有的類型，則將建立沒有類型的項目。 如果專案中的命令將類型設定為 PATH 或 FILEPATH，則 <值> 將會轉換為絕對路徑。

此選項也可以作為單一引數給定：-D<變數>:<類型>=<值> 或 -D<變數>=<值>。

重要的是要注意 -C 和 -D 引數的順序非常重要。 它們將按照列出的順序執行，最後一個引數優先於先前的引數。 例如，如果您指定 -DCMAKE_BUILD_TYPE=Debug，然後指定一個 -C 引數，其中包含呼叫的檔案

set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE)

則 -C 引數將優先，且 CMAKE_BUILD_TYPE 將設定為 Release。 但是，如果 -D 引數在 -C 引數之後，則會將其設定為 Debug。

如果 -C 檔案中的 set(... CACHE ...) 呼叫未使用 FORCE，且 -D 引數設定了相同的變數，則 -D 引數將優先，而與順序無關，因為非 FORCE set(... CACHE ...) 呼叫的性質所致。

-U <globbing_expr>

從 CMake CACHE 中移除相符的項目。

此選項可用於從 CMakeCache.txt 檔案中移除一個或多個變數，支援使用 * 和 ? 的 globbing 運算式。 可以重複此選項以設定所需數量的 CACHE 項目。

請謹慎使用，您可能會使您的 CMakeCache.txt 無法運作。

-G <產生器名稱>

指定建置系統產生器。

CMake 可能在某些平台上支援多個原生建置系統。 產生器負責產生特定的建置系統。 可能的產生器名稱在 cmake-generators(7) 手冊中指定。

如果未指定，CMake 會檢查 CMAKE_GENERATOR 環境變數，否則會回復為內建的預設選取。

-T <工具集規格>

產生器的工具集規格（如果支援）。

某些 CMake 產生器支援工具集規格，以告知原生建置系統如何選擇編譯器。 請參閱 CMAKE_GENERATOR_TOOLSET 變數以取得詳細資訊。

-A <平台名稱>

指定平台名稱（如果產生器支援）。

某些 CMake 產生器支援提供給原生建置系統的平台名稱，以選擇編譯器或 SDK。 請參閱 CMAKE_GENERATOR_PLATFORM 變數以取得詳細資訊。

--toolchain <檔案路徑>

在 3.21 版本中新增。

指定交叉編譯工具鏈檔案，相當於設定 CMAKE_TOOLCHAIN_FILE 變數。 相對路徑會解譯為相對於建置目錄，如果找不到，則解譯為相對於原始碼目錄。

--install-prefix <目錄>

在 3.21 版本中新增。

指定安裝目錄，由 CMAKE_INSTALL_PREFIX 變數使用。 必須是絕對路徑。

--project-file <專案檔名>

在 4.0 版本中新增。

指定替代的專案檔名。

這決定了 CMake 在組態專案時處理的頂層檔案，以及 add_subdirectory() 處理的檔案。

預設情況下，這是 CMakeLists.txt。 如果設定為其他任何名稱，則每當在專案子目錄中找不到指定的檔案時，CMakeLists.txt 將會用作後備檔案。

注意

此功能旨在供開發人員在增量轉換期間暫時使用，而非用於發佈最終產品。 當專案檔案不是 CMakeLists.txt 時，CMake 始終會發出警告。

-Wno-dev

抑制開發人員警告。

抑制旨在給 CMakeLists.txt 檔案作者的警告。 預設情況下，這也會關閉棄用警告。

-Wdev

啟用開發人員警告。

啟用旨在給 CMakeLists.txt 檔案作者的警告。 預設情況下，這也會開啟棄用警告。

-Wdeprecated

啟用已棄用功能警告。

啟用旨在給 CMakeLists.txt 檔案作者的已棄用功能使用警告。

-Wno-deprecated

抑制已棄用功能警告。

抑制旨在給 CMakeLists.txt 檔案作者的已棄用功能使用警告。

-Werror=<what>

將 CMake 警告視為錯誤。 <what> 必須是下列其中一項

dev

將開發人員警告視為錯誤。

將旨在給 CMakeLists.txt 檔案作者的警告視為錯誤。 預設情況下，這也會將棄用警告視為錯誤。

deprecated

將已棄用的巨集和函式警告視為錯誤。

將旨在給 CMakeLists.txt 檔案作者的已棄用巨集和函式使用警告視為錯誤。

-Wno-error=<what>

不要將 CMake 警告視為錯誤。 <what> 必須是下列其中一項

dev

將旨在給 CMakeLists.txt 檔案作者的警告不視為錯誤。 預設情況下，這也會關閉將棄用警告視為錯誤。

deprecated

將旨在給 CMakeLists.txt 檔案作者的已棄用巨集和函式使用警告不視為錯誤。

--fresh

在 3.24 版本中新增。

對建置樹狀目錄執行全新組態。 這會移除任何現有的 CMakeCache.txt 檔案和相關聯的 CMakeFiles/ 目錄，並從頭開始重新建立它們。

變更於 3.30 版本：對於先前由 FetchContent 使用 CMP0168 政策的 NEW 設定填入的相依性，將會移除先前任何執行中的戳記和腳本檔案。 因此，下載、更新和修補步驟將會強制重新執行。

-L[A][H]

列出非進階快取變數。

列出 CACHE 變數將執行 CMake 並列出 CMake CACHE 中所有未標記為 INTERNAL 或 ADVANCED 的變數。 這將有效地顯示目前的 CMake 設定，然後可以使用 -D 選項變更這些設定。 變更某些變數可能會導致建立更多變數。 如果指定 A，則也會顯示進階變數。 如果指定 H，則也會顯示每個變數的說明。

-LR[A][H] <regex>

在 3.31 版本中新增。

顯示特定的非進階快取變數

顯示 CMake CACHE 中與給定 regex 相符的非 INTERNAL 且非 ADVANCED 變數。 如果指定 A，則也會顯示進階變數。 如果指定 H，則也會顯示每個變數的說明。

-N

僅檢視模式。

僅載入快取。 請勿實際執行組態和產生步驟。

--graphviz=<檔案>

產生相依性的 graphviz，請參閱 CMakeGraphVizOptions 以取得更多資訊。

產生 graphviz 輸入檔案，其中將包含專案中的所有函式庫和可執行檔相依性。 請參閱 CMakeGraphVizOptions 的文件以取得更多詳細資訊。

--system-information [檔案]

傾印有關此系統的資訊。

傾印有關目前系統的各種資訊。 如果從 CMake 專案的二進位樹狀目錄頂層執行，它將傾印其他資訊，例如快取、記錄檔等。

--print-config-dir

在 3.31 版本中新增。

列印使用者範圍 FileAPI 查詢的 CMake 組態目錄。

請參閱 CMAKE_CONFIG_DIR 以取得更多詳細資訊。

--log-level=<層級>

在 3.16 版本中新增。

設定記錄 <層級>。

message() 命令將僅輸出指定記錄層級或更高等級的訊息。 有效的記錄層級為 ERROR、WARNING、NOTICE、STATUS（預設）、VERBOSE、DEBUG 或 TRACE。

若要使記錄層級在 CMake 執行之間持續存在，請改為將 CMAKE_MESSAGE_LOG_LEVEL 設定為快取變數。 如果同時給定命令列選項和變數，則命令列選項優先。

基於回溯相容性原因，--loglevel 也被接受為此選項的同義詞。

在 3.25 版本中新增：請參閱 cmake_language() 命令，以取得查詢目前訊息記錄層級的方式。

--log-context

啟用 message() 命令，以輸出附加到每個訊息的內容。

此選項僅針對當前的 CMake 執行啟用顯示上下文。若要讓上下文顯示功能在所有後續的 CMake 執行中保持啟用，請將 CMAKE_MESSAGE_CONTEXT_SHOW 設定為快取變數。當指定此命令列選項時，CMAKE_MESSAGE_CONTEXT_SHOW 將被忽略。

--sarif-output=<path>

在 4.0 版本中新增。

啟用以 SARIF 格式記錄 CMake 產生的診斷訊息。

將診斷訊息寫入指定路徑的 SARIF 檔案。專案也可以將 CMAKE_EXPORT_SARIF 設定為 ON，以便為建置樹狀結構啟用此功能。

--debug-trycompile

不要刪除為 try_compile() / try_run() 呼叫所建立的檔案和目錄。這在偵錯失敗的檢查時很有用。

請注意，某些 try_compile() 的使用方式可能會使用相同的建置樹狀結構，如果專案執行多個 try_compile()，則會限制此選項的實用性。例如，這種使用方式可能會改變結果，因為先前 try-compile 的產物可能會導致不同的測試錯誤地通過或失敗。此選項最好僅在偵錯時使用。

（關於前述內容，try_run() 命令實際上是一個 try_compile()。兩者的任何組合都可能受到所述潛在問題的影響。）

版本 3.25 新增: 啟用此選項後，每次 try-compile 檢查都會印出記錄訊息，報告執行檢查的目錄。

--debug-output

將 cmake 設為偵錯模式。

在 cmake 執行期間印出額外資訊，例如帶有 message(SEND_ERROR) 呼叫的堆疊追蹤。

--debug-find

版本 3.17 新增。

將 cmake find 命令設為偵錯模式。

在 cmake 執行期間，將額外的 find 呼叫資訊印出到標準錯誤。輸出是為人類閱讀而設計，而不是為了剖析。另請參閱 CMAKE_FIND_DEBUG_MODE 變數，以偵錯專案的更局部部分。

--debug-find-pkg=<pkg>[,...]

版本 3.23 新增。

在 find_package(<pkg>) 的呼叫下執行時，將 cmake find 命令設為偵錯模式，其中 <pkg> 是給定的逗號分隔、大小寫敏感的套件名稱清單中的一個項目。

與 --debug-find 類似，但將範圍限制為指定的套件。

--debug-find-var=<var>[,...]

版本 3.23 新增。

當以 <var> 作為結果變數呼叫時，將 cmake find 命令設為偵錯模式，其中 <var> 是給定的逗號分隔清單中的一個項目。

與 --debug-find 類似，但將範圍限制為指定的變數名稱。

--trace

將 cmake 設為追蹤模式。

印出所有已進行呼叫及其來源的追蹤。

--trace-expand

將 cmake 設為追蹤模式。

與 --trace 類似，但會展開變數。

--trace-format=<format>

版本 3.17 新增。

將 cmake 設為追蹤模式，並設定追蹤輸出格式。

<format> 可以是以下值之一。

human

以人類可讀的格式印出每條追蹤行。這是預設格式。

json-v1

將每一行印出為單獨的 JSON 文件。每個文件都以換行符號 (\n) 分隔。保證 JSON 文件內部不會出現換行符號。

JSON 追蹤格式

{
  "file": "/full/path/to/the/CMake/file.txt",
  "line": 0,
  "cmd": "add_executable",
  "args": ["foo", "bar"],
  "time": 1579512535.9687231,
  "frame": 2,
  "global_frame": 4
}

成員為

file

呼叫函數的 CMake 原始檔的完整路徑。

line

file 中函數呼叫開始的行號。

line_end

如果函數呼叫跨越多行，則此欄位將設定為函數呼叫結束的行號。如果函數呼叫跨越單行，則此欄位將不會設定。此欄位在 json-v1 格式的次要版本 2 中新增。

defer

可選成員，當函數呼叫被 cmake_language(DEFER) 延遲時存在。如果存在，其值是一個字串，包含延遲的呼叫 <id>。

cmd

被呼叫的函數名稱。

args

所有函數參數的字串清單。

time

函數呼叫的時間戳記（自 epoch 以來的秒數）。

frame

在目前正在處理的 CMakeLists.txt 上下文中，被呼叫函數的堆疊框架深度。

global_frame

在追蹤中涉及的所有 CMakeLists.txt 檔案中，全域追蹤的被呼叫函數的堆疊框架深度。此欄位在 json-v1 格式的次要版本 2 中新增。

此外，第一個輸出的 JSON 文件包含目前主要和次要版本的 version 鍵

JSON 版本格式

{
  "version": {
    "major": 1,
    "minor": 2
  }
}

成員為

version

指示 JSON 格式的版本。版本具有遵循語意版本慣例的主要和次要組件。

--trace-source=<file>

將 cmake 設為追蹤模式，但僅輸出指定檔案的行。

允許多個選項。

--trace-redirect=<file>

將 cmake 設為追蹤模式，並將追蹤輸出重新導向到檔案而不是 stderr。

--warn-uninitialized

警告關於未初始化的值。

當使用未初始化的變數時，印出警告。

--warn-unused-vars

沒有作用。在 CMake 3.2 及更早版本中，這會啟用關於未使用變數的警告。在 CMake 3.3 到 3.18 版本中，此選項已損壞。在 CMake 3.19 及更高版本中，此選項已被移除。

--no-warn-unused-cli

不要警告關於命令列選項。

不要尋找在命令列上宣告但未使用的變數。

--check-system-vars

尋找系統檔案中變數使用上的問題。

通常，未使用和未初始化的變數僅在 CMAKE_SOURCE_DIR 和 CMAKE_BINARY_DIR 中搜尋。此旗標告訴 CMake 也警告其他檔案。

--compile-no-warning-as-error

在 3.24 版本中新增。

忽略目標屬性 COMPILE_WARNING_AS_ERROR 和變數 CMAKE_COMPILE_WARNING_AS_ERROR，防止將編譯警告視為錯誤。

--link-no-warning-as-error

在 4.0 版本中新增。

忽略目標屬性 LINK_WARNING_AS_ERROR 和變數 CMAKE_LINK_WARNING_AS_ERROR，防止將連結警告視為錯誤。

--profiling-output=<path>

版本 3.18 新增。

與 --profiling-format 結合使用，以輸出到給定的路徑。

--profiling-format=<file>

啟用以給定格式輸出 CMake 腳本的效能分析資料。

這可以幫助分析已執行的 CMake 腳本的效能。應使用第三方應用程式將輸出處理為人類可讀的格式。

目前支援的值為：google-trace 以 Google Trace Format 輸出，可由 Google Chrome 的 about:tracing 標籤或使用 Trace Compass 等工具的插件進行剖析。

--preset <preset>, --preset=<preset>

從 CMakePresets.json 和 CMakeUserPresets.json 檔案讀取 預設集，這些檔案必須與頂層 CMakeLists.txt 檔案位於相同的目錄中。預設集可以指定產生器、建置目錄、變數清單以及要傳遞給 CMake 的其他引數。CMakePresets.json 或 CMakeUserPresets.json 至少必須存在一個。CMake GUI 也識別並支援 CMakePresets.json 和 CMakeUserPresets.json 檔案。有關這些檔案的完整詳細資訊，請參閱 cmake-presets(7)。

預設集會在所有其他命令列選項之前讀取，儘管可以使用 -S 選項來指定包含 CMakePresets.json 和 CMakeUserPresets.json 檔案的原始碼目錄。如果未給定 -S，則目前的目錄會被假定為頂層原始碼目錄，並且必須包含預設集檔案。由選定的預設集指定的選項（變數、產生器等）都可以通過在命令列上手動指定來覆寫。例如，如果預設集將名為 MYVAR 的變數設定為 1，但使用者使用 -D 引數將其設定為 2，則優先使用值 2。

--list-presets[=<type>]

列出指定 <type> 的可用預設集。<type> 的有效值為 configure、build、test、package 或 all。如果省略 <type>，則假定為 configure。除非使用 -S 選項來指定不同的頂層原始碼目錄，否則目前的工作目錄必須包含 CMake 預設集檔案。

--debugger

啟用 CMake 語言的互動式偵錯。CMake 在由 --debugger-pipe 命名的管道上公開一個偵錯介面，該介面符合 Debug Adapter Protocol 規範，並具有以下修改。

initialize 回應包含一個名為 cmakeVersion 的額外欄位，該欄位指定正在偵錯的 CMake 版本。

偵錯器初始化回應

{
  "cmakeVersion": {
    "major": 3,
    "minor": 27,
    "patch": 0,
    "full": "3.27.0"
  }
}

成員為

major

一個整數，指定主要版本號。

minor

一個整數，指定次要版本號。

patch

一個整數，指定修補程式版本號。

full

一個字串，指定完整的 CMake 版本。

--debugger-pipe <pipe name>, --debugger-pipe=<pipe name>

用於偵錯器通訊的管道（在 Windows 上）或網域 socket（在 Unix 上）的名稱。

--debugger-dap-log <log path>, --debugger-dap-log=<log path>

將所有偵錯器通訊記錄到指定的檔案。

建置專案

CMake 提供命令列簽章來建置已產生的專案二元樹狀結構

cmake --build <dir>             [<options>] [-- <build-tool-options>]
cmake --build --preset <preset> [<options>] [-- <build-tool-options>]

這使用以下選項抽象化了原生建置工具的命令列介面

--build <dir>

要建置的專案二元目錄。這是必要的（除非指定了預設集）並且必須是第一個。

--preset <preset>, --preset=<preset>

使用建置預設集來指定建置選項。專案二元目錄從 configurePreset 鍵推斷而來。目前的工作目錄必須包含 CMake 預設集檔案。有關更多詳細資訊，請參閱 預設集。

--list-presets

列出可用的建置預設集。目前的工作目錄必須包含 CMake 預設集檔案。

-j [<jobs>], --parallel [<jobs>]

版本 3.12 新增。

建置時要使用的最大並行處理程序數。如果省略 <jobs>，則使用原生建置工具的預設數字。

如果設定了 CMAKE_BUILD_PARALLEL_LEVEL 環境變數，則在未給定此選項時，指定預設的並行層級。

某些原生建置工具始終以並行方式建置。<jobs> 值為 1 可用於限制為單個作業。

-t <tgt>..., --target <tgt>...

建置 <tgt> 而不是預設目標。可以給定多個目標，以空格分隔。

--config <cfg>

對於多配置工具，選擇配置 <cfg>。

--clean-first

先建置目標 clean，然後再建置。（若僅清理，請使用 --target clean。）

--resolve-package-references=<value>

版本 3.23 新增。

在建置之前，從外部套件管理器（例如 NuGet）解析遠端套件參考。當 <value> 設定為 on（預設值）時，將在建置目標之前還原套件。當 <value> 設定為 only 時，將還原套件，但不會執行任何建置。當 <value> 設定為 off 時，將不會還原任何套件。

如果目標未定義任何套件參考，則此選項不會執行任何操作。

此設定可以在建置預設集中指定（使用 resolvePackageReferences）。如果指定了此命令列選項，則會忽略預設集設定。

如果未提供命令列參數或預設集選項，則將評估環境特定的快取變數，以決定是否應執行套件還原。

當使用 Visual Studio 產生器時，套件參考使用 VS_PACKAGE_REFERENCES 屬性定義。套件參考使用 NuGet 還原。可以通過將 CMAKE_VS_NUGET_PACKAGE_RESTORE 變數設定為 OFF 來停用它。

--use-stderr

已忽略。行為在 CMake >= 3.0 中為預設行為。

-v, --verbose

啟用詳細輸出 - 如果支援 - 包括要執行的建置命令。

如果設定了 VERBOSE 環境變數或 CMAKE_VERBOSE_MAKEFILE 快取變數，則可以省略此選項。

--

將剩餘選項傳遞給原生工具。

執行 cmake --build，不帶選項以獲得快速說明。

安裝專案

CMake 提供命令列簽章來安裝已產生的專案二元樹狀結構

cmake --install <dir> [<options>]

這可以在建置專案後使用，以執行安裝，而無需使用產生的建置系統或原生建置工具。選項如下

--install <dir>

要安裝的專案二元目錄。這是必要的，並且必須是第一個。

--config <cfg>

對於多配置產生器，選擇配置 <cfg>。

--component <comp>

基於組件的安裝。僅安裝組件 <comp>。

--default-directory-permissions <permissions>

預設目錄安裝權限。格式為 <u=rwx,g=rx,o=rx> 的權限。

--prefix <prefix>

覆寫安裝前綴，CMAKE_INSTALL_PREFIX。

--strip

在安裝前剝離符號。

-v, --verbose

啟用詳細輸出。

如果設定了 VERBOSE 環境變數，則可以省略此選項。

-j <jobs>, --parallel <jobs>

在 3.31 版本中新增。

使用給定的作業數並行安裝。僅當啟用 INSTALL_PARALLEL 時可用。當未提供此選項時，CMAKE_INSTALL_PARALLEL_LEVEL 環境變數指定預設的並行層級。

執行 cmake --install，不帶選項以獲得快速說明。

開啟專案

cmake --open <dir>

在相關聯的應用程式中開啟產生的專案。這僅受某些產生器支援。

執行腳本

cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]

-D <var>=<value>

為腳本模式定義變數。

-P <cmake-script-file>

將給定的 cmake 檔案作為以 CMake 語言編寫的腳本處理。不執行配置或產生步驟，並且不會修改快取。如果使用 -D 定義變數，則必須在 -P 引數之前完成。

在 -- 之後的任何選項都不會被 CMake 剖析，但它們仍然包含在傳遞給腳本的 CMAKE_ARGV<n> 變數集中（包括 -- 本身）。

執行命令列工具

CMake 通過簽章提供內建的命令列工具

cmake -E <command> [<options>]

-E [help]

執行 cmake -E 或 cmake -E help 以獲得命令摘要。

可用的命令是

capabilities

版本 3.7 新增。

以 JSON 格式報告 cmake 功能。輸出是一個 JSON 物件，具有以下鍵

version

具有版本資訊的 JSON 物件。鍵為

string

cmake --version 顯示的完整版本字串。

major

主要版本號碼，以整數形式表示。

minor

次要版本號碼，以整數形式表示。

patch

修補程式層級，以整數形式表示。

suffix

cmake 版本字尾字串。

isDirty

一個布林值，如果 cmake 建置來自dirty tree，則設定為 true。

generators

可用產生器列表。每個產生器都是一個 JSON 物件，具有以下鍵

name

包含產生器名稱的字串。

toolsetSupport

如果產生器支援工具組，則為 true，否則為 false。

platformSupport

如果產生器支援平台，則為 true，否則為 false。

supportedPlatforms

在 3.21 版本中新增。

當產生器支援透過 CMAKE_GENERATOR_PLATFORM (-A ...) 指定平台時，可能存在的選用成員。值是已知支援的平台列表。

extraGenerators

包含所有與產生器相容的 額外產生器 的字串列表。

fileApi

當 cmake-file-api(7) 可用時存在的選用成員。值是一個具有一個成員的 JSON 物件

requests

包含零或多個支援的 file-api 請求的 JSON 陣列。每個請求都是一個具有成員的 JSON 物件

kind

指定支援的 物件種類 之一。

version

一個 JSON 陣列，其元素各自是一個 JSON 物件，包含指定非負整數版本組件的 major 和 minor 成員。

serverMode

如果 cmake 支援伺服器模式，則為 true，否則為 false。自 CMake 3.20 以來始終為 false。

tls

在版本 3.25 中新增。

如果啟用 TLS 支援，則為 true，否則為 false。

debugger

在版本 3.27 中新增。

如果支援 --debugger 模式，則為 true，否則為 false。

cat [--] <files>...

版本 3.18 新增。

串連檔案並列印到標準輸出。

--

在 3.24 版本中新增。

新增了對雙破折號引數 -- 的支援。cat 的這個基本實作不支援任何選項，因此使用以 - 開頭的選項將會導致錯誤。使用 -- 來指示選項的結束，以防檔案以 - 開頭。

版本 3.29 新增: cat 現在可以透過傳遞 - 引數來列印標準輸入。

chdir <dir> <cmd> [<arg>...]

變更目前的工作目錄並執行命令。

compare_files [--ignore-eol] <file1> <file2>

檢查 <file1> 是否與 <file2> 相同。如果檔案相同，則傳回 0，否則傳回 1。如果引數無效，則傳回 2。

--ignore-eol

在版本 3.14 中新增。

此選項表示逐行比較，並忽略 LF/CRLF 差異。

copy <file>... <destination>, copy -t <destination> <file>...

將檔案複製到 <destination> (檔案或目錄)。如果指定多個檔案，或者如果指定 -t，則 <destination> 必須是目錄並且必須存在。如果未指定 -t，則最後一個引數會被假定為 <destination>。不支援萬用字元。copy 會追蹤符號連結。這表示它不會複製符號連結，而是複製它們指向的檔案或目錄。

版本 3.5 新增: 支援多個輸入檔案。

版本 3.26 新增: 支援 -t 引數。

copy_directory <dir>... <destination>

將 <dir>... 目錄的內容複製到 <destination> 目錄。如果 <destination> 目錄不存在，則會建立它。copy_directory 會追蹤符號連結。

版本 3.5 新增: 支援多個輸入目錄。

版本 3.15 新增: 當來源目錄不存在時，此命令現在會失敗。先前，它會透過建立空的目標目錄而成功。

copy_directory_if_different <dir>... <destination>

在版本 3.26 中新增。

將 <dir>... 目錄的變更內容複製到 <destination> 目錄。如果 <destination> 目錄不存在，則會建立它。

copy_directory_if_different 會追蹤符號連結。當來源目錄不存在時，此命令會失敗。

copy_if_different <file>... <destination>

如果檔案已變更，則將檔案複製到 <destination> (檔案或目錄)。如果指定多個檔案，則 <destination> 必須是目錄並且必須存在。copy_if_different 會追蹤符號連結。

版本 3.5 新增: 支援多個輸入檔案。

create_symlink <old> <new>

建立一個名為 <new> 的符號連結，指向 <old>。

版本 3.13 新增: 支援在 Windows 上建立符號連結。

注意

將建立 <new> 符號連結的路徑必須事先存在。

create_hardlink <old> <new>

在版本 3.19 中新增。

建立一個名為 <new> 的硬連結，指向 <old>。

注意

將建立 <new> 硬連結的路徑必須事先存在。<old> 必須事先存在。

echo [<string>...]

將引數顯示為文字。

echo_append [<string>...]

將引數顯示為文字，但不換行。

env [<options>] [--] <command> [<arg>...]

在版本 3.1 中新增。

在修改後的環境中執行命令。選項包括

NAME=VALUE

將 NAME 的目前值取代為 VALUE。

--unset=NAME

取消設定 NAME 的目前值。

--modify ENVIRONMENT_MODIFICATION

在版本 3.25 中新增。

將單個 ENVIRONMENT_MODIFICATION 操作套用到修改後的環境。

NAME=VALUE 和 --unset=NAME 選項分別等效於 --modify NAME=set:VALUE 和 --modify NAME=unset:。請注意，--modify NAME=reset: 會將 NAME 重設為 cmake 啟動時的值 (或取消設定)，而不是最新的 NAME=VALUE 選項。

--

在 3.24 版本中新增。

新增了對雙破折號引數 -- 的支援。使用 -- 來停止解譯選項/環境變數，並將下一個引數視為命令，即使它以 - 開頭或包含 =。

environment

顯示目前的環境變數。

false

在 3.16 版本中新增。

不執行任何動作，並傳回結束代碼 1。

make_directory <dir>...

建立 <dir> 目錄。如有必要，也建立父目錄。如果目錄已存在，則會靜默忽略。

版本 3.5 新增: 支援多個輸入目錄。

md5sum <file>...

以 md5sum 相容格式建立檔案的 MD5 總和檢查碼

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

sha1sum <file>...

在版本 3.10 中新增。

以 sha1sum 相容格式建立檔案的 SHA1 總和檢查碼

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

sha224sum <file>...

在版本 3.10 中新增。

以 sha224sum 相容格式建立檔案的 SHA224 總和檢查碼

b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

sha256sum <file>...

在版本 3.10 中新增。

以 sha256sum 相容格式建立檔案的 SHA256 總和檢查碼

76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

sha384sum <file>...

在版本 3.10 中新增。

以 sha384sum 相容格式建立檔案的 SHA384 總和檢查碼

acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

sha512sum <file>...

在版本 3.10 中新增。

以 sha512sum 相容格式建立檔案的 SHA512 總和檢查碼

2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

remove [-f] <file>...

自版本 3.17 起已棄用。

移除檔案。計劃行為是，如果任何列出的檔案已經不存在，則命令會傳回非零結束代碼，但不會記錄任何訊息。-f 選項會變更行為，在這種情況下傳回零結束代碼 (即成功)。remove 不會追蹤符號連結。這表示它只會移除符號連結，而不會移除它們指向的檔案。

此實作有錯誤，且始終傳回 0。如果不破壞回溯相容性，則無法修正。請改用 rm。

remove_directory <dir>...

自版本 3.17 起已棄用。

移除 <dir> 目錄及其內容。如果目錄不存在，則會靜默忽略。請改用 rm。

版本 3.15 新增: 支援多個目錄。

版本 3.16 新增: 如果 <dir> 是目錄的符號連結，則只會移除符號連結。

rename <oldname> <newname>

重新命名檔案或目錄 (在一個磁碟區上)。如果具有 <newname> 名稱的檔案已存在，則會靜默取代。

rm [-rRf] [--] <file|dir>...

版本 3.17 新增。

移除檔案 <file> 或目錄 <dir>。使用 -r 或 -R 以遞迴方式移除目錄及其內容。如果任何列出的檔案/目錄不存在，則命令會傳回非零結束代碼，但不會記錄任何訊息。-f 選項會變更行為，在這種情況下傳回零結束代碼 (即成功)。使用 -- 來停止解譯選項，並將所有剩餘的引數視為路徑，即使它們以 - 開頭。

sleep <number>

在版本 3.0 中新增。

睡眠 <number> 秒。<number> 可以是浮點數。由於啟動/停止 CMake 可執行檔的額外負荷，實際最小值約為 0.1 秒。這在 CMake 腳本中插入延遲時很有用

# Sleep for about 0.5 seconds
execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5)

tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]

建立或解壓縮 tar 或 zip 封存檔。選項包括

c

建立一個包含指定檔案的新封存檔。如果使用，則 <pathname>... 引數是強制性的。

x

從封存檔解壓縮到磁碟。

版本 3.15 新增: <pathname>... 引數可用於僅解壓縮選定的檔案或目錄。在解壓縮選定的檔案或目錄時，您必須提供它們的確切名稱，包括路徑，如 list (-t) 所列印的。

t

列出封存檔內容。

版本 3.15 新增: <pathname>... 引數可用於僅列出選定的檔案或目錄。

v

產生詳細輸出。

z

使用 gzip 壓縮產生的封存檔。

j

使用 bzip2 壓縮產生的封存檔。

J

在版本 3.1 中新增。

使用 XZ 壓縮產生的封存檔。

--zstd

在版本 3.15 中新增。

使用 Zstandard 壓縮產生的封存檔。

--files-from=<file>

在版本 3.1 中新增。

從給定檔案中讀取檔名，每行一個。空白行會被忽略。行不能以 - 開頭，但 --add-file=<name> 除外，用於新增名稱以 - 開頭的檔案。

--format=<format>

在版本 3.3 中新增。

指定要建立的封存檔格式。支援的格式包括: 7zip、gnutar、pax、paxr (受限 pax，預設) 和 zip。

--mtime=<date>

在版本 3.1 中新增。

指定記錄在 tarball 條目中的修改時間。

--touch

在 3.24 版本中新增。

使用目前的本機時間戳記，而不是從封存檔中解壓縮檔案時間戳記。

--

在版本 3.1 中新增。

停止解譯選項，並將所有剩餘的引數視為檔名，即使它們以 - 開頭。

版本 3.1 新增: LZMA (7zip) 支援。

版本 3.15 新增: 即使某些檔案無法讀取，此命令現在也會繼續將檔案新增到封存檔。此行為更符合經典的 tar 工具。此命令現在也會剖析所有旗標，如果提供了無效的旗標，則會發出警告。

time <command> [<args>...]

執行 <command> 並顯示經過的時間 (包括 CMake 前端的額外負荷)。

版本 3.5 新增: 此命令現在可以正確地將帶有空格或特殊字元的引數傳遞到子程序。這可能會破壞使用自己的額外引號或跳脫字元來解決錯誤的腳本。

touch <file>...

如果檔案不存在，則建立 <file>。如果 <file> 存在，則會變更 <file> 的存取和修改時間。

touch_nocreate <file>...

如果檔案存在，則更新檔案的時間戳記，但不建立檔案。如果檔案不存在，則會靜默忽略。

true

在 3.16 版本中新增。

不執行任何動作，並傳回結束代碼 0。

Windows 專用命令列工具

以下 cmake -E 命令僅在 Windows 上可用

delete_regv <key>

刪除 Windows 登錄值。

env_vs8_wince <sdkname>

在版本 3.2 中新增。

顯示一個批次檔，該檔案設定 VS2005 中安裝的提供的 Windows CE SDK 的環境。

env_vs9_wince <sdkname>

在版本 3.2 中新增。

顯示一個批次檔，該檔案設定 VS2008 中安裝的提供的 Windows CE SDK 的環境。

write_regv <key> <value>

寫入 Windows 登錄值。

執行 Find-Package 工具

CMake 為基於 Makefile 的專案提供了一個類似 pkg-config 的輔助工具

cmake --find-package [<options>]

它使用 find_package() 搜尋套件，並將產生的旗標列印到 stdout。這可以用來代替 pkg-config，以在純粹基於 Makefile 的專案或基於 autoconf 的專案 (透過 share/aclocal/cmake.m4) 中尋找已安裝的程式庫。

注意

由於一些技術限制，此模式未獲得良好支援。它被保留以實現相容性，但不應在新專案中使用。

執行工作流程預設集

在版本 3.25 中新增。

CMake 預設集 提供了一種依序執行多個建置步驟的方法

cmake --workflow <options>

選項包括

--workflow

使用以下選項之一選取 工作流程預設集。

--preset <preset>, --preset=<preset>

使用工作流程預設集來指定工作流程。專案二進制目錄會從初始設定預設集中推斷而來。目前的工作目錄必須包含 CMake 預設集檔案。請參閱 preset 以取得更多詳細資訊。

變更於版本 3.31: 當緊接在 --workflow 選項之後時，可以省略 --preset 引數，而僅給定 <preset> 名稱。這表示以下語法有效

$ cmake --workflow my-preset

--list-presets

列出可用的工作流程預設集。目前的工作目錄必須包含 CMake 預設集檔案。

--fresh

執行組建樹狀結構的全新設定，其效果與 cmake --fresh 相同。

檢視說明

若要從 CMake 文件中列印選定的頁面，請使用

cmake --help[-<topic>]

搭配以下選項之一

-version [<file>], --version [<file>], /V [<file>]

顯示程式名稱/版本橫幅並結束。如果指定了具名的 <file>，則輸出會列印到該檔案。

-h, -H, --help, -help, -usage, /?

列印用法資訊並結束。

用法描述基本命令列介面及其選項。

--help <keyword> [<file>]

列印一個 CMake 關鍵字的說明。

<keyword> 可以是屬性、變數、命令、策略、產生器或模組。

以人類可讀的文字格式列印 <keyword> 的相關手冊條目。如果指定了具名的 <file>，則輸出會列印到該檔案。

變更於版本 3.28: 在 CMake 3.28 之前，此選項僅支援命令名稱。

--help-full [<file>]

列印所有說明手冊並結束。

所有手冊都以人類可讀的文字格式列印。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-manual <man> [<file>]

列印一本說明手冊並結束。

指定的手冊以人類可讀的文字格式列印。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-manual-list [<file>]

列出可用的說明手冊並結束。

此清單包含所有可使用 --help-manual 選項後接手冊名稱來取得說明的手冊。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-command <cmd> [<file>]

列印一個命令的說明並結束。

以人類可讀的文字格式列印 <cmd> 的 cmake-commands(7) 手冊條目。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-command-list [<file>]

列出提供說明的命令並結束。

此清單包含所有可使用 --help-command 選項後接命令名稱來取得說明的命令。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-commands [<file>]

列印 cmake-commands 手冊並結束。

以人類可讀的文字格式列印 cmake-commands(7) 手冊。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-module <mod> [<file>]

列印一個模組的說明並結束。

以人類可讀的文字格式列印 <mod> 的 cmake-modules(7) 手冊條目。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-module-list [<file>]

列出提供說明的模組並結束。

此清單包含所有可使用 --help-module 選項後接模組名稱來取得說明的模組。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-modules [<file>]

列印 cmake-modules 手冊並結束。

以人類可讀的文字格式列印 cmake-modules(7) 手冊。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-policy <cmp> [<file>]

列印一個策略的說明並結束。

以人類可讀的文字格式列印 <cmp> 的 cmake-policies(7) 手冊條目。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-policy-list [<file>]

列出提供說明的策略並結束。

此清單包含所有可使用 --help-policy 選項後接策略名稱來取得說明的策略。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-policies [<file>]

列印 cmake-policies 手冊並結束。

以人類可讀的文字格式列印 cmake-policies(7) 手冊。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-property <prop> [<file>]

列印一個屬性的說明並結束。

以人類可讀的文字格式列印 <prop> 的 cmake-properties(7) 手冊條目。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-property-list [<file>]

列出提供說明的屬性並結束。

此清單包含所有可使用 --help-property 選項後接屬性名稱來取得說明的屬性。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-properties [<file>]

列印 cmake-properties 手冊並結束。

以人類可讀的文字格式列印 cmake-properties(7) 手冊。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-variable <var> [<file>]

列印一個變數的說明並結束。

以人類可讀的文字格式列印 <var> 的 cmake-variables(7) 手冊條目。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-variable-list [<file>]

列出提供說明的變數並結束。

此清單包含所有可使用 --help-variable 選項後接變數名稱來取得說明的變數。如果指定了具名的 <file>，則輸出會列印到該檔案。

--help-variables [<file>]

列印 cmake-variables 手冊並結束。

以人類可讀的文字格式列印 cmake-variables(7) 手冊。如果指定了具名的 <file>，則輸出會列印到該檔案。

若要檢視專案可用的預設集，請使用

cmake <source-dir> --list-presets

傳回值（結束代碼）

在正常終止時，cmake 可執行檔會傳回結束代碼 0。

如果終止是由命令 message(FATAL_ERROR) 或其他錯誤狀況所造成，則會傳回非零的結束代碼。

參見

以下資源可用於取得使用 CMake 的說明

首頁

https://cmake.dev.org.tw

學習 CMake 的主要起點。

線上文件和社群資源

https://cmake.dev.org.tw/documentation

可在此網頁上找到可用文件和社群資源的連結。

Discourse 論壇

https://discourse.cmake.org

Discourse 論壇託管關於 CMake 的討論和問題。