Справочник по схеме launch.vs.json (C++)

Visual Studio 2017 и более поздние версии позволяют открывать и компилировать код из практически любого основанного на каталогах проекта без необходимости в файле проекта или решения. Если файл проекта или решения отсутствует, вы можете задавать настраиваемые задачи сборки и параметры запуска, используя файлы конфигурации JSON. В этой статье приведено описание файла launch.vs.json, который задает параметры отладки. Дополнительные сведения о функции "Открыть папку" см. в статье Разработка кода в Visual Studio без использования проектов и решений.

Чтобы создать файл, щелкните правой кнопкой мыши исполняемый файл в Обозревателе решений и выберите Параметры отладки и запуска. Выберите параметр, который наиболее полно соответствует проекту, а затем используйте следующие свойства, чтобы изменить конфигурацию по необходимости. Дополнительные сведения об отладке проектов CMake см. в разделе Настройка сеансов отладки CMake.

Свойства по умолчанию

Свойство	Type	Описание
args	array	Задает аргументы командной строки, передаваемые в запущенную программу.
buildConfigurations	array	Пара "ключ-значение", которая указывает имя режима сборки для применения конфигураций. Например, Debug или Release и конфигурации, используемые в соответствии с выбранным режимом сборки.
currentDir	строка	Указывает полный путь к каталогу для целевого объекта сборки. Если этот параметр не задан, каталог обнаруживается автоматически.
cwd	строка	Полный путь к каталогу в удаленной системе, где будет выполняться программа. По умолчанию — "${debugInfo.defaultWorkingDirectory}".
debugType	строка	Задает режим отладки в соответствии с типом кода (собственный, управляемый или смешанный). Если этот параметр не задан, режим обнаруживается автоматически. Допустимые значения: "native", "managed", "mixed".
env	array	Указывает список значений ключа для настраиваемых переменных среды. Например: env:{"myEnv":"myVal"}.
inheritEnvironments	array	Задает набор переменных среды, унаследованных из нескольких источников. Можно определить некоторые переменные в файлах, например CMakeSettings.json или CppProperties.json, и сделать их доступными для контекста отладки. Visual Studio 16.4. Укажите переменные среды на основе каждого целевого объекта с помощью синтаксиса env.VARIABLE_NAME . Чтобы отменить переменную, задайте для нее значение "null".
name	строка	Задает имя записи в раскрывающемся списке объектов отладки.
noDebug	boolean	Указывает, следует ли выполнять отладку запущенной программы. Если параметр не задан, используется значение по умолчанию false.
portName	строка	Задает имя порта при подключении к выполняющемуся процессу.
program	строка	Команда отладки для выполнения. По умолчанию — "${debugInfo.fullTargetPath}".
project	строка	Задает относительный путь к файлу проекта. Обычно изменять это значение при отладке проекта CMake не требуется.
projectTarget	строка	Указывает необязательный целевой объект, вызываемый при построении project. Имя целевого объекта должно соответствовать имени в раскрывающемся списке объектов отладки.
stopOnEntry	boolean	Указывает, следует ли прерывать работу сразу после запуска процесса и присоединения отладчика. Значение параметра по умолчанию — false.
remoteMachine	строка	Указывает имя удаленного компьютера, на котором запускается программа.
type	строка	Указывает, является ли проект dll или exe (по умолчанию — EXE)

Свойства C++ Linux

Свойство	Type	Описание:
program	строка	Полный путь к исполняемому файлу программы на удаленном компьютере. При использовании CMake в качестве значения этого поля можно использовать макрос ${debugInfo.fullTargetPath}.
processId	integer	Необязательный идентификатор процесса для подключения отладчика.
sourceFileMap	объект	Необязательные сопоставления исходных файлов, переданных модулю отладки. Формат: { "\<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	строка	Один из sourceFileMapOptions. (См. ниже.)
MIMode	строка	Указывает тип отладчика консоли с поддержкой MI, к которому будет подключаться MIDebugEngine. Допустимые значения: "gdb" и "lldb".
args	array	Аргументы командной строки, переданные в программу.
environment	array	Переменные среды для добавления в среду для программы. Пример: [ { "name": "squid", "value": "clam" } ].
targetArchitecture	строка	Архитектура отлаживаемого объекта. Если этот параметр не задан, архитектура обнаруживается автоматически. Допустимые значения: x86, arm, arm64, mips, x64, amd64, x86_64.
visualizerFile	строка	Файл NATVIS, используемый при отладке этого процесса. Этот параметр несовместим с автоматическим форматированием GDB. См. "showDisplayString" при использовании этого параметра.
showDisplayString	boolean	Если указан visualizerFile, showDisplayString включит отображаемую строку. Включение этого параметра может привести к снижению производительности во время отладки.
remoteMachineName	строка	Удаленный компьютер Linux, на котором размещается GDB, и программа для отладки. Используйте диспетчер подключений для добавления новых компьютеров Linux. При использовании CMake в качестве значения этого поля можно использовать макрос ${debugInfo.remoteMachineName}.
miDebuggerPath	строка	Путь к отладчику с поддержкой Управляемого экземпляра (например, gdb). Если этот параметр не указан, сначала будет осуществляться поиск пути для отладчика.
miDebuggerServerAddress	строка	Сетевой адрес сервера отладчика с поддержкой Управляемого экземпляра для подключения. Пример: "localhost:1234".
setupCommands	array	Одна или несколько команд GDB/LLDB, которые необходимо выполнить для настройки базового отладчика. Пример: "setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]. Дополнительные сведения см. в разделе "Запуск команд установки".
customLaunchSetupCommands	array	Будучи указанным, это значение заменяет используемые по умолчанию команды для запуска целевого объекта на какие-то другие. Например, используйте "-target-attach" для подключения к целевому процессу. Пустой список команд заменяет команды запуска на Nothing, что может быть полезно, если отладчик предоставляет параметры запуска в виде параметров командной строки. Пример: "customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }].
launchCompleteCommand	строка	Команда, выполняемая после полной настройки отладчика для запуска целевого процесса. Допустимые значения: "exec-run", "exec-continue", "None". Значение по умолчанию — "exec-run".
debugServerPath	строка	Необязательный полный путь к серверу отладки для запуска. Значение по умолчанию — NULL.
debugServerArgs	строка	Необязательные аргументы сервера отладки. Значение по умолчанию — NULL.
filterStderr	boolean	Поиск запущенного сервером шаблона в потоке stderr и регистрация stderr в выходных данных отладки. По умолчанию — false.
coreDumpPath	строка	Необязательный полный путь к основному файлу дампа для указанной программы. Значение по умолчанию — NULL.
externalConsole	boolean	Если значение — true, для отлаживаемого объекта запускается консоль. Если значение — false, консоль не запускается. Значение по умолчанию для этого параметра — false. В некоторых случаях этот параметр игнорируется по техническим причинам.
pipeTransport	строка	Это значение (при наличии) требует, чтобы отладчик подключался к удаленному компьютеру, используя другой исполняемый файл в качестве канала для пересылки стандартного ввода-вывода между Visual Studio и отладчиком с поддержкой Управляемого экземпляра (например, gdb). Допустимые значения: один или несколько параметров транспорта канала.

Макросы debugInfo

Следующие макросы предоставляют сведения о среде отладки. Они полезны при настройке запуска приложения для отладки.

Макрос	Description	Пример
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	Полный путь Windows к файлу VS Linux .natvis. Обычно отображается как значение "visualizerFile".
parentProcessId	ИД процесса для текущего экземпляра Visual Studio. Используется в качестве параметра для shellexec.	См. пример для pipeTransport ниже.
remoteMachineId	Уникальный числовой идентификатор для подключения к удаленному компьютеру. Используется в качестве параметра для shellexec.	См. пример для pipeTransport ниже.
remoteWorkspaceRoot	Путь Linux к удаленной копии рабочей области.	Укажите расположение файлов на удаленном компьютере. Например: "args": ["${debugInfo.remoteWorkspaceRoot}/Data/MyInputFile.dat"]
resolvedRemoteMachineName	Имя целевого удаленного компьютера.	Значение "targetMachine" в директиве развертывания.
shellexecPath	Путь к программе shellexec, используемой Visual Studio для управления подключением удаленного компьютера.	См. пример для pipeTransport ниже.
tty	Отладчик gdb будет перенаправлять входные и выходные данные на это устройство для отлаживаемой программы. Используется в качестве параметра для gdb (-tty).	См. пример для pipeTransport ниже.
windowsSubsystemPath	Полный путь к экземпляру подсистемы Windows для Linux.

В следующем примере 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

Используется при отладке и развертывании приложения на удаленном компьютере.

Свойство	Type	Описание:
cwd	строка	Рабочий каталог целевого объекта на удаленном компьютере. При использовании CMake в качестве значения этого поля можно использовать макрос ${debugInfo.defaultWorkingDirectory}. Значение по умолчанию — каталог программы или команды отладки.
deploy	строка	Указывает дополнительные файлы или каталоги для развертывания. Например: "deploy": {"sourcePath":"<Full path to source file/directory on host machine>", "targetPath":"<Full destination path to file/directory on target machine>"}
deployDirectory	строка	Расположение на удаленном компьютере, где автоматически развертываются выходные данные проекта. Значение по умолчанию — C:\Windows Default Deploy Directory\<name of app>
deployDebugRuntimeLibraries	строка	Указывает, следует ли развернуть отладочные библиотеки времени выполнения для активной платформы. Значение по умолчанию — "true", если активный параметр configurationType имеет значение "Debug"
deployRuntimeLibraries	строка	Указывает, следует ли развернуть библиотеки времени выполнения для активной платформы. Значение по умолчанию — "true", если активный параметр configurationType имеет значение "MinSizeRel", "RelWithDebInfo" или "Release".
disableDeploy	boolean	Указывает, следует ли развертывать файлы.
remoteMachineName	строка	Указывает имя удаленного компьютера ARM64 Windows, на котором запускается программа. Может быть именем сервера или IP-адресом удаленного компьютера.
authenticationType	строка	Указание типа удаленного подключения. Возможные значения: "windows" и "none". Значение по умолчанию — "windows". Это значение должно соответствовать параметру проверки подлинности, указанному в удаленном отладчике, который работает на удаленном компьютере.

Запуск команд установки

Используется со свойством setupCommands:

Свойство	Type	Описание:
text	строка	Команда отладчика для выполнения.
description	строка	Необязательное описание команды.
ignoreFailures	boolean	Если значение — true, ошибки, передаваемые командой, следует игнорировать. По умолчанию — false.

Параметры транспорта канала

Используется со свойством pipeTransport:

Свойство	Type	Описание:
pipeCwd	строка	Полный путь к рабочему каталогу для программы канала.
pipeProgram	строка	Полная команда канала для выполнения.
pipeArgs	array	Аргументы командной строки, передаваемые в программу канала для настройки подключения.
debuggerPath	строка	Полный путь к отладчику на конечном компьютере, например: /usr/bin/gdb.
pipeEnv	объект	Переменные среды, переданные в программу канала.
quoteArgs	boolean	Если отдельные аргументы содержат символы (например, пробелы или знаки табуляции), следует ли заключать их в кавычки? При значении false команда отладчика больше не будет автоматически заключаться в кавычки. По умолчанию — true.

Параметры карты исходного файла

Используется со свойством sourceFileMap:

Свойство	Type	Описание:
editorPath	строка	Расположение исходного кода для поиска редактором.
useForBreakpoints	boolean	При задании точек останова следует использовать это сопоставление источника. Если задано значение false, для установки точек останова используется только имя файла и номер строки. Если задано значение true, точки останова будут заданы полным путем к файлу и номеру строки только при использовании этого сопоставления источника. В противном случае при задании точек останова будет использоваться только имя файла и номер строки. По умолчанию — true.