ceedling 1.1.9 → 1.2.0

data/site-local/testing-guide/conventions.html

@@ -89,10 +89,34 @@
     </div>
     <div data-md-component="announce">
       
+        <aside class="md-banner">
+          <div class="md-banner__inner md-grid md-typeset">
+            
+            
+  
+
+          </div>
+          
+        </aside>
+      
     </div>
     
       <div data-md-color-scheme="default" data-md-component="outdated" hidden>
         
+          <aside class="md-banner md-banner--warning">
+            <div class="md-banner__inner md-grid md-typeset">
+              
+  
+    You are not viewing the latest version.
+    <a href="../..">
+      <strong>Click here to go to latest.</strong>
+    </a>
+  
+
+            </div>
+            <script>var el=document.querySelector("[data-md-component=outdated]"),base=new URL(".."),outdated=__md_get("__outdated",sessionStorage,base);!0===outdated&&el&&(el.hidden=!1)</script>
+          </aside>
+        
       </div>
     
     
@@ -332,7 +356,7 @@
     
     
       <li class="md-tabs__item">
-        <a href="../project/release-history.html" class="md-tabs__link">
+        <a href="../project/index.html" class="md-tabs__link">
           
   
   
@@ -641,6 +665,8 @@
         
       
         
+      
+        
       
         
       
@@ -788,6 +814,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../getting-started/builds.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Builds
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -814,7 +868,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_5" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_6" >
         
           
           <div class="md-nav__link md-nav__container">
@@ -836,14 +890,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_3_5" id="__nav_3_5_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_3_6" id="__nav_3_6_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_5_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3_5">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_6_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3_6">
             <span class="md-nav__icon md-icon"></span>
             
   
@@ -1199,6 +1253,45 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#distinguishing-same-named-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Distinguishing same-named files
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Distinguishing same-named files">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#header-source-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Header / source files
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#test-files-cli-test-tasks" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Test files (CLI test tasks)
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -1305,6 +1398,50 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#preprocessing-for-include-directives" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Preprocessing for include directives
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#preprocessing-for-tests-and-mocks" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Preprocessing for tests and mocks
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#preprocessing-for-partials" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Preprocessing for Partials
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#fallback-test-build-preprocessing" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Fallback test build preprocessing
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -1404,23 +1541,6 @@
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Dependency tracking">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#not-so-smart-rebuilds" class="md-nav__link">
-    <span class="md-ellipsis">
-      
-        (Not so) smart rebuilds
-      
-    </span>
-  </a>
-  
-</li>
-        
-      </ul>
-    </nav>
-  
 </li>
       
         <li class="md-nav__item">
@@ -2759,6 +2879,8 @@
         
       
         
+      
+        
       
         
       
@@ -3390,8 +3512,61 @@
   
   
     <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">
@@ -3401,6 +3576,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>
   
   
@@ -3411,6 +3630,14 @@
 
               
             
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
               
                 
   
@@ -3880,6 +4107,12 @@
     
       
         
+          
+        
+      
+        
+      
+        
       
         
       
@@ -3899,8 +4132,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">
@@ -3914,8 +4148,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">
@@ -3929,6 +4169,8 @@
           <ul class="md-nav__list" data-md-scrollfix>
             
               
+            
+              
                 
   
   
@@ -3962,6 +4204,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">
         
@@ -4033,6 +4303,8 @@
       
         
       
+        
+      
         
       
     
@@ -4123,6 +4395,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../development/releases.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Branching & Releases
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -4149,7 +4449,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10_4" >
         
           
           <div class="md-nav__link md-nav__container">
@@ -4171,14 +4471,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_10_3" id="__nav_10_3_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_10_4" id="__nav_10_4_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_10_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_10_3">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_10_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_10_4">
             <span class="md-nav__icon md-icon"></span>
             
   
@@ -4324,6 +4624,45 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#distinguishing-same-named-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Distinguishing same-named files
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Distinguishing same-named files">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#header-source-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Header / source files
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#test-files-cli-test-tasks" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Test files (CLI test tasks)
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -4430,6 +4769,50 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#preprocessing-for-include-directives" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Preprocessing for include directives
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#preprocessing-for-tests-and-mocks" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Preprocessing for tests and mocks
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#preprocessing-for-partials" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Preprocessing for Partials
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#fallback-test-build-preprocessing" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Fallback test build preprocessing
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -4529,23 +4912,6 @@
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Dependency tracking">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#not-so-smart-rebuilds" class="md-nav__link">
-    <span class="md-ellipsis">
-      
-        (Not so) smart rebuilds
-      
-    </span>
-  </a>
-  
-</li>
-        
-      </ul>
-    </nav>
-  
 </li>
       
         <li class="md-nav__item">
@@ -4678,10 +5044,10 @@
 
 
 <h1 id="conventions-behaviors">Conventions &amp; Behaviors</h1>
-<p><strong>How to get things done and understand what's happening during builds</strong></p>
+<p><strong>How to get things done and understand what’s happening during builds</strong></p>
 <h2 id="directory-structure-filenames">Directory structure &amp; filenames</h2>
-<p>Much of Ceedling's functionality is driven by collecting files
-matching certain patterns inside the paths it's configured
+<p>Much of Ceedling’s functionality is driven by collecting files
+matching certain patterns inside the paths it’s configured
 to search. See the documentation for the <code>:extension</code> section
 of your configuration file (found in the <a href="../configuration/index.html">configuration reference</a>) to
 configure the file extensions Ceedling uses to match and collect
@@ -4689,14 +5055,70 @@ files. Test file naming is covered later in this section.</p>
 <p>Test files and source files must be segregated by directories.
 Any directory structure will do. Tests can be held in subdirectories
 within source directories, or tests and source directories
-can be wholly separated at the top of your project's directory
+can be wholly separated at the top of your project’s directory
 tree.</p>
+<h2 id="distinguishing-same-named-files">Distinguishing same-named files</h2>
+<h3 id="header-source-files">Header / source files</h3>
+<p>Ceedling distinguishes files by their full relative path, not just their
+filename. A project may have, for example, both <code>src/drivers/uart.c</code> and
+<code>src/sensors/uart.c</code> without one hiding or colliding with the other.</p>
+<p>Distinguishing files is mostly an issue in test builds. If two files share
+a name without enough path to distinguish them, Ceedling resolves the reference 
+to the first match among the file collection. File collections are ordered per
+your project configuration (<code>:paths</code>). The ordering of collected files is
+identical to the search path ordering provided to the compiler from the same
+<code>:paths</code> configuration plus any use of
+<a href="build-directives.html#test_include_path"><code>TEST_INCLUDE_PATH()</code></a> directives in
+a test file. When Ceedling finds more than one reference, it uses the first
+in the ordered file list but logs an informational notice naming multi-file 
+matches, so the choice is not silent.</p>
+<p>If Ceedling uses the wrong match for lack of path information, your test build 
+fails downstream with an ordinary compilation error indirectly revealing the
+issue. Add enough path at the point of reference to select the file you actually 
+meant.</p>
+<ul>
+<li>Use paths in <code>#include</code> directives in your test files to distinguish header 
+  files of the same name (mocks are distiguished by the same filepath as the 
+  headers from which they are generated). Examples: <code>#include "foo/bar/file.h"</code>
+  and/or <code>#include "foo/bar/mock_file.h"</code>.</li>
+<li>Use the <a href="build-directives.html"><code>TEST_SOURCE_FILE()</code> build directive macro</a>
+  to provide a path to distinguish source files of the same name to be 
+  compiled and linked with a test executable.</li>
+</ul>
+<div class="admonition tip">
+<p class="admonition-title">Mocking two same-named headers in one test file</p>
+<p>Include each mock through its folder, as in <code>#include "drivers/uart/mock_config.h"</code>
+and <code>#include "drivers/spi/mock_config.h"</code>. With
+<a href="../configuration/reference/cmock.html#mock_name_include_folder"><code>:cmock</code> ↳ <code>:mock_name_include_folder</code></a>,
+enabled by default, each mock is named by that folder, and the two do not collide.</p>
+</div>
+<p><code>TEST_SOURCE_FILE()</code> also takes precedence over the header/source correspondence
+convention above. If a test both <code>#include</code>s a header and separately names a
+same-named source via <code>TEST_SOURCE_FILE()</code>, the directive’s own path wins outright
+— its source is the one compiled, and the header/source convention does not also
+compile whatever it would otherwise have found on its own for that same name. This
+holds even when the header’s own <code>#include</code> was already unambiguous; a
+<code>TEST_SOURCE_FILE()</code> entry sharing that basename is always authoritative. (The
+header itself is still validated/resolved as usual — only which <em>source</em> file gets
+compiled for a shared basename is affected.) Like the search-path resolution
+above, this override is logged with an informational notice naming the winning
+<code>TEST_SOURCE_FILE()</code> entry and the <code>#include</code> it overrode, so the substitution
+is not silent either.</p>
+<h3 id="test-files-cli-test-tasks">Test files (CLI test tasks)</h3>
+<p>Execute <a href="../getting-started/command-line.html"><code>ceedling test:</code> tasks</a> at the command line with an
+optional partial path to distinguish test executables (e.g. <code>test:foo/bar.c</code>),
+recalling that multiple conventions exist for finding/executing a test
+executable via <code>test:</code> task.</p>
+<p>Unlike the cases above, a same-named test file given at the command line is 
+<strong>not</strong> auto-resolved. You must supply enough path yourself in the task
+name. Ceedling will complain about colliding task names and provide a list
+of matching candidates to help you provide path to disambiguate test files.</p>
 <h2 id="test-build-search-paths">Test build search paths</h2>
 <p>Test builds in C are fairly complex. Each test file becomes a test
 executable. Each test executable needs generated runner code and 
 optionally generated mocks. Slicing and dicing what files are 
 compiled and linked and how search paths are assembled is tricky
-business. That's why Ceedling exists in the first place. Because
+business. That’s why Ceedling exists in the first place. Because
 of these issues, search paths, in particular, require quite a bit
 of special handling.</p>
 <p>Unless your project is relying exclusively on <code>extern</code> statements and
@@ -4734,8 +5156,8 @@ it is assembled from a variety of sources. In order:</p>
 <li><code>:paths</code> ↳ <code>:support</code> list from your project configuration</li>
 <li><code>:paths</code> ↳ <code>:include</code> list from your project configuration</li>
 <li><code>:paths</code> ↳ <code>:libraries</code> list from your project configuration</li>
-<li>Internal path for Unity's unit test framework C code</li>
-<li>Internal paths for CMock's C code (if respective feature enabled)</li>
+<li>Internal path for Unity’s unit test framework C code</li>
+<li>Internal paths for CMock’s C code (if respective feature enabled)</li>
 <li><code>:paths</code> ↳ <code>:test_toolchain_include</code> list from your project 
    configuration</li>
 </ol>
@@ -4776,7 +5198,7 @@ source file is compiled into an object file. All object files are linked.
 A Ceedling release build may optionally compile and link in CException
 and can handle linking in libraries as well.</p>
 <p>Search paths for release builds are configured with <code>:paths</code> ↳ <code>:include</code> 
-in your project configuration. That's about all there is to it.</p>
+in your project configuration. That’s about all there is to it.</p>
 <h2 id="source-files-release-artifacts">Source files &amp; release artifacts</h2>
 <p>Your binary release artifact results from the compilation and
 linking of all source files Ceedling finds in the specified source
@@ -4800,6 +5222,38 @@ For example, <code>test_some_super_functionality.c</code>, <code>TestYourSourceF
 or <code>testing_MyAwesomeCode.C</code> could each be valid test file
 names. Note, however, that Ceedling can recognize only one test
 file naming convention per project.</p>
+<h4 id="installer-like-test-filenames-on-windows">Installer-like test filenames on Windows</h4>
+<p>On Windows, Ceedling writes a manifest beside each test executable. It lets a
+test executable run whatever its name.</p>
+<p>A test executable is named after its test file. Windows treats an executable
+whose name contains <em>install</em>, <em>setup</em>, <em>update</em>, or <em>patch</em> as an installer.
+The Installer Detection feature of User Account Control (UAC) then demands
+administrator privileges to run it. A test file such as <code>test_setup_parser.c</code>
+would otherwise build a test executable Windows will not run.</p>
+<p>The manifest, <code>&lt;test executable&gt;.manifest</code>, asks Windows to run the executable
+with your own privileges. That turns Installer Detection off for it. When a
+test filename contains one of these words, Ceedling logs a warning noting that
+it generated the manifest.</p>
+<p>Windows ignores a manifest file when the executable already embeds a manifest
+of its own. Whether yours does depends on your toolchain.</p>
+<ul>
+<li><strong>MinGW-w64 GCC from <a href="https://www.msys2.org">MSYS2</a></strong> links a default manifest into every executable
+  when its <code>windows-default-manifest</code> package is installed. That manifest
+  already asks Windows to run the executable with your own privileges, so
+  these names cause no trouble, and the manifest file is unused. This GCC is
+  also the one RubyInstaller’s DevKit provides.</li>
+<li><strong>Other MinGW-w64 distributions</strong> may or may not include that default
+  manifest. GCC links it only when it finds <code>default-manifest.o</code> among its
+  libraries. Without it, the manifest file Ceedling writes is what lets these
+  test executables run.</li>
+<li><strong>The original MinGW</strong> (mingw.org) is believed to embed no manifest, so it
+  relies on the manifest file.</li>
+</ul>
+<p>To see whether an executable embeds a manifest, search it for the text
+<code>requestedExecutionLevel</code>. A match means Windows uses the embedded manifest.</p>
+<p>Before 1.2.0, Ceedling wrote no manifest. With a toolchain that embeds none,
+test files with these words in their names could not be run on Windows without
+administrator privileges.</p>
 <h3 id="source-mock-files-to-compile-and-link">Source &amp; mock files to compile and link</h3>
 <p>Ceedling knows what files to compile and link into each individual
 test executable by way of the <code>#include</code> list contained in each
@@ -4815,12 +5269,23 @@ test file and optional test directive macros.</p>
    compile &amp; link that generated code into into the test executable 
    as well.</li>
 </ol>
+<p>A mock is generated into the directory mirroring the header it came from, so two
+same-named headers in different directories produce two mocks in different
+directories. A single test file can mock both when it includes each mock through
+its folder (e.g. <code>#include "folder/mock_foo.h"</code>), since each mock is then named 
+by that folder.</p>
 <p>Sometimes the source file you need to add to your test executable has
 no corresponding header file — e.g. <code>file_abc.h</code> contains symbols 
 present in <code>file_xyz.c</code>. In these cases, you can use the test 
 directive macro <code>TEST_SOURCE_FILE(...)</code> to tell Ceedling to compile 
 and link the desired source file into the test executable (see 
 <a href="build-directives.html">macro documentation</a>).</p>
+<p>Conversely, sometimes you may need to remove from a test executable 
+build a source file that corresponds to an <code>#include</code> directive in your
+test file. A <code>TEST_SOURCE_FILE()</code> entry prefixed with a <code>-:</code> decorator 
+removes a named file from a test‘s compile/link list. See 
+<a href="build-directives.html#test_source_file-subtractive-notation"><code>TEST_SOURCE_FILE()</code> Subtractive Notation</a>
+for the full discussion.</p>
 <p>That was a lot of information and many clauses in a very few 
 sentences; the commented example test file code that follows in a 
 bit will make it clearer.</p>
@@ -4847,13 +5312,39 @@ the naming convention of your test case functions.</p>
 <p>Ceedling and CMock are advanced tools that both perform fairly sophisticated
 parsing.</p>
 <p>However, neither of these tools fully understands the entire C language,
-especially C's preprocessing statements.</p>
+especially C’s preprocessing statements.</p>
+<p>Ceedling’s preprocessing features rely on <code>gcc</code>’s preprocessing mode to strip 
+down / expand test files and headers to their raw code content that can then 
+be parsed as text by Ceedling and CMock. These tools must be in your search 
+path if Ceedling’s preprocessing is enabled.</p>
+<p>See the <a href="../configuration/reference/project.html"><code>:project</code> ↳ <code>:use_test_preprocessor</code></a> project 
+configuration setting.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Ceedling’s test preprocessing abilities are directly tied to the features and 
+output of <code>gcc</code>. The default tool definitions for these should not be 
+redefined for other toolchains. Future Ceedling improvements will allow for a 
+plugin-style ability to use your own tools in this highly specialized capacity.</p>
+</div>
+<h3 id="preprocessing-for-include-directives">Preprocessing for include directives</h3>
+<p>In order for Ceedling to do its job, it needs an accurate picture of <code>#include</code>
+directives used by mockable headers and test files. For simple projects, this can
+be done with simple text scanning.</p>
+<p>For projects with conditional compilation (e.g. <code>#ifdef</code>) around include 
+directives or include directives with macros as targets, preprocessing is required.
+Ceedling uses various passes of preprocessor modes to successfully extract
+<code>#include</code> directives.</p>
+<p>A test file’s <code>#include</code> directives are extracted with the preprocessor only when
+test files are preprocessed, with <code>:use_test_preprocessor</code> set to <code>:tests</code> or <code>:all</code>.
+With <code>:mocks</code>, only mockable headers are preprocessed, and a test file’s
+<code>#include</code> directives come from text scanning.</p>
+<h3 id="preprocessing-for-tests-and-mocks">Preprocessing for tests and mocks</h3>
 <p>If your test files rely on macros and <code>#ifdef</code> conditionals used in certain
-ways (see examples below), there's a chance that Ceedling will break on trying
+ways (see examples below), there’s a chance that Ceedling will break on trying
 to process your test files, or, alternatively, your test suite will build but 
 not execute as expected.</p>
 <p>Similarly, generating mocks of header files with macros and <code>#ifdef</code>
-conditionals around or in function signatures can get weird. Of course, it's 
+conditionals around or in function signatures can get weird. Of course, it’s 
 often in sophisticated projects with complex header files that mocking is most 
 desired in the first place.</p>
 <p>Ceedling includes an optional ability to preprocess the following files before 
@@ -4863,38 +5354,60 @@ then extracting test cases and functions to be mocked with text parsing.</p>
 <li>Mockable header files, or</li>
 <li>Both of the above </li>
 </ol>
-<p>See the <a href="../configuration/reference/project.html"><code>:project</code> ↳ <code>:use_test_preprocessor</code></a> project 
-configuration setting.</p>
-<p>This Ceedling feature uses <code>gcc</code>'s preprocessing mode and the <code>cpp</code> preprocessor 
-tool to strip down / expand test files and headers to their raw code content 
-that can then be parsed as text by Ceedling and CMock. These tools must be in 
-your search path if Ceedling's preprocessing is enabled.</p>
-<p><strong>Ceedling's test preprocessing abilities are directly tied to the features and 
-output of <code>gcc</code> and <code>cpp</code>. The default Ceedling tool definitions for these should 
-not be redefined for other toolchains. It is highly unlikely to work for you. 
-Future Ceedling improvements will allow for a plugin-style ability to use your 
-own tools in this highly specialized capacity.</strong></p>
+<h3 id="preprocessing-for-partials">Preprocessing for Partials</h3>
+<p>When <a href="partials/index.html">Partials</a> are enabled, Ceedling expands the use of preprocessing
+beyond only include directives, mockable headers, and test files to partialized
+source files as well. In order to extract and surgically alter your source code
+to become a generated Partial, your source code must be run through various passes
+of preprocessig to resolve conditional compilation, expand macros, etc.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The use of Partials automatically enables test preprocessing regardless of 
+your configuration setting and logs the setting update.</p>
+</div>
+<h3 id="fallback-test-build-preprocessing">Fallback test build preprocessing</h3>
+<p>Ceedling depends on the GNU Compiler Collection (<code>gcc</code>) for many of its advanced 
+features (such as in the preceding sections).</p>
+<p>Older versions of <code>gcc</code> or <code>clang</code> standins may not support certain preprocessing
+features Ceedling requires. Ceedling probes for those features; if they are not 
+found then Ceedling falls back to a simpler, best-effort
+<a href="../configuration/reference/test-build.html#preprocess_force_fallback">fallback preprocessing</a>.</p>
+<p>Fallback preprocessing is a best effort with no guarantees. It is not as capable 
+as full preprocessing, but it can usually handle the most common preprocessing 
+needs (i.e. conditional compilation). Ceedling does what it can to find and log 
+issues related to inadequate preprocessing before you get to mysterious 
+compilation errors.</p>
+<div class="admonition tip">
+<p class="admonition-title">Fallback preprocessing for faster test builds</p>
+<p>Ceedling’s internal <a href="../configuration/reference/test-build.html#preprocess_force_fallback">fallback preprocessing mode can be forced</a>,
+and, for <strong><em>some</em></strong> projects this can be a shortcut to running advanced 
+Ceedling features such as Partials with faster builds.</p>
+<p><strong><em>If using Partials, there’s a good chance your code is too complex for fallback preprocessing.</em></strong></p>
+</div>
 <h3 id="limitations-gotchas">Limitations &amp; gotchas</h3>
 <h4 id="preprocessing-limitations-cheatsheet">Preprocessing limitations cheatsheet</h4>
-<p>Ceedling's preprocessing abilities are generally quite useful — especially in 
+<p>Ceedling’s preprocessing abilities are generally quite useful — especially in 
 projects with multiple build configurations for different feature sets or 
 multiple targets, legacy code that cannot be refactored, and complex header 
 files provided by vendors.</p>
-<p>However, best applying Ceedling's preprocessing abilities requires understanding 
+<p>However, best applying Ceedling’s preprocessing abilities requires understanding 
 how the feature works, when to use it, and its limitations.</p>
-<p>At a high level, Ceedling's preprocessing is applicable for cases where macros 
+<p>At a high level, Ceedling’s preprocessing is applicable for cases where macros 
 or conditional compilation preprocessing statements (e.g. <code>#ifdef</code>):</p>
 <ul>
 <li>Generate or hide/reveal your test files' <code>#include</code> statements.</li>
 <li>Generate or hide/reveal your test files' test case function signatures 
-  (e.g. <code>void test_foo()</code>.</li>
+  (e.g. <code>void test_foo()</code>).</li>
 <li>Generate or hide/reveal mockable header files' <code>#include</code> statements.</li>
 <li>Generate or hide/reveal header files' mockable function signatures.</li>
 </ul>
-<p><strong><em>NOTE:</em> You do not necessarily need to enable Ceedling's preprocessing only
-because you have preprocessing statements in your test files or mockable header 
-files. The feature is only truly needed if your project meets the conditions 
-above.</strong></p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>You do not necessarily need to enable Ceedling’s preprocessing only
+because you have preprocessing statements in your test files or mockable
+header files. The feature is only truly needed if your project meets the 
+conditions above.</p>
+</div>
 <p>The sections that follow flesh out the details of the bulleted list above.</p>
 <h4 id="preprocessing-gotchas">Preprocessing gotchas</h4>
 <h5 id="test_include_path-incompatibe-with-ifdef"><code>TEST_INCLUDE_PATH()</code> incompatibe with <code>#ifdef</code></h5>
@@ -4909,7 +5422,7 @@ statements.</p>
 for advanced abilities discovered by Ceedling parsing a test file as plain text.
 Whether or not Ceedling preprocessing is enabled, Ceedling will always discover 
 this marker macro in the plain text of a test file.</p>
-<p>Why is <code>TEST_INCLUDE_PATH()</code> incompatible with <code>#ifdef</code>? Well, it's because of
+<p>Why is <code>TEST_INCLUDE_PATH()</code> incompatible with <code>#ifdef</code>? Well, it’s because of
 a cyclical dependency that cannot be resolved. In order to perform test 
 preprocessing, we need a full complement of <code>#include</code> search paths. These 
 could be provided, in part, by <code>TEST_INCLUDE_PATH()</code>. But, if we allow 
@@ -4921,7 +5434,7 @@ plain text looking for this macro at the beginning of a test build.</p>
 <ul>
 <li><code>TEST_SOURCE_FILE()</code> <em>can</em> be placed within conditional compilation
   C preprocessing statements.</li>
-<li><code>TEST_INCLUDE_PATH()</code> &amp; <code>TEST_SOURCE_FILE()</code> can be “hidden” from Ceedling's
+<li><code>TEST_INCLUDE_PATH()</code> &amp; <code>TEST_SOURCE_FILE()</code> can be “hidden” from Ceedling’s
   text scanning with traditional C comments.</li>
 </ul>
 <h3 id="test-file-preprocessing">Test file preprocessing</h3>
@@ -4930,9 +5443,9 @@ statements in test files before extracting <code>#include</code> conventions and
 signatures. That is, preprocessing output is used to generate test runners 
 and assemble the components of a test executable build.</p>
 <div class="admonition tip">
-<p class="admonition-title">Preprocessing Not Needed Inside Test Functions</p>
+<p class="admonition-title">Preprocessing not needed inside test functions</p>
 <p>Conditional directives <em>inside</em> test case functions generally do not require
-Ceedling's test preprocessing ability. Assuming your code is correct, the C
+Ceedling’s test preprocessing ability. Assuming your code is correct, the C
 preprocessor within your toolchain will do the right thing for you in your
 test build. Read on for more details and the other cases of interest.</p>
 </div>
@@ -4941,17 +5454,17 @@ preprocessor directives generate the <code>#include</code> statements for your t
 and/or generate or enclose full test case functions. Ceedling will not be able 
 to properly discover your <code>#include</code> statements or test case functions unless 
 they are plainly available in an expanded, raw code version of your test file. 
-Ceedling's preprocessing abilities provide that expansion.</p>
+Ceedling’s preprocessing abilities provide that expansion.</p>
 <h4 id="examples-of-when-ceedling-preprocessing-is-needed-for-test-files">Examples of when Ceedling preprocessing <strong><em>is</em></strong> needed for test files</h4>
 <p>Generally, Ceedling preprocessing is needed when:</p>
 <ol>
-<li><code>#include</code> statements are generated by macros</li>
+<li><code>#include</code> directives targets are macros</li>
 <li><code>#include</code> statements are conditionally present due to <code>#ifdef</code> statements</li>
 <li>Test case function signatures are generated by macros</li>
 <li>Test case function signatures are conditionaly present due to <code>#ifdef</code> statements</li>
 </ol>
-<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">// #include conventions are not recognized for anything except #include &quot;...&quot; statements</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="n">INCLUDE_STATEMENT_MAGIC</span><span class="p">(</span><span class="s">&quot;header_file&quot;</span><span class="p">)</span>
+<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">// #include directive targeting a macor</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="cp">#include INCLUDE_STATEMENT_MAGIC(&quot;header_file&quot;)</span>
 </code></pre></div>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="c1">// Test file scanning will always see this #include statement</span>
 <a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="cp">#ifdef BUILD_VARIANT_A</span>
@@ -4970,29 +5483,57 @@ Ceedling's preprocessing abilities provide that expansion.</p>
 <a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="w">   </span><span class="n">TEST_ASSERT_EQUALS</span><span class="p">(...);</span>
 <a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="p">}</span>
 </code></pre></div></p>
+<h4 id="where-the-macros-deciding-an-include-come-from">Where the macros deciding an <code>#include</code> come from</h4>
+<p>With test preprocessing, a conditional <code>#include</code> (item 2 above) is decided by the same
+macros your compiler will see, wherever they are defined. A macro may come from your
+project’s <code>:defines</code>, from the test file itself, or from a header the test file includes.
+That header can even be one the test file mocks, since a mock includes its real header.</p>
+<p><div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="c1">// config.h</span>
+<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="cp">#define FEATURE_X_ENABLED</span>
+</code></pre></div>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="c1">// test_feature.c</span>
+<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;mock_config.h&quot;</span><span class="c1">     // The mock includes config.h, defining FEATURE_X_ENABLED</span>
+<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>
+<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="cp">#ifdef FEATURE_X_ENABLED</span>
+<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;mock_feature_x.h&quot;</span><span class="c1">  // Ceedling finds and generates this mock</span>
+<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="cp">#endif</span>
+</code></pre></div></p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>One combination is out of reach. An <code>#include</code> whose target is a macro (item 1
+above) cannot name a mock when only a header defines that macro. Define the macro
+under <code>:defines</code> ↳ <code>:test</code> instead, so the test file sees it directly.</p>
+</div>
+<p><div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="c1">// config.h</span>
+<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="cp">#define FEATURE_MOCK &quot;mock_feature_x.h&quot;</span>
+</code></pre></div>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="c1">// test_feature.c</span>
+<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="cp">#include</span><span class="w"> </span><span class="cpf">&quot;config.h&quot;</span>
+<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="cp">#include FEATURE_MOCK  </span><span class="c1">// Ceedling cannot find this mock</span>
+</code></pre></div></p>
 <h4 id="examples-of-when-test-preprocessing-is-not-needed-for-test-files">Examples of when test preprocessing is <strong><em>not</em></strong> needed for test files</h4>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="c1">// Code inside a test case is simply code that your toolchain will expand and build as you desire</span>
-<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="c1">// You can manage your compile time symbols with the :defines section of your project configuration file</span>
-<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="kt">void</span><span class="w"> </span><span class="nf">test_some_test_case</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
-<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="cp">#ifdef BUILD_VARIANT_A</span>
-<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w">   </span><span class="n">TEST_ASSERT_EQUALS</span><span class="p">(...);</span>
-<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="cp">#endif</span>
-<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a>
-<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a><span class="cp">#ifdef BUILD_VARIANT_B</span>
-<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a><span class="w">   </span><span class="n">TEST_ASSERT_EQUALS</span><span class="p">(...);</span>
-<a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a><span class="cp">#endif</span>
-<a id="__codelineno-4-11" name="__codelineno-4-11" href="#__codelineno-4-11"></a><span class="p">}</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="c1">// Code inside a test case is simply code that your toolchain will expand and build as you desire</span>
+<a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a><span class="c1">// You can manage your compile time symbols with the :defines section of your project configuration file</span>
+<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="kt">void</span><span class="w"> </span><span class="nf">test_some_test_case</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="cp">#ifdef BUILD_VARIANT_A</span>
+<a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="w">   </span><span class="n">TEST_ASSERT_EQUALS</span><span class="p">(...);</span>
+<a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a><span class="cp">#endif</span>
+<a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a>
+<a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a><span class="cp">#ifdef BUILD_VARIANT_B</span>
+<a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a><span class="w">   </span><span class="n">TEST_ASSERT_EQUALS</span><span class="p">(...);</span>
+<a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a><span class="cp">#endif</span>
+<a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a><span class="p">}</span>
 </code></pre></div>
 <h3 id="header-file-preprocessing">Header file preprocessing</h3>
 <p>When preprocessing is enabled for mocking, Ceedling will expand preprocessor 
 statements in header files before generating mocks from them. CMock requires
 a clear look at function definitions and types in order to do its work.</p>
 <p>Header files with preprocessor directives and conditional macros can easily
-obscure details from CMock's limited C parser. Advanced C projects tend
+obscure details from CMock’s limited C parser. Advanced C projects tend
 to rely on preprocessing directives and macros to accomplish everything from
 build variants to OS calls to register access to managing proprietary language
 extensions.</p>
-<p>Mocking is often most useful in complicated codebases. As such Ceedling's 
+<p>Mocking is often most useful in complicated codebases. As such Ceedling’s 
 preprocessing abilities tend to be quite necessary to properly expand header
 files so CMock can parse them.</p>
 <h4 id="examples-of-when-ceedling-preprocessing-is-needed-for-mockable-headers">Examples of when Ceedling preprocessing <strong><em>is</em></strong> needed for mockable headers</h4>
@@ -5006,15 +5547,15 @@ files so CMock can parse them.</p>
 <p><strong><em>Important Notes:</em></strong></p>
 <ul>
 <li>
-<p>Sometimes CMock's parsing features can be configured to handle scenarios
+<p>Sometimes CMock’s parsing features can be configured to handle scenarios
   that fall within (3) above. CMock can match and remove most text strings,
   match and replace certain text strings, map custom types to mockable 
   alternatives, and be extended with a Unity helper to handle complex and 
-  compound types. See <a href="http://github.com/ThrowTheSwitch/CMock">CMock</a>'s documentation for more.</p>
+  compound types. See <a href="http://github.com/ThrowTheSwitch/CMock">CMock</a>’s documentation for more.</p>
 </li>
 <li>
 <p>Test preprocessing causes any macros or symbols in a mockable header to 
-  "disappear" in the generated mock. It's quite common to have needed symbols
+  "disappear" in the generated mock. It’s quite common to have needed symbols
   or macros in a header file that do not directly impact the function 
   signatures to be mocked. This can break compilation of your test suite.</p>
 </li>
@@ -5022,21 +5563,21 @@ files so CMock can parse them.</p>
 <p>Possible solutions to this problem include:</p>
 <div class="highlight"><pre><span></span><code>1. Move symbols and macros in your header file that do not impact function 
   signatures to another source header file that will not be filtered
-  by Ceedling&#39;s header file preprocessing.
+  by Ceedling’s header file preprocessing.
 1. If (1) is not possible, you may duplicate the needed symbols and macros
   in a header file that is only available in your test build search paths
   and include it in your test file.
 </code></pre></div>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="c1">// Header file scanning will see this function signature but mistakenly mock the name of the macro</span>
-<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="kt">void</span><span class="w"> </span><span class="nf">FUNCTION_SIGNATURE_MAGIC</span><span class="p">(...);</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="c1">// Header file scanning will see this function signature but mistakenly mock the name of the macro</span>
+<a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a><span class="kt">void</span><span class="w"> </span><span class="nf">FUNCTION_SIGNATURE_MAGIC</span><span class="p">(...);</span>
 </code></pre></div>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="c1">// Header file scanning will always see this function signature</span>
-<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="cp">#ifdef BUILD_VARIANT_A</span>
-<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">someFunction</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
-<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="cp">#endif</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="c1">// Header file scanning will always see this function signature</span>
+<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="cp">#ifdef BUILD_VARIANT_A</span>
+<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">someFunction</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="cp">#endif</span>
 </code></pre></div>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="c1">// Header file scanning will either fail for this function signature or extract erroneous type names</span>
-<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="n">INLINE_MAGIC</span><span class="w"> </span><span class="n">RETURN_TYPE_MAGIC</span><span class="w"> </span><span class="n">someFunction</span><span class="p">(</span><span class="n">PARAMETER_MAGIC</span><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="c1">// Header file scanning will either fail for this function signature or extract erroneous type names</span>
+<a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="n">INLINE_MAGIC</span><span class="w"> </span><span class="n">RETURN_TYPE_MAGIC</span><span class="w"> </span><span class="n">someFunction</span><span class="p">(</span><span class="n">PARAMETER_MAGIC</span><span class="p">);</span>
 </code></pre></div>
 <h2 id="duration-reporting">Duration reporting</h2>
 <h3 id="logged-run-times">Logged run times</h3>
@@ -5044,11 +5585,11 @@ files so CMock can parse them.</p>
 <p>It first logs the set up time necessary to process your project file, parse code
 files, build an internal representation of your project, etc. This duration does
 not capture the time necessary to load the Ruby runtime itself.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>Ceedling set up completed in 223 milliseconds
+<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a>Ceedling set up completed in 223 milliseconds
 </code></pre></div>
 <p>Secondly, each Ceedling run also logs the time necessary to run all the tasks 
 you specify at the command line.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>Ceedling operations completed in 1.03 seconds
+<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>Ceedling operations completed in 1.03 seconds
 </code></pre></div>
 <h3 id="test-suite-executable-durations">Test suite &amp; executable durations</h3>
 <p>A test suite comprises one or more Unity test executables (see 
@@ -5061,8 +5602,8 @@ effort is usually required to map Ceedling duration values to a relevant test
 suite abstraction within a given test report format.</p>
 <p>Because Ceedling can execute builds with multiple threads, care must be taken
 to interpret test suite duration values — particularly in relation to 
-Ceedling's logged run times.</p>
-<p>In a multi-threaded build it's quite common for the logged Ceedling project run
+Ceedling’s logged run times.</p>
+<p>In a multi-threaded build it’s quite common for the logged Ceedling project run
 time to be less than the total suite time in a test report. In multi-threaded 
 builds on multi-core machines, test executables are run on different processors
 simultaneously. As such, the total on-processor time in a test report can 
@@ -5076,13 +5617,13 @@ a in a comparable single-threaded build.</p>
 supports the time mechanism Unity relies on, Ceedling will automatically 
 collect test case time values — generally made use of by test report plugins.</p>
 <p>To enable test case duration measurements, they must be enabled as a Unity
-compilation option. Add <code>UNITY_INCLUDE_EXEC_TIME</code> to Unity's compilation
+compilation option. Add <code>UNITY_INCLUDE_EXEC_TIME</code> to Unity’s compilation
 symbols (<code>:unity</code> ↳ <code>:defines</code>) in your Ceedling project file (see example
 below). Unity test case durations as reported by Ceedling default to 0 if the
 compilation option is not set.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="nt">:unity</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="nt">:defines</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">UNITY_INCLUDE_EXEC_TIME</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="nt">:unity</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="nt">:defines</span><span class="p">:</span>
+<a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">UNITY_INCLUDE_EXEC_TIME</span>
 </code></pre></div>
 <p><em>NOTE:</em> Most test cases are quite short, and most computers are quite fast. As
  such, Unity test case execution time is often reported as 0 milliseconds as
@@ -5090,46 +5631,30 @@ compilation option is not set.</p>
  range. Unity would require special rigging that is inconsistently available
  across platforms to measure test case durations at a finer resolution.</p>
 <h2 id="dependency-tracking">Dependency tracking</h2>
-<p>Previous versions of Ceedling used features of Rake to offer
-various kinds of smart rebuilds — that is, only regenerating files, 
-recompiling code files, or relinking executables when changes within 
-the project had occurred since the last build. Optional Ceedling 
-features discovered “deep dependencies” such that, for example, a 
-change in a header file several nested layers deep in <code>#include</code> 
-statements would cause all the correct test executables to be 
-updated and run.</p>
-<p>These features have been temporarily disabled and/or removed for 
-test suites and remain in limited form for release build while
-Ceedling undergoes a major overhaul.</p>
-<p>Please see the <a href="https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/ReleaseNotes.md">Release Notes</a>.</p>
-<h3 id="not-so-smart-rebuilds">(Not so) smart rebuilds</h3>
-<ul>
-<li>
-<p>New features that are a part of the Ceedling overhaul can 
-  significantly speed up test suite execution and release builds 
-  despite the present behavior of brute force running all build 
-  steps. See the discussion of enabling multi-threaded builds in 
-  later sections.</p>
-</li>
-<li>
-<p>When smart rebuilds return, they will further speed up builds as
-  will other planned optimizations.</p>
-</li>
-</ul>
+<p>Ceedling only regenerates, compiles, links, or runs an element of the build
+pipeline if a change in the dependency tree requires it. This includes “deep
+dependencies” wherein a change in a header file several nested layers deep in
+<code>#include</code> statements correctly triggers a rebuild of every test executable
+that depends on it, directly or indirectly.</p>
+<p>This is called a delta build. Delta builds are automatic, need no
+configuration, and complement Ceedling’s parallel build steps for further
+build time speedups. See <a href="../getting-started/builds.html">Delta Builds</a> for the
+full picture, including how test result caching works and the
+<code>--force-test-rerun</code> flag.</p>
 <h2 id="build-output">Build output</h2>
 <p>Ceedling requires a top-level build directory for all the stuff
 that it, the accompanying test tools, and your toolchain generate.
-That build directory's location is configured in the top-level 
+That build directory’s location is configured in the top-level 
 <code>:project</code> section of your configuration file (discussed in the
 <a href="../configuration/index.html">configuration reference</a>). There
 can be a ton of generated files. By and large, you can live a full
 and meaningful life knowing absolutely nothing at all about
 the files and directories generated below the root build directory.</p>
-<p>As noted already, it's good practice to add your top-level build
+<p>As noted already, it’s good practice to add your top-level build
 directory to source control but nothing generated beneath it.
 you'll spare yourself headache if you let Ceedling delete and
 regenerate files and directories in a non-versioned corner
-of your project's filesystem beneath the top-level build directory.</p>
+of your project’s filesystem beneath the top-level build directory.</p>
 <p>The <code>artifacts/</code> directory is the one and only directory you may
 want to know about beneath the top-level build directory. The
 subdirectories beneath <code>artifacts</code> will hold your binary release
@@ -5167,18 +5692,18 @@ no problem-o. You may be of the mind that running a test suite to
 completion should yield a successful exit code (even if tests failed).
 Add the following to your project file to force Ceedling to finish a 
 build with an exit code of 0 even upon test case failures.</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"># Ceedling terminates with happy `exit(0)` even if test cases fail</span>
-<a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="nt">:test_build</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="nt">:graceful_fail</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</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"># Ceedling terminates with happy `exit(0)` even if test cases fail</span>
+<a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a><span class="nt">:test_build</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="nt">:graceful_fail</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
 </code></pre></div>
 <p>If you use the option for graceful failures in CI, you'll want to
-rig up some kind of logging monitor that scans Ceedling's test
+rig up some kind of logging monitor that scans Ceedling’s test
 summary report sent to <code>$stdout</code> and/or a log file. Otherwise, you
 could have a successful build but failing tests.</p>
 <h3 id="test-executable-exit-codes">Test executable exit codes</h3>
 <p>Ceedling works by collecting multiple Unity test executables together 
 into a test suite (more here: <a href="test-suite-anatomy.html">Anatomy of a Test Suite</a>).</p>
-<p>A Unity test executable's exit code is the number of failed tests. An
+<p>A Unity test executable’s exit code is the number of failed tests. An
 exit code of <code>0</code> means all tests passed while anything larger than zero
 is the number of test failures.</p>
 <p>Because of platform limitations on how big an exit code number can be