Visual Studio Code

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

外部控制台

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

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

避免Windows控制台重定向

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

日志记录

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

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

可视化文件

.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
}

配置目标应用程序

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

参数

传递给程序启动时的命令行参数的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的行为：

MIMode

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

miDebuggerPath

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

miDebuggerArgs

传递给调试器的额外参数（例如gdb）。

stopAtEntry

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

stopAtConnect

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

设置命令

用于设置GDB或LLDB的JSON命令数组。示例："setupCommands": [ { "text": "target-run", "description": "运行目标", "ignoreFailures": false }]。

customLaunchSetupCommands

如果提供，这将替换用于启动目标的默认命令为其他命令。例如，这可以是“-target-attach”以附加到目标进程。空命令列表将启动命令替换为空，这在调试器通过命令行选项提供启动选项时非常有用。示例："customLaunchSetupCommands": [ { "text": "target-run", "description": "运行目标", "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。

服务器启动超时

调试器等待debugServer启动的时间，以毫秒为单位。默认值为10000。

管道传输

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

硬件断点

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

附加属性

processId

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

请求

指示配置部分是否用于launch程序或attach到已经运行的实例。

目标架构

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

类型

指示正在使用的基础调试器。使用Visual Studio Windows调试器时必须是cppvsdbg，使用GDB或LLDB时必须是cppdbg。当创建launch.json文件时，这将自动设置为正确的值。

源文件映射

这允许将编译时的源路径映射到本地源位置。它是一个键/值对的对象，并将解析第一个字符串匹配的路径。（例如："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