Configure C/C++ debugging
launch.json 文件用于在 Visual Studio Code 中配置調試器。
Visual Studio Code 會生成一個 launch.json (位于項目的 .vscode 文件夾下),其中幾乎包含了所有必需的信息。要開始調試,您需要填寫 program 字段,指定要調試的可執行文件的路徑。這必須同時在 launch 和 attach (如果您計劃隨時附加到正在運行的實例)配置中指定。
生成的文件包含兩個部分,一個配置了 launch 調試,另一個配置了 attach 調試。
Configure VS Code’s debugging behavior
設置或更改以下選項以控制 VS Code 在調試期間的行為:
program (必填)
指定調試器將啟動或附加的可執行文件的完整路徑。調試器需要此位置來加載調試符號。
symbolSearchPath
告訴 Visual Studio Windows 調試器在哪里搜索符號 (.pdb) 文件。用分號分隔多個路徑。例如: “C:\Symbols;C:\SymbolDir2”。
requireExactSource
一個可選標志,告訴 Visual Studio Windows 調試器要求當前源代碼與 pdb 完全匹配。
additionalSOLibSearchPath
告訴 GDB 或 LLDB 搜索 .so 文件的路徑。用分號分隔多個路徑。例如: “/Users/user/dir1;/Users/user/dir2”。
externalConsole
僅在啟動被調試程序時使用。對于 attach,此參數不會改變被調試程序的行為。
- Windows: 設置為 true 時,它將生成一個外部控制臺。設置為 false 時,它將使用 VS Code 的 integratedTerminal。
- Linux: 設置為 true 時,它將通知 VS Code 生成一個外部控制臺。設置為 false 時,它將使用 VS Code 的 integratedTerminal。
- macOS: 設置為 true 時,它將通過 lldb-mi 生成一個外部控制臺。設置為 false 時,輸出可以在 VS Code 的 debugConsole 中查看。由于 lldb-mi 的限制,不支持 integratedTerminal。
avoidWindowsConsoleRedirection
為了支持在 Windows 上使用 gdb 的 VS Code 集成終端,該擴展會添加控制臺重定向命令到被調試程序的參數,以便將控制臺輸入和輸出顯示在集成終端中。將此選項設置為 true 將禁用它。
logging
確定應該將哪種類型的消息記錄到"調試控制臺"的可選標志。
- exceptions: 確定是否將異常消息記錄到"調試控制臺"的可選標志。默認為 true。
- moduleLoad: 確定是否將模塊加載事件記錄到"調試控制臺"的可選標志。默認為 true。
- programOutput: 確定是否將程序輸出記錄到"調試控制臺"的可選標志。默認為 true。
- engineLogging: 確定是否將診斷引擎日志記錄到"調試控制臺"的可選標志。默認為 false。
- trace: 確定是否將診斷適配器命令跟蹤記錄到"調試控制臺"的可選標志。默認為 false。
- traceResponse: 確定是否將診斷適配器命令和響應跟蹤記錄到"調試控制臺"的可選標志。默認為 false。
visualizerFile
在調試時使用的 .natvis 文件。有關如何創建 Natvis 文件的信息,請參見"創建本機對象的自定義視圖"。
showDisplayString
當指定了 visualizerFile 時,showDisplayString 將啟用顯示字符串。打開此選項可能會在調試期間導致性能下降。
Configure the target application
下面選項可以讓您在啟動目標應用程序時修改其狀態:
args
傳遞給程序的命令行參數的 JSON 數組。例如 [“arg1”, “arg2”]。如果需要轉義字符,則需要進行雙轉義。例如, [“{“arg1”: true}”] 將向應用程序發送 {“arg1”: true}。
cwd
設置調試器啟動的應用程序的工作目錄。
environment
要添加到程序環境中的環境變量。例如: [ { “name”: “config”, “value”: “Debug” } ], 而不是 [ { “config”: “Debug” } ]。
Customizing GDB or LLDB
以下是 GDB 或 LLDB 配置選項:
MIMode
指示 VS Code 將連接到的調試器。必須設置為 gdb 或 lldb。這是根據操作系統預先配置的,可以根據需要進行更改。
miDebuggerPath
調試器(如 gdb)的路徑。僅指定可執行文件時,它將搜索操作系統的 PATH 變量以找到調試器(Linux 和 Windows 上的 GDB,macOS 上的 LLDB)。
miDebuggerArgs
傳遞給調試器(如 gdb)的其他參數。
stopAtEntry
如果設置為 true,調試器應該在目標的入口點停止(在附加時忽略)。默認值為 false。
stopAtConnect
如果設置為 true,調試器應該在連接到目標后停止。如果設置為 false,調試器將在連接后繼續。默認值為 false。
setupCommands
要按順序執行以設置 GDB 或 LLDB 的 JSON 數組命令。例如: “setupCommands”: [ { “text”: “target-run”, “description”: “run target”, “ignoreFailures”: false }]。
customLaunchSetupCommands
如果提供,這將替換用于啟動目標的默認命令,改用其他命令。例如,這可以是 "-target-attach"以附加到目標進程。空命令列表用于替換啟動命令,這在調試器作為命令行選項提供時很有用。例如: “customLaunchSetupCommands”: [ { “text”: “target-run”, “description”: “run target”, “ignoreFailures”: false }]。
launchCompleteCommand
調試器完全設置好后要執行的命令,以使目標進程運行。允許的值為 “exec-run”、“exec-continue”、“None”。默認值為 “exec-run”。
關于 symbolLoadInfo 的選項:
symbolLoadInfo
loadAll: 如果設置為 true,則會加載所有庫的符號,否則不會加載任何動態共享庫的符號。可由 exceptionList 修改。默認值為 true。
exceptionList: 以分號 ; 分隔的文件名列表(支持通配符)。修改 LoadAll 的行為。如果 LoadAll 為 true,則不會加載與列表中任何名稱匹配的庫的符號。否則只會加載與列表匹配的庫的符號。例如: “foo.so;bar.so”
Debugging dump files
C/C++ 擴展程序支持在 Windows 上調試轉儲文件和在 Linux 和 macOS 上調試核心轉儲文件。
dumpPath
如果要調試 Windows 轉儲文件,請在啟動配置中將此設置為轉儲文件的路徑以開始調試。
coreDumpPath
要調試的程序的完整核心轉儲文件路徑。在啟動配置中設置此選項以開始調試核心轉儲。注意:MinGw 不支持核心轉儲調試。
Remote debugging or debugging with a local debugger server
遠程調試或使用本地調試器服務器進行調試的相關選項:
miDebuggerServerAddress
用于遠程調試的調試器服務器(如 gdbserver)的網絡地址(例如: localhost:1234)。
debugServerPath
調試服務器的完整路徑。
debugServerArgs
調試器服務器的參數。
serverStarted
在調試服務器輸出中搜索的服務器啟動模式。支持正則表達式。
filterStdout
如果設置為 true,則搜索標準輸出流以查找服務器啟動模式,并將標準輸出記錄到調試輸出。默認值為 true。
filterStderr
如果設置為 true,則搜索標準錯誤流以查找服務器啟動模式,并將標準錯誤記錄到調試輸出。默認值為 false。
serverLaunchTimeout
調試器等待調試服務器啟動的時間(以毫秒為單位)。默認值為 10000。
pipeTransport
有關附加到遠程進程(如在 Docker 容器中調試進程)的信息,請參閱 Pipe transport settings 文章。
hardwareBreakpoints
如果提供,這將明確控制遠程目標的硬件斷點行為。如果 require 設置為 true,則始終使用硬件斷點。默認值為 false。 limit 是在 require 為 true 且 limit 大于 0 時強制執行的可用硬件斷點數量的可選限制。默認值為 0。示例: “hardwareBreakpoints”: { require: true, limit: 6 }。
這些選項允許您配置遠程調試或使用本地調試器服務器進行調試的各種設置,以滿足不同的調試需求。
Additional properties
還有一些其他的屬性可以配置:
processId
默認值為 ${command:pickProcess},它將顯示調試器可以附加到的可用進程列表。我們建議您保留此默認值,但也可以將此屬性顯式設置為特定的進程 ID,以便調試器附加到該進程。
request
指示配置部分是打算啟動程序還是附加到正在運行的實例。
targetArchitecture
已棄用。此選項不再需要,因為目標體系結構會自動檢測。
type
指示正在使用的底層調試器。當使用 Visual Studio Windows 調試器時必須為 cppvsdbg,當使用 GDB 或 LLDB 時必須為 cppdbg。創建 launch.json 文件時會自動設置為正確的值。
sourceFileMap
這允許將源代碼的編譯時路徑映射到本地源代碼位置。它是一個鍵/值對對象,將解析第一個字符串匹配的路徑。(例如: “sourceFileMap”: { “/mnt/c”: “c:” } 將把調試器返回的任何以 /mnt/c 開頭的路徑映射到 c:\ 。您可以在對象中有多個映射,但它們將按照提供的順序處理。)
Environment variable definitions file
環境變量定義文件是一個簡單的文本文件,其中包含以 environment_variable=value 形式的鍵值對,使用 # 進行注釋。不支持多行值。
cppvsdbg 調試器配置還包含一個 envFile 屬性,允許您輕松地為調試目的設置變量。
例如:
project.env 文件:
Symbol Options
The symbolOptions element allows customization of how the debugger searches for symbols. Example:
Properties:
searchPaths: 這是一個數組,包含需要搜索 .pdb 文件的符號服務器 URL 或目錄。這些目錄會被搜索,除了默認位置(模塊旁邊和 pdb 最初被放置的路徑)。
searchMicrosoftSymbolServer: 如果設置為 true,則會將 Microsoft Symbol 服務器 (https://msdl.microsoft.com/download/symbols) 添加到符號搜索路徑。如果未指定,此選項默認為 false。
cachePath: 這是一個目錄,用于緩存從符號服務器下載的符號。如果未指定,調試器將默認使用 %TEMP%\SymbolCache。
moduleFilter.mode:
- “loadAllButExcluded”: 調試器會加載所有模塊的符號,除非該模塊在 ‘excludedModules’ 數組中。
- “loadOnlyIncluded”: 調試器不會嘗試加載任何模塊的符號,除非該模塊在 ‘includedModules’ 數組中,或通過 ‘includeSymbolsNextToModules’ 設置包含。
moduleFilter.excludedModules: 在 “loadAllButExcluded” 模式下,這是一個數組,包含調試器不應加載符號的模塊。支持通配符。
moduleFilter.includedModules: 在 “loadOnlyIncluded” 模式下,這是一個數組,包含調試器應加載符號的模塊。支持通配符。
moduleFilter.includeSymbolsNextToModules: 如果設置為 true,對于任何不在 ‘includedModules’ 數組中的模塊,調試器仍然會檢查該模塊本身和啟動可執行文件旁邊的位置,但不會檢查符號搜索列表上的路徑。默認為 true。