ceedling 1.1.10 → 1.2.1

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

@@ -21,7 +21,7 @@
       
       
       <link rel="icon" href="../../assets/images/favicon.png">
-      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.7">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
     
     
       
@@ -29,10 +29,10 @@
       
     
     
-      <link rel="stylesheet" href="../../assets/stylesheets/main.ec1eaa64.min.css">
+      <link rel="stylesheet" href="../../assets/stylesheets/main.57a0d79d.min.css">
       
         
-        <link rel="stylesheet" href="../../assets/stylesheets/palette.ab4e12ef.min.css">
+        <link rel="stylesheet" href="../../assets/stylesheets/palette.fb2fffe2.min.css">
       
       
 
@@ -93,6 +93,16 @@
     
       <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 +342,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 +651,8 @@
         
       
         
+      
+        
       
         
       
@@ -788,6 +800,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 +854,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 +876,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 +2452,8 @@
         
       
         
+      
+        
       
         
       
@@ -3347,6 +3389,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>
@@ -3541,6 +3594,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">
@@ -3707,8 +3849,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">
@@ -3718,6 +3916,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>
   
   
@@ -3728,6 +3970,14 @@
 
               
             
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
               
                 
   
@@ -4197,6 +4447,12 @@
     
       
         
+          
+        
+      
+        
+      
+        
       
         
       
@@ -4216,8 +4472,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">
@@ -4231,8 +4488,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">
@@ -4246,6 +4509,8 @@
           <ul class="md-nav__list" data-md-scrollfix>
             
               
+            
+              
                 
   
   
@@ -4279,6 +4544,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">
         
@@ -4350,6 +4643,8 @@
       
         
       
+        
+      
         
       
     
@@ -4440,6 +4735,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../development/releases.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Branching & Releases
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -4466,7 +4789,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">
@@ -4488,14 +4811,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>
             
   
@@ -5017,6 +5340,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>
@@ -5211,6 +5545,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">
@@ -5347,11 +5770,12 @@ 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>A Gcovr config file replaces Ceedling's own automatically generated exclusion
 patterns (see <a href="#results-filtering">Results filtering</a> below) entirely — it is
@@ -5367,56 +5791,62 @@ layout yourself (example below).</p>
 <a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="c1">;</span>
 <a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="c1">; Note: Format is flat `key = value` lines with no `[section]` header.</span>
 <a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="c1">; Test path(s) exclusions for &#39;test_&#39; files with .c extensions. </span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="c1">; Test path(s) exclusions for 'test_' files with .c extensions. </span>
 <a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="na">exclude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">.*test.*/test_.+\.c$</span>
 <a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
 <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>
+<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$
+<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 <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><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-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>.*test/support/.+\.c$
+<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. 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>
+    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-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>.*build/.+\.c$
+<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.</p>
+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
@@ -5429,24 +5859,28 @@ yourself.</p>
 <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>
+"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-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>
+<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-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>
+<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
@@ -5458,7 +5892,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
@@ -5471,14 +5906,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
@@ -5531,9 +5970,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
@@ -5563,10 +6001,10 @@ of them.</p>
 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>
+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>
@@ -5625,6 +6063,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>
@@ -5675,11 +6134,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>
 
 
@@ -5748,10 +6236,10 @@ Text reports may be printed to the console or output to a file.</p>
     
       
       
-      <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
+      <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
     
     
-      <script src="../../assets/javascripts/bundle.d7400e89.min.js"></script>
+      <script src="../../assets/javascripts/bundle.c21346df.min.js"></script>
       
     
   </body>