An up-to-date guide to using PLCrashReporter in your app

A while back, I received an email from a user of Rest.app that it was crashing for him a couple of seconds after start. I tried to replicate the issue by asking for the app settings and running it on the same OS version as he did, but I couldn’t pintpoint the problem. I did try to tighten up a few code areas that I thought might be the cause, but I didn’t have anything solid.

So I went looking for a framework, a library or a piece of code – anything that I could add to my app to log the crash in more detail. One of the most mentioned frameworks was PLCrashReporter, so I decided to try it. I spent some time on that, as it took a while to figure out what I needed to do exactly, especially since most of the posts I could find online were for iOS projects, or a bit outdated. It didn’t help that 10.9 introduced a couple more complications along the way, either. So, here’s a small guide/documentation of my efforts, hoping it might help someone in the same boat as I was.

The first thing we want to do is grab the PLCrashReporter framework. Just head to the PLCrashReporter.org website and hit the Download button. Get the v1.2-rc2 – Release Candidate (or newer) binary download.

Once you’ve opened the, drag the CrashReporter.framework to your project.

It should appear as in the screenshot above.

Also, make sure you drag appropriate framework (Mac OS X Framework) in my case, otherwise you’ll be getting an error like the following:

dyld: Library not loaded: @rpath/CrashReporter.framework/Versions/A/CrashReporter
Referenced from: /Users/dinoangelov/Library/Developer/Xcode/DerivedData/Rest-cjwrouqdhixsimfajjtvuymwxzjt/Build/Products/Debug/    Rest.app/Contents/MacOS/Rest
Reason: no suitable image found.  Did find:
/Users/dinoangelov/Library/Developer/Xcode/DerivedData/Rest-cjwrouqdhixsimfajjtvuymwxzjt/Build/Products/Debug/Rest.app/Contents/MacOS/../Frameworks/CrashReporter.framework/Versions/A/CrashReporter: no matching architecture in universal wrapper (lldb)

Note the last line.

Anyway, once you’ve dragged the framework in your project, you still need to do a couple of things.

First, you need to make sure the library is linked to your target, under Build Phases.

Then, you need to make sure the framework is actually included in your app bundle. Add a new build phase (in Xcode 5, that’s Editor > Add Build Phase > Add Copy Files Build Phase.

You can drag the framework in the item list.

Also, make sure you set your search paths, otherwise you’ll be getting the following error:

dyld: Library not loaded: @rpath/CrashReporter.framework/Versions/A/CrashReporter
Referenced from: /Users/dinoangelov/Library/Developer/Xcode/DerivedData/Rest-cjwrouqdhixsimfajjtvuymwxzjt/Build/Products/Debug/Rest.app/Contents/MacOS/Rest
Reason: image not found

You can do so by setting the ‘Runpath Search Paths’ (LD_RUNPATH_SEARCH_PATHS) to @executable_path/../Frameworks on your application target. You can find them under Build Settings.

Finally, we should be good to go and build the project. If you’re on Mavericks (OS X 10.9) though, there’s one more step to follow. You might get the following error on Mavericks:

Command /usr/bin/codesign failed with exit code 1

I followed the steps suggested at Furbo.org: Code Signing and Mavericks and that did the trick. Here’s the exact shell script code i used:

LOCATION="${BUILT_PRODUCTS_DIR}"/"${FRAMEWORKS_FOLDER_PATH}"
IDENTITY="3rd Party Mac Developer Application: Dino Angelov (*******)"
codesign --verbose --force --sign "$IDENTITY" "$LOCATION/CrashReporter.framework/Versions/A"

If you’re unsure the full name of the identity, just type “3rd Party Mac Developer” and it should work. If it matches more than 1 profile, it will complain about ambiguity, and it will show you in the error log which identities matched what you typed. Just pick one and copy and paste the full name into the script above and you’re all set.

If something doesn’t work, and you try a different step/fix to get things to work, make sure you Product > Clean first, otherwise Xcode may not reflect your changes.

As a last note, make sure you save your dSYM files – they are usually generated and kept in the Xcode archives for your project, should you use Product > Archive from Xcode. You will need those later to make the error reports a bit more readable. Read more about symbolication and dSYM files.

Thanks to Landon Fuller & Mike Ash from Plausible Labs (the company behind PLCrashReporter) and dirkg from the #macdev irc channel for all their help in making this work.

PS: I’m probably going to be writing a web/server component too, to accept the data from PLCrashReporter – I’ll update this guide with any links if I do so.

UPDATE 23.02.2014 I also wrote a little helper app that might help you symbolicate those crash reports, if you’re having trouble with the official way. Note that it’s very rough/early alpha, so it provides little information, but potentially more than the standard route. Get it here.

UPDATE 21.04.2016 This project is now dead. Crashlytics is a much, MUCH better alternative — and free.