forked from facebook/react-native-website
-
Notifications
You must be signed in to change notification settings - Fork 327
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #766 from facebook/main
0.73 sync 1029
- Loading branch information
Showing
75 changed files
with
982 additions
and
736 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| --- | ||
| id: debugging-release-builds | ||
| title: Debugging Release Builds | ||
| --- | ||
|
|
||
| import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; | ||
|
|
||
| ## Symbolicating a stack trace | ||
|
|
||
| If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read. | ||
|
|
||
| ```shell | ||
| 07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules | ||
| 07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack: | ||
| 07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161 | ||
| 07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084 | ||
| 07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854 | ||
| 07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119 | ||
| ``` | ||
|
|
||
| In the above stack trace, entries like `p@1:132161` are minified function names and bytecode offsets. To debug these calls, we want to translate these into file, line, and function name, e.g. `AwesomeProject/App.js:54:initializeMap`. This is known as **symbolication.** | ||
|
|
||
| You can symbolicate minified function names and bytecode like the above by passing the stack trace and a generated source map to [`metro-symbolicate`](http://npmjs.com/package/metro-symbolicate). | ||
|
|
||
| ### Enabling source maps | ||
|
|
||
| Source maps are required to symbolicate stack traces. Make sure that source maps are enabled within the build config for the target platform. | ||
|
|
||
| <Tabs groupId="platform" queryString defaultValue={constants.defaultPlatform} values={constants.platforms} className="pill-tabs"> | ||
| <TabItem value="android"> | ||
|
|
||
| :::info | ||
| On Android, source maps are **enabled** by default. | ||
| ::: | ||
|
|
||
| To enable source map generation, ensure the following `hermesFlags` are present in `android/app/build.gradle`. | ||
|
|
||
| ```groovy | ||
| react { | ||
| hermesFlags = ["-O", "-output-source-map"] | ||
| } | ||
| ``` | ||
|
|
||
| If done correctly you should see the output location of the source map during Metro build output. | ||
|
|
||
| ```text | ||
| Writing bundle output to:, android/app/build/generated/assets/react/release/index.android.bundle | ||
| Writing sourcemap output to:, android/app/build/intermediates/sourcemaps/react/release/index.android.bundle.packager.map | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="ios"> | ||
|
|
||
| :::info | ||
| On iOS, source maps are **disabled** by default. Use the following instructions to enable them. | ||
| ::: | ||
|
|
||
| To enable source map generation: | ||
|
|
||
| - Open Xcode and edit the build phase "Bundle React Native code and images". | ||
| - Above the other exports, add a `SOURCEMAP_FILE` entry with the desired output path. | ||
|
|
||
| ```diff | ||
| + SOURCEMAP_FILE="$(pwd)/../main.jsbundle.map"; | ||
| WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh" | ||
| ``` | ||
|
|
||
| If done correctly you should see the output location of the source map during Metro build output. | ||
|
|
||
| ```text | ||
| Writing bundle output to:, Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle | ||
| Writing sourcemap output to:, Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle.map | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ### Using `metro-symbolicate` | ||
|
|
||
| With source maps being generated, we can now translate our stack traces. | ||
|
|
||
| ```shell | ||
| # Print usage instructions | ||
| npx metro-symbolicate | ||
|
|
||
| # From a file containing the stack trace | ||
| npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt | ||
|
|
||
| # From adb logcat (Android) | ||
| adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map | ||
| ``` | ||
|
|
||
| ### Notes on source maps | ||
|
|
||
| - Multiple source maps may be generated by the build process. Make sure to use the one in the location shown in the examples. | ||
| - Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets. | ||
| - If `metro-symbolicate` exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal. |
Oops, something went wrong.