RubyGems - ceedling - Versions diffs - 1.1.10 → 1.2.1 - Mend

ceedling 1.1.10 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1145) hide show

data/site-local/development/plugins/plugin-subclass.html CHANGED Viewed

@@ -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>
@@ -330,7 +340,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>
@@ -2410,6 +2450,8 @@
@@ -3041,10 +3083,63 @@
     <li class="md-nav__item">
-      <a href="../../plugins/bullseye.html" class="md-nav__link">
+      <a href="../../plugins/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--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6_13" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../plugins/bullseye/index.html" class="md-nav__link ">
   <span class="md-ellipsis">
@@ -3052,6 +3147,50 @@
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_6_13" id="__nav_6_13_label" tabindex="0">
+                <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="../../plugins/bullseye/licensing.html" class="md-nav__link">
+  <span class="md-ellipsis">
+    Licensing
   </span>
@@ -3062,6 +3201,14 @@
+          </ul>
+        </nav>
+    </li>
@@ -3531,6 +3678,12 @@
@@ -3550,8 +3703,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">
@@ -3565,8 +3719,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">
@@ -3580,6 +3740,8 @@
           <ul class="md-nav__list" data-md-scrollfix>
@@ -3613,6 +3775,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">
@@ -3685,6 +3875,8 @@
@@ -3777,6 +3969,34 @@
+    <li class="md-nav__item">
+      <a href="../releases.html" class="md-nav__link">
+  <span class="md-ellipsis">
+    Branching & Releases
+  </span>
+      </a>
+    </li>
@@ -3810,7 +4030,7 @@
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_3" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_4" checked>
           <div class="md-nav__link md-nav__container">
@@ -3832,14 +4052,14 @@
             </a>
-              <label class="md-nav__link " for="__nav_10_3" id="__nav_10_3_label" tabindex="">
+              <label class="md-nav__link " for="__nav_10_4" id="__nav_10_4_label" tabindex="">
                 <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="true">
-          <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="true">
+          <label class="md-nav__title" for="__nav_10_4">
             <span class="md-nav__icon md-icon"></span>
@@ -4070,6 +4290,28 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#delta-build-hooks" class="md-nav__link">
+    <span class="md-ellipsis">
+        Delta build hooks
+    </span>
+  </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-pre_test_compile_registerarg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method pre_test_compile_register(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4081,6 +4323,17 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-pre_test_link_registerarg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method pre_test_link_register(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4092,6 +4345,17 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-pre_test_fixture_registerarg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method pre_test_fixture_register(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4103,6 +4367,17 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-explain_test_crasharg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method explain_test_crash(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4175,7 +4450,7 @@
   <a href="#validating-a-plugins-tools" class="md-nav__link">
     <span class="md-ellipsis">
-        Validating a plugin's tools
+        Validating a plugin’s tools
     </span>
   </a>
@@ -4191,6 +4466,78 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#test-results-report-templates" class="md-nav__link">
+    <span class="md-ellipsis">
+        Test results report templates
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Test results report templates">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#supplying-a-template" class="md-nav__link">
+    <span class="md-ellipsis">
+        Supplying a template
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#supported-syntax" class="md-nav__link">
+    <span class="md-ellipsis">
+        Supported syntax
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#newline-trimming" class="md-nav__link">
+    <span class="md-ellipsis">
+        Newline trimming
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#what-a-template-can-reference" class="md-nav__link">
+    <span class="md-ellipsis">
+        What a template can reference
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#unsupported-syntax" class="md-nav__link">
+    <span class="md-ellipsis">
+        Unsupported syntax
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
 </li>
     </ul>
@@ -4396,6 +4743,28 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#delta-build-hooks" class="md-nav__link">
+    <span class="md-ellipsis">
+        Delta build hooks
+    </span>
+  </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-pre_test_compile_registerarg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method pre_test_compile_register(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4407,6 +4776,17 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-pre_test_link_registerarg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method pre_test_link_register(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4418,6 +4798,17 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-pre_test_fixture_registerarg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method pre_test_fixture_register(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4429,6 +4820,17 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#plugin-hook-method-explain_test_crasharg_hash" class="md-nav__link">
+    <span class="md-ellipsis">
+        Plugin hook method explain_test_crash(arg_hash)
+    </span>
+  </a>
 </li>
         <li class="md-nav__item">
@@ -4501,7 +4903,7 @@
   <a href="#validating-a-plugins-tools" class="md-nav__link">
     <span class="md-ellipsis">
-        Validating a plugin's tools
+        Validating a plugin’s tools
     </span>
   </a>
@@ -4517,6 +4919,78 @@
     </span>
   </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#test-results-report-templates" class="md-nav__link">
+    <span class="md-ellipsis">
+        Test results report templates
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Test results report templates">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#supplying-a-template" class="md-nav__link">
+    <span class="md-ellipsis">
+        Supplying a template
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#supported-syntax" class="md-nav__link">
+    <span class="md-ellipsis">
+        Supported syntax
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#newline-trimming" class="md-nav__link">
+    <span class="md-ellipsis">
+        Newline trimming
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#what-a-template-can-reference" class="md-nav__link">
+    <span class="md-ellipsis">
+        What a template can reference
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#unsupported-syntax" class="md-nav__link">
+    <span class="md-ellipsis">
+        Unsupported syntax
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
 </li>
     </ul>
@@ -4609,17 +5083,17 @@
 <p>Naming and location conventions:</p>
 <ul>
 <li><code>&lt;plugin_name&gt;/lib/&lt;plugin_name&gt;.rb</code></li>
-<li>The plugin's class name must be the camelized version (a.k.a. "bumpy case")
+<li>The plugin’s class name must be the camelized version (a.k.a. "bumpy case")
   of the plugin filename — <code>whiz_bang.rb</code> ➡️ <code>WhizBang</code>.</li>
 </ul>
 <p>This plugin option allows full programmatic ability connected to any of a number
 of predefined Ceedling build steps.</p>
 <p>The contents of <code>&lt;plugin_name&gt;.rb</code> must implement a class that subclasses
-<code>Plugin</code>, Ceedling's plugin base class.</p>
+<code>Plugin</code>, Ceedling’s plugin base class.</p>
 <h2 id="example-plugin-subclass">Example <code>Plugin</code> subclass</h2>
 <p>An incomplete <code>Plugin</code> subclass follows to illustrate the basics.</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"># whiz_bang/lib/whiz_bang.rb</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="nb">require</span><span class="w"> </span><span class="s1">&#39;ceedling/plugins/plugin&#39;</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="nb">require</span><span class="w"> </span><span class="s1">'ceedling/plugins/plugin'</span>
 <a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
 <a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="k">class</span><span class="w"> </span><span class="nc">WhizBang</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">Plugin</span>
 <a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">setup</span>
@@ -4698,7 +5172,7 @@ one difference.</p>
 <p>In the <code>post_</code> hook, the <code>arg_hash</code> parameter will contain a <code>shell_result</code> key
 whose associated value is itself a hash with the following contents:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="p">{</span>
-<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="w">  </span><span class="ss">:output</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;Console output&gt;&quot;</span><span class="p">,</span><span class="w"> </span><span class="c1"># String holding any $stdout / redirected $stderr output</span>
+<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="w">  </span><span class="ss">:output</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;Console output&gt;"</span><span class="p">,</span><span class="w"> </span><span class="c1"># String holding any $stdout / redirected $stderr output</span>
 <a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="w">  </span><span class="ss">:status</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="no">Process</span><span class="o">::</span><span class="no">Status</span><span class="o">&gt;</span><span class="p">,</span><span class="w">  </span><span class="c1"># Ruby object of type Process::Status</span>
 <a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="w">  </span><span class="ss">:exit_code</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">int</span><span class="o">&gt;</span><span class="p">,</span><span class="w">           </span><span class="c1"># Command line exit code (extracted from :status object)</span>
 <a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a><span class="w">  </span><span class="ss">:time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">&lt;</span><span class="n">float</span><span class="o">&gt;</span><span class="w">               </span><span class="c1"># Seconds elapsed for shell operation</span>
@@ -4708,7 +5182,7 @@ whose associated value is itself a hash with the following contents:</p>
 <p class="admonition-title">Preprocessing Hook Limitations</p>
 <p>Test preprocessing steps are quite sophisticated and involve various combinations
 of tool executions. The <code>post_</code> preprocessing hooks do not include shell results.
-Future updates to Ceedling's plugin system will create a more robust means of
+Future updates to Ceedling’s plugin system will create a more robust means of
 attaching custom behaviors to test preprocessing or connecting your own
 preprocessing pipeline with toolchains other than GCC.</p>
 </div>
@@ -4721,11 +5195,11 @@ number of mocks in a test build.</p>
 <p>The argument <code>arg_hash</code> follows the structure below:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w">  </span><span class="c1"># Filepath of header file to be preprocessed on its way to being mocked</span>
-<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w">  </span><span class="ss">:header_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w">  </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w">  </span><span class="ss">:header_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w">  </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w">  </span><span class="c1"># Filepath of processed header file</span>
-<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w">  </span><span class="ss">:preprocessed_header_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w">  </span><span class="ss">:preprocessed_header_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="w">  </span><span class="c1"># Filepath of tests C file the mock will be used by</span>
-<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a><span class="w">  </span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a><span class="w">  </span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a><span class="w">  </span><span class="c1"># List of flags to be provided to `cpp` GNU preprocessor tool</span>
 <a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
 <a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a><span class="w">  </span><span class="c1"># List of search paths to be provided to `cpp` GNU preprocessor tool</span>
@@ -4743,11 +5217,11 @@ files in a test build.</p>
 <p>The argument <code>arg_hash</code> follows the structure below:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </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="c1"># Filepath of C test file to be preprocessed on its way to being used to generate runner</span>
-<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w">  </span><span class="ss">:test_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</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="ss">:test_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w">  </span><span class="c1"># Filepath of processed tests file</span>
-<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w">  </span><span class="ss">:preprocessed_test_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w">  </span><span class="ss">:preprocessed_test_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="w">  </span><span class="c1"># Filepath of tests C file the mock will be used by</span>
-<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w">  </span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w">  </span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><span class="w">  </span><span class="c1"># List of flags to be provided to `cpp` GNU preprocessor tool</span>
 <a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
 <a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a><span class="w">  </span><span class="c1"># List of search paths to be provided to `cpp` GNU preprocessor tool</span>
@@ -4764,14 +5238,14 @@ build.</p>
 <p>The argument <code>arg_hash</code> follows the structure below:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
 <a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="w">  </span><span class="c1"># Filepath of the header file being mocked.</span>
-<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a><span class="w">  </span><span class="ss">:header_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a><span class="w">  </span><span class="ss">:header_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="w">  </span><span class="c1"># Additional context passed by the calling function.</span>
 <a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a><span class="w">  </span><span class="c1"># Ceedling passes the :test symbol by default while plugins may provide another</span>
 <a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
 <a id="__codelineno-6-7" name="__codelineno-6-7" href="#__codelineno-6-7"></a><span class="w">  </span><span class="c1"># Filepath of the tests C file that references the requested mock</span>
-<a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a><span class="w">  </span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a><span class="w">  </span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-6-9" name="__codelineno-6-9" href="#__codelineno-6-9"></a><span class="w">  </span><span class="c1"># Filepath of the generated mock C code.</span>
-<a id="__codelineno-6-10" name="__codelineno-6-10" href="#__codelineno-6-10"></a><span class="w">  </span><span class="ss">:output_path</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span>
+<a id="__codelineno-6-10" name="__codelineno-6-10" href="#__codelineno-6-10"></a><span class="w">  </span><span class="ss">:output_path</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span>
 <a id="__codelineno-6-11" name="__codelineno-6-11" href="#__codelineno-6-11"></a><span class="p">}</span>
 </code></pre></div>
 <h2 id="plugin-hook-methods-pre_runner_generatearg_hash-and-post_runner_generatearg_hash"><code>Plugin</code> hook methods <code>pre_runner_generate(arg_hash)</code> and <code>post_runner_generate(arg_hash)</code></h2>
@@ -4786,42 +5260,90 @@ called a number of times equal to the number of test files in a test build.</p>
 <a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="w">  </span><span class="c1"># Ceedling passes the :test symbol by default while plugins may provide another</span>
 <a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
 <a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a><span class="w">  </span><span class="c1"># Filepath of the tests C file.</span>
-<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a><span class="w">  </span><span class="ss">:test_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a><span class="w">  </span><span class="ss">:test_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-7-7" name="__codelineno-7-7" href="#__codelineno-7-7"></a><span class="w">  </span><span class="c1"># Filepath of the test file to be processed (if preprocessing enabled, this is not the same as :test_file).  </span>
-<a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a><span class="w">  </span><span class="ss">:input_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
+<a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a><span class="w">  </span><span class="ss">:input_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
 <a id="__codelineno-7-9" name="__codelineno-7-9" href="#__codelineno-7-9"></a><span class="w">  </span><span class="c1"># Filepath of the generated tests runner file.</span>
-<a id="__codelineno-7-10" name="__codelineno-7-10" href="#__codelineno-7-10"></a><span class="w">  </span><span class="ss">:runner_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span>
+<a id="__codelineno-7-10" name="__codelineno-7-10" href="#__codelineno-7-10"></a><span class="w">  </span><span class="ss">:runner_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span>
 <a id="__codelineno-7-11" name="__codelineno-7-11" href="#__codelineno-7-11"></a><span class="p">}</span>
 </code></pre></div>
-<h2 id="plugin-hook-methods-pre_compile_executearg_hash-and-post_compile_executearg_hash"><code>Plugin</code> hook methods <code>pre_compile_execute(arg_hash)</code> and <code>post_compile_execute(arg_hash)</code></h2>
-<p>These methods are called before and after source file compilation. These are
-called in both test and release builds. This pair of methods is called a number
-of times equal to the number of C files in a test or release build.</p>
+<h2 id="delta-build-hooks">Delta build hooks</h2>
+<p>Ceedling skips work when nothing has changed. This is called a delta build.
+See <a href="../../getting-started/builds.html">Delta Builds</a> for the full picture.</p>
+<p>Three hook methods run before Ceedling checks delta build state for a
+target. Each one always runs, for every target, whether or not that target
+turns out to need rebuilding. A plugin uses one of these hooks to swap in
+its own tool for its own build context. Doing the swap here, not only in
+the matching <code>pre_*_execute</code> hook below, makes sure Ceedling’s delta build
+check sees the real tool. Otherwise a change to that tool’s own settings
+will not force a rebuild.</p>
+<h2 id="plugin-hook-method-pre_test_compile_registerarg_hash"><code>Plugin</code> hook method <code>pre_test_compile_register(arg_hash)</code></h2>
+<p>Test builds only, not release builds. Runs once per C file in a test build.
+Runs before Ceedling registers the file as a delta build target.</p>
 <p>The argument <code>arg_hash</code> follows the structure below:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </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="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </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="c1"># Hash holding compiler tool properties — see &#39;:tools&#39; in the Project Configuration Reference</span>
+<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="w">    </span><span class="c1"># Hash holding compiler tool properties — see ':tools' in the Project Configuration Reference</span>
 <a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="w">  </span><span class="p">},</span>
-<a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="w">  </span><span class="c1"># Symbol of the operation being performed, e.g. :compile, :assemble or :link</span>
+<a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="w">  </span><span class="c1"># Symbol of the operation being considered, e.g. :compile or :assemble</span>
 <a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a><span class="w">  </span><span class="ss">:operation</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">operation</span><span class="o">&gt;</span><span class="p">,</span>
-<a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a><span class="w">  </span><span class="c1"># Additional context passed by the calling function.</span>
-<a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a><span class="w">  </span><span class="c1"># Ceedling provides :test or :release by default while plugins may provide another.</span>
-<a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
-<a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a><span class="w">  </span><span class="c1"># Filepath of the input C file</span>
-<a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a><span class="w">  </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-8-12" name="__codelineno-8-12" href="#__codelineno-8-12"></a><span class="w">  </span><span class="c1"># Filepath of the output object file</span>
-<a id="__codelineno-8-13" name="__codelineno-8-13" href="#__codelineno-8-13"></a><span class="w">  </span><span class="ss">:object</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-8-14" name="__codelineno-8-14" href="#__codelineno-8-14"></a><span class="w">  </span><span class="c1"># List of flags to be provided to compiler tool</span>
-<a id="__codelineno-8-15" name="__codelineno-8-15" href="#__codelineno-8-15"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
-<a id="__codelineno-8-16" name="__codelineno-8-16" href="#__codelineno-8-16"></a><span class="w">  </span><span class="c1"># List of search paths to be provided to compiler tool</span>
-<a id="__codelineno-8-17" name="__codelineno-8-17" href="#__codelineno-8-17"></a><span class="w">  </span><span class="ss">:search_paths</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">paths</span><span class="o">&gt;]</span><span class="p">,</span>
-<a id="__codelineno-8-18" name="__codelineno-8-18" href="#__codelineno-8-18"></a><span class="w">  </span><span class="c1"># List of compilation symbols to be provided to compiler tool</span>
-<a id="__codelineno-8-19" name="__codelineno-8-19" href="#__codelineno-8-19"></a><span class="w">  </span><span class="ss">:defines</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">defines</span><span class="o">&gt;]</span><span class="p">,</span>
-<a id="__codelineno-8-20" name="__codelineno-8-20" href="#__codelineno-8-20"></a><span class="w">  </span><span class="c1"># Filepath of the listing file, e.g. .lst file</span>
-<a id="__codelineno-8-21" name="__codelineno-8-21" href="#__codelineno-8-21"></a><span class="w">  </span><span class="ss">:list</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-8-22" name="__codelineno-8-22" href="#__codelineno-8-22"></a><span class="w">  </span><span class="c1"># Filepath of the dependencies file, e.g. .d file</span>
-<a id="__codelineno-8-23" name="__codelineno-8-23" href="#__codelineno-8-23"></a><span class="w">  </span><span class="ss">:dependencies</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span>
-<a id="__codelineno-8-24" name="__codelineno-8-24" href="#__codelineno-8-24"></a><span class="p">}</span>
+<a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
+<a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a><span class="w">  </span><span class="ss">:module_name</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;name&gt;"</span><span class="p">,</span>
+<a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a><span class="w">  </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a><span class="w">  </span><span class="ss">:object</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
+<a id="__codelineno-8-12" name="__codelineno-8-12" href="#__codelineno-8-12"></a><span class="w">  </span><span class="ss">:defines</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">defines</span><span class="o">&gt;]</span>
+<a id="__codelineno-8-13" name="__codelineno-8-13" href="#__codelineno-8-13"></a><span class="p">}</span>
+</code></pre></div>
+<h2 id="plugin-hook-methods-pre_compile_executearg_hash-and-post_compile_executearg_hash"><code>Plugin</code> hook methods <code>pre_compile_execute(arg_hash)</code> and <code>post_compile_execute(arg_hash)</code></h2>
+<p>These methods are called before and after source file compilation. These are
+called in both test and release builds. This pair of methods is called a number
+of times equal to the number of C files in a test or release build.</p>
+<p>The argument <code>arg_hash</code> follows the structure below:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a><span class="w">  </span><span class="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="w">    </span><span class="c1"># Hash holding compiler tool properties — see ':tools' in the Project Configuration Reference</span>
+<a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="w">  </span><span class="p">},</span>
+<a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="w">  </span><span class="c1"># Symbol of the operation being performed, e.g. :compile, :assemble or :link</span>
+<a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a><span class="w">  </span><span class="ss">:operation</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">operation</span><span class="o">&gt;</span><span class="p">,</span>
+<a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a><span class="w">  </span><span class="c1"># Additional context passed by the calling function.</span>
+<a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a><span class="w">  </span><span class="c1"># Ceedling provides :test or :release by default while plugins may provide another.</span>
+<a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
+<a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="w">  </span><span class="c1"># Filepath of the input C file</span>
+<a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></a><span class="w">  </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-9-12" name="__codelineno-9-12" href="#__codelineno-9-12"></a><span class="w">  </span><span class="c1"># Filepath of the output object file</span>
+<a id="__codelineno-9-13" name="__codelineno-9-13" href="#__codelineno-9-13"></a><span class="w">  </span><span class="ss">:object</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-9-14" name="__codelineno-9-14" href="#__codelineno-9-14"></a><span class="w">  </span><span class="c1"># List of flags to be provided to compiler tool</span>
+<a id="__codelineno-9-15" name="__codelineno-9-15" href="#__codelineno-9-15"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
+<a id="__codelineno-9-16" name="__codelineno-9-16" href="#__codelineno-9-16"></a><span class="w">  </span><span class="c1"># List of search paths to be provided to compiler tool</span>
+<a id="__codelineno-9-17" name="__codelineno-9-17" href="#__codelineno-9-17"></a><span class="w">  </span><span class="ss">:search_paths</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">paths</span><span class="o">&gt;]</span><span class="p">,</span>
+<a id="__codelineno-9-18" name="__codelineno-9-18" href="#__codelineno-9-18"></a><span class="w">  </span><span class="c1"># List of compilation symbols to be provided to compiler tool</span>
+<a id="__codelineno-9-19" name="__codelineno-9-19" href="#__codelineno-9-19"></a><span class="w">  </span><span class="ss">:defines</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">defines</span><span class="o">&gt;]</span><span class="p">,</span>
+<a id="__codelineno-9-20" name="__codelineno-9-20" href="#__codelineno-9-20"></a><span class="w">  </span><span class="c1"># Filepath of the listing file, e.g. .lst file</span>
+<a id="__codelineno-9-21" name="__codelineno-9-21" href="#__codelineno-9-21"></a><span class="w">  </span><span class="ss">:list</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-9-22" name="__codelineno-9-22" href="#__codelineno-9-22"></a><span class="w">  </span><span class="c1"># Filepath of the dependencies file, e.g. .d file</span>
+<a id="__codelineno-9-23" name="__codelineno-9-23" href="#__codelineno-9-23"></a><span class="w">  </span><span class="ss">:dependencies</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span>
+<a id="__codelineno-9-24" name="__codelineno-9-24" href="#__codelineno-9-24"></a><span class="p">}</span>
+</code></pre></div>
+<h2 id="plugin-hook-method-pre_test_link_registerarg_hash"><code>Plugin</code> hook method <code>pre_test_link_register(arg_hash)</code></h2>
+<p>Test builds only, not release builds. Runs once per test executable in a
+test build. Runs before Ceedling registers the executable as a delta build
+target. See <a href="#delta-build-hooks">Delta build hooks</a> above for why this hook
+exists and when it runs.</p>
+<p>A plugin swapping in its own linker tool for its own build context should
+do so here, for the same reason described under <code>pre_test_compile_register</code>
+above. Because this hook always runs, it also gives a plugin a reliable
+place to note that its own build context ran at all, apart from whether
+anything actually needed relinking.</p>
+<p>The argument <code>arg_hash</code> follows the structure below:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="w">  </span><span class="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="w">    </span><span class="c1"># Hash holding linker tool properties — see ':tools' in the Project Configuration Reference</span>
+<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="w">  </span><span class="p">},</span>
+<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
+<a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
+<a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a><span class="w">  </span><span class="ss">:executable</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span>
+<a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a><span class="p">}</span>
 </code></pre></div>
 <h2 id="plugin-hook-methods-pre_link_executearg_hash-and-post_link_executearg_hash"><code>Plugin</code> hook methods <code>pre_link_execute(arg_hash)</code> and <code>post_link_execute(arg_hash)</code></h2>
 <p>These methods are called before and after linking an executable. These are
@@ -4830,27 +5352,58 @@ executable and each release artifact. This pair of methods is called a number
 of times equal to the number of test files in a test build or release artifacts
 in a release build.</p>
 <p>The argument <code>arg_hash</code> follows the structure below:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a><span class="w">  </span><span class="c1"># Hash holding linker tool properties.</span>
-<a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="w">  </span><span class="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="w">    </span><span class="c1"># Hash holding compiler tool properties — see &#39;:tools&#39; in the Project Configuration Reference</span>
-<a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="w">  </span><span class="p">},</span>
-<a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a><span class="w">  </span><span class="c1"># Additional context passed by the calling function.</span>
-<a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a><span class="w">  </span><span class="c1"># Ceedling provides :test or :release by default while plugins may provide another.</span>
-<a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
-<a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="w">  </span><span class="c1"># List of object files paths being linked, e.g. .o files</span>
-<a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="w">  </span><span class="ss">:objects</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[]</span><span class="p">,</span>
-<a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></a><span class="w">  </span><span class="c1"># List of flags to be provided to linker tool</span>
-<a id="__codelineno-9-12" name="__codelineno-9-12" href="#__codelineno-9-12"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
-<a id="__codelineno-9-13" name="__codelineno-9-13" href="#__codelineno-9-13"></a><span class="w">  </span><span class="c1"># Filepath of the output file, e.g. .out file</span>
-<a id="__codelineno-9-14" name="__codelineno-9-14" href="#__codelineno-9-14"></a><span class="w">  </span><span class="ss">:executable</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-9-15" name="__codelineno-9-15" href="#__codelineno-9-15"></a><span class="w">  </span><span class="c1"># Filepath of the map file, e.g. .map file</span>
-<a id="__codelineno-9-16" name="__codelineno-9-16" href="#__codelineno-9-16"></a><span class="w">  </span><span class="ss">:map</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-9-17" name="__codelineno-9-17" href="#__codelineno-9-17"></a><span class="w">  </span><span class="c1"># List of libraries to link, e.g. those passed to the (GNU) linker with -l</span>
-<a id="__codelineno-9-18" name="__codelineno-9-18" href="#__codelineno-9-18"></a><span class="w">  </span><span class="ss">:libraries</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">names</span><span class="o">&gt;]</span><span class="p">,</span>
-<a id="__codelineno-9-19" name="__codelineno-9-19" href="#__codelineno-9-19"></a><span class="w">  </span><span class="c1"># List of libraries paths, e.g. the ones passed to the (GNU) linker with -L</span>
-<a id="__codelineno-9-20" name="__codelineno-9-20" href="#__codelineno-9-20"></a><span class="w">  </span><span class="ss">:libpaths</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">paths</span><span class="o">&gt;]</span>
-<a id="__codelineno-9-21" name="__codelineno-9-21" href="#__codelineno-9-21"></a><span class="p">}</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="w">  </span><span class="c1"># Hash holding linker tool properties.</span>
+<a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a><span class="w">  </span><span class="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="w">    </span><span class="c1"># Hash holding compiler tool properties — see ':tools' in the Project Configuration Reference</span>
+<a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a><span class="w">  </span><span class="p">},</span>
+<a id="__codelineno-11-6" name="__codelineno-11-6" href="#__codelineno-11-6"></a><span class="w">  </span><span class="c1"># Additional context passed by the calling function.</span>
+<a id="__codelineno-11-7" name="__codelineno-11-7" href="#__codelineno-11-7"></a><span class="w">  </span><span class="c1"># Ceedling provides :test or :release by default while plugins may provide another.</span>
+<a id="__codelineno-11-8" name="__codelineno-11-8" href="#__codelineno-11-8"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
+<a id="__codelineno-11-9" name="__codelineno-11-9" href="#__codelineno-11-9"></a><span class="w">  </span><span class="c1"># List of object files paths being linked, e.g. .o files</span>
+<a id="__codelineno-11-10" name="__codelineno-11-10" href="#__codelineno-11-10"></a><span class="w">  </span><span class="ss">:objects</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[]</span><span class="p">,</span>
+<a id="__codelineno-11-11" name="__codelineno-11-11" href="#__codelineno-11-11"></a><span class="w">  </span><span class="c1"># List of flags to be provided to linker tool</span>
+<a id="__codelineno-11-12" name="__codelineno-11-12" href="#__codelineno-11-12"></a><span class="w">  </span><span class="ss">:flags</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">flags</span><span class="o">&gt;]</span><span class="p">,</span>
+<a id="__codelineno-11-13" name="__codelineno-11-13" href="#__codelineno-11-13"></a><span class="w">  </span><span class="c1"># Filepath of the output file, e.g. .out file</span>
+<a id="__codelineno-11-14" name="__codelineno-11-14" href="#__codelineno-11-14"></a><span class="w">  </span><span class="ss">:executable</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-11-15" name="__codelineno-11-15" href="#__codelineno-11-15"></a><span class="w">  </span><span class="c1"># Filepath of the map file, e.g. .map file</span>
+<a id="__codelineno-11-16" name="__codelineno-11-16" href="#__codelineno-11-16"></a><span class="w">  </span><span class="ss">:map</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-11-17" name="__codelineno-11-17" href="#__codelineno-11-17"></a><span class="w">  </span><span class="c1"># List of libraries to link, e.g. those passed to the (GNU) linker with -l</span>
+<a id="__codelineno-11-18" name="__codelineno-11-18" href="#__codelineno-11-18"></a><span class="w">  </span><span class="ss">:libraries</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">names</span><span class="o">&gt;]</span><span class="p">,</span>
+<a id="__codelineno-11-19" name="__codelineno-11-19" href="#__codelineno-11-19"></a><span class="w">  </span><span class="c1"># List of libraries paths, e.g. the ones passed to the (GNU) linker with -L</span>
+<a id="__codelineno-11-20" name="__codelineno-11-20" href="#__codelineno-11-20"></a><span class="w">  </span><span class="ss">:libpaths</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[&lt;</span><span class="n">paths</span><span class="o">&gt;]</span>
+<a id="__codelineno-11-21" name="__codelineno-11-21" href="#__codelineno-11-21"></a><span class="p">}</span>
+</code></pre></div>
+<h2 id="plugin-hook-method-pre_test_fixture_registerarg_hash"><code>Plugin</code> hook method <code>pre_test_fixture_register(arg_hash)</code></h2>
+<p>Runs once per test executable. Runs before Ceedling registers the test run
+as a delta build target. See <a href="#delta-build-hooks">Delta build hooks</a> above
+for why this hook exists and when it runs.</p>
+<p>A plugin swapping in its own wrapper tool to run the test executable (as
+Valgrind does) should do so here, for the same reason described under
+<code>pre_test_compile_register</code> above. Otherwise a change to that wrapper tool’s own
+settings will not force a rerun.</p>
+<p>A wrapper tool runs the test executable as one of its own arguments. Ceedling
+places Unity’s test case filters (from <code>--test-case</code>, <code>--exclude_test_case</code>, and
+backtrace reruns) after the tool’s arguments, where the executable is.</p>
+<p>A crashed test executable reruns one test case at a time when
+<code>:use_backtrace</code> is <code>:simple</code>. By default the reruns go through Ceedling’s own
+backtrace tool, not a swapped wrapper. A wrapper the reruns should run through
+too (as the Sanitize plugin’s does, to keep its runtime options) sets
+<code>:backtrace_rerun =&gt; true</code> in its tool hash. Such a tool can't run under gdb, so
+<code>:gdb</code> backtraces fall back to <code>:simple</code> for it, with a notice. Leave the key out
+for a wrapper that writes one report per test, as Valgrind’s does, since each
+rerun would overwrite it.</p>
+<p>The argument <code>arg_hash</code> follows the structure below:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a><span class="w">  </span><span class="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a><span class="w">    </span><span class="c1"># Hash holding execution tool properties — see ':tools' in the Project Configuration Reference</span>
+<a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a><span class="w">  </span><span class="p">},</span>
+<a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
+<a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a><span class="w">  </span><span class="ss">:test_name</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;name&gt;"</span><span class="p">,</span>
+<a id="__codelineno-12-7" name="__codelineno-12-7" href="#__codelineno-12-7"></a><span class="w">  </span><span class="c1"># The delta build target for this test run. A plugin can register its own</span>
+<a id="__codelineno-12-8" name="__codelineno-12-8" href="#__codelineno-12-8"></a><span class="w">  </span><span class="c1"># additional data against this same target — see Delta Builds.</span>
+<a id="__codelineno-12-9" name="__codelineno-12-9" href="#__codelineno-12-9"></a><span class="w">  </span><span class="ss">:target</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span>
+<a id="__codelineno-12-10" name="__codelineno-12-10" href="#__codelineno-12-10"></a><span class="p">}</span>
 </code></pre></div>
 <h2 id="plugin-hook-methods-pre_test_fixture_executearg_hash-and-post_test_fixture_executearg_hash"><code>Plugin</code> hook methods <code>pre_test_fixture_execute(arg_hash)</code> and <code>post_test_fixture_execute(arg_hash)</code></h2>
 <p>These methods are called before and after running a test executable. If a build
@@ -4858,23 +5411,56 @@ does not include tests, these are not called. This pair of methods is called
 for each test executable in a build (each test file is ultimately built into a
 test executable).</p>
 <p>The argument <code>arg_hash</code> follows the structure below:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="w">  </span><span class="c1"># Hash holding execution tool properties.</span>
-<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="w">  </span><span class="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="w">    </span><span class="c1"># Hash holding compiler tool properties — see &#39;:tools&#39; in the Project Configuration Reference</span>
-<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="w">  </span><span class="p">},</span>
-<a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="w">  </span><span class="c1"># Additional context passed by the calling function.</span>
-<a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a><span class="w">  </span><span class="c1"># Ceedling provides :test or :release by default while plugins may provide another.</span>
-<a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
-<a id="__codelineno-10-9" name="__codelineno-10-9" href="#__codelineno-10-9"></a><span class="w">  </span><span class="c1"># Name of the test file minus path and extension (`test/TestIness.c` -&gt; &#39;TestIness&#39;)</span>
-<a id="__codelineno-10-10" name="__codelineno-10-10" href="#__codelineno-10-10"></a><span class="w">  </span><span class="ss">:test_name</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;name&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-10-11" name="__codelineno-10-11" href="#__codelineno-10-11"></a><span class="w">  </span><span class="c1"># Filepath of original tests C file that became the test executable</span>
-<a id="__codelineno-10-12" name="__codelineno-10-12" href="#__codelineno-10-12"></a><span class="w">  </span><span class="ss">:test_filepath</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-10-13" name="__codelineno-10-13" href="#__codelineno-10-13"></a><span class="w">  </span><span class="c1"># Path to the tests executable file, e.g. .out file</span>
-<a id="__codelineno-10-14" name="__codelineno-10-14" href="#__codelineno-10-14"></a><span class="w">  </span><span class="ss">:executable</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span><span class="p">,</span>
-<a id="__codelineno-10-15" name="__codelineno-10-15" href="#__codelineno-10-15"></a><span class="w">  </span><span class="c1"># Path to the tests result file, e.g. .pass/.fail file</span>
-<a id="__codelineno-10-16" name="__codelineno-10-16" href="#__codelineno-10-16"></a><span class="w">  </span><span class="ss">:result_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;filepath&gt;&quot;</span>
-<a id="__codelineno-10-17" name="__codelineno-10-17" href="#__codelineno-10-17"></a><span class="p">}</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="w">  </span><span class="c1"># Hash holding execution tool properties.</span>
+<a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="w">  </span><span class="ss">:tool</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-4"></a><span class="w">    </span><span class="c1"># Hash holding compiler tool properties — see ':tools' in the Project Configuration Reference</span>
+<a id="__codelineno-13-5" name="__codelineno-13-5" href="#__codelineno-13-5"></a><span class="w">  </span><span class="p">},</span>
+<a id="__codelineno-13-6" name="__codelineno-13-6" href="#__codelineno-13-6"></a><span class="w">  </span><span class="c1"># Additional context passed by the calling function.</span>
+<a id="__codelineno-13-7" name="__codelineno-13-7" href="#__codelineno-13-7"></a><span class="w">  </span><span class="c1"># Ceedling provides :test or :release by default while plugins may provide another.</span>
+<a id="__codelineno-13-8" name="__codelineno-13-8" href="#__codelineno-13-8"></a><span class="w">  </span><span class="ss">:context</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="ss">:&lt;</span><span class="n">context</span><span class="o">&gt;</span><span class="p">,</span>
+<a id="__codelineno-13-9" name="__codelineno-13-9" href="#__codelineno-13-9"></a><span class="w">  </span><span class="c1"># Name of the test file minus path and extension (`test/TestIness.c` -&gt; 'TestIness')</span>
+<a id="__codelineno-13-10" name="__codelineno-13-10" href="#__codelineno-13-10"></a><span class="w">  </span><span class="ss">:test_name</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;name&gt;"</span><span class="p">,</span>
+<a id="__codelineno-13-11" name="__codelineno-13-11" href="#__codelineno-13-11"></a><span class="w">  </span><span class="c1"># Filepath of original tests C file that became the test executable</span>
+<a id="__codelineno-13-12" name="__codelineno-13-12" href="#__codelineno-13-12"></a><span class="w">  </span><span class="ss">:test_filepath</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-13-13" name="__codelineno-13-13" href="#__codelineno-13-13"></a><span class="w">  </span><span class="c1"># Path to the tests executable file, e.g. .out file</span>
+<a id="__codelineno-13-14" name="__codelineno-13-14" href="#__codelineno-13-14"></a><span class="w">  </span><span class="ss">:executable</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span><span class="p">,</span>
+<a id="__codelineno-13-15" name="__codelineno-13-15" href="#__codelineno-13-15"></a><span class="w">  </span><span class="c1"># Path to the tests result file, e.g. .pass/.fail file</span>
+<a id="__codelineno-13-16" name="__codelineno-13-16" href="#__codelineno-13-16"></a><span class="w">  </span><span class="ss">:result_file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;filepath&gt;"</span>
+<a id="__codelineno-13-17" name="__codelineno-13-17" href="#__codelineno-13-17"></a><span class="p">}</span>
+</code></pre></div>
+<h2 id="plugin-hook-method-explain_test_crasharg_hash"><code>Plugin</code> hook method <code>explain_test_crash(arg_hash)</code></h2>
+<p>Called when a test executable crashed, before Ceedling writes the crash as test
+failures. A plugin that recognizes the cause, such as a sanitizer’s report in the
+run’s output, sets <code>arg_hash[:explanation]</code> to a short message. That message
+replaces the generic crash message in the test’s failure, except with <code>:gdb</code>
+backtraces, whose failures carry gdb’s own trace. It also replaces Ceedling’s
+generic crash notice and its backtrace advice.</p>
+<p>Two optional keys shape the notice:</p>
+<ul>
+<li><code>:explanation_heading</code> completes its first line, “Test executable <code>x</code> …”.
+  Without it, the line ends “crashed.”</li>
+<li><code>:explanation_details</code> lists lines that follow the cause, such as where a
+  log is. The failure message adds them in parentheses.</li>
+</ul>
+<p>With <code>:use_backtrace</code> set to <code>:simple</code>, it is called again for each rerun that
+crashes, with that rerun’s own shell result, so each crashed test case can be
+explained on its own.</p>
+<p>The argument <code>arg_hash</code> holds the same keys as <code>pre_test_fixture_execute</code> above,
+plus:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="n">arg_hash</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a><span class="w">  </span><span class="c1"># ...the keys above...</span>
+<a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a><span class="w">  </span><span class="c1"># The crashed run’s shell result -- see Command line tool shell results</span>
+<a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a><span class="w">  </span><span class="ss">:shell_result</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">...</span><span class="w"> </span><span class="p">},</span>
+<a id="__codelineno-14-5" name="__codelineno-14-5" href="#__codelineno-14-5"></a><span class="w">  </span><span class="c1"># Set by a plugin that recognizes the cause; nil otherwise</span>
+<a id="__codelineno-14-6" name="__codelineno-14-6" href="#__codelineno-14-6"></a><span class="w">  </span><span class="ss">:explanation</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="kp">nil</span><span class="p">,</span>
+<a id="__codelineno-14-7" name="__codelineno-14-7" href="#__codelineno-14-7"></a><span class="w">  </span><span class="c1"># True for the crash's main run, whose explanation reaches the crash notice;</span>
+<a id="__codelineno-14-8" name="__codelineno-14-8" href="#__codelineno-14-8"></a><span class="w">  </span><span class="c1"># false for a backtrace rerun</span>
+<a id="__codelineno-14-9" name="__codelineno-14-9" href="#__codelineno-14-9"></a><span class="w">  </span><span class="ss">:crash_notice</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="kp">true</span><span class="p">,</span>
+<a id="__codelineno-14-10" name="__codelineno-14-10" href="#__codelineno-14-10"></a><span class="w">  </span><span class="c1"># Optional, set alongside :explanation</span>
+<a id="__codelineno-14-11" name="__codelineno-14-11" href="#__codelineno-14-11"></a><span class="w">  </span><span class="ss">:explanation_details</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="kp">nil</span><span class="p">,</span>
+<a id="__codelineno-14-12" name="__codelineno-14-12" href="#__codelineno-14-12"></a><span class="w">  </span><span class="ss">:explanation_heading</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="kp">nil</span>
+<a id="__codelineno-14-13" name="__codelineno-14-13" href="#__codelineno-14-13"></a><span class="p">}</span>
 </code></pre></div>
 <h2 id="plugin-hook-methods-pre_testtest-and-post_testtest"><code>Plugin</code> hook methods <code>pre_test(test)</code> and <code>post_test(test)</code></h2>
 <p>These methods are called before and after performing all steps needed to run a
@@ -4889,6 +5475,10 @@ termination points, including early exit due to a build error.</p>
 <p>The argument <code>context</code> is the build context symbol (e.g. <code>:test</code>, <code>:gcov</code>) that
 was passed to <code>TestInvoker#setup_and_invoke</code>. This lets a plugin respond
 differently depending on which kind of build triggered the pipeline.</p>
+<p>Each context also gets its own separate delta build cache. A plugin that
+runs its own build under a distinct context symbol keeps that build’s
+tracked state apart from ordinary test builds and from any other plugin’s
+builds. See <a href="../../getting-started/builds.html">Delta Builds</a> for more.</p>
 <p>The argument <code>timestamp_s</code> is a floating-point stopwatch value in seconds
 (from <code>SystemWrapper.time_stopwatch_s</code>). Compare the <code>pre_test_build</code> and
 <code>post_test_build</code> timestamps to compute the total test build duration using
@@ -4918,27 +5508,27 @@ cases is not a build error.</p>
 <p>This method is called when invoking the summary task, <code>ceedling summary</code>. This
 method facilitates logging the results of the last build without running the
 previous build again.</p>
-<h2 id="validating-a-plugins-tools">Validating a plugin's tools</h2>
+<h2 id="validating-a-plugins-tools">Validating a plugin’s tools</h2>
 <p>By default, Ceedling validates configured tools at startup according to a
 simple setting within the tool definition. This works just fine for default
 core tools and options. However, in the case of plugins, tools may not be even
-relevant to a plugin's operation depending on its configurable options. It's
+relevant to a plugin’s operation depending on its configurable options. It’s
 a bit silly for a tool not needed by your project to fail validation if
-Ceedling can't find it in your <code>$PATH</code>. Similarly, it's irresponsible to skip
+Ceedling can't find it in your <code>$PATH</code>. Similarly, it’s irresponsible to skip
 validating a tool just because it may not be needed.</p>
 <p>Ceedling provides optional, programmatic tool validation for these cases.
-<code>@ceedling[:tool_validator].validate()</code> can be forced to ignore a tool's
+<code>@ceedling[:tool_validator].validate()</code> can be forced to ignore a tool’s
 <code>required:</code> setting to validate it. In such a scenario, a plugin should
 configure its own tools as <code>:optional =&gt; true</code> but forcibly validate them at
-plugin startup if the plugin's configuration options require said tool.</p>
+plugin startup if the plugin’s configuration options require said tool.</p>
 <p>An example from the <code>gcov</code> plugin illustrates this.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="c1"># Validate gcov summary tool if coverage summaries are enabled (summaries rely on the `gcov` tool)</span>
-<a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="k">if</span><span class="w"> </span><span class="n">summaries_enabled?</span><span class="p">(</span><span class="w"> </span><span class="vi">@project_config</span><span class="w"> </span><span class="p">)</span>
-<a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a><span class="w">  </span><span class="vi">@ceedling</span><span class="o">[</span><span class="ss">:tool_validator</span><span class="o">].</span><span class="n">validate</span><span class="p">(</span>
-<a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="w">    </span><span class="ss">tool</span><span class="p">:</span><span class="w"> </span><span class="no">TOOLS_GCOV_SUMMARY</span><span class="p">,</span><span class="w"> </span><span class="c1"># Tool defintion as Ruby hash</span>
-<a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a><span class="w">    </span><span class="ss">boom</span><span class="p">:</span><span class="w"> </span><span class="kp">true</span><span class="w">                </span><span class="c1"># Ignore optional status (raise exception if invalid)</span>
-<a id="__codelineno-11-6" name="__codelineno-11-6" href="#__codelineno-11-6"></a><span class="w">  </span><span class="p">)</span>
-<a id="__codelineno-11-7" name="__codelineno-11-7" href="#__codelineno-11-7"></a><span class="k">end</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="c1"># Validate gcov summary tool if coverage summaries are enabled (summaries rely on the `gcov` tool)</span>
+<a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a><span class="k">if</span><span class="w"> </span><span class="n">summaries_enabled?</span><span class="p">(</span><span class="w"> </span><span class="vi">@project_config</span><span class="w"> </span><span class="p">)</span>
+<a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a><span class="w">  </span><span class="vi">@ceedling</span><span class="o">[</span><span class="ss">:tool_validator</span><span class="o">].</span><span class="n">validate</span><span class="p">(</span>
+<a id="__codelineno-15-4" name="__codelineno-15-4" href="#__codelineno-15-4"></a><span class="w">    </span><span class="ss">tool</span><span class="p">:</span><span class="w"> </span><span class="no">TOOLS_GCOV_SUMMARY</span><span class="p">,</span><span class="w"> </span><span class="c1"># Tool defintion as Ruby hash</span>
+<a id="__codelineno-15-5" name="__codelineno-15-5" href="#__codelineno-15-5"></a><span class="w">    </span><span class="ss">boom</span><span class="p">:</span><span class="w"> </span><span class="kp">true</span><span class="w">                </span><span class="c1"># Ignore optional status (raise exception if invalid)</span>
+<a id="__codelineno-15-6" name="__codelineno-15-6" href="#__codelineno-15-6"></a><span class="w">  </span><span class="p">)</span>
+<a id="__codelineno-15-7" name="__codelineno-15-7" href="#__codelineno-15-7"></a><span class="k">end</span>
 </code></pre></div>
 <p>The tool <code>TOOLS_GCOV_SUMMARY</code> is defined with a Ruby hash in the plugin code.
 It is configured with <code>:optional =&gt; true</code>. At plugin startup, configuration
@@ -4950,73 +5540,221 @@ utility method is available for this purpose.</p>
 <p><code>@ceedling[:plugin_reportinator].assemble_test_results()</code></p>
 <p>This method takes as an argument a list of results filepaths. These typically
 correspond directly to the collection of test files Ceedling processed in a
-given test build. It's common for this list of filepaths to be assembled from
+given test build. It’s common for this list of filepaths to be assembled from
 the <code>post_test_fixture_execute</code> build step execution hook.</p>
 <p>The data that <code>assemble_test_results()</code> returns has a structure as follows. In
 this example, actual results from a single, real test file are presented as
 hash/array Ruby code with comments and with some edits to reduce line length.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="p">{</span>
-<a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a><span class="w">  </span><span class="c1"># Associates each test executable (i.e. test file) with an execution run time</span>
-<a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a><span class="w">  </span><span class="ss">:times</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a><span class="w">    </span><span class="s2">&quot;test/TestUsartModel.c&quot;</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">21196400001645088</span>
-<a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a><span class="w">  </span><span class="p">},</span>
-<a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a>
-<a id="__codelineno-12-7" name="__codelineno-12-7" href="#__codelineno-12-7"></a><span class="w">  </span><span class="c1"># List of succeeding test cases, grouped by test file.</span>
-<a id="__codelineno-12-8" name="__codelineno-12-8" href="#__codelineno-12-8"></a><span class="w">  </span><span class="ss">:successes</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-9" name="__codelineno-12-9" href="#__codelineno-12-9"></a><span class="w">    </span><span class="p">{</span>
-<a id="__codelineno-12-10" name="__codelineno-12-10" href="#__codelineno-12-10"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test/TestUsartModel.c&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;TestUsartModel.c&quot;</span><span class="p">},</span>
-<a id="__codelineno-12-11" name="__codelineno-12-11" href="#__codelineno-12-11"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-12" name="__codelineno-12-12" href="#__codelineno-12-12"></a><span class="w">        </span><span class="c1"># If Unity is configured to do so, it will output execution run time for each test case.</span>
-<a id="__codelineno-12-13" name="__codelineno-12-13" href="#__codelineno-12-13"></a><span class="w">        </span><span class="c1"># Ceedling creates a zero entry if the Unity option is not enabled.</span>
-<a id="__codelineno-12-14" name="__codelineno-12-14" href="#__codelineno-12-14"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;testCase1&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">17</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">},</span>
-<a id="__codelineno-12-15" name="__codelineno-12-15" href="#__codelineno-12-15"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;testCase2&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">31</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">}</span>
-<a id="__codelineno-12-16" name="__codelineno-12-16" href="#__codelineno-12-16"></a><span class="w">      </span><span class="o">]</span>
-<a id="__codelineno-12-17" name="__codelineno-12-17" href="#__codelineno-12-17"></a><span class="w">    </span><span class="p">}</span>
-<a id="__codelineno-12-18" name="__codelineno-12-18" href="#__codelineno-12-18"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
-<a id="__codelineno-12-19" name="__codelineno-12-19" href="#__codelineno-12-19"></a>
-<a id="__codelineno-12-20" name="__codelineno-12-20" href="#__codelineno-12-20"></a><span class="w">  </span><span class="c1"># List of failing test cases, grouped by test file.</span>
-<a id="__codelineno-12-21" name="__codelineno-12-21" href="#__codelineno-12-21"></a><span class="w">  </span><span class="ss">:failures</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-22" name="__codelineno-12-22" href="#__codelineno-12-22"></a><span class="w">    </span><span class="p">{</span>
-<a id="__codelineno-12-23" name="__codelineno-12-23" href="#__codelineno-12-23"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test/TestUsartModel.c&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;TestUsartModel.c&quot;</span><span class="p">},</span>
-<a id="__codelineno-12-24" name="__codelineno-12-24" href="#__codelineno-12-24"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-25" name="__codelineno-12-25" href="#__codelineno-12-25"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;testCase3&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">25</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&lt;failure message&gt;&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">}</span>
-<a id="__codelineno-12-26" name="__codelineno-12-26" href="#__codelineno-12-26"></a><span class="w">      </span><span class="o">]</span>
-<a id="__codelineno-12-27" name="__codelineno-12-27" href="#__codelineno-12-27"></a><span class="w">    </span><span class="p">}</span>
-<a id="__codelineno-12-28" name="__codelineno-12-28" href="#__codelineno-12-28"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
-<a id="__codelineno-12-29" name="__codelineno-12-29" href="#__codelineno-12-29"></a>
-<a id="__codelineno-12-30" name="__codelineno-12-30" href="#__codelineno-12-30"></a><span class="w">  </span><span class="c1"># List of ignored test cases, grouped by test file.</span>
-<a id="__codelineno-12-31" name="__codelineno-12-31" href="#__codelineno-12-31"></a><span class="w">  </span><span class="ss">:ignores</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-32" name="__codelineno-12-32" href="#__codelineno-12-32"></a><span class="w">    </span><span class="p">{</span>
-<a id="__codelineno-12-33" name="__codelineno-12-33" href="#__codelineno-12-33"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test/TestUsartModel.c&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;TestUsartModel.c&quot;</span><span class="p">},</span>
-<a id="__codelineno-12-34" name="__codelineno-12-34" href="#__codelineno-12-34"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-35" name="__codelineno-12-35" href="#__codelineno-12-35"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;testCase4&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">39</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">}</span>
-<a id="__codelineno-12-36" name="__codelineno-12-36" href="#__codelineno-12-36"></a><span class="w">      </span><span class="o">]</span>
-<a id="__codelineno-12-37" name="__codelineno-12-37" href="#__codelineno-12-37"></a><span class="w">    </span><span class="p">}</span>
-<a id="__codelineno-12-38" name="__codelineno-12-38" href="#__codelineno-12-38"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
-<a id="__codelineno-12-39" name="__codelineno-12-39" href="#__codelineno-12-39"></a>
-<a id="__codelineno-12-40" name="__codelineno-12-40" href="#__codelineno-12-40"></a><span class="w">  </span><span class="c1"># List of strings printed to $stdout, grouped by test file.</span>
-<a id="__codelineno-12-41" name="__codelineno-12-41" href="#__codelineno-12-41"></a><span class="w">  </span><span class="ss">:stdout</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-42" name="__codelineno-12-42" href="#__codelineno-12-42"></a><span class="w">    </span><span class="p">{</span>
-<a id="__codelineno-12-43" name="__codelineno-12-43" href="#__codelineno-12-43"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test/TestUsartModel.c&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;test&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;TestUsartModel.c&quot;</span><span class="p">},</span>
-<a id="__codelineno-12-44" name="__codelineno-12-44" href="#__codelineno-12-44"></a><span class="w">      </span><span class="c1"># Calls to print to $stdout are outside Unity&#39;s scope, preventing attaching test file line numbers</span>
-<a id="__codelineno-12-45" name="__codelineno-12-45" href="#__codelineno-12-45"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
-<a id="__codelineno-12-46" name="__codelineno-12-46" href="#__codelineno-12-46"></a><span class="w">        </span><span class="s2">&quot;&lt;$stdout string (e.g. printf() call)&gt;&quot;</span>
-<a id="__codelineno-12-47" name="__codelineno-12-47" href="#__codelineno-12-47"></a><span class="w">      </span><span class="o">]</span>
-<a id="__codelineno-12-48" name="__codelineno-12-48" href="#__codelineno-12-48"></a><span class="w">    </span><span class="p">}</span>
-<a id="__codelineno-12-49" name="__codelineno-12-49" href="#__codelineno-12-49"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
-<a id="__codelineno-12-50" name="__codelineno-12-50" href="#__codelineno-12-50"></a>
-<a id="__codelineno-12-51" name="__codelineno-12-51" href="#__codelineno-12-51"></a><span class="w">  </span><span class="c1"># Test suite run stats</span>
-<a id="__codelineno-12-52" name="__codelineno-12-52" href="#__codelineno-12-52"></a><span class="w">  </span><span class="ss">:counts</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-12-53" name="__codelineno-12-53" href="#__codelineno-12-53"></a><span class="w">    </span><span class="ss">:total</span><span class="w">   </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span>
-<a id="__codelineno-12-54" name="__codelineno-12-54" href="#__codelineno-12-54"></a><span class="w">    </span><span class="ss">:passed</span><span class="w">  </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span>
-<a id="__codelineno-12-55" name="__codelineno-12-55" href="#__codelineno-12-55"></a><span class="w">    </span><span class="ss">:failed</span><span class="w">  </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
-<a id="__codelineno-12-56" name="__codelineno-12-56" href="#__codelineno-12-56"></a><span class="w">    </span><span class="ss">:ignored</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
-<a id="__codelineno-12-57" name="__codelineno-12-57" href="#__codelineno-12-57"></a><span class="w">    </span><span class="ss">:stdout</span><span class="w">  </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">1</span><span class="p">},</span>
-<a id="__codelineno-12-58" name="__codelineno-12-58" href="#__codelineno-12-58"></a>
-<a id="__codelineno-12-59" name="__codelineno-12-59" href="#__codelineno-12-59"></a><span class="w">  </span><span class="c1"># The sum of all test file execution run times</span>
-<a id="__codelineno-12-60" name="__codelineno-12-60" href="#__codelineno-12-60"></a><span class="w">  </span><span class="ss">:total_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">21196400001645088</span>
-<a id="__codelineno-12-61" name="__codelineno-12-61" href="#__codelineno-12-61"></a><span class="p">}</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="p">{</span>
+<a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a><span class="w">  </span><span class="c1"># Associates each test executable (i.e. test file) with an execution run time</span>
+<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a><span class="w">  </span><span class="ss">:times</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-16-4" name="__codelineno-16-4" href="#__codelineno-16-4"></a><span class="w">    </span><span class="s2">"test/TestUsartModel.c"</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">21196400001645088</span>
+<a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a><span class="w">  </span><span class="p">},</span>
+<a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-6"></a>
+<a id="__codelineno-16-7" name="__codelineno-16-7" href="#__codelineno-16-7"></a><span class="w">  </span><span class="c1"># List of succeeding test cases, grouped by test file.</span>
+<a id="__codelineno-16-8" name="__codelineno-16-8" href="#__codelineno-16-8"></a><span class="w">  </span><span class="ss">:successes</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-9" name="__codelineno-16-9" href="#__codelineno-16-9"></a><span class="w">    </span><span class="p">{</span>
+<a id="__codelineno-16-10" name="__codelineno-16-10" href="#__codelineno-16-10"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test/TestUsartModel.c"</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test"</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"TestUsartModel.c"</span><span class="p">},</span>
+<a id="__codelineno-16-11" name="__codelineno-16-11" href="#__codelineno-16-11"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-12" name="__codelineno-16-12" href="#__codelineno-16-12"></a><span class="w">        </span><span class="c1"># If Unity is configured to do so, it will output execution run time for each test case.</span>
+<a id="__codelineno-16-13" name="__codelineno-16-13" href="#__codelineno-16-13"></a><span class="w">        </span><span class="c1"># Ceedling creates a zero entry if the Unity option is not enabled.</span>
+<a id="__codelineno-16-14" name="__codelineno-16-14" href="#__codelineno-16-14"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"testCase1"</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">17</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">},</span>
+<a id="__codelineno-16-15" name="__codelineno-16-15" href="#__codelineno-16-15"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"testCase2"</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">31</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">}</span>
+<a id="__codelineno-16-16" name="__codelineno-16-16" href="#__codelineno-16-16"></a><span class="w">      </span><span class="o">]</span>
+<a id="__codelineno-16-17" name="__codelineno-16-17" href="#__codelineno-16-17"></a><span class="w">    </span><span class="p">}</span>
+<a id="__codelineno-16-18" name="__codelineno-16-18" href="#__codelineno-16-18"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
+<a id="__codelineno-16-19" name="__codelineno-16-19" href="#__codelineno-16-19"></a>
+<a id="__codelineno-16-20" name="__codelineno-16-20" href="#__codelineno-16-20"></a><span class="w">  </span><span class="c1"># List of failing test cases, grouped by test file.</span>
+<a id="__codelineno-16-21" name="__codelineno-16-21" href="#__codelineno-16-21"></a><span class="w">  </span><span class="ss">:failures</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-22" name="__codelineno-16-22" href="#__codelineno-16-22"></a><span class="w">    </span><span class="p">{</span>
+<a id="__codelineno-16-23" name="__codelineno-16-23" href="#__codelineno-16-23"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test/TestUsartModel.c"</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test"</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"TestUsartModel.c"</span><span class="p">},</span>
+<a id="__codelineno-16-24" name="__codelineno-16-24" href="#__codelineno-16-24"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-25" name="__codelineno-16-25" href="#__codelineno-16-25"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"testCase3"</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">25</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"&lt;failure message&gt;"</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">}</span>
+<a id="__codelineno-16-26" name="__codelineno-16-26" href="#__codelineno-16-26"></a><span class="w">      </span><span class="o">]</span>
+<a id="__codelineno-16-27" name="__codelineno-16-27" href="#__codelineno-16-27"></a><span class="w">    </span><span class="p">}</span>
+<a id="__codelineno-16-28" name="__codelineno-16-28" href="#__codelineno-16-28"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
+<a id="__codelineno-16-29" name="__codelineno-16-29" href="#__codelineno-16-29"></a>
+<a id="__codelineno-16-30" name="__codelineno-16-30" href="#__codelineno-16-30"></a><span class="w">  </span><span class="c1"># List of ignored test cases, grouped by test file.</span>
+<a id="__codelineno-16-31" name="__codelineno-16-31" href="#__codelineno-16-31"></a><span class="w">  </span><span class="ss">:ignores</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-32" name="__codelineno-16-32" href="#__codelineno-16-32"></a><span class="w">    </span><span class="p">{</span>
+<a id="__codelineno-16-33" name="__codelineno-16-33" href="#__codelineno-16-33"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test/TestUsartModel.c"</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test"</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"TestUsartModel.c"</span><span class="p">},</span>
+<a id="__codelineno-16-34" name="__codelineno-16-34" href="#__codelineno-16-34"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-35" name="__codelineno-16-35" href="#__codelineno-16-35"></a><span class="w">        </span><span class="p">{</span><span class="ss">:test</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"testCase4"</span><span class="p">,</span><span class="w"> </span><span class="ss">:line</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">39</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w"> </span><span class="ss">:unity_test_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">0</span><span class="p">}</span>
+<a id="__codelineno-16-36" name="__codelineno-16-36" href="#__codelineno-16-36"></a><span class="w">      </span><span class="o">]</span>
+<a id="__codelineno-16-37" name="__codelineno-16-37" href="#__codelineno-16-37"></a><span class="w">    </span><span class="p">}</span>
+<a id="__codelineno-16-38" name="__codelineno-16-38" href="#__codelineno-16-38"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
+<a id="__codelineno-16-39" name="__codelineno-16-39" href="#__codelineno-16-39"></a>
+<a id="__codelineno-16-40" name="__codelineno-16-40" href="#__codelineno-16-40"></a><span class="w">  </span><span class="c1"># List of strings printed to $stdout, grouped by test file.</span>
+<a id="__codelineno-16-41" name="__codelineno-16-41" href="#__codelineno-16-41"></a><span class="w">  </span><span class="ss">:stdout</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-42" name="__codelineno-16-42" href="#__codelineno-16-42"></a><span class="w">    </span><span class="p">{</span>
+<a id="__codelineno-16-43" name="__codelineno-16-43" href="#__codelineno-16-43"></a><span class="w">      </span><span class="ss">:source</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="ss">:file</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test/TestUsartModel.c"</span><span class="p">,</span><span class="w"> </span><span class="ss">:dirname</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"test"</span><span class="p">,</span><span class="w"> </span><span class="ss">:basename</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">"TestUsartModel.c"</span><span class="p">},</span>
+<a id="__codelineno-16-44" name="__codelineno-16-44" href="#__codelineno-16-44"></a><span class="w">      </span><span class="c1"># Calls to print to $stdout are outside Unity’s scope, preventing attaching test file line numbers</span>
+<a id="__codelineno-16-45" name="__codelineno-16-45" href="#__codelineno-16-45"></a><span class="w">      </span><span class="ss">:collection</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="o">[</span>
+<a id="__codelineno-16-46" name="__codelineno-16-46" href="#__codelineno-16-46"></a><span class="w">        </span><span class="s2">"&lt;$stdout string (e.g. printf() call)&gt;"</span>
+<a id="__codelineno-16-47" name="__codelineno-16-47" href="#__codelineno-16-47"></a><span class="w">      </span><span class="o">]</span>
+<a id="__codelineno-16-48" name="__codelineno-16-48" href="#__codelineno-16-48"></a><span class="w">    </span><span class="p">}</span>
+<a id="__codelineno-16-49" name="__codelineno-16-49" href="#__codelineno-16-49"></a><span class="w">  </span><span class="o">]</span><span class="p">,</span>
+<a id="__codelineno-16-50" name="__codelineno-16-50" href="#__codelineno-16-50"></a>
+<a id="__codelineno-16-51" name="__codelineno-16-51" href="#__codelineno-16-51"></a><span class="w">  </span><span class="c1"># Test suite run stats</span>
+<a id="__codelineno-16-52" name="__codelineno-16-52" href="#__codelineno-16-52"></a><span class="w">  </span><span class="ss">:counts</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-16-53" name="__codelineno-16-53" href="#__codelineno-16-53"></a><span class="w">    </span><span class="ss">:total</span><span class="w">   </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span>
+<a id="__codelineno-16-54" name="__codelineno-16-54" href="#__codelineno-16-54"></a><span class="w">    </span><span class="ss">:passed</span><span class="w">  </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span>
+<a id="__codelineno-16-55" name="__codelineno-16-55" href="#__codelineno-16-55"></a><span class="w">    </span><span class="ss">:failed</span><span class="w">  </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
+<a id="__codelineno-16-56" name="__codelineno-16-56" href="#__codelineno-16-56"></a><span class="w">    </span><span class="ss">:ignored</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
+<a id="__codelineno-16-57" name="__codelineno-16-57" href="#__codelineno-16-57"></a><span class="w">    </span><span class="ss">:stdout</span><span class="w">  </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">1</span><span class="p">},</span>
+<a id="__codelineno-16-58" name="__codelineno-16-58" href="#__codelineno-16-58"></a>
+<a id="__codelineno-16-59" name="__codelineno-16-59" href="#__codelineno-16-59"></a><span class="w">  </span><span class="c1"># The sum of all test file execution run times</span>
+<a id="__codelineno-16-60" name="__codelineno-16-60" href="#__codelineno-16-60"></a><span class="w">  </span><span class="ss">:total_time</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="mi">0</span><span class="o">.</span><span class="mi">21196400001645088</span>
+<a id="__codelineno-16-61" name="__codelineno-16-61" href="#__codelineno-16-61"></a><span class="p">}</span>
 </code></pre></div>
+<h2 id="test-results-report-templates">Test results report templates</h2>
+<p>Ceedling renders test results reports from templates. A plugin that prints test
+results supplies a template, and Ceedling compiles these templates with its own
+compiler rather than with ERB.</p>
+<p>ERB was removed as a Ceedling dependency in 1.2.0. The template language Ceedling
+accepts is now a deliberate subset of what ERB accepted. Every template Ceedling
+ships stays within that subset. A template written for an earlier Ceedling works
+unchanged if it does the same.</p>
+<h3 id="supplying-a-template">Supplying a template</h3>
+<p>A <code>ReportTestsStdoutPlugin</code> subclass supplies a template by overriding the private
+<code>load_template</code> method. That method returns the template as a String. The base
+class registers the template during <code>setup()</code> and owns every build step hook, so a
+subclass needs nothing else.</p>
+<p>The default <code>load_template</code> reads <code>assets/test_results.template</code> from the plugin’s
+own root path. It falls back to the historical <code>assets/template.erb</code> name when only
+that older file exists. A plugin shipping the old filename therefore keeps working.</p>
+<p>Every stock stdout report plugin uses the asset file default.
+<code>report_tests_pretty_stdout</code> has an empty subclass body.</p>
+<p>A template can also call its own plugin object. Ceedling’s system objects include
+each loaded plugin, named for it, so a template reaches its plugin as
+<code>@ceedling[:&lt;plugin name&gt;]</code>. <code>report_tests_gtestlike_stdout</code> and
+<code>report_tests_ide_stdout</code> work this way. Their templates hand results to plugin
+methods that build lines in Ruby. That keeps formatting logic testable and
+configurable. Gcov, Bullseye, and Valgrind render test results through whichever
+template is registered, so they get the same lines.</p>
+<p>A plugin can also render a template directly. <code>@ceedling[:plugin_reportinator]</code>
+exposes <code>run_report(template, hash)</code> for this. The Bullseye plugin uses it to
+render its coverage summary from <code>assets/coverage.template</code>.</p>
+<h3 id="supported-syntax">Supported syntax</h3>
+<p>Five constructs are available, and two of them carry nearly every template. A
+percent sign in column zero introduces a line of Ruby. A <code>&lt;%= expression %&gt;</code> tag
+inserts that expression’s value into the output.</p>
+<table>
+<thead>
+<tr>
+<th>Construct</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>% ruby_code</code></td>
+<td>Executes the line as Ruby. Nothing is emitted.</td>
+</tr>
+<tr>
+<td><code>%%</code></td>
+<td>Emits one literal percent sign. Column zero only.</td>
+</tr>
+<tr>
+<td><code>&lt;%= expression %&gt;</code></td>
+<td>Emits the expression, converted with <code>to_s</code>.</td>
+</tr>
+<tr>
+<td><code>&lt;% ruby_code %&gt;</code></td>
+<td>Executes the code. Nothing is emitted.</td>
+</tr>
+<tr>
+<td><code>&lt;%# comment %&gt;</code></td>
+<td>Emits nothing.</td>
+</tr>
+</tbody>
+</table>
+<p>A percent sign is only special in column zero. Whitespace may follow it freely, so
+a template can indent Ruby lines to show nesting. A percent sign anywhere else on a
+line is literal text.</p>
+<p>All Ruby in a template shares one scope. A value assigned on a percent line is
+visible to every later line and tag, including across block boundaries.</p>
+<h3 id="newline-trimming">Newline trimming</h3>
+<p>A line whose first tag opens it and whose last tag closes it contributes no newline
+of its own. Text between those two tags does not change that. Every other line
+keeps its newline. Ceedling’s own templates depend on this behavior to control
+blank lines in report output.</p>
+<h3 id="what-a-template-can-reference">What a template can reference</h3>
+<p>Templates render against <code>PluginReportinator</code>’s own binding. The report data
+arrives as a local named <code>hash</code>. Global constants such as <code>TEST_SYM</code> resolve
+normally.</p>
+<p><code>@ceedling[:plugin_reportinator]</code> exposes several helpers intended for templates.</p>
+<table>
+<thead>
+<tr>
+<th>Helper</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>test_report_preamble(hash)</code></td>
+<td>Returns the counts and banner prefix every stdout report needs.</td>
+</tr>
+<tr>
+<td><code>generate_banner(text)</code></td>
+<td>Formats a section divider.</td>
+</tr>
+<tr>
+<td><code>generate_heading(text)</code></td>
+<td>Formats a heading.</td>
+</tr>
+<tr>
+<td><code>reflow_message(message, continuation_prefix)</code></td>
+<td>Indents the second and later lines of a multi-line message.</td>
+</tr>
+<tr>
+<td><code>decorate_summary_banner(text, failed_count)</code></td>
+<td>Colors a summary banner by outcome.</td>
+</tr>
+</tbody>
+</table>
+<h3 id="unsupported-syntax">Unsupported syntax</h3>
+<p>Four ERB constructs are unavailable. A template relying on any of them needs
+revision.</p>
+<table>
+<thead>
+<tr>
+<th>Construct</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>-%&gt;</code></td>
+<td>Raises <code>SyntaxError</code>. ERB offered this only under a trim mode Ceedling never used.</td>
+</tr>
+<tr>
+<td><code>&lt;%%</code></td>
+<td>Not an escape. The characters are not translated to a literal <code>&lt;%</code>.</td>
+</tr>
+<tr>
+<td>A tag spanning lines</td>
+<td>Raises <code>CeedlingException</code> naming the template line.</td>
+</tr>
+<tr>
+<td>A tag never closed on its line</td>
+<td>Raises <code>CeedlingException</code> naming the template line.</td>
+</tr>
+</tbody>
+</table>
+<p>The last two are deliberate. ERB accepted a multi-line tag. ERB also responded to
+an unclosed tag by treating the rest of the template as Ruby, which produced
+garbled output rather than an error. Naming the offending line is more useful to a
+template author than either behavior.</p>
+<div class="admonition warning">
+<p class="admonition-title">Porting a template written for ERB</p>
+<p>Ceedling’s own templates never used the unsupported constructs above, and
+neither did any template this project has seen. Check a template against the
+table before assuming it needs no changes. A Ruby error inside a template
+reports its location as <code>(ceedling template):&lt;line&gt;</code>, where the line number is
+the template’s own.</p>
+</div>
 <p><br/><br/></p>
@@ -5088,10 +5826,10 @@ hash/array Ruby code with comments and with some edits to reduce line length.</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>