Generate Single Header via GitHub Workflows (#299)

* Single header generation test

* Test pushing csv.hpp to single header

* Update cmake-multi-platform.yml

* Update documentation

* Make single include test optional

* Added small redirect

* Update CMakeLists.txt

* Stabilize Windows CI build

* Update cmake-multi-platform.yml

Author: vincentlaucsb

.github/workflows/cmake-multi-platform.yml

@@ -4,7 +4,7 @@ name: CMake on multiple platforms
 
 on:
   push:
-    branches: [ "master", "feb-15-2026" ]
+    branches: [ "master" ]
   pull_request:
     branches: [ "master" ]
 
@@ -51,6 +51,11 @@ jobs:
       with:
         submodules: recursive
 
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
     - name: Set reusable strings
       # Turn repeated input strings (such as the build output directory) into step outputs. These step outputs can be used throughout the workflow file.
       id: strings
@@ -64,17 +69,27 @@ jobs:
       run: >
         cmake -B ${{ steps.strings.outputs.build-output-dir }}
         -DCSV_CXX_STANDARD=${{ matrix.cxx_standard }}
+        -DCSV_BUILD_SINGLE_INCLUDE_TEST=ON
         -DCMAKE_CXX_COMPILER=${{ matrix.cpp_compiler }}
         -DCMAKE_C_COMPILER=${{ matrix.c_compiler }}
         -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
         -S ${{ github.workspace }}
 
     - name: Build
       # Build your program with the given configuration. Note that --config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
+      # single_include_test is excluded from the default "all" target and is built explicitly in the next step.
       run: cmake --build ${{ steps.strings.outputs.build-output-dir }} --config ${{ matrix.build_type }}
 
+    - name: Single-header smoke test
+      if: matrix.os != 'windows-latest'
+      # Explicitly build the single-header smoke-test target so CI validates the freshly generated amalgamated header.
+      # TODO: Re-enable on Windows after fixing single_include_test target generation/project discovery.
+      run: cmake --build ${{ steps.strings.outputs.build-output-dir }} --config ${{ matrix.build_type }} --target single_include_test
+
     - name: Test
       working-directory: ${{ steps.strings.outputs.build-output-dir }}
       # Execute tests defined by the CMake configuration. Note that --build-config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
       # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
       run: ctest --build-config ${{ matrix.build_type }}
+
+

.github/workflows/codeql.yml

@@ -2,7 +2,7 @@ name: CodeQL Analysis
 
 on:
   push:
-    branches: [ "master", "feb-15-2026" ]
+    branches: [ "master" ]
   pull_request:
     branches: [ "master" ]
   schedule:

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Documentation
+name: Documentation and Single Header
 
 on:
   push:
@@ -33,6 +33,16 @@ jobs:
     - name: Run Doxygen
       run: doxygen Doxyfile
 
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: Generate single header
+      # Drops csv.hpp into docs/html so it is served at the same Pages URL
+      # as the Doxygen docs: https://<owner>.github.io/csv-parser/csv.hpp
+      run: python single_header.py docs/html/csv.hpp
+
     - name: Upload Pages artifact
       uses: actions/upload-pages-artifact@v3
       with:

.github/workflows/sanitizers.yml

@@ -2,7 +2,7 @@ name: Memory and Thread Sanitizers
 
 on:
   push:
-    branches: [ "master", "feb-15-2026" ]
+    branches: [ "master" ]
   pull_request:
     branches: [ "master" ]
 

.gitignore

@@ -54,6 +54,12 @@ docs/html
 *.gcno
 *.gcov
 
+# Generated single-header files
+# These are auto-generated by single_header.py and deployed via CI
+# Users should download from: https://vincentlaucsb.github.io/csv-parser/csv.hpp
+single_include_test/csv.hpp
+build/single_include_generated/
+
 # =========================
 # Operating System Files
 # =========================

CMakeLists.txt

@@ -8,6 +8,7 @@ else()
 endif(CSV_CXX_STANDARD)
 
 option(BUILD_PYTHON "Build Python Binding" OFF)
+option(CSV_BUILD_SINGLE_INCLUDE_TEST "Build single-header smoke test (requires Python)" OFF)
 option(ENABLE_CODE_COVERAGE "Enable code coverage instrumentation" OFF)
 
 message("Building CSV library using C++${CMAKE_CXX_STANDARD}")
@@ -92,15 +93,44 @@ if (CSV_DEVELOPER)
       find_package(Python3 COMPONENTS Interpreter)
     endif()
     if(Python3_Interpreter_FOUND OR PYTHONINTERP_FOUND)
-      add_custom_target(generate_single_header
-          COMMAND ${Python3_EXECUTABLE} single_header.py > single_include/csv.hpp
-          COMMAND ${Python3_EXECUTABLE} single_header.py > single_include_test/csv.hpp
+      if(Python3_Interpreter_FOUND)
+        set(CSV_PYTHON_EXECUTABLE ${Python3_EXECUTABLE})
+      else()
+        set(CSV_PYTHON_EXECUTABLE ${PYTHON_EXECUTABLE})
+      endif()
+
+      set(CSV_SINGLE_INCLUDE_GENERATED_DIR ${CSV_BUILD_DIR}/single_include_generated)
+      set(CSV_SINGLE_INCLUDE_GENERATED_HEADER ${CSV_SINGLE_INCLUDE_GENERATED_DIR}/csv.hpp)
+          file(GLOB_RECURSE CSV_SINGLE_HEADER_INPUTS CONFIGURE_DEPENDS
+            ${CSV_INCLUDE_DIR}/*.hpp
+            ${CSV_INCLUDE_DIR}/*.h
+            ${CSV_INCLUDE_DIR}/*.cpp
+          )
+
+      add_custom_command(
+          OUTPUT ${CSV_SINGLE_INCLUDE_GENERATED_HEADER}
+          COMMAND ${CMAKE_COMMAND} -E make_directory ${CSV_SINGLE_INCLUDE_GENERATED_DIR}
+          COMMAND ${CSV_PYTHON_EXECUTABLE} single_header.py ${CSV_SINGLE_INCLUDE_GENERATED_HEADER}
           WORKING_DIRECTORY ${CSV_ROOT_DIR}
+            DEPENDS ${CSV_ROOT_DIR}/single_header.py ${CSV_SINGLE_HEADER_INPUTS}
+          COMMENT "Generating single-header csv.hpp"
       )
-      # Single header compilation test
-      add_subdirectory(single_include_test)
+
+      add_custom_target(generate_single_header
+          DEPENDS ${CSV_SINGLE_INCLUDE_GENERATED_HEADER}
+      )
+
+      # Single header compilation test (optional, mainly for validation)
+      if(CSV_BUILD_SINGLE_INCLUDE_TEST)
+          # Keep this target out of the default "all" build so CI can run it
+          # explicitly in its dedicated smoke-test step.
+          add_subdirectory(single_include_test EXCLUDE_FROM_ALL)
+      endif()
     else()
       message(WARNING "Python3 not found, skipping target 'generate_single_header'.")
+      if(CSV_BUILD_SINGLE_INCLUDE_TEST)
+        message(FATAL_ERROR "CSV_BUILD_SINGLE_INCLUDE_TEST=ON requires a Python 3 interpreter for single-header generation.")
+      endif()
     endif()
 
     # Documentation

README.md

@@ -118,7 +118,14 @@ While C++17 is recommended, C++11 is the minimum version required. This library
 [Martin Moene's string view library](https://github.com/martinmoene/string-view-lite) if `std::string_view` is not available.
 
 ### Single Header
-This library is available as a single `.hpp` file under [`single_include/csv.hpp`](single_include/csv.hpp).
+**[📥 Download csv.hpp](https://vincentlaucsb.github.io/csv-parser/csv.hpp)** — Available on GitHub Pages
+
+Or copy the URL:
+```
+https://vincentlaucsb.github.io/csv-parser/csv.hpp
+```
+
+The file is automatically generated and deployed on every commit to `master`, ensuring you always have the latest version.
 
 ### CMake Instructions
 If you're including this in another CMake project, you can simply clone this repo into your project directory, 

include/csv.hpp

@@ -1,5 +1,5 @@
 /*
-CSV for C++, version 2.5.0
+CSV for C++, version 2.5.1
 https://github.com/vincentlaucsb/csv-parser
 
 MIT License

single_header.py

@@ -1,6 +1,8 @@
 from collections import namedtuple
+from contextlib import redirect_stdout
 import os
 import re
+import sys
 
 CPP_SEP = '/'
 Include = namedtuple('Include', ['path', 'line_no'])
@@ -194,7 +196,7 @@ def process_file(path: Path):
 
     return header_concat
 
-if __name__ == "__main__":
+def generate_single_header():
     ''' Iterate over every .cpp and .hpp file '''
     headers = []
     sources = []
@@ -226,9 +228,19 @@ def process_file(path: Path):
 
     for cpp in sources:
         source_collate += file_strip(cpp) + '\n'
-    
+
     # Generate hpp file
     print("#pragma once")
     print(header_concat.replace(
         "#define CSV_INLINE", "#define CSV_INLINE inline").replace(
-            "/** INSERT_CSV_SOURCES **/", source_collate))
+            "/** INSERT_CSV_SOURCES **/", source_collate))
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1:
+        output_path = sys.argv[1]
+        with open(output_path, mode='w', newline='') as outfile:
+            with redirect_stdout(outfile):
+                generate_single_header()
+    else:
+        generate_single_header()

single_include/README.md

@@ -0,0 +1,73 @@
+# Single Header Distribution
+
+> **`single_include/csv.hpp` is now a small compatibility shim, not the full amalgamated header.**
+
+## For Users
+
+**[📥 Download csv.hpp](https://vincentlaucsb.github.io/csv-parser/csv.hpp)** — Available on GitHub Pages
+
+Or copy the URL:
+```
+https://vincentlaucsb.github.io/csv-parser/csv.hpp
+```
+
+This file is automatically generated and deployed on every commit to `master`, ensuring you always have the latest version.
+
+### Usage
+
+Once downloaded, simply include it in your project:
+
+```cpp
+#include "csv.hpp"
+
+// Use the library as normal
+```
+
+No build configuration needed — everything is self-contained in the single file.
+
+---
+
+## For Maintainers
+
+### Generating the Single Header Locally
+
+To generate the amalgamated header yourself:
+
+```bash
+python single_header.py output_path/csv.hpp
+```
+
+This reads all source files from `include/` and produces a completely self-contained header file.
+
+### Validation
+
+The CI pipeline automatically validates the generated header by:
+1. Generating it in the build tree during CMake configuration
+2. Compiling it cleanly with `single_include_test` (multi-TU smoke test)
+3. Deploying the result to GitHub Pages
+
+Run the smoke test locally:
+
+```bash
+cd build
+cmake --build . --target single_include_test
+```
+
+### Important Notes
+
+- **Do not manually commit `csv.hpp`** — it is generated and deployed by CI
+- **Do not modify generated files** — always edit the source files in `include/`
+- **The build-generated header is under `build/single_include_generated/`** — this is the stable artifact used by `single_include_test`
+- **GitHub Pages serves the canonical version** — see [Distribution Overview](#for-users) above
+
+### Distribution Model
+
+- **Build-time:** CMake generates into build tree for testing
+- **CI/Release:** Deployed to GitHub Pages for public consumption
+- **Repository:** Source files only (no pre-generated artifacts)
+
+This model ensures:
+- No stale artifacts in git
+- Always-fresh version on GitHub Pages
+- Deterministic, reproducible generation
+- Clean maintenance burden