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

> Complete guide to building and developing Dolphin Emulator for Android

## System Requirements

<Note>
  Android 5.0 Lollipop or higher is required to run Dolphin.
</Note>

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

<Warning>
  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.
</Warning>

### Performance Considerations

Performance varies heavily with driver quality. See the [Dolphin and OpenGL Drivers article](https://dolphin-emu.org/blog/2013/09/26/dolphin-emulator-and-opengl-drivers-hall-fameshame/) for more information.

## Development Prerequisites

<Steps>
  <Step title="Install Android Studio">
    Download and install [Android Studio](https://developer.android.com/studio/) with default options.

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

  <Step title="Clone the Repository">
    Clone the Dolphin repository and initialize submodules:

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

    <Warning>
      Make sure to pull submodules before building. Building without submodules will fail.
    </Warning>
  </Step>
</Steps>

## Building with Android Studio

<Steps>
  <Step title="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
  </Step>

  <Step title="Wait for Sync">
    Wait for Gradle sync and background tasks to complete.

    You can monitor progress in the bottom status bar.
  </Step>

  <Step title="Build the App">
    Use one of these methods to build:

    <Tabs>
      <Tab title="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`
      </Tab>

      <Tab title="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
      </Tab>

      <Tab title="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

        <Note>
          Emulator performance for Dolphin may be very poor. Physical devices are recommended.
        </Note>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Build System Overview

Dolphin's Android app uses a dual build system:

<CardGroup cols={2}>
  <Card title="Gradle" icon="java">
    Compiles the Java/Kotlin Android application code.
  </Card>

  <Card title="CMake" icon="c">
    Compiles Dolphin's native C++ component.
  </Card>
</CardGroup>

<Note>
  The Gradle script automatically runs CMake builds when building the Java code. You don't need to invoke CMake manually.
</Note>

## Code Style Configuration

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

<Steps>
  <Step title="Open Settings">
    Navigate to **File > Settings > Editor > Code Style**

    (On macOS: **Android Studio > Settings > Editor > Code Style**)
  </Step>

  <Step title="Import Scheme">
    1. Click the gear icon
    2. Choose **Import Scheme**
    3. Select `Source/Android/code-style-java.xml` from the repository
  </Step>

  <Step title="Select Scheme">
    Ensure that **Dolphin-Java** is selected as the active code style scheme.
  </Step>
</Steps>

### Format Code Before Committing

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

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

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

## Command-Line Building

For command-line users or CI/CD pipelines:

<Steps>
  <Step title="Navigate to Android directory">
    ```bash theme={null}
    cd Source/Android
    ```
  </Step>

  <Step title="Run Gradle tasks">
    Execute any Gradle task using the wrapper:

    <CodeGroup>
      ```bash Assemble APKs theme={null}
      # Build debug and release APKs
      ./gradlew assemble

      # APKs will be in:
      # app/build/outputs/apk/debug/
      # app/build/outputs/apk/release/
      ```

      ```bash Build Specific Variants theme={null}
      # Debug build only
      ./gradlew assembleDebug

      # Release build only
      ./gradlew assembleRelease
      ```

      ```bash Clean Build theme={null}
      # Clean previous builds
      ./gradlew clean

      # Clean and build
      ./gradlew clean assembleRelease
      ```

      ```bash Run Tests theme={null}
      # Run unit tests
      ./gradlew test

      # Run instrumented tests (requires connected device)
      ./gradlew connectedAndroidTest
      ```
    </CodeGroup>
  </Step>
</Steps>

### Windows Users

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

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

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    rm -rf .gradle
    ```

    Then sync in Android Studio.
  </Accordion>

  <Accordion title="CMake build fails">
    Ensure submodules are initialized:

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

    Check that NDK is installed in Android Studio:

    * **Tools > SDK Manager > SDK Tools**
    * Check **NDK (Side by side)**
  </Accordion>

  <Accordion title="Build fails with submodule errors">
    Ensure you've initialized and updated all submodules:

    ```bash theme={null}
    git submodule update --init --recursive
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    adb devices
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Slow build times">
    1. Enable Gradle daemon (usually enabled by default)
    2. Increase Gradle memory in `gradle.properties`:

    ```properties theme={null}
    org.gradle.jvmargs=-Xmx4096m
    ```

    3. Use parallel builds:

    ```properties theme={null}
    org.gradle.parallel=true
    ```
  </Accordion>
</AccordionGroup>

## Testing on Devices

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

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

<CardGroup cols={2}>
  <Card title="Use Release Builds" icon="rocket">
    Debug builds are significantly slower. Always test performance with release builds.
  </Card>

  <Card title="Check Driver Support" icon="circle-check">
    Performance varies heavily with GPU driver quality. See the driver quality article for details.
  </Card>

  <Card title="Test on Real Hardware" icon="mobile">
    Android emulators cannot accurately represent Dolphin performance. Always test on physical devices.
  </Card>

  <Card title="Monitor Thermal Throttling" icon="temperature-high">
    GameCube/Wii emulation is demanding. Monitor device temperature during extended testing.
  </Card>
</CardGroup>

## 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](https://github.com/dolphin-emu/dolphin/blob/master/Contributing.md) for more details.