ceedling 1.0.1 → 1.1.0

data/lib/ceedling/{plugin_manager.rb → plugins/plugin_manager.rb}

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
@@ -12,7 +12,7 @@ class PluginManager
   constructor :configurator, :plugin_manager_helper, :loginator, :reportinator, :system_wrapper
 
   def setup
-    @build_fail_registry = []
+    @build_fail_registry = {}
     @plugin_objects = [] # List so we can preserve order
   end
 
@@ -23,8 +23,9 @@ class PluginManager
       # Protect against instantiating object multiple times due to processing config multiple times (option files, etc)
       next if (@plugin_manager_helper.include?( @plugin_objects, hash[:plugin] ) )
 
-      msg = @reportinator.generate_progress( "Instantiating plugin class #{camelize( hash[:plugin] )}" )
-      @loginator.log( msg, Verbosity::OBNOXIOUS )
+      @loginator.lazy( Verbosity::OBNOXIOUS ) do 
+        @reportinator.generate_progress( "Instantiating plugin class #{camelize( hash[:plugin] )}" )
+      end
 
       begin
         @system_wrapper.require_file( "#{hash[:plugin]}.rb" )
@@ -53,21 +54,38 @@ class PluginManager
   end
 
   def print_plugin_failures
-    if (@build_fail_registry.size > 0)
-      report = @reportinator.generate_banner('BUILD FAILURE SUMMARY')
-
-      @build_fail_registry.each do |failure|
-        report += "#{' - ' if (@build_fail_registry.size > 1)}#{failure}\n"
-      end
+    return if (@build_fail_registry.size == 0)
+    failures = []
 
-      report += "\n"
+    banner = @reportinator.generate_banner(
+      @loginator.decorate( 'BUILD FAILURE SUMMARY', LogLabels::FAIL )
+    )
 
-      @loginator.log( report, Verbosity::ERRORS, LogLabels::NONE )
+    # If we only ran basic unit tests, there's no need to prefix the failure messages with the context.
+    if (@build_fail_registry.keys.size == 1 and @build_fail_registry.keys[0] == TEST_SYM)
+      @build_fail_registry.each do |context, messages|
+        messages.each {|message| failures << message}
+      end
+    # Otherwise, add the context to each message so the user knows the source of the failure.
+    else
+      @build_fail_registry.each do |context, messages|
+        messages.each {|message| failures << "[#{context.to_s.upcase}] #{message}"}
+      end
     end
+
+    @loginator.log_list( failures, "\n" + banner, Verbosity::ERRORS, LogLabels::NONE )
   end
 
-  def register_build_failure(message)
-    @build_fail_registry << message if (message and not message.empty?)
+  def register_build_failure(context, message)
+    return if (message.nil? or message.empty?)
+
+    _context = context.is_a?(Symbol) ? context : context.to_sym
+
+    # Create a new key/value with empty list if it doesn't exist
+    @build_fail_registry[_context] ||= []
+
+    list = @build_fail_registry[_context]
+    list << message if !list.include?( message )
   end
 
   #### execute all plugin methods ####
@@ -94,18 +112,25 @@ class PluginManager
   def post_test_fixture_execute(arg_hash)
     # Special arbitration: Raw test results are printed or taken over by plugins handling the job
     @loginator.log( arg_hash[:shell_result][:output] ) if @configurator.plugins_display_raw_test_results
+
+    # Core failure detection independent of any reporting plugin
+    register_build_failure( arg_hash[:context], 'Unit test failures' ) if arg_hash.dig(:results, :counts, :failed).to_i > 0
+
     execute_plugins(:post_test_fixture_execute, arg_hash)
   end
 
   def pre_test(test); execute_plugins(:pre_test, test); end
   def post_test(test); execute_plugins(:post_test, test); end
 
-  def pre_release; execute_plugins(:pre_release); end
-  def post_release; execute_plugins(:post_release); end
+  def pre_test_build(context, timestamp_s); execute_plugins(:pre_test_build, context, timestamp_s); end
+  def post_test_build(context, timestamp_s); execute_plugins(:post_test_build, context, timestamp_s); end
+
+  def pre_release_build(timestamp_s); execute_plugins(:pre_release_build, timestamp_s); end
+  def post_release_build(timestamp_s); execute_plugins(:post_release_build, timestamp_s); end
 
-  def pre_build; execute_plugins(:pre_build); end
-  def post_build; execute_plugins(:post_build); end
-  def post_error; execute_plugins(:post_error); end
+  def pre_build(timestamp_s); execute_plugins(:pre_build, timestamp_s); end
+  def post_build(timestamp_s); execute_plugins(:post_build, timestamp_s); end
+  def post_error(timestamp_s); execute_plugins(:post_error, timestamp_s); end
 
   def summary; execute_plugins(:summary); end
 
@@ -119,8 +144,9 @@ class PluginManager
     @plugin_objects.each do |plugin|
       begin
         if plugin.respond_to?(method)
-          message = @reportinator.generate_progress( "Plugin | #{camelize( plugin.name )} > :#{method}" )
-          @loginator.log( message, Verbosity::OBNOXIOUS )
+          @loginator.lazy( Verbosity::OBNOXIOUS ) do 
+            @reportinator.generate_progress( "Plugin | #{camelize( plugin.name )} > :#{method}" )
+          end
           plugin.send(method, *args)
         end
       rescue

data/lib/ceedling/{plugin_manager_helper.rb → plugins/plugin_manager_helper.rb}

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 

data/lib/ceedling/{plugin_reportinator.rb → plugins/plugin_reportinator.rb}

@@ -1,17 +1,18 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
+require 'erb'
 require 'ceedling/constants'
 require 'ceedling/defaults'
 require 'ceedling/exceptions'
 
 class PluginReportinator
   
-  constructor :plugin_reportinator_helper, :plugin_manager, :reportinator
+  constructor :plugin_reportinator_helper, :plugin_manager, :reportinator, :loginator
 
   def setup
     @test_results_template = nil
@@ -22,7 +23,8 @@ class PluginReportinator
   end
 
   def set_system_objects(system_objects)
-    @plugin_reportinator_helper.ceedling = system_objects
+    # Available for use inside ERB report rendering via binding()
+    @ceedling = system_objects
   end
   
   def fetch_results(results_path, test, options={:boom => false})
@@ -93,29 +95,19 @@ class PluginReportinator
     return aggregated_results
   end
       
-  def run_test_results_report(hash, verbosity=Verbosity::NORMAL, &block)
+  def run_test_results_report(hash, verbosity=Verbosity::NORMAL)
     if @test_results_template.nil?
       raise CeedlingException.new( "No test results report template has been set." )
     end
 
-    run_report(
-      @test_results_template,
-      hash,
-      verbosity,
-      &block
-    )
+    run_report( @test_results_template, hash, verbosity )
   end
   
   def run_report(template, hash=nil, verbosity=Verbosity::NORMAL)
-    failure = nil
-    failure = yield() if block_given?
-  
-    @plugin_manager.register_build_failure( failure )
-  
-    # Set verbosity to error level if there were failures
-    verbosity = failure ? Verbosity::ERRORS : Verbosity::NORMAL
+    output = ERB.new( template, trim_mode: "%<>" )
 
-    @plugin_reportinator_helper.run_report( template, hash, verbosity )
+    # Run the report template and log result with no log level heading
+    @loginator.log( output.result(binding()), verbosity, LogLabels::NONE )
   end
   
   #

data/lib/ceedling/{plugin_reportinator_helper.rb → plugins/plugin_reportinator_helper.rb}

@@ -1,21 +1,17 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-require 'erb'
-require 'rubygems'
 require 'rake' # for ext()
 require 'ceedling/constants'
 require 'ceedling/exceptions'
 
 class PluginReportinatorHelper
-  
-  attr_writer :ceedling
-  
-  constructor :configurator, :loginator, :yaml_wrapper, :file_wrapper
+    
+  constructor :configurator, :yaml_wrapper, :file_wrapper
   
   def fetch_results(results_path, options)
     # Create the results filepaths
@@ -40,21 +36,28 @@ class PluginReportinatorHelper
       end
     end
 
-    # Handle if both files exists and return the newer results
-    if pass_exists and fail_exists
-      if @file_wrapper.newer?( pass_path, fail_path )
-        return @yaml_wrapper.load( pass_path )
-      else
-        return @yaml_wrapper.load( fail_path )
+    begin
+      # Handle if both files exists and return the newer results
+      if pass_exists and fail_exists
+        if @file_wrapper.newer?( pass_path, fail_path )
+          return @yaml_wrapper.load( pass_path )
+        else
+          return @yaml_wrapper.load( fail_path )
+        end
       end
-    end
 
-    # Return success results
-    return @yaml_wrapper.load(pass_path) if pass_exists
+      # Return success results
+      return @yaml_wrapper.load(pass_path) if pass_exists
+
+      # Return fail results
+      return @yaml_wrapper.load(fail_path) if fail_exists
+    rescue YamlLoadException => e
+      raise YamlLoadException.new(
+        reason: e.reason, source: e.source, original_error: e.original_error,
+        message: "Generated test results file is corrupted or unreadable ⏩️ #{e.message}"
+      )
+    end
 
-    # Return fail results
-    return @yaml_wrapper.load(fail_path) if fail_exists
-    
     # Safety fall-through (flow control should never get here)
     return {}
   end
@@ -73,12 +76,5 @@ class PluginReportinatorHelper
     aggregate[:counts][:stdout]  += results[:stdout].size
     aggregate[:total_time]       += results[:time]
   end
-
-  def run_report(template, hash, verbosity)
-    output = ERB.new( template, trim_mode: "%<>" )
-
-    # Run the report template and log result with no log level heading
-    @loginator.log( output.result(binding()), verbosity, LogLabels::NONE )
-  end
   
 end

data/lib/ceedling/plugins/report_tests_stdout_plugin.rb

@@ -0,0 +1,88 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/plugins/plugin'
+require 'ceedling/defaults'
+
+# Base class for stdout test-results reporting plugins.
+# Subclasses need only override the private `load_template` method to supply
+# a different ERB template string. All hook logic lives here.
+class ReportTestsStdoutPlugin < Plugin
+
+  # `Plugin` setup()
+  def setup
+    @result_list = []
+    @mutex = Mutex.new
+
+    # References
+    @configurator        = @ceedling[:configurator]
+    @plugin_reportinator = @ceedling[:plugin_reportinator]
+    @file_path_utils     = @ceedling[:file_path_utils]
+    @rake_invocation_tracker   = @ceedling[:rake_invocation_tracker]
+
+    # Set the report template (subclass supplies via load_template)
+    @plugin_reportinator.register_test_results_template( load_template() )
+  end
+
+  # `Plugin` build step hook -- collect result file paths after each test fixture execution
+  def post_test_fixture_execute(arg_hash)
+    result_file = arg_hash[:result_file]
+
+    # Thread-safe manipulation since test fixtures can be run in child processes
+    # spawned within multiple test execution threads.
+    @mutex.synchronize do
+      if (result_file =~ /#{PROJECT_TEST_RESULTS_PATH}/) && !@result_list.include?(result_file)
+        @result_list << arg_hash[:result_file]
+      end
+    end
+  end
+
+  # `Plugin` build step hook -- render a report immediately upon build completion (that invoked tests)
+  def post_build(_timestamp_s)
+    # Ensure a test task was invoked as part of the build
+    return if not @rake_invocation_tracker.test_task_invoked?
+
+    return if @configurator.plugins_display_raw_test_results
+
+    results = @plugin_reportinator.assemble_test_results( @result_list )
+    hash = { :context => TEST_SYM, :results => results }
+    verbosity = (results[:counts][:failed] > 0) ? Verbosity::ERRORS : Verbosity::NORMAL
+
+    # Print unit test suite results
+    @plugin_reportinator.run_test_results_report( hash, verbosity )
+  end
+
+  # `Plugin` build step hook -- render a test results report on demand using results from a previous build
+  def summary
+    return if @configurator.plugins_display_raw_test_results
+
+    # Build up the list of passing results from all tests
+    result_list = @file_path_utils.form_pass_results_filelist(
+      PROJECT_TEST_RESULTS_PATH,
+      COLLECTION_ALL_TESTS
+    )
+
+    hash = {
+      :context => TEST_SYM,
+      # Collect all existing test results (success or failing) in the filesystem,
+      # limited to our test collection
+      :results => @plugin_reportinator.assemble_test_results( result_list, {:boom => false} )
+    }
+
+    @plugin_reportinator.run_test_results_report( hash )
+  end
+
+  private
+
+  # Returns the ERB template string used for test results reports.
+  # Default: reads assets/template.erb from the plugin's own root path.
+  # Override in a subclass to supply a different template string.
+  def load_template
+    return @ceedling[:file_wrapper].read( File.join( @plugin_root_path, 'assets/template.erb' ) )
+  end
+
+end

data/lib/ceedling/preprocess/README.md

@@ -0,0 +1,184 @@
+# Preprocessing in Ceedling
+
+## Summary
+
+Ceedling’s preprocessing system provides the basis for C code extraction and transformation capabilities for test builds. It operates in two primary modes utilitizing GCC’s preprpocessor output:
+
+1. **Includes Extraction** — Extracts and categorizes `#include` directives (user vs. system headers).
+2. **Code Expansion** — Fully expands macros and preprocessor directives to generate simplified C files (both test and source files). Reconstructing C code from this expansion is dependent on (1).
+
+Ceedling’s preprocessing system runs GCC’s preprocessor in multiple modes to extract includes and expand C code. It employs cacheing and conditional strategies to minimize preprocessing tool execution across test runs.
+
+---
+
+## Includes Extraction
+
+### Overview
+
+Includes extraction identifies all `#include` directives in a C file and categorizes them as either user includes (`#include "header.h"`) or system includes (`#include <header.h>`). This process can operate independently of code expansion for use in Ceedling build steps. The same process is relied upon to provide the include directives needed for reconstructing expanded C files.
+
+### Three-Way Intersection Technique
+
+Ceedling uses a three-way intersection approach to accurately extract and categorize includes:
+
+#### 1. Bare Includes Extraction
+
+The preprocessor runs in **dependencies mode** (`-MM -MG -MP`) with:
+- All project symbols defined.
+- **Only** the Ceedling vendor path in search paths (no project paths). This ensures no header files are opened apart from Ceedling’s internal _partials.h_.
+
+This configuration causes the preprocessor to:
+- Conditionally evaluate all `#ifdef`, `#ifndef`, and `#if defined()` directives.
+- Assume any unresolved includes will be generated (via `-MG` flag). This encompasses mocks but also avoids any include guard complications since no headers are actually opened.
+- Extract all includes that would be processed given the current symbol definitions.
+
+**Result:** A complete list of all includes that would be processed but without distinguishing user vs. system includes.
+
+#### 2. User Includes Extraction
+
+The preprocessor runs in **directives-only mode** (`-E -dD -fdirectives-only`) with full symbols and search paths, which:
+- Outputs only preprocessor directives and line markers.
+- Preserves the original `#include` statements.
+- Generates line markers showing file entry/exit points.
+
+Ceedling parses the line markers to identify:
+- All user includes via tracing which headers were entered (flag `1` in line markers).
+- Which files are user headers (_absence_ of flag `3` in line markers).
+
+**Result:** A list of all user includes associated with the processed file. Note that because of nesting includes and include guards this list cannot be used to determine the top-level (i.e. depth 0) includes in the way bare includes extraction can.
+
+**Note:** The directives-only mode requires that all files referenced in `#include` directives exist in search paths. Ceedling addresses this need by generating blank “stand-in” files for mocks and partials to allow the preprocessor to succeed. These files are replaced by the actual generated content in later build steps.
+
+#### 3. System Includes Extraction
+
+Using the same directives-only preprocessor output as used for user includes, Ceedling identifies:
+- Includes marked with the system header flag (`3`).
+- Includes limited to a practical depth (typically 5 levels) to avoid excessive noise from deeply nested internal system includes.
+
+**Result:** A list of system includes associated with the processed file. Note that because of nesting includes and include guards this list cannot be used to determine the top-level (i.e. depth 0) includes in the way bare includes extraction can.
+
+#### 4. Intersection and Reconciliation
+
+The three lists are reconciled using `Includes.reconcile()`:
+- **Bare includes** provide the authoritative list of the top-level (i.e. depth 0) includes but with no distinction of user and system includes.
+- **User includes** from line markers distinguishes user headers.
+- **System includes** from line markers distinguishes system headers.
+- Any include appearing in bare includes but not in user/system lists is ignored.
+
+The final list is sanitized to:
+- Remove self-references (a file referencing itself).
+- Remove any includes that have been mocked (e.g., `mock_header.h` supersedes `header.h`).
+- Sort such that system includes are first in the resulting list (a C best practice).
+
+### Benefits of This Approach
+
+- **Conditional accuracy:** Respects `#ifdef` and other conditional compilation directives.
+- **No include guard issues:** Never opens actual header files during bare includes extraction, ensuring a list of top-level (i.e. depth 0) include directives.
+- **Handles generated files:** Assumes missing files will be generated (mocks, etc.).
+- **Proper categorization:** Distinguishes user vs. system includes for correct build ordering.
+
+---
+
+## Code Expansion
+
+### Overview
+
+Code expansion transforms C source and header files by fully expanding all preprocessor directives, macros, and conditional compilation statements. This produces simplified files suitable for extracting test case names, C function definitions (for Partials), and more as needed by Ceedling’s advanced features.
+
+Code expansion via the preprocessor is “too good.” It expands all include directives, macros, etc. These details are needed by various build steps and text extraction. As such, after code expansion, Ceedling reconstructs the expanded code file to inject include directives and certain macros.
+
+### Full Preprocessing Mode
+
+The preprocessor runs in **full expansion mode** (`-E`) with:
+- All project symbols defined.
+- Complete search paths (project, vendor, system).
+- All header files opened and processed.
+
+This generates output where:
+- All macros are expanded to their final values.
+- All `#ifdef`/`#ifndef` blocks are resolved.
+- All `#include` directives are replaced with file contents.
+- Line markers indicate the source of each line.
+
+### File Reconstruction
+
+Expanded files are reconstructed to maintain a usable structure:
+
+#### 1. Header Reconstruction
+
+For each expanded header file:
+1. Extract the original includes list (using the includes extraction process discussed in preceding sections).
+2. Create a new file with:
+   - Original `#include` directives at the top (user and system headers).
+   - Fully expanded macros, function declarations, and function definitions.
+
+#### 2. Source File Reconstruction
+
+For each expanded source file:
+1. Extract the original includes list.
+2. Create a new file with:
+   - Original `#include` directives at the top.
+   - Fully expanded code with all macros resolved.
+   - All conditional compilation resolved.
+
+### Directives-Only Output Usage
+
+The directives-only preprocessor output serves multiple purposes in reconstruction:
+
+1. **Include:** Used by includes extraction to inject includes into reconstructed files.
+2. **Macro Preservation (Optional):** Can extract `#define` directives for inclusion in reconstructed C files. Key “marker” macros like `TEST_SOURCE_FILE()` must be preserved for text scanning steps that provide the details of the marker needed in later build steps.
+
+### Dependency on Includes Extraction
+
+Code expansion **requires** includes extraction because:
+- Reconstructed files need original `#include` directives at the top, but these are expanded inline during preprocessing.
+- Mock generation requires knowing which mocks a test author referenced in a test file.
+
+Without accurate includes extraction, reconstructed files would lack proper header dependencies and fail to compile or provide necessary build details to later build steps.
+
+---
+
+## Efficiencies and Caching
+
+### Shared Directives-Only Output
+
+**Problem:** Multiple preprocessing steps need the same directives-only preprocessor output.
+
+**Solution:** Generate the directives-only output once and pass its filepath to all consumers:
+
+**Benefits:**
+- Reduces preprocessor invocations from N to 1 per file.
+- Eliminates redundant file I/O.
+- Ensures consistency across extraction steps.
+
+### Shared Directives-Only Output
+
+**Problem:** Preprocessing is expensive and often repeated unnecessarily.
+
+**Solution:** Cache extracted includes lists as YAML files and rely on file timestamps to determine if cached includes are up to date and can be used in place of running the preprocessor multiple times.
+
+**Benefits:**
+- Skips expensive preprocessing on unchanged files.
+- Preserves full includes information across runs.
+
+---
+
+## Fallback
+
+If executing the preprocessor fails for any reason — a mode not supported by the toolchain available in the environment or some oddball quirk of symbols and paths — automatic fallback options are executed.
+
+In fallback modes, in place of relying on the preprocessor, Ceedling relies on simple text scanning of the original file. Of course, this cannot be resilient to conditional compilation, etc. that preprocessing handles. But, this can often be good enough or bring a test build to a sufficient point of completion to allow a test author to more easily determine the failure scenario at hand.
+
+---
+
+## Implementation Details
+
+**Key Classes**
+- `Preprocessinator` - Main preprocessing orchestrator.
+- `PreprocessinatorIncludesHandler` - Manages includes extraction workflows.
+- `PreprocessinatorLineMarkerIncludesExtractor` - Parses line markers from directives-only output.
+- `PreprocessinatorBareIncludesExtractor` - Parses make-style dependency output.
+- `PreprocessinatorReconstructor` — Recreates C code files from fully expanded output, include lists, and optionally preserved directives.
+- `Include` objects and derivatives — Encapsulates include directive details.
+- `Includes` - Various utilities for processing includes lists.
+- `IncludeFactory` - Manufactures `UserInclude` and `SystemInclude` objects.