💻 欢迎参加 6 月 3 日 MS Build 上的 VS Code 直播活动。

配置 C/C++ 调试

launch.json 文件用于在 Visual Studio Code 中配置调试器。

Visual Studio Code 会生成一个 launch.json（位于项目中的 .vscode 文件夹下），其中包含了几乎所有必需的信息。要开始调试，你需要填写 program 字段，指向你计划调试的可执行文件的路径。无论是“启动（launch）”还是“附加（attach）”（如果你打算在任何时候附加到正在运行的实例）配置，都必须指定此路径。

生成的文件包含两个部分，一部分用于配置“启动”调试，另一部分用于配置“附加”调试。

配置 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 上调试核心转储 (core dump) 文件。

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：符号服务器 URL（例如：https://msdl.microsoft.com/download/symbols）或目录（例如：/build/symbols）的数组，用于搜索 .pdb 文件。除了默认位置（模块旁边以及最初放置 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'。

6/10/2021
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.