Symbolic

Symbolic 是一个用 Rust 编写的库，在 Sentry 中用于实现本地堆栈跟踪的符号化、处理压缩 JavaScript 的源映射等。它由多个基本独立的 crate 组成，捆绑成一个 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 源映射展开
  • 基本令牌映射
  • 基于压缩源代码查找原始函数名的启发式算法
  • 索引源映射到源映射合并
• Proguard 函数映射
• 从 Mach、ELF 和 PDB 生成 Breakpad 符号文件
• 方便的 C 和 Python 库
• 处理 Unreal Engine 4 原生崩溃报告
  • 提取和处理 minidump
  • 暴露日志和 UE4 上下文信息

Rust 使用

Rust软件包发布到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。有关更多信息，请参阅Symbolic C-ABI说明。

源软件包

此库公开的许多功能都来自独立Rust软件包，以便更好地使用。

• source map
• proguard
• gimli
• goblin
• pdb

构建和开发

要构建Rust软件包，我们需要最新的稳定版Rust，以及C++11编译器。软件包被分割成具有多个特性的工作区，因此运行构建或测试时，请确保传递--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的解名。

lib.rs:

实验性的IL2CPP代码。

此crate不支持，它可能破坏其API，也可能再次完全消失。不要将这部分视为symbolic发布的一部分。这是用于探索Unity IL2CPP调试的实验性代码。