Everyone knows that feeling when you get a “raw” crash and you don’t know what to do — there is nothing more than a lot of addresses. It can happen either because of a crash service fail (e.g. Fabric) or you can get a raw crash from testers, clients or customers’ devices.
DON’T worry. The process of symbolicating return addresses back into human-readable text is rather easy. It takes only a few steps that you can follow in this text. If you are lazy to read, our Youtube video can be of great help 😊.
First of all, you need two files – Crash and dSYM file. You probably already have the crash file if you are reading this article. So let’s go find dSYM file(s).
- You can find
.appfile. In case you can see only .ipa file, decompress it just like an ordinary .zip file and extract .app file from it.
.dSYMfile can be also found in
.xarchivefile. If you have
.appfile you can find
.dSYMfile in this package. Also if you have
.ipafile you can extract
.appfile by decompressing it. It’s just like
- The last option is a derived data folder. You can find
.dSYMfile by the following way: DerivedData -> “YourApp” -> Build -> Products -> “YourDevice”
- You can find
- In the beginning of symbolicating process you need to find the command line tool provided by Apple. The tool is called “symbolicatecrash” and is shipped with Xcode. Open Terminal and write this command:
$ find /Applications -name symbolicatecrash
You will see something like that:
Find the path which contains DVTFoundation.framework. Copy the full path to the clipboard. You will use it later.
- In the next step you set the DEVELOPER_DIR environment variable. Write this command: $ export DEVELOPER_DIR=”/Applications/Xcode.app/Contents/Developer”
- Finally, this is the last step of the process. Paste the previously copied value to the terminal (the path of symbolicatecrash tool). This tool takes two arguments. The first argument is the path to your crash file. The second argument is the path to the dSYM file. So, the final command may look like this: $/Applications/Xcode.app/Contents/SharedFrameworks/DVTFoundation.framework/Versions/A/Resources/symbolicatecrash MyAwesomeCrash.crash MyAwesomeApp.dSYM > Symbolicated.crash
You are done! Pretty simple, right? 😊
At this moment Symbolicated.crash file contains human-readable text. You can see your class name, method name, and file name.
Crash can occur either in a third-party framework or your own framework. So, you have
.dSYM of your App and another
.dSYM file of your framework. Symbolicating this type of crash is very simple. The second parameter of command is
.dSYM path. It can be a path to folder which contains multiple
.dSYMs. It will use all dSYMs in that folder to symbolicate your crash.
I have a confession – I lied a little bit to you. The second parameter of symbolicatecrash tool is rather optional, so you can freely omit it. The symbolicatecrash tool finds correct dSYMs files on your disk and then use them for symbolicating your crash. So, the second parameter is used only for defining another path that will help to search dSYMs files (e.g. flash disc). Following such a method, you can be sure that the tool will use the same path as well…
If it doesn’t work
As it happens, sometimes things don’t work out the way you want them to.. You have to check whether UUID of your
.app and crash match together. It’s also simple – use another command line tool. This tool is called dwarfdump. You can easily extract UUID out of that files with this tool. If you have
.dSYM file named like this “MyAwesomeApp.dSYM” you can write this command in terminal:
$ dwarfdump –uuid MyAwesomeApp.dSYM/Contents/Resources/DWARF/MyAwesomeApp
It returns something like this:
Then you can check if UUIDs match (I mean if crash contains UUID from .dSYM file) by this command:
grep -o -i ‘2d189bea-ffcf-36ef-b8d1-fd4220374034’ MyAwesomeCrash.crash
If you have any questions, please write them in the comments below. Also if you want to understand more deeply this topic, please visit the official Apple documentation.