Android Setup

This guide covers setting up Android development for Rainbow Wallet on macOS, Linux, and Windows.

Prerequisites

Before setting up Android, ensure you have:

✅ Prerequisites installed (Node.js, Ruby)
✅ Dependencies installed (yarn install && yarn setup)

Installation Steps

Install JDK 17

Rainbow requires JDK 17. Do not use the JDK bundled with Android Studio (it’s JDK 21, which causes build failures).

macOS
Linux
Windows

Install Azul Zulu JDK 17 via Homebrew:

brew install --cask zulu@17

Verify installation:

/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home/bin/java -version

Install OpenJDK 17:

sudo apt update
sudo apt install openjdk-17-jdk

Verify installation:

java -version

Download Azul Zulu JDK 17 from https://www.azul.com/downloads/?package=jdk#zulu
Run the installer
Verify in Command Prompt:
```
java -version
```

Configure Environment Variables

Add Android SDK and Java paths to your shell profile.

macOS / Linux (zsh)
macOS / Linux (bash)
Windows

Add to ~/.zshrc:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
# export ANDROID_HOME=$HOME/Android/Sdk        # Linux
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

For Linux, also install system dependencies:

sudo apt install libsecret-tools watchman

Add to ~/.bashrc:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
# export ANDROID_HOME=$HOME/Android/Sdk        # Linux
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Add to System Environment Variables:

Open System Properties → Environment Variables
Add new variables:
- JAVA_HOME: C:\Program Files\Zulu\zulu-17
- ANDROID_HOME: C:\Users\YourUsername\AppData\Local\Android\Sdk
Edit Path and add:
- %ANDROID_HOME%\emulator
- %ANDROID_HOME%\platform-tools

After adding environment variables, restart any open terminals for changes to take effect.

Install Android Studio

Download and install Android Studio from https://developer.android.com/studio.

Run the installer
Follow the standard setup wizard (recommended)
Install Android SDK, SDK Platform, and Android Virtual Device

The wizard will install:

Android SDK
Android SDK Platform-Tools
Android SDK Build-Tools
Android Emulator

Configure Android Studio

After installation, configure Android Studio for Rainbow:

Increase IDE Memory

Rainbow is a large project. Increase the heap size:

Android Studio → Settings → Memory Settings (macOS: Preferences → Memory Settings)
Set IDE Heap Size to at least 4096 MB (default is 2048 MB)
Click Save and Restart

Set Gradle JDK

Configure Gradle to use JDK 17 (not the bundled JDK 21):

Settings → Build, Execution, Deployment → Build Tools → Gradle
Under Gradle JDK, select the JAVA_HOME (Azul Zulu 17) entry
Click Apply

The default Gradle JDK points to the bundled JDK 21, which will cause build failures.

Create Android Emulator

Create a virtual device for testing (skip if using a physical device):

Open Android Studio → Device Manager (or Tools → Device Manager)
Click Create Device
Select a phone (e.g., Pixel 6)
Download and select a system image (e.g., Android 13 - API 33)
Click Finish

You can also use a physical Android device. Enable Developer Options and USB Debugging on your device.

Run First Gradle Build

Run the first build from the terminal to generate native headers needed for Gradle sync:

cd android
./gradlew assembleDebug
cd ..

This first build can take 5-15 minutes. Subsequent builds are much faster.

Open Project in Android Studio

Always launch Android Studio from the terminal so it inherits your shell environment (including node from nvm).

macOS
Linux
Windows

open -a "Android Studio"

Then in Android Studio:

File → Open
Select the android/ folder
Wait for Gradle sync to complete

studio.sh

Or if installed via snap:

android-studio

Then open the android/ folder.

Launch from Command Prompt or PowerShell:

"C:\Program Files\Android\Android Studio\bin\studio64.exe"

Then open the android\ folder.

Always launch Android Studio from the terminal (not Spotlight/Dock/Start Menu). Launching from GUI won’t inherit your PATH, causing “Cannot run program node” errors during Gradle sync.

Android Build Configuration

Rainbow’s Android build is configured in android/build.gradle:

buildToolsVersion = "35.0.0"
minSdkVersion = 26
compileSdkVersion = 35
targetSdkVersion = 35
ndkVersion = "27.1.12297006"
kotlin_version = "2.1.20"

Minimum SDK

minSdkVersion: 26 (Android 8.0)
Supports Android 8.0 and above

Target SDK

targetSdkVersion: 35 (Android 15)
compileSdkVersion: 35

NDK Version

ndkVersion: 27.1.12297006
Native Development Kit for C/C++ libraries

Verify Android Setup

Check Java version

java -version

Should output: openjdk version "17.x.x"

Verify JAVA_HOME

echo $JAVA_HOME

Should point to JDK 17 installation.

Check Android SDK

echo $ANDROID_HOME
adb --version

adb (Android Debug Bridge) should be available.

List connected devices

adb devices

Should list your emulator or physical device (after starting it).

Test Gradle build

cd android
./gradlew tasks

Should list available Gradle tasks without errors.

Troubleshooting

Gradle sync failed: 'Cannot run program node'

Android Studio doesn’t have node in its PATH.Solution: Always launch Android Studio from terminal:

# macOS
open -a "Android Studio"

# Linux
studio.sh

This ensures Android Studio inherits your shell PATH (including nvm’s node).

Build fails with 'Unsupported Java version'

You’re using the wrong JDK version (likely JDK 21 bundled with Android Studio).Solution:

Install JDK 17 (see Step 1)
In Android Studio: Settings → Build Tools → Gradle → Gradle JDK
Select Azul Zulu 17

Command 'android' not found

The android command is deprecated. Use Android Studio’s GUI or sdkmanager:

$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --list

Emulator fails to start

Check virtualization is enabled:macOS: Virtualization is built-in.Linux:

# Check if KVM is available
egrep -c '(vmx|svm)' /proc/cpuinfo

# Install KVM
sudo apt install qemu-kvm

Windows: Enable Hyper-V or HAXM in BIOS.

Clean Android build

If you encounter persistent issues:

# Clean Android builds
yarn clean:android

# Or manually
cd android
./gradlew clean
rm -rf build
rm -rf app/build
cd ..

# Rebuild
cd android
./gradlew assembleDebug
cd ..

Port already in use (8081)

Metro bundler port is in use:

# Kill process on port 8081
lsof -ti:8081 | xargs kill -9

# Restart Metro
yarn start

adb: command not found

Android SDK platform-tools are not in your PATH:

export PATH=$PATH:$ANDROID_HOME/platform-tools

Add to your shell profile to make it permanent.

Gradle Commands

Useful Gradle commands for Android development:

cd android

# List all tasks
./gradlew tasks

# Build debug APK
./gradlew assembleDebug

# Build release APK
./gradlew assembleRelease

# Build release bundle (for Play Store)
./gradlew bundleRelease

# Clean build
./gradlew clean

# Install debug build on device
./gradlew installDebug

Or use yarn scripts:

# Build release APK
yarn android:apk

# Build release bundle
yarn android:bundle

# Run Gradle command
yarn gradle assembleDebug

ADB Commands

Android Debug Bridge (adb) commands:

# List connected devices
adb devices

# Install APK
adb install android/app/build/outputs/apk/release/app-release.apk

# Uninstall app
adb uninstall me.rainbow

# Reverse ports for Metro bundler
adb reverse tcp:8081 tcp:8081

# View device logs
adb logcat

# Clear app data
adb shell pm clear me.rainbow

Yarn scripts for ADB:

# Reverse ports (single device)
yarn android-reverse-ports

# Reverse ports (all devices)
yarn android-reverse-ports-all

# Uninstall app
yarn uninstall:android

Introduction

Setup

Development

Prerequisites

Installation Steps

Increase IDE Memory

Set Gradle JDK

Android Build Configuration

Minimum SDK

Target SDK

NDK Version

Verify Android Setup

Troubleshooting

Gradle Commands

ADB Commands

Next Steps

Running the App

Building

Additional Resources

Build docs developers (and LLMs) love

Introduction

Setup

Development

​Prerequisites

​Installation Steps

​Increase IDE Memory

​Set Gradle JDK

​Android Build Configuration

​Minimum SDK

​Target SDK

​NDK Version

​Verify Android Setup

​Troubleshooting

​Gradle Commands

​ADB Commands

​Next Steps

Running the App

Building

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Increase IDE Memory

Set Gradle JDK

Android Build Configuration

Minimum SDK

Target SDK

NDK Version

Verify Android Setup

Troubleshooting

Gradle Commands

ADB Commands

Next Steps

Additional Resources