Add CTest coverage reporting

Instrument libakgl in opt-in coverage builds, use CTest fixtures to reset counters and emit Cobertura XML and detailed HTML reports, and upload those reports from Gitea CI. Document the local coverage workflow for contributors.

Co-authored-by: Codex (GPT-5) <noreply@openai.com>

CMakeLists.txt

@@ -2,6 +2,14 @@ cmake_minimum_required(VERSION 3.10)
 project(akgl LANGUAGES C)
 
 include(CTest)
+option(AKGL_COVERAGE "Instrument libakgl and generate coverage reports with CTest" OFF)
+
+if(AKGL_COVERAGE)
+  if(NOT CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+    message(FATAL_ERROR "AKGL_COVERAGE requires GCC or Clang")
+  endif()
+  find_program(GCOVR_EXECUTABLE gcovr REQUIRED)
+endif()
 
 if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
 
@@ -141,6 +149,44 @@ target_include_directories(akgl PUBLIC
   deps/semver/
   )
 
+if(AKGL_COVERAGE)
+  target_compile_options(akgl PRIVATE --coverage -O0 -g)
+  target_link_options(akgl PRIVATE --coverage)
+
+  set(AKGL_COVERAGE_DIR "${CMAKE_CURRENT_BINARY_DIR}/coverage")
+  file(MAKE_DIRECTORY "${AKGL_COVERAGE_DIR}")
+
+  add_test(
+    NAME coverage_reset
+    COMMAND ${GCOVR_EXECUTABLE}
+            --root "${CMAKE_CURRENT_SOURCE_DIR}"
+            --object-directory "${CMAKE_CURRENT_BINARY_DIR}"
+            --delete
+  )
+  set_tests_properties(coverage_reset PROPERTIES FIXTURES_SETUP akgl_coverage)
+  set_tests_properties(
+    actor bitmasks character registry sprite staticstring tilemap util semver_unit
+    PROPERTIES FIXTURES_REQUIRED akgl_coverage
+  )
+
+  add_test(
+    NAME coverage_report
+    COMMAND ${GCOVR_EXECUTABLE}
+            --root "${CMAKE_CURRENT_SOURCE_DIR}"
+            --object-directory "${CMAKE_CURRENT_BINARY_DIR}"
+            --filter "${CMAKE_CURRENT_SOURCE_DIR}/src/"
+            --xml-pretty
+            --xml "${AKGL_COVERAGE_DIR}/coverage.xml"
+            --html-details "${AKGL_COVERAGE_DIR}/index.html"
+  )
+  set_tests_properties(
+    coverage_report
+    PROPERTIES
+      FIXTURES_CLEANUP akgl_coverage
+      WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+  )
+endif()
+
 target_link_libraries(akgl
   PUBLIC
     SDL3::SDL3