9.7.2018

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 😊.

Important Files

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).

    1. You can find .dSYM file in .appfile. In case you can see only .ipa file, decompress it just like an ordinary .zip file and extract .app file from it.
    2. .dSYMfile can be also found in .xarchive file. If you have .app file you can find .dSYM file in this package. Also if you have .ipa file you can extract .app file by decompressing it. It’s just like .zip file.
    3. The last option is a derived data folder. You can find .dSYM file by the following way: DerivedData -> “YourApp” -> Build -> Products -> “YourDevice”

 

Symbolicating

  1. 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.
  2. In the next step you set the DEVELOPER_DIR environment variable. Write this command: $ export DEVELOPER_DIR=”/Applications/Xcode.app/Contents/Developer”
  3. 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.

Unsymbolicated

Symbolicated

Multiple dSYMs

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 .dSYM, .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:
UUID:2D189BEA-FFCF-36EF-B8D1-FD4220374034(arm64)MyAwesomeApp.dSYM/Contents/Resources/DWARF/MyAwesomeApp

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.

Libor Polehňa