Restructure2

.clang-tidy

@@ -0,0 +1,20 @@
+Checks: >
+  clang-diagnostic-*,
+  clang-analyzer-*,
+  modernize-*,
+  readability-*,
+  performance-*,
+  bugprone-*,
+  -modernize-use-trailing-return-type,
+  -readability-magic-numbers,
+  -readability-named-parameter,
+  -readability-const-return-type,
+  -readability-identifier-length,
+  -readability-braces-around-statements,
+  -readability-implicit-bool-conversion,
+  -readability-function-cognitive-complexity,
+  -modernize-avoid-c-arrays,
+  -bugprone-easily-swappable-parameters,
+  -modernize-use-equals-default,
+  -readability-convert-member-functions-to-static
+HeaderFilterRegex: '.*(src|test|demo)/.*\.(h|cc)$'

.editorconfig

@@ -6,7 +6,11 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.{cc,h}]
+[*.{h,cc}]
+indent_style = space
+indent_size = 2
+
+[CMakeLists.txt]
 indent_style = space
 indent_size = 2
 

.github/workflows/ci.yml

@@ -10,14 +10,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install GSL
+      - name: Install dependencies
         run: sudo apt-get install -y libgsl-dev
 
-      - name: Configure
-        run: cmake -B build -DCMAKE_BUILD_TYPE=Debug
-
-      - name: Build
-        run: cmake --build build
-
-      - name: Test
-        run: build/dvrlib_main
+      - name: Build and test
+        run: make test

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Docs
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: sudo apt-get install -y libgsl-dev doxygen graphviz
+
+      - name: Build docs
+        run: make doc
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/html
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

CMakeLists.txt

@@ -25,18 +25,18 @@ target_link_libraries(dvrlib PUBLIC GSL::gsl GSL::gslcblas)
 target_compile_options(dvrlib PRIVATE -Wall)
 
 # Tests
-add_executable(dvrlib_main
+add_executable(dvrlib_test
     test/main.cc
     test/gsl_wrapper_tests.cc
     test/recon_tests.cc
     test/vdi2048_test.cc
 )
-target_link_libraries(dvrlib_main PRIVATE dvrlib Catch2::Catch2)
-target_compile_options(dvrlib_main PRIVATE -Wall)
+target_link_libraries(dvrlib_test PRIVATE dvrlib Catch2::Catch2)
+target_compile_options(dvrlib_test PRIVATE -Wall)
 
 include(CTest)
 include(Catch)
-catch_discover_tests(dvrlib_main)
+catch_discover_tests(dvrlib_test)
 
 # Demo
 add_executable(dvrlib_demo demo/vdi2048_demo.cc demo/vdi2048.cc)

Doxyfile

@@ -854,7 +854,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  =
+INPUT                  = README.md src
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1007,7 +1007,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

Makefile

@@ -1,4 +1,8 @@
-.PHONY: all demo test coverage coverage-html clean
+SHELL := /bin/bash
+SRCS = $(shell find src test demo -name '*.h' -o -name '*.cc')
+
+.PHONY: all demo test coverage coverage-html check doc clean
+
 
 BUILD     = build
 BUILD_COV = build-cov
@@ -7,28 +11,35 @@ COV_OUT   = coverage-html
 all: $(BUILD)/CMakeCache.txt
 	cmake --build $(BUILD) -- -s
 
-demo: all
+run-demo: all
 	$(BUILD)/dvrlib_demo
 
-test: all
-	@$(BUILD)/dvrlib_main
+run-demo-zalg: all
+	$(BUILD)/dvrlib_demo --keep-free
+
+run-demo-compare: all
+	@diff --width=160 -y <($(BUILD)/dvrlib_demo) <($(BUILD)/dvrlib_demo --keep-free) || true
+
+run-tests: all
+	@$(BUILD)/dvrlib_test
 
-coverage: $(BUILD_COV)/CMakeCache.txt
+run-coverage: $(BUILD_COV)/CMakeCache.txt
 	cmake --build $(BUILD_COV) -- -s
-	$(BUILD_COV)/dvrlib_main
+	$(BUILD_COV)/dvrlib_test
 	@cd $(BUILD_COV)/CMakeFiles/dvrlib.dir/src && \
 	    gcov *.gcno 2>/dev/null \
 	        | awk '/File.*\/src\/[^/]+\.cc/{f=1; print} f && /Lines executed/{print; f=0}'; \
 	    rm -f *.gcov 2>/dev/null || true
 
-coverage-html: $(BUILD_COV)/CMakeCache.txt
+run-coverage-html: $(BUILD_COV)/CMakeCache.txt
 	@which lcov > /dev/null 2>&1 || { echo "lcov not found. Install with: sudo apt install lcov"; exit 1; }
 	cmake --build $(BUILD_COV) -- -s
-	$(BUILD_COV)/dvrlib_main
+	$(BUILD_COV)/dvrlib_test
 	lcov --capture --directory $(BUILD_COV) --output-file $(BUILD_COV)/coverage.info
 	lcov --remove $(BUILD_COV)/coverage.info '*/build-cov/_deps/*' '/usr/*' --output-file $(BUILD_COV)/coverage.info
 	genhtml $(BUILD_COV)/coverage.info --output-directory $(COV_OUT)
-	@echo "Report: $(COV_OUT)/index.html"
+	@echo "================================================="
+	@echo "Report written to: $(COV_OUT)/index.html"
 
 $(BUILD)/CMakeCache.txt:
 	cmake -B $(BUILD) -S . -DCMAKE_BUILD_TYPE=Debug
@@ -38,5 +49,19 @@ $(BUILD_COV)/CMakeCache.txt:
 	    -DCMAKE_CXX_FLAGS="--coverage" \
 	    -DCMAKE_EXE_LINKER_FLAGS="--coverage"
 
+check: $(BUILD)/CMakeCache.txt
+	# Commented out, clang-tidy reports too much (sometimes dangerous) nonsense
+	#	@echo "--- clang-tidy ---"
+	#	@find src test demo -name '*.cc' | xargs clang-tidy -p $(BUILD)
+	@echo "--- clang-format ---"
+	@clang-format --dry-run --Werror $(SRCS) && echo "format OK"
+
+format_source:
+	@echo "--- clang-format ---"
+	@clang-format $(SRCS) -i --verbose
+
+doc: $(BUILD)/CMakeCache.txt
+	cmake --build $(BUILD) --target doc
+
 clean:
 	rm -rf $(BUILD) $(BUILD_COV) $(COV_OUT)

README.md

@@ -25,24 +25,33 @@ On Debian/Ubuntu:
 sudo apt install libgsl-dev cmake build-essential
 ```
 
-## Building
+## Building and Testing
 
 ```bash
-cmake -B build -DCMAKE_BUILD_TYPE=Debug   # configure
-cmake -B build                            # build library + test binary
-cmake -B build --target doc               # generate API docs (requires Doxygen)
-rm -rf build                              # clean (remove build directory)
+make                   # configure (if needed) and build
+make run-tests         # build and run tests
+make run-demo          # build and run the VDI 2048 demo
+make run-demo-zalg     # same, using the Z-algorithm (keeps free variables)
+make run-demo-compare  # show both variants side by side
+make run-coverage      # build with coverage flags and show per-file line coverage
+make run-coverage-html # same, but generate HTML report (requires lcov)
+make check             # run clang-format check
+make clean             # remove all build directories
 ```
 
-Produces `build/libdvrlib.a` (static library) and `build/dvrlib_main` (test binary).
-
-## Running Tests
+For the HTML coverage report:
 
 ```bash
-cmake -B build && build/dvrlib_main
+sudo apt install lcov
+make run-coverage-html
+# open coverage-html/index.html
 ```
 
-The test binary runs the GSL wrapper tests, the reconciliation tests, and the VDI 2048 example. A clean exit (return code 0) means all tests pass; an assertion failure or uncaught exception indicates a failure.
+To build the API docs (requires Doxygen):
+
+```bash
+make doc
+```
 
 ## Usage Example
 
@@ -80,13 +89,18 @@ int main() {
 
 ```
 src/
-  gsl_wrapper.{h,cc}       GSL vector/matrix RAII wrappers
-  gsl_wrapper_tests.{h,cc} Tests for the wrapper layer
-  recon.{h,cc}              Reconciliation algorithms
-  recon_system.{h,cc}       High-level system description
-  recon_tests.{h,cc}        Tests for reconciliation
-  vdi2048.{h,cc}            VDI 2048 worked example
-  main.cc                   Test runner entry point
+  gsl_wrapper.{h,cc}    GSL vector/matrix RAII wrappers
+  recon.{h,cc}          Reconciliation algorithms
+  recon_system.{h,cc}   High-level system description
+test/
+  main.cc               Catch2 test runner entry point
+  gsl_wrapper_tests.cc  Tests for the wrapper layer
+  recon_tests.cc        Tests for reconciliation
+  vdi2048_test.cc       VDI 2048 regression test
+  custom_reporter.h     Custom Catch2 summary listener
+demo/
+  vdi2048.{h,cc}        VDI 2048 worked example
+  vdi2048_demo.cc       Demo entry point
 ```
 
 ## License

demo/utils.h

@@ -3,12 +3,21 @@
 
 #include <cstdio>
 #include <sstream>
+#include <string>
 
-#define PRINT(x) \
-  do { std::ostringstream _s; _s << (x); printf(#x ": %s\n", _s.str().c_str()); } while(0)
+#define PRINT(x)                           \
+  do {                                     \
+    std::ostringstream _s;                 \
+    _s << (x);                             \
+    printf(#x ": %s\n", _s.str().c_str()); \
+  } while(0)
 #define PRINT_SEP \
   printf("======================================================================\n")
-#define PRINT_TITLE(x) \
-  do { PRINT_SEP; printf("     %s\n", (x)); PRINT_SEP; } while(0)
+#define PRINT_TITLE(x)                        \
+  do {                                        \
+    PRINT_SEP;                                \
+    printf("     %s\n", (std::string() + x).c_str()); \
+    PRINT_SEP;                                \
+  } while(0)
 
 #endif  // DVRLIB_UTILS_H