Utiliser des débogueurs

Cette page détaille l'utilisation de LLDB pour le développement de systèmes d'exploitation. Pour le développement d'applications, consultez plutôt Déboguer votre application , qui explique comment utiliser l'interface graphique d'Android Studio (basée sur LLDB).

GDB n'est plus pris en charge ni fourni. Si vous passez de GDB à LLDB, vous devriez probablement commencer par lire le didacticiel LLDB . Si vous êtes un utilisateur expert de GDB, la mappe de commandes GDB vers LLDB est très utile lors de la transition.

Conditions préalables

Pour utiliser un débogueur :

• Configurez l'environnement de construction avec la commande habituelle envsetup.sh .
• Exécutez la même commande lunch que vous avez utilisée lors de la construction. Notez que l'élément du déjeuner doit correspondre exactement à l'appareil que vous déboguez. Si l'élément du déjeuner ne correspond pas à l'appareil connecté, vous obtiendrez une erreur du type : You used the wrong lunch: TARGET_PRODUCT (aosp_arm64) does not match attached device (xyzabc)
• Connectez votre appareil à la machine.

Pour plus d'aide sur la configuration de votre environnement, consultez Configurer l'environnement .

Débogage d'un binaire

Pour déboguer un binaire que vous avez construit sur votre machine, vous devrez d'abord copier le binaire sur le périphérique, puis lancer le débogueur. Par exemple:

adb push test.exe /data/local/tmp/test.exe
lldbclient.py --port 5038 -r /data/local/tmp/test.exe

Débogage des applications ou des processus en cours d'exécution

Pour vous connecter à une application en cours d'exécution ou à un démon natif, utilisez lldbclient.py avec un PID. Par exemple, pour déboguer le processus avec le PID 1234, exécutez ceci sur l'hôte :

lldbclient.py -p 1234

Le script configure la redirection de port, démarre le stub de débogage distant approprié sur le périphérique, démarre le débogueur sur l'hôte, le configure pour rechercher des symboles et le connecte au stub de débogage distant.

Débogage du démarrage du processus natif

Pour déboguer un processus au démarrage, utilisez lldbclient.py avec l'option -r . Par exemple, pour déboguer ls /bin , exécutez ceci sur l'hôte :

lldbclient.py -r /system/bin/ls /bin

Ensuite, entrez continue à l'invite du débogueur.

Démarrage de l'application de débogage

Parfois, vous souhaitez déboguer une application au démarrage, par exemple en cas de crash et vous souhaitez parcourir le code pour voir ce qui s'est passé avant le crash. La pièce jointe fonctionne dans certains cas, mais dans d'autres cas, elle est impossible car l'application se bloque avant que vous puissiez la joindre. L'approche logwrapper (utilisée pour strace ) ne fonctionne pas toujours car l'application peut ne pas avoir les autorisations nécessaires pour ouvrir un port et lldbserver hérite de cette restriction.

Pour déboguer le démarrage de l'application, utilisez les options de développement dans Paramètres pour demander à l'application d'attendre qu'un débogueur Java se connecte :

1. Accédez à Paramètres > Options du développeur > Sélectionnez l'application de débogage et choisissez votre application dans la liste, puis cliquez sur Attendre le débogueur .
2. Démarrez l'application, soit depuis le lanceur, soit en utilisant la ligne de commande pour l'exécuter :

   adb shell am start -a android.intent.action.MAIN -n APP_NAME/.APP_ACTIVITY
   

3. Attendez que l'application se charge et qu'une boîte de dialogue apparaisse vous indiquant que l'application attend un débogueur.
4. Attachez normalement lldbserver / lldbclient , définissez des points d'arrêt, puis continuez le processus.

Pour permettre à l'application de s'exécuter, attachez un débogueur Java Debug Wire Protocol (JDWP) tel que Java Debugger (jdb) :

adb forward tcp:12345 jdwp:XXX  # (Where XXX is the PID
of the debugged process.)
jdb -attach localhost:12345

Débogage d'applications ou de processus qui plantent

Si vous souhaitez debuggerd suspende les processus en panne afin de pouvoir attacher un débogueur, définissez la propriété appropriée :

• Après Android 11

  adb shell setprop debug.debuggerd.wait_for_debugger true
  

• Android 11 et versions antérieures

  adb shell setprop debug.debuggerd.wait_for_gdb true
  

• Android 6.0 Marshmallow et version inférieure

  adb shell setprop debug.db.uid 999999
  

À la fin de la sortie de crash habituelle, debuggerd fournit des instructions de copier-coller dans logcat montrant comment connecter le débogueur au processus en panne.

Débogage avec VS Code

LLDB prend en charge le code de la plateforme de débogage sur Visual Studio Code . Vous pouvez utiliser l'interface du débogueur VS Code au lieu de l'interface CLI LLDB pour contrôler et déboguer le code natif exécuté sur les appareils.

Avant d'utiliser VS Code pour le débogage, installez l' extension CodeLLDB .

Pour déboguer du code à l’aide de VS Code :

1. Assurez-vous que tous les artefacts de build (tels que les symboles) requis pour exécuter lldbclient.py ou lldbclient.py sont présents.
2. Dans VS Code, appuyez sur Ctrl+Shift+P pour exécuter une commande, recherchez Debug: Add Configuration... , puis sélectionnez LLDB . Cela ouvre un fichier launch.json et ajoute un nouvel objet JSON à une liste.
3. Remplacez la configuration du débogueur nouvellement ajoutée par deux lignes de commentaires - // #lldbclient-generated-begin et // #lldbclient-generated-end , afin que votre liste de configuration ressemble à ceci :

   "configurations": [
       // #lldbclient-generated-begin
       // #lldbclient-generated-end
   ]

   lldbclient.py utilise ces commentaires pour détecter où écrire la configuration. S'il y a d'autres éléments dans la liste, ajoutez les lignes de commentaires à la fin après les autres configurations.

4. Exécutez la commande suivante dans le terminal où vous avez exécuté envsetup.sh et lunch :

   lldbclient.py --setup-forwarding vscode-lldb \
         --vscode-launch-file LAUNCH_JSON_PATH \
         ANY_OTHER_FLAGS -p pid | -n proc-name | -r ...

   lldbclient.py écrit la configuration générée dans launch.json et continue de s'exécuter. C'est prévu ; ne tuez pas le programme lldbclient.py . Si vous omettez le --vscode-launch-file le script imprimera l'extrait JSON que vous devrez copier et coller manuellement dans launch.json .

   L'indicateur -r doit être le dernier indicateur s'il est présent en raison de la façon dont les indicateurs sont analysés par l'outil.

5. Ouvrez la barre latérale Exécuter et déboguer - la nouvelle configuration devrait apparaître dans la liste du débogueur. Appuyez sur Démarrer le débogage (F5) . Le débogueur devrait se connecter après 10 à 30 secondes.

   Si la nouvelle configuration n'apparaît pas dans la vue Exécuter et déboguer, rechargez la fenêtre pour actualiser la liste des débogueurs - appuyez sur Ctrl+Shift+P et tapez reload window .

6. Une fois le débogage terminé, accédez au terminal exécutant lldbclient.py et appuyez sur Entrée pour terminer le programme lldbclient.py . Les exécutions ultérieures du script généreraient la configuration entre les commentaires #lldbclient-generated et remplaceraient l'ancien contenu, vous n'avez pas besoin de les supprimer manuellement.

Pour ajouter des propriétés personnalisées à la configuration de lancement générée, vous pouvez utiliser l'indicateur --vscode-launch-props . Par exemple :

lldbclient.py --setup-forwarding vscode-lldb \
    --vscode-launch-props \
    '{"initCommands" : ["script print(\"Hello\")"], "preLaunchTask" : "Build"}' \
    ...

Les exemples de propriétés obligeraient VS Code à exécuter une tâche nommée Build avant le débogage et ajouteraient une nouvelle étape d'initialisation du débogage aux étapes générées par le script. Vous pouvez trouver un aperçu des propriétés disponibles dans la documentation VS Code et dans le manuel d'utilisation de l' extension CodeLLDB .