Building on Linux

Complete guide to building Dolphin Emulator on Linux with CMake

Dolphin uses CMake for building on Linux. This guide covers all three build types: global installation, local development, and portable builds.

Prerequisites

Required Software

• CMake: Version 3.20 or later
• Git: For cloning the repository
• GCC: Version 12 or later, OR Clang: Version 15 or later
• Make or Ninja: Build system backend

Compiler Requirements

Dolphin requires a modern compiler with C++23 support:

• GCC 12+: Recommended for most distributions
• Clang 15+: Alternative compiler

CMake will inform you if your compiler is too old.

Dependencies

Dolphin bundles many dependencies in Externals/. CMake will inform you if any additional system packages are needed.

For optimal builds, consider installing system development libraries. Refer to the Dolphin wiki for distribution-specific package lists.

Build Type Overview

Linux supports three distinct build types:

Build Type	Use Case	Root Required	Portable
Global	System-wide installation	Yes (for install)	No
Local	Development and testing	No	No
Portable	Multiple setups, external storage	No	Yes

Global Build (System Installation)

This build type installs Dolphin system-wide, making it available to all users.

Uninstalling Global Builds

To uninstall a global build:

cd build
cat install_manifest.txt | xargs -d '\n' rm

This must be run as root from the original build directory.

Local Build (Development)

Local builds are ideal for development as they don’t require root access and create relocatable binaries.

Running Local Builds

Run Dolphin from the build directory:

./Binaries/dolphin-emu

Portable Build

Portable builds can be stored on external storage and used across different Linux systems. They’re also useful for maintaining multiple Dolphin configurations for testing, development, or TAS work.

Using Portable Builds

Portable builds store all user data (saves, configs, etc.) in the Binaries/ directory alongside the executable. You can:

• Copy the entire Binaries/ folder to external storage
• Run on different Linux systems
• Maintain multiple independent Dolphin setups

CMake Build Options

Customize your build with CMake options:

Common Options

Build Type

# Release build (optimized)
cmake .. -DCMAKE_BUILD_TYPE=Release

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

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

Combining Options

Multiple options can be combined:

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DLINUX_LOCAL_DEV=true \
  -DENABLE_LTO=ON \
  -DUSE_SYSTEM_LIBS=AUTO

Using Ninja Instead of Make

Ninja is faster than Make for incremental builds:

# Configure with Ninja
cmake .. -GNinja

# Build with Ninja
ninja

# Use all cores (Ninja does this by default)
ninja -j $(nproc)

Advanced Build Scenarios

Generic Build (No JIT)

For unsupported architectures or when JIT is not desired:

cmake .. -DENABLE_GENERIC=ON

Generic builds are significantly slower as they disable the JIT compiler.

Cross-Compilation

For cross-compiling to different architectures, use CMake toolchain files:

cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain.cmake

Custom Install Prefix

Change the installation directory:

cmake .. -DCMAKE_INSTALL_PREFIX=/opt/dolphin
sudo make install

Troubleshooting

Compiler Too Old

Error: CMake reports compiler version is too old

Solution: Install a newer compiler:

# Ubuntu/Debian - Install GCC 12
sudo apt install gcc-12 g++-12

# Use the newer compiler
cmake .. -DCMAKE_C_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12

Missing Dependencies

Error: CMake reports missing packages

Solution: CMake will inform you which packages are missing. Install them using your distribution’s package manager, or let CMake use bundled versions.

Submodules Not Initialized

Error: Missing files from Externals directory

Solution:

git submodule update --init --recursive

Build Errors After Git Pull

Solution: Clean and rebuild:

cd build
rm -rf *
cmake ..
make -j $(nproc)

Sys Folder Not Found

Error: Dolphin can’t find the Sys folder

Solution:

• Local builds: Ensure the symlink exists: ln -s ../../Data/Sys Binaries/
• Portable builds: Ensure Sys was copied: cp -r ../Data/Sys/ Binaries/

Distribution-Specific Notes

Ubuntu/Debian

# Install build dependencies
sudo apt install cmake git g++ libgl1-mesa-dev libx11-dev \
  libxrandr-dev libudev-dev libevdev-dev libsfml-dev \
  libminiupnpc-dev libmbedtls-dev libcurl4-openssl-dev \
  libhidapi-dev libbluetooth-dev

Fedora

# Install build dependencies
sudo dnf install cmake git gcc-c++ mesa-libGL-devel \
  libX11-devel libXrandr-devel systemd-devel libevdev-devel \
  SFML-devel miniupnpc-devel mbedtls-devel libcurl-devel \
  hidapi-devel bluez-libs-devel

Arch Linux

# Install build dependencies
sudo pacman -S cmake git gcc mesa libx11 libxrandr \
  systemd libevdev sfml miniupnpc mbedtls curl hidapi bluez-libs

These are example package lists. CMake will inform you of any missing dependencies specific to your configuration.

Next Steps

After building:

• Global builds: Run dolphin-emu from anywhere
• Local/Portable builds: Run ./Binaries/dolphin-emu from the build directory
• User data is stored in ~/.local/share/dolphin-emu/ (or Binaries/User/ for portable builds)