Symbolic

Symbolic 是一个用 Rust 编写的库，用于在 Sentry 中实现原生堆栈跟踪的符号化、压缩 JavaScript 的 sourcemap 处理等。它由多个主要独立的部分组成，这些部分被打包成一个 C 和 Python 库，以便可以独立于 Rust 使用。

包中包含的内容

Symbolic 提供以下功能

• 基于自定义缓存文件（symcache）的符号化
• 从以下生成符号缓存文件：
  • Mach、ELF 和 PE 符号表
  • Mach、ELF 和 PE 嵌入的 DWARF 数据
  • PDB CodeView 调试信息
  • .NET 可移植 PDB
  • Breakpad 符号文件
  • Unity IL2CPP
• Demangling 支持
  • C++（GCC、clang 和 MSVC）
  • Objective C / Objective C++
  • Rust
  • Swift
• JavaScript sourcemap 扩展
  • 基本令牌映射
  • 基于压缩源代码的启发式算法以查找原始函数名称
  • 索引 sourcemap 与 sourcemap 合并
• Proguard 函数映射
• 从 Mach、ELF 和 PDB 生成 Breakpad 符号文件
• 方便的 C 和 Python 库
• 处理 Unreal Engine 4 原生崩溃报告
  • 提取和处理 minidumps
  • 公开日志和 UE4 上下文信息

Rust 使用方法

Rust 的 crate 发布在 Crates.io，文档可在 docs.rs 上找到。

Python 使用方法

Symbolic 存放在 PyPI 上。它作为一个库，提供了为 Linux 和 macOS 预构建的 wheels。在其他操作系统或用作 Rust 库时，需要手动构建 Symbolic。它应与 Python 2 和 Python 3 都兼容。

Python 库将上述所有功能打包在一个平面模块中。

from symbolic import Archive

fat = Archive.open('/path/to/object')
obj = fat.get_object(arch = 'x86_64')
print 'object debug id: {}' % obj.debug_id

C 绑定

Symbolic 还提供了 C 绑定，允许将 FFI（Foreign Function Interface）扩展到任意语言。更多信息请参阅 Symbolic C-ABI README。

源码仓

该库暴露的许多功能来自独立的 Rust 仓，以提高使用效率。

• sourcemap
• proguard
• gimli
• goblin
• pdb

构建和开发

为了构建 Rust 仓，我们需要最新的稳定版 Rust 以及一个 C++11 编译器。该仓被分割为一个包含多个功能的 workspace，因此构建或运行测试时，始终确保传递 --all 和 --all-features 标志。

# Check whether the crate compiles
cargo check --all --all-features

# Run Rust tests
cargo test --all --all-features

我们使用最新稳定通道中的 rustfmt 和 clippy 进行代码格式化和 linting。为了确保这些工具正确设置并使用正确的配置运行，请使用以下 make 目标。

# Format the entire codebase
make format

# Run clippy on the entire codebase
make lint

新功能可能还需要添加到 Python 包中。首先需要将新的函数暴露在 C ABI 中。有关此信息，请参阅 Symbolic C-ABI README。

我们强烈建议在 虚拟环境 中开发和测试 Python 包。一旦 ABI 已更新并测试，确保虚拟环境已激活并安装包，该包构建了本地库。有两种安装方式。

# Install the release build, recommended:
pip install --editable ./py

# Install the debug build, faster installation but much slower runtime:
SYMBOLIC_DEBUG=1 pip install --editable ./py

对于测试，我们使用普遍的 pytest。再次确保虚拟环境已激活，并已安装最新版本的本地库。然后运行。

# Run tests manually
pytest ./py/tests

# Creates a new virtualenv, installs the release build and runs tests:
make pytest

示例

仓库包含一些示例，展示了如何使用 symbolic 与调试文件和 minidumps 交互。大多数这些示例也可以用于从此类文件中提取信息或验证它们的完整性。

• dump_cfi：将对象文件中的调用帧信息写入标准输出。输出格式是 Breakpad 的 STACK 记录。

• dump_sources：从引用对象文件的所有文件创建一个源存档。现在这已集成到 sentry-cli difutil bundle-sources 中。

• minidump_stackwalk：从 minidump 中提取堆栈跟踪并将其符号化。可以指定包含调试信息文件的目录的路径。

• object_debug：打印对象文件内容的基本信息。

• sourcemapcache_debug：将压缩的 JavaScript 文件及其相应的 SourceMap 转换为 sourcemapcache，并解析给定的行/列位置。

• symcache_debug：将对象文件转换为 symcache 并打印其内容。可选地，这可以用来符号化相对地址。

• unreal_engine_crash：列出 Unreal Engine 4 崩溃存档中包含的文件。

要运行这些示例，请使用 run 脚本。例如

./run minidump_stackwalk mini.dmp /path/to/files

许可证

Symbolic 使用 MIT 许可证。它使用 Apple 的 Apache2 许可证的某些代码进行 Swift demangling。