build: avoid version header rewrites with generated override

Author: Pierre-Luc Gagné

.github/workflows/release.yml

@@ -110,10 +110,10 @@ jobs:
           VERSION="${{ needs.validate-version.outputs.version }}"
           ARCHIVE="ds_mysql-v${VERSION}.tar.gz"
 
-          # Merge source headers with the generated version.hpp
+          # Merge source headers with generated version override header.
           mkdir -p _dist/ds_mysql
           cp -r lib/include/ds_mysql/. _dist/ds_mysql/
-          cp _ver_build/lib/include/ds_mysql/version.hpp _dist/ds_mysql/version.hpp
+          cp _ver_build/lib/include/ds_mysql/version_generated.hpp _dist/ds_mysql/version_generated.hpp
           rm -f _dist/ds_mysql/version.hpp.in
 
           tar -czf "$ARCHIVE" -C _dist ds_mysql

README.md

@@ -152,8 +152,9 @@ target_link_libraries(my_target PRIVATE ds_mysql::ds_mysql)
 
 If you are not using CMake, you can consume headers directly from either the
 release archive or a git checkout: `ds_mysql/version.hpp` is checked in as a
-fallback. In CMake builds, a generated `version.hpp` (from `version.hpp.in`) is
-preferred so `project(VERSION ...)` remains the authoritative source.
+stable wrapper/fallback. In CMake builds, a generated
+`ds_mysql/version_generated.hpp` (from `version.hpp.in`) is used so
+`project(VERSION ...)` remains authoritative without rewriting tracked headers.
 
 ## Key API
 

lib/CMakeLists.txt

@@ -5,7 +5,7 @@
 # CMakeLists.txt project(VERSION ...) remains the single source of truth.
 configure_file(
     include/ds_mysql/version.hpp.in
-    include/ds_mysql/version.hpp
+    include/ds_mysql/version_generated.hpp
     @ONLY
 )
 
@@ -48,7 +48,7 @@ if(DSMYSQL_ENABLE_INSTALL AND NOT CMAKE_SKIP_INSTALL_RULES)
     )
 
     install(
-        FILES ${CMAKE_CURRENT_BINARY_DIR}/include/ds_mysql/version.hpp
+        FILES ${CMAKE_CURRENT_BINARY_DIR}/include/ds_mysql/version_generated.hpp
         DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/ds_mysql
     )
 

lib/include/ds_mysql/version.hpp

@@ -3,23 +3,30 @@
 #include <cstdint>
 #include <string_view>
 
+#if __has_include("ds_mysql/version_generated.hpp")
+
+#include "ds_mysql/version_generated.hpp"
+
+#else
+
 namespace ds_mysql {
 
 /// Compile-time version information for DSMySQL.
 ///
-/// This checked-in header is a fallback for non-CMake consumption.
-/// In CMake builds, `version.hpp.in` is configured into the build tree and
-/// should be preferred so `project(VERSION ...)` stays authoritative.
+/// This checked-in fallback is used only when no build-system generated
+/// `version_generated.hpp` is present (e.g. raw-header, non-CMake usage).
 struct version {
-    static constexpr std::uint32_t major  = 1;
+    static constexpr std::uint32_t major  = 0;
     static constexpr std::uint32_t minor  = 0;
     static constexpr std::uint32_t patch  = 0;
 
     /// Packed integer: major * 10000 + minor * 100 + patch.
     static constexpr std::uint32_t value  = major * 10'000u + minor * 100u + patch;
 
-    /// Canonical "major.minor.patch" string.
-    static constexpr std::string_view string = "1.0.0";
+    /// Canonical fallback string for non-generated builds.
+    static constexpr std::string_view string = "0.0.0+unknown";
 };
 
-}  // namespace ds_mysql
+}  // namespace ds_mysql
+
+#endif

lib/include/ds_mysql/version.hpp.in

@@ -7,8 +7,9 @@ namespace ds_mysql {
 
 /// Compile-time version information for DSMySQL.
 ///
-/// The values are generated from the CMakeLists.txt project() declaration and
-/// therefore always match the authoritative version of the library.
+/// This header is generated by CMake as `version_generated.hpp` from
+/// CMakeLists.txt project(VERSION ...), and included by `version.hpp`.
+/// Values therefore always match the authoritative project version.
 ///
 /// Usage:
 ///   static_assert(ds_mysql::version::major >= 1);