This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Building Citron on Linux
This guide is for developers who wish to build Citron from source on Linux systems. If you're a user looking to simply run Citron, consider downloading the prebuilt binaries from the Citron website.
Table of Contents
Dependencies
You'll need to install the following software to build Citron:
General Tools
- GCC v11+ (for C++20 support)
- Clang v14+ (if GCC 12 or later is used)
- CMake 3.15+
Libraries (handled by Citron's externals or your system package manager)
- FFmpeg
- SDL2 2.0.18+
- Opus
- Qt 5.15+
- Boost 1.79.0+
- Catch2 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, set:
export VCPKG_FORCE_SYSTEM_BINARIES=1
Installing Dependencies by Distribution
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
Ubuntu / 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
- Ensure you're on Ubuntu 22.04+, Debian Bullseye, or later.
- To enable Qt Web Engine, add
-DCITRON_USE_QT_WEB_ENGINE=ONwhen configuring with CMake.
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 36+ requires Clang for compatibility with GCC 12.
Gentoo:
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
Cloning Citron with Git
Clone the Citron repository, including its submodules:
git clone --recursive https://git.citron-emu.org/Citron/Citron.git
cd Citron
Building Citron
Building in Release Mode
Release mode is optimized for performance.
mkdir build && cd build
cmake .. -GNinja -DCITRON_USE_BUNDLED_VCPKG=ON -DCITRON_TESTS=OFF -DCITRON_USE_LLVM_DEMANGLE=OFF -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_CXX_FLAGS="-march=native -mtune=native" -DCMAKE_C_FLAGS="-march=native -mtune=native" -DUSE_DISCORD_PRESENCE=ON -DBUNDLE_SPEEX=ON
ninja
sudo ninja install
Building in Debug Mode
Debug mode includes extra information for debugging but runs slower.
mkdir build && cd build
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Debug -DCITRON_USE_BUNDLED_VCPKG=ON -DCITRON_TESTS=OFF -DCITRON_USE_LLVM_DEMANGLE=OFF -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_CXX_FLAGS="-march=native -mtune=native" -DCMAKE_C_FLAGS="-march=native -mtune=native" -DUSE_DISCORD_PRESENCE=ON -DBUNDLE_SPEEX=ON
ninja
Running Without Installing
After building, binaries such as citron and citron-cmd will be located in the build/bin/ directory.
Running Citron
cd build/bin/
./citron
Debugging
To debug Citron, use gdb:
cd data
gdb ../build/bin/citron
Once in GDB:
run
<crash>
bt
This will provide a backtrace to identify the code path leading to the crash.
Additional Notes
- Ensure you’re using the correct versions of dependencies.
- Contributions to improve this guide are welcome!