設定 CMake 偵錯工作階段

發行項
11/21/2024

Visual Studio 2017 和更新版本提供原生 CMake 支援。若要查看這些版本的文件，請將本文的 Visual Studio 版本選取器控制項設定為 Visual Studio 2017 或更新版本。其位於此頁面目錄頂端。

工具列的 [啟動項目] 下拉式清單中會顯示所有可執行的 CMake 目標。選取一個以啟動偵錯會話並啟動調試程式。

CMake 啟動專案下拉式清單的螢幕快照。

您也可以從方案總管啟動偵錯會話。首先，切換至 [方案總管] 視窗中的 [CMake 目標檢視]。

CMake 目標檢視功能表的螢幕快照。

然後，以滑鼠右鍵按下可執行檔，然後選取 [ 偵錯]。此命令會根據您的使用中組態自動開始偵錯選取的目標。

CMake 目標檢視偵錯選項功能表的螢幕快照。

從 Visual Studio 2022 17.6 版開始，您也可以在 CMakeLists.txt 檔案上啟動偵錯會話。若要這樣做，只要在CMakeLists.txt檔案中設定斷點，然後從 [專案] 下拉式清單中執行 [使用 CMake 調試程式設定專案]。

CMake 除錯程式下拉式清單的螢幕快照。

自訂偵錯工具設定

您可以自定義專案中任何可執行 CMake 目標的除錯程式設定。在名為 launch.vs.json 的組態檔中找到，位於 .vs 專案根目錄中的資料夾。啟動組態檔在大部分偵錯案例中很有用，因為您可以設定及儲存偵錯設定詳細數據。此檔案有三個進入點：

偵錯功能表：從主功能表中選取 > [偵錯偵錯] 和 [啟動 ${activeDebugTarget} 的設定]，以自定義作用中偵錯目標特有的偵錯組態。如果您沒有選取偵錯目標，此選項會呈現灰色。

目標檢視：流覽至 方案總管中的目標檢視。然後，以滑鼠右鍵按下偵錯目標，然後選取 [新增偵錯組態 ] 來自定義所選目標特定的偵錯組態。

目標快捷方式選單上 [新增偵錯組態] 命令的螢幕快照。

根CMakeLists.txt：以滑鼠右鍵按兩下根CMakeLists.txt，然後選取 [新增偵錯組態] 以開啟 [選取調試程式] 對話框。對話框可讓您新增 任何類型的 偵錯組態，但您必須手動指定要透過 projectTarget 屬性叫用的 CMake 目標。

[選取除錯程式] 對話框的螢幕快照。

您可以編輯 launch.vs.json 檔案，為任意數目的 CMake 目標建立偵錯組態。當您儲存盤案時，Visual Studio 會在 [ 啟動專案] 下拉式清單中建立每個新組態的專案 。

CMakeSettings.json中的參考索引鍵

若要參考CMakeSettings.json檔案中的任何索引鍵，請在 launch.vs.json 前面加上cmake.它。下列範例顯示簡單的launch.vs.json檔案，該檔案會提取目前選取組態之CMakeSettings.json檔案中的索引鍵值remoteCopySources：

{
  "version": "0.2.1",
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "name": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "args": ["${cmake.remoteCopySources}"]
    }
  ]
}

CMakeSettings.json中定義的環境變數也可以使用語法 ${env.VARIABLE_NAME}在 launch.vs.json中使用。在 Visual Studio 2019 16.4 版和更新版本中，使用您在 CMakeSettings.json 中指定的環境自動啟動偵錯目標。您可以將環境變數設定為 null，以取消設定環境變數。

Launch.vs.json參考

有許多 launch.vs.json 屬性可支援所有偵錯案例。下列屬性適用於所有偵錯組態，包括遠端和本機：

projectTarget：指定要在建置專案時叫用的 CMake 目標。如果您從 [偵錯] 功能表或 [目標檢視] 輸入launch.vs.json，Visual Studio 就會自動填入此屬性。此值必須符合 [啟動專案] 下拉式清單中所列的現有偵錯目標名稱。

env：使用語法新增的其他環境變數：

"env": {
      "DEBUG_LOGGING_LEVEL": "trace;info",
      "ENABLE_TRACING": "true"
    }

args：傳遞至程式以偵錯的命令行自變數。

遠端專案和 WSL 的Launch.vs.json參考

在 Visual Studio 2019 16.6 版中，我們新增了的 type: cppgdb 偵錯組態，以簡化遠端系統和 WSL 上的偵錯。仍然支援的 type: cppdbg 舊偵錯組態。

組態類型 `cppgdb`

name：在 [啟動專案] 下拉式清單中識別組態的易記名稱。
project：指定項目檔的相對路徑。一般而言，偵錯 CMake 專案時不需要變更此路徑。
projectTarget：指定要在建置專案時叫用的 CMake 目標。如果您從 [偵錯] 功能表或 [目標檢視] 輸入launch.vs.json，Visual Studio 就會自動填入此屬性。此目標值必須符合 [啟動專案] 下拉式清單中所列的現有偵錯目標名稱。
debuggerConfiguration：表示要使用的偵錯預設值集。在 Visual Studio 2019 16.6 版中，唯一有效的選項是 gdb。 Visual Studio 2019 16.7 版或更新版本也支援 gdbserver。
args：在啟動時傳遞至偵錯程式的命令行自變數。
env：傳遞至正在偵錯之程式的其他環境變數。例如： {"DISPLAY": "0.0"} 。
processID：要附加的Linux進程標識碼。只有在附加至遠端進程時才會使用。如需詳細資訊，請參閱針對使用 GDB 附加至進程的疑難解答。

組 `gdb` 態的其他選項

program 預設為 "${debugInfo.fullTargetPath}"。要偵錯之應用程式的 Unix 路徑。只有在不同於組建或部署位置中目標可執行檔時才需要。
remoteMachineName 預設為 "${debugInfo.remoteMachineName}"。裝載程式要偵錯之遠端系統的名稱。只有在不同於建置系統時才需要。連線管理員中必須有現有的專案。按 Ctrl+空格 鍵以檢視所有現有遠端連線的清單。
cwd 預設為 "${debugInfo.defaultWorkingDirectory}"。執行所在遠端系統上 program 目錄的 Unix 路徑。目錄必須存在。
gdbpath 預設為 /usr/bin/gdb。用來偵 gdb 錯之的完整 Unix 路徑。只有在使用自訂版本的 gdb時才需要。
preDebugCommand：叫用之前 gdb要立即執行的Linux命令。 gdb 在命令完成之前，才會啟動。您可以使用選項執行之前 gdb執行文稿。

設定 `gdbserver` 允許的其他選項（16.7 或更新版本）

program 預設為 "${debugInfo.fullTargetPath}"。要偵錯之應用程式的 Unix 路徑。只有在不同於組建或部署位置中目標可執行檔時才需要。

提示

本機跨編譯案例尚不支援部署。如果您要在Windows上進行交叉編譯（例如，在 Windows 上使用跨編譯程式來建置 Linux ARM 可執行檔），則必須在偵錯之前，手動將二進位檔複製到遠端 ARM 計算機上所 program 指定的位置。
remoteMachineName 預設為 "${debugInfo.remoteMachineName}"。裝載程式要偵錯之遠端系統的名稱。只有在不同於建置系統時才需要。連線管理員中必須有現有的專案。按 Ctrl+空格 鍵以檢視所有現有遠端連線的清單。
cwd 預設為 "${debugInfo.defaultWorkingDirectory}"。執行所在遠端系統上 program 目錄的完整 Unix 路徑。目錄必須存在。
gdbPath 預設為 ${debugInfo.vsInstalledGdb}。用來偵錯之的完整 Windows 路徑 gdb 。預設為 gdb 使用 C/C++ 工作負載進行 Linux 開發的。
gdbserverPath 預設為 usr/bin/gdbserver。用來偵 gdbserver 錯之的完整 Unix 路徑。
preDebugCommand：啟動之前 gdbserver要立即執行的Linux命令。 gdbserver 在命令完成之前，才會啟動。

部署選項

使用下列選項，將組建計算機（CMakeSettings.json中定義）與遠端偵錯計算機分開。

remoteMachineName：遠端偵錯電腦。只有在不同於建置計算機時才需要。連線管理員中必須有現有的專案。按 Ctrl+空格 鍵以檢視所有現有遠端連線的清單。
disableDeploy 預設為 false。指出是否已停用建置/偵錯區隔。當時 false，此選項可讓建置和偵錯發生在兩個不同的計算機上。
deployDirectory：可執行檔複製到目錄的完整 Unix 路徑 remoteMachineName 。
deploy：進階部署設定的陣列。當您想要更細微地控制部署程式時，您只需要設定這些設定。根據預設，只有進程偵錯所需的檔案會部署到遠端偵錯計算機。
- sourceMachine：從中複製檔案或目錄的計算機。按 Ctrl+Space 以檢視儲存在連線管理員中的所有遠端連線清單。在 WSL 上原生建置時，會忽略此選項。
- targetMachine：複製檔案或目錄的計算機。按 Ctrl+Space 以檢視儲存在連線管理員中的所有遠端連線清單。
- sourcePath：上的 sourceMachine檔案或目錄位置。
- targetPath：上的 targetMachine檔案或目錄位置。
- deploymentType：部署類型的描述。 LocalRemote 支援與 RemoteRemote 。 LocalRemote表示從本機檔系統複製到 launch.vs.json 中指定的remoteMachineName遠端系統。 RemoteRemote表示從 CMakeSettings.json 中指定的遠端建置系統複製到launch.vs.json中指定的不同遠端系統。
- executable：指出已部署的檔案是否為可執行檔。

執行自定義 `gdb` 命令

Visual Studio 支援執行自定義 gdb 命令，以直接與基礎調試程序互動。如需詳細資訊，請參閱執行自定義 gdb lldb 命令。

啟用記錄

啟用MIEngine記錄以查看哪些命令會傳送至 gdb、輸出會傳回哪些命令 gdb ，以及每個命令所花費的時間長度。深入了解

組態類型 `cppdbg`

在遠端系統上偵錯時，可以使用下列選項，或使用組態類型進行 WSL cppdbg 偵錯。在 Visual Studio 2019 16.6 版或更新版本中，建議使用組態類型 cppgdb 。

name：在 [啟動專案] 下拉式清單中識別組態的易記名稱。
project：指定項目檔的相對路徑。通常，在偵錯 CMake 專案時您不需要變更此值。
projectTarget：指定要在建置專案時叫用的 CMake 目標。如果您從 [偵錯] 功能表或 [目標檢視] 輸入launch.vs.json，Visual Studio 就會自動填入此屬性。此值必須符合 [啟動專案] 下拉式清單中所列的現有偵錯目標名稱。
args：在啟動時傳遞至偵錯程式的命令行自變數。
processID：要附加的Linux進程標識碼。只有在附加至遠端進程時才會使用。如需詳細資訊，請參閱針對使用 GDB 附加至進程的疑難解答。
program 預設為 "${debugInfo.fullTargetPath}"。要偵錯之應用程式的 Unix 路徑。只有在不同於組建或部署位置中目標可執行檔時才需要。
remoteMachineName 預設為 "${debugInfo.remoteMachineName}"。裝載程式要偵錯之遠端系統的名稱。只有在不同於建置系統時才需要。連線管理員中必須有現有的專案。按 Ctrl+空格 鍵以檢視所有現有遠端連線的清單。
cwd 預設為 "${debugInfo.defaultWorkingDirectory}"。執行所在遠端系統上 program 目錄的完整 Unix 路徑。目錄必須存在。

environment：傳遞至正在偵錯之程式的其他環境變數。例如，

  "environment": [
      {
        "name": "ENV1",
        "value": "envvalue1"
      },
      {
        "name": "ENV2",
        "value": "envvalue2"
      }
    ]

pipeArgs：傳遞至管道程式以設定連線的命令行自變數數位。管線程式可用來轉譯 Visual Studio 與 gdb之間的標準輸入/輸出。偵錯 CMake 專案時，不需要自定義此陣列的大部分。例外狀況是在 ${debuggerCommand}遠端系統上啟動 gdb 的。它可以修改為：
- 匯出 Linux 系統上環境變數 DISPLAY 的值。在下列範例中，此值為 :1。
```
"pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "export DISPLAY=:1;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],
```
- 在執行之前 gdb執行腳本。請確定文稿上已設定執行許可權。
```
"pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "/path/to/script.sh;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],
```
stopOnEntry：布爾值，指定是否要在啟動進程時立即中斷。預設值為 false。
visualizerFile：偵錯此進程時要使用的 .natvis 檔案。此選項與 gdb 漂亮的列印不相容。當您設定這個屬性時，也會設定 showDisplayString 。
showDisplayString：布爾值，可在指定時 visualizerFile 啟用顯示字串。將此選項設定為 true 可能會導致偵錯期間的效能變慢。
setupCommands：要執行的一或多個 gdb 命令，以設定基礎調試程式。
miDebuggerPath：的完整路徑 gdb。未指定時，Visual Studio 會先搜尋PATH來尋找調試程式。
最後，針對 cppgdb 組態類型定義的所有部署選項也可以由 cppdbg 組態類型使用。

使用進行偵錯 `gdbserver`

您可以使用來設定組 cppdbg 態以偵 gdbserver錯。您可以在 Microsoft C++ Team 部落格文章使用偵錯 Linux CMake 專案gdbserver中找到更多詳細數據和範例啟動組態。

另請參閱

Visual Studio 中的 CMake 專案
 設定 Linux CMake 專案
 連線到遠端 Linux 電腦
 自訂 CMake 建置設定
 設定 CMake 偵錯工作階段
 部署、執行及偵錯 Linux 專案
 CMake 預先定義組態參考

共用方式為

設定 CMake 偵錯工作階段

自訂偵錯工具設定

CMakeSettings.json中的參考索引鍵

Launch.vs.json參考

遠端專案和 WSL 的Launch.vs.json參考

組態類型 `cppgdb`

組 `gdb` 態的其他選項

設定 `gdbserver` 允許的其他選項（16.7 或更新版本）

部署選項

執行自定義 `gdb` 命令

啟用記錄

組態類型 `cppdbg`

使用進行偵錯 `gdbserver`

另請參閱

意見反應

其他資源

共用方式為

設定 CMake 偵錯工作階段

自訂偵錯工具設定

CMakeSettings.json中的參考索引鍵

Launch.vs.json參考

遠端專案和 WSL 的Launch.vs.json參考

組態類型 cppgdb

組 gdb 態的其他選項

設定 gdbserver 允許的其他選項 （16.7 或更新版本）

部署選項

執行自定義 gdb 命令

啟用 記錄

組態類型 cppdbg

使用進行偵錯 gdbserver

另請參閱

意見反應

其他資源

組態類型 `cppgdb`

組 `gdb` 態的其他選項

設定 `gdbserver` 允許的其他選項（16.7 或更新版本）

執行自定義 `gdb` 命令

啟用記錄

組態類型 `cppdbg`

使用進行偵錯 `gdbserver`