Building for Android

Complete guide to building Dolphin Emulator for Android with Gradle and Android Studio

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

1. Clone the Repository
2. git clone https://github.com/dolphin-emu/dolphin.git
   cd dolphin
   

3. Initialize Submodules
4. git submodule update --init --recursive
   

5. Skipping this step will cause build failures.

6. Open the Project
8. Wait for Background Tasks
9. Android Studio will automatically:
11. Allow these tasks to complete before building.
12. Build the APK
13. Build the app using one of these methods:
14. 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
    
15. Locate the APK
16. After building, APK files are located in:
17. Source/Android/app/build/outputs/apk/
    

18. Build variants:

Building from Command Line

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

1. Clone and Initialize
2. git clone https://github.com/dolphin-emu/dolphin.git
   cd dolphin
   git submodule update --init --recursive
   

3. Navigate to Android Directory
4. cd Source/Android
   

5. Build with Gradlew
6. Linux/macOS - All Variants

   ./gradlew assemble
   

   Windows - All Variants

   gradlew.bat assemble
   

   Debug Build Only

   ./gradlew assembleDebug
   

   Release Build Only

   ./gradlew assembleRelease
   
7. Locate Output APKs
8. APKs are created in:
9. 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

1. Gradle manages Java/Kotlin code compilation
2. Gradle automatically invokes CMake to build native C++ components
3. CMake builds the Dolphin core libraries
4. 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

1. Open Settings
2. Navigate to:
4. Import Scheme
6. Verify Selection
7. 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:

1. Ensure submodules are initialized
2. 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

1. Connect your device or start an emulator
2. Click the Run button (green triangle) in the toolbar
3. Select your target device
4. 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.