Nativen Code debuggen

Defold ist gut getestet und sollte unter normalen Umständen nur sehr selten abstürzen. Es lässt sich jedoch nicht garantieren, dass es niemals abstürzt, insbesondere wenn dein Spiel native Erweiterungen (native extensions) verwendet. Wenn du Probleme mit Abstürzen oder nativem Code hast, der sich nicht wie erwartet verhält, gibt es verschiedene Vorgehensweisen:

• Einen Debugger verwenden, um den Code schrittweise auszuführen
• Debugging mit Protokollausgaben verwenden
• Ein Absturzprotokoll analysieren
• Einen Aufrufstapel symbolisieren

Einen Debugger verwenden

Am häufigsten wird der Code mit einem Debugger ausgeführt. Damit kannst du den Code schrittweise ausführen und Haltepunkte setzen. Bei einem Absturz hält der Debugger die Ausführung an.

Für jede Plattform gibt es mehrere Debugger.

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

Jedes Werkzeug kann bestimmte Plattformen debuggen:

• Visual studio - Windows + Plattformen, die gdbserver unterstützen (z. B. Linux/Android)
• VSCode - Windows, macOS (lldb), Linux (lldb/gdb) + Plattformen, die gdbserver unterstützen
• Xcode - macOS, iOS (mehr erfahren)
• Android Studio - Android (mehr erfahren)
• WinDBG - Windows
• lldb/gdb - macOS, Linux, (iOS)
• ios-deploy - iOS (über lldb)

Debugging mit Protokollausgaben verwenden

Die einfachste Möglichkeit, deinen nativen Code zu debuggen, ist Debugging mit Protokollausgaben. Verwende die Funktionen im Namensraum dmLog, um Variablen zu beobachten oder den Ausführungsfluss sichtbar zu machen. Alle Protokollfunktionen geben Meldungen in der Ansicht Console im Editor und im Spielprotokoll aus.

Ein Absturzprotokoll analysieren

Die Defold-Engine speichert bei einem schweren Absturz eine Datei namens _crash. Die Absturzdatei enthält Informationen über das System sowie über den Absturz. Die Ausgabe des Spielprotokolls gibt an, wo sich die Absturzdatei befindet (dies hängt vom Betriebssystem, dem Gerät und der Anwendung ab).

Du kannst das crash-Modul verwenden, um diese Datei in der nächsten Sitzung zu lesen. Es wird empfohlen, die Datei zu lesen, die Informationen zusammenzutragen, sie auf der Konsole auszugeben und an einen Analysedienst zu senden, der das Sammeln von Absturzprotokollen unterstützt.

Das Absturzprotokoll von einem Gerät abrufen

Wenn ein Absturz auf einem Mobilgerät auftritt, kannst du die Absturzdatei auf deinen eigenen Computer herunterladen und lokal auswerten.

Android

Wenn die App debuggbar ist, kannst du das Absturzprotokoll mit dem Werkzeug Android Debug Bridge (ADB) und dem Befehl adb shell abrufen:

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

iOS

In iTunes kannst du den Container einer App anzeigen/herunterladen.

Im Fenster Xcode -> Devices kannst du auch die Absturzprotokolle auswählen

Einen Aufrufstapel symbolisieren

Wenn du einen Aufrufstapel (call stack) aus einer Datei namens _crash oder einer Protokolldatei erhältst, kannst du ihn symbolisieren. Dabei wird jede Adresse im Aufrufstapel in einen Dateinamen und eine Zeilennummer umgewandelt, was dabei hilft, die eigentliche Ursache zu finden.

Es ist wichtig, dass du die zum Aufrufstapel passende Engine verwendest. Andernfalls wirst du bei der Fehlersuche sehr wahrscheinlich an der falschen Stelle suchen! Verwende die Option --with-symbols, wenn du mit bob ein Bundle erstellst, oder aktiviere im Dialogfeld zur Bundle-Erstellung im Editor das Kontrollkästchen „Generate debug symbols“:

• iOS - Der Ordner dmengine.dSYM.zip in build/arm64-ios enthält die Debug-Symbole für iOS-Builds.
• macOS - Der Ordner dmengine.dSYM.zip in build/x86_64-macos enthält die Debug-Symbole für macOS-Builds.
• Android - Der Ausgabeordner des Bundles projecttitle.apk.symbols/lib/ enthält die Debug-Symbole für die Zielarchitekturen.
• Linux - Die ausführbare Datei enthält die Debug-Symbole.
• Windows - Die Datei dmengine.pdb in build/x86_64-win32 enthält die Debug-Symbole für Windows-Builds.
• HTML5 - Das Verzeichnis <project_name>_symbols neben dem HTML5-Bundle enthält <project_name>_wasm.js.symbols und, wenn die Architektur wasm_pthread-web ausgewählt ist, <project_name>_pthread_wasm.js.symbols.

Symbole auf Google Play hochladen

Du kannst die Debug-Symbole auf Google Play hochladen, damit alle in Google Play protokollierten Abstürze symbolisierte Aufrufstapel anzeigen. Packe den Inhalt des Ausgabeordners des Bundles projecttitle.apk.symbols/lib/ in ein ZIP-Archiv. Der Ordner enthält einen oder mehrere Unterordner mit Architekturnamen wie arm64-v8a, armeabi-v7a und x86_64.

Einen Android-Aufrufstapel symbolisieren

1. Hole die Engine aus deinem Build-Ordner

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

1. Entpacke sie in einen Ordner:

	$ unzip dmengine.apk -d dmengine_1_2_105

1. Ermittle die Adresse im Aufrufstapel

   In einem nicht symbolisierten Aufrufstapel könnte sie beispielsweise so aussehen

   #00 pc 00257224 libmy_game_name.so

   Dabei ist 00257224 die Adresse

2. Löse die Adresse auf

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

Hinweis: Wenn du einen Stacktrace aus den Android-Protokollen erhältst, kannst du ihn möglicherweise mit ndk-stack symbolisieren

Einen iOS-Aufrufstapel symbolisieren

1. Wenn du native Erweiterungen verwendest, kann der Server dir die Symbole (.dSYM) bereitstellen (übergib --with-symbols an bob.jar)

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

1. Wenn du keine nativen Erweiterungen verwendest, lade die Standardsymbole herunter:

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

1. Symbolisiere mit der Ladeadresse

   Aus irgendeinem Grund funktioniert es nicht, nur die Adresse aus dem Aufrufstapel anzugeben (d. h. mit der Ladeadresse 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

Es funktioniert, wenn du die Ladeadresse zur Adresse addierst:

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