ercmine · ercmine · Apr 6, 2026 · Apr 6, 2026
diff --git a/.github/workflows/main-validation.yml b/.github/workflows/main-validation.yml
@@ -0,0 +1,79 @@
+name: Main Validation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  full-validation:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-full-release
+            os: ubuntu-latest
+            configure_preset: linux-ci
+            build_preset: linux-ci
+            build_config_flag: ""
+            run_full: true
+          - name: macos-build-test
+            os: macos-latest
+            configure_preset: macos-release
+            build_preset: macos-release
+            build_config_flag: ""
+            run_full: false
+          - name: windows-build-test
+            os: windows-latest
+            configure_preset: windows-release
+            build_preset: windows-release
+            build_config_flag: --config Release
+            run_full: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Ninja
+        uses: seanmiddleditch/gha-setup-ninja@v5
+
+      - name: Cache FetchContent dependencies
+        uses: actions/cache@v4
+        with:
+          path: .fc
+          key: ${{ runner.os }}-fc-${{ hashFiles('CMakeLists.txt', 'cmake/**/*.cmake', 'CMakePresets.json') }}
+
+      - name: Configure
+        run: >-
+          cmake --preset ${{ matrix.configure_preset }}
+          -DRENDER_ALLOW_FETCHCONTENT=ON
+          -DFETCHCONTENT_BASE_DIR=${{ github.workspace }}/.fc
+
+      - name: Build
+        run: >-
+          cmake --build --preset ${{ matrix.build_preset }}
+          ${{ matrix.build_config_flag }}
+
+      - name: Run unit + headless checks
+        run: >-
+          ctest --test-dir out/build/${{ matrix.configure_preset }}
+          ${{ matrix.os == 'windows-latest' && '-C Release' || '' }}
+          --output-on-failure -L "unit|headless"
+
+      - name: Run Linux full validation
+        if: matrix.run_full
+        run: |
+          cmake --build --preset ${{ matrix.build_preset }} --target render_shader_check
+          cmake --build --preset ${{ matrix.build_preset }} --target render_package_validate
+
+      - name: Upload Linux artifacts
+        if: matrix.run_full
+        uses: actions/upload-artifact@v4
+        with:
+          name: main-validation-${{ matrix.name }}
+          path: |
+            out/build/${{ matrix.configure_preset }}/logs
+            out/build/${{ matrix.configure_preset }}/Testing/Temporary
+            out/build/${{ matrix.configure_preset }}/package
+          if-no-files-found: warn
diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml
@@ -0,0 +1,83 @@
+name: PR Validation
+
+on:
+  pull_request:
+
+jobs:
+  build-and-test:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-full
+            os: ubuntu-latest
+            configure_preset: linux-ci
+            build_preset: linux-ci
+            build_config_flag: ""
+            full_validation: true
+          - name: macos-build-test
+            os: macos-latest
+            configure_preset: macos-debug
+            build_preset: macos-debug
+            build_config_flag: ""
+            full_validation: false
+          - name: windows-build-test
+            os: windows-latest
+            configure_preset: windows-debug
+            build_preset: windows-debug
+            build_config_flag: --config Debug
+            full_validation: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Ninja
+        uses: seanmiddleditch/gha-setup-ninja@v5
+
+      - name: Cache FetchContent dependencies
+        uses: actions/cache@v4
+        with:
+          path: .fc
+          key: ${{ runner.os }}-fc-${{ hashFiles('CMakeLists.txt', 'cmake/**/*.cmake', 'CMakePresets.json') }}
+
+      - name: Configure
+        run: >-
+          cmake --preset ${{ matrix.configure_preset }}
+          -DRENDER_ALLOW_FETCHCONTENT=ON
+          -DFETCHCONTENT_BASE_DIR=${{ github.workspace }}/.fc
+
+      - name: Build
+        run: >-
+          cmake --build --preset ${{ matrix.build_preset }}
+          ${{ matrix.build_config_flag }}
+
+      - name: Run unit tests
+        run: >-
+          ctest --test-dir out/build/${{ matrix.configure_preset }}
+          ${{ matrix.os == 'windows-latest' && '-C Debug' || '' }}
+          --output-on-failure -L unit
+
+      - name: Run headless smoke validation
+        run: >-
+          ctest --test-dir out/build/${{ matrix.configure_preset }}
+          ${{ matrix.os == 'windows-latest' && '-C Debug' || '' }}
+          --output-on-failure -L headless
+
+      - name: Run shader and packaging checks (Linux full lane)
+        if: matrix.full_validation
+        run: |
+          cmake --build --preset ${{ matrix.build_preset }} --target render_shader_check
+          cmake --build --preset ${{ matrix.build_preset }} --target render_package_validate
+
+      - name: Upload Linux validation artifacts
+        if: matrix.full_validation
+        uses: actions/upload-artifact@v4
+        with:
+          name: validation-${{ matrix.name }}
+          path: |
+            out/build/${{ matrix.configure_preset }}/logs
+            out/build/${{ matrix.configure_preset }}/Testing/Temporary
+            out/build/${{ matrix.configure_preset }}/package
+          if-no-files-found: warn
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -17,6 +17,7 @@ include(Dependencies)
 include(Versioning)
 include(Utils)
 include(ShaderCompilation)
+include(GNUInstallDirs)
 
 render_prevent_in_source_builds()
 render_apply_standard_settings()
@@ -26,6 +27,10 @@ render_setup_dependencies()
 render_setup_versioning()
 render_setup_shader_compilation()
 
+if(RENDER_BUILD_TESTS)
+  include(CTest)
+endif()
+
 add_library(render_core STATIC
   engine/core/types.hpp
   engine/core/math.hpp
@@ -149,8 +154,6 @@ if(RENDER_BUILD_TOOLS)
 endif()
 
 if(RENDER_BUILD_TESTS)
-  include(CTest)
-
   add_executable(render_platform_types_tests tests/platform/platform_types_tests.cpp)
   target_link_libraries(render_platform_types_tests PRIVATE render::engine)
   render_apply_project_options(render_platform_types_tests)
@@ -173,10 +176,78 @@ if(RENDER_BUILD_TESTS)
   render_apply_project_options(render_filesystem_tests)
   render_apply_warnings(render_filesystem_tests)
 
-  add_test(NAME render_platform_types_tests COMMAND render_platform_types_tests)
-  add_test(NAME render_core_runtime_tests COMMAND render_core_runtime_tests)
-  add_test(NAME render_serialization_tests COMMAND render_serialization_tests)
-  add_test(NAME render_filesystem_tests COMMAND render_filesystem_tests)
+  add_executable(render_headless_validation tests/headless/headless_validation.cpp)
+  target_link_libraries(render_headless_validation PRIVATE render::filesystem render::serialization)
+  render_apply_project_options(render_headless_validation)
+  render_apply_warnings(render_headless_validation)
+
+  add_test(NAME unit.platform.types COMMAND render_platform_types_tests)
+  set_tests_properties(unit.platform.types PROPERTIES LABELS "unit;platform")
+  add_test(NAME unit.core.runtime COMMAND render_core_runtime_tests)
+  set_tests_properties(unit.core.runtime PROPERTIES LABELS "unit;core")
+  add_test(NAME unit.serialization.roundtrip COMMAND render_serialization_tests)
+  set_tests_properties(unit.serialization.roundtrip PROPERTIES LABELS "unit;serialization")
+  add_test(NAME unit.filesystem.service COMMAND render_filesystem_tests)
+  set_tests_properties(unit.filesystem.service PROPERTIES LABELS "unit;filesystem")
+  add_test(NAME headless.smoke.startup COMMAND render_headless_validation)
+  set_tests_properties(headless.smoke.startup PROPERTIES LABELS "headless;smoke")
+
+  add_custom_target(render_test_unit
+    COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure --label-regex unit
+    DEPENDS render_platform_types_tests render_core_runtime_tests render_serialization_tests render_filesystem_tests
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
+    COMMENT "Running render unit tests"
+  )
+
+  add_custom_target(render_test_headless
+    COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure --label-regex headless
+    DEPENDS render_headless_validation
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
+    COMMENT "Running render headless smoke validation"
+  )
+endif()
+
+set(RENDER_PACKAGE_STAGE_DIR "${CMAKE_BINARY_DIR}/package/stage")
+set(RENDER_PACKAGE_BIN_SUBDIR "${CMAKE_INSTALL_BINDIR}")
+set(RENDER_PACKAGE_SHADER_RELATIVE_DIR "shaders/bin")
+
+install(TARGETS render_shell RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}")
+install(DIRECTORY "${CMAKE_BINARY_DIR}/bin/shaders/bin/" DESTINATION "shaders/bin" OPTIONAL)
+
+add_custom_target(render_package_stage
+  COMMAND ${CMAKE_COMMAND} -E rm -rf "${RENDER_PACKAGE_STAGE_DIR}"
+  DEPENDS render_shell render_shader_check
+  COMMENT "Staging render package layout"
+)
+if(CMAKE_CONFIGURATION_TYPES)
+  add_custom_command(TARGET render_package_stage
+    COMMAND ${CMAKE_COMMAND} --install "${CMAKE_BINARY_DIR}" --prefix "${RENDER_PACKAGE_STAGE_DIR}" --config $<CONFIG>
+  )
+else()
+  add_custom_command(TARGET render_package_stage
+    COMMAND ${CMAKE_COMMAND} --install "${CMAKE_BINARY_DIR}" --prefix "${RENDER_PACKAGE_STAGE_DIR}"
+  )
+endif()
+
+add_custom_target(render_package_validate
+  COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_BINARY_DIR}/logs"
+  COMMAND ${CMAKE_COMMAND}
+    -DRENDER_PACKAGE_STAGE_DIR=${RENDER_PACKAGE_STAGE_DIR}
+    -DRENDER_PACKAGE_BIN_SUBDIR=${RENDER_PACKAGE_BIN_SUBDIR}
+    -DRENDER_PACKAGE_SHADER_RELATIVE_DIR=${RENDER_PACKAGE_SHADER_RELATIVE_DIR}
+    -DRENDER_PACKAGE_LOG_FILE=${CMAKE_BINARY_DIR}/logs/package_validation.log
+    -P "${CMAKE_SOURCE_DIR}/cmake/validate_package_layout.cmake"
+  DEPENDS render_package_stage
+  COMMENT "Validating package stage and archive creation"
+  VERBATIM
+)
+
+add_custom_target(render_validate_all
+  DEPENDS render_shader_check render_package_validate
+  COMMENT "Build/render validation umbrella target"
+)
+if(RENDER_BUILD_TESTS)
+  add_dependencies(render_validate_all render_test_unit render_test_headless)
 endif()
 
 message(STATUS "Configured ${PROJECT_NAME} ${PROJECT_VERSION} for ${CMAKE_SYSTEM_NAME}")

diff --git a/CMakePresets.json b/CMakePresets.json
@@ -76,6 +76,14 @@
         "CMAKE_BUILD_TYPE": "Debug"
       }
     },
+    {
+      "name": "linux-ci",
+      "inherits": ["linux-debug"],
+      "cacheVariables": {
+        "RENDER_BGFX_BUILD_TOOLS": "ON",
+        "RENDER_REQUIRE_SHADER_COMPILATION": "ON"
+      }
+    },
     {
       "name": "linux-release",
       "inherits": ["linux-base"],
@@ -113,6 +121,10 @@
       "name": "linux-debug",
       "configurePreset": "linux-debug"
     },
+    {
+      "name": "linux-ci",
+      "configurePreset": "linux-ci"
+    },
     {
       "name": "linux-release",
       "configurePreset": "linux-release"
@@ -133,6 +145,40 @@
       "output": {
         "outputOnFailure": true
       }
+    },
+    {
+      "name": "linux-unit",
+      "configurePreset": "linux-debug",
+      "output": {
+        "outputOnFailure": true
+      },
+      "execution": {
+        "stopOnFailure": true
+      },
+      "filter": {
+        "label": {
+          "include": [
+            "unit"
+          ]
+        }
+      }
+    },
+    {
+      "name": "linux-headless",
+      "configurePreset": "linux-debug",
+      "output": {
+        "outputOnFailure": true
+      },
+      "execution": {
+        "stopOnFailure": true
+      },
+      "filter": {
+        "label": {
+          "include": [
+            "headless"
+          ]
+        }
+      }
     }
   ]
 }
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 `render` is a desktop-first C++20 codebase for building a custom 3D rendering engine and a game layer on top of it.
 
-## Current milestone (Statement 7)
+## Current milestone (Statement 8)
 
 The repository now includes:
 
@@ -12,6 +12,9 @@ The repository now includes:
 - a runnable shell that clears and submits minimal geometry each frame
 - a deterministic serialization foundation for save, recipe, item, room, and network payload schemas
 - an engine-owned filesystem/resource storage layer with category-based roots for source data, cache, saves, logs, screenshots, and crash dumps
+- CTest-integrated unit + headless smoke validation entry points
+- shader and packaging validation targets suitable for CI quality gates
+- GitHub Actions workflows for PR and main-branch validation
 
 ## Key boundaries
 
@@ -38,3 +41,5 @@ cmake --build --preset linux-debug
 - `docs/architecture.md` — platform + renderer boundary and layering notes
 - `docs/serialization.md` — canonical binary encoding, schema/version policy, and migration hooks
 - `docs/filesystem.md` — canonical path categories, writable layout, safe write behavior, and dev vs packaged lookup policy
+- `docs/testing.md` — testing categories, labels, and local validation commands
+- `docs/ci.md` — CI workflow matrix, blocking policy, and artifacts
diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake
@@ -4,6 +4,7 @@ set(RENDER_DEPENDENCY_ROOT "${CMAKE_SOURCE_DIR}/third_party" CACHE PATH "Default
 set(RENDER_SDL3_ROOT "" CACHE PATH "Optional local path override for SDL3")
 set(RENDER_BGFX_ROOT "" CACHE PATH "Optional local path override for bgfx.cmake (contains bgfx/bx/bimg)")
 option(RENDER_ALLOW_FETCHCONTENT "Allow FetchContent fallbacks for dependencies" OFF)
+option(RENDER_BGFX_BUILD_TOOLS "Build bgfx tool targets such as shaderc when available" OFF)
 
 function(render_setup_dependencies)
   add_library(render_dependencies INTERFACE)
@@ -111,7 +112,11 @@ function(render_configure_bgfx_bundle)
     message(STATUS "Dependency bgfx/bx/bimg: ${source_hint} path -> ${chosen_path}")
     if(EXISTS "${chosen_path}/CMakeLists.txt")
       set(BGFX_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
-      set(BGFX_BUILD_TOOLS OFF CACHE BOOL "" FORCE)
+      if(RENDER_BGFX_BUILD_TOOLS)
+        set(BGFX_BUILD_TOOLS ON CACHE BOOL "" FORCE)
+      else()
+        set(BGFX_BUILD_TOOLS OFF CACHE BOOL "" FORCE)
+      endif()
       add_subdirectory("${chosen_path}" "${CMAKE_BINARY_DIR}/_deps/bgfx-build" EXCLUDE_FROM_ALL)
     else()
       message(FATAL_ERROR "bgfx.cmake path does not contain CMakeLists.txt: ${chosen_path}")
@@ -121,6 +126,11 @@ function(render_configure_bgfx_bundle)
 
   if(RENDER_ALLOW_FETCHCONTENT)
     message(STATUS "Dependency bgfx/bx/bimg: FetchContent fallback enabled")
+    if(RENDER_BGFX_BUILD_TOOLS)
+      set(BGFX_BUILD_TOOLS ON CACHE BOOL "" FORCE)
+    else()
+      set(BGFX_BUILD_TOOLS OFF CACHE BOOL "" FORCE)
+    endif()
     FetchContent_Declare(
       bgfx_bundle
       GIT_REPOSITORY https://github.com/bkaradzic/bgfx.cmake.git