ceedling 1.1.9 → 1.1.10

data/lib/ceedling/objects.yml

@@ -383,6 +383,8 @@ partializer:
     - file_finder
     - c_extractor
     - file_path_utils
+    - preprocessinator_reconstructor
+    - file_wrapper
     - reportinator
     - loginator
 

data/lib/ceedling/partials/partializer.rb

@@ -14,12 +14,18 @@ require 'ceedling/c_extractor/c_extractor'
 require 'ceedling/c_extractor/c_extractor_constants'
 require 'ceedling/c_extractor/c_extractor_types'
 require 'ceedling/constants'
+require 'ceedling/encodinator'
 
 class Partializer
 
+  # Enough of a header to reach its include guard. The guard pair sits at the top of a header by
+  # construction, so a bounded read beats loading a large file to find it.
+  GUARD_SCAN_BYTES = 2048
+
   include Partials
 
-  constructor :partializer_helper, :file_finder, :c_extractor, :file_path_utils, :reportinator, :loginator
+  constructor :partializer_helper, :file_finder, :c_extractor, :file_path_utils,
+              :preprocessinator_reconstructor, :file_wrapper, :reportinator, :loginator
 
   def setup()
     # Alias
@@ -82,120 +88,89 @@ class Partializer
     return configs
   end
 
+  # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
+  # Includes for the generated implementation header. This module's own header is replaced by
+  # the shared types header at its original list position; every other partialized module's
+  # include is dropped.
+  #
   # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
   def remap_implementation_header_includes(name:, includes:, partials:, types_header: nil, test: nil)
-    _includes = includes.clone()
-
-    # This module's own header include is spliced out in favor of the shared types
-    # header at its exact original list position -- see #splice_in_replacement.
-    _includes = splice_in_replacement(includes: _includes, name: name, replacement: types_header)
-
-    # Remove includes for every other partialized module (this module's own name was
-    # already handled above)
-    _includes = remove_matching_includes(
-      includes: _includes,
-      modules: (partials.keys - [name])
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: types_header,
+      others:      :drop,
+      noun:        'Header includes to inject for testable Partial',
+      test:        test
     )
-
-    # Remove any duplicates
-    Includes.sanitize!(_includes)
-
-    @loginator.log_list(
-      _includes,
-      "Header includes to inject for testable Partial #{test}::#{name}:",
-      Verbosity::OBNOXIOUS
-    ) if test
-
-    return _includes
   end
 
+  # Includes for the generated mockable interface header. Same treatment as the implementation
+  # header: both files carry the shared types header, which is how a module tested and mocked
+  # in one test file still gets exactly one definition of each of its types.
+  #
   # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
-  def remap_implementation_source_includes(name:, includes:, partials:, test: nil)
-    _includes = includes.clone()
-
-    # Splice the implementation header in at this module's own header's original list
-    # position, same rationale as #splice_in_replacement -- the generated
-    # implementation header carries the shared types header in correctly-ordered
-    # position internally, but that alone doesn't help if THIS file's own separate
-    # include list still reaches an unrelated header that transitively re-includes the
-    # real module header before the implementation header (and everything it carries)
-    # is ever reached. Appending it at the very end (after this file's own copy of every
-    # other real include) would put it after exactly that kind of transitive
-    # re-inclusion instead of before it.
-    _includes = splice_in_replacement(
-      includes: _includes,
-      name: name,
-      replacement: @file_path_utils.form_partial_implementation_header_filename(name)
+  def remap_interface_header_includes(name:, includes:, partials:, types_header: nil, test: nil)
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: types_header,
+      others:      :drop,
+      noun:        'Header includes to inject for mockable Partial',
+      test:        test
     )
+  end
 
-    mockable_modules = []
-
-    partials.each do |_module, config|
-      # Remap mockable interface headers that will be injected into generated partial implementation
-      #
-      # Any real (non-nil) mock mode means this module has a generated mock interface header
-      # to redirect to -- PUBLIC/PRIVATE alone once covered every mode that existed, but DEDUCT
-      # (MOCK_PARTIAL_ALL_MODULE) and ACCUMULATE (MOCK_PARTIAL_MODULE) were added later without
-      # updating this check, so a module mocked via either of those was silently never
-      # redirected: its real header (and any static inline/static function bodies in it) stayed
-      # #include'd verbatim, compiling straight past the mock instead of being replaced by it.
-      if includes.any? { |include| include.filename.ext().downcase() == _module.downcase() }
-        if !config.mocks.type.nil?
-          # Insert mockable interface header from remapping of module name
-          _includes << UserInclude.new(
-            @file_path_utils.form_partial_interface_header_filename(_module)
-          )
-          # Remember the module for later removal of original header
-          mockable_modules << _module
-        end
-      end
-    end
-
-    # Remove the original headers of any OTHER modules now remapped to mockable
-    # interfaces above -- this module's own original header was already handled by
-    # the splice above.
-    _includes = remove_matching_includes(
-      includes: _includes,
-      modules: mockable_modules
+  # Includes for the generated implementation source. This module's own header is replaced by
+  # the generated implementation header, which carries the types header internally. Another
+  # partialized module that is mocked is redirected to its generated interface header; one that
+  # is not mocked keeps its real header, which the generated code still needs.
+  #
+  # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
+  def remap_implementation_source_includes(name:, includes:, partials:, test: nil)
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: @file_path_utils.form_partial_implementation_header_filename(name),
+      others:      :mock_or_keep,
+      noun:        'Source includes to inject for testable Partial',
+      test:        test
     )
-
-    # Remove any duplicates
-    Includes.sanitize!(_includes)
-
-    @loginator.log_list(
-      _includes,
-      "Source includes to inject for testable Partial #{test}::#{name}:",
-      Verbosity::OBNOXIOUS
-    ) if test
-
-    return _includes
   end
 
+  # Includes the shared types header carries so the extracted types resolve wherever that file
+  # lands. Nothing replaces this module's own header here -- the types header cannot include
+  # itself -- so it is simply dropped. Another partialized module is redirected to its generated
+  # interface header when mocked and dropped otherwise: its real header would reintroduce the
+  # very content that module's own Partial replaced.
+  #
   # When `test:` is provided, logs the resulting includes at OBNOXIOUS.
-  def remap_interface_header_includes(name:, includes:, partials:, types_header: nil, test: nil)
-    _includes = includes.clone()
-
-    # This module's own header include is spliced out in favor of the shared types
-    # header at its exact original list position -- see #splice_in_replacement.
-    _includes = splice_in_replacement(includes: _includes, name: name, replacement: types_header)
-
-    # Remove includes for every other partialized module (this module's own name was
-    # already handled above)
-    _includes = remove_matching_includes(
-      includes: _includes,
-      modules: (partials.keys - [name])
+  def remap_types_header_includes(name:, includes:, partials:, test: nil)
+    _remap_includes(
+      name:        name,
+      includes:    includes,
+      partials:    partials,
+      replacement: nil,
+      others:      :mock_or_drop,
+      noun:        'Dependency includes to carry into the shared types header for Partial',
+      test:        test
     )
+  end
 
-    # Remove any duplicates
-    Includes.sanitize!(_includes)
-
-    @loginator.log_list(
-      _includes,
-      "Header includes to inject for mockable Partial #{test}::#{name}:",
-      Verbosity::OBNOXIOUS
-    ) if test
-
-    return _includes
+  # The include guard macro the module's real header defines, or nil when it has none.
+  #
+  # Read from the original header rather than from the reconstituted copy or from extracted
+  # macros. The reconstituted copy carries a synthetic guard that #sanitize strips, so neither is
+  # a dependable source. A nil return means the header guards itself some other way --
+  # `#pragma once` -- and offers no macro for a generated file to spoof.
+  def extract_module_include_guard(filepath)
+    return nil if filepath.nil?
+
+    text = @file_wrapper.read( filepath, GUARD_SCAN_BYTES ).clean_encoding
+    @preprocessinator_reconstructor.extract_include_guard( text )
   end
 
   # Extracts and combines C code contents from header and source files
@@ -457,6 +432,94 @@ class Partializer
     )
   end
 
+  # One body behind all four public remaps. Each differs only in what replaces this module's
+  # own header, what becomes of other partialized modules, and the noun it logs under -- the
+  # splice, the sanitize, and the logging are identical in every case.
+  #
+  # `others` selects the treatment of every OTHER partialized module in the same test file:
+  #   :drop         -- remove its include outright, with no substitute
+  #   :mock_or_keep -- redirect to its interface header when mocked, else leave its real header
+  #   :mock_or_drop -- redirect to its interface header when mocked, else drop it
+  def _remap_includes(name:, includes:, partials:, replacement:, others:, noun:, test: nil)
+    _includes = includes.clone()
+
+    # A nil replacement strips this module's own header and substitutes nothing.
+    _includes = splice_in_replacement( includes: _includes, name: name, replacement: replacement )
+
+    _includes =
+      case others
+      when :drop
+        remove_matching_includes( includes: _includes, modules: (partials.keys - [name]) )
+      when :mock_or_keep, :mock_or_drop
+        # The types header differs from the generated source in two ways at once, which is why
+        # both flags below read from one condition.
+        #
+        # It skips this module: the interface header includes the types header, so carrying the
+        # interface back in would fold that file's declarations into this one. The generated
+        # source needs the opposite -- a module tested and mocked in one test file keeps its
+        # public bodies in the implementation and the private declarations they call in the
+        # interface, so it needs both.
+        #
+        # And it drops an unmocked partialized dependency rather than keeping its real header,
+        # which would reintroduce content that module's own Partial replaced.
+        shared_types_header = ( others == :mock_or_drop )
+
+        _redirect_mocked_partials(
+          includes: _includes,
+          original: includes,
+          name: name,
+          partials: partials,
+          drop_unmocked: shared_types_header,
+          skip_self: shared_types_header
+        )
+      else
+        PartializerRuntime.raise_on_option( others )
+      end
+
+    # Remove any duplicates
+    Includes.sanitize!(_includes)
+
+    @loginator.log_list(
+      _includes,
+      "#{noun} #{test}::#{name}:",
+      Verbosity::OBNOXIOUS
+    ) if test
+
+    return _includes
+  end
+
+  # Appends the generated interface header for each mocked partialized module the original list
+  # named, then removes the real headers those replaced. `skip_self` decides whether the module
+  # being generated counts as one of them, which it does everywhere except the types header --
+  # see the call site.
+  #
+  # Mutates `includes`, which always arrives fresh from splice_in_replacement.
+  #
+  # Any real (non-nil) mock mode counts. PUBLIC/PRIVATE alone once covered every mode that
+  # existed, but DEDUCT (MOCK_PARTIAL_ALL_MODULE) and ACCUMULATE (MOCK_PARTIAL_MODULE) were
+  # added later without updating the check, so a module mocked via either was silently never
+  # redirected: its real header, and any static inline or static function bodies in it, stayed
+  # #include'd verbatim and compiled straight past the mock.
+  def _redirect_mocked_partials(includes:, original:, name:, partials:, drop_unmocked:, skip_self:)
+    retired = []
+
+    partials.each do |_module, config|
+      next if skip_self && _module == name
+      next unless original.any? { |include| include.filename.ext().downcase() == _module.downcase() }
+
+      if config.mocks.type.nil?
+        retired << _module if drop_unmocked
+      else
+        includes << UserInclude.new(
+          @file_path_utils.form_partial_interface_header_filename(_module)
+        )
+        retired << _module
+      end
+    end
+
+    remove_matching_includes( includes: includes, modules: retired )
+  end
+
   # Swaps `name`'s own header include for `replacement` at that same list position,
   # instead of stripping it out and appending the replacement at the very end.
   #

data/lib/ceedling/test_invoker/test_build_executor.rb

@@ -183,15 +183,27 @@ class TestBuildExecutor
 
       @partializer.sanitize( module_contents )
 
+      # The real header's guard is spoofed deliberately in every generated file, and the types
+      # header carries the dependencies its extracted types name.
+      module_include_guard = @partializer.extract_module_include_guard( config.header.filepath )
+      types_header_includes = @partializer.remap_types_header_includes(
+        name:     config.module,
+        includes: (config.source.includes + config.header.includes),
+        partials: testable.partials.configs,
+        test:     name
+      )
+
       # Generated once and shared by the implementation and interface headers below (via
       # their own includes lists), so a module tested and mocked in the same test file gets
       # exactly one C definition of each of its typedefs and aggregate types.
       types_header = @generator.generate_partial_types(
-        name:        config.module, # Module name, not test name -- two modules Partialed
-                                     # in the same test file must not collide on one
-                                     # shared types header filename
-        c_module:    module_contents,
-        output_path: testable.paths[:partials]
+        name:          config.module, # Module name, not test name -- two modules Partialed
+                                      # in the same test file must not collide on one
+                                      # shared types header filename
+        c_module:      module_contents,
+        output_path:   testable.paths[:partials],
+        includes:      types_header_includes,
+        include_guard: module_include_guard
       )
 
       implementation = @partializer.extract_implementation_functions(
@@ -235,7 +247,8 @@ class TestBuildExecutor
                                 test:     name
                               ),
         input_filepath:       config.source.filepath,
-        output_path:          testable.paths[:partials]
+        output_path:          testable.paths[:partials],
+        include_guard:        module_include_guard
       }
 
       unless implementation.nil?
@@ -256,7 +269,8 @@ class TestBuildExecutor
                                ),
         c_module:              module_contents,
         input_filepath:        config.header.filepath,
-        output_path:           testable.paths[:partials]
+        output_path:           testable.paths[:partials],
+        include_guard:         module_include_guard
       }
 
       unless interface.nil?

data/lib/version.rb

@@ -15,7 +15,7 @@
 module Ceedling
   module Version
     # Convenience constants for gem building, etc.
-    GEM = '1.1.9'
+    GEM = '1.1.10'
     TAG = GEM
 
     # If run as a script print Ceedling's version to $stdout

data/site-local/development/index.html

@@ -4080,6 +4080,13 @@ Please familiarize yourself with it before participating.</p>
 <p>Guidelines for contributing to this project — be it code, reviews,
 documentation, or issue reports.</p>
 </li>
+<li>
+<p><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 1 3 5v6c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V5zm0 6c1.4 0 2.8 1.1 2.8 2.5V11c.6 0 1.2.6 1.2 1.3v3.5c0 .6-.6 1.2-1.3 1.2H9.2c-.6 0-1.2-.6-1.2-1.3v-3.5c0-.6.6-1.2 1.2-1.2V9.5C9.2 8.1 10.6 7 12 7m0 1.2c-.8 0-1.5.5-1.5 1.3V11h3V9.5c0-.8-.7-1.3-1.5-1.3"/></svg></span> <strong><a href="https://github.com/ThrowTheSwitch/Ceedling?tab=security-ov-file">Security</a></strong></p>
+<hr />
+<p>See the <a href="https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/SECURITY.md">policy</a> for disclosure details and
+guidance on issues that vulnerability inspection tools may surface.
+Report a vulnerability through a <a href="https://github.com/ThrowTheSwitch/Ceedling/security/advisories/new">private advisory</a>.</p>
+</li>
 </ul>
 </div>
 <h2 id="projects">Projects</h2>

data/site-local/plugins/fff.html

@@ -4424,7 +4424,7 @@
 <h1 id="fake-function-framework-for-ceedling">Fake Function Framework for Ceedling</h1>
 <p>This plugin causes Ceedling to use the <a href="https://github.com/meekrosoft/fff">Fake Function Framework</a> for mocking instead of CMock, the default mocking framework packaged with Ceedling.</p>
 <p>Using <em>FFF</em> provides less strict mocking than CMock and affords more loosely-coupled tests.</p>
-<p>This Ceedling 1.x plugin incorporates a snapshot of <em>FFF</em> version 0.1.1 and supersedes a separately available <a href="https://github.com/ElectronVector/fake_function_framework">FFF Ceedling plugin project</a>. The built-in <em>FFF</em> plugin that now comes with Ceedling was derived from the ElectronVector project and is now maintained along with Ceedling and tracks its updates.</p>
+<p>This Ceedling 1.x plugin incorporates a snapshot of <em>FFF</em> version 1.1 and supersedes a separately available <a href="https://github.com/ElectronVector/fake_function_framework">FFF Ceedling plugin project</a>. The built-in <em>FFF</em> plugin that now comes with Ceedling was derived from the ElectronVector project and is now maintained along with Ceedling and tracks its updates.</p>
 <div class="admonition note">
 <p class="admonition-title">Special thanks to Matt Chernosky</p>
 <p><a href="http://www.electronvector.com">Matt Chernosky</a> originally developed this plugin 

data/site-local/plugins/gcov/gcovr.html

@@ -2999,6 +2999,34 @@
       </ul>
     </nav>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#results-filtering" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Results filtering
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Results filtering">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#overriding-the-defaults" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Overriding the defaults
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -4641,6 +4669,34 @@
       </ul>
     </nav>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#results-filtering" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Results filtering
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Results filtering">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#overriding-the-defaults" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Overriding the defaults
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -5297,9 +5353,14 @@ plugin configuration. This prevents overriding config file settings with
 CLI arguments. You must provide any settings that would have been provided 
 by the Gcov plugin.</p>
 </div>
-<p>To preserve filtering of test and build files from coverage results when
-using a Gcovr config file, you must provide explicit exclusion patterns matching 
-your project layout (example below).</p>
+<p>A Gcovr config file replaces Ceedling's own automatically generated exclusion
+patterns (see <a href="#results-filtering">Results filtering</a> below) entirely — it is
+the only way to override or remove one of those defaults, since the
+project-configuration <code>:report_exclude</code> option can only add further
+exclusions on top of them, never take one away. To preserve the same
+filtering of test and build files when switching to a Gcovr config file, you
+must provide equivalent explicit exclusion patterns matching your project
+layout yourself (example below).</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="c1">; You will need to revise these example exclude patterns to match your</span>
 <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="c1">; project directories and file naming as they cannot be automatically </span>
 <a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="c1">; provided to Gcovr when a Gcovr configuration file is in use.</span>
@@ -5312,6 +5373,84 @@ your project layout (example below).</p>
 <a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="c1">; Build path exlcude for all generated C files (runners, mocks, partials).</span>
 <a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="na">exclude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">.*build/.+\.c$</span>
 </code></pre></div>
+<h2 id="results-filtering">Results filtering</h2>
+<p>By default, this plugin configures <code>gcovr</code> to excludes three categories of 
+<code>.c</code> files from coverage results. These defaults exist because a
+coverage percentage is typically only meaningful over the production code 
+you're actually trying to exercise with test coverage. Test code, test 
+support code, and every file Ceedling itself generates as part of a build 
+will skew that number if left in coverage reporting.</p>
+<p>The list that follows details the filtering this plugin injects into 
+Gcovr coverage report generation. The examples are usable regular 
+expressions that mirror the defaults in use. The plugin dynamically 
+generates these regular expressions from your project configuration.
+When creating them youself, you will need to match your project 
+configuration settings with static strings.</p>
+<ol>
+<li>
+<p><strong>Test files</strong> — matched by <code>:test_file_prefix</code> within your configured
+    <code>:paths</code> ↳ <code>:test</code> directories.</p>
+<p>Given <code>:test_file_prefix</code> ⇒ <code>test_</code> and a <code>:paths</code> ↳ <code>:test</code> entry of
+<code>test/</code>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>.*test/.*/test_.+\.c$
+</code></pre></div>
+</li>
+<li>
+<p><strong>Test support files</strong> — any <code>.c</code> file within your configured <code>:paths</code> ↳
+    <code>:support</code> directories, regardless of name. Helpers, stubs, and fixtures
+    living there are no more production code than the test files themselves.</p>
+<p>Given a <code>:paths</code> ↳ <code>:support</code> entry of <code>test/support/</code>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>.*test/support/.+\.c$
+</code></pre></div>
+</li>
+<li>
+<p><strong>Generated and vendored files</strong> — any <code>.c</code> file anywhere below your
+    <code>:build_root</code>: generated mocks, test runners, Partials output, and the
+    vendored Unity/CMock/CException framework sources Ceedling copies in to
+    build against. This pattern always matches a literal <code>.c</code> extension
+    regardless of your project's own <code>:extension</code> ↳ <code>:source</code> setting, since
+    every file it catches is one Ceedling itself writes in plain C.</p>
+<p>Given <code>:build_root</code> ⇒ <code>build/</code>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>.*build/.+\.c$
+</code></pre></div>
+</li>
+</ol>
+<p>These patterns are generated automatically and combined with whatever you
+provide via <a href="#report_exclude"><code>:report_exclude</code></a> below.</p>
+<div class="admonition warning">
+<p class="admonition-title">Not applied when using a Gcovr configuration file</p>
+<p>These defaults are only generated when Ceedling builds <code>gcovr</code>'s command
+line directly. As covered in
+<a href="#gcovr-configuration-file">Gcovr configuration file</a> above, setting
+<code>:config_file</code> bypasses this entirely — none of the three patterns above
+are applied, and you must supply equivalent exclusions in the config file
+yourself.</p>
+</div>
+<h3 id="overriding-the-defaults">Overriding the defaults</h3>
+<p><a href="#report_exclude"><code>:report_exclude</code></a> can only add exclusions on top of the
+three defaults above — <code>gcovr --exclude</code> is a deny-list with no way to
+"un-exclude" a pattern already passed to it, and this plugin always passes its
+own three patterns ahead of anything you configure there. Setting
+<a href="#report_include"><code>:report_include</code></a> doesn't help either; it narrows which
+files are considered at all, but an exclude pattern still wins over it for
+any file matching both.</p>
+<p>The only way to actually remove or replace one of these defaults — for
+example, to include test files in coverage results so you can confirm a
+conditional test build compiled the branches you expect — is a
+<a href="#gcovr-configuration-file">Gcovr configuration file</a>. Setting <code>:config_file</code>
+stops Ceedling from generating any of the three patterns at all, handing you
+full control:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="c1">; gcovr.cfg — omits the test-file exclude pattern so test files remain in</span>
+<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="c1">; coverage results, while still keeping generated/vendored build output out.</span>
+<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="na">exclude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">.*build/.+\.c$</span>
+</code></pre></div>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="nt">:gcov</span><span class="p">:</span>
+<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w">  </span><span class="nt">:gcovr</span><span class="p">:</span>
+<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w">    </span><span class="nt">:config_file</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">gcovr.cfg</span>
+</code></pre></div>
+<p>Note that this isn't scoped per category. Once a default is dropped, any
+file it would have excluded is folded into the same combined report as your
+production code, not broken out separately.</p>
 <h2 id="plugin-configuration">Plugin configuration</h2>
 <p>The following options are exposed through your project configuration file, all
 beneath <code>:gcov</code> ↳ <code>:gcovr</code>. Only specify those you need or those whose defaults
@@ -5409,11 +5548,25 @@ is in addition to any other configured reports. (<code>gcovr --print-summary</co
 <h3 id="report_include"><code>:report_include</code></h3>
 <p>Keep only source files that match this filter. Filters are regular
 expressions. (<code>gcovr --filter</code>)</p>
+<p>This narrows which files are considered at all, but does not override
+<a href="#results-filtering">Results filtering</a>'s automatic exclusion defaults — a
+file excluded by one of those three default patterns stays excluded even if
+it also matches <code>:report_include</code>. See
+<a href="#overriding-the-defaults">Overriding the defaults</a> if you need to remove one
+of them.</p>
 <p><strong>Example:</strong> <code>"^src"</code></p>
 <hr />
 <h3 id="report_exclude"><code>:report_exclude</code></h3>
 <p>Exclude source files that match this filter. Filters are regular expressions.
 (<code>gcovr --exclude</code>)</p>
+<p>Ceedling automatically generates and prepends its own exclusion patterns for
+test files, test support files, and generated/vendored build files — see
+<a href="#results-filtering">Results filtering</a> above for exactly what these cover
+and why. Anything you provide here is combined with those defaults, not a
+replacement for them. This option can only add further exclusions, never
+remove or override one of the three defaults.
+See <a href="#overriding-the-defaults">Overriding the defaults</a> for how to do 
+that instead.</p>
 <p><strong>Example:</strong> <code>"^vendor.*|^build.*|^test.*|^lib.*"</code></p>
 <hr />
 <h3 id="gcov_filter"><code>:gcov_filter</code></h3>