1## Prereqs 2 3Follow instructions for "Building Projects with Native Code" at 4https://facebook.github.io/react-native/docs/getting-started.html to 5install and configure Android. 6 7### Installing an NDK version 8Additionally an `NDK` version needs to be installed for `yarn rn-gobuild-android` to work. 9 10**With Android Studio** 11You will already have the `sdkmanager` command line tool installed. So run: 12 13`sdkmanager --install "ndk-bundle"` which should write to `$HOME/Library/Android/sdk/ndk-bundle` on macOS. 14 15**Without Android Studio** 16You will need the Android Studio Command Line Tools to use `sdkmanager` without Android Studio. 17[Download Command Line Tools](https://developer.android.com/studio/index.html#command-tools) here. 18 19Then run `sdkmanager --install "ndk-bundle"` which should write to `$HOME/Library/Android/sdk/ndk-bundle` on macOS. 20 21## Emulator Setup 22 23### macOS 24 25If you're installing on macOS on High Sierra, skip installing 26HAX. Instead, follow the instructions in 27https://issuetracker.google.com/issues/62395878#comment7 , i.e. put 28`HVF = on` in `~/.android/advancedFeatures.ini`. 29 30On Mojave with the lastest android studio, this is no longer necessary. 31 32### Linux 33 34If you're installing on Linux, you'll want to get KVM set 35up. Otherwise, you'll see this message: 36 37``` 38> ./emulator @Nexus_5X_API_28_x86 39emulator: ERROR: x86 emulation currently requires hardware acceleration! 40Please ensure KVM is properly installed and usable. 41CPU acceleration status: This user doesn't have permissions to use KVM (/dev/kvm) 42``` 43 44Normally, `/dev/kvm` can only be used by `root`, but you don't 45want to run things as root regularly. Instead, make a `kvm` group and 46add your current user in it: 47 48```sh 49# As root 50addgroup kvm 51usermod -a -G kvm $USER 52``` 53 54You may have to log out and re-log in, or even reboot, for this to 55take effect. Then you'll want to configure the right group and permissions 56for `/dev/kvm`. From [this StackExchange answer](https://unix.stackexchange.com/questions/373872/non-root-user-can-not-use-enable-kvm), 57 581. Create the file `/etc/udev/rules.d/65-kvm.rules` as root 592. Put the following line inside this file: 60 61``` 62KERNEL=="kvm", NAME="%k", GROUP="kvm", MODE="0660" 63``` 64 653. Reload rules with `udevadm control --reload-rules && udevadm trigger` 66 67## Android Studio 68 69Select "Open an existing Android Studio Project" and point it to 70`shared/android`. Not necessary to register the `client` 71dir as a VCS-controlled dir with Android studio, but may as well. 72 73You might get various prompts about installing various tools. You should 74install 'Build Tools' and any missing platforms. However, _don't_ 75update the Android Gradle Plugin to 3.0.1. 76 77Also see below for some messages you may encounter with Android Studio. 78 79Some instructions talk about the SDK Manager / AVD Manager. This is 80under the Tools > Android menu. You may have to wait for Gradle to 81sync before they appear. 82 83Before running the build process in android studio, you will need to 84run `yarn rn-gobuild-android`. 85 86### Dealing with Android Studio 87 88Sometimes Android Studio gets into a bad state, especially if you're 89doing stuff like `yarn modules` in the background. 90 91If 'Gradle sync' fails, you can retry it from Tools > Android > 'Sync 92Project with Gradle Files'. 93 94Sometimes, especially after opening Android Studio after a run of 95`yarn modules`, you'll get an "Unsupported Modules Detected" message 96for "react-native-fetch-blob" and "react-native-contacts". This seems 97to be harmless. 98 99Sometimes you'll also get an "An IDE Error has occured" message. That 100also seems to be harmless, although you may want to resync/reopen the 101project in that case. 102 103If nothing above works, you can try closing (File > Close Project) and 104reopening the project. Or even closing and reopening the app. 105 106### Building and developing without Android Studio 107 108Alternatively, you can build and develop without Android 109Studio. However, first make sure you _can_ build and run with Android 110Studio first, as it's easier to get that working first. 111 112So make sure you've run `yarn rn-gobuild-android` and you have the 113react-native packager running (`yarn rn-start android`). 114 115Then run 116 117```sh 118yarn react-native run-android 119 120# for storybook 121yarn react-native run-android --variant 'storybook' 122 123``` 124 125Unless you're modifying the Java files or you're modifying Go files 126(and thus re-running `run-gobuild-android`), you likely have to only 127run this occasionally. 128 129Then make sure you either have an emulator running, or you have your 130Android device connected (but not both). To check, run 131 132```sh 133adb devices 134``` 135 136It should list exactly one device. 137 138### Using an emulator 139 140Either use the avd manager in Android Studio or use the raw commands below. 141Setting up an avd is much easier in Android Studio, so it's recommended to do that for the inital setup at least 142 143```sh 144# Even though emulator should be in your path, it 145# seems to require you to be in this directory. 146cd $ANDROID_HOME/emulator 147 148emulator -list-avds 149 150# Nexus_5X_API_27_x86 is an example avd. 151# 152# The leading './' is needed on Linux. 153./emulator @Nexus_5X_API_27_x86 154``` 155 156assuming you've set the `$ANDROID_HOME` variable and added 157`$ANDROID_HOME/tools` to your `PATH`, per 158https://facebook.github.io/react-native/docs/getting-started.html . 159 160### Using a device 161 162To run on your Android device, make sure USB debugging is enabled; see 163[these 164instructions](https://facebook.github.io/react-native/docs/running-on-device.html). Then 165plug in your device via USB and tap 'OK' on the 'Allow USB debugging?' 166prompt if it appears. After that, `adb devices` should list your 167device. If it says 'unauthorized' next to your device, then you likely 168haven't tapped 'OK' on the prompt yet. If you saw no prompt, try 169revoking (https://stackoverflow.com/a/25546300/670659). 170 171**Turn off Instant Run** 172 173To turn off Instant Run go to [Android Studio | Settings | Build, Execution, Deployment | Instant Run | Uncheck the box](https://i.imgur.com/0ofeBMn.png). 174 175If you see the errors including `Failed to execute aapt` or `transformDexWithInstantRunDependenciesApkForDebug` the problem might be that Instant Run is enabled. 176 177## Port forwarding 178 179You need to port forward 8081 so react-native can react its packager. 180 181On your computer run: 182 183```sh 184adb reverse tcp:8081 tcp:8081 185``` 186 187To recap, you should have run: 188 1891. `adb devices` (should list _exactly_ one device) 1901. `yarn rn-gobuild-android` 1911. `yarn react-native run-android` 192 193Happy developing! 194 195### Troubleshooting 196 197Occasionally you might get a white screen that doesn't go away, even 198after the bundler has finished bundling. Stopping the app and 199restarting it seems to fix it. 200