|
|
@@ -0,0 +1,151 @@
|
|
|
+# Debugging native code
|
|
|
+
|
|
|
+Here we describe some ways to debug an application, and also symbolicate crash logs.
|
|
|
+
|
|
|
+## Debugger
|
|
|
+
|
|
|
+When you get a particularly troublesome issue in your code,
|
|
|
+there are several ways to find the root cause.
|
|
|
+
|
|
|
+The most common way is to run the code via a `debugger`.
|
|
|
+It let's you step through the code, set `breakpoints` and it will stop the execution if you get a crash.
|
|
|
+
|
|
|
+There are several debuggers around for each platform.
|
|
|
+
|
|
|
+* Visual studio - Windows
|
|
|
+* VSCode - Windows, macOS, Linux
|
|
|
+* Android Studio - Windows, macOS, Linux
|
|
|
+* XCode - macOS
|
|
|
+* WinDBG - Windows
|
|
|
+* lldb / gdb - macOS, Linux, (Windows)
|
|
|
+* ios-deply - macOS
|
|
|
+
|
|
|
+And each tool can debug certain platforms:
|
|
|
+
|
|
|
+* Visual studio - Windows + platforms supporting gdbserver (E.g. Linux/Android)
|
|
|
+* VSCode - Windows, macOS (lldb), Linux (lldb/gdb) + platforms supporting gdbserver
|
|
|
+* XCode - macOS, iOS
|
|
|
+* WinDBG - Windows
|
|
|
+* lldb/gdb - macOS, Linux, (iOS)
|
|
|
+* ios-deploy - iOS (via lldb)
|
|
|
+
|
|
|
+
|
|
|
+## Print debugging
|
|
|
+
|
|
|
+In certain cases, one might want to add printf() statements to the code.
|
|
|
+Afterwards, you can get the logs from your device ana analyze them.
|
|
|
+
|
|
|
+Note that Defold by default only prints using dmLog* functions in the debug build.
|
|
|
+
|
|
|
+### Android
|
|
|
+
|
|
|
+On Android, the simplest way to get the log is to run `adb` in the terminal.
|
|
|
+You can also see the `console` inside Android Studio, which is the same thing.
|
|
|
+
|
|
|
+If you get hold of a stack trace from the Android logs, you might be able to symbolicate it using [ndk-stack](https://developer.android.com/ndk/guides/ndk-stack.html)
|
|
|
+
|
|
|
+### iOS
|
|
|
+
|
|
|
+On iOS, you need to open either iTunes or XCode to view the device logs.
|
|
|
+
|
|
|
+## Defold Crash Log
|
|
|
+
|
|
|
+The Defold engine saves a `_crash` file when it does a hard crash.
|
|
|
+It will contain information about the system as well as the crash.
|
|
|
+
|
|
|
+You can use the [crash module](https://www.defold.com/ref/crash/) to read this file in the subsequent session.
|
|
|
+
|
|
|
+You are adviced to read the file, gather information and send it to a server of choice to aggregate the data.
|
|
|
+
|
|
|
+### Getting the crash log from a device
|
|
|
+
|
|
|
+#### Android
|
|
|
+
|
|
|
+The adb output says where it is located (different location on different devices)
|
|
|
+
|
|
|
+If the app is [debuggable](https://www.defold.com/manuals/project-settings/#_android), you can get the crash log like so:
|
|
|
+
|
|
|
+ $ adb shell "run-as com.defold.adtest sh -c 'cat /data/data/com.defold.adtest/files/_crash'" > ./_crash
|
|
|
+
|
|
|
+#### iOS
|
|
|
+
|
|
|
+In iTunes, you can vie/download an apps container.
|
|
|
+
|
|
|
+In the `XCode -> Devices` window, you can also select the crash logs
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+## Symbolication
|
|
|
+
|
|
|
+If you get a callstack from either a `_crash` file or a log file, you can start symbolicate it.
|
|
|
+This means translating each address in the callstack into a filename and line number, which in turn helps
|
|
|
+when finding out the root cause.
|
|
|
+
|
|
|
+### Get correct engine
|
|
|
+
|
|
|
+It is important that you match the correct engine with the callstack.
|
|
|
+Otherwize it's very likely to send you debugging the incorrect things.
|
|
|
+
|
|
|
+Also, if you are building with native extensions, be sure to add the flag [--with-symbols](https://www.defold.com/manuals/bob/)
|
|
|
+so that you get all the needed data from the build server. For instance, in the `build.zip` you'll find the `dmengine.dSYM` folder for iOS/macOS builds.
|
|
|
+
|
|
|
+Android/Linux executables already contain the debug symbols.
|
|
|
+
|
|
|
+Also, you should keep an unstripped version of the engine.
|
|
|
+This allows for the best symbolication of the callstack.
|
|
|
+
|
|
|
+
|
|
|
+### Android
|
|
|
+
|
|
|
+1. Get it from your build folder
|
|
|
+
|
|
|
+ $ ls <project>/build/<platform>/[lib]dmengine[.exe|.so]
|
|
|
+
|
|
|
+1. Unzip to a folder:
|
|
|
+
|
|
|
+ $ unzip dmengine.apk -d dmengine_1_2_105
|
|
|
+
|
|
|
+1. Find the callstack address
|
|
|
+
|
|
|
+ E.g. in the non symbolicated callstack on Crash Analytics, it could look like this
|
|
|
+
|
|
|
+ #00 pc 00257224 libmy_game_name.so
|
|
|
+
|
|
|
+ Where *00257224* is the address
|
|
|
+
|
|
|
+1. Resolve the address
|
|
|
+
|
|
|
+ $ arm-linux-androideabi-addr2line -C -f -e dmengine_1_2_105/lib/armeabi-v7a/libdmengine.so <address>
|
|
|
+
|
|
|
+### iOS
|
|
|
+
|
|
|
+1. If you are using Native Extensions, the server can provide the symbols (.dSYM) for you (pass "--with-symbols" to bob.jar)
|
|
|
+
|
|
|
+ $ unzip <project>/build/arm64-darwin/build.zip
|
|
|
+ # it will produce a Contents/Resources/DWARF/dmengine
|
|
|
+
|
|
|
+1. If you're not using Native Extensions, download the vanilla symbols:
|
|
|
+
|
|
|
+ $ wget http://d.defold.com/archive/<sha1>/engine/arm64-darwin/dmengine.dSYM
|
|
|
+
|
|
|
+1. Symbolicate using load address
|
|
|
+
|
|
|
+ For some reason, simply putting the address from the callstack doesn't work (i.e. load address 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)
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
mathiaswking
