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。