Working on SDLPainter. For building it see Building from source; for the helper scripts see the Script Reference.

Contribution rules (commit format, branch strategy, when an ADR is required) are in CONTRIBUTING.md.

Directory layout

sdl-painter/
├── include/sdl_painter/   # Public headers (including app/)
├── src/                   # Implementation
│   ├── app/               # Application framework (sdl_painter_app)
│   ├── opengl/            # OpenGL backend + GLSL shaders
│   └── vulkan/            # Vulkan backend + SPIR-V shaders
├── tests/                 # GTest unit tests
├── examples/              # Demo applications (see examples/README.md)
├── packaging/consumer/    # External-consumer verification project
├── doc/                   # Design documents (Turkish), diagrams, screenshots
│   └── en/                # English design documents
├── cmake/                 # CMake helper modules
├── scripts/               # Build/test helper scripts (.sh + .ps1)
└── adr/                   # Architecture Decision Records

packaging/consumer/ is a standalone project that links SDLPainter from the outside, in both find_package and add_subdirectory mode. It must stay outside any gitignored directory — CI builds it.

Quality checks

# Format check
./scripts/format-check.sh
 
# Auto-fix formatting
./scripts/format-check.sh --fix
 
# clang-tidy (after building)
find src/ -name '*.cpp' | xargs clang-tidy-18 -p build/linux-debug/

Formatting is mandatory: quality:clang-format fails the pipeline on any violation. clang-tidy runs as a soft fail.

API reference (Doxygen)

Online: on every push to the default branch the docs job publishes to GitHub Pages — https://yazilimperver.github.io/sdl-painter

Locally:

doxygen Doxyfile              # documentation only
./scripts/build.sh --docs     # build + documentation
xdg-open build/docs/index.html

doxygen Doxyfile
.\scripts\Build.ps1 -Docs
Start-Process build\docs\index.html

If Doxygen is not installed: apt install doxygen (Linux) or doxygen.nl (Windows).

Doxygen configuration and comment conventions: Documentation Guide.

CI/CD

The primary pipeline is GitHub Actions (.github/workflows/ci.yml). Linux jobs run in the prebuilt Docker Hub image (yazilimperver/sdl-painter:ci-v1.2); Windows jobs run on a native MSVC runner.

Job	Environment	What it does
build:linux:debug	Linux (container)	Debug, Vulkan on
build:linux:release	Linux (container)	Release, Vulkan on
build:windows:debug	windows-2022, MSVC	Debug, Vulkan on, runs ctest
build:windows:release	windows-2022, MSVC	Release, Vulkan on
test:unit	Linux (container)	GTest — headless (offscreen + lavapipe ICD)
test:unit:asan	Linux (container)	ASan + UBSan, built without Vulkan
build:standalone-cmake	Linux (container)	Configure without presets, install, then build packaging/consumer/
package:conan-create	Linux (container)	conan create + test_package — early warning for the packaging path
quality:shader-freshness	ubuntu-latest	Checks the SPIR-V outputs against the GLSL sources via sources.sha256
quality:clang-format	Linux (container)	Google Style check — hard fail
quality:clang-tidy	Linux (container)	Static analysis — soft fail
docs	ubuntu-latest	Doxygen → GitHub Pages (default branch only)
release:publish	ubuntu-latest	GitHub Release on v..* tags

Notes worth knowing before touching CI:

Renderer smoke tests only really run on Linux. Windows' offscreen video driver cannot load EGL, so the OpenGL/Vulkan smoke tests SKIP there. On Linux, Mesa EGL plus the lavapipe ICD makes them run headless for real.
The lavapipe ICD filename is resolved at runtime (lvp_icd*.json), because it varies by Mesa version. A wrong hardcoded path makes the loader load no driver, and the Vulkan tests then SKIP silently.
SPIR-V is compared through a manifest, not by recompiling. The CI image has no glslc; cmake -P cmake/CheckShaderFreshness.cmake re-hashes the GLSL sources and compares them against src/vulkan/shaders/spirv/sources.sha256.

Test environment variables

GPU, font and validation dependent tests skip quietly when their prerequisite is missing, so a local run on a machine without a GPU still passes. CI sets the variables below to turn those silent skips into failures. Each one is on when set to anything other than empty or 0.

Variable	When set	Set in CI
SDLPAINTER_REQUIRE_FONT	A test that needs a system TTF font fails instead of skipping when none is found or it cannot be loaded	Linux test jobs
SDLPAINTER_REQUIRE_BACKEND	A test that needs a real OpenGL or Vulkan backend fails instead of skipping when the window, renderer or Initialize fails. Backends that are not compiled in are never required	test:unit, test:unit:asan, quality:coverage
SDLPAINTER_REQUIRE_VALIDATION	A test that creates a Vulkan context fails unless the Vulkan validation layer is fully active (Debug build, layer found, debug messenger created); the message names the reason. Only meaningful in Debug builds: in Release the library never enables validation, so every Vulkan test fails	test:unit, quality:coverage (Debug, Vulkan on)

SDLPAINTER_REQUIRE_BACKEND is not set on the Windows job, where the offscreen driver cannot load EGL. To reproduce the Linux CI test job locally, install the validation layer (vulkan-validationlayers on Debian/Ubuntu) and run with all three variables set plus SDL_VIDEODRIVER=offscreen.

The repository also contains a .gitlab-ci.yml for the GitLab mirror. Both pipelines now run the same 15 jobs — including the packaging path (build:standalone-cmake, build:shared, package:conan-create, quality:shader-freshness), which the mirror was missing until 26 August 2026. clang-format is a hard gate on both.

Three differences remain, all deliberate: Windows builds go through MinGW cross-compile on a Linux runner (GitHub uses native MSVC), the Windows test job is commented out (it needs a GitLab SaaS Windows runner), and the pages job publishes to GitLab Pages instead of GitHub Pages.