Skip to content

Commit

Permalink
Update the "Build from source" page (#3570)
Browse files Browse the repository at this point in the history 
* Update build-from-source page

* Update website/contributing/how-to-build-from-source.md
  • Loading branch information
@cortinico
cortinico authored Feb 16, 2023
1 parent b023540 commit 50a01ac
Showing 1 changed file with 21 additions and 206 deletions.
227 changes: 21 additions & 206 deletions website/contributing/how-to-build-from-source.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,139 +8,38 @@ You will need to build React Native from source if you want to work on a new fea

### Prerequisites

Assuming you have the Android SDK installed, run `android` to open the Android SDK Manager.
To build from source, you need to have the Android SDK installed. If you followed the [Setting up the development environment](/docs/environment-setup) guide, you should already be set up.

Make sure you have the following installed:
There is no need to install other tools like specific version of NDK or CMake as the Android SDK will **automatically download** whatever is needed for the build from source.

1. Android SDK (find the specific version in the `compileSdkVersion` in [`build.gradle`](https://github.com/facebook/react-native/blob/main/ReactAndroid/build.gradle#L253)).
2. Android NDK
### Point your project to a nightly

#### Point Gradle to your Android SDK

**Step 1:** Set environment variables through your local shell.

:::note
Files may vary based on shell flavor. See below for examples from common shells.
:::

- bash: `.bash_profile` or `.bashrc`
- zsh: `.zprofile` or `.zshrc`
- ksh: `.profile` or `$ENV`

Example:
To use the latest fixes and features of React Native, you can update your project to use a nightly version of React Native with:

```
export ANDROID_SDK=/Users/your_unix_name/android-sdk-macosx
export ANDROID_NDK=/Users/your_unix_name/android-ndk/android-ndk-r20b
yarn add react-native@nightly
```

**Step 2:** Create a `local.properties` file in the `android` directory of your react-native app with the following contents:

Example:

```
sdk.dir=/Users/your_unix_name/android-sdk-macosx
ndk.dir=/Users/your_unix_name/android-ndk/android-ndk-r20b
```

#### Download links for Android NDK

You can find the instructions to install the NDK on the [official Android NDK website](https://developer.android.com/studio/projects/install-ndk).

### Building the source
This will update your project to use a nightly version of React Native that gets released every night with the latest changes.

#### 1. Installing from the fork
### Update your project to build from source

First, you need to clone `react-native` from the repo you want to use locally inside the `node_modules` folder. For example, if you wish to build against `main` of this repo:

```sh
mkdir node_modules
git clone git@github.com:facebook/react-native.git node_modules/react-native
```

#### 2. Adding gradle dependencies

Update the `android/build.gradle` to make sure you're using AGP 7.x and add the highlighted lines.
Both with stable releases and nightlies, you will be consuming **precompiled** artifacts. If instead you want to switch to building from source, so you can test your changes to the framework directly, you will have to edit the `android/settings.gradle` file as follows:

```diff
buildscript {
// ...
dependencies {
// Make sure that AGP is at least at version 7.x
classpath("com.android.tools.build:gradle:7.0.4")
+ classpath("com.facebook.react:react-native-gradle-plugin")
+ classpath("de.undercouch:gradle-download-task:5.0.1")
}
}
```

#### 3. Adding the `:ReactAndroid` project

Add the `:ReactAndroid` project in `android/settings.gradle`:

```groovy
pluginManagement {
repositories {
gradlePluginPortal()
mavenLocal()
google()
}
}
// ...
include ':ReactAndroid'
project(':ReactAndroid').projectDir = new File(
rootProject.projectDir, '../node_modules/react-native/ReactAndroid')
// Includes React Native Gradle Plugin into Gradle project. Required by `:ReactAndroid` project configuration.
includeBuild('../node_modules/react-native/packages/react-native-gradle-plugin')
// ...
```

Modify your `android/app/build.gradle` to use the `:ReactAndroid` project instead of the pre-compiled library, e.g. - replace `implementation 'com.facebook.react:react-native:+'` with `implementation project(':ReactAndroid')`:

```groovy
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
implementation project(':ReactAndroid')
// ...
}
```

#### 4. Making 3rd-party modules use your fork

If you use 3rd-party React Native modules, you need to override their dependencies so that they don't bundle the pre-compiled library. Otherwise you'll get an error while compiling:

```
Error: more than one library with package name 'com.facebook.react'
```

Modify your `android/build.gradle`, and add:

```groovy
allprojects {
repositories { /* ... */ }
configurations.all {
resolutionStrategy {
dependencySubstitution {
substitute module("com.facebook.react:react-native:+") with project(":ReactAndroid")
}
}
}
}
// ...
include ':app'
includeBuild('../node_modules/react-native-gradle-plugin')
+ includeBuild('../node_modules/react-native') {
+ dependencySubstitution {
+ substitute(module("com.facebook.react:react-android")).using(project(":ReactAndroid"))
+ substitute(module("com.facebook.react:react-native")).using(project(":ReactAndroid"))
+ substitute(module("com.facebook.react:hermes-android")).using(project(":ReactAndroid:hermes-engine"))
+ substitute(module("com.facebook.react:hermes-engine")).using(project(":ReactAndroid:hermes-engine"))
+ }
+ }
```

### Building from Android Studio

From the Welcome screen of Android Studio choose "Import project" and select the `android` folder of your app.

You should be able to use the _Run_ button to run your app on a device. Android Studio won't start the packager automatically, you'll need to start it by running `npm start` on the command line.

### Additional notes

Building from source can take a long time, especially for the first build, as it needs to download ~200 MB of artifacts and compile the native code.
Expand All @@ -156,92 +55,8 @@ gradle.projectsLoaded {
}
```

### Troubleshooting

Gradle build fails in `ndk-build`. See the section about `local.properties` file above.

## Publish your own version of React Native

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than [Docker](https://docs.docker.com/install/)), which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native [repo](https://github.com/facebook/react-native).

```bash
git checkout -d release/my-react-native-release
npm install
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push
```

Install it in your app project package.json.

```json
"dependencies": {
// ...
"react-native": "myName/react-native#release/my-react-native-release"
}
```

## Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue.

Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

## Building

This binary needs to become available in your project's `node_modules/react-native/android` folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

```$bash
./gradlew :ReactAndroid:installArchives --no-daemon
```

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a React Native binary.

```bash
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
```

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

### Publishing to Maven/Nexus

Upload the binaries from the `android` folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

### Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR.

To start making your dependency branch, make sure you are on a `release/my-forked-release` branch, then merge any commits that you need from yourself or others into this branch.

:::warning
This release branch should never be merged into any other branch.
:::

```bash
# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push
```

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

```json
"dependencies": {
// ...
"react-native": "my-name/react-native#release/my-forked-release",
}
```
The recommended approach to working with React Native is to always update to the latest version. The support we provide for older versions is [described in our support policy](https://github.com/reactwg/react-native-releases/#releases-support-policy).

No other modifications to your dependencies should be necessary for your native changes to be included in your project.
The build from source approach should be used to end-to-end test a fix before submitting a pull request to React Native, and we're not encouraging its usages in the long run. Especially forking React Native or switching your setup to always use a build from source, will result in projects that are harder to update and generally a worse developer experience.

0 comments on commit 50a01ac

Please sign in to comment.