Symbolic

Symbolic 是一个 Rust 编写的库，它被用于 Sentry 来实现原生堆栈跟踪的符号化、精简 JavaScript 的 sourcemap 处理等。它由多个主要独立 Crates 组成，这些 Crates 被捆绑在一起形成 C 和 Python 库，因此可以在 Rust 之外独立使用。

包中包含的内容

Symbolic 提供以下功能

• 基于自定义缓存文件的符号化
• 从
  • 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 Crates 发布到 Crates.io，文档可在 docs.rs 上找到。

Python 使用说明

Symbolic 存放在 PyPI 上。它作为一个库提供预构建的 Linux 和 macOS 轮子。在其他操作系统或作为 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 说明书。

源 Crates

该库公开了许多功能，这些功能来自独立的 Rust Crates，以便更好地使用。

• sourcemap
• proguard
• gimli
• goblin
• pdb

构建和开发

要构建 Rust Crate，我们需要最新的稳定 Rust 以及一个 C++11 编译器。该 Crate 被分成一个具有多个功能的 workspace，因此在构建或运行测试时，请务必传递 --all 和 --all-features 标志。

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

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

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

# Format the entire codebase
make format

# Run clippy on the entire codebase
make lint

新功能很可能还需要添加到 Python 包中。这首先需要通过 C ABI 暴露新函数。有关此信息，请参阅 Symbolic C-ABI 说明书。

我们强烈建议在 虚拟环境 中开发和测试 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。

lib.rs:

处理调用帧信息（堆栈帧信息）。

本crate公开的根类型是CfiCache，它提供了一个高级API，用于从目标文件中提取CFI并序列化为Breakpad处理器能够理解的格式。

背景

调用帧信息（CFI）由处理器用于在堆栈跟踪过程中提高堆栈跟踪的质量。当可执行文件以省略帧指针编译时，调用栈不包含足够的信息来独立解决其帧。CFI包含可以根据当前帧的寄存器值计算帧基本地址的程序。

没有CFI，堆栈跟踪器需要扫描堆栈内存以查找看起来像有效基本地址的值。这通常会产生假阳性。