{"id":13994644,"url":"https://github.com/getsentry/symbolic","last_synced_at":"2025-05-13T21:07:49.194Z","repository":{"id":37925925,"uuid":"102011536","full_name":"getsentry/symbolic","owner":"getsentry","description":"Stack trace symbolication library written in Rust","archived":false,"fork":false,"pushed_at":"2025-05-02T10:06:35.000Z","size":24485,"stargazers_count":493,"open_issues_count":8,"forks_count":79,"subscribers_count":60,"default_branch":"master","last_synced_at":"2025-05-07T05:57:05.115Z","etag":null,"topics":["symbolication","tag-production"],"latest_commit_sha":null,"homepage":"https://github.com/getsentry/symbolic#readme","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getsentry.png","metadata":{"funding":{"custom":["https://sentry.io/pricing/","https://sentry.io/"]},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-08-31T14:48:11.000Z","updated_at":"2025-05-02T10:06:39.000Z","dependencies_parsed_at":"2023-09-27T16:11:33.481Z","dependency_job_id":"2c429a50-432a-452d-997f-44d36ccd302d","html_url":"https://github.com/getsentry/symbolic","commit_stats":{"total_commits":1277,"total_committers":51,"mean_commits":25.03921568627451,"dds":0.711824588880188,"last_synced_commit":"3b2f1f6664c9b71f8138acdde5cb8213035eda0e"},"previous_names":[],"tags_count":162,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsymbolic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsymbolic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsymbolic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsymbolic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getsentry","download_url":"https://codeload.github.com/getsentry/symbolic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254028871,"owners_count":22002280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["symbolication","tag-production"],"created_at":"2024-08-09T14:03:00.794Z","updated_at":"2025-05-13T21:07:44.132Z","avatar_url":"https://github.com/getsentry.png","language":"Rust","readme":"# Symbolic\n\n[![Build Status](https://github.com/getsentry/symbolic/workflows/CI/badge.svg)](https://github.com/getsentry/symbolic/actions?workflow=CI)\n\u003ca href=\"https://crates.io/crates/symbolic\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/symbolic.svg\" alt=\"\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.python.org/pypi/Symbolic\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/symbolic.svg\" alt=\"\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/getsentry/symbolic/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/pypi/l/Symbolic.svg\" alt=\"\"\u003e\u003c/a\u003e\n[![codecov](https://codecov.io/gh/getsentry/symbolic/branch/master/graph/badge.svg?token=suNHZfbjKW)](https://codecov.io/gh/getsentry/symbolic)\n\n[Symbolic](https://docs.rs/symbolic) is a library written in Rust which is used at\n[Sentry](https://sentry.io/) to implement symbolication of native stack traces, sourcemap handling\nfor minified JavaScript and more. It consists of multiple largely independent crates which are\nbundled together into a C and Python library so it can be used independently of Rust.\n\n## What's in the package\n\nSymbolic provides the following functionality:\n\n- Symbolication based on custom cache files (symcache)\n- Symbol cache file generators from:\n  - Mach, ELF and PE symbol tables\n  - Mach, ELF and PE embedded DWARF data\n  - PDB CodeView debug information\n  - .NET Portable PDB\n  - Breakpad symbol files\n  - Unity IL2CPP\n- Demangling support\n  - C++ (GCC, clang and MSVC)\n  - Objective C / Objective C++\n  - Rust\n  - Swift\n- JavaScript sourcemap expansion\n  - Basic token mapping\n  - Heuristics to find original function names based on minified sources\n  - Indexed sourcemap to sourcemap merging\n- Proguard function mappings\n- Generate Breakpad symbol files from Mach, ELF and PDBs\n- Convenient C and Python library\n- Processing of Unreal Engine 4 native crash reports\n  - Extract and process minidumps\n  - Expose logs and UE4 context information\n\n## Rust Usage\n\nThe Rust crates are published to [Crates.io](https://crates.io/crates/symbolic) and documentation is available on [docs.rs](https://docs.rs/symbolic/latest/symbolic/).\n\n## Python Usage\n\nSymbolic is hosted on [PyPI](https://pypi.python.org/pypi/symbolic). It comes as a library with\nprebuilt wheels for linux and macOS. On other operating systems or when using as rust library, you\nneed to build symbolic manually. It should be compatible with both Python 2 and Python 3.\n\nThe python library ships all of the above features in a flat module:\n\n```python\nfrom symbolic import Archive\n\nfat = Archive.open('/path/to/object')\nobj = fat.get_object(arch = 'x86_64')\nprint 'object debug id: {}' % obj.debug_id\n```\n\n## C Bindings\n\nSymbolic also offers C bindings, which allow for FFI into arbitrary languages. Have a look at the\nthe [Symbolic C-ABI readme](symbolic-cabi/README.md) for more information.\n\n## Source Crates\n\nA lot of functionality exposed by this library come from independent Rust crates\nfor better use:\n\n- [sourcemap](https://github.com/getsentry/rust-sourcemap)\n- [proguard](https://github.com/getsentry/rust-proguard)\n- [gimli](https://github.com/gimli-rs/gimli)\n- [goblin](https://github.com/m4b/goblin)\n- [pdb](https://github.com/willglynn/pdb)\n\n## Building and Development\n\nTo build the Rust crate, we require the **latest stable Rust**, as well as a C++11 compiler. The\ncrate is split into a workspace with multiple features, so when running building or running tests\nalways make sure to pass the `--all` and `--all-features` flags.\n\n```bash\n# Check whether the crate compiles\ncargo check --all --all-features\n\n# Run Rust tests\ncargo test --all --all-features\n```\n\nWe use `rustfmt` and `clippy` from the latest stable channel for code formatting and linting. To\nmake sure that these tools are set up correctly and running with the right configuration, use the\nfollowing make targets:\n\n```bash\n# Format the entire codebase\nmake format\n\n# Run clippy on the entire codebase\nmake lint\n```\n\nMost likely, new functionality also needs to be added to the Python package. This first requires to\nexpose new functions in the C ABI. For this, refer to the [Symbolic C-ABI readme](symbolic-cabi/README.md).\n\nWe highly recommend to develop and test the python package in a **virtual environment**. Once the\nABI has been updated and tested, ensure the virtualenv is active and install the package, which\nbuilds the native library. There are two ways to install this:\n\n```bash\n# Install the release build, recommended:\npip install --editable ./py\n\n# Install the debug build, faster installation but much slower runtime:\nSYMBOLIC_DEBUG=1 pip install --editable ./py\n```\n\nFor testing, we use ubiquitous `pytest`. Again, ensure that your virtualenv is active and the latest\nversion of the native library has been installed. Then, run:\n\n```bash\n# Run tests manually\npytest ./py/tests\n\n# Creates a new virtualenv, installs the release build and runs tests:\nmake pytest\n```\n\n## Examples\n\nThe repository contains a few examples that show how to use `symbolic` to work with debug files and\nminidumps. Most of these examples can also be used to extract information from such files or verify\ntheir integrity:\n\n- `dump_cfi`: Writes call frame information from an object file to standard out. The output format\n  is Breakpad's `STACK` records.\n\n- `dump_sources`: Creates a source archive from all files referenced by an object file. This is now\n  integrated into `sentry-cli difutil bundle-sources`.\n\n- `minidump_stackwalk`: Extracts stack traces from a minidump and symbolicates them. A path to a\n  directory containing debug information files can be specified.\n\n- `object_debug`: Prints basic information about the contents of an object file.\n\n- `sourcemapcache_debug`: Converts a minified JavaScript file and its corresponding SourceMap into\n  a sourcemapcache and resolves given line/col location.\n\n- `symcache_debug`: Converts an object file into a symcache and prints its contents. Optionally,\n  this can be used to symbolicate a relative address.\n\n- `unreal_engine_crash`: Lists files contained within an Unreal Engine 4 crash archive.\n\nTo run these examples, use the `run` script. For example:\n\n```sh\n./run minidump_stackwalk mini.dmp /path/to/files\n```\n\n## Supported Rust Versions\n\nSymbolic tries to not break MSRV compatibility but makes no guarantees about the Rust version.\nAlthough you can expect Rust version compatibility of **at least 6 months**.\n\nThe current MSRV is 1.73.\n\n## License\n\nSymbolic is licensed under the MIT license. It uses some Apache2 licensed code\nfrom Apple for the Swift demangling.\n","funding_links":["https://sentry.io/pricing/","https://sentry.io/"],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fsymbolic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetsentry%2Fsymbolic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fsymbolic/lists"}