設定 CMake 偵錯工作階段

發行項
10/28/2023

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

所有可執行檔 CMake 目標都會顯示在 工具列的 [啟動專案 ] 下拉式清單中。選取一個以啟動偵錯會話並啟動偵錯工具。

Screenshot of the CMake startup items dropdown.

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

Screenshot of the CMake Targets View menu.

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

Screenshot of the CMake Targets View debug option menu.

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

Screenshot of the CMake Debugger dropdown.

自訂偵錯工具設定

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

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

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

Screenshot of the Add Debug Configuration command on the shortcut menu for the target.

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

Screenshot of the Select a debugger dialog box.

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

CMake 中的參考索引鍵設定.json

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

{
  "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}"]
    }
  ]
}

CMake 中定義的 環境變數 設定.json 也可以使用語法 ${env.VARIABLE_NAME} 在 launch.vs.json 中使用。在 Visual Studio 2019 16.4 版和更新版本中，偵錯目標會使用您在 CMake設定.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}" 。裝載程式要偵錯之遠端系統的名稱。只有在不同于建置系統時才需要。在連線ion Manager 中必須有現有的專案。按 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}" 。裝載程式要偵錯之遠端系統的名稱。只有在不同于建置系統時才需要。在連線ion Manager 中必須有現有的專案。按 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 在命令完成之前，才會啟動。

部署選項

使用下列選項，將組建電腦（定義于 CMake設定.json）與遠端偵錯電腦分開。

remoteMachineName：遠端偵錯電腦。只有在不同于建置電腦時才需要。在連線ion Manager 中必須有現有的專案。按 Ctrl+空格 鍵以檢視所有現有遠端連線的清單。
disableDeploy：預設為 false 。指出是否已停用建置/偵錯區隔。當時 false ，此選項可讓建置和偵錯發生在兩個不同的電腦上。
deployDirectory：可執行檔案複製到目錄的完整 Unix 路徑 remoteMachineName 。
deploy：進階部署設定的陣列。當您想要更細微地控制部署程式時，您只需要設定這些設定。根據預設，只有進程偵錯所需的檔案會部署到遠端偵錯電腦。
- sourceMachine：從中複製檔案或目錄的電腦。按 Ctrl+Space 以檢視儲存在連線ion Manager 中的所有遠端連線清單。在 WSL 上原生建置時，會忽略此選項。
- targetMachine：複製檔案或目錄的電腦。按 Ctrl+Space 以檢視儲存在連線ion Manager 中的所有遠端連線清單。
- sourcePath：上的 sourceMachine 檔案或目錄位置。
- targetPath：上的 targetMachine 檔案或目錄位置。
- deploymentType：部署類型的描述。 LocalRemote 支援和 RemoteRemote 。 LocalRemote表示從本機檔案系統複製到 launch.vs.json 中指定的 remoteMachineName 遠端系統。 RemoteRemote表示從 CMake設定.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}" 。裝載程式要偵錯之遠端系統的名稱。只有在不同于建置系統時才需要。在連線ion Manager 中必須有現有的專案。按 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++ 小組部落格文章使用偵錯 Linux CMake 專案 gdbserver 中找到更多詳細資料和範例啟動組態。

另請參閱

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

共用方式為

設定 CMake 偵錯工作階段

自訂偵錯工具設定

CMake 中的參考索引鍵設定.json

Launch.vs.json 參考

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

組態類型 `cppgdb`

組 `gdb` 態的其他選項

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

部署選項

執行自訂 `gdb` 命令

啟用記錄

組態類型 `cppdbg`

使用進行偵錯 `gdbserver`

另請參閱

意見反應

其他資源

共用方式為

設定 CMake 偵錯工作階段

自訂偵錯工具設定

CMake 中的參考索引鍵設定.json

Launch.vs.json 參考

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

組態類型 cppgdb

組 gdb 態的其他選項

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

部署選項

執行自訂 gdb 命令

啟用 記錄

組態類型 cppdbg

使用 進行偵錯 gdbserver

另請參閱

意見反應

其他資源

組態類型 `cppgdb`

組 `gdb` 態的其他選項

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

執行自訂 `gdb` 命令

啟用記錄

組態類型 `cppdbg`

使用進行偵錯 `gdbserver`