Débogage du code natif

Defold est rigoureusement testé et ne devrait que très rarement planter dans des circonstances normales. Il est toutefois impossible de garantir qu’il ne plantera jamais, en particulier si votre jeu utilise des extensions natives. Si vous rencontrez des plantages ou du code natif qui ne se comporte pas comme prévu, plusieurs approches sont possibles :

• Utiliser un débogueur pour parcourir le code pas à pas
• Utiliser le débogage par affichage
• Analyser un journal de plantage
• Symboliquer une pile d’appels

Utiliser un débogueur

L’approche la plus courante consiste à exécuter le code avec un débogueur (debugger). Il vous permet de parcourir le code pas à pas, de définir des points d’arrêt (breakpoints) et arrête l’exécution en cas de plantage.

Plusieurs débogueurs sont disponibles pour chaque plateforme.

• Visual studio - Windows
• VSCode - Windows, macOS, Linux
• Android Studio - Windows, macOS, Linux
• Xcode - macOS
• WinDBG - Windows
• lldb / gdb - macOS, Linux, (Windows)
• ios-deploy - macOS

Chaque outil permet de déboguer certaines plateformes :

• Visual studio - Windows + plateformes prenant en charge gdbserver (p. ex. Linux/Android)
• VSCode - Windows, macOS (lldb), Linux (lldb/gdb) + plateformes prenant en charge gdbserver
• Xcode - macOS, iOS (en savoir plus)
• Android Studio - Android (en savoir plus)
• WinDBG - Windows
• lldb/gdb - macOS, Linux, (iOS)
• ios-deploy - iOS (via lldb)

Utiliser le débogage par affichage

La manière la plus simple de déboguer votre code natif est d’utiliser le débogage par affichage. Utilisez les fonctions de l’espace de noms (namespace) dmLog pour surveiller des variables ou indiquer le déroulement de l’exécution. Toutes les fonctions de journalisation affichent leurs messages dans la vue Console de l’éditeur et dans le journal du jeu.

Analyser un journal de plantage

Le moteur Defold enregistre un fichier _crash en cas de plantage brutal. Ce fichier contient des informations sur le système et sur le plantage. La sortie du journal du jeu indique l’emplacement du fichier de plantage (qui varie selon le système d’exploitation, l’appareil et l’application).

Vous pouvez utiliser le module crash pour lire ce fichier lors de la session suivante. Il est recommandé de lire le fichier, de rassembler les informations, de les afficher dans la console et de les envoyer à un service d’analyse qui prend en charge la collecte des journaux de plantage.

Récupérer le journal de plantage d’un appareil

Si un plantage se produit sur un appareil mobile, vous pouvez télécharger le fichier de plantage sur votre ordinateur et l’analyser localement.

Android

Si l’application autorise le débogage, vous pouvez récupérer le journal de plantage à l’aide de l’outil Android Debug Bridge (ADB) et de la commande adb shell :

$ adb shell "run-as com.defold.example sh -c 'cat /data/data/com.defold.example/files/_crash'" > ./_crash

iOS

Dans iTunes, vous pouvez afficher ou télécharger le conteneur d’une application.

Dans la fenêtre Xcode -> Devices, vous pouvez également sélectionner les journaux de plantage

Symboliquer une pile d’appels

Si vous récupérez une pile d’appels à partir d’un fichier _crash ou d’un fichier journal, vous pouvez la symboliquer. Cela consiste à convertir chaque adresse de la pile d’appels en un nom de fichier et un numéro de ligne, ce qui aide à trouver la cause du problème.

Il est important d’utiliser le moteur correspondant à la pile d’appels, sinon vous risquez fort de déboguer les mauvais éléments ! Utilisez l’option --with-symbols lors de la création d’un bundle avec bob, ou cochez la case « Generate debug symbols » dans la boîte de dialogue de création de bundles de l’éditeur :

• iOS - le dossier dmengine.dSYM.zip dans build/arm64-ios contient les symboles de débogage des builds iOS.
• macOS - le dossier dmengine.dSYM.zip dans build/x86_64-macos contient les symboles de débogage des builds macOS.
• Android - le dossier de sortie du bundle projecttitle.apk.symbols/lib/ contient les symboles de débogage des architectures cibles.
• Linux - l’exécutable contient les symboles de débogage.
• Windows - le fichier dmengine.pdb dans build/x86_64-win32 contient les symboles de débogage des builds Windows.
• HTML5 - le répertoire <project_name>_symbols situé à côté du bundle HTML5 contient <project_name>_wasm.js.symbols et, lorsque l’architecture wasm_pthread-web est sélectionnée, <project_name>_pthread_wasm.js.symbols.

Importer des symboles dans Google Play

Vous pouvez importer les symboles de débogage dans Google Play afin que les piles d’appels des plantages enregistrés dans Google Play soient symboliquées. Créez une archive ZIP du contenu du dossier de sortie du bundle projecttitle.apk.symbols/lib/. Ce dossier comprend un ou plusieurs sous-dossiers portant des noms d’architectures tels que arm64-v8a, armeabi-v7a et x86_64.

Symboliquer une pile d’appels Android

1. Récupérez le moteur dans votre dossier de build

	$ ls <project>/build/<platform>/[lib]dmengine[.exe|.so]

1. Décompressez-le dans un dossier :

	$ unzip dmengine.apk -d dmengine_1_2_105

1. Repérez l’adresse dans la pile d’appels

   Par exemple, dans une pile d’appels non symboliquée, elle pourrait se présenter ainsi

   #00 pc 00257224 libmy_game_name.so

   Où 00257224 est l’adresse

2. Résolvez l’adresse

    $ arm-linux-androideabi-addr2line -C -f -e dmengine_1_2_105/lib/armeabi-v7a/libdmengine.so _address_

Remarque : si vous disposez d’une trace de pile provenant des journaux Android, vous pouvez peut-être la symboliquer avec ndk-stack

Symboliquer une pile d’appels iOS

1. Si vous utilisez des extensions natives, le serveur peut vous fournir les symboles (.dSYM) (passez --with-symbols à bob.jar)

	$ unzip <project>/build/arm64-darwin/build.zip
	# it will produce a Contents/Resources/DWARF/dmengine

1. Si vous n’utilisez pas d’extensions natives, téléchargez les symboles du moteur standard :

	$ wget http://d.defold.com/archive/<sha1>/engine/arm64-darwin/dmengine.dSYM

1. Symboliquez à l’aide de l’adresse de chargement

   Pour une raison inconnue, utiliser simplement l’adresse de la pile d’appels ne fonctionne pas (c’est-à-dire avec l’adresse de chargement 0x0)

		$ atos -arch arm64 -o Contents/Resources/DWARF/dmengine 0x1492c4

# Neither does specifying the load address directly

		$ atos -arch arm64 -o MyApp.dSYM/Contents/Resources/DWARF/MyApp -l0x100000000 0x1492c4

Adding the load address to the address works:

		$ atos -arch arm64 -o MyApp.dSYM/Contents/Resources/DWARF/MyApp 0x1001492c4
		dmCrash::OnCrash(int) (in MyApp) (backtrace_execinfo.cpp:27)