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

<Note>
  CMake will inform you if your compiler is too old.
</Note>

### 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](https://github.com/dolphin-emu/dolphin/wiki/Building-for-Linux) 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.

<Steps>
  ### Clone and Initialize

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

  ### Create Build Directory

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

  ### Configure with CMake

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

  <Note>
    CMake will check for dependencies and inform you of any missing packages or if bundled versions will be used.
  </Note>

  ### Build

  ```bash theme={null}
  make -j $(nproc)
  ```

  The `-j $(nproc)` flag uses all available CPU cores for parallel compilation.

  ### Install

  ```bash theme={null}
  sudo make install
  ```

  This installs Dolphin to the standard system directories (typically `/usr/local/`).
</Steps>

### Uninstalling Global Builds

To uninstall a global build:

```bash theme={null}
cd build
cat install_manifest.txt | xargs -d '\n' rm
```

<Warning>
  This must be run as root from the original build directory.
</Warning>

## Local Build (Development)

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

<Steps>
  ### Clone and Initialize

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

  ### Create Build Directory

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

  ### Configure with Local Dev Option

  ```bash theme={null}
  cmake .. -DLINUX_LOCAL_DEV=true
  ```

  The `LINUX_LOCAL_DEV` option enables relocatable binary creation.

  ### Build

  ```bash theme={null}
  make -j $(nproc)
  ```

  ### Create Sys Symlink

  ```bash theme={null}
  ln -s ../../Data/Sys Binaries/
  ```

  This creates a symbolic link to the Sys folder needed by Dolphin.
</Steps>

### Running Local Builds

Run Dolphin from the build directory:

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

<Steps>
  ### Clone and Initialize

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

  ### Create Build Directory

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

  ### Configure with Local Dev Option

  ```bash theme={null}
  cmake .. -DLINUX_LOCAL_DEV=true
  ```

  ### Build

  ```bash theme={null}
  make -j $(nproc)
  ```

  ### Copy Sys Files

  ```bash theme={null}
  cp -r ../Data/Sys/ Binaries/
  ```

  Unlike local builds, portable builds copy (not symlink) the Sys folder.

  ### Create Portable Flag

  ```bash theme={null}
  touch Binaries/portable.txt
  ```

  The presence of `portable.txt` tells Dolphin to store user data locally.
</Steps>

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

<CodeGroup>
  ```bash Build Type theme={null}
  # 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
  ```

  ```bash System Libraries theme={null}
  # Use system libraries where available
  cmake .. -DUSE_SYSTEM_LIBS=AUTO

  # Force system libraries (fail if unavailable)
  cmake .. -DUSE_SYSTEM_LIBS=ON

  # Always use bundled libraries
  cmake .. -DUSE_SYSTEM_LIBS=OFF
  ```

  ```bash Frontend Options theme={null}
  # Disable Qt GUI
  cmake .. -DENABLE_QT=OFF

  # Disable NoGUI frontend
  cmake .. -DENABLE_NOGUI=OFF

  # Headless build (no GUI, no Discord)
  cmake .. -DENABLE_HEADLESS=ON
  ```

  ```bash Platform Options theme={null}
  # Disable X11 support
  cmake .. -DENABLE_X11=OFF

  # Disable EGL support
  cmake .. -DENABLE_EGL=OFF
  ```

  ```bash Audio Backends theme={null}
  # Disable ALSA
  cmake .. -DENABLE_ALSA=OFF

  # Disable PulseAudio
  cmake .. -DENABLE_PULSEAUDIO=OFF
  ```

  ```bash Features theme={null}
  # Enable Link Time Optimization
  cmake .. -DENABLE_LTO=ON

  # Disable automatic updates
  cmake .. -DENABLE_AUTOUPDATE=OFF

  # Disable Discord Rich Presence
  cmake .. -DUSE_DISCORD_PRESENCE=OFF
  ```
</CodeGroup>

### Combining Options

Multiple options can be combined:

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

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

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

<Warning>
  Generic builds are significantly slower as they disable the JIT compiler.
</Warning>

### Cross-Compilation

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

```bash theme={null}
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain.cmake
```

### Custom Install Prefix

Change the installation directory:

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

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

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

### Build Errors After Git Pull

**Solution**: Clean and rebuild:

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

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

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

```bash theme={null}
# Install build dependencies
sudo pacman -S cmake git gcc mesa libx11 libxrandr \
  systemd libevdev sfml miniupnpc mbedtls curl hidapi bluez-libs
```

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

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