launch.vs.json 架构参考 (C++)

在 Visual Studio 2017 及更高版本中,你可以打开几乎任何基于目录的项目的代码,而无需创建解决方案或者项目文件。 如果没有项目或解决方案文件,则可指定自定义生成任务并通过 JSON 配置文件启动参数。 本文介绍 launch.vs.json 文件,该文件指定调试参数。 有关“打开文件夹”功能的更多信息,请参阅在 Visual Studio 中开发代码而无需创建项目或解决方案

要创建文件,请在“解决方案资源管理器”中右键单击可执行文件,然后选择“调试和启动设置”。 选择与项目最匹配的选项,然后根据需要使用以下属性修改配置。 有关调试 CMake 项目的详细信息,请参阅配置 CMake 调试会话

默认属性

properties 类型​​ 说明
args array 指定传递给已启动程序的命令行参数。
buildConfigurations 数组 一个键值对,指定要应用配置的生成模式的名称。 例如,DebugRelease,且要使用的配置根据所选生成模式确定。
currentDir string 指定生成目标的完整目录路径。 除非设置了此参数,否则会自动检测到此目录。
cwd string 远程系统上将运行程序的目录的完整路径。 默认为 "${debugInfo.defaultWorkingDirectory}"
debugType string 根据代码类型指定调试模式(本机、托管或混合)。 除非设置了此参数,否则会自动检测到此模式。 允许的值:"native""managed""mixed"
env array 指定自定义环境变量的键值列表。 例如:env:{"myEnv":"myVal"}
inheritEnvironments array 指定从多个源继承的一组环境变量。 可以在 CMakeSettings.jsonCppProperties.json 等文件中定义一些变量,并使它们可用于调试上下文。 Visual Studio 16.4:使用 env.VARIABLE_NAME 语法根据每个目标指定环境变量。 若要取消设置某个变量,请将它设置为 "null"
name string 指定“启动项”下拉列表中条目的名称
noDebug boolean 指定是否调试已启动程序。 如果没有指定,则此参数的默认值为 false
portName string 指定附加到正在运行的进程时的端口名称。
program string 要执行的调试命令。 默认为 "${debugInfo.fullTargetPath}"
project string 指定项目文件的相对路径。 通常,调试 CMake 项目时不需要更改此值。
projectTarget string 指定生成 project 时调用的可选目标。 目标必须与“启动项”下拉列表中的名称匹配
stopOnEntry boolean 指定在启动进程并附加调试程序后是否立即中断。 此参数的默认值为 false
remoteMachine string 指定启动程序的远程计算机的名称。
type string 指定项目是 dll 还是 exe(默认为 .exe)

C++ Linux 属性

properties 类型​​ 说明
program string 远程计算机上的程序可执行文件的完整路径。 使用 CMake 时,宏 ${debugInfo.fullTargetPath} 可用作此字段的值。
processId 整型 要将调试程序附加到的可选进程 ID。
sourceFileMap object 传递给调试引擎的可选源文件映射。 格式:{ "\<Compiler source location>": "\<Editor source location>" }{ "\<Compiler source location>": { "editorPath": "\<Editor source location>", "useForBreakpoints": true } }。 示例:{ "/home/user/foo": "C:\\foo" }{ "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }。 有关详细信息,请参阅源文件映射选项
additionalProperties string 其中一个 sourceFileMapOptions。 (请参阅下文。)
MIMode string 指示 MIDebugEngine 将连接到的已启用 MI 的控制台调试程序的类型。 允许的值为 "gdb""lldb"
args array 传递给程序的命令行参数。
environment 数组 要添加到程序环境的环境变量。 示例:[ { "name": "squid", "value": "clam" } ]
targetArchitecture string 调试对象的体系结构。 除非设置了此参数,否则会自动检测到此体系结构。 允许的值为 x86armarm64mipsx64amd64x86_64
visualizerFile string 调试此进程时要使用的 .natvis 文件。 此选项与 GDB 整齐打印不兼容。 如果使用此设置,请参阅 "showDisplayString"
showDisplayString boolean 指定 visualizerFile 时,showDisplayString 将启用显示字符串。 启用此选项会降低调试期间的性能。
remoteMachineName string 托管 gdb 和要调试的程序的远程 Linux 计算机。 使用连接管理器添加新的 Linux 计算机。 使用 CMake 时,宏 ${debugInfo.remoteMachineName} 可用作此字段的值。
miDebuggerPath string 启用 MI 的调试程序(例如 gdb)的路径。 如果未指定,它将首先搜索调试程序的路径。
miDebuggerServerAddress string 要连接到的已启用 MI 的调试程序服务器的网络地址。 示例:"localhost:1234"
setupCommands array 为设置基础调试程序而要执行一个或多个 GDB/LLDB 命令。 示例:"setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]。 有关详细信息,请参阅启动安装程序命令
customLaunchSetupCommands 数组 如果提供,此值会使用一些其他命令替换用于启动目标的默认命令。 例如,使用“-target-attach”附加到目标进程。 空命令列表将启动命令替换为空内容,这在将启动选项作为命令行选项提供给调试程序时很有用。 示例:"customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]
launchCompleteCommand string 调试程序完全设置好以后要执行的命令,用于使目标进程运行。 允许的值为“exec-run”、“exec-continue”、“None”。 默认值为“exec-run”。
debugServerPath string 要启动的调试服务器的可选完整路径。 默认为“null”。
debugServerArgs string 可选的调试服务器参数。 默认为“null”。
filterStderr boolean 在 stderr 流中搜索服务器启动模式,并将 stderr 记录到调试输出。 默认为 false
coreDumpPath string 指定程序的核心转储文件的可选完整路径。 默认为“null”。
externalConsole boolean 如果为 true,则为调试对象启动控制台。 如果为 false,则不会启动任何控制台。 此设置的默认值为“”false。 由于技术原因,此选项在某些情况下被忽略。
pipeTransport string 如果存在,此值会告知调试程序使用其他可执行文件作为管道连接到远程计算机,此管道将在 Visual Studio 和已启用 MI 的调试程序(例如 gdb)之间中继标准输入/输出。 允许的值:一个或多个管道传输选项

debugInfo 宏

以下宏提供有关调试环境的信息。 可使用这些宏自定义应用的启动以进行调试。

说明 示例
addressSanitizerRuntimeFlags 用于自定义地址擦除器行为的运行时标志。 用于设置 "ASAN_OPTIONS" 环境变量。 "env": {"ASAN_OPTIONS": "${addressSanitizerRuntimeFlags}:anotherFlag=true"}
defaultWorkingDirectory 设置为 "fullTargetPath" 的目录部分。 如果定义了 CMake 变量 VS_DEBUGGER_WORKING_DIRECTORY,则改为将 defaultWorkingDirectory 设置为该值。 "cwd":"${debugInfo.defaultWorkingDirectory}"
fullTargetPath 要调试的二进制文件的完整路径。 "program": "${debugInfo.fullTargetPath}"
linuxNatvisPath VS linux .natvis 文件的完整窗口路径。 通常显示为 "visualizerFile" 值。
parentProcessId 当前 Visual Studio 实例的进程 ID。 用作 shellexec 的参数。 请查看下方的 pipeTransport 示例。
remoteMachineId 连接到远程计算机的唯一数字标识符。 用作 shellexec 的参数。 请查看下方的 pipeTransport 示例。
remoteWorkspaceRoot 工作区远程副本的 Linux 路径。 指定远程计算机上的文件位置。 例如:"args": ["${debugInfo.remoteWorkspaceRoot}/Data/MyInputFile.dat"]
resolvedRemoteMachineName 目标远程计算机的名称。 部署指令中的 "targetMachine"
shellexecPath Visual Studio 管理远程计算机连接时所使用的 shellexec 程序的路径。 请查看下方的 pipeTransport 示例
tty gdb 会将正在调试的程序的输入和输出重定向到此设备。 用作 gdb (-tty) 的参数。 请查看下方的 pipeTransport 示例。
windowsSubsystemPath 适用于 Linux 的 Windows 子系统实例的完整路径。

下面的 pipeTransport 示例演示如何使用上面所述的部分 debugInfo 宏:

"pipeTransport": {
    "pipeProgram": "${debugInfo.shellexecPath}",
    "pipeArgs": [
        "/s",
        "${debugInfo.remoteMachineId}",
        "/p",
        "${debugInfo.parentProcessId}",
        "/c",
        "${debuggerCommand}",
        "--tty=${debugInfo.tty}"
    ],
    "pipeCmd": [
        "/s",
        "${debugInfo.remoteMachineId}",
        "/p",
        "${debugInfo.parentProcessId}",
        "/c",
        "${debuggerCommand}"
    ]
    }

C++ Windows 远程调试和部署属性

在远程计算机上调试和部署应用程序时使用。

properties 类型​​ 说明
cwd string 远程计算机上的目标的工作目录。 使用 CMake 时,宏 ${debugInfo.defaultWorkingDirectory} 可用作此字段的值。 默认值是调试程序/命令的目录。
deploy string 指定要部署的额外文件或目录。 例如:
"deploy": {"sourcePath":"<Full path to source file/directory on host machine>", "targetPath":"<Full destination path to file/directory on target machine>"}
deployDirectory string 项目输出自动部署到的远程计算机上的位置。 默认为 C:\Windows Default Deploy Directory\<name of app>
deployDebugRuntimeLibraries string 指定是否为活动平台部署调试运行时库。 如果活动 configurationType 为 "Debug",则默认为 "true"
deployRuntimeLibraries string 指定是否为活动平台部署运行时库。 如果活动 configurationType 为 "MinSizeRel""RelWithDebInfo""Release",则默认为 "true"
disableDeploy boolean 指定是否应部署文件。
remoteMachineName string 指定启动程序的远程 ARM64 Windows 计算机的名称。 可能是服务器名称或远程计算机的 IP 地址。
authenticationType string 指定远程连接的类型。 可能值为 "windows""none"。 默认值为 "windows"。 此值应与在远程计算机上运行的远程调试器上指定的身份验证设置相匹配。

启动安装程序命令

setupCommands 属性配合使用:

properties 类型​​ 说明
text string 要执行的调试程序命令。
description string 命令的可选说明。
ignoreFailures boolean 如果为 true,则应忽略命令的失败。 默认为 false

管道传输选项

pipeTransport 属性配合使用:

properties 类型​​ 说明
pipeCwd string 管道程序工作目录的完全限定的路径。
pipeProgram string 要执行的完全限定的管道命令。
pipeArgs 数组 传递给管道程序用于配置连接的命令行参数。
debuggerPath string 目标计算机上调试程序的完整路径,例如,/usr/bin/gdb。
pipeEnv object 传递给管道程序的环境变量。
quoteArgs boolean 如果各个参数包含字符(例如空格或制表符),是否应将其加引号? 如果为 false,则调试器命令将不再被自动引用。 默认值为 true

源文件映射选项

sourceFileMap 属性配合使用:

properties 类型​​ 说明
editorPath string 编辑器要查找的源代码的位置。
useForBreakpoints boolean 设置断点时,应使用此源映射。 如果为 false,则只有文件名和行号用于设置断点。 如果为 true,则只有在使用此源映射时,才会使用文件的完整路径和行号设置断点。 否则,设置断点时将仅使用文件名和行号。 默认值为 true