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

CMake will inform you if your compiler version is insufficient.

Installing Dependencies

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

# Using Homebrew (optional)
brew install cmake git

Single-Architecture Build

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

Universal Binary Build

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

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

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

Universal Build Script Options

View available options:

python3 ../BuildMacOSUniversalBinary.py --help

Common options:

# 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

Build Type

# 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

Architecture-Specific Builds

Building for Apple Silicon (ARM64)

On an Apple Silicon Mac, CMake defaults to ARM64:

mkdir build
cd build
cmake ..
make -j $(sysctl -n hw.logicalcpu)

Building for Intel (x64)

On an Intel Mac, CMake defaults to x64:

mkdir build
cd build
cmake ..
make -j $(sysctl -n hw.logicalcpu)

Cross-Compilation

To build for a different architecture than your Mac:

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

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

Cross-compilation requires dependencies for the target architecture.

Code Signing

macOS requires code signing, especially on Apple Silicon Macs.

Adhoc Signing (Default)

Dolphin uses adhoc signing by default:

cmake .. -DMACOS_CODE_SIGNING=ON -DMACOS_CODE_SIGNING_IDENTITY="-"

This is sufficient for local development and testing.

Developer ID Signing

For distribution:

cmake .. \
  -DMACOS_CODE_SIGNING=ON \
  -DMACOS_CODE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"

Disabling Code Signing

Disabling code signing will prevent Dolphin from running on Apple Silicon Macs.

cmake .. -DMACOS_CODE_SIGNING=OFF

Advanced Build Scenarios

Bundle Postprocessing

For redistributable builds:

cmake .. -DPOSTPROCESS_BUNDLE=ON

This ensures all dependencies are properly bundled within the app.

Custom Deployment Target

Change the minimum macOS version:

cmake .. -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0

Default is macOS 11.0 (Big Sur).

Link Time Optimization

Enable LTO for better performance:

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.

Minimum requirement: Xcode 14.3 (AppleClang 14.0.3)

Submodules Not Initialized

Error: Missing header files from Externals

Solution:

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:

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:

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:

cmake .. -DUSE_BUNDLED_MOLTENVK=ON

Build Errors After Git Pull

Solution: Clean and rebuild:

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:

cmake .. -DCMAKE_PREFIX_PATH=/opt/homebrew

Running the Built Application

From Build Directory

open ./Binaries/Dolphin.app

From Command Line

./Binaries/Dolphin.app/Contents/MacOS/Dolphin

Installing to Applications

cp -r ./Binaries/Dolphin.app /Applications/

Uninstalling

To uninstall Dolphin:

# 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

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