Building from Source
Compiling SolarFlare, CMake build flags, developer profiles, and running the GoogleTest suite.
Build Prerequisites#
SolarFlare requires a C++20 compliant compiler (GCC 13+ or Clang 17+), CMake 3.25+, Ninja, NodeJS 20+, and development headers for PipeWire, Opus, DRM, VA-API, and OpenSSL.
Standard Build Commands#
Keep build directories under cmake-build-. Switch tabs for host OS prefixes.
cmake -S . -B cmake-build-release -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_TESTS=OFF \
-DBUILD_DOCS=OFF
cmake --build cmake-build-release --target sunshine web-ui -j2
sudo setcap 'cap_sys_admin,cap_sys_nice+p' cmake-build-release/sunshineRunning the Test Suite#
SolarFlare uses GoogleTest (gtest). The test executable test_sunshine is generated in cmake-build-release/tests/:
# Build test target
cmake --build cmake-build-release --target test_sunshine -j$(nproc)
# Run full test suite
./cmake-build-release/tests/test_sunshine --gtest_brief=1Toolchain requirements#
C++23 with GCC 13+ (14+ recommended; Fedora 45 uses GCC 15) or Clang 17+, CMake 3.20 minimum (the linux_build.sh Docker/CI builder enforces CMake 4.0+ and bootstraps 4.3 when needed), Ninja, Node.js 20+ with npm, Python 3.14+ with uv for Flatpak generators, and Doxygen 1.10–1.12 plus Graphviz for docs builds. Optional accelerators: ccache and mold/lld linkers (auto-preferred), CUDA 12+ for NVENC paths. Ubuntu 22.04 needs the gcc-13 toolchain PPA.
| Component | Minimum | Notes |
|---|---|---|
| GCC | 13+ (14+ recommended) | C++23 <format> needs it; CI uses GCC 14 |
| Clang | 17+ | Linux and FreeBSD |
| CMake | 3.20 (4.0+ for linux_build.sh) | Bootstraps 4.3 when distro is old |
| Ninja | any recent | Recommended generator |
| Node.js + npm | 20+ | Web UI build |
| Doxygen + Graphviz | 1.10 - 1.12 | Required when BUILD_DOCS=ON |
| CUDA | 12.0+ | NVENC / NvFBC paths only |
CMake options reference#
All options live in cmake/prep/options.cmake. The maintained installer path already picks sane Release defaults; override individual flags for manual or packaging builds.
| Option | Default | Purpose |
|---|---|---|
| BUILD_TESTS | ON | Build test_sunshine and enable CTest |
| BUILD_DOCS | ON | Build Doxygen docs (OFF for fast dev) |
| BUILD_WERROR | OFF | Treat warnings as errors (CI sets ON) |
| ENABLE_COVERAGE | OFF | gcov instrumentation for tests |
| NPM_OFFLINE | OFF | Offline npm cache (Flatpak builds) |
| SUNSHINE_ENABLE_TRAY | ON | System tray (installer sets OFF) |
| SUNSHINE_ENABLE_CUDA | ON | NVENC/CUDA paths (installer sets OFF) |
| SUNSHINE_ENABLE_DRM / VAAPI / VULKAN / WAYLAND / X11 / KWIN / PORTAL | ON | Capture and encode backends |
| SUNSHINE_BUILD_APPIMAGE / FLATPAK | OFF | Alternate packaging layouts |
| FFMPEG_PREPARED_BINARIES | (auto) | Override path to extracted FFmpeg static libs |
Build profiles & test commands#
Keep every local tree under the cmake-build- prefix. Bare build/ is reserved for the linux_build.sh Docker/CI builder. The test binary is always <build-dir>/tests/test_sunshine. Iterate with --gtest_filter, then run the full suite before review; hardware-dependent tests skip without devices, failures must be explained.
cmake -S . -B cmake-build-dev -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON -DBUILD_DOCS=OFF
cmake -S . -B cmake-build-tests -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON -DBUILD_DOCS=OFF
cmake -S . -B cmake-build-release -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF -DBUILD_DOCS=OFF
cmake -S . -B cmake-build-docs -G Ninja -DBUILD_DOCS=ON -DBUILD_TESTS=OFF
cmake --build cmake-build-tests --target test_sunshine -j2
./cmake-build-tests/tests/test_sunshine --gtest_brief=1
./cmake-build-tests/tests/test_sunshine --gtest_filter='ConfigTest.*' --gtest_brief=1
cmake --build cmake-build-release --target sunshine web-ui -j2
clang-format --dry-run --Werror src/path/to/changed.cpp
git diff --checkCUDA / NVENC builds#
Default installer builds disable CUDA (VA-API/Vulkan cover most Linux users). For NVENC: install a driver plus a CUDA toolkit matching your GCC, then configure with SUNSHINE_ENABLE_CUDA=ON and point CMAKE_CUDA_COMPILER at nvcc. Known-good reference is CUDA 13.1.1 with driver build 590.48.01; Flatpak pins 13.2.0; release notes record CUDA 13.4 builds. Architecture coverage follows the toolkit version (older toolkits cover sm_50–sm_90, newer ones add sm_100+ families). glibc mismatches against NVCC math headers are fixed by the patches under packaging/linux/patches/.
Failed build recovery#
| Failure | Likely cause | Recovery |
|---|---|---|
| Empty third-party/* at configure | Submodules not initialized | git submodule update --init --recursive |
| FFmpeg release tag unavailable | build-deps not at a tag | git -C third-party/build-deps fetch --tags |
| No pinned FFmpeg checksum | Unsupported arch/OS | Build on x86_64/aarch64 Linux, Windows, macOS, or FreeBSD amd64 |
| Doxygen target fails | Missing doxygen/graphviz | -DBUILD_DOCS=OFF for code-only builds |
| Link OOM under LTO | Low RAM with -flto | -DSUNSHINE_CACHYOS_NATIVE=OFF or lower -j |
| ninja: no build.ninja | Wrong build dir | Reuse one -B cmake-build-* path consistently |
| KMS permission denied after install | Missing setcap | sudo setcap 'cap_sys_admin,cap_sys_nice+p' on the binary |