ETSymbolication
ETSymbolication from Emerge Tools enables symbolicating iOS crash reports with symbols from Apple's private frameworks like SwiftUI.
βοΈ You can use the free symbolicator to symbolicate crash reports with symbols in this repo
π To learn more about this repo, you can read our posts on discovering hidden symbols and building an open-source symbolicator
Features
- Symbolicate all crash reports
- Utilize Apple's crash reporting service for symbol extraction
- Simplify crash analysis and debugging process
Supported Symbols
You will find available symbols inside the Symbols
folder. Each folder inside represents a different device. For example, iPhone 12,8
represents symbols for the iPhone SE 2nd gen. Files in Symbols
correspond to a specific OS version. There can be symbols for multiple frameworks in a single file.
A full list of supported symbols can be found below. All pairings with a β are supported in the Emerge Tools' symbolicator.
Symbols marked with β are in this repo, but not supported in the Emerge Tools symbolicator.
iPhone SE 2nd Gen (iPhone 12,8)
OS Version | SwiftUI |
---|---|
iOS 16.5 (20F66) | β |
iOS 16.5.1 (20F75) | β |
iOS 17.0 Beta 6 (21A5312c) | β |
iOS 17.1.1 (21B91) | β |
iPhone 13 Pro (iPhone 14,2)
OS Version | SwiftUI |
---|---|
iOS 17.2 (21C62) | β |
Contributing
This repo provides the tools to generate symbols for any framework. Symbols are generated for Device x OS x Framework pairings in the Symbols
folder.
- Prerequisites
- Extracting Framework Symbols
- Getting a Framework's linker address
- Building Symbols from Crashes
- Opening a PR for new symbols
Prerequisites
To use ETSymbolication, ensure that you have the following prerequisites:
- macOS
If the required Device x OS x Framework pairing has not been extracted yet:
- iOS Device on the correct version
- An Apple Developer Account
Extracting Framework Symbols
- Open the Xcode Project (
ETSymbolication.xcodeproj
). - Make sure your Framework is listed in the array inside
Libraries.swift
. - Create a new version and upload it to TestFlight.
- Download it on the device you want to work on.
- Open the App.
- Select your app in the picker
- Select the number of threads and the offset to crash with.
- Threads: Each thread is capable of extracting 500 symbols, the more threads you are using, the less crashes you need to fully extract them. But keep in mind that using too many threads may need more time for apple's crash reporting service to make the crash available for download.
- Offset: Since you will need multiple crashes to fully extracts the symbols, the offset parameter is used to indicate at which memory address to start. If we split the full list of symbols a binary has by the number of symbols per crash (threads * 500), the offset indicates which position in the array we will start working from.
- Press crash
- Upload the crash (you can use the feedback field to enter the parameters used)
- Repeat increasing the offset by 1 (and keeping the number of thread fixed) until you see an alert saying
There are no more symbols to extract
.
Getting a Framework's linker address
- Download your device IPSW: https://ipsw.me.
- Install [ipsw](brew install blacktop/tap/ipsw) tool.
brew install blacktop/tap/ipsw
- Extract the shared cache from the IPSW.
ipsw extract --dyld PATH_TO_IPSW
- Install DyldExtractor.
python3 -m pip install git+https://github.com/arandomdev/DyldExtractor#egg=dyldextractor
- Extract your framework.
dyldex -e /System/Library/Frameworks/YOUR_FRAMEWORK.framework/YOUR_FRAMEWORK ./PATH_TO_EXTRACTED_IPSW/dyld_shared_cache_arm64e
- Replace YOUR_FRAMEWORK with your framework name
- The extracted binaries will be located inside a new folder called
binaries/System/Library/Frameworks/YOUR_FRAMEWORK.framework/
.
- Print the binary load commands
otool -l binaries/System/Library/Frameworks/YOUR_FRAMEWORK.framework/YOUR_FRAMEWORK | grep LC_SEGMENT -A8
- Look for the section with
segname __TEXT
and thevmaddr
value will be the linker address.
Example for MetalPerformanceShadersGraph:
otool -l binaries/System/Library/Frameworks/MetalPerformanceShadersGraph.framework/MetalPerformanceShadersGraph | grep LC_SEGMENT -A8
Output:
cmd LC_SEGMENT_64
cmdsize 1112
segname __TEXT
vmaddr 0x00000001800fc000
vmsize 0x0000000000c5c000
fileoff 0
filesize 12959744
maxprot 0x00000005
initprot 0x00000005
The linker adddress is 0x00000001800fc000
Building Symbols from Crashes
- Go to AppStoreConnect.
- Login with your dev account.
- Go to your App -> TestFlight -> Crashes.
- Wait until you see all your crashes and see an button "Open in Xcode" when you hover over the crash (otherwise it will not be ready yet).
- Press over the crash (but not "Open in Xcode") and download the crash to yor computer using the download button on the top right corner.
- Repeat for all the crashes.
- Unzip the downloaded files and place the
*.crash
files inside a new folder. - Execute
SymbolsBuilder
binary with the following parameters:- --csv (output a .csv file)
- --input: path to the folder containing the crashes.
- --output: path to the folder that will have the symbols file.
- --library-name: name of the Framework.
- --library-linker-address: Framework's linker address (it depends on the device and OS). Instructions to get linker address are in the previous section
Opening a PR for new symbols
The SymbolsBuilder
command will output a .csv file with all required symbol data. If you are generating symbols for a Device and OS pairing already in the Symbols
folder, append your symbols to the existing OS file. If the OS does not yet exist, please create a new file with the appropriate OS name.