> ## 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 with CMake, including universal binaries

Dolphin uses CMake for building on macOS. This guide covers both single-architecture and universal binary builds.

## Prerequisites

### Required Software

* **macOS**: 11.0 Big Sur or later
* **Xcode**: 14.3 or later
* **CMake**: Version 3.20 or later
* **Git**: For cloning the repository

### Compiler Requirements

Dolphin requires AppleClang with C++23 support:

* **AppleClang**: Version 14.0.3 or later (included in Xcode 14.3+)

<Note>
  CMake will inform you if your compiler version is insufficient.
</Note>

### Installing Dependencies

While many dependencies are bundled, some system libraries may improve build times:

```bash theme={null}
# Using Homebrew (optional)
brew install cmake git
```

## Single-Architecture Build

Building for a single architecture (either x64 or ARM64) is the simplest approach.

<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>
    Failing to initialize submodules will cause build errors.
  </Warning>

  ### Create Build Directory

  ```bash theme={null}
  mkdir build
  cd build
  ```

  ### Configure with CMake

  ```bash theme={null}
  cmake ..
  ```

  CMake will automatically detect your Mac's architecture (Apple Silicon or Intel).

  ### Build

  ```bash theme={null}
  make -j $(sysctl -n hw.logicalcpu)
  ```

  This uses all available CPU cores for parallel compilation.

  ### Locate the Application Bundle

  After a successful build, the application bundle is created in:

  ```
  ./Binaries/Dolphin.app
  ```
</Steps>

## Universal Binary Build

Universal binaries support both x64 (Intel) and ARM64 (Apple Silicon) in a single application bundle.

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

  ### Create Build Directory

  ```bash theme={null}
  mkdir build
  cd build
  ```

  ### Run the Universal Build Script

  ```bash theme={null}
  python3 ../BuildMacOSUniversalBinary.py
  ```

  The script will:

  1. Create separate build directories for x64 and ARM64
  2. Build both architectures
  3. Combine them into a universal binary

  ### Locate Universal Binaries

  Universal binaries are created in:

  ```
  ./universal/
  ```
</Steps>

### Universal Build Requirements

Building universal binaries is more complex because it requires:

* Library dependencies for **both** x64 and ARM64 architectures
* OR universal library equivalents that support both architectures
* Additional configuration for library locations

<Note>
  If you have architecture-specific libraries installed, you may need to specify their locations using additional arguments.
</Note>

### Universal Build Script Options

View available options:

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

Common options:

```bash theme={null}
# Specify library paths for different architectures
python3 ../BuildMacOSUniversalBinary.py \
  --arm64-lib-path /opt/homebrew/lib \
  --x64-lib-path /usr/local/lib
```

## CMake Build Options

Customize your macOS build with these options:

### Common Options

<CodeGroup>
  ```bash Build Type theme={null}
  # Release build (optimized, default)
  cmake .. -DCMAKE_BUILD_TYPE=Release

  # Debug build (with debug symbols)
  cmake .. -DCMAKE_BUILD_TYPE=Debug

  # Release with debug info
  cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
  ```

  ```bash Library Management theme={null}
  # Use system libraries where available (default)
  cmake .. -DUSE_SYSTEM_LIBS=AUTO

  # Don't prioritize system library paths
  cmake .. -DMACOS_USE_DEFAULT_SEARCH_PATH=ON
  ```

  ```bash Code Signing theme={null}
  # Enable code signing (default, required for ARM)
  cmake .. -DMACOS_CODE_SIGNING=ON

  # Specify signing identity
  cmake .. -DMACOS_CODE_SIGNING_IDENTITY="Developer ID Application: Your Name"

  # Adhoc signing (default, "-")
  cmake .. -DMACOS_CODE_SIGNING_IDENTITY="-"
  ```

  ```bash Bundle Processing theme={null}
  # Postprocess bundle for redistributability
  cmake .. -DPOSTPROCESS_BUNDLE=ON
  ```

  ```bash MoltenVK theme={null}
  # Use bundled MoltenVK with Dolphin patches (default)
  cmake .. -DUSE_BUNDLED_MOLTENVK=ON

  # Use system MoltenVK
  cmake .. -DUSE_BUNDLED_MOLTENVK=OFF
  ```
</CodeGroup>

## Architecture-Specific Builds

### Building for Apple Silicon (ARM64)

On an Apple Silicon Mac, CMake defaults to ARM64:

```bash theme={null}
mkdir build
cd build
cmake ..
make -j $(sysctl -n hw.logicalcpu)
```

### Building for Intel (x64)

On an Intel Mac, CMake defaults to x64:

```bash theme={null}
mkdir build
cd build
cmake ..
make -j $(sysctl -n hw.logicalcpu)
```

### Cross-Compilation

To build for a different architecture than your Mac:

```bash theme={null}
# On Apple Silicon, build for Intel
cmake .. -DCMAKE_OSX_ARCHITECTURES=x86_64

# On Intel, build for Apple Silicon
cmake .. -DCMAKE_OSX_ARCHITECTURES=arm64
```

<Warning>
  Cross-compilation requires dependencies for the target architecture.
</Warning>

## Code Signing

macOS requires code signing, especially on Apple Silicon Macs.

### Adhoc Signing (Default)

Dolphin uses adhoc signing by default:

```bash theme={null}
cmake .. -DMACOS_CODE_SIGNING=ON -DMACOS_CODE_SIGNING_IDENTITY="-"
```

This is sufficient for local development and testing.

### Developer ID Signing

For distribution:

```bash theme={null}
cmake .. \
  -DMACOS_CODE_SIGNING=ON \
  -DMACOS_CODE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
```

### Disabling Code Signing

<Warning>
  Disabling code signing will prevent Dolphin from running on Apple Silicon Macs.
</Warning>

```bash theme={null}
cmake .. -DMACOS_CODE_SIGNING=OFF
```

## Advanced Build Scenarios

### Bundle Postprocessing

For redistributable builds:

```bash theme={null}
cmake .. -DPOSTPROCESS_BUNDLE=ON
```

This ensures all dependencies are properly bundled within the app.

### Custom Deployment Target

Change the minimum macOS version:

```bash theme={null}
cmake .. -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0
```

Default is macOS 11.0 (Big Sur).

### Link Time Optimization

Enable LTO for better performance:

```bash theme={null}
cmake .. -DENABLE_LTO=ON
```

## Troubleshooting

### Xcode Version Too Old

**Error**: CMake reports AppleClang version is too old

**Solution**: Update Xcode through the Mac App Store or download from [Apple Developer](https://developer.apple.com/download/).

Minimum requirement: Xcode 14.3 (AppleClang 14.0.3)

### Submodules Not Initialized

**Error**: Missing header files from Externals

**Solution**:

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

### Code Signing Errors on Apple Silicon

**Error**: Binary won't run on Apple Silicon

**Solution**: Ensure code signing is enabled:

```bash theme={null}
cmake .. -DMACOS_CODE_SIGNING=ON
make -j $(sysctl -n hw.logicalcpu)
```

### Universal Binary Build Fails

**Error**: Missing libraries for one architecture

**Solution**: Universal builds require dependencies for both architectures. Either:

1. Install universal versions of dependencies
2. Install separate versions for each architecture and specify paths:

```bash theme={null}
python3 ../BuildMacOSUniversalBinary.py \
  --arm64-lib-path /opt/homebrew/lib \
  --x64-lib-path /usr/local/lib
```

### MoltenVK Issues

**Error**: Vulkan backend not working

**Solution**: Ensure bundled MoltenVK is enabled:

```bash theme={null}
cmake .. -DUSE_BUNDLED_MOLTENVK=ON
```

### Build Errors After Git Pull

**Solution**: Clean and rebuild:

```bash theme={null}
cd build
rm -rf *
git submodule update --init --recursive
cmake ..
make -j $(sysctl -n hw.logicalcpu)
```

### Library Path Issues

**Error**: CMake can't find certain libraries

**Solution**: If using Homebrew, library paths differ by architecture:

* **Apple Silicon**: `/opt/homebrew/`
* **Intel**: `/usr/local/`

Specify the correct path:

```bash theme={null}
cmake .. -DCMAKE_PREFIX_PATH=/opt/homebrew
```

## Running the Built Application

### From Build Directory

```bash theme={null}
open ./Binaries/Dolphin.app
```

### From Command Line

```bash theme={null}
./Binaries/Dolphin.app/Contents/MacOS/Dolphin
```

### Installing to Applications

```bash theme={null}
cp -r ./Binaries/Dolphin.app /Applications/
```

## Uninstalling

To uninstall Dolphin:

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

# Remove user data (optional)
rm -rf ~/Library/Application\ Support/Dolphin
```

## Next Steps

After building:

* The application bundle is ready to use in `Binaries/Dolphin.app`
* User data is stored in `~/Library/Application Support/Dolphin/`
* For distribution, consider bundle postprocessing and proper code signing

<Note>
  For universal binaries intended for distribution, use the universal build script and enable bundle postprocessing.
</Note>