ceedling 1.1.9 → 1.2.0

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

@@ -89,10 +89,34 @@
     </div>
     <div data-md-component="announce">
       
+        <aside class="md-banner">
+          <div class="md-banner__inner md-grid md-typeset">
+            
+            
+  
+
+          </div>
+          
+        </aside>
+      
     </div>
     
       <div data-md-color-scheme="default" data-md-component="outdated" hidden>
         
+          <aside class="md-banner md-banner--warning">
+            <div class="md-banner__inner md-grid md-typeset">
+              
+  
+    You are not viewing the latest version.
+    <a href="../../..">
+      <strong>Click here to go to latest.</strong>
+    </a>
+  
+
+            </div>
+            <script>var el=document.querySelector("[data-md-component=outdated]"),base=new URL("../.."),outdated=__md_get("__outdated",sessionStorage,base);!0===outdated&&el&&(el.hidden=!1)</script>
+          </aside>
+        
       </div>
     
     
@@ -332,7 +356,7 @@
     
     
       <li class="md-tabs__item">
-        <a href="../../project/release-history.html" class="md-tabs__link">
+        <a href="../../project/index.html" class="md-tabs__link">
           
   
   
@@ -641,6 +665,8 @@
         
       
         
+      
+        
       
         
       
@@ -788,6 +814,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../getting-started/builds.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Builds
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -814,7 +868,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_5" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_6" >
         
           
           <div class="md-nav__link md-nav__container">
@@ -836,14 +890,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_3_5" id="__nav_3_5_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_3_6" id="__nav_3_6_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_5_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3_5">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_6_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3_6">
             <span class="md-nav__icon md-icon"></span>
             
   
@@ -2412,6 +2466,8 @@
         
       
         
+      
+        
       
         
       
@@ -2999,6 +3055,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">
@@ -3319,6 +3403,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#custom_args" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :custom_args
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -3513,6 +3608,95 @@
       </ul>
     </nav>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#jacoco-xml-reports" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        JaCoCo XML reports
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="JaCoCo XML reports">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#jacoco_pretty" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :jacoco_pretty
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#jacoco_artifact_filename" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :jacoco_artifact_filename
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#lcov-reports" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        LCOV reports
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="LCOV reports">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#lcov_comment" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :lcov_comment
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#lcov_test_name" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :lcov_test_name
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#lcov_artifact_filename" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :lcov_artifact_filename
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -3679,8 +3863,64 @@
   
   
     <li class="md-nav__item">
-      <a href="../bullseye.html" class="md-nav__link">
+      <a href="../sanitize.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Sanitize (ASan, UBSan & Leaks)
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    
+    
+      
+        
+          
+        
+      
+        
+      
+    
+    
+    
+      
+      
+        
+          
+          
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--section md-nav__item--nested">
+      
         
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6_13" >
+        
+          
+          <div class="md-nav__link md-nav__container">
+            <a href="../bullseye/index.html" class="md-nav__link ">
+              
   
   
   <span class="md-ellipsis">
@@ -3690,6 +3930,50 @@
   
 
     
+  </span>
+  
+  
+
+            </a>
+            
+              
+              <label class="md-nav__link " for="__nav_6_13" id="__nav_6_13_label" tabindex="">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+            
+          </div>
+        
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_6_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_6_13">
+            <span class="md-nav__icon md-icon"></span>
+            
+  
+    Bullseye (Coverage)
+  
+
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../bullseye/licensing.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Licensing
+  
+
+    
   </span>
   
   
@@ -3700,6 +3984,14 @@
 
               
             
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
               
                 
   
@@ -4169,6 +4461,12 @@
     
       
         
+          
+        
+      
+        
+      
+        
       
         
       
@@ -4188,8 +4486,9 @@
         <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" >
         
           
-          <label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex="0">
-            
+          <div class="md-nav__link md-nav__container">
+            <a href="../../project/index.html" class="md-nav__link ">
+              
   
   
   <span class="md-ellipsis">
@@ -4203,8 +4502,14 @@
   
   
 
-            <span class="md-nav__icon md-icon"></span>
-          </label>
+            </a>
+            
+              
+              <label class="md-nav__link " for="__nav_8" id="__nav_8_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+            
+          </div>
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_8">
@@ -4218,6 +4523,8 @@
           <ul class="md-nav__list" data-md-scrollfix>
             
               
+            
+              
                 
   
   
@@ -4251,6 +4558,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../project/sbom.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Software Bill of Materials
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../../project/upgrade.html" class="md-nav__link">
         
@@ -4322,6 +4657,8 @@
       
         
       
+        
+      
         
       
     
@@ -4412,6 +4749,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../development/releases.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Branching & Releases
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -4438,7 +4803,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_4" >
         
           
           <div class="md-nav__link md-nav__container">
@@ -4460,14 +4825,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_10_3" id="__nav_10_3_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_10_4" id="__nav_10_4_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_10_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_10_3">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_10_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_10_4">
             <span class="md-nav__icon md-icon"></span>
             
   
@@ -4641,6 +5006,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">
@@ -4961,6 +5354,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#custom_args" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :custom_args
+      
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -5155,6 +5559,95 @@
       </ul>
     </nav>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#jacoco-xml-reports" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        JaCoCo XML reports
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="JaCoCo XML reports">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#jacoco_pretty" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :jacoco_pretty
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#jacoco_artifact_filename" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :jacoco_artifact_filename
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#lcov-reports" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        LCOV reports
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="LCOV reports">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#lcov_comment" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :lcov_comment
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#lcov_test_name" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :lcov_test_name
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#lcov_artifact_filename" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        :lcov_artifact_filename
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -5291,15 +5784,21 @@ and then break out report-specific options.</p>
 <h3 id="gcovr-configuration-file">Gcovr configuration file</h3>
 <div class="admonition warning">
 <p class="admonition-title">Using a gcovr configuration file</p>
-<p>When <code>:config_file</code> is set, Ceedling passes only <code>--root</code> (<code>:report_root</code>) 
-and <code>--config</code> (<code>:config_file</code>) to <code>gcovr</code> at the command line from your
-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>
+<p>When <code>:config_file</code> is set, Ceedling passes only <code>--root</code> (<code>:report_root</code>), 
+<code>--config</code> (<code>:config_file</code>), and any <code>:custom_args:</code> to <code>gcovr</code> at the command 
+line from your plugin configuration. This prevents overriding config file 
+settings with other CLI arguments derived from plugin configuration. You must 
+provide any settings that would have been provided by the Gcov plugin, either 
+in the config file itself or via <code>:custom_args:</code>.</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 +5811,94 @@ 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, <code>gcovr</code> excludes three categories of <code>.c</code> files from coverage
+results, on top of whatever <code>gcov</code> itself already limits reporting to (the
+sources your test build actually compiled). These defaults exist because a
+coverage percentage is only meaningful over the production code you're
+actually trying to cover — test code, test support code, and every file
+Ceedling itself generates as part of a build all skew that number if left in.</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>
+<p>A project's <code>:extension</code> ↳ <code>:source</code> can list more than one source
+extension; every configured extension is joined into this same
+alternation. Given <code>:extension</code> ↳ <code>:source</code> ⇒ <code>['.c', '.C']</code>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>.*(?:^|/)test/(?:.*/)?test_[^/]+(?:\.c|\.C)$
+</code></pre></div>
+</li>
+<li>
+<p><strong>Test support files</strong> — any file matching one of your configured source
+    extensions 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-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>.*(?:^|/)test/support/.+(?:\.c)$
+</code></pre></div>
+<p>Again, every configured <code>:extension</code> ↳ <code>:source</code> value is included in
+the alternation. Given <code>:extension</code> ↳ <code>:source</code> ⇒ <code>['.c', '.C']</code>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>.*(?:^|/)test/support/.+(?:\.c|\.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. Unlike the two patterns above, this one 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-5-1" name="__codelineno-5-1" href="#__codelineno-5-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 — you don't need to
+(and normally shouldn't) duplicate them yourself.</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 Ceedling always passes its
+own three patterns ahead of anything you configure there. Neither
+<a href="#report_include"><code>:report_include</code></a> nor <a href="#custom_args"><code>:custom_args</code></a> helps
+either: <code>:report_include</code> narrows which files are considered at all, but an
+exclude pattern still wins over it for any file matching both; <code>:custom_args</code>
+lets you pass additional raw <code>gcovr</code> flags, but a raw <code>--filter</code>/<code>--exclude</code>
+of your own is just as additive as <code>:report_exclude</code> — there's no <code>gcovr</code>
+flag that removes or replaces an exclusion already given, only ones that add
+more.</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-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="c1">; gcovr.cfg — omits the test-file exclude pattern so test files remain in</span>
+<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="c1">; coverage results, while still keeping generated/vendored build output out.</span>
+<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-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-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="nt">:gcov</span><span class="p">:</span>
+<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="w">  </span><span class="nt">:gcovr</span><span class="p">:</span>
+<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-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
@@ -5319,7 +5906,8 @@ you need to override. You do not need to include all these options in your
 Gcov plugin configuration.</p>
 <h3 id="report_root"><code>:report_root</code></h3>
 <p>The root directory of your source files. File names are reported relative to
-this root. <code>:report_root</code> is also the default <code>:report_include</code>.</p>
+this root. Ceedling does not derive a default <code>:report_include</code> from it —
+<code>gcovr</code> itself only searches beneath <code>--root</code> when no <code>--filter</code> is given.</p>
 <div class="admonition warning">
 <p class="admonition-title"><code>gcovr</code> accepts only one reporting root path</p>
 <p><code>gcovr</code> accepts only a single path for <code>:report_root</code>. In unusual project
@@ -5332,14 +5920,18 @@ reporting (see <code>:report_exclude</code> and <code>:exclude_directories</code
 <h3 id="config_file"><code>:config_file</code></h3>
 <p>Load the specified <code>gcovr</code> configuration file. (<code>gcovr --config</code>)</p>
 <p>When <code>:config_file</code> is set, Ceedling passes only <code>--root</code> and <code>--config</code> to
-<code>gcovr</code> and defers all other configuration to the file. This prevents
+<code>gcovr</code> and defers (nearly) all other configuration to the file. This prevents
 Ceedling from overriding config file values with its CLI arguments.
 <code>:report_root</code> is still applied because Ceedling may invoke <code>gcovr</code> from a
-different working directory than your project root.</p>
+different working directory than your project root, and <code>:custom_args:</code> is
+still applied too — the one way to pass Gcovr flags of your own alongside a
+config file (see <code>:custom_args</code> below).</p>
 <p>To preserve the plugin's base filtering behavior, include exclusion patterns
 matching your project layout in the config file itself — see
 <a href="#gcovr-configuration-file">Gcovr configuration file</a> above.</p>
-<p><strong>Default:</strong> <code>gcovr.cfg</code> in the <code>:report_root</code> directory, if that file exists.</p>
+<p><strong>Default:</strong> unset — Ceedling does not look for or autodetect a config file
+on disk; <code>gcovr</code> itself is only ever told to load one when <code>:config_file</code> is
+explicitly set.</p>
 <hr />
 <h3 id="fail_under_line"><code>:fail_under_line</code></h3>
 <p>Exit with a status of 2 if the total line coverage is less than this minimum
@@ -5392,9 +5984,8 @@ deprecated as of 7.0, though still functional); <code>gcovr --branches</code> be
 <hr />
 <h3 id="sort_uncovered"><code>:sort_uncovered</code></h3>
 <p>Sort entries by increasing number of uncovered lines. Applies to text and HTML
-reports. Uses <code>gcovr --sort uncovered-number</code> on <code>gcovr</code> 7.0+
-(<code>--sort-uncovered</code> is deprecated as of 7.0, though still functional);
-<code>gcovr --sort-uncovered</code> below it.</p>
+reports. Uses <code>gcovr --sort uncovered-number</code> on <code>gcovr</code> 7.0+ (<code>--sort-uncovered</code>
+is deprecated as of 7.0, though still functional); <code>gcovr --sort-uncovered</code> below it.</p>
 <hr />
 <h3 id="sort_percentage"><code>:sort_percentage</code></h3>
 <p>Sort entries by increasing percentage of uncovered lines. Applies to text and
@@ -5409,11 +6000,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 (e.g. to include test files in
+results). 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>
@@ -5472,6 +6077,27 @@ error. (<code>gcovr --gcov-ignore-parse-errors</code>)</p>
 <hr />
 <h3 id="threads"><code>:threads</code></h3>
 <p>Set the number of threads <code>gcovr</code> uses in parallel. (<code>gcovr -j</code>)</p>
+<hr />
+<h3 id="custom_args"><code>:custom_args</code></h3>
+<p>Optional list of one or more raw command line arguments to pass to <code>gcovr</code>.
+Useful as an escape hatch for any <code>gcovr</code> flag Ceedling has no named option
+for (e.g. limiting <code>gcovr</code>'s search root).</p>
+<p>Unlike every other option above, these arguments are still applied even when
+<code>:config_file</code> is set — the one way to pass <code>gcovr</code> flags of your own
+alongside a config file.</p>
+<p>This does not, on its own, let you override
+<a href="#results-filtering">Results filtering</a>'s automatic exclusion defaults when
+<code>:config_file</code> is unset — a raw <code>--filter</code>/<code>--exclude</code> passed here is just as
+additive as <a href="#report_exclude"><code>:report_exclude</code></a>; see
+<a href="#overriding-the-defaults">Overriding the defaults</a> for the one option that
+actually does.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="nt">:gcov</span><span class="p">:</span>
+<a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a><span class="w">  </span><span class="nt">:gcovr</span><span class="p">:</span>
+<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="w">    </span><span class="nt">:custom_args</span><span class="p">:</span>
+<a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">&lt;argument&gt;</span>
+<a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
+</code></pre></div>
+<p><strong>Default:</strong> <code>[]</code></p>
 <h2 id="html-reports">HTML reports</h2>
 <p>Generation of HTML reports may be modified with the following configuration items.</p>
 <h3 id="html_artifact_filename"><code>:html_artifact_filename</code></h3>
@@ -5522,11 +6148,40 @@ links. (<code>gcovr --html-absolute-paths</code>)</p>
 <hr />
 <h3 id="json_artifact_filename"><code>:json_artifact_filename</code></h3>
 <p>Override the default JSON report output filename.</p>
+<h2 id="jacoco-xml-reports">JaCoCo XML reports</h2>
+<p>A JaCoCo XML report is a coverage format that Java-oriented tools and IDEs such as
+CLion import. Enable it with <code>JaCoCo</code> in <code>:gcov</code> ↳ <code>:reports</code>.</p>
+<p><strong>Requires:</strong> <code>gcovr</code> 7.0 or higher. An older <code>gcovr</code> stops the build.</p>
+<p>Generation of JaCoCo XML reports may be modified with the following configuration items.</p>
+<h3 id="jacoco_pretty"><code>:jacoco_pretty</code></h3>
+<p>Pretty-print the JaCoCo XML report. (<code>gcovr --jacoco-pretty</code>)</p>
+<p><strong>Default:</strong> <code>false</code></p>
+<hr />
+<h3 id="jacoco_artifact_filename"><code>:jacoco_artifact_filename</code></h3>
+<p>Override the default JaCoCo XML report output filename.</p>
+<p><strong>Default:</strong> <code>GcovCoverageJaCoCo.xml</code></p>
+<h2 id="lcov-reports">LCOV reports</h2>
+<p>An LCOV info file is the coverage format of the <code>lcov</code> toolset that many coverage
+viewers and services read. Enable it with <code>lcov</code> in <code>:gcov</code> ↳ <code>:reports</code>.
+ReportGenerator also writes <code>lcov</code>, each utility into its own artifacts folder.</p>
+<p><strong>Requires:</strong> <code>gcovr</code> 7.0 or higher. An older <code>gcovr</code> stops the build when it is the
+only enabled utility. With ReportGenerator also enabled, an older <code>gcovr</code> logs a
+warning and leaves <code>lcov</code> to ReportGenerator.</p>
+<p>Generation of LCOV reports may be modified with the following configuration items.</p>
+<h3 id="lcov_comment"><code>:lcov_comment</code></h3>
+<p>Set a comment in the LCOV report. (<code>gcovr --lcov-comment</code>)</p>
+<hr />
+<h3 id="lcov_test_name"><code>:lcov_test_name</code></h3>
+<p>Set the test name recorded in the LCOV report. (<code>gcovr --lcov-test-name</code>)</p>
+<hr />
+<h3 id="lcov_artifact_filename"><code>:lcov_artifact_filename</code></h3>
+<p>Override the default LCOV report output filename.</p>
+<p><strong>Default:</strong> <code>GcovCoverage.lcov</code></p>
 <h2 id="text-reports">Text reports</h2>
-<p>Generation of text reports may be modified with the following configuration items.
-Text reports may be printed to the console or output to a file.</p>
+<p>Generation of text reports may be modified with the following configuration items.</p>
 <h3 id="text_artifact_filename"><code>:text_artifact_filename</code></h3>
 <p>Override the default text report output filename.</p>
+<p><strong>Default:</strong> <code>coverage.txt</code></p>
 <p><br/><br/></p>