Repository files navigation

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 usingAppCenter. However, if you want to use PLCrashReporter directly, grab the latest release atreleases page.

• 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
• Backtraces for all active threads are provided.
• Provides full register state for the crashed thread.

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

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

In addition to the in-library decoding support, you may use the includedplcrashutil binary to convert crash reports to apple's standard iPhone text format:

plcrashutilconvert --format=iphoneexample_report.plcrash

You can useatos command-line tool to symbolicate the output. For more information about this tool, seeAdding Identifiable Symbol Names to a Crash Report.Future library releases may include built-in re-usable formatters, for outputting alternative formats directly from the phone.

PLCrashReporter can be added to your app viaCocoaPods,Carthage,Swift Package Manager, or by manually adding the binaries to your project.

1. Add the following line to yourPodfile:

   pod'PLCrashReporter'

2. Runpod install to install your newly defined pod and open the project's.xcworkspace.

1. From the Xcode menu, clickFile >Swift Packages >Add Package Dependency.
2. In the dialog that appears, enter the repository URL:https://github.com/microsoft/plcrashreporter.git.
3. In Version, selectUp to Next Major and take the default option.

1. Add the following line to yourCartfile:

   github"microsoft/plcrashreporter"

2. Runcarthage update --use-xcframeworks to fetch dependencies.
3. In Xcode, open your application target'sGeneral settings tab. Drag and dropCrashReporter.xcframework from theCarthage/Build folder into theFrameworks, Libraries and Embedded Content section. For iOS and tvOS, setEmbed toDo not embed. For macoS, setEmbed toEmbed and Sign.

NOTE:Carthage integration doesn't build the dependency correctly in Xcode 12 with flag "--no-use-binaries" or from a specific branch. To make it work, refer tothis instruction.

1. Download thePLCrashReporter frameworks provided as a zip file.
2. Unzip the file and you'll see a folder calledPLCrashReporter that contains subfolders for all supported platforms.
3. Add PLCrashReporter to the project in Xcode:
   • Make sure the Project Navigator is visible (⌘+1).
   • Now drag & dropPLCrashReporter.framework (orPLCrashReporter.xcframework) from the Finder into Xcode's Project Navigator.
   • A dialog will appear, make sure your app target is checked and clickFinish.

   NOTE:PLCrashReporter xcframework contains static binaries for iOS and tvOS, and dynamic binaries for macOS. When adding the framework to your project make sure that inFrameworks, Libraries and Embedded Content sectionEmbed is selected toDo not embed for iOS and tvOS andEmbed and Sign for macOS.PLCrashReporter-Static-{version}.zip is an exception - it contains static frameworks for all platforms.

The following example shows a way how to initialize crash reporter. Please note that enabling in-process crash reporting will conflict with any attached debuggers so make sure thedebugger isn't attached when you crash the app.

@import CrashReporter;...// Uncomment and implement isDebuggerAttached to safely run this code with a debugger.// See: https://github.com/microsoft/plcrashreporter/blob/2dd862ce049e6f43feb355308dfc710f3af54c4d/Source/Crash%20Demo/main.m#L96// if (![self isDebuggerAttached]) {// It is strongly recommended that local symbolication only be enabled for non-release builds.// Use PLCrashReporterSymbolicationStrategyNone for release versions.PLCrashReporterConfig *config = [[PLCrashReporterConfigalloc]initWithSignalHandlerType: PLCrashReporterSignalHandlerTypeMachsymbolicationStrategy: PLCrashReporterSymbolicationStrategyAll];PLCrashReporter *crashReporter = [[PLCrashReporteralloc]initWithConfiguration: config];// Enable the Crash Reporter.NSError *error;if (![crashReporterenableCrashReporterAndReturnError: &error]) {NSLog(@"Warning: Could not enable crash reporter:%@", error);}// }

Checking collected crash report can be done in the following way:

if ([crashReporterhasPendingCrashReport]) {NSError *error;// Try loading the crash report.NSData *data = [crashReporterloadPendingCrashReportDataAndReturnError: &error];if (data ==nil) {NSLog(@"Failed to load crash report data:%@", error);return;    }// Retrieving crash reporter data.    PLCrashReport *report = [[PLCrashReportalloc]initWithData: dataerror: &error];if (report ==nil) {NSLog(@"Failed to parse crash report:%@", error);return;    }// We could send the report from here, but we'll just print out some debugging info instead.NSString *text = [PLCrashReportTextFormatterstringValueForCrashReport: reportwithTextFormat: PLCrashReportTextFormatiOS];NSLog(@"%@", text);// Purge the report.    [crashReporterpurgePendingCrashReport];}

import CrashReporter...// Uncomment and implement isDebuggerAttached to safely run this code with a debugger.// See: https://github.com/microsoft/plcrashreporter/blob/2dd862ce049e6f43feb355308dfc710f3af54c4d/Source/Crash%20Demo/main.m#L96// if (!isDebuggerAttached()) {  // It is strongly recommended that local symbolication only be enabled for non-release builds.  // Use [] for release versions.letconfig=PLCrashReporterConfig(signalHandlerType:.mach, symbolicationStrategy:.all)guardlet crashReporter=PLCrashReporter(configuration: config)else{print("Could not create an instance of PLCrashReporter")return}  // Enable the Crash Reporter.do{try crashReporter.enableAndReturnError()}catchlet error{print("Warning: Could not enable crash reporter:\(error)")}// }

Checking collected crash report can be done in the following way:

  // Try loading the crash report.if crashReporter.hasPendingCrashReport(){do{letdata=try crashReporter.loadPendingCrashReportDataAndReturnError()      // Retrieving crash reporter data.letreport=tryPLCrashReport(data: data)      // We could send the report from here, but we'll just print out some debugging info instead.iflet text=PLCrashReportTextFormatter.stringValue(for: report, with: PLCrashReportTextFormatiOS){print(text)}else{print("CrashReporter: can't convert report to text")}}catchlet error{print("CrashReporter failed to load and parse with error:\(error)")}}  // Purge the report.  crashReporter.purgePendingCrashReport()

• 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. Seethe official Doxygen repository for more information or useHomebrew to install it.
• GraphViz to generate the documentation. Seethe official GraphViz website for more information or useHomebrew to install it.
• protobuf-c to convert Protocol Buffer.proto files to C descriptor code. Seethe official protobuf-c repository for more information or useHomebrew to install it.

• Open a new window for your Terminal.

• Go to PLCrashReporter's root folder and run

  xcodebuild -configuration Release -target'CrashReporter'

  to create binaries for all platforms.

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 andprotobuf-c to convert Protocol Buffer.proto files to C descriptor code.

This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQ or contactopencode@microsoft.com with any additional questions or comments.