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 <var>:<type>=<value>, -D <var>=<value>

建立或更新 CMake CACHE 項目。

當 CMake 首次在空的建置樹中執行時，它會建立一個 CMakeCache.txt 檔案，並使用專案的可自訂設定來填充它。此選項可用於指定一個優先於專案預設值的設定。此選項可以重複使用，以指定任意數量的 CACHE 項目。

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

此選項也可以作為單一參數給定：-D<var>:<type>=<value> 或 -D<var>=<value>。

請務必注意，-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 參數設定了相同的變數，則由於非 FORCE set(... CACHE ...) 呼叫的特性，-D 參數將優先，而無論順序如何。

-U <globbing_expr>

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

此選項可用於從 CMakeCache.txt 檔案中移除一個或多個變數，支援使用 * 和 ? 的 globbing 表達式。此選項可以重複使用，以指定任意數量的 CACHE 項目。

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

-G <generator-name>

指定一個建置系統產生器。

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

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

-T <toolset-spec>

如果支援，則為產生器指定工具鏈規範。

一些 CMake 產生器支援工具鏈規範，以告知原生建置系統如何選擇編譯器。有關詳細資訊，請參閱 CMAKE_GENERATOR_TOOLSET 變數。

-A <platform-name>

如果產生器支援，則指定平台名稱。

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

--toolchain <path-to-file>

在 3.21 版本中新增。

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

--install-prefix <directory>

在 3.21 版本中新增。

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

-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 使用 NEW 設定為政策 CMP0168 填充的相依性，它們先前執行的戳記和腳本檔案將會被移除。因此，將強制重新執行下載、更新和修補步驟。

-L[A][H]

列出非進階的快取變數。

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

-LR[A][H] <regex>

新增於版本 3.31。

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

顯示 CMake CACHE 中與給定的正規表示式匹配的非 INTERNAL 或 ADVANCED 變數。如果指定了 A，則也會顯示進階變數。如果指定了 H，則也會顯示每個變數的說明。

-N

僅檢視模式。

僅載入快取。實際上不執行配置和產生步驟。

--graphviz=<file>

產生依賴關係的 graphviz，請參閱 CMakeGraphVizOptions 以取得更多資訊。

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

--system-information [file]

傾印有關此系統的資訊。

傾印有關目前系統的各種資訊。如果從 CMake 專案的二元樹頂端執行，它將傾印額外的資訊，例如快取、記錄檔等。

--print-config-dir

新增於版本 3.31。

列印使用者範圍 FileAPI 查詢的 CMake 設定目錄。

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

--log-level=<level>

新增於版本 3.16。

設定記錄 <level>。

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。

--debug-trycompile

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

請注意，某些 try_compile() 的使用可能會使用相同的建置樹，如果專案執行多個 try_compile()，這將限制此選項的實用性。例如，這種使用可能會改變結果，因為先前嘗試編譯的成品可能會導致不同的測試不正確地通過或失敗。此選項最好僅在偵錯時使用。

（關於前面所述，try_run() 命令實際上是一個 try_compile()。這兩者的任何組合都可能出現所述的潛在問題。）

新增於版本 3.25：當啟用此選項時，每個嘗試編譯檢查都會列印一則記錄訊息，報告執行檢查的目錄。

--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

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

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，防止將警告視為編譯錯誤。

--profiling-output=<path>

在 3.18 版本中新增。

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

--profiling-format=<file>

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

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

目前支援的值為：google-trace 以 Google Trace 格式輸出，可以使用 Google Chrome 的 about:tracing 標籤或使用 Trace Compass 等工具的外掛程式來解析。

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

從 CMakePresets.json 和 CMakeUserPresets.json 檔案讀取 preset，這些檔案必須與頂層 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。目前的工作目錄必須包含 CMake 預設設定檔，除非使用 -S 選項來指定不同的頂層來源目錄。

--debugger

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

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 預設設定檔。有關更多詳細資訊，請參閱 preset。

--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。

使用指定數量的 jobs 平行安裝。僅在啟用 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 物件。鍵是

字串

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

major

主要版本號，為整數形式。

minor

次要版本號，為整數形式。

patch

修補程式層級，為整數形式。

suffix

cmake 版本後綴字串。

isDirty

一個布林值，如果 cmake 建置來自一個不乾淨的樹，則設定為 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

一個 JSON 陣列，包含零個或多個支援的 file-api 請求。每個請求都是一個 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 登錄值。

執行尋找套件工具

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

cmake --find-package [<options>]

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

注意

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

執行工作流程預設

在 3.25 版本中新增。

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

cmake --workflow <options>

選項如下：

--workflow

使用下列選項之一選取工作流程預設值。

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

使用工作流程預設值來指定工作流程。專案二進位目錄是從初始設定預設值推斷出來的。目前工作目錄必須包含 CMake 預設值檔案。如需詳細資訊，請參閱 預設值。

在 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>]

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

cmake-variables(7) 手冊中關於 <var> 的條目會以人類可讀的文字格式列印。如果提供命名 <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

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

論壇

https://discourse.cmake.org

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