kylefang/react-native
1
0
Fork 0
mirror of https://github.com/zhigang1992/react-native.git synced 2026-04-22 19:48:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Streamline Getting Started Instructions

Browse Source 
Summary:
The Getting Started guide is one of the first documents a new user will encounter. This pull request aims to minimize the amount of time it takes to get a React Native app up and running.

* The original section title, "Required prerequisites", is redundant. "Installing React Native" is a better description of what this section is about.
* Detailed installation instructions for each of the required tools are delegated to the first party instructions where available.
* If the installation instructions already take care of installing the latest version, there's no need to warn the user about the minimum required version.

* Assume the user is familiar with Homebrew or Chocolatey, and defer installation instructions to the package manager's website. The installation and explanation of what a package manager is is out of scope within this document.
* Link to Node.js package manager instructions and let savvy Linux users use the pack
Closes https://github.com/facebook/react-native/pull/8010

Differential Revision: D3407029

Pulled By: JoelMarcey

fbshipit-source-id: c8b25d5b176c40eb58e5d7d3c6f13d43cde65166
This commit is contained in:
Héctor Ramos
2016-06-08 13:17:19 -07:00
committed by Facebook Github Bot 2
parent 3a8b50ad55
commit 8324e92f76
3 changed files with 141 additions and 595 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
docs/Debugging.md
View File

@@ -7,59 +7,73 @@ permalink: docs/debugging.html
next: testing
---
## Debugging React Native Apps
To access the in-app developer menu:
## In-app Errors and Warnings
1. On iOS shake the device or press `control + ⌘ + z` in the simulator.
2. On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in [genymotion](https://www.genymotion.com) you can press `⌘ + m` or `F2` to simulate hardware menu button click). You can also install [Frappé](http://getfrappe.com), a tool for OS X, which allows you to emulate shaking of devices remotely. You can use `⌘ + Shift + R` as a shortcut to trigger a **shake** from Frappé.
Errors and warnings are displayed inside your app in development builds.
> Hint
### Errors
> To disable the developer menu for production builds:
>
> 1. For iOS open your project in Xcode and select `Product` → `Scheme` → `Edit Scheme...` (or press `⌘ + <`). Next, select `Run` from the menu on the left and change the Build Configuration to `Release`.
> 2. For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle `assembleRelease` task). Although this behavior can be customized by passing proper value to `ReactInstanceManager#setUseDeveloperSupport`.
In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use `console.error()` to manually trigger one.
### Android logging
Run `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal to see your Android app's logs.
### Warnings
### Reload
Selecting `Reload` (or pressing `⌘ + r` in the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image to `Images.xcassets` on iOS or to `res/drawable` folder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.
Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them.
### YellowBox/RedBox
Using `console.warn` will display an on-screen log on a yellow background. Click on this warning to show more information about it full screen and/or dismiss the warning.
As with a RedBox, you can use `console.warn()` to trigger a YellowBox.
You can use `console.error` to display a full screen error on a red background.
YellowBoxes can be disabled during development by using `console.disableYellowBox = true;`. Specific warnings can be ignored programmatically by setting an array of prefixes that should be ignored: `console.ignoredYellowBox = ['Warning: ...'];`
By default, the warning box is enabled in `__DEV__`. Set the following flag to disable it:
```js
console.disableYellowBox = true;
console.warn('YellowBox is disabled.');
```
Specific warnings can be ignored programmatically by setting the array:
```js
console.ignoredYellowBox = ['Warning: ...'];
```
Strings in `console.ignoredYellowBox` can be a prefix of the warning that should be ignored.
> RedBoxes and YellowBoxes are automatically disabled in release (production) builds.
### Chrome Developer Tools
To debug the JavaScript code in Chrome, select `Debug JS Remotely` from the developer menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui).
## Accessing the In-App Developer Menu
In Chrome, press `⌘ + option + i` or select `View` → `Developer` → `Developer Tools` to toggle the developer tools console. Enable [Pause On Caught Exceptions](http://stackoverflow.com/questions/2233339/javascript-is-there-a-way-to-get-chrome-to-break-on-all-errors/17324511#17324511) for a better debugging experience.
You can access the developer menu by shaking your device. You can also use the `Command⌘ + D` keyboard shortcut when your app is running in the iPhone Simulator, or `Command⌘ + M` when running in an Android emulator.
To debug on a real device:
> The Developer Menu is disabled in release (production) builds.
1. On iOS - open the file [`RCTWebSocketExecutor.m`](https://github.com/facebook/react-native/blob/master/Libraries/WebSocket/RCTWebSocketExecutor.m) and change `localhost` to the IP address of your computer. Shake the device to open the development menu with the option to start debugging.
2. On Android, if you're running Android 5.0+ device connected via USB you can use `adb` command line tool to setup port forwarding from the device to your computer. For that run: `adb reverse tcp:8081 tcp:8081` (see [this link](http://developer.android.com/tools/help/adb.html) for help on `adb` command). Alternatively, you can [open dev menu](#debugging-react-native-apps) on the device and select `Dev Settings`, then update `Debug server host for device` setting to the IP address of your computer.
## Reloading JavaScript
### Custom JavaScript debugger
To use a custom JavaScript debugger define the `REACT_DEBUGGER` environment variable to a command that will start your custom debugger. That variable will be read from the Packager process. If that environment variable is set, selecting `Debug JS Remotely` from the developer menu will execute that command instead of opening Chrome. The exact command to be executed is the contents of the REACT_DEBUGGER environment variable followed by the space separated paths of all project roots (e.g. If you set REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative" then the command "node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app" will end up being executed). Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
Selecting `Reload` from the Developer Menu will reload the JavaScript that powers your application. You can also press `Command⌘ + R` in the iOS Simulator, or press `R` twice on Android emulators.
### Live Reload
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
You will need to rebuild your app for changes to take effect in certain situations:
1. On iOS, select `Enable Live Reload` via the developer menu to have the application automatically reload when changes are made to the JavaScript.
2. On Android, [launch dev menu](#debugging-react-native-apps), go to `Dev Settings` and select `Auto reload on JS change` option
* You have added new resources to your native app's bundle, such as an image in `Images.xcassets` on iOS or in `res/drawable` folder on Android.
* You have modified native code (Objective-C/Swift on iOS or Java/C++ on Android).
### FPS (Frames per Second) Monitor
On `0.5.0-rc` and higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.
### Automatic reloading
You may enable Live Reload to automatically trigger a reload whenever your JavaScript code changes.
Live Reload is available on iOS via the Developer Menu. On Android, select "Dev Settings" from the Developer Menu and enable "Auto reload on JS change".
## Accessing logs
To view detailed logs on iOS, open your app in Xcode, then Build and Run your app on a device or the iPhone Simulator. The console should appear automatically after the app launches.
Run `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal to display the logs for an Android app running on a device or an emulator.
## Chrome Developer Tools
To debug the JavaScript code in Chrome, select `Debug JS Remotely` from the Developer Menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui).
In Chrome, press `Command⌘ + Option⌥ + I` or select `View` → `Developer` → `Developer Tools` to toggle the developer tools console. Enable [Pause On Caught Exceptions](http://stackoverflow.com/questions/2233339/javascript-is-there-a-way-to-get-chrome-to-break-on-all-errors/17324511#17324511) for a better debugging experience.
### Debugging on a device with Chrome Developer Tools
On iOS devices, open the file [`RCTWebSocketExecutor.m`](https://github.com/facebook/react-native/blob/master/Libraries/WebSocket/RCTWebSocketExecutor.m) and change `localhost` to the IP address of your computer, then select `Debug JS Remotely` from the Developer Menu.
On Android 5.0+ devices connected via USB, you can use the [`adb` command line tool](http://developer.android.com/tools/help/adb.html) to setup port forwarding from the device to your computer:
`adb reverse tcp:8081 tcp:8081`
Alternatively, select `Dev Settings` from the Developer Menu, then update the `Debug server host for device` setting to match the IP address of your computer.
### Debugging using a custom JavaScript debugger
To use a custom JavaScript debugger in place of Chrome Developer Tools, set the `REACT_DEBUGGER` environment variable to a command that will start your custom debugger. You can then select `Debug JS Remotely` from the Developer Menu to start debugging.
> The debugger will receive a list of all project roots, separated by a space. For example, if you set `REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative"`, then the command `node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app` will be used to start your debugger. Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
## FPS (Frames per Second) Monitor
You can enable a FPS graph overlay in the Developer Menu in order to help you debug performance problems.

627
docs/QuickStart-GettingStarted.md
View File

@@ -56,35 +56,31 @@ block { display: none; }
<!-- ######### MAC for iOS ##################### -->
<block class="mac ios" />
## Installing React Native
There's a few things you need to install first. You will need Node.js, the React Native command line tools, Watchman, and Xcode.
<block class="mac android" />
## Installing React Native
There's a few things you need to install first. You will need Node.js, the React Native command line tools, Watchman, and Android Studio.
<block class="mac ios android" />
## Installation
#### Node.js
### Required Prerequisites
#### Homebrew
[Homebrew](http://brew.sh/), in order to install the required NodeJS, in addition to some
recommended installs.
```
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
#### Node
Use Homebrew to install [Node.js](https://nodejs.org/).
> NodeJS 4.0 or greater is required for React Native. The default Homebrew package for Node is
> currently 6.0, so that is not an issue.
We recommend installing Node.js via [Homebrew](http://brew.sh/), a popular package manager for OS X:
```
brew install node
```
#### React Native Command Line Tools
#### React Native command line tools
The React Native command line tools allow you to easily create and initialize projects, etc.
Use Node's package manager to install the React Native command line tools. These will allow you to easily create your first React Native project.
```
npm install -g react-native-cli
@@ -93,69 +89,6 @@ npm install -g react-native-cli
> If you see the error, `EACCES: permission denied`, please run the command:
> `sudo npm install -g react-native-cli`.
<block class="mac ios" />
#### Xcode
[Xcode](https://developer.apple.com/xcode/downloads/) 7.0 or higher is required. You can install Xcode via the App Store or [Apple developer downloads](https://developer.apple.com/xcode/downloads/). This will install the Xcode IDE and Xcode Command Line Tools.
> While generally installed by default, you can verify that the Xcode Command Line Tools are installed by launching Xcode and selecting `Xcode | Preferences | Locations` and ensuring there is a version of the command line tools shown in the `Command Line Tools` list box. The Command Line Tools give you `git`, etc.
<block class="mac android" />
#### Android Studio
[Android Studio](http://developer.android.com/sdk/index.html) 2.0 or higher.
> Android Studio requires the Java Development Kit [JDK] 1.8 or higher. You can type
> `javac -version` to see what version you have, if any. If you do not meet the JDK requirement,
> you can
> [download it](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
Android Studio will provide you the Android SDK and emulator required to run and test your React
Native apps.
> Unless otherwise mentioned, keep all the setup defaults intact. For example, the
> `Android Support Repository` is installed automatically with Android Studio, and we need that
> for React Native.
You will need to customize your installation:
- Choose a `Custom` installation
![custom installation](img/react-native-android-studio-custom-install.png)
- Choose both `Performance` and `Android Virtual Device`
![additional installs](img/react-native-android-studio-additional-installs.png)
- After installation, choose `Configure | SDK Manager` from the Android Studio welcome window.
![configure sdk](img/react-native-android-studio-configure-sdk.png)
- In the `SDK Platforms` window, choose `Show Package Details` and under `Android 6.0 (Marshmallow)`, make sure that `Google APIs`, `Intel x86 Atom System Image`, `Intel x86 Atom_64 System Image`, and `Google APIs Intel x86 Atom_64 System Image` are checked.
![platforms](img/react-native-android-studio-android-sdk-platforms.png)
- In the `SDK Tools` window, choose `Show Package Details` and under `Android SDK Build Tools`, make sure that `Android SDK Build-Tools 23.0.1` is selected.
![build tools](img/react-native-android-studio-android-sdk-build-tools.png)
#### ANDROID_HOME Environment Variable
Ensure the `ANDROID_HOME` environment variable points to your existing Android SDK. To do that, add
this to your `~/.bashrc`, `~/.bash_profile` (or whatever your shell uses) and re-open your terminal:
```
# If you installed the SDK without Android Studio, then it may be something like:
# /usr/local/opt/android-sdk
export ANDROID_HOME=~/Library/Android/sdk
```
<block class="mac ios android" />
### Highly Recommended Installs
#### Watchman
[Watchman](https://facebook.github.io/watchman/docs/install.html) is a tool by Facebook for watching
@@ -165,160 +98,60 @@ changes in the filesystem. It is recommended you install it for better performan
brew install watchman
```
#### Flow
<block class="mac ios" />
[Flow](http://www.flowtype.org), for static typechecking of your React Native code (when using
Flow as part of your codebase).
#### Xcode
```
brew install flow
```
You can install Xcode via the [Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12), or download it directly from the [Apple Developer portal](https://developer.apple.com/xcode/downloads/).
<block class="mac android" />
#### Add Android Tools Directory to your `PATH`
#### Android Studio
You can add the Android tools directory on your `PATH` in case you need to run any of the Android
tools from the command line such as `android avd`. In your `~/.bash` or `~/.bash_profile`:
```
# Your exact string here may be different.
PATH="~/Library/Android/sdk/tools:~/Library/Android/sdk/platform-tools:${PATH}"
export PATH
```
Download and install [Android Studio](https://developer.android.com/studio/install.html).
#### Gradle Daemon
Enable [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) which greatly improves incremental build times for changes in java code.
### Other Optional Installs
#### Git
Git version control. If you have installed [Xcode](https://developer.apple.com/xcode/), Git is
already installed, otherwise run the following:
```
brew install git
```
<block class="mac ios android" />
#### Nuclide
[Nuclide](http://nuclide.io) is an IDE from Facebook providing a first-class development environment
for writing, [running](http://nuclide.io/docs/platforms/react-native/#running-applications) and
[debugging](http://nuclide.io/docs/platforms/react-native/#debugging)
[React Native](http://nuclide.io/docs/platforms/react-native/) applications.
Get started with Nuclide [here](http://nuclide.io/docs/quick-start/getting-started/).
<block class="mac android" />
#### Genymotion
Genymotion is an alternative to the stock Google emulator that comes with Android Studio.
However, it's only free for personal use. If you want to use Genymotion, see below.
1. Download and install [Genymotion](https://www.genymotion.com/).
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
### Troubleshooting
#### Virtual Device Not Created When Installing Android Studio
There is a [known bug](https://code.google.com/p/android/issues/detail?id=207563) on some versions
of Android Studio where a virtual device will not be created, even though you selected it in the
installation sequence. You may see this at the end of the installation:
```
Creating Android virtual device
Unable to create a virtual device: Unable to create Android virtual device
```
If you see this, run `android avd` and create the virtual device manually.
![avd](img/react-native-android-studio-avd.png)
Then select the new device in the AVD Manager window and click `Start...`.
#### Shell Command Unresponsive Exception
If you encounter:
```
Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException
```
try downgrading your Gradle version to 1.2.3 in `<project-name>/android/build.gradle` (https://github.com/facebook/react-native/issues/2720)
While optional, enabling [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) will greatly improve incremental build times for changes in Java code.
<!-- ######### LINUX and WINDOWS for ANDROID ##################### -->
<block class="linux windows android" />
## Installation
## Installing React Native
### Required Prerequisites
<block class="windows android" />
#### Chocolatey
[Chocolatey](https://chocolatey.org) is a package manager for Windows similar to `yum` and
`apt-get`. See the [website](https://chocolatey.org) for updated instructions, but installing from
the Terminal should be something like:
```
@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
```
> Normally when you run Chocolatey to install a package, you should run your Terminal as
> Administrator.
#### Python 2
Fire up the Terminal and use Chocolatey to install Python 2.
> Python 3 will currently not work when initializing a React Native project.
```
choco install python2
```
There's a few things you need to install first. You will need Node.js, the React Native command line tools, Watchman, and Android Studio.
<block class="linux windows android" />
#### Node
#### Node.js
<block class="linux android" />
Fire up the Terminal and type the following commands to install NodeJS from the NodeSource
repository:
```
sudo apt-get install -y build-essential
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo ln -s /usr/bin/nodejs /usr/bin/node
```
Follow the [installation instructions for your Linux distribution](https://nodejs.org/en/download/package-manager/) to install Node.js 4 or newer.
<block class='windows android' />
Fire up the Termimal and use Chocolatey to install NodeJS.
We recommend installing Node.js via [Chocolatey](https://chocolatey.org), a popular package manager for Windows. Open a Command Prompt as Administrator, then run the following command:
```
choco install nodejs.install
```
##### Python
The React Native command line tools require Python2. Install it using Chocolatey:
```
choco install python2
```
<block class="windows linux android" />
#### React Native Command Line Tools
#### React Native command line tools
The React Native command line tools allow you to easily create and initialize projects, etc.
Use Node's package manager to install the React Native command line tools. These will allow you to easily create your first React Native project.
```
npm install -g react-native-cli
@@ -327,351 +160,41 @@ npm install -g react-native-cli
> If you see the error, `EACCES: permission denied`, please run the command:
> `sudo npm install -g react-native-cli`.
<block class="windows linux android" />
#### Android Studio
[Android Studio](http://developer.android.com/sdk/index.html) 2.0 or higher.
> Android Studio requires the Java Development Kit [JDK] 1.8 or higher. You can type
> `javac -version` to see what version you have, if any. If you do not meet the JDK requirement,
> you can
> [download it](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html),
> or use a pacakage manager to install it (e.g. `choco install jdk8`,
> `apt-get install default-jdk`).
Android Studio will provide you the Android SDK and emulator required to run and test your React
Native apps.
> Unless otherwise mentioned, keep all the setup defaults intact. For example, the
> `Android Support Repository` is installed automatically with Android Studio, and we need that
> for React Native.
<block class="linux android" />
You will need to customize your installation:
- Choose a `Custom` installation
![custom installation](img/react-native-android-studio-custom-install-linux.png)
- Choose `Android Virtual Device`
![additional installs](img/react-native-android-studio-additional-installs-linux.png)
<block class="windows android" />
- Make sure all components are checked for the install, particularly the `Android SDK` and `Android Device Emulator`.
- After the initial install, choose a `Custom` installation.
![custom installation](img/react-native-android-studio-custom-install-windows.png)
- Verify installed components, particularly the emulator and the HAXM accelerator. They should be checked.
![verify installs](img/react-native-android-studio-verify-installs-windows.png)
<block class="windows linux android" />
- After installation, choose `Configure | SDK Manager` from the Android Studio welcome window.
<block class="linux android" />
![configure sdk](img/react-native-android-studio-configure-sdk-linux.png)
<block class="windows android" />
![configure sdk](img/react-native-android-studio-configure-sdk-windows.png)
<block class="windows linux android" />
- In the `SDK Platforms` window, choose `Show Package Details` and under `Android 6.0 (Marshmallow)`, make sure that `Google APIs`, `Intel x86 Atom System Image`, `Intel x86 Atom_64 System Image`, and `Google APIs Intel x86 Atom_64 System Image` are checked.
<block class="linux android" />
![platforms](img/react-native-android-studio-android-sdk-platforms-linux.png)
<block class="windows android" />
![platforms](img/react-native-android-studio-android-sdk-platforms-windows.png)
<block class="windows linux android" />
- In the `SDK Tools` window, choose `Show Package Details` and under `Android SDK Build Tools`, make sure that `Android SDK Build-Tools 23.0.1` is selected.
<block class="linux android" />
![build tools](img/react-native-android-studio-android-sdk-build-tools-linux.png)
<block class="windows android" />
![build tools](img/react-native-android-studio-android-sdk-build-tools-windows.png)
<block class="windows linux android" />
#### ANDROID_HOME Environment Variable
Ensure the `ANDROID_HOME` environment variable points to your existing Android SDK.
<block class="linux android" />
To do that, add this to your `~/.bashrc`, `~/.bash_profile` (or whatever your shell uses) and
re-open your terminal:
```
# If you installed the SDK without Android Studio, then it may be something like:
# /usr/local/opt/android-sdk; Generally with Android Studio, the SDK is installed here...
export ANDROID_HOME=~/Android/Sdk
```
> You need to restart the Terminal to apply the new environment variables (or `source` the relevant
> bash file).
<block class="windows android" />
Go to `Control Panel` -> `System and Security` -> `System` -> `Change settings` ->
`Advanced System Settings` -> `Environment variables` -> `New`
> Your path to the SDK will vary to the one shown below.
![env variable](img/react-native-android-sdk-environment-variable-windows.png)
> You need to restart the Command Prompt (Windows) to apply the new environment variables.
<block class="linux windows android" />
### Highly Recommended Installs
Download and install [Android Studio](https://developer.android.com/studio/install.html).
<block class="linux android" />
#### Watchman
Watchman is a tool by Facebook for watching changes in the filesystem. It is recommended you install
it for better performance.
> This also helps avoid a node file-watching bug.
Type the following into your terminal to compile watchman from source and install it:
```
git clone https://github.com/facebook/watchman.git
cd watchman
git checkout v4.5.0 # the latest stable release
./autogen.sh
./configure
make
sudo make install
```
#### Flow
[Flow](http://www.flowtype.org), for static typechecking of your React Native code (when using
Flow as part of your codebase).
Type the following in the terminal:
```
npm install -g flow-bin
```
[Watchman](https://facebook.github.io/watchman) is a tool by Facebook for watching changes in the filesystem. It is recommended you install
it for better performance. You can follow the [Watchman installation guide](https://facebook.github.io/watchman/docs/install.html#installing-from-source) to compile and install from source.
<block class="windows linux android" />
#### Gradle Daemon
Enable [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) which greatly
improves incremental build times for changes in java code.
<block class="mac linux android" />
```
touch ~/.gradle/gradle.properties && echo "org.gradle.daemon=true" >> ~/.gradle/gradle.properties
```
<block class="windows android" />
```
(if not exist "%USERPROFILE%/.gradle" mkdir "%USERPROFILE%/.gradle") && (echo org.gradle.daemon=true >> "%USERPROFILE%/.gradle/gradle.properties")
```
<block class="linux android" />
#### Android Emulator Accelerator
You may have seen the following screen when installing Android Studio.
![accelerator](img/react-native-android-studio-kvm-linux.png)
If your system supports KVM, you should install the
[Intel Android Emulator Accelerator](https://software.intel.com/en-us/android/articles/speeding-up-the-android-emulator-on-intel-architecture#_Toc358213272).
<block class="windows linux android" />
#### Add Android Tools Directory to your `PATH`
You can add the Android tools directory on your `PATH` in case you need to run any of the Android
tools from the command line such as `android avd`.
<block class="linux android" />
In your `~/.bashrc` or `~/.bash_profile`:
```
# Your exact string here may be different.
PATH="~/Android/Sdk/tools:~/Android/Sdk/platform-tools:${PATH}"
export PATH
```
<block class="windows android" />
Go to `Control Panel` -> `System and Security` -> `System` -> `Change settings` ->
`Advanced System Settings` -> `Environment variables` -> highlight `PATH` -> `Edit...`
> The location of your Android tools directories will vary.
![env variable](img/react-native-android-tools-environment-variable-windows.png)
<block class="windows linux android" />
### Other Optional Installs
#### Git
<block class="linux android">
Install Git [via your package manager](https://git-scm.com/download/linux)
(e.g., `sudo apt-get install git-all`).
<block class="windows android" />
You can use Chocolatey to install `git` via:
```
choco install git
```
Alternatively, you can download and install [Git for Windows](https://git-for-windows.github.io/).
During the setup process, choose "Run Git from Windows Command Prompt", which will add `git` to your
`PATH` environment variable.
<block class="linux android" />
#### Nuclide
[Nuclide] is an IDE from Facebook providing a first-class development environment for writing,
[running](http://nuclide.io/docs/platforms/react-native/#running-applications) and
[debugging](http://nuclide.io/docs/platforms/react-native/#debugging)
[React Native](http://nuclide.io/docs/platforms/react-native/) applications.
Get started with Nuclide [here](http://nuclide.io/docs/quick-start/getting-started/).
<block class="linux windows android" />
#### Genymotion
Genymotion is an alternative to the stock Google emulator that comes with Android Studio.
However, it's only free for personal use. If you want to use the stock Google emulator, see below.
1. Download and install [Genymotion](https://www.genymotion.com/).
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
<block class="windows android" />
#### Visual Studio Emulator for Android
The [Visual Studio Emulator for Android](https://www.visualstudio.com/en-us/features/msft-android-emulator-vs.aspx)
is a free android emulator that is hardware accelerated via Hyper-V. It is an alternative to the
stock Google emulator that comes with Android Studio. It doesn't require you to install Visual
Studio at all.
To use it with react-native you just have to add a key and value to your registry:
1. Open the Run Command (Windows+R)
2. Enter `regedit.exe`
3. In the Registry Editor navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Android SDK Tools`
4. Right Click on `Android SDK Tools` and choose `New > String Value`
5. Set the name to `Path`
6. Double Click the new `Path` Key and set the value to `C:\Program Files\Android\sdk`. The path value might be different on your machine.
You will also need to run the command `adb reverse tcp:8081 tcp:8081` with this emulator.
Then restart the emulator and when it runs you can just do `react-native run-android` as usual.
<block class="windows linux android" />
### Troubleshooting
#### Unable to run mksdcard SDK Tool
When installing Android Studio, if you get the error:
```
Unable to run mksdcard SDK tool
```
then install the standard C++ library:
```
sudo apt-get install lib32stdc++6
```
#### Virtual Device Not Created When Installing Android Studio
There is a [known bug](https://code.google.com/p/android/issues/detail?id=207563) on some versions
of Android Studio where a virtual device will not be created, even though you selected it in the
installation sequence. You may see this at the end of the installation:
<block class="linux android" />
```
Creating Android virtual device
Unable to create a virtual device: Unable to create Android virtual device
```
<block class="windows android" />
![no virtual device](img/react-native-android-studio-no-virtual-device-windows.png)
<block class="windows linux android" />
If you see this, run `android avd` and create the virtual device manually.
<block class="linux android" />
![avd](img/react-native-android-studio-avd-linux.png)
<block class="windows android" />
![avd](img/react-native-android-studio-avd-windows.png)
<block class="windows linux android" />
Then select the new device in the AVD Manager window and click `Start...`.
<block class="linux android" />
#### Shell Command Unresponsive Exception
In case you encounter
```
Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException
```
try downgrading your Gradle version to 1.2.3 in `<project-name>/android/build.gradle` (https://github.com/facebook/react-native/issues/2720)
While optional, enabling [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) will greatly improve incremental build times for changes in Java code.
<block class="mac ios android" />
## Testing Installation
## Testing your React Native Installation
<block class="mac ios" />
Use the React Native command line tools to generate a new React Native project called "AwesomeProject", then run `react-native run-ios` inside the newly created folder.
```
react-native init AwesomeProject
cd AwesomeProject
react-native run-ios
```
If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.
> You can also
> [open the `AwesomeProject`](http://nuclide.io/docs/quick-start/getting-started/#adding-a-project)
> folder in [Nuclide](http://nuclide.io) and
@@ -680,12 +203,16 @@ react-native run-ios
<block class="mac android" />
Use the React Native command line tools to generate a new React Native project called "AwesomeProject", then run `react-native run-android` inside the newly created folder.
```
react-native init AwesomeProject
cd AwesomeProject
react-native run-android
```
If everything is set up correctly, you should see your new app running in your Android emulator shortly.
> You can also
> [open the `AwesomeProject`](http://nuclide.io/docs/quick-start/getting-started/#adding-a-project)
> folder in [Nuclide](http://nuclide.io) and
@@ -693,24 +220,23 @@ react-native run-android
<block class="mac ios android" />
### Modifying Project
### Modifying your app
Now that you successfully started the project, let's modify it:
Now that you have successfully run the app, let's modify it.
<block class="mac ios" />
- Open `index.ios.js` in your text editor of choice (e.g. [Nuclide](http://nuclide.io/docs/platforms/react-native/)) and edit some lines.
- Hit ⌘-R in your iOS simulator to reload the app and see your change!
- Open `index.ios.js` in your text editor of choice and edit some lines.
- Hit `Command⌘ + R` in your iOS Simulator to reload the app and see your change!
<block class="mac android" />
- Open `index.android.js` in your text editor of choice (e.g. [Nuclide](http://nuclide.io/docs/platforms/react-native/)) and edit some lines.
- Press the `R` key twice **OR** open the menu (F2 by default, or ⌘-M in Genymotion) and select Reload JS to see your change!
- Run `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal to see your app's logs
- Open `index.android.js` in your text editor of choice and edit some lines.
- Press the `R` key twice or select `Reload` from the Developer Menu to see your change!
<block class="mac ios android" />
### That's It
### That's it!
Congratulations! You've successfully run and modified your first React Native app.
@@ -718,7 +244,9 @@ Congratulations! You've successfully run and modified your first React Native ap
<block class="windows linux android" />
## Testing Installation
## Testing your React Native Installation
Use the React Native command line tools to generate a new React Native project called "AwesomeProject", then run `react-native run-android` inside the newly created folder.
```
react-native init AwesomeProject
@@ -726,33 +254,25 @@ cd AwesomeProject
react-native run-android
```
<block class="windows linux android" />
If everything is set up correctly, you should see your new app running in your Android emulator shortly.
### Troubleshooting Run
A common issue is that the packager is not started automatically when you run
`react-native run-android`. You can start it manually using:
```
cd AwesomeProject
react-native start
```
> A common issue is that the packager is not started automatically when you run
`react-native run-android`. You can start it manually using `react-native start`.
<block class="windows android" />
Or if you hit a `ERROR Watcher took too long to load` on Windows, try increasing the timeout in [this file](https://github.com/facebook/react-native/blob/5fa33f3d07f8595a188f6fe04d6168a6ede1e721/packager/react-packager/src/DependencyResolver/FileWatcher/index.js#L16) (under your `node_modules/react-native/`).
> If you hit a `ERROR Watcher took too long to load` on Windows, try increasing the timeout in [this file](https://github.com/facebook/react-native/blob/5fa33f3d07f8595a188f6fe04d6168a6ede1e721/packager/react-packager/src/DependencyResolver/FileWatcher/index.js#L16) (under your `node_modules/react-native/`).
<block class="windows linux android" />
### Modifying Project
### Modifying your app
Now that you successfully started the project, let's modify it:
Now that you have successfully run the app, let's modify it.
- Open `index.android.js` in your text editor of choice (e.g. [Nuclide](http://nuclide.io/docs/platforms/react-native/)) and edit some lines.
- Press the `R` key twice **OR** open the menu (F2 by default, or ctrl-M in the emulator) and select Reload JS to see your change!
- Run `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal to see your app's logs
- Open `index.android.js` in your text editor of choice and edit some lines.
- Press the `R` key twice or select `Reload` from the Developer Menu to see your change!
### That's It
### That's it!
Congratulations! You've successfully run and modified your first React Native app.
@@ -772,8 +292,7 @@ Congratulations! You've successfully run and modified your first React Native ap
<block class="mac ios android" />
- If you run into any issues getting started, see the [Troubleshooting page](docs/troubleshooting.html#content).
- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) and [Debugging](docs/debugging.html#content) pages.
<block class="windows linux android" />
@@ -781,7 +300,7 @@ Congratulations! You've successfully run and modified your first React Native ap
- If you want to run on a physical device, see the [Running on Android Device page](docs/running-on-device-android.html#content).
- If you run into any issues getting started, see the [Troubleshooting page](docs/troubleshooting.html#content).
- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) and [Debugging](docs/debugging.html#content) pages.
<script>
// Convert <div>...<span><block /></span>...</div>

15
docs/Troubleshooting.md
View File

@@ -14,6 +14,8 @@ Enable iOS simulator's "Connect hardware keyboard" from menu Hardware > Keyboard
If you are using a non-QWERTY/AZERTY keyboard layout you can use the `Hardware > Shake Gesture` to bring up the dev menu and click "Refresh". Alternatively, you can hit `Cmd-P` on Dvorak/Colemak layouts to reload the simulator.
You can use Cmd+M on Android to bring up the dev menu.
## Port already in use red-screen
![red-screen](https://cloud.githubusercontent.com/assets/602176/6857442/63fd4f0a-d3cc-11e4-871f-875b0c784611.png)
@@ -28,7 +30,6 @@ then
`$ kill -9 <cma process id>`
##### Change the port in Xcode
Edit `AppDelegate.m` to use a different port.
```
@@ -107,3 +108,15 @@ import Firebase from 'firebase';
Requiring firebase *before* react-native will result in a 'No transports available' redbox.
Discovered thanks to issue [#3645](https://github.com/facebook/react-native/issues/3645). If you're curious, the polyfills are set up in [InitializeJavaScriptAppEngine.js](https://github.com/facebook/react-native/blob/master/Libraries/JavaScriptAppEngine/Initialization/InitializeJavaScriptAppEngine.js).
## Shell Command Unresponsive Exception
If you encounter:
```
Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException
```
Try downgrading your Gradle version to 1.2.3 in `<project-name>/android/build.gradle` (https://github.com/facebook/react-native/issues/2720)