Symbolic

Symbolic 是一个用Rust编写的库，用于在 Sentry 中实现原生堆栈跟踪的符号化、精简JavaScript的源映射处理等功能。它由多个相对独立的crate组成，这些crate被打包成一个C和Python库，以便可以独立于Rust使用。

包中包含的内容

Symbolic提供以下功能

• 基于自定义缓存文件的符号化
• 从
  • Mach、ELF和PE符号表
  • Mach、ELF和PE内嵌的DWARF数据
  • PDB CodeView调试信息
  • .NET Portable PDB
  • Breakpad符号文件
  • Unity IL2CPP
• 解引用支持
  • C++（GCC、clang和MSVC）
  • Objective C / Objective C++
  • Rust
  • Swift
• JavaScript源映射展开
  • 基本令牌映射
  • 基于精简源代码查找原始函数名的启发式算法
  • 索引源映射到源映射合并
• Proguard函数映射
• 从Mach、ELF和PDB生成Breakpad符号文件
• 方便的C和Python库
• 处理Unreal Engine 4原生崩溃报告
  • 提取和处理最小转储
  • 公开日志和UE4上下文信息

Rust使用

Rust的crate发布到 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的readme。

源代码包

该库大量功能来自于独立的Rust源代码包，以提高其使用性

• sourcemap
• 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的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与调试文件和minidump交互。这些示例中的大多数也可以用于从这些文件中提取信息或验证它们的完整性

• 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解命名。