Configurer des sessions de débogage CMake

La prise en charge native de CMake est disponible dans Visual Studio 2017 et versions ultérieures. Pour afficher la documentation sur ces versions, définissez le contrôle de sélecteur de version de Visual Studio pour cet article sur Visual Studio 2017 ou version ultérieure. Il se trouve en haut de la table des matières de cette page.

Toutes les cibles CMake exécutables figurent dans la liste déroulante Élément de démarrage de la barre d’outils. Sélectionnez-en une pour démarrer une session de débogage et lancer le débogueur.

Capture d’écran de la liste déroulante des éléments de démarrage de CMake.

Vous pouvez également démarrer une session de débogage à partir de l’Explorateur de solutions. Tout d’abord, basculez en mode Vue des cibles CMake dans la fenêtre de l’Explorateur de solutions.

Capture d’écran du menu Vue des cibles CMake.

Ensuite, cliquez avec le bouton droit sur un exécutable et sélectionnez Déboguer. Cette commande démarre automatiquement le débogage de la cible sélectionnée en fonction de votre configuration active.

Capture d’écran du menu de l’option de débogage Vue des cibles CMake.

À compter de Visual Studio 2022 version 17.6, vous pouvez également démarrer une session de débogage sur votre fichier CMakeLists.txt. Pour ce faire, définissez simplement un point d’arrêt dans votre fichier CMakeLists.txt et exécutez Configurer Project avec le débogueur CMake à partir de la liste déroulante Projet.

Capture d’écran de la liste déroulante du débogueur CMake.

Personnaliser les paramètres du débogueur

Vous pouvez personnaliser les paramètres du débogueur pour n’importe quelle cible CMake exécutable dans votre projet. Ils se trouvent dans un fichier de configuration appelé launch.vs.json, situé dans un dossier .vs à la racine de votre projet. Un fichier de configuration de lancement est utile dans la plupart des scénarios de débogage, car vous pouvez configurer et enregistrer les détails de votre configuration de débogage. Il existe trois points d’entrée dans ce fichier :

Menu Débogage : sélectionnez Déboguer > Paramètres de débogage et de lancement pour ${activeDebugTarget} dans le menu principal pour personnaliser la configuration de débogage spécifique à votre cible de débogage active. Si aucune cible de débogage n’est sélectionnée, cette option est grisée.

Vue des cibles : accédez à Vue des cibles dans l’Explorateur de solutions. Ensuite, cliquez avec le bouton droit sur une cible de débogage, puis sélectionnez Ajouter une configuration de débogage pour personnaliser la configuration de débogage spécifique à la cible sélectionnée.

Capture d’écran de la commande Ajouter une configuration de débogage dans le menu contextuel de la cible.

CMakeLists.txt racine : cliquez avec le bouton droit sur un fichier CMakeLists.txt racine, puis sélectionnez Ajouter une configuration de débogage pour ouvrir la boîte de dialogue Sélectionner un débogueur. Cette boîte de dialogue vous permet d’ajouter n’importe quel type de configuration de débogage, mais vous devez spécifier manuellement la cible CMake à appeler via la propriété projectTarget.

Capture d’écran de la boîte de dialogue Sélectionner un débogueur.

Vous pouvez modifier le fichier launch.vs.json pour créer des configurations de débogage pour un nombre quelconque de cibles CMake. Lorsque vous enregistrez le fichier, Visual Studio crée une entrée pour chaque nouvelle configuration dans la liste déroulante Élément de démarrage.

Clés de référence dans CMakeSettings.json

Pour référencer n’importe quelle clé dans un fichier CMakeSettings.json, ajoutez-lui cmake. dans launch.vs.json. L’exemple suivant montre un fichier launch.vs.json simple qui tire (pull) la valeur de la clé remoteCopySources dans le fichier CMakeSettings.json pour la configuration actuellement sélectionnée :

{
  "version": "0.2.1",
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "name": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "args": ["${cmake.remoteCopySources}"]
    }
  ]
}

Les variables d’environnement définies dans CMakeSettings.json peuvent également être utilisées dans launch.vs.json à l’aide de la syntaxe ${env.VARIABLE_NAME}. Dans Visual Studio 2019 version 16.4 et ultérieures, les cibles de débogage sont lancées automatiquement à l’aide de l’environnement que vous spécifiez dans CMakeSettings.json. Vous pouvez annuler la définition d’une variable d’environnement en la définissant sur null.

Informations de référence sur launch.vs.json

Il existe de nombreuses propriétés launch.vs.json pour prendre en charge tous vos scénarios de débogage. Les propriétés suivantes sont communes à toutes les configurations de débogage, à la fois distantes et locales :

projectTarget : spécifie la cible CMake à appeler lors de la génération du projet. Visual Studio remplit automatiquement cette propriété si vous entrez launch.vs.json à partir du menu Déboguer ou de la vue des cibles. Cette valeur doit correspondre au nom d’une cible de débogage existante répertoriée dans la liste déroulante Élément de démarrage.
env : variables d’environnement supplémentaires à ajouter à l’aide de la syntaxe suivante :
```
"env": {
      "DEBUG_LOGGING_LEVEL": "trace;info",
      "ENABLE_TRACING": "true"
    }
```
args : arguments de ligne de commande passés au programme à déboguer.

Informations de référence sur launch.vs.json pour les projets distants et WSL

Dans Visual Studio 2019 version 16.6, nous avons ajouté une nouvelle configuration de débogage de type: cppgdb pour simplifier le débogage sur les systèmes distants et WSL. Les anciennes configurations de débogage de type: cppdbg sont toujours prises en charge.

Type de configuration `cppgdb`

name : nom convivial permettant d’identifier la configuration dans la liste déroulante Élément de démarrage.
project : spécifie le chemin d’accès relatif au fichier projet. Normalement, vous n’avez pas besoin de modifier ce chemin lors du débogage d’un projet CMake.
projectTarget : spécifie la cible CMake à appeler lors de la génération du projet. Visual Studio remplit automatiquement cette propriété si vous entrez launch.vs.json à partir du menu Déboguer ou de la vue des cibles. Cette valeur cible doit correspondre au nom d’une cible de débogage existante répertoriée dans la liste déroulante Élément de démarrage.
debuggerConfiguration : indique l’ensemble des valeurs par défaut de débogage à utiliser. Dans Visual Studio 2019 version 16.6, la seule option valide est gdb. Visual Studio 2019 version 16.7 ou ultérieure prend également en charge gdbserver.
args : arguments de ligne de commande passés au moment du démarrage au programme en cours de débogage.
env : variables d’environnement supplémentaires passées au programme en cours de débogage. Par exemple : {"DISPLAY": "0.0"}.
processID : ID de processus Linux auquel attacher. Utilisé uniquement lors de l’attachement à un processus distant. Pour plus d’informations, consultez Résoudre les problèmes liés à l’attachement aux processus à l’aide de GDB.

Options supplémentaires pour la configuration de `gdb`

program : la valeur par défaut est "${debugInfo.fullTargetPath}". Chemin Unix de l’application à déboguer. Obligatoire uniquement s’il est différent de l’exécutable cible dans l’emplacement de génération ou de déploiement.
remoteMachineName : la valeur par défaut est "${debugInfo.remoteMachineName}". Nom du système distant qui héberge le programme à déboguer. Obligatoire uniquement s’il est différent du système de génération. Une entrée doit exister dans le Gestionnaire des connexions. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.
cwd : la valeur par défaut est "${debugInfo.defaultWorkingDirectory}". Chemin Unix vers le répertoire sur le système distant où program est exécuté. Le répertoire doit exister.
gdbpath : la valeur par défaut est /usr/bin/gdb. Chemin d’accès Unix complet vers le gdb utilisé pour le débogage. Obligatoire uniquement si vous utilisez une version personnalisée de gdb.
preDebugCommand : commande Linux à exécuter immédiatement avant d’appeler gdb. gdb ne démarre pas tant que la commande n’est pas terminée. Vous pouvez utiliser l’option pour exécuter un script avant l’exécution de gdb.

Options supplémentaires autorisées avec la configuration de `gdbserver` (version 16.7 ou ultérieure)

program : la valeur par défaut est "${debugInfo.fullTargetPath}". Chemin Unix de l’application à déboguer. Obligatoire uniquement s’il est différent de l’exécutable cible dans l’emplacement de génération ou de déploiement.

Conseil

Le déploiement n’est pas encore pris en charge pour les scénarios de compilation croisée locaux. Si vous effectuez une compilation croisée sur Windows (par exemple, à l’aide d’un compilateur croisé sur Windows pour générer un exécutable ARM Linux), vous devez copier manuellement le fichier binaire à l’emplacement spécifié par program sur la machine ARM distante avant le débogage.
remoteMachineName : la valeur par défaut est "${debugInfo.remoteMachineName}". Nom du système distant qui héberge le programme à déboguer. Obligatoire uniquement s’il est différent du système de génération. Une entrée doit exister dans le Gestionnaire des connexions. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.
cwd : la valeur par défaut est "${debugInfo.defaultWorkingDirectory}". Chemin d’accès Unix complet vers le répertoire sur le système distant où program est exécuté. Le répertoire doit exister.
gdbPath: chemin d’accès Windows complet du gdb utilisé pour déboguer.
gdbserverPath : la valeur par défaut est usr/bin/gdbserver. Chemin d’accès Unix complet vers le gdbserver utilisé pour le débogage.
preDebugCommand : commande Linux à exécuter immédiatement avant de démarrer gdbserver. gdbserver ne démarre pas tant que la commande n’est pas terminée.

Options de déploiement

Utilisez les options suivantes pour séparer votre machine de build (définie dans CMakeSettings.json) de votre ordinateur de débogage distant.

remoteMachineName : machine de débogage distante. Obligatoire uniquement si elle est différente de la machine de génération. Une entrée doit exister dans le Gestionnaire des connexions. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.
disableDeploy : la valeur par défaut est false. Indique si la séparation compilation/débogage est désactivée. Lorsque la valeur est définie sur false, cette option permet de procéder à la génération et au débogage sur deux machines distinctes.
deployDirectory : chemin d’accès Unix complet vers le répertoire de remoteMachineName dans lequel l’exécutable est copié.
deploy : tableau de paramètres de déploiement avancés. Vous ne devez configurer ces paramètres que si vous souhaitez exercer un contrôle plus précis sur le processus de déploiement. Par défaut, seuls les fichiers nécessaires au processus de débogage sont déployés sur la machine de débogage distante.
- sourceMachine : machine à partir de laquelle le fichier ou le répertoire est copié. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes stockées dans le Gestionnaire des connexions. Lorsque vous générez en mode natif sur WSL, cette option est ignorée.
- targetMachine : machine vers laquelle le fichier ou le répertoire est copié. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes stockées dans le Gestionnaire des connexions.
- sourcePath : emplacement du fichier ou du répertoire sur sourceMachine.
- targetPath : emplacement du fichier ou du répertoire sur targetMachine.
- deploymentType : description du type de déploiement. LocalRemote et RemoteRemote sont pris en charge. LocalRemote signifie copier à partir du système de fichiers local vers le système distant spécifié par remoteMachineName dans launch.vs.json. RemoteRemote signifie copier à partir du système de génération à distance spécifié dans CMakeSettings.json vers l’autre système distant spécifié dans launch.vs.json.
- executable : indique si le fichier déployé est un exécutable.

Exécuter des commandes `gdb` personnalisées

Visual Studio prend en charge l’exécution de commandes gdb personnalisées pour interagir directement avec le débogueur sous-jacent. Pour plus d’informations, consultez Exécution de commandes gdb lldb personnalisées.

Activation de la journalisation

Activez la journalisation MIEngine pour voir quelles commandes sont envoyées à gdb, quelle sortie gdb renvoie et combien de temps prend chaque commande. En savoir plus

Type de configuration `cppdbg`

Les options suivantes peuvent être utilisées lors du débogage sur un système distant ou un WSL à l’aide du type de configuration cppdbg. Dans Visual Studio 2019 version 16.6 ou ultérieure, le type de configuration cppgdb est recommandé.

name : nom convivial permettant d’identifier la configuration dans la liste déroulante Élément de démarrage.
project : spécifie le chemin d’accès relatif au fichier projet. Normalement, vous n’avez pas besoin de modifier cette valeur lors du débogage d’un projet CMake.
projectTarget : spécifie la cible CMake à appeler lors de la génération du projet. Visual Studio remplit automatiquement cette propriété si vous entrez launch.vs.json à partir du menu Déboguer ou de la vue des cibles. Cette valeur doit correspondre au nom d’une cible de débogage existante répertoriée dans la liste déroulante Élément de démarrage.
args : arguments de ligne de commande passés au moment du démarrage au programme en cours de débogage.
processID : ID de processus Linux auquel attacher. Utilisé uniquement lors de l’attachement à un processus distant. Pour plus d’informations, consultez Résoudre les problèmes liés à l’attachement aux processus à l’aide de GDB.
program : la valeur par défaut est "${debugInfo.fullTargetPath}". Chemin Unix de l’application à déboguer. Obligatoire uniquement s’il est différent de l’exécutable cible dans l’emplacement de génération ou de déploiement.
remoteMachineName : la valeur par défaut est "${debugInfo.remoteMachineName}". Nom du système distant qui héberge le programme à déboguer. Obligatoire uniquement s’il est différent du système de génération. Une entrée doit exister dans le Gestionnaire des connexions. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.
cwd : la valeur par défaut est "${debugInfo.defaultWorkingDirectory}". Chemin d’accès Unix complet vers le répertoire sur le système distant où program est exécuté. Le répertoire doit exister.

environment : variables d’environnement supplémentaires passées au programme en cours de débogage. Par exemple :

  "environment": [
      {
        "name": "ENV1",
        "value": "envvalue1"
      },
      {
        "name": "ENV2",
        "value": "envvalue2"
      }
    ]

pipeArgs : tableau d’arguments de ligne de commande passés au programme pipe pour configurer la connexion. Le programme pipe est utilisé pour relayer les entrées/sorties standard entre Visual Studio et gdb. La plupart de ce tableau n’a pas besoin d’être personnalisé lors du débogage de projets CMake. L’exception est ${debuggerCommand}, qui lance gdb sur le système distant. Il peut être modifié pour :
- Exporter la valeur de la variable d’environnement DISPLAY sur votre système Linux. Dans l’exemple suivant, cette valeur est :1.
```
"pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "export DISPLAY=:1;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],
```
- Exécuter un script avant l’exécution de gdb. Vérifiez que les autorisations d’exécution sont définies sur votre script.
```
"pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "/path/to/script.sh;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],
```
stopOnEntry : valeur booléenne qui spécifie s’il faut s’arrêter dès le lancement du processus. La valeur par défaut est false.
visualizerFile : fichier .natvis à utiliser lors du débogage de ce processus. Cette option n’est pas compatible avec l’impression en mode Pretty gdb. Définissez également showDisplayString lorsque vous définissez cette propriété.
showDisplayString : valeur booléenne qui active la chaîne d’affichage lorsqu’une option visualizerFile est spécifiée. Définir cette option sur true peut entraîner un ralentissement des performances pendant le débogage.
setupCommands : une ou plusieurs commandes gdb à exécuter pour configurer le débogueur sous-jacent.
miDebuggerPath : chemin d’accès complet à gdb. S’il n’est pas spécifié, Visual Studio recherche d’abord le débogueur dans PATH.
Enfin, toutes les options de déploiement définies pour le type de configuration cppgdb peuvent également être utilisées par le type de configuration cppdbg.

Débogage à l’aide de `gdbserver`

Vous pouvez configurer la configuration de cppdbg pour déboguer à l’aide de gdbserver. Vous trouverez plus d’informations et un exemple de configuration de lancement dans le billet de blog de l’équipe Microsoft C++ sur le débogage des projets CMake Linux avec gdbserver.

Voir aussi

Projets CMake dans Visual Studio
Configurer un projet CMake Linux
Se connecter à un ordinateur Linux distant
Personnaliser les paramètres de génération CMake
Configurer des sessions de débogage CMake
Déployer, exécuter et déboguer un projet Linux
Informations de référence sur la configuration prédéfinie de CMake

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-11-07

Partager via

Configurer des sessions de débogage CMake

Personnaliser les paramètres du débogueur

Clés de référence dans CMakeSettings.json

Informations de référence sur launch.vs.json

Informations de référence sur launch.vs.json pour les projets distants et WSL

Type de configuration cppgdb

Options supplémentaires pour la configuration de gdb

Options supplémentaires autorisées avec la configuration de gdbserver (version 16.7 ou ultérieure)