Informations de référence sur le schéma launch.vs.json (C++)

  • Article

Dans Visual Studio 2017 et versions ultérieures, vous pouvez ouvrir et générer du code à partir de presque n’importe quel projet basé sur un répertoire sans nécessiter de solution ou de fichier projet. En l’absence de fichier projet ou solution, vous pouvez spécifier des tâches de génération personnalisées et lancer des paramètres via des fichiers de configuration JSON. Cet article décrit le fichier launch.vs.json, qui spécifie les paramètres de débogage. Pour plus d’informations sur la fonctionnalité « Dossier ouvert¤», consultez Développer du code dans Visual Studio sans projets ni solutions.

Pour créer le fichier, cliquez avec le bouton droit sur un fichier exécutable dans l’Explorateur de solutions, puis choisissez Déboguer et lancer les paramètres. Choisissez l’option qui correspond le plus étroitement à votre projet, puis utilisez les propriétés suivantes pour modifier la configuration si nécessaire. Pour plus d’informations sur les projets de débogage CMake, consultez Configurer les sessions de débogage CMake.

Propriétés par défaut

Propriété Type Description
args tableau Spécifie les arguments de ligne de commande passés au programme lancé.
buildConfigurations tableau Une paire clé-valeur qui spécifie le nom du mode de génération pour appliquer les configurations. Par exemple, Debug ou Release et les configurations à utiliser en fonction du mode de génération sélectionné.
currentDir string Spécifie le chemin d’accès complet du répertoire à la cible de build. Le répertoire est détecté automatiquement, sauf si ce paramètre est défini.
cwd string Chemin complet du répertoire sur le système distant où le programme s’exécutera. La valeur par défaut est "${debugInfo.defaultWorkingDirectory}"
debugType string Spécifie le mode de débogage en fonction du type de code (natif, managé ou mixte). Le mode est détecté automatiquement, sauf si ce paramètre est défini. Valeurs autorisées : "native", "managed", "mixed".
env tableau Spécifie une liste clé-valeur des variables d’environnement personnalisées. Par exemple : env:{"myEnv":"myVal"}.
inheritEnvironments tableau Spécifie un ensemble de variables d’environnement héritées de plusieurs sources. Vous pouvez définir certaines variables dans des fichiers tels CMakeSettings.json ou CppProperties.json et les rendre disponibles pour déboguer le contexte. Visual Studio 16.4 : spécifiez des variables d’environnement par cible à l’aide de la syntaxe env.VARIABLE_NAME. Pour annuler la définition d’une variable, définissez-la sur "null".
name string Spécifie le nom de l’entrée dans la liste déroulante Élément de démarrage.
noDebug booléen Spécifie s’il faut déboguer le programme lancé. La valeur par défaut de ce paramètre est si false n’est pas spécifiée.
portName string Spécifie le nom du port durant l'attachement à un processus en cours d'exécution.
program string Commande de débogage à exécuter. La valeur par défaut est "${debugInfo.fullTargetPath}".
project string Spécifie le chemin relatif du fichier projet. Normalement, vous n’avez pas besoin de modifier cette valeur lors du débogage d’un projet CMake.
projectTarget string Spécifie la cible facultative appelée lors de la génération project. La cible doit correspondre au nom dans la liste déroulante Élément de démarrage.
stopOnEntry booléen Spécifie s’il faut interrompre le processus dès que le processus est lancé et que le débogueur s’attache. La valeur par défaut de ce paramètre est false.
remoteMachine string Spécifie le nom de la machine distante sur laquelle le programme est lancé.
type string Spécifie si le projet est un dll ou exe par défaut pour .exe

Propriétés Linux C++

Propriété Type Description
program string Chemin complet du programme exécutable sur l’ordinateur distant. Lorsque vous utilisez CMake, la macro ${debugInfo.fullTargetPath} peut être utilisée comme valeur de ce champ.
processId entier ID de processus facultatif auquel le débogueur doit être attaché.
sourceFileMap object Mappages de fichiers sources facultatifs passés au moteur de débogage. Format : { "\<Compiler source location>": "\<Editor source location>" } ou { "\<Compiler source location>": { "editorPath": "\<Editor source location>", "useForBreakpoints": true } }. Exemple : { "/home/user/foo": "C:\\foo" } ou { "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }. Pour plus d’informations, consultez les options de mappage de fichiers sources.
additionalProperties string Une des options sourceFileMapOptions. (Voir ci-dessous.)
MIMode string Indique le type de débogueur de console compatible mi auquel le MIDebugEngine se connectera. Les valeurs autorisées sont "gdb", "lldb".
args tableau Arguments de ligne de commande passés au programme.
environment tableau Variables d’environnement à ajouter à l’environnement du programme. Exemple : [ { "name": "squid", "value": "clam" } ].
targetArchitecture string Architecture du débogueur. L’architecture est détectée automatiquement, sauf si ce paramètre est défini. Les valeurs autorisées sont x86, arm, arm64, mips, x64, amd64 et x86_64.
visualizerFile string Le fichier .natvis à utiliser pendant le débogage de ce processus. Cette option n’est pas compatible avec l’impression GDB. Vérifiez "showDisplayString" si vous utilisez ce paramètre.
showDisplayString booléen Lorsqu’un visualizerFile est spécifié, showDisplayString active la chaîne d’affichage. L’activation de cette option peut ralentir les performances pendant le débogage.
remoteMachineName string Machine Linux distante qui héberge gdb et le programme à déboguer. Utilisez le gestionnaire de connexions pour l’ajout de nouvelles machines Linux. Lorsque vous utilisez CMake, la macro ${debugInfo.remoteMachineName} peut être utilisée comme valeur de ce champ.
miDebuggerPath string Chemin d’accès au débogueur prenant en charge MI (par exemple, gdb). Lorsqu’il n’est pas spécifié, il recherche d’abord PATH pour le débogueur.
miDebuggerServerAddress string Adresse réseau du serveur de débogueur prenant en charge MI pour se connecter. Exemple : "localhost:1234".
setupCommands tableau Une ou plusieurs commandes GDB/LLDB à exécuter pour configurer le débogueur sous-jacent. Exemple : "setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]. Pour plus d’informations, consultez Commandes pour lancer le programme d’installation.
customLaunchSetupCommands tableau Si elle est fournie, cette valeur remplace les commandes par défaut utilisées pour lancer une cible par d’autres commandes. Par exemple, utilisez « -target-attach » pour l’attacher à un processus cible. Une liste de commandes vide remplace les commandes de lancement par rien, ce qui peut être utile si le débogueur fournit des options de lancement en tant qu’options de ligne de commande. Exemple : "customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }].
launchCompleteCommand string Commande à exécuter une fois le débogueur entièrement configuré, pour provoquer l’exécution du processus cible. Les valeurs autorisées sont « exec-run », « exec-continue », « None ». La valeur par défaut est « exec-run ».
debugServerPath string Chemin complet facultatif du serveur de débogage à lancer. La valeur par défaut est Null.
debugServerArgs string Arguments de serveur de débogage facultatifs. La valeur par défaut est Null.
filterStderr booléen Permet de rechercher dans le flux stderr le modèle correspondant au démarrage du serveur, et de journaliser stderr dans la sortie de débogage. La valeur par défaut est false.
coreDumpPath string Chemin complet facultatif d'un fichier d'image mémoire principal pour le programme spécifié. La valeur par défaut est Null.
externalConsole booléen Si la valeur est True, une console est lancée pour le débogueur. Si false, aucune console n’est lancée. La valeur par défaut de ce paramètre est false. Cette option est ignorée dans certains cas pour des raisons techniques.
pipeTransport string Lorsque présent, cette valeur signale au débogueur qu'il doit se connecter à un ordinateur distant en se servant d'un autre exécutable comme canal de relais d'entrée/de sortie standard entre Visual Studio \net le débogueur MI (par exemple, gdb). Valeurs autorisées : une ou plusieurs options de transport de canal.

macros de débogageInfo

Les macros suivantes fournissent des informations sur l’environnement de débogage. Ils sont utiles pour personnaliser le lancement de votre application pour le débogage.

Macro Description Exemple
addressSanitizerRuntimeFlags Indicateurs d’exécution utilisés pour personnaliser le comportement de l’assainissant d’adresse. Utilisé pour définir la variable d’environnement "ASAN_OPTIONS". "env": {"ASAN_OPTIONS": "${addressSanitizerRuntimeFlags}:anotherFlag=true"}
defaultWorkingDirectory Défini sur la partie répertoire de "fullTargetPath". Si la variable CMake VS_DEBUGGER_WORKING_DIRECTORY est définie, alors defaultWorkingDirectory est définie à cette valeur. "cwd":"${debugInfo.defaultWorkingDirectory}"
fullTargetPath Chemin d’accès complet au fichier binaire en cours de débogage. "program": "${debugInfo.fullTargetPath}"
linuxNatvisPath Chemin d’accès complet aux fenêtres du fichier VS linux .natvis. Apparaît généralement sous la forme de la valeur "visualizerFile".
parentProcessId ID de processus de l’instance Visual Studio actuelle. Utilisé comme paramètre pour shellexec. Consultez l’exemple pipeTransport ci-dessous.
remoteMachineId Identificateur numérique unique pour la connexion à l’ordinateur distant. Utilisé comme paramètre pour shellexec. Consultez l’exemple pipeTransport ci-dessous.
remoteWorkspaceRoot Chemin d’accès Linux à la copie distante de l’espace de travail. Spécifiez des emplacements de fichier sur l’ordinateur distant. Par exemple : "args": ["${debugInfo.remoteWorkspaceRoot}/Data/MyInputFile.dat"]
resolvedRemoteMachineName Nom de l’ordinateur distant cible. La valeur "targetMachine" dans une directive de déploiement
shellexecPath Chemin d’accès au programme shellexec que Visual Studio utilise pour gérer la connexion de l’ordinateur distant. Voir l’exemple pipeTransport ci-dessous
tty gdb redirige l’entrée et la sortie vers cet appareil pour le programme en cours de débogage. Utilisé comme paramètre pour gdb (-tty). Consultez l’exemple pipeTransport ci-dessous.
windowsSubsystemPath Chemin d’accès complet à l’instance du sous-système Windows pour Linux.

L’exemple pipeTransport ci-dessous montre comment utiliser certaines des macros debugInfo définies ci-dessus :

"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}"
    ]
    }

Débogage distant Windows C++ et propriétés de déploiement

Utilisé lors du débogage et du déploiement d’une application sur une machine distante.

Propriété Type Description
cwd string Répertoire de travail de la cible sur l’ordinateur distant. Lorsque vous utilisez CMake, la macro ${debugInfo.defaultWorkingDirectory} peut être utilisée comme valeur de ce champ. La valeur par défaut est le répertoire du programme/commande de débogage.
deploy string Spécifie des fichiers ou répertoires supplémentaires à déployer. Par exemple :
"deploy": {"sourcePath":"<Full path to source file/directory on host machine>", "targetPath":"<Full destination path to file/directory on target machine>"}
deployDirectory string Emplacement sur l’ordinateur distant sur lequel les sorties du projet sont automatiquement déployées. La valeur par défaut est « C:\Windows Default Deploy Directory\<name of app>
deployDebugRuntimeLibraries string Spécifie le déploiement ou non des bibliothèques runtime de débogage pour la plateforme active. "true" est par défaut, si le configurationType actif est "Debug"
deployRuntimeLibraries string Spécifie le déploiement ou non des bibliothèques runtime pour la plateforme active. "true" est par défaut, si le configurationType actif est "MinSizeRel", "RelWithDebInfo" ou "Release".
disableDeploy booléen Spécifie si les fichiers doivent être déployés.
remoteMachineName string Spécifie le nom de la machine Windows ARM64 distante où le programme est lancé. Il peut s’agir du nom du serveur ou de l’adresse IP de l’ordinateur distant.
authenticationType string Spécifie le type de connexion à distance. Les valeurs possibles sont "windows" et "none". Par défaut, il s’agit de "windows". Cette valeur doit correspondre au paramètre d’authentification spécifié sur le débogueur distant qui s’exécute sur l’ordinateur distant.

Lancer les commandes d’installation

Utilisé avec la propriété setupCommands :

Propriété Type Description
text string Commande de débogueur à exécuter.
description string Description facultative de la commande.
ignoreFailures booléen Si la valeur est True, les échecs de la commande doivent être ignorés. La valeur par défaut est false.

Options de transport Pipe

Utilisé avec la propriété pipeTransport :

Propriété Type Description
pipeCwd string Chemin d’accès complet du répertoire de travail du programme canal.
pipeProgram string Commande canal complète à exécuter.
pipeArgs tableau Arguments de ligne de commande passés au programme canal pour configurer la connexion.
debuggerPath string Chemin complet du débogueur sur la machine cible, par exemple /usr/bin/gdb.
pipeEnv object Variables d'environnement passées au programme canal.
quoteArgs booléen Si des arguments individuels contiennent des caractères (tels que des espaces ou des onglets), doit-il être entre guillemets ? Si false, la commande du débogueur ne sera plus automatiquement entre guillemets. La valeur par défaut est true.

Options de mappage de fichiers sources

Utilisez-la avec la propriété sourceFileMap :

Propriété Type Description
editorPath string Emplacement du code source de l'éditeur à localiser.
useForBreakpoints booléen Lorsque vous définissez des points d’arrêt, ce mappage source doit être utilisé. Si false, seul le nom de fichier et le numéro de ligne sont utilisés pour définir des points d’arrêt. Si true, les points d’arrêt sont définis avec le chemin complet du fichier et du numéro de ligne uniquement lorsque ce mappage source est utilisé. Sinon, un nom de fichier et un numéro de ligne sont utilisés lors de la définition de points d’arrêt. La valeur par défaut est true.