React-native: Documentation for Android setup seems incomplete compared to previous versions

[BrendanBerkley]

I've been trying out React Native for Android for the first time, and I didn't find the Getting Started page to be all that helpful. Simply following the instructions for Linux + Android as of 0.30 yields at least errors that need to be worked through:

• Must have an emulator installed and running, or have a device plugged in
• Must have the environment variable $ANDROID_HOME set
• Must have some version of Android API installed (23 as of today)

I also tried this on the Mac and had similar issues, particularly with the last bullet point.

The reason why I'm filing this as a bug was that I found the 0.28 Getting Started page to be far more helpful than its 0.30 equivalent. I was browsing the commits and saw that some refactoring had occurred between 0.28 and 0.29 - did something get lost in the shuffle?

[satya164]

cc @JoelMarcey

[JoelMarcey]

cc @lacker

We removed a bunch of stuff from the 0.28 docs to make it more streamlined. Particularly when we removed the screenshots of Android studio, etc. @lacker, maybe we removed too much?

[lacker]

I remember it was quite unclear to us which of the instructions were necessary and which were not so yeah I bet this has errors. Let me address point by point.

Must have an emulator installed and running, or have a device plugged in

It doesn't seem like the 0.28 instructions specifically said, you have to have an emulator running. They talked a whole bunch about different emulator options and I bet we removed them because they were noncritical, but perhaps left out the basics of "You need to run an emulator". Perhaps we should just say briefly, you must have an emulator running or a device plugged in, and link to other pages on how to install emulators?

Must have the environment variable $ANDROID_HOME set

OK let's just resurrect the old section about $ANDROID_HOME.

Must have some version of Android API installed (23 as of today)

You mean the Android SDK Build-Tools? We did have a section before saying to install those, with the screen shots. If that's necessary we should resurrect the screen shots.

[hramos]

Agree that we should update these steps if they don't result in a minimally working dev environment.

We want to delegate any Android development environment setup instructions to the official Android documentation site, so we can focus on any steps that are specific to getting React Native up and running.

@BrendanBerkley, can you share a bit more about how you went through the set up? I expected the basic Android Studio install to take care of installing at least one Android API and setting up the $ANDROID_HOME env var for you. Let me know if that is not the actual case.

[follower]

I took some notes on my out-of-the-box experience with React Native and Android where I encountered some of the same issues, which you might find helpful to read for additional perspective on the current documentation: http://www.labradoc.com/i/follower/p/notes-react-native#20160727

[JoelMarcey]

@follower @BrendanBerkley What do you think is the best course of action. A partial revert of the removal of the old stuff --- or a new pull request from either of you to add some additional data to help here?

[whithajess]

Encountered the exact same things as @BrendanBerkley looking at the older linked 0.28 page it seems that there is so much more info there that would be helpful I would say the best course of action would be a partial revert and then a pull request to clean up. Also encountered problem with finding build tools revision 23.01.

[JoelMarcey]

Is reverting to the old docs the best short-term solution until we come up with a strict subset of that information to provide exactly the necessary steps?

[keithmichelson]

Yes this is very confusing just starting on React Native. I was getting "Can't find sdk" had to install all those and the ANDROID_HOME error. Still can't quite anything to pull up on the Android simulator but the iOS works.

[bbodenmiller]

I had a few of the same issues discussed here with the getting started guide:

• ANDROID_HOME environment variable missing - Android Studio does not install this
• Gradle does not use HTTP_PROXY or HTTPS_PROXY - I had to set per https://docs.gradle.org/current/userguide/build_environment.html#sec:accessing_the_web_via_a_proxy
• Android SDK Platform 23 must be installed - Android Studio is currently installing 24
• Android SDK Build-Tools 23.0.1 - Android Studio is currently installing 24.0.2

[hramos]

@bbodenmiller I'm looking at this issue today. Did you run into any issues with Android SDK Platform 24? Android Nougat is already shipping and I believe targeting the most recent Android API level is a reasonable default.

[bbodenmiller]

Not sure about Android SDK Platform 24. I actually just went in to the SDK manager and installed the tools React Native expected.

[bbodenmiller]

Just tested with 24 and all seems good. I did however notice that by default Android Studio does not add adb to your path and thus react-native run-android does not run without problems.

[hramos]

I'm working on this at #9867. Regarding adb, that probably would be fixed by setting up ANDROID_HOME correctly.

[AsaAyers]

Days ago I read all of the getting started docs and the tutorial. Last night I decided I'd try my first project, just a small fun personal project. I build React web apps all day at work. I'll just run a couple commands, prototype my idea and in a couple hours I'll decide if I want to continue.

The docs simply say "Download and install Android Studio." I did that, but when trying to launch my project:

1. It always complained that adb wasn't found, but continued anyway. I never figured out how to get adb
2. I got big ugly errors and it suggested $ANDROID_HOME. IDK what that is, but I'm guessing it's ~/Android or maybe ~/Android/Sdk. Both seemed to work
3. Now it complains that I don't have android-23. hndr in Discord was able to point me in the right direction. After fumbling around Android Studio for a while I found the SDK Manager
4. Now when I launch it complains about missing build tools 23.0.1. I figured out the SDK Manager also installs those.
5. Now it complains that there isn't a device. The getting started didn't say I needed a device and I know Android Studio has an emulator. I don't know how to launch the emulator, I just know it exists.

Somewhere in there I also got some kind of warning/error about an inotify setting being too low. This may have come from Android Studio as I created a project there just to make sure it was working. Watchman mentions that the limits exist, but gives no guidance at all on what reasonable values are.

It seems like I must be at the last step, right? It seemed that way at every step, so this is the point where I decide I this isn't worth it and delete and uninstall everything.

[hramos]

@AsaAyers can you expand on the error you saw when android-23 was not installed? A clean Android Studio install today will install android-24 (Nougat). Are you saying that the React Native CLI failed to launch your Android app because it _requires_ android-23 (Marshmallow)? Can you check and make sure this is not an AVD issue where your Android virtual device was configured for android-23 but it wasn't installed?

[AsaAyers]

I did not think to screenshot and document my problems as I encountered them last night. I have also removed everything I installed so that hopefully in a few months when I want to try again I'll be able to start clean.

All I have left is a discord log where I said:

export ANDROID_HOME=/home/asa/Android/Sdk With that in place I now get:

failed to find target with hash string 'android-23' in: /home/asa/Android/Sdk

[faassen]

I just tried the tutorial and I can confirm much of what others said. Only thanks to the suggestions here did I make a bit more progress , but it still won't work. Here are my experiences:

• the tutorial doesn't tell you how to set up ANDROID_HOME. This seems required.
• I still get errors that adb is not found. I know it's somewhere in Android home, but I didn't set up a path and I'm not sure android home is being looked at.
• I tried installing Android SDK 23. I'm not sure whether that is required or not. But when you do, it complains: failed to find Build Tools revision 23.0.1. I had to turn on a check box to enable showing older revisions of the SDK tools and then install build tools 23.0.1. Not sure why it didn't ask for 23.0.3 or whatever.

Next I tried to set up the emulator:

• I had to create a project in Android Studio.
• then I had to go to Tools -> Android -> AVD Manager. It shows a reactnative entry, but there's a missing image download.
• once that was done I could click on the device and it would start the emulator.
• I'd much appreciate a note saying how to start up the emulator with the command-line instead of having to go through android studio.

So now I have an emulator, perhaps now it will work:

• running react-native run-android still fails with no connected devices. Probably because adb still not on the path? It should really just complain it can't find adb and bail out directly, instead of saying there are no connected devices, right?
• I added <...>/Android/sdk/platform_tools to my PATH, as I found adb there. I have no idea whether that's correct.

Running the react-native run-android again:

• no more missing adb error, yay.
• I get an "Installing APK 'app-debug.apk' but then a Java traceback saying "Failed to establish session"
• I get the helpful message:

Try: Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

but apparently this is some underlying tool as those options don't exist for react-native.

So far I'm stuck, but I'll try a few more things later.

[faassen]

Some more progress.

I forgot to say I'm on 64 bit Linux.

I figured out a way to run the avd manager from the commandline, but I got hopelessly stuck as it didn't appear to be the same avd manager as the one in android studio, or the sdk manager wasn't. But I'll try again later once I have it running with android studio.

Anyway, I figured I might be confused by cruft left over from a previous attempt to install react native, so I removed the .android settings, the Android SDK stuff and re-ran `studio.sh to start up android studio. Then I went to the avd manager under tools again. This time it offered me to download a bunch of images that I didn't see before. I've downloaded all images listed under "recommended". This time I managed to create a virtual device that actually does boot up (I realize now my old attempt hung at the bootup screen).

I wiped out my previous system so now Android 23 is not installed. Now when I run react-native run-android I get this error:

A problem occurred configuring project ':app'.
> failed to find target with hash string 'android-23' in: /home/faassen/Android/Sdk

Some progress, but I'm not there yet.

[faassen]

The continuing progress. This is where I get things working.

I followed the link by the comment by follower in this issue to find the following:

http://www.labradoc.com/i/follower/p/notes-react-native#20160727

I had trouble getting the patch to apply, so I made the modifications in android/app/build.gradle manually to include 24. I had to adjust the buildToolsVersion to "24.0.3" as this was the version now installed by Android Studio. It strikes me react native shouldn't hard code this but get this from the android configuration somehow, but I don't understand enough about this tooling infrastructure to know what's really going on.

After this the tool did connect to my emulated nexus 5 phone, but there were new problems. First is that it immediately threw me into screen overlay permissions settings. I don't know whether that's normal but it should be documented. The app crashed.

Once I enabled the screen overlay for the app (why is this needed?) and then started the same app again, I got "please wait, fetching JS bundle". Then I got a red screen on the emulated phone that says "Could not connect to the development server." with a bunch of advice, at the bottom there's a reference to DevServerHelper.java:226.

The screen told me to enable USB debugging, so after some googling I went to the build number in "about this phone" clicked it 7 times, became a developer, and then enabled USB debugging in the developer options. For some reason this _still_ didn't fix the issue right away, but once I tried it again, I got the "Welcome to React Native!" screen. Now I can edit the react code and see changes. Awesome!

It's still not reliable: I get the red screen again after I restarted my emulator. Only the second time does it actually successfully load the dev server. I'm not even sure whether enabling USB debugging fixed this, or whether it just always takes starting the app 2 times after booting up the emulator.

I figured out a way to run my emulator without having to start the huge android studio. The trick is to add ANDROID_HOME/tools to your path, and you then have the emulator command, so for instance:

$ emulator -avd Nexus_5_API_24

I hope that the record of this journey helps some people coming after me. I also hope it can help with the improvement of the installation instructions. It strikes me that there are a few bits missing for Android development noobs such as myself.

[lacker]

FWIW, we have added some improvements to how the Android tools detect and print out problems with the environment setup, and Hector fixed a bunch of stuff up with https://github.com/facebook/react-native/pull/9867 . I think this issue is greatly improved and we should close it, although there's sort of always more journey to go when it comes to making startup easy. If there is still a specific problem with these docs then I encourage folks to open new issues specifically focused on one bug/error so that it's easy for us to crank through them. Thanks everyone for helping debug / provide feedback here!