Build Guide

SparkEngine Build Guide

Audience: Programmers and contributors

Thread Context: Not applicable — build workflow

Platform/Backend Scope: The only declared release profile is blocked and uncertified stable-v1 on Windows 11 x64/MSVC v143 with D3D11 and Windows NullRHI, plus the required Windows products enumerated in readiness. Windows 10, other toolchains/backends, Linux, and macOS are development or experimental paths outside it.

Documented build paths

SparkEngine requires CMake 3.25+ and a C++23-capable compiler. The in-profile candidate path is Windows 11 x64 with MSVC v143; Windows 10, Linux, and macOS instructions document development builds rather than release support.

Choose the preset for the host platform and use its matching build directory:

# Windows
cmake --preset windows-release
cmake --build --preset windows-release
ctest --test-dir build/windows-release -C Release --output-on-failure --no-tests=error

For a reproducible native configure, keep one CMake executable, generator, and MSVC toolset associated with a build directory. Do not configure the same directory concurrently or switch between the Visual Studio-bundled CMake and a standalone CMake installation in place: compiler-identification and feature metadata are generated state, and an interrupted or competing configure can leave that state incomplete. After changing any of those inputs, start from a new directory or explicitly refresh the preset directory:

cmake --fresh --preset windows-release

The Windows preset selects Visual Studio 17 2022, x64, and v143; it does not pin the patch version of CMake, MSVC, or the Windows SDK. Record those exact versions separately for release certification.

# Linux
cmake --preset linux-gcc-release
cmake --build --preset linux-gcc-release
ctest --test-dir build/linux-gcc-release --output-on-failure --no-tests=error

# macOS
cmake --preset macos-release
cmake --build --preset macos-release
ctest --test-dir build/macos-release --output-on-failure --no-tests=error

Read before building

• Getting Started — prerequisites and the normal build sequence.
• System Requirements — build requirements, development paths, and the narrow release boundary.
• Build System and CMake Modules — presets, options, and CMake architecture.
• Cross-Compilation and Wine Testing — Windows-target builds from Linux.
• CI Reproducible Builds — commands matching continuous integration.
• Troubleshooting — common configure, build, runtime, and graphics failures.

The authoritative preset definitions are in CMakePresets.json.

Source & Freshness

This guide summarizes the canonical presets on Working; CMakePresets.json and the linked platform pages are authoritative for exact options.