配置C/C++调试

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

Visual Studio Code 生成一个包含几乎所有必需信息的文件launch.json（.vscode在项目的文件夹下）。要开始调试，您需要在program字段中填写您计划调试的可执行文件的路径。必须为启动和附加（如果您计划在任何时候附加到正在运行的实例）配置指定此项。

生成的文件包含两部分，第一部分配置启动调试，第二部分配置附加调试。

配置 VS Code 的调试行为

设置或更改以下选项以控制调试期间 VS Code 的行为：

程序（必填）

指定调试器将启动或附加到的可执行文件的完整路径。调试器需要此位置才能加载调试符号。

符号搜索路径

告诉 Visual Studio Windows 调试器搜索符号 (.pdb) 文件的路径。用分号分隔多个路径。例如："C:\\Symbols;C:\\SymbolDir2".

要求精确源

一个可选标志，告诉 Visual Studio Windows 调试器要求当前源代码与 pdb 匹配。

附加 SOLibSearchPath

告诉 GDB 或 LLDB 搜索 .so 文件的路径。用分号分隔多个路径。例如："/Users/user/dir1;/Users/user/dir2".

外部控制台

仅在启动调试程序时使用。对于attach，此参数不会更改调试对象的行为。

  • Windows：当设置为 true 时，它​​将生成一个外部控制台。当设置为 false 时，它​​将使用 VS Code 的集成终端。
  • Linux：设置为 true 时，它​​将通知 VS Code 生成外部控制台。当设置为 false 时，它​​将使用 VS Code 的集成终端。
  • macOS：当设置为 true 时，它​​将通过lldb-mi. 当设置为 false 时，可以在 VS Code 的 debugConsole 中看到输出。由于 内的限制lldb-mi，集成终端支持不可用。

避免Windows控制台重定向

为了在 Windows 上支持 VS Code 的带有 gdb 的集成终端，该扩展将控制台重定向命令添加到调试对象的参数中，以使控制台输入和输出显示在集成终端中。将此选项设置为true将禁用它。

记录

用于确定应将哪些类型的消息记录到调试控制台的可选标志。

  • excepts：可选标志，用于确定是否应将异常消息记录到调试控制台。默认为 true。
  • moduleLoad：可选标志，用于确定是否应将模块加载事件记录到调试控制台。默认为 true。
  • programOutput：可选标志，用于确定程序输出是否应记录到调试控制台。默认为 true。
  • engineLogging：可选标志，用于确定是否应将诊断引擎日志记录到调试控制台。默认为 false。
  • trace：可选标志，用于确定是否应将诊断适配器命令跟踪记录到调试控制台。默认为 false。
  • traceResponse：可选标志，用于确定是否应将诊断适配器命令和响应跟踪记录到调试控制台。默认为 false。

可视化文件

.natvis调试时使用的文件。有关如何创建 Natvis 文件的信息，请参阅创建本机对象的自定义视图。

显示显示字符串

visualizerFile当指定a时，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
}

配置目标应用程序

以下选项使您能够在启动目标应用程序时修改目标应用程序的状态：

参数

启动程序时传递给程序的命令行参数的 JSON 数组。例子["arg1", "arg2"]。如果要转义字符，则需要对它们进行双重转义。例如，["{\\\"arg1\\\": true}"]将发送{"arg1": true}到您的应用程序。

西德

设置调试器启动的应用程序的工作目录。

环境

添加到程序环境的环境变量。示例：[ { "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 的行为：

MI模式

指示 VS Code 将连接到的调试器。必须设置为gdb或lldb。这是根据每个操作系统预先配置的，并且可以根据需要进行更改。

mi调试器路径

调试器（例如 gdb）的路径。当仅指定可执行文件时，它将在操作系统的 PATH 变量中搜索调试器（Linux 和 Windows 上的 GDB，OS X 上的 LLDB）。

miDebuggerArgs

要传递给调试器（例如 gdb）的其他参数。

进入时停止

如果设置为 true，调试器应在目标的入口点停止（在附加时忽略）。默认值为false。

连接时停止

如果设置为 true，调试器应在连接到目标后停止。如果设置为 false，调试器将在连接后继续。默认值为false。

设置命令

为了设置 GDB 或 LLDB 而要执行的 JSON 命令数组。示例："setupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }].

自定义启动设置命令

如果提供，这会将用于启动目标的默认命令替换为其他一些命令。例如，这可以是“-target-attach”以便附加到目标进程。空命令列表会替换任何内容的启动命令，如果将启动选项作为命令行选项提供给调试器，这会很有用。示例："customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }].

启动完整命令

调试器完全设置后要执行的命令，以使目标进程运行。允许的值为“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"
  }
}

符号加载信息

  • loadAll：如果为 true，则将加载所有库的符号，否则不会加载 solib 符号。由异常列表修改。默认值为 true。
  • exceptionList：以分号分隔的文件名列表（允许使用通配符）;。修改 LoadAll 的行为。如果 LoadAll 为 true，则不加载与列表中任何名称匹配的库的符号。否则，仅加载匹配的库的符号。例子："foo.so;bar.so"

调试转储文件

C/C++ 扩展允许调试 Windows 上的转储文件以及 Linux 和 OS X 上的核心转储文件。

转储路径

如果要调试 Windows 转储文件，请将其设置为转储文件的路径以在配置中开始调试launch。

核心转储路径

用于调试指定程序的核心转储文件的完整路径。将其设置为核心转储文件的路径以在launch配置中开始调试。 注意：MinGw 不支持核心转储调试。

远程调试或使用本地调试器服务器进行调试

mi调试器服务器地址

要连接以进行远程调试的调试器服务器（例如 gdbserver）的网络地址（例如：localhost:1234）。

调试服务器路径

要启动的调试服务器的完整路径。

调试服务器参数

调试器服务器的参数。

服务器已启动

在调试服务器输出中查找的服务器启动模式。支持正则表达式。

过滤标准输出

如果设置为 true，则stdout在流中搜索服务器启动模式并记录 stdout 以调试输出。默认值为true。

过滤器错误

如果设置为 true，则stderr在流中搜索服务器启动的模式并记录 stderr 以调试输出。默认值为false。

服务器启动超时

调试器等待调试服务器启动的时间（以毫秒为单位）。默认值为 10000。

管道运输

有关附加到远程进程（例如调试 Docker 容器中的进程）的信息，请参阅管道传输设置一文。

硬件断点

如果提供，这将显式控制远程目标的硬件断点行为。如果require设置为 true，则始终使用硬件断点。默认值为false。limit是对可用硬件断点数量的可选限制，仅当require为 true 且limit大于 0 时才强制执行。默认值为 0。示例："hardwareBreakpoints": { require: true, limit: 6 }。

附加属性

进程ID

默认情况下${command:pickProcess}将显示调试器可以附加到的可用进程的列表。我们建议您保留此默认值，但可以将该属性显式设置为调试器要附加到的特定进程 ID。

要求

指示配置节是用于launch程序还是attach已运行的实例。

目标架构

Deprecated由于会自动检测目标架构，因此不再需要此选项。

类型

指示正在使用的底层调试器。必须cppvsdbg在使用 Visual Studio Windows 调试器以及cppdbg使用 GDB 或 LLDB 时进行。launch.json创建文件时，该值会自动设置为正确的值 。

源文件映射

这允许将源的编译时路径映射到本地源位置。它是一个键/值对的对象，将解析第一个字符串匹配的路径。（示例："sourceFileMap": { "/mnt/c": "c:\\" }将映射调试器返回的以 开头的任何路径/mnt/c并将其转换为c:\\。您可以在对象中拥有多个映射，但它们将按照提供的顺序进行处理。）

环境变量定义文件

环境变量定义文件是一个简单的文本文件，包含 形式的键值对environment_variable=value，#用于注释。不支持多行值。

调试cppvsdbg器配置还包含一个envFile属性，允许您轻松设置变量以进行调试。

例如：

项目.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：如果将trueMicrosoft 符号服务器 (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”。

2021 年 6 月 10 日