Building for Android - Dolphin Emulator

Dolphin for Android uses Gradle as the build system, which automatically invokes CMake to build native components. This guide covers building with both Android Studio and the command line.

Prerequisites

Required Software

Android Studio: Latest stable version
Git: For cloning the repository
Android SDK: Automatically installed by Android Studio
Android NDK: Automatically installed by Android Studio

Android Studio will automatically download required SDK components and tooling when you open the project.

Platform Requirements

Minimum Android Version: 5.0 Lollipop (API 21)
Target Architectures: ARMv8 (ARM64) and x86-64
Graphics: OpenGL ES 3.0 or higher required

Building with Android Studio

Clone the Repository

git clone https://github.com/dolphin-emu/dolphin.git
cd dolphin

Initialize Submodules

git submodule update --init --recursive

Skipping this step will cause build failures.

Open the Project

Launch Android Studio

Select File > Open

Navigate to and select the Source/Android directory

Click OK

Wait for Background Tasks

Android Studio will automatically:

Download required SDK components

Download the Android NDK

Sync Gradle dependencies

Index the project

Allow these tasks to complete before building.

Build the APK

Build the app using one of these methods:

Build Menu

Build > Assemble 'app' Run Configuration

Toolbar

Click the hammer icon in the toolbar

Generate APK

Build > Generate App Bundles or APKs > Generate APKs

Locate the APK

After building, APK files are located in:

Source/Android/app/build/outputs/apk/

Build variants:

debug/ - Debug build with debugging symbols

release/ - Optimized release build (requires signing)

Building from Command Line

For automation or CI/CD, build from the command line using Gradle.

Clone and Initialize

git clone https://github.com/dolphin-emu/dolphin.git
cd dolphin
git submodule update --init --recursive

Navigate to Android Directory

cd Source/Android

Build with Gradlew

Linux/macOS - All Variants

./gradlew assemble

Windows - All Variants

gradlew.bat assemble

Debug Build Only

./gradlew assembleDebug

Release Build Only

./gradlew assembleRelease

Locate Output APKs

APKs are created in:

app/build/outputs/apk/debug/
app/build/outputs/apk/release/

Build Variants

Debug Build

Purpose: Development and testing
Characteristics:
- Includes debug symbols
- No optimization (slower)
- Allows debugging with Android Studio
- Automatically signed with debug keystore

./gradlew assembleDebug

Release Build

Purpose: Distribution and production
Characteristics:
- Optimized for performance
- Smaller APK size
- Requires release keystore for signing
- ProGuard/R8 code shrinking enabled

./gradlew assembleRelease

Release builds require proper signing configuration. Unsigned release APKs cannot be installed.

Architecture Support

Dolphin for Android supports two architectures:

ARM64 (ARMv8)

Most Android devices (phones, tablets)
Recommended for best compatibility
Primary target architecture

x86-64

Android emulators (Android Studio AVD)
Some Intel/AMD-based Android devices
Chromebooks with x86 processors

32-bit devices (ARMv7, x86) are not supported. Attempting to install on 32-bit devices will fail with an error.

Gradle Build System

How It Works

Gradle manages Java/Kotlin code compilation
Gradle automatically invokes CMake to build native C++ components
CMake builds the Dolphin core libraries
Gradle packages everything into an APK

Gradle Tasks

Common Gradle tasks:

# List all available tasks
./gradlew tasks

# Clean build artifacts
./gradlew clean

# Build all variants
./gradlew assemble

# Build and install debug APK to connected device
./gradlew installDebug

# Run unit tests
./gradlew test

# Build Android App Bundle (for Google Play)
./gradlew bundleRelease

Code Style and Formatting

Dolphin maintains a consistent code style for Java and Kotlin.

Import Code Style

Open Settings

Navigate to:

Windows/Linux: File > Settings > Editor > Code Style

macOS: Android Studio > Settings > Editor > Code Style

Import Scheme

Click the gear icon

Choose Import Scheme

Select Source/Android/code-style-java.xml from the repository

Click OK

Verify Selection

Ensure Dolphin-Java is selected in the scheme dropdown.

Format Before Committing

Before submitting changes:

Code > Reformat Code (Ctrl+Alt+L on Windows/Linux, ⌥⌘L on macOS)

Run formatting after every edit to maintain consistency with the project.

Advanced Build Options

Custom CMake Arguments

Pass custom CMake arguments through Gradle:

./gradlew assembleDebug -DCMAKE_BUILD_TYPE=Debug

Building Specific ABIs

Build for specific architectures only:

// In app/build.gradle
android {
    defaultConfig {
        ndk {
            abiFilters 'arm64-v8a'  // ARM64 only
            // abiFilters 'x86_64'  // x86-64 only
        }
    }
}

Parallel Builds

Speed up builds with parallel execution:

./gradlew assemble --parallel --max-workers=4

Build Cache

Enable Gradle build cache:

./gradlew assemble --build-cache

Signing Release Builds

Release builds require signing with a keystore.

Create a Keystore

keytool -genkey -v -keystore dolphin-release.keystore \
  -alias dolphin -keyalg RSA -keysize 2048 -validity 10000

Configure Signing

Create keystore.properties in Source/Android/:

storeFile=/path/to/dolphin-release.keystore
storePassword=your_store_password
keyAlias=dolphin
keyPassword=your_key_password

Never commit keystore.properties or keystore files to version control.

Build Signed APK

./gradlew assembleRelease

Troubleshooting

SDK/NDK Not Found

Error: Android SDK or NDK not found Solution: Open the project in Android Studio and let it download required components automatically.

Submodules Not Initialized

Error: Missing files from Externals Solution:

git submodule update --init --recursive

CMake Build Failures

Error: Native build fails during Gradle execution Solution:

Ensure submodules are initialized

Clean the build:

./gradlew clean
rm -rf app/.cxx
./gradlew assemble

Out of Memory During Build

Error: Gradle daemon runs out of memory Solution: Increase heap size in gradle.properties:

org.gradle.jvmargs=-Xmx4096m

APK Installation Failed

Error: Cannot install APK on device Solution:

Ensure device supports 64-bit apps (ARMv8 or x86-64)
Check minimum Android version (5.0+)
Verify USB debugging is enabled
For release builds, ensure proper signing

Build Errors After Git Pull

Solution: Clean and rebuild:

cd Source/Android
./gradlew clean
rm -rf app/.cxx app/build
git submodule update --init --recursive
./gradlew assemble

Running on Device or Emulator

Install Debug Build

# Install to connected device
./gradlew installDebug

# Install and launch
adb install app/build/outputs/apk/debug/app-debug.apk

Using Android Studio

Connect your device or start an emulator
Click the Run button (green triangle) in the toolbar
Select your target device
Android Studio will build, install, and launch the app

Building App Bundles

For Google Play distribution, build an Android App Bundle (AAB):

./gradlew bundleRelease

Output location:

app/build/outputs/bundle/release/app-release.aab

Next Steps

After building:

APKs are in Source/Android/app/build/outputs/apk/
Install on device with adb install <apk-file>
Or use Android Studio’s Run button for automatic installation
Debug builds can be distributed directly for testing
Release builds require signing for distribution

For contributing to the Android project, ensure you format code using the imported Dolphin code style before submitting pull requests.

Building

Architecture

Contributing

Technical Specs

​Prerequisites

​Required Software

​Platform Requirements

​Building with Android Studio

​Building from Command Line

​Build Variants

​Debug Build

​Release Build

​Architecture Support

​ARM64 (ARMv8)

​x86-64

​Gradle Build System

​How It Works

​Gradle Tasks

​Code Style and Formatting

​Import Code Style

​Format Before Committing

​Advanced Build Options

​Custom CMake Arguments

​Building Specific ABIs

​Parallel Builds

​Build Cache

​Signing Release Builds

​Create a Keystore

​Configure Signing

​Build Signed APK

​Troubleshooting

​SDK/NDK Not Found

​Submodules Not Initialized

​CMake Build Failures

​Out of Memory During Build

​APK Installation Failed

​Build Errors After Git Pull

​Running on Device or Emulator

​Install Debug Build

​Using Android Studio

​Building App Bundles

​Next Steps

Prerequisites

Required Software

Platform Requirements

Building with Android Studio

Building from Command Line

Build Variants

Debug Build

Release Build

Architecture Support

ARM64 (ARMv8)

x86-64

Gradle Build System

How It Works

Gradle Tasks

Code Style and Formatting

Import Code Style

Format Before Committing

Advanced Build Options

Custom CMake Arguments

Building Specific ABIs

Parallel Builds

Build Cache

Signing Release Builds

Create a Keystore

Configure Signing

Build Signed APK

Troubleshooting

SDK/NDK Not Found

Submodules Not Initialized

CMake Build Failures

Out of Memory During Build

APK Installation Failed

Build Errors After Git Pull

Running on Device or Emulator

Install Debug Build

Using Android Studio

Building App Bundles

Next Steps