Utiliser des débogueurs

Cette page explique comment utiliser LLDB pour le développement d'un OS. Pour le développement d'applications, consultez plutôt Déboguer votre application, qui explique comment utiliser l'IUG 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 tutoriel LLDB. Si vous êtes un expert GDB, la carte des commandes GDB vers LLDB est très utile lors de la transition.

Prérequis

Pour utiliser un débogueur:

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

Pour obtenir de l'aide sur la configuration de votre environnement, consultez la section Configurer l'environnement.

Déboguer un binaire

Pour déboguer un binaire que vous avez compilé sur votre machine, vous devez d'abord le copier sur l'appareil, puis lancer le débogueur. Exemple :

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

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

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

lldbclient.py -p 1234

Le script configure le transfert de port, démarre le bouchon de débogage à distance approprié sur l'appareil, démarre le débogueur sur l'hôte, le configure pour rechercher des symboles et le connecte au bouchon de débogage à distance.

Déboguer le 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 la commande suivante sur l'hôte:

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

Saisissez ensuite continue à l'invite du débogueur.

Déboguer le démarrage de l'application

Vous pouvez parfois vouloir déboguer une application au démarrage, par exemple en cas de plantage et si vous souhaitez suivre le code pour voir ce qui s'est passé avant le plantage. L'association fonctionne dans certains cas, mais dans d'autres, elle est impossible, car l'application plante avant que vous ne puissiez l'associer. L'approche logwrapper (utilisée pour strace) ne fonctionne pas toujours, car l'application peut ne pas disposer des 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 pour les développeurs dans les paramètres pour demander à l'application d'attendre qu'un débogueur Java soit associé:

1. Accédez à Settings > Developer options > Select debug app (Paramètres > Options pour les développeurs > Sélectionner une application de débogage), choisissez votre application dans la liste, puis cliquez sur Wait for debugger (Attendre le débogueur).
2. Démarrez l'application à partir du lanceur ou de la ligne de commande:

   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 s'affiche pour vous indiquer qu'elle attend un débogueur.
4. Associez lldbserver/lldbclient normalement, définissez des points d'arrêt, puis poursuivez le processus.

Pour permettre à l'application de s'exécuter, associez un débogueur JDWP (Java Debug Wire Protocol), 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éboguer des applications ou des processus qui plantent

Si vous souhaitez que debuggerd suspende les processus qui plantent afin que vous puissiez joindre 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 ou version antérieure

  adb shell setprop debug.debuggerd.wait_for_gdb true
  

• Android 6.0 Marshmallow et versions antérieures

  adb shell setprop debug.db.uid 999999
  

À la fin de la sortie d'erreur habituelle, debuggerd fournit des instructions de copier-coller dans Logcat pour savoir comment connecter le débogueur au processus en cours d'erreur.

Déboguer avec VS Code

LLDB est compatible avec le débogage du code de la plate-forme dans Visual Studio Code. Vous pouvez utiliser l'interface du débogueur VS Code au lieu de l'interface de la 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 compilation (tels que les symboles) requis pour exécuter lldbclient.py ou lldbclient.py sont présents.
2. Dans VS Code, appuyez sur Ctrl+Maj+P pour exécuter une commande, recherchez Debug: Add Configuration (Déboguer : Ajouter une configuration), puis sélectionnez LLDB. Un fichier launch.json s'ouvre et un nouvel objet JSON est ajouté à une liste.
3. Remplacez la configuration du débogueur nouvellement ajoutée par deux lignes de commentaire : // #lldbclient-generated-begin et // #lldbclient-generated-end, de sorte que votre liste de configuration se présente comme suit :

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

   lldbclient.py utilise ces commentaires pour détecter où écrire la configuration. Si d'autres éléments figurent dans la liste, ajoutez les lignes de commentaire à 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. Ce comportement est normal. Ne fermez pas le programme lldbclient.py. Si vous omettez --vscode-launch-file, le script imprime 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 Run and Debug (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 doit se connecter au bout de 10 à 30 secondes.

   Si la nouvelle configuration n'est pas apparue dans la vue "Exécuter et déboguer", actualisez la fenêtre pour actualiser la liste du débogueur. Appuyez sur Ctrl+Maj+P, puis saisissez reload window.

6. Lorsque vous avez terminé le débogage, accédez au terminal exécutant lldbclient.py et appuyez sur Entrée pour arrêter le programme lldbclient.py. Les exécutions ultérieures du script généreront la configuration entre les commentaires #lldbclient-generated et remplaceront les anciens contenus. 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'option --vscode-launch-props. Exemple :

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