Building for Linux - SUYU EMULATOR

Developer Notice

This guide is intended for developers.
If you’re simply looking to run suyu, we recommend downloading the Mainline AppImage.
No installation is needed—just make the file executable and run it.

Development Dependencies

To compile suyu from source, ensure you have the following:

General Tools

GCC 11+ with C++20 support
- (If using GCC 12, you must also install Clang v14+)
CMake version 3.15 or higher

Automatically Managed Dependencies (via `externals`)

FFmpeg
SDL2 (version 2.0.18+)
Opus
Qt 5.15+
- If version 5.15.2 is missing, prebuilt binaries are auto-downloaded by CMake.

Additional Packages via vcpkg (auto-installed if missing)

Boost 1.79+
Catch2 (versions 2.13.7 – 2.13.9)
fmt 8.0.1+
lz4 1.8+
nlohmann_json 3.8+
OpenSSL
Zlib 1.2+
zstd 1.5+

For ARM64 builds:

export VCPKG_FORCE_SYSTEM_BINARIES=1

OS-Specific Dependency Installation

Arch / Manjaro

sudo pacman -Syu --needed base-devel boost catch2 cmake ffmpeg fmt git glslang libzip lz4 mbedtls ninja nlohmann-json openssl opus qt5 sdl2 zlib zstd zip unzip

For Qt WebEngine, pass the following to CMake:

-DCMAKE_CXX_FLAGS="-I/usr/include/qt/QtWebEngineWidgets"

Note: GCC 11 or newer is required.

Ubuntu / Linux Mint / Debian

sudo apt-get install autoconf cmake g++-11 gcc-11 git glslang-tools libasound2 libboost-context-dev libglu1-mesa-dev libhidapi-dev libpulse-dev libtool libudev-dev libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-xinerama0 libxcb-xkb1 libxext-dev libxkbcommon-x11-0 mesa-common-dev nasm ninja-build qtbase5-dev qtbase5-private-dev qtwebengine5-dev qtmultimedia5-dev libmbedtls-dev catch2 libfmt-dev liblz4-dev nlohmann-json3-dev libzstd-dev libssl-dev libavfilter-dev libavcodec-dev libswscale-dev

OS Requirement: Ubuntu 22.04+, Linux Mint 20+, or Debian Bullseye+
CMake must include:

-DSUYU_USE_QT_WEB_ENGINE=ON
-DCMAKE_C_COMPILER=gcc-11 -DCMAKE_CXX_COMPILER=g++-11

If you prefer to skip building SDL2 from source:

-DSUYU_USE_EXTERNAL_SDL2=OFF

Fedora

sudo dnf install autoconf ccache cmake fmt-devel gcc{,-c++} glslang hidapi-devel json-devel libtool libusb1-devel libzstd-devel lz4-devel nasm ninja-build openssl-devel pulseaudio-libs-devel qt5-linguist qt5-qtbase{-private,}-devel qt5-qtwebengine-devel qt5-qtmultimedia-devel speexdsp-devel wayland-devel zlib-devel ffmpeg-devel libXext-devel

Fedora 32+ is required.
Fedora 36+ (using GCC 12) must also install clang and pass to CMake:

-DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang

Optional CMake flags:

SDL2:     -DSUYU_USE_BUNDLED_SDL2=OFF -DSUYU_USE_EXTERNAL_SDL2=OFF  
FFmpeg:   -DSUYU_USE_EXTERNAL_FFMPEG=OFF

Note: To install ffmpeg-devel, RPM Fusion (free) must be enabled.

Gentoo (Community-Maintained)

emerge --ask app-arch/lz4 dev-libs/boost dev-libs/hidapi dev-libs/libzip dev-libs/openssl dev-qt/linguist dev-qt/qtconcurrent dev-qt/qtcore dev-util/cmake dev-util/glslang dev-vcs/git media-libs/alsa-lib media-libs/opus media-sound/pulseaudio media-video/ffmpeg net-libs/mbedtls sys-libs/zlib x11-libs/libXext

GCC 11+ is mandatory
You might need USE flags: pulseaudio, bindist, context

Cloning suyu from Git

Clone with all submodules:

git clone --recursive https://git.suyu.dev/suyu/suyu
cd suyu

Building suyu

Release Mode (Optimized Build)

mkdir build && cd build
cmake .. -GNinja -DSUYU_USE_BUNDLED_VCPKG=ON -DSUYU_TESTS=OFF
ninja
sudo ninja install

For Discord Rich Presence support:

-DUSE_DISCORD_PRESENCE=ON

To fix errors with spvOptimizerOptionsCreate, try:

-DSUYU_USE_EXTERNAL_VULKAN_SPIRV_TOOLS=OFF

You may use cmake-gui .. to toggle options like disabling the Qt GUI.

Debug Mode (Slow)

mkdir build && cd build
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Debug -DSUYU_USE_BUNDLED_VCPKG=ON -DSUYU_TESTS=OFF
ninja

Build with Debug Symbols

mkdir build && cd build
cmake .. -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DSUYU_USE_BUNDLED_VCPKG=ON -DSUYU_TESTS=OFF
ninja

Running Without Installation

After compiling, you’ll find executables in build/bin/.

CLI Mode (SDL):

cd build/bin/
./suyu-cmd

Qt GUI Mode:

cd build/bin/
./suyu

Debugging with GDB

Go to data/ directory:

cd data

Launch GDB:

gdb ../build/bin/suyu

Run and debug:

(gdb) run
# after crash
(gdb) bt   # to view the full backtrace

Pro Tip: Disable Host MMU options and enable CPU debugging for deeper insights.