PLCrashReporter

PLCrashReporter 是一个可靠的开源库，为 iOS、macOS 和 tvOS 提供了进程内实时崩溃报告框架。该库可以检测崩溃并生成报告，帮助你调查和排查问题，提供应用程序、系统、进程、线程等信息以及堆栈跟踪。

使用 PLCrashReporter 最简单的方法是通过 AppCenter。但如果你想直接使用 PLCrashReporter，可以在发布页面获取最新版本。

特性

仅使用受支持的公共 API/ABI 进行崩溃报告。
使用 DWARF 和 Apple Compact Unwind 帧数据提供最精确的堆栈展开。
自 2008 年首次发布以来，已在数十万个应用中使用。PLCrashReporter 经过了大量用户测试。
不干扰 lldb/gdb 调试。
提供所有活动线程的回溯。
为崩溃的线程提供完整的寄存器状态。

先决条件

Xcode 11 或更高版本。
最低支持平台：iOS 11、macOS 10.9、tvOS 11、Mac Catalyst 13.0。

解码崩溃报告

崩溃报告以 protobuf 编码消息的形式输出，可以使用 CrashReporter 库或任何 Google Protocol Buffers 解码器进行解码。

除了库内解码支持外，你还可以使用附带的 plcrashutil 二进制文件将崩溃报告转换为 Apple 标准的 iPhone 文本格式：

plcrashutil convert --format=iphone example_report.plcrash

你可以使用 atos 命令行工具对输出进行符号化。有关此工具的更多信息，请参阅向崩溃报告添加可识别的符号名称。未来的库版本可能会包含内置的可重用格式化程序，用于直接从手机输出替代格式。

将 PLCrashReporter 添加到你的项目

PLCrashReporter 可以通过 CocoaPods、Carthage、Swift Package Manager 或手动将二进制文件添加到项目中来集成到你的应用中。

通过 CocoaPods 集成

在你的 Podfile 中添加以下行：
```
pod 'PLCrashReporter'
```
运行 pod install 安装新定义的 pod，并打开项目的 .xcworkspace。

通过 Swift Package Manager 集成

从 Xcode 菜单中，点击 File > Swift Packages > Add Package Dependency。
在出现的对话框中，输入仓库 URL：https://github.com/microsoft/plcrashreporter.git。
在版本选项中，选择 Up to Next Major 并使用默认选项。

通过 Carthage 集成

在你的 Cartfile 中添加以下行：
```
github "microsoft/plcrashreporter"
```
运行 carthage update --use-xcframeworks 获取依赖。
在 Xcode 中，打开应用程序目标的 General 设置选项卡。将 Carthage/Build 文件夹中的 CrashReporter.xcframework 拖放到 Frameworks, Libraries and Embedded Content 部分。对于 iOS 和 tvOS，将 Embed 设置为 Do not embed。对于 macOS，将 Embed 设置为 Embed and Sign。

注意： 在 Xcode 12 中，使用 "--no-use-binaries" 标志或从特定分支进行 Carthage 集成时无法正确构建依赖项。要解决这个问题，请参考这个说明。

通过将二进制文件复制到项目中进行集成

下载作为 zip 文件提供的 PLCrashReporter 框架。
解压文件，你会看到一个名为 PLCrashReporter 的文件夹，其中包含所有支持平台的子文件夹。
在 Xcode 中将 PLCrashReporter 添加到项目中：
- 确保项目导航器可见（⌘+1）。
- 现在将 PLCrashReporter.framework（或 PLCrashReporter.xcframework）从 Finder 拖放到 Xcode 的项目导航器中。
- 会出现一个对话框，确保选中你的应用目标，然后点击 Finish。
注意： PLCrashReporter xcframework 包含 iOS 和 tvOS 的静态二进制文件，以及 macOS 的动态二进制文件。将框架添加到项目时，确保在 Frameworks, Libraries and Embedded Content 部分中，iOS 和 tvOS 的 Embed 选项设置为 Do not embed，macOS 设置为 Embed and Sign。PLCrashReporter-Static-{version}.zip 是一个例外 - 它包含所有平台的静态框架。

示例

以下示例展示了如何初始化崩溃报告器。请注意，启用进程内崩溃报告会与任何附加的调试器冲突，所以在崩溃应用程序时请确保未附加调试器。

Objective-C

@import CrashReporter;

...

// 取消注释并实现 isDebuggerAttached 以安全地运行此代码和调试器。
// 参见：https://github.com/microsoft/plcrashreporter/blob/2dd862ce049e6f43feb355308dfc710f3af54c4d/Source/Crash%20Demo/main.m#L96
// if (![self isDebuggerAttached]) {

// 强烈建议仅为非发布版本启用本地符号化。
// 对于发布版本，使用 PLCrashReporterSymbolicationStrategyNone。
PLCrashReporterConfig *config = [[PLCrashReporterConfig alloc] initWithSignalHandlerType: PLCrashReporterSignalHandlerTypeMach
                                                                   symbolicationStrategy: PLCrashReporterSymbolicationStrategyAll];
PLCrashReporter *crashReporter = [[PLCrashReporter alloc] initWithConfiguration: config];

// 启用崩溃报告器。
NSError *error;
if (![crashReporter enableCrashReporterAndReturnError: &error]) {
    NSLog(@"警告：无法启用崩溃报告器：%@", error);
}
// }

检查收集到的崩溃报告可以通过以下方式进行：

if ([crashReporter hasPendingCrashReport]) {
    NSError *error;

    // 尝试加载崩溃报告。
    NSData *data = [crashReporter loadPendingCrashReportDataAndReturnError: &error];
    if (data == nil) {
        NSLog(@"加载崩溃报告数据失败：%@", error);
        return;
    }

    // 检索崩溃报告器数据。
    PLCrashReport *report = [[PLCrashReport alloc] initWithData: data error: &error];
    if (report == nil) {
        NSLog(@"解析崩溃报告失败：%@", error);
        return;
    }

// 我们可以从这里发送报告，但我们只会打印一些调试信息。 NSString *text = [PLCrashReportTextFormatter stringValueForCrashReport: report withTextFormat: PLCrashReportTextFormatiOS]; NSLog(@"%@", text);

// 清除报告。 [crashReporter purgePendingCrashReport]; }


### Swift

```swift 
import CrashReporter

...
// 取消注释并实现isDebuggerAttached以安全地使用调试器运行此代码。
// 参见：https://github.com/microsoft/plcrashreporter/blob/2dd862ce049e6f43feb355308dfc710f3af54c4d/Source/Crash%20Demo/main.m#L96
// if (!isDebuggerAttached()) {

  // 强烈建议仅为非发布版本启用本地符号化。
  // 发布版本使用[]。
  let config = PLCrashReporterConfig(signalHandlerType: .mach, symbolicationStrategy: .all)
  guard let crashReporter = PLCrashReporter(configuration: config) else {
    print("无法创建PLCrashReporter实例")
    return
  }

  // 启用崩溃报告器。
  do {
    try crashReporter.enableAndReturnError()
  } catch let error {
    print("警告：无法启用崩溃报告器：\(error)")
  }
// }

可以通过以下方式检查收集的崩溃报告：

  // 尝试加载崩溃报告。
  if crashReporter.hasPendingCrashReport() {
    do {
      let data = try crashReporter.loadPendingCrashReportDataAndReturnError()

      // 获取崩溃报告器数据。
      let report = try PLCrashReport(data: data)

      // 我们可以从这里发送报告，但我们只会打印一些调试信息。
      if let text = PLCrashReportTextFormatter.stringValue(for: report, with: PLCrashReportTextFormatiOS) { 
        print(text)
      } else {
        print("崩溃报告器：无法将报告转换为文本")
      }
    } catch let error {
      print("崩溃报告器加载和解析失败，错误：\(error)")
    }
  }

  // 清除报告。
  crashReporter.purgePendingCrashReport()

构建

先决条件

运行符合Xcode要求的macOS的Mac电脑。
Xcode 11或更高版本。

此外，以下可选工具用于构建额外资源：

Doxygen用于生成文档。更多信息请参见Doxygen官方仓库，或使用Homebrew安装。
GraphViz用于生成文档。更多信息请参见GraphViz官方网站，或使用Homebrew安装。
protobuf-c用于将Protocol Buffer .proto文件转换为C描述符代码。更多信息请参见protobuf-c官方仓库，或使用Homebrew安装。

构建

打开一个新的终端窗口。
进入PLCrashReporter的根目录并运行
```
xcodebuild -configuration Release -target 'CrashReporter'
```
以创建所有平台的二进制文件。

贡献

我们期待您通过拉取请求做出贡献。

要为PLCrashReporter做出贡献，您需要上述工具来为所有架构构建PLCrashReporter，并使用protobuf-c将Protocol Buffer .proto文件转换为C描述符代码。

行为准则

本项目采用了Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题或联系opencode@microsoft.com提出任何其他问题或意见。