配置 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

仅在启动 debuggee 时使用。对于 attach，此参数不会更改 debuggee 的行为。

• 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

为了支持 VS Code 在 Windows 上使用 gdb 的集成终端，扩展会将控制台重定向命令添加到 debuggee 的参数中，以使控制台输入和输出显示在集成终端中。将此选项设置为 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

要执行的命令的 JSON 数组，以便设置 GDB 或 LLDB。示例："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'。