{"id":20149050,"url":"https://github.com/emergetools/etsymbolication","last_synced_at":"2025-04-07T06:11:27.262Z","repository":{"id":212334233,"uuid":"657256911","full_name":"EmergeTools/ETSymbolication","owner":"EmergeTools","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-10T17:13:54.000Z","size":16361,"stargazers_count":103,"open_issues_count":2,"forks_count":4,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-05T14:36:05.285Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","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/EmergeTools.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-22T16:54:16.000Z","updated_at":"2025-03-13T01:41:44.000Z","dependencies_parsed_at":"2025-01-14T12:12:04.649Z","dependency_job_id":"e23a6a30-1561-4fa7-8ada-fe1ecd68bd8f","html_url":"https://github.com/EmergeTools/ETSymbolication","commit_stats":null,"previous_names":["emergetools/etsymbolication"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmergeTools%2FETSymbolication","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmergeTools%2FETSymbolication/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmergeTools%2FETSymbolication/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmergeTools%2FETSymbolication/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EmergeTools","download_url":"https://codeload.github.com/EmergeTools/ETSymbolication/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601448,"owners_count":20964864,"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":[],"created_at":"2024-11-13T22:41:04.815Z","updated_at":"2025-04-07T06:11:27.233Z","avatar_url":"https://github.com/EmergeTools.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ETSymbolication\n\nETSymbolication from [Emerge Tools](https://www.emergetools.com/) enables symbolicating iOS crash reports with symbols from Apple's private frameworks like SwiftUI.\n\n⭐️ You can use the [free symbolicator](https://www.emergetools.com/symbolicate) to symbolicate crash reports with symbols in this repo\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\".github/images/symbolicate.gif\" width=\"700\"/\u003e\n\u003c/p\u003e\n\n📚 To learn more about this repo, you can read our posts on [discovering hidden symbols](https://www.emergetools.com/blog/posts/symbolicating-swiftui-and-any-apple-framework) and [building an open-source symbolicator](https://www.emergetools.com/blog/posts/symbolicating-swiftui-and-any-apple-framework-part-2)\n\n## Features\n\n- Symbolicate all crash reports\n- Utilize Apple's crash reporting service for symbol extraction\n- Simplify crash analysis and debugging process\n\n## Supported Symbols\n\nYou 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.\n\nA full list of supported symbols can be found below. All pairings with a ✅ are supported in the Emerge Tools' [symbolicator](https://www.emergetools.com/symbolicate).\n\nSymbols marked with ❎ are in this repo, but not supported in the Emerge Tools symbolicator.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e\u003cfont size=\"+1\"\u003eiPhone SE 2nd Gen (iPhone 12,8)\u003c/font\u003e\u003c/b\u003e\u003c/summary\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eOS Version\u003c/th\u003e\n    \u003cth style=\"text-align: center;\"\u003eSwiftUI\u003c/th\u003e \n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eiOS 16.5 (20F66)\u003c/td\u003e\n    \u003ctd style=\"text-align: center;\"\u003e\u003ccenter\u003e✅\u003c/center\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eiOS 16.5.1 (20F75)\u003c/td\u003e\n  \u003ctd style=\"text-align: center;\"\u003e\u003ccenter\u003e✅\u003c/center\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eiOS 17.0 Beta 6 (21A5312c)\u003c/td\u003e\n  \u003ctd style=\"text-align: center;\"\u003e\u003ccenter\u003e✅\u003c/center\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eiOS 17.1.1 (21B91)\u003c/td\u003e\n  \u003ctd style=\"text-align: center;\"\u003e\u003ccenter\u003e✅\u003c/center\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e\u003cfont size=\"+1\"\u003eiPhone 13 Pro (iPhone 14,2)\u003c/font\u003e\u003c/b\u003e\u003c/summary\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eOS Version\u003c/th\u003e\n    \u003cth style=\"text-align: center;\"\u003eSwiftUI\u003c/th\u003e \n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eiOS 17.2 (21C62)\u003c/td\u003e\n    \u003ctd style=\"text-align: center;\"\u003e\u003ccenter\u003e❎\u003c/center\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n## Contributing\n\nThis repo provides the tools to generate symbols for any framework. Symbols are generated for Device x OS x Framework pairings in the `Symbols` folder.\n\n**⚠️ Refer to [supported symbols](#supported-symbols) to ensure the symbols you're looking for aren't already generated.**\n\n- [Prerequisites](#prerequisites)\n- [Extracting Framework Symbols](#extracting-framework-symbols)\n- [Getting a Framework's linker address](#getting-a-frameworks-linker-address)\n- [Building Symbols from Crashes](#building-symbols-from-crashes)\n- [Opening a PR for new symbols](#opening-a-pr-for-new-symbols)\n\n### Prerequisites\n\nTo use ETSymbolication, ensure that you have the following prerequisites:\n\n- macOS\n\nIf the required Device x OS x Framework pairing has not been extracted yet:\n\n- iOS Device on the correct version\n- An Apple Developer Account\n\n### Extracting Framework Symbols\n\n1. Open the Xcode Project (`ETSymbolication.xcodeproj`).\n2. Make sure your Framework is listed in the array inside `Libraries.swift`.\n3. Create a new version and upload it to TestFlight.\n4. Download it on the device you want to work on.\n5. Open the App.\n6. Select your app in the picker\n\n\u003ccenter\u003e\n    \u003cimg src=\".github/images/picker_view.jpeg\" width=\"300\"/\u003e\n\u003c/center\u003e\n\n7.  Select the number of threads and the offset to crash with.\n    - **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.\n    - **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.\n\n\u003ccenter\u003e\n    \u003cimg src=\".github/images/threads_and_offset.jpeg\" width=\"300\"/\u003e\n\u003c/center\u003e\n\n8. Press crash\n\n\u003ccenter\u003e\n    \u003cimg src=\".github/images/crashed.png\" width=\"300\"/\u003e\n\u003c/center\u003e\n\n9. Upload the crash (you can use the feedback field to enter the parameters used)\n\n\u003ccenter\u003e\n    \u003cimg src=\".github/images/upload.png\" width=\"300\"/\u003e\n\u003c/center\u003e\n\n10. 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`.\n\n\u003ccenter\u003e\n    \u003cimg src=\".github/images/symbols_done.jpeg\" width=\"300\"/\u003e\n\u003c/center\u003e\n\n### Getting a Framework's linker address\n\n1. Download your device IPSW: [https://ipsw.me](https://ipsw.me).\n2. Install [ipsw](brew install blacktop/tap/ipsw) tool.\n   - `brew install blacktop/tap/ipsw`\n3. Extract the shared cache from the IPSW.\n   - `ipsw extract --dyld PATH_TO_IPSW`\n4. Install [DyldExtractor](https://github.com/arandomdev/DyldExtractor).\n   - `python3 -m pip install git+https://github.com/arandomdev/DyldExtractor#egg=dyldextractor`\n5. Extract your framework.\n   - `dyldex -e /System/Library/Frameworks/YOUR_FRAMEWORK.framework/YOUR_FRAMEWORK ./PATH_TO_EXTRACTED_IPSW/dyld_shared_cache_arm64e`\n   - Replace YOUR_FRAMEWORK with your framework name\n   - The extracted binaries will be located inside a new folder called `binaries/System/Library/Frameworks/YOUR_FRAMEWORK.framework/`.\n6. Print the binary load commands\n   - `otool -l binaries/System/Library/Frameworks/YOUR_FRAMEWORK.framework/YOUR_FRAMEWORK | grep LC_SEGMENT -A8`\n   - Look for the section with `segname __TEXT` and the `vmaddr` value will be the linker address.\n\nExample for MetalPerformanceShadersGraph:\n\n```\notool -l binaries/System/Library/Frameworks/MetalPerformanceShadersGraph.framework/MetalPerformanceShadersGraph | grep LC_SEGMENT -A8\n\nOutput:\n      cmd LC_SEGMENT_64\n  cmdsize 1112\n  segname __TEXT\n   vmaddr 0x00000001800fc000\n   vmsize 0x0000000000c5c000\n  fileoff 0\n filesize 12959744\n  maxprot 0x00000005\n initprot 0x00000005\n```\n\nThe linker adddress is `0x00000001800fc000`\n\n### Building Symbols from Crashes\n\n1. Go to [AppStoreConnect](https://appstoreconnect.apple.com/).\n2. Login with your dev account.\n3. Go to your App -\u003e TestFlight -\u003e Crashes.\n4. 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).\n\n\u003ccenter\u003e\n    \u003cimg src=\".github/images/open_in_xcode.png\" width=\"600\"/\u003e\n\u003c/center\u003e\n\n5. 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.\n\n\u003ccenter\u003e\n    \u003cimg src=\".github/images/download_crash.png\" width=\"400\"/\u003e\n\u003c/center\u003e\n\n6. Repeat for all the crashes.\n7. Unzip the downloaded files and place the `*.crash` files inside a new folder.\n8. Execute `SymbolsBuilder` binary with the following parameters:\n   - **--csv** (output a .csv file)\n   - **--input:** path to the folder containing the crashes.\n   - **--output:** path to the folder that will have the symbols file.\n   - **--library-name:** name of the Framework.\n   - **--library-linker-address:** Framework's linker address (it depends on the device and OS). Instructions to get linker address are in the [previous section](#getting-a-frameworks-linker-address)\n\n### Opening a PR for new symbols\n\nThe `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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femergetools%2Fetsymbolication","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femergetools%2Fetsymbolication","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femergetools%2Fetsymbolication/lists"}