End of life — September 2026. SolarFlare is no longer maintained and this site is kept for reference only. No further releases, updates, bug fixes, or security patches will be published. Users are encouraged to migrate to Slipstream, the successor project, which remains actively maintained.

SolarFlareDocs
On this page
Developer & APIBuild

Building from Source

Compiling SolarFlare, CMake build flags, developer profiles, and running the GoogleTest suite.

5 min readUpdated August 2026

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.

bash
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/sunshine

Running the Test Suite#

SolarFlare uses GoogleTest (gtest). The test executable test_sunshine is generated in cmake-build-release/tests/:

bash
# 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=1

Toolchain 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.

ComponentMinimumNotes
GCC13+ (14+ recommended)C++23 <format> needs it; CI uses GCC 14
Clang17+Linux and FreeBSD
CMake3.20 (4.0+ for linux_build.sh)Bootstraps 4.3 when distro is old
Ninjaany recentRecommended generator
Node.js + npm20+Web UI build
Doxygen + Graphviz1.10 - 1.12Required when BUILD_DOCS=ON
CUDA12.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.

OptionDefaultPurpose
BUILD_TESTSONBuild test_sunshine and enable CTest
BUILD_DOCSONBuild Doxygen docs (OFF for fast dev)
BUILD_WERROROFFTreat warnings as errors (CI sets ON)
ENABLE_COVERAGEOFFgcov instrumentation for tests
NPM_OFFLINEOFFOffline npm cache (Flatpak builds)
SUNSHINE_ENABLE_TRAYONSystem tray (installer sets OFF)
SUNSHINE_ENABLE_CUDAONNVENC/CUDA paths (installer sets OFF)
SUNSHINE_ENABLE_DRM / VAAPI / VULKAN / WAYLAND / X11 / KWIN / PORTALONCapture and encode backends
SUNSHINE_BUILD_APPIMAGE / FLATPAKOFFAlternate 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.

bash
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 --check

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

FailureLikely causeRecovery
Empty third-party/* at configureSubmodules not initializedgit submodule update --init --recursive
FFmpeg release tag unavailablebuild-deps not at a taggit -C third-party/build-deps fetch --tags
No pinned FFmpeg checksumUnsupported arch/OSBuild on x86_64/aarch64 Linux, Windows, macOS, or FreeBSD amd64
Doxygen target failsMissing doxygen/graphviz-DBUILD_DOCS=OFF for code-only builds
Link OOM under LTOLow RAM with -flto-DSUNSHINE_CACHYOS_NATIVE=OFF or lower -j
ninja: no build.ninjaWrong build dirReuse one -B cmake-build-* path consistently
KMS permission denied after installMissing setcapsudo setcap 'cap_sys_admin,cap_sys_nice+p' on the binary
PreviousMulti-Distro PortingNext Dependencies & Third-Party