Building on Android

Complete guide to building and developing Dolphin Emulator for Android

System Requirements

Android 5.0 Lollipop or higher is required to run Dolphin.

Hardware Requirements

• Processor: 64-bit processor (ARMv8 or x86-64)
• Graphics: OpenGL ES 3.0 or higher (standard desktop OpenGL features recommended for best performance)

Dolphin can only be installed on devices that satisfy these requirements. Attempting to install on an unsupported device will fail and display an error message.

Performance Considerations

Performance varies heavily with driver quality. See the Dolphin and OpenGL Drivers article for more information.

Development Prerequisites

1. Install Android Studio

   Download and install Android Studio with default options.

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

2. Clone the Repository

   Clone the Dolphin repository and initialize submodules:

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

   Make sure to pull submodules before building. Building without submodules will fail.

Building with Android Studio

1. Open Project

   Open the Source/Android project in Android Studio.

   Let any background tasks finish. Android Studio will automatically:

   • Download required SDK components
   • Download build tools and dependencies
   • Sync Gradle files
2. Wait for Sync

   Wait for Gradle sync and background tasks to complete.

   You can monitor progress in the bottom status bar.

3. Build the App

   Use one of these methods to build:

   Build APK

   1. Use the hammer icon or Build > Assemble ‘app’ Run Configuration
   2. Choose Build > Generate App Bundles or APKs > Generate APKs
   3. APK will be created in Source/Android/app/build/outputs/apk

   Run on Device

   1. Connect your Android device via USB (with USB debugging enabled)
   2. Click the Run button (green triangle) or press Shift+F10
   3. Select your device from the list

   Run on Emulator

   1. Create an Android Virtual Device (AVD) in AVD Manager
   2. Click the Run button (green triangle)
   3. Select the emulator from the list

   Emulator performance for Dolphin may be very poor. Physical devices are recommended.

Build System Overview

Dolphin’s Android app uses a dual build system:

Gradle

Compiles the Java/Kotlin Android application code.

CMake

Compiles Dolphin’s native C++ component.

The Gradle script automatically runs CMake builds when building the Java code. You don’t need to invoke CMake manually.

Code Style Configuration

The project maintains a custom IntelliJ/Android Studio style file for consistent Java and Kotlin formatting.

1. Open Settings

   Navigate to File > Settings > Editor > Code Style

   (On macOS: Android Studio > Settings > Editor > Code Style)

2. Import Scheme

   1. Click the gear icon
   2. Choose Import Scheme
   3. Select Source/Android/code-style-java.xml from the repository
3. Select Scheme

   Ensure that Dolphin-Java is selected as the active code style scheme.

Format Code Before Committing

Before submitting a pull request, reformat any Java or Kotlin files you modified:

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

Re-run formatting after edits to keep spacing, imports, and wrapping consistent with the rest of the project.

Command-Line Building

For command-line users or CI/CD pipelines:

1. Navigate to Android directory

   cd Source/Android
   
2. Run Gradle tasks

   Execute any Gradle task using the wrapper:

   Assemble APKs

   # Build debug and release APKs
   ./gradlew assemble
   
   # APKs will be in:
   # app/build/outputs/apk/debug/
   # app/build/outputs/apk/release/
   

Windows Users

On Windows, use gradlew.bat instead of ./gradlew:

gradlew.bat assemble

Project Structure

Key directories in Source/Android:

Source/Android/
├── app/                    # Main application module
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/      # Java/Kotlin source code
│   │   │   ├── res/       # Android resources
│   │   │   └── jni/       # JNI interface to C++ code
│   │   └── debug/         # Debug-specific code
│   └── build.gradle       # App module build config
├── gradle/                # Gradle wrapper files
├── build.gradle           # Root build configuration
└── code-style-java.xml    # Code style configuration

Troubleshooting

Gradle sync fails

1. Ensure you have a stable internet connection
2. Click File > Invalidate Caches and Restart
3. Delete .gradle folder and sync again:

rm -rf .gradle

Then sync in Android Studio.

CMake build fails

Ensure submodules are initialized:

git submodule update --init --recursive

Check that NDK is installed in Android Studio:

• Tools > SDK Manager > SDK Tools
• Check NDK (Side by side)

Build fails with submodule errors

Ensure you’ve initialized and updated all submodules:

git submodule update --init --recursive

Device not detected

1. Enable Developer Options on your Android device:
   • Go to Settings > About Phone
   • Tap Build Number 7 times
2. Enable USB Debugging in Developer Options
3. Connect device and accept the debugging prompt
4. Verify connection:

adb devices

Installation fails on device

Your device may not meet the minimum requirements:

• Android 5.0+ required
• 64-bit processor required (ARMv8 or x86-64)
• OpenGL ES 3.0+ support required

Check device specifications and ensure it meets all requirements.

Slow build times

1. Enable Gradle daemon (usually enabled by default)
2. Increase Gradle memory in gradle.properties:

org.gradle.jvmargs=-Xmx4096m

3. Use parallel builds:

org.gradle.parallel=true

Testing on Devices

Physical devices are strongly recommended for testing Dolphin. Emulator performance is typically insufficient for GameCube/Wii emulation.

Recommended Test Devices

• Recent flagship devices (Snapdragon 8 series, Google Tensor, etc.)
• Devices with good OpenGL ES driver support
• At least 4GB RAM recommended

Performance Tips

Use Release Builds

Debug builds are significantly slower. Always test performance with release builds.

Check Driver Support

Performance varies heavily with GPU driver quality. See the driver quality article for details.

Test on Real Hardware

Android emulators cannot accurately represent Dolphin performance. Always test on physical devices.

Monitor Thermal Throttling

GameCube/Wii emulation is demanding. Monitor device temperature during extended testing.

Contributing

When contributing to Dolphin Android:

1. Follow the code style by importing code-style-java.xml
2. Reformat code before committing
3. Test on multiple devices if possible
4. Ensure both debug and release builds work
5. Update submodules when necessary

See the main Contributing Guide for more details.