Development

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, diagrams, screenshots
├── 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 (in Turkish).

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.0); 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.

The repository also contains a .gitlab-ci.yml for the GitLab mirror. It sets up the same stages with two differences: Windows builds go through MinGW cross-compile on a Linux runner (without Vulkan), and the pages job publishes to GitLab Pages.