配置 C/C++ 调试
launch.json
文件用于在 Visual Studio Code 中配置调试器。
Visual Studio Code 会生成一个 launch.json
文件(位于项目中的 .vscode
文件夹下),其中包含几乎所有需要的信息。要开始调试,您需要将 program
字段填写为您计划调试的可执行文件的路径。无论是启动配置还是附加配置(如果您计划在任何时候附加到正在运行的实例),都必须指定此项。
生成的文件包含两个部分,一个用于配置启动调试,另一个用于配置附加调试。
配置 VS Code 的调试行为
设置或更改以下选项以控制 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 上支持 VS Code 的集成终端与 gdb,该扩展会将控制台重定向命令添加到被调试对象的参数中,以便在集成终端中显示控制台的输入和输出。将此选项设置为 true
将禁用此功能。
logging
可选标志,用于确定应将哪些类型的消息记录到调试控制台。
- exceptions:可选标志,用于确定是否应将异常消息记录到调试控制台。默认为 true。
- moduleLoad:可选标志,用于确定是否应将模块加载事件记录到调试控制台。默认为 true。
- programOutput:可选标志,用于确定是否应将程序输出记录到调试控制台。默认为 true。
- engineLogging:可选标志,用于确定是否应将诊断引擎日志记录到调试控制台。默认为 false。
- trace:可选标志,用于确定是否应将诊断适配器命令跟踪记录到调试控制台。默认为 false。
- traceResponse:可选标志,用于确定是否应将诊断适配器命令和响应跟踪记录到调试控制台。默认为 false。
visualizerFile
调试时使用的 .natvis
文件。有关如何创建 Natvis 文件的信息,请参阅创建原生对象的自定义视图。
showDisplayString
当指定 visualizerFile
时,showDisplayString
将启用显示字符串。开启此选项可能会导致调试期间性能下降。
示例
{
"name": "C++ Launch (Windows)",
"type": "cppvsdbg",
"request": "launch",
"program": "C:\\app1\\Debug\\app1.exe",
"symbolSearchPath": "C:\\Symbols;C:\\SymbolDir2",
"externalConsole": true,
"logging": {
"moduleLoad": false,
"trace": true
},
"visualizerFile": "${workspaceFolder}/my.natvis",
"showDisplayString": true
}
配置目标应用程序
以下选项允许您在启动目标应用程序时修改其状态。
args
在启动程序时传递给程序的命令行参数的 JSON 数组。例如 ["arg1", "arg2"]
。如果您要转义字符,则需要双重转义。例如,["{\\\"arg1\\\": true}"]
将向您的应用程序发送 {"arg1": true}
。
cwd
设置由调试器启动的应用程序的工作目录。
environment
要为程序添加到环境中的环境变量。示例:[ { "name": "config", "value": "Debug" } ]
,而不是 [ { "config": "Debug" } ]
。
示例
{
"name": "C++ Launch",
"type": "cppdbg",
"request": "launch",
"program": "${workspaceFolder}/a.out",
"args": ["arg1", "arg2"],
"environment": [{ "name": "config", "value": "Debug" }],
"cwd": "${workspaceFolder}"
}
自定义 GDB 或 LLDB
您可以通过设置以下选项来更改 GDB 或 LLDB 的行为。
MIMode
指示 VS Code 将连接到的调试器。必须设置为 gdb
或 lldb
。这是根据每个操作系统预先配置的,可以根据需要进行更改。
miDebuggerPath
调试器的路径(例如 gdb)。如果仅指定可执行文件,它将在操作系统的 PATH 变量中搜索调试器(Linux 和 Windows 上是 GDB,OS X 上是 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"。
示例
{
"name": "C++ Launch",
"type": "cppdbg",
"request": "launch",
"program": "${workspaceFolder}/a.out",
"stopAtEntry": false,
"customLaunchSetupCommands": [
{ "text": "target-run", "description": "run target", "ignoreFailures": false }
],
"launchCompleteCommand": "exec-run",
"linux": {
"MIMode": "gdb",
"miDebuggerPath": "/usr/bin/gdb"
},
"osx": {
"MIMode": "lldb"
},
"windows": {
"MIMode": "gdb",
"miDebuggerPath": "C:\\MinGw\\bin\\gdb.exe"
}
}
symbolLoadInfo
- loadAll:如果为 true,则会加载所有库的符号,否则不会加载任何 solib 符号。由 ExceptionList 修改。默认值为 true。
- exceptionList:用分号
;
分隔的文件名列表(允许使用通配符)。修改 LoadAll 的行为。如果 LoadAll 为 true,则不加载与列表中任何名称匹配的库的符号。否则,仅加载匹配的库的符号。示例:"foo.so;bar.so"
调试转储文件
C/C++ 扩展支持在 Windows 上调试转储文件,以及在 Linux 和 OS X 上调试核心转储文件。
dumpPath
如果要调试 Windows 转储文件,请在 launch
配置中将其设置为转储文件的路径以开始调试。
coreDumpPath
用于调试指定程序的核心转储文件的完整路径。在 launch
配置中将其设置为核心转储文件的路径以开始调试。注意:MinGw 不支持核心转储调试。
远程调试或使用本地调试器服务器进行调试
miDebuggerServerAddress
用于远程调试的调试器服务器(例如 gdbserver)的网络地址(例如:localhost:1234
)。
debugServerPath
要启动的调试服务器的完整路径。
debugServerArgs
调试器服务器的参数。
serverStarted
在调试服务器输出中要查找的服务器启动模式。支持正则表达式。
filterStdout
如果设置为 true,则在 stdout
流中搜索服务器启动模式,并将 stdout 记录到调试输出。默认值为 true
。
filterStderr
如果设置为 true,则在 stderr
流中搜索服务器启动模式,并将 stderr 记录到调试输出。默认值为 false
。
serverLaunchTimeout
调试器等待 debugServer 启动的时间(以毫秒为单位)。默认为 10000。
pipeTransport
有关附加到远程进程的信息(例如在 Docker 容器中调试进程),请参阅管道传输设置文章。
hardwareBreakpoints
如果提供,此选项将显式控制远程目标的硬件断点行为。如果 require
设置为 true,则始终使用硬件断点。默认值为 false
。limit
是可用硬件断点数量的可选限制,仅在 require
为 true 且 limit
大于 0 时强制执行。默认值为 0。示例:"hardwareBreakpoints": { require: true, limit: 6 }
。
其他属性
processId
默认为 ${command:pickProcess}
,它将显示调试器可以附加的可用进程列表。我们建议您保留此默认值,但该属性可以显式设置为调试器要附加的特定进程 ID。
request
指示配置部分是用于 launch
程序还是 attach
到已在运行的实例。
targetArchitecture
已弃用
此选项不再需要,因为目标体系结构是自动检测的。
type
指示正在使用的底层调试器。使用 Visual Studio Windows 调试器时必须为 cppvsdbg
,使用 GDB 或 LLDB 时必须为 cppdbg
。当创建 launch.json
文件时,此值会自动设置为正确的值。
sourceFileMap
这允许将源代码的编译时路径映射到本地源位置。它是一个键/值对的对象,并将解析第一个字符串匹配的路径。(例如:"sourceFileMap": { "/mnt/c": "c:\\" }
会将调试器返回的任何以 /mnt/c
开头的路径映射并转换为 c:\\
。您可以在对象中有多个映射,但它们将按提供的顺序处理。)
环境变量定义文件
环境变量定义文件是一个简单的文本文件,包含 environment_variable=value
形式的键值对,并使用 #
表示注释。不支持多行值。
cppvsdbg
调试器配置还包含一个 envFile
属性,允许您轻松地为调试目的设置变量。
例如
project.env 文件:
# project.env
# Example environment with key as 'MYENVRIONMENTPATH' and value as C:\\Users\\USERNAME\\Project
MYENVRIONMENTPATH=C:\\Users\\USERNAME\\Project
# Variables with spaces
SPACED_OUT_PATH="C:\\This Has Spaces\\Project"
符号选项
symbolOptions
元素允许自定义调试器搜索符号的方式。示例:
"symbolOptions": {
"searchPaths": [
"C:\\src\\MyOtherProject\\bin\\debug",
"https://my-companies-symbols-server"
],
"searchMicrosoftSymbolServer": true,
"cachePath": "%TEMP%\\symcache",
"moduleFilter": {
"mode": "loadAllButExcluded",
"excludedModules": [ "DoNotLookForThisOne*.dll" ]
}
}
属性
searchPaths:用于搜索 .pdb 文件的符号服务器 URL(例如:https://msdl.microsoft.com/download/symbols)或目录(例如:/build/symbols)的数组。除了默认位置(模块旁边和 pdb 最初放置的路径)之外,还将在这些目录中进行搜索。
searchMicrosoftSymbolServer:如果为 true
,则将 Microsoft 符号服务器 (https://msdl.microsoft.com/download/symbols) 添加到符号搜索路径中。如果未指定,此选项默认为 false
。
cachePath:应缓存从符号服务器下载的符号的目录。如果未指定,调试器将默认为 %TEMP%\SymbolCache。
moduleFilter.mode:此值为 "loadAllButExcluded"
或 "loadOnlyIncluded"
。在 "loadAllButExcluded"
模式下,调试器会加载所有模块的符号,除非该模块位于 'excludedModules' 数组中。在 "loadOnlyIncluded"
模式下,调试器不会尝试加载任何模块的符号,除非它位于 'includedModules' 数组中,或通过 'includeSymbolsNextToModules' 设置包含它。
"loadAllButExcluded"
模式的属性
moduleFilter.excludedModules:调试器不应加载符号的模块数组。支持通配符(例如:MyCompany.*.dll)。
"loadOnlyIncluded"
模式的属性
moduleFilter.includedModules:调试器应为其加载符号的模块数组。支持通配符(例如:MyCompany.*.dll)。
moduleFilter.includeSymbolsNextToModules:如果为 true,对于不在 'includedModules' 数组中的任何模块,调试器仍将检查模块本身和启动可执行文件旁边,但不会检查符号搜索列表中的路径。此选项默认为 'true'。