Configurer des sessions de débogage CMake

  • Article

La prise en charge native de CMake est disponible dans Visual Studio 2017 et versions ultérieures. Pour afficher la documentation de ces versions, définissez le contrôle sélecteur de version 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 sont affichées 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.

Screenshot of the CMake startup items dropdown.

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

Screenshot of the CMake Targets View menu.

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.

Screenshot of the CMake Targets View debug option menu.

À 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 Project .

Screenshot of the CMake Debugger dropdown.

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 .vs dossier de 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 vos détails de configuration de débogage. Il existe trois points d’entrée dans ce fichier :

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

Screenshot of the Debug menu command Debug and launch settings for the project.

  • Vue Cibles : accédez à la vue Cibles dans 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.

Screenshot of the Add Debug Configuration command on the shortcut menu for the target.

  • Racine CMakeLists.txt : 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. La 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 projectTarget propriété.

Screenshot of the Select a debugger dialog box.

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 CMake Paramètres.json

Pour référencer n’importe quelle clé dans un fichier CMake Paramètres.json, ajoutez-la cmake. dans launch.vs.json. L’exemple suivant montre un fichier launch.vs.json simple qui extrait la valeur de la remoteCopySources clé dans le fichier CMake Paramètres.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 CMake Paramètres.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érieure, les cibles de débogage sont lancées automatiquement à l’aide de l’environnement que vous spécifiez dans CMake Paramètres.json. Vous pouvez annuler la définition d’une variable d’environnement en la définissant sur Null.

Référence 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ébogage ou de la vue 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 :

    "env": {
      "DEBUG_LOGGING_LEVEL": "trace;info",
      "ENABLE_TRACING": "true"
    }

  • args: arguments de ligne de commande passés au programme pour déboguer.

Référence 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 permettant de type: cppgdb simplifier le débogage sur les systèmes distants et WSL. Les anciennes configurations de débogage sont type: cppdbg 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 relatif du 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ébogage ou de la vue 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 de 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 transmis au démarrage au programme en cours de débogage.
  • env: variables d’environnement supplémentaires transmises 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 aux processus à l’aide de GDB.

Options supplémentaires pour la gdb configuration

  • program : a la valeur par défaut "${debugInfo.fullTargetPath}". Chemin Unix de l’application à déboguer. Obligatoire uniquement s’il est différent de l’exécutable cible dans la build ou l’emplacement de déploiement.
  • remoteMachineName : a la valeur par défaut "${debugInfo.remoteMachineName}". Nom du système distant qui héberge le programme pour déboguer. Obligatoire uniquement s’il est différent du système de build. Doit avoir une entrée existante dans le Gestionnaire Connecter ion. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.
  • cwd : a la valeur par défaut "${debugInfo.defaultWorkingDirectory}". Chemin Unix vers le répertoire sur le système distant où program est exécuté. Le répertoire doit exister.
  • gdbpath : a la valeur par défaut /usr/bin/gdb. Chemin d’accès Unix complet à l’utilisation gdb pour déboguer. Obligatoire uniquement si vous utilisez une version personnalisée de gdb.
  • preDebugCommand: commande Linux à exécuter immédiatement avant l’appel 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 gdbserver configuration (16.7 ou version ultérieure)

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

    Conseil

    Le déploiement n’est pas encore pris en charge pour les scénarios de compilation croisée locale. 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é sur program la machine ARM distante avant le débogage.

  • remoteMachineName : a la valeur par défaut "${debugInfo.remoteMachineName}". Nom du système distant qui héberge le programme pour déboguer. Obligatoire uniquement s’il est différent du système de build. Doit avoir une entrée existante dans le Gestionnaire Connecter ion. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.

  • cwd : a la valeur par défaut "${debugInfo.defaultWorkingDirectory}". Chemin Unix complet vers le répertoire sur le système distant où program est exécuté. Le répertoire doit exister.

  • gdbPath : a la valeur par défaut ${debugInfo.vsInstalledGdb}. Chemin d’accès Windows complet à l’utilisateur gdb utilisé pour déboguer. La valeur par défaut est installée gdb avec le développement Linux avec la charge de travail C/C++.

  • gdbserverPath : a la valeur par défaut usr/bin/gdbserver. Chemin d’accès Unix complet à l’utilisation gdbserver pour déboguer.

  • preDebugCommand: commande Linux à exécuter immédiatement avant le démarrage 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 CMake Paramètres.json) de votre ordinateur de débogage distant.

  • remoteMachineName: ordinateur de débogage distant. Obligatoire uniquement s’il est différent de l’ordinateur de build. Doit avoir une entrée existante dans le Gestionnaire Connecter ion. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.
  • disableDeploy : a la valeur par défaut false. Indique si la séparation de build/débogage est désactivée. Quand false, cette option permet de générer et de déboguer sur deux ordinateurs distincts.
  • deployDirectory: chemin Unix complet vers le répertoire sur remoteMachineName lequel l’exécutable est copié.
  • deploy: tableau de paramètres de déploiement avancés. Vous devez uniquement configurer ces paramètres lorsque vous souhaitez 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 l’ordinateur de débogage distant.
    • sourceMachine: ordinateur à partir duquel 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 Connecter ion. Lorsque vous générez en mode natif sur WSL, cette option est ignorée.
    • targetMachine: ordinateur sur lequel 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 Connecter ion.
    • 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 la copie à partir du système de fichiers local vers le système distant spécifié par remoteMachineNamelaunch.vs.json. RemoteRemotesignifie la copie à partir du système de build distant spécifié dans CMake Paramètres.json vers le 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 personnalisées gdb

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

Activer la journalisation

Activez la journalisation MIEngine pour voir quelles commandes sont envoyées, gdbquelles sorties gdb retournent et combien de temps chaque commande prend. En savoir plus

Type de configuration cppdbg

Les options suivantes peuvent être utilisées lors du débogage sur un système distant ou WSL à l’aide du cppdbg type de configuration. Dans Visual Studio 2019 version 16.6 ou ultérieure, le type cppgdb de configuration 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 relatif du 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ébogage ou de la vue 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 transmis au 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 aux processus à l’aide de GDB.

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

  • remoteMachineName : a la valeur par défaut "${debugInfo.remoteMachineName}". Nom du système distant qui héberge le programme pour déboguer. Obligatoire uniquement s’il est différent du système de build. Doit avoir une entrée existante dans le Gestionnaire Connecter ion. Appuyez sur Ctrl+Espace pour afficher la liste de toutes les connexions distantes existantes.

  • cwd : a la valeur par défaut "${debugInfo.defaultWorkingDirectory}". Chemin 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 transmises 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 transmis au programme de canal pour configurer la connexion. Le programme de canal 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 celle ${debuggerCommand}qui démarre gdb sur le système distant. Il peut être modifié pour :

    • Exportez 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écutez 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: booléen qui spécifie s’il faut 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 gdb l’impression. Définissez également lorsque vous définissez showDisplayString cette propriété.

  • showDisplayString: booléen qui active la chaîne d’affichage lorsqu’une visualizerFile valeur est spécifiée. La définition de cette option true peut entraîner des performances plus lentes pendant le débogage.

  • setupCommands: une ou plusieurs gdb commandes à exécuter pour configurer le débogueur sous-jacent.

  • miDebuggerPath: chemin d’accès complet à gdb. Lorsqu’il n’est pas spécifié, Visual Studio recherche d’abord PATH pour le débogueur.

  • Enfin, toutes les options de déploiement définies pour le cppgdb type de configuration peuvent également être utilisées par le cppdbg type de configuration.

Déboguer à l’aide de gdbserver

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