diff --git a/docs/android-setup.html b/docs/android-setup.html index 7a5cd6a4bf5..17aab10e822 100644 --- a/docs/android-setup.html +++ b/docs/android-setup.html @@ -1,5 +1,5 @@ Android Setup – React Native | A framework for building native apps using React
React Native

Quick Start

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Android Setup

This guide describes basic steps of the Android development environment setup that are required to run React Native android apps on an android emulator. We don't discuss developer tool configuration such as IDEs here.

Install Git #

  • On Mac, if you have installed XCode, Git is already installed, otherwise run the following:

    brew install git

  • On Linux, install Git via your package manager.

  • On Windows, download and install Git for Windows. During the setup process, choose "Run Git from Windows Command Prompt", which will add Git to your PATH environment variable.

Install the Android SDK (unless you have it) #

  1. Install the latest JDK
  2. Install the Android SDK:

Define the ANDROID_HOME environment variable #

IMPORTANT: Make sure the ANDROID_HOME environment variable points to your existing Android SDK:

  • On Mac, add this to your ~/.bashrc, ~/.bash_profile or whatever your shell uses:

    # If you installed the SDK via Homebrew, otherwise ~/Library/Android/sdk -export ANDROID_HOME=/usr/local/opt/android-sdk

  • On Linux, add this to your ~/.bashrc, ~/.bash_profile or whatever your shell uses:

    export ANDROID_HOME=<path_where_you_unpacked_android_sdk>

  • On Windows, go to Control Panel -> System and Security -> System -> Change settings -> Advanced -> Environment variables -> New

NOTE: You need to restart the Command Prompt (Windows) / Terminal Emulator (Mac OS X, Linux) to apply the new Environment variables.

Use gradle daemon #

React Native Android use gradle as a build system. We recommend to enable gradle daemon functionailty which may result in up to 50% improvement in incremental build times for changes in java code. Learn here how to enable it for your platform.

Configure your SDK #

  1. Open the Android SDK Manager (on Mac start a new shell and run android); in the window that appears make sure you check:
    • Android SDK Build-tools version 23.0.1
    • Android 6.0 (API 23)
    • Android Support Repository
  2. Click "Install Packages"

SDK Manager window SDK Manager window

Install Genymotion #

Genymotion is much easier to set up than stock Google emulators. However, it's only free for personal use. If you want to use the stock Google emulator, see below.

  1. Download and install Genymotion.
  2. Open Genymotion. It might ask you to install VirtualBox unless you already have it.
  3. Create a new emulator and start it.
  4. To bring up the developer menu press ⌘+M

Alternative: Create a stock Google emulator #

  1. Start a new shell and run android; in the window that appears make sure you check:
    • Intel x86 Atom System Image (for Android 5.1.1 - API 22)
    • Intel x86 Emulator Accelerator (HAXM installer)
  2. Click "Install Packages".
  3. Configure hardware acceleration (HAXM), otherwise the emulator is going to be slow.
  4. Create an Android Virtual Device (AVD):
    1. Run android avd and click on Create... +export ANDROID_HOME=/usr/local/opt/android-sdk

  • On Linux, add this to your ~/.bashrc, ~/.bash_profile or whatever your shell uses:

    export ANDROID_HOME=<path_where_you_unpacked_android_sdk>

  • On Windows, go to Control Panel -> System and Security -> System -> Change settings -> Advanced -> Environment variables -> New

    • NOTE: You need to restart the Command Prompt (Windows) / Terminal Emulator (Mac OS X, Linux) to apply the new Environment variables.

    Use gradle daemon #

    React Native Android use gradle as a build system. We recommend to enable gradle daemon functionality which may result in up to 50% improvement in incremental build times for changes in java code. Learn here how to enable it for your platform.

    Configure your SDK #

    1. Open the Android SDK Manager (on Mac start a new shell and run android); in the window that appears make sure you check:
      • Android SDK Build-tools version 23.0.1
      • Android 6.0 (API 23)
      • Android Support Repository
    2. Click "Install Packages"

    SDK Manager window SDK Manager window

    Install Genymotion #

    Genymotion is much easier to set up than stock Google emulators. However, it's only free for personal use. If you want to use the stock Google emulator, see below.

    1. Download and install Genymotion.
    2. Open Genymotion. It might ask you to install VirtualBox unless you already have it.
    3. Create a new emulator and start it.
    4. To bring up the developer menu press ⌘+M

    Alternative: Create a stock Google emulator #

    1. Start a new shell and run android; in the window that appears make sure you check:
      • Intel x86 Atom System Image (for Android 5.1.1 - API 22)
      • Intel x86 Emulator Accelerator (HAXM installer)
    2. Click "Install Packages".
    3. Configure hardware acceleration (HAXM), otherwise the emulator is going to be slow.
    4. Create an Android Virtual Device (AVD):
      1. Run android avd and click on Create... Create AVD dialog
      2. With the new AVD selected, click Start...
    5. To bring up the developer menu press F2
    Next →
    React Native

    Quick Start

    Guides

    Guides (iOS)

    Guides (Android)

    components

    apis

    Polyfills

    Profiling Android UI Performance

    We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).

    The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...

    Make sure that JS dev mode is OFF!

    You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs (which you can view using adb logcat)

    Profiling with Systrace #

    Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

    Collecting a trace #

    NOTE:

    Systrace support was added in react-native v0.15. You will need to build with that version to collect a trace.

    First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows

    $ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

    A quick breakdown of this command:

    • time is the length of time the trace will be collected in seconds
    • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
    • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

    Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

    Reading the trace #

    After opening the trace in your browser (preferrably Chrome), you should see something like this:

    Example

    HINT: Use the WASD keys to strafe and zoom

    Enable VSync highlighting #

    The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:

    Enable VSync Highlighting

    You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

    Find your process #

    Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

    On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

    UI Thread #

    This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

    JS Thread #

    This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

    Native Modules Thread #

    This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

    Bonus: Render Thread #

    If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

    Identifying a culprit #

    A smooth animation should look something like the following:

    Smooth Animation

    Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.

    If you noticed chop, however, you might see something like this:

    Choppy Animation from JS

    Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.

    You might also see something like this:

    Choppy Animation from UI

    In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

    At this point, you'll have some very helpful information to inform your next steps.

    JS Issues #

    If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

    Too much JS

    This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

    TODO: Add more tools for profiling JS

    Native UI Issues #

    If you identified a native UI problem, there are usually two scenarios:

    1. the UI you're trying to draw each frame involves to much work on the GPU, or
    2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

    Too much GPU work #

    In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

    Overloaded GPU

    Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

    To mitigate this, you should:

    • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
    • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

    If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

    Creating new views on the UI thread #

    In the second scenario, you'll see something more like this:

    Creating Views

    Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

    There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

    Still stuck? #

    If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.

    Next →
    React Native

    Quick Start

    Guides

    Guides (iOS)

    Guides (Android)

    components

    apis

    Polyfills

    Profiling Android UI Performance

    We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).

    The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...

    Make sure that JS dev mode is OFF!

    You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs (which you can view using adb logcat)

    Profiling with Systrace #

    Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

    Collecting a trace #

    NOTE:

    Systrace support was added in react-native v0.15. You will need to build with that version to collect a trace.

    First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows

    $ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

    A quick breakdown of this command:

    • time is the length of time the trace will be collected in seconds
    • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
    • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

    Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

    Reading the trace #

    After opening the trace in your browser (preferably Chrome), you should see something like this:

    Example

    HINT: Use the WASD keys to strafe and zoom

    Enable VSync highlighting #

    The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:

    Enable VSync Highlighting

    You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

    Find your process #

    Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

    On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

    UI Thread #

    This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

    JS Thread #

    This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

    Native Modules Thread #

    This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

    Bonus: Render Thread #

    If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

    Identifying a culprit #

    A smooth animation should look something like the following:

    Smooth Animation

    Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.

    If you noticed chop, however, you might see something like this:

    Choppy Animation from JS

    Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.

    You might also see something like this:

    Choppy Animation from UI

    In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

    At this point, you'll have some very helpful information to inform your next steps.

    JS Issues #

    If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

    Too much JS

    This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

    TODO: Add more tools for profiling JS

    Native UI Issues #

    If you identified a native UI problem, there are usually two scenarios:

    1. the UI you're trying to draw each frame involves to much work on the GPU, or
    2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

    Too much GPU work #

    In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

    Overloaded GPU

    Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

    To mitigate this, you should:

    • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
    • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

    If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

    Creating new views on the UI thread #

    In the second scenario, you'll see something more like this:

    Creating Views

    Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

    There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

    Still stuck? #

    If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.

    Next →
    React Native

    Quick Start

    Guides

    Guides (iOS)

    Guides (Android)

    components

    apis

    Polyfills

    Running On Device

    Prerequisite: USB Debugging #

    You'll need this in order to install your app on your device. First, make sure you have USB debugging enabled on your device.

    Check that your device has been successfully connected by running adb devices:

    $ adb devices List of devices attached emulator-5554 offline # Google emulator -14ed2fcc device # Physical device

    Seeing device in the right column means the device is connected. Android - go figure :) You must have only one device connected.

    Now you can use react-native run-android to install and lauch your app on the device.

    Accessing development server from device #

    You can also iterate quickly on device using the development server. Follow one of the steps described below to make your development server running on your laptop accessible for your device.

    Hint

    Most modern android devices don't have a hardware menu button, which we use to trigger the developer menu. In that case you can shake the device to open the dev menu (to reload, debug, etc.)

    Using adb reverse #

    Note that this option is available on devices running android 5.0+ (API 21).

    Have your device connected via USB with debugging enabled (see paragraph above on how to enable USB debugging on your device).

    1. Run adb reverse tcp:8081 tcp:8081
    2. You can use Reload JS and other development options with no extra configuration

    Configure your app to connect to the local dev server via Wi-Fi #

    1. Make sure your laptop and your phone are on the same Wi-Fi network.
    2. Open your React Native app on your device. You can do this the same way you'd open any other app.
    3. You'll see a red screen with an error. This is OK. The following steps will fix that.
    4. Open the Developer menu by shaking the device or running adb shell input keyevent 82 from the command line.
    5. Go to Dev Settings.
    6. Go to Debug server host for device.
    7. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081). On Mac, you can find the IP address in System Preferences / Network. On Windows, open the command prompt and type ipconfig to find your machine's IP address (more info).
    8. Go back to the Developer menu and select Reload JS.
    Next →