> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dolphin-emu/dolphin/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

### 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

<Steps>
  ### Clone the Repository

  ```bash theme={null}
  git clone https://github.com/dolphin-emu/dolphin.git
  cd dolphin
  ```

  ### Initialize Submodules

  ```bash theme={null}
  git submodule update --init --recursive
  ```

  <Warning>
    Skipping this step will cause build failures.
  </Warning>

  ### Open the Project

  1. Launch Android Studio
  2. Select **File > Open**
  3. Navigate to and select the `Source/Android` directory
  4. 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:

  <CodeGroup>
    ```text Build Menu theme={null}
    Build > Assemble 'app' Run Configuration
    ```

    ```text Toolbar theme={null}
    Click the hammer icon in the toolbar
    ```

    ```text Generate APK theme={null}
    Build > Generate App Bundles or APKs > Generate APKs
    ```
  </CodeGroup>

  ### 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)
</Steps>

## Building from Command Line

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

<Steps>
  ### Clone and Initialize

  ```bash theme={null}
  git clone https://github.com/dolphin-emu/dolphin.git
  cd dolphin
  git submodule update --init --recursive
  ```

  ### Navigate to Android Directory

  ```bash theme={null}
  cd Source/Android
  ```

  ### Build with Gradlew

  <CodeGroup>
    ```bash Linux/macOS - All Variants theme={null}
    ./gradlew assemble
    ```

    ```bash Windows - All Variants theme={null}
    gradlew.bat assemble
    ```

    ```bash Debug Build Only theme={null}
    ./gradlew assembleDebug
    ```

    ```bash Release Build Only theme={null}
    ./gradlew assembleRelease
    ```
  </CodeGroup>

  ### Locate Output APKs

  APKs are created in:

  ```
  app/build/outputs/apk/debug/
  app/build/outputs/apk/release/
  ```
</Steps>

## 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

```bash theme={null}
./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

```bash theme={null}
./gradlew assembleRelease
```

<Warning>
  Release builds require proper signing configuration. Unsigned release APKs cannot be installed.
</Warning>

## 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

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

## 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:

```bash theme={null}
# 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

<Steps>
  ### Open Settings

  Navigate to:

  * **Windows/Linux**: **File > Settings > Editor > Code Style**
  * **macOS**: **Android Studio > Settings > Editor > Code Style**

  ### Import Scheme

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

  ### Verify Selection

  Ensure **Dolphin-Java** is selected in the scheme dropdown.
</Steps>

### Format Before Committing

Before submitting changes:

```text theme={null}
Code > Reformat Code (Ctrl+Alt+L on Windows/Linux, ⌥⌘L on macOS)
```

<Note>
  Run formatting after every edit to maintain consistency with the project.
</Note>

## Advanced Build Options

### Custom CMake Arguments

Pass custom CMake arguments through Gradle:

```bash theme={null}
./gradlew assembleDebug -DCMAKE_BUILD_TYPE=Debug
```

### Building Specific ABIs

Build for specific architectures only:

```groovy theme={null}
// 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:

```bash theme={null}
./gradlew assemble --parallel --max-workers=4
```

### Build Cache

Enable Gradle build cache:

```bash theme={null}
./gradlew assemble --build-cache
```

## Signing Release Builds

Release builds require signing with a keystore.

### Create a Keystore

```bash theme={null}
keytool -genkey -v -keystore dolphin-release.keystore \
  -alias dolphin -keyalg RSA -keysize 2048 -validity 10000
```

### Configure Signing

Create `keystore.properties` in `Source/Android/`:

```properties theme={null}
storeFile=/path/to/dolphin-release.keystore
storePassword=your_store_password
keyAlias=dolphin
keyPassword=your_key_password
```

<Warning>
  Never commit `keystore.properties` or keystore files to version control.
</Warning>

### Build Signed APK

```bash theme={null}
./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**:

```bash theme={null}
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:
   ```bash theme={null}
   ./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`:

```properties theme={null}
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:

```bash theme={null}
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

```bash theme={null}
# 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):

```bash theme={null}
./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

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