共用方式為

設定 CMake 偵錯工作階段

  • 發行項

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：用來偵錯的 gdb 的完整 Windows 路徑。

  • 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中找到更多詳細數據和範例啟動組態。