Use a generated file instead of a macro.

Hopefully this will not trigger to re-build the whole project in case of a version change.

Author: dhebbeker

.gitignore

@@ -7,3 +7,5 @@
 doc/html/
 doc/latex/
 .vscode/settings.json
+__pycache__
+/lib/utilities/vcs_identifier_gen.hpp

define_vcs_id_macro.py

@@ -0,0 +1,28 @@
+"""
+generate_vcs_identifier.py
+
+This script generates a source file containing a version control system (VCS)
+identifier string. It retrieves the VCS identifier from the 'vcs_utils' module
+and writes it to a specified source file.
+
+The script will overwrite the file if it already exists, and any write failures 
+are handled gracefully.
+
+This script should be loaded by PlatformIO during the project build and is not
+designed to be run independently.
+"""
+
+from vcs_utils import get_vcs_id, write_vcs_id_to_file
+import os.path
+Import("env")
+
+# Get the source directory path from PlatformIO configuration
+source_dir = env.subst("$PROJECT_DIR")
+
+# Path to the output file within
+output_file = os.path.join(source_dir, 'lib', 'utilities', 'vcs_identifier_gen.hpp')
+
+vcs_id = get_vcs_id()
+
+if vcs_id:
+    write_vcs_id_to_file(vcs_id, output_file)

generate_vcs_identifier.py

@@ -0,0 +1,9 @@
+#pragma once
+
+#include <optional>
+#if __has_include("vcs_identifier_gen.hpp")
+#include "vcs_identifier_gen.hpp"
+constexpr std::optional<const char *> vcsId = VCS_ID;
+#else
+constexpr std::optional<const char *> vcsId = std::nullopt;
+#endif

get_vcs_identifier.py

@@ -22,7 +22,7 @@ build_flags =
 	-DBAUD_RATE=${this.monitor_speed}
 monitor_speed = 115200
 extra_scripts =
-	pre:define_vcs_id_macro.py
+	pre:generate_vcs_identifier.py
 
 [env:native]
 platform = native

lib/utilities/version.hpp

@@ -19,22 +19,9 @@ void setup()
 {
     serial_port::initialize();
     serial_port::cout << "\x1b[20h"; // Tell the terminal to use CR/LF for newlines instead of just CR.
-
-    constexpr const auto programIdentificationString = []() {
-        constexpr const auto versionString = getVersionString();
-        if constexpr (versionString)
-        {
-            return versionString.value();
-        }
-        else
-        {
-            return " compiled at " __DATE__ " " __TIME__;
-        }
-    }();
-
     serial_port::cout
         << std::endl
-        << " begin program '" << __FILE__ << programIdentificationString << std::endl;
+        << " begin program version '" << vcsId.value_or("unknown") << "'" << std::endl;
     serial_port::setCallbackForLineReception([](const serial_port::String &commandLine) {
         ProtocolHandler::execute(commandLine.c_str());
     });

platformio.ini

@@ -0,0 +1,66 @@
+"""
+vcs_utils.py
+
+This module provides utility functions to retrieve the version control system
+(VCS) identifier using Git and to write it to a C source file.
+
+The functions handle cases where Git is not installed or the current directory
+is not a Git repository, and handle file write failures gracefully.
+"""
+
+import subprocess
+import sys
+
+def get_vcs_id():
+    """
+    Attempts to retrieve the VCS identifier using the 'git describe' command.
+    
+    Returns:
+        str: A string containing the VCS identifier if successful, or an empty 
+             string if Git is not available or the directory is not a Git repository.
+    
+    This function handles the following exceptions:
+        - subprocess.CalledProcessError: Raised if the 'git' command fails, e.g.,
+          if the current directory is not a Git repository.
+        - FileNotFoundError: Raised if 'git' is not installed or not found in the
+          system's PATH.
+    
+    All warnings are printed to stderr.
+    """
+    try:
+        vcs_output = subprocess.run(
+            ["git", "describe", "--always", "--dirty", "--all", "--long"],
+            stdout=subprocess.PIPE, text=True, check=True
+        )
+        vcs_string = vcs_output.stdout.strip()
+        print("vcs string: " + vcs_string)
+        return vcs_string
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        # Print the warning to stderr
+        print("Warning: Unable to retrieve VCS description. Error:", str(e), file=sys.stderr)
+        return ""
+
+
+def write_vcs_id_to_file(vcs_id, file_path):
+    """
+    Writes the given VCS identifier as a C-style string to a file.
+    
+    Args:
+        vcs_id (str): The VCS identifier string to write to the file.
+        file_path (str): The path to the C source file to write to.
+    
+    If the file exists, it will be overwritten. If writing to the file fails,
+    a warning will be printed to stderr, but the script will not terminate
+    with an error.
+    """
+    try:
+        # Prepare the C-style string definition
+        c_content = f'#define VCS_ID "{vcs_id}"\n'
+        
+        # Write the content to the file (overwriting if it exists)
+        with open(file_path, 'w') as file:
+            file.write(c_content)
+    
+    except IOError as e:
+        # If writing to the file fails, print the warning to stderr
+        print(f"Warning: Unable to write VCS ID to file '{file_path}'. Error: {str(e)}", file=sys.stderr)