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

> Complete guide to building Dolphin Emulator on macOS including universal binaries

## System Requirements

<Note>
  macOS 11.0 Big Sur or higher is required to run Dolphin.
</Note>

### Hardware Requirements

* **Processor**: CPU with SSE2 support (modern 3 GHz Dual Core recommended, not older than 2008)
* **Graphics**: Graphics card supporting OpenGL 3.3 (OpenGL 4.4 recommended)

## Build Requirements

### Required Tools

* **CMake** - Build system generator
* **Xcode Command Line Tools** - Provides Clang compiler with C++20 support
* **Git** - Version control
* **Python 3** - Required for universal binary builds

### Installing Prerequisites

Install Xcode Command Line Tools:

```bash theme={null}
xcode-select --install
```

Install CMake (via Homebrew):

```bash theme={null}
brew install cmake
```

<Note>
  CMake will inform you if your compiler is too old or if you need to install any missing packages.
</Note>

## Building Dolphin

### Clone the Repository

First, 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>

### Build Methods

Dolphin can be built for a single architecture or as a universal binary supporting both x64 and ARM:

<Tabs>
  <Tab title="Single Architecture">
    Build a binary supporting your current architecture (Intel x64 or Apple Silicon ARM).

    <Steps>
      <Step title="Create build directory">
        ```bash theme={null}
        mkdir build
        cd build
        ```
      </Step>

      <Step title="Configure with CMake">
        ```bash theme={null}
        cmake ..
        ```

        CMake will automatically detect your architecture and configure accordingly.
      </Step>

      <Step title="Compile">
        ```bash theme={null}
        make -j $(sysctl -n hw.logicalcpu)
        ```

        This uses all available CPU cores for faster compilation.
      </Step>

      <Step title="Locate application bundle">
        An application bundle will be created in `./Binaries/Dolphin.app`.

        You can now run Dolphin by opening the app bundle.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Universal Binary">
    Build a universal binary supporting both x64 (Intel) and ARM (Apple Silicon) in the same application bundle.

    <Steps>
      <Step title="Create build directory">
        ```bash theme={null}
        mkdir build
        cd build
        ```
      </Step>

      <Step title="Run universal binary script">
        ```bash theme={null}
        python ../BuildMacOSUniversalBinary.py
        ```

        The script located at `BuildMacOSUniversalBinary.py` handles the complex universal build process.
      </Step>

      <Step title="Wait for compilation">
        The script will:

        1. Build the x64 (Intel) version
        2. Build the ARM (Apple Silicon) version
        3. Combine them into a universal binary

        This process takes longer than a single-architecture build.
      </Step>

      <Step title="Locate universal binary">
        Universal binaries will be available in the `universal` folder.

        ```bash theme={null}
        open universal/Dolphin.app
        ```
      </Step>
    </Steps>

    <Note>
      Building universal binaries requires installation of library dependencies for both x64 and ARM (or universal library equivalents).
    </Note>

    ### Advanced Universal Binary Options

    The `BuildMacOSUniversalBinary.py` script supports additional arguments for complex build scenarios:

    ```bash theme={null}
    python ../BuildMacOSUniversalBinary.py --help
    ```

    You may need to specify additional arguments to point to relevant library locations if you have architecture-specific dependencies installed.
  </Tab>
</Tabs>

## Running Dolphin

After building, you can run Dolphin in several ways:

<Tabs>
  <Tab title="From Finder">
    Navigate to the `Binaries` (or `universal`) folder and double-click `Dolphin.app`.
  </Tab>

  <Tab title="From Terminal">
    ```bash theme={null}
    open Binaries/Dolphin.app
    ```

    Or for universal builds:

    ```bash theme={null}
    open universal/Dolphin.app
    ```
  </Tab>

  <Tab title="Command Line">
    Run the binary directly:

    ```bash theme={null}
    ./Binaries/Dolphin.app/Contents/MacOS/Dolphin
    ```
  </Tab>
</Tabs>

## Command Line Usage

Dolphin supports various command-line options:

<CodeGroup>
  ```bash Basic Usage theme={null}
  # Launch a game directly
  ./Dolphin.app/Contents/MacOS/Dolphin -e "path/to/game.iso"

  # Run in batch mode (no UI)
  ./Dolphin.app/Contents/MacOS/Dolphin -b -e "game.iso"
  ```

  ```bash Advanced Options theme={null}
  # Set configuration option
  ./Dolphin.app/Contents/MacOS/Dolphin -C System.Section.Key=Value

  # Specify video backend
  ./Dolphin.app/Contents/MacOS/Dolphin -v Vulkan -e "game.iso"

  # Enable Metal backend (macOS)
  ./Dolphin.app/Contents/MacOS/Dolphin -v Metal -e "game.iso"
  ```

  ```bash Debugging theme={null}
  # Enable debugger and logger
  ./Dolphin.app/Contents/MacOS/Dolphin -d -l -e "game.iso"
  ```
</CodeGroup>

### Available Video Backends

* **OGL** - OpenGL
* **Vulkan** - Vulkan API (requires MoltenVK)
* **Metal** - Apple Metal (native macOS graphics API)
* **Null** - No rendering
* **Software Renderer** - CPU rendering (debugging only)

## Uninstalling

To uninstall Dolphin:

```bash theme={null}
# Remove application bundle
rm -rf Binaries/Dolphin.app

# Or for universal builds
rm -rf universal/Dolphin.app
```

<Note>
  To completely remove Dolphin, also delete the global user directory if you don't plan on reinstalling:

  ```bash theme={null}
  rm -rf ~/Library/Application\ Support/Dolphin
  ```
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CMake not found">
    Install CMake via Homebrew:

    ```bash theme={null}
    brew install cmake
    ```
  </Accordion>

  <Accordion title="Xcode Command Line Tools not installed">
    Install the tools:

    ```bash theme={null}
    xcode-select --install
    ```

    If already installed, ensure they're up to date:

    ```bash theme={null}
    softwareupdate --install -a
    ```
  </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="Universal binary build fails">
    Universal binary builds are more complex and may require:

    1. Both x64 and ARM versions of dependencies
    2. Universal (fat) libraries for dependencies
    3. Additional CMake arguments to locate libraries

    Run with `--help` to see available options:

    ```bash theme={null}
    python ../BuildMacOSUniversalBinary.py --help
    ```

    Consider building for your current architecture only if you don't need universal binary support.
  </Accordion>

  <Accordion title="Compiler too old">
    CMake will inform you if your compiler is too old. Update Xcode Command Line Tools:

    ```bash theme={null}
    softwareupdate --install -a
    xcode-select --install
    ```
  </Accordion>

  <Accordion title="Missing dependencies">
    Many libraries are bundled with Dolphin. If CMake reports missing dependencies, install them via Homebrew:

    ```bash theme={null}
    brew install <package-name>
    ```
  </Accordion>
</AccordionGroup>

## Performance Tips

<CardGroup cols={2}>
  <Card title="Use Metal Backend" icon="apple">
    On macOS, the Metal backend often provides better performance than OpenGL on Apple Silicon.
  </Card>

  <Card title="Enable Optimization" icon="gauge-high">
    Ensure you're building in Release mode (default) rather than Debug for best performance.
  </Card>
</CardGroup>

## DolphinTool Usage

Dolphin includes a command-line tool for disc image operations:

```bash theme={null}
./Binaries/Dolphin.app/Contents/MacOS/dolphin-tool COMMAND -h
```

### Common Operations

<Tabs>
  <Tab title="Convert">
    ```bash theme={null}
    ./dolphin-tool convert -i input.iso -o output.rvz \
      -f rvz -c zstd -l 5 -b 131072
    ```
  </Tab>

  <Tab title="Verify">
    ```bash theme={null}
    ./dolphin-tool verify -i game.iso -a md5
    ```
  </Tab>

  <Tab title="Extract">
    ```bash theme={null}
    ./dolphin-tool extract -i game.iso -o output_folder
    ```
  </Tab>
</Tabs>