PLCrashReporter

PLCrashReporter is a reliable open source library that provides an in-process live crash reporting framework for use on iOS, macOS and tvOS. The library detects crashes and generates reports to help your investigation and troubleshooting with the information of application, system, process, thread, etc. as well as stack traces.

The easiest way to use PLCrashReporter is by using AppCenter. However, if you want to use PLCrashReporter directly, grab the latest release at releases page.

Features

• Uses only supported and public APIs/ABIs for crash reporting.
• The most accurate stack unwinding available, using DWARF and Apple Compact Unwind frame data.
• First released in 2008, and used in hundreds of thousands of apps. PLCrashReporter has seen a tremendous amount of user testing.
• Does not interfere with debugging in lldb/gdb
• Easy to integrate with existing or custom crash reporting services.
• Backtraces for all active threads are provided.
• Provides full register state for the crashed thread.

Prerequisites

• Xcode 11 or above.
• Minimum supported platforms: iOS 8, macOS 10.7, tvOS 9, Mac Catalyst 13.0.

Decoding Crash Reports

Crash reports are output as protobuf-encoded messages, and may be decoded using the CrashReporter library or any Google Protocol Buffers decoder.

In addition to the in-library decoding support, you may use the included plcrashutil binary to convert crash reports to apple's standard iPhone text format. This may be passed to the symbolicate tool.

./bin/plcrashutil convert --format=iphone example_report.plcrash | symbolicatecrash Future library releases may include built-in re-usable formatters, for outputting alternative formats directly from the phone.

Building

Prerequisites

• A Mac running macOS compliant with Xcode requirements.
• Xcode 11 or above.

Also, next optional tools are used to build additional resources:

• Doxygen to generate the documentation. See the official Doxygen repository for more information or use Homebrew to install it.
• GraphViz to generate the documentation. See the official GraphViz website for more information or use Homebrew to install it.
• protobuf-c to convert Protocol Buffer .proto files to C descriptor code. See the official protobuf-c repository for more information or use Homebrew to install it.

To build

• Open a new window for your Terminal.

• Go to PLCrashReporter's root folder and run

  xcodebuild -configuration Release -target 'Disk Image'

  to create binaries for all platforms.

• Verify that your iOS and tvOS binaries have Bitcode enabled by running otool -l build/Release-appletv/CrashReporter.framework/Versions/A/CrashReporter | grep __LLVM (adjust the path to the binary as necessary). If you see some output, it means the binary is Bitcode enabled.

Contributing

We are looking forward to your contributions via pull requests.

To contribute to PLCrashReporter, you need the tools mentioned above to build PLCrashReporter for all architectures and protobuf-c to convert Protocol Buffer .proto files to C descriptor code.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Checking out the repository

PLCrashReporter has a dependency on Protocol Buffers implementation in C as a git submodule. Use below command to clone PLCrashReporter repository or update the repository if you have already cloned it.

git clone --recursive https://github.com/microsoft/plcrashreporter.git

git submodule update --init --recursive

ABOUT

This repository contained a custom fork of PLCrashReporter that is not being used any longer.

HockeySDK-iOS v3.5.0 and later and HockeySDK-Mac v2.0 and later are using the official PLCrashReporter code that can be found here: Official PLCrashReporter repository