ceedling 1.1.10 → 1.2.0

data/site-local/plugins/module-generator.html

@@ -89,10 +89,34 @@
     </div>
     <div data-md-component="announce">
       
+        <aside class="md-banner">
+          <div class="md-banner__inner md-grid md-typeset">
+            
+            
+  
+
+          </div>
+          
+        </aside>
+      
     </div>
     
       <div data-md-color-scheme="default" data-md-component="outdated" hidden>
         
+          <aside class="md-banner md-banner--warning">
+            <div class="md-banner__inner md-grid md-typeset">
+              
+  
+    You are not viewing the latest version.
+    <a href="../..">
+      <strong>Click here to go to latest.</strong>
+    </a>
+  
+
+            </div>
+            <script>var el=document.querySelector("[data-md-component=outdated]"),base=new URL(".."),outdated=__md_get("__outdated",sessionStorage,base);!0===outdated&&el&&(el.hidden=!1)</script>
+          </aside>
+        
       </div>
     
     
@@ -332,7 +356,7 @@
     
     
       <li class="md-tabs__item">
-        <a href="../project/release-history.html" class="md-tabs__link">
+        <a href="../project/index.html" class="md-tabs__link">
           
   
   
@@ -641,6 +665,8 @@
         
       
         
+      
+        
       
         
       
@@ -788,6 +814,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../getting-started/builds.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Builds
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -814,7 +868,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_5" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_6" >
         
           
           <div class="md-nav__link md-nav__container">
@@ -836,14 +890,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_3_5" id="__nav_3_5_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_3_6" id="__nav_3_6_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_5_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3_5">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_6_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3_6">
             <span class="md-nav__icon md-icon"></span>
             
   
@@ -2412,6 +2466,8 @@
         
       
         
+      
+        
       
         
       
@@ -3049,8 +3105,64 @@
   
   
     <li class="md-nav__item">
-      <a href="bullseye.html" class="md-nav__link">
+      <a href="sanitize.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Sanitize (ASan, UBSan & Leaks)
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    
+    
+      
+        
+          
+        
+      
+        
+      
+    
+    
+    
+      
+      
+        
+          
+          
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--section md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6_13" >
         
+          
+          <div class="md-nav__link md-nav__container">
+            <a href="bullseye/index.html" class="md-nav__link ">
+              
   
   
   <span class="md-ellipsis">
@@ -3060,6 +3172,50 @@
   
 
     
+  </span>
+  
+  
+
+            </a>
+            
+              
+              <label class="md-nav__link " for="__nav_6_13" id="__nav_6_13_label" tabindex="">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+            
+          </div>
+        
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_6_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_6_13">
+            <span class="md-nav__icon md-icon"></span>
+            
+  
+    Bullseye (Coverage)
+  
+
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="bullseye/licensing.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Licensing
+  
+
+    
   </span>
   
   
@@ -3070,6 +3226,14 @@
 
               
             
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
               
                 
   
@@ -3282,11 +3446,33 @@
     <nav class="md-nav" aria-label="Paths">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#path-hints" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Path hints
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#adding-to-paths" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Adding to Paths
+        Adding to paths
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#same-named-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Same-named files
       
     </span>
   </a>
@@ -3307,6 +3493,28 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#testing-from-headers" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Testing from headers
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#destroying" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Destroying
+      
+    </span>
+  </a>
+  
 </li>
       
         <li class="md-nav__item">
@@ -3321,6 +3529,28 @@
     <nav class="md-nav" aria-label="Configuration">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#naming-convention" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Naming convention
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#default-paths" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Default paths
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#includes" class="md-nav__link">
     <span class="md-ellipsis">
@@ -3341,13 +3571,24 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#boilerplate-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Boilerplate files
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
   <a href="#test-defines" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Test Defines
+        Test defines
       
     </span>
   </a>
@@ -3355,10 +3596,10 @@
 </li>
         
           <li class="md-nav__item">
-  <a href="#naming-convention" class="md-nav__link">
+  <a href="#test-guards" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Naming Convention
+        Test guards
       
     </span>
   </a>
@@ -3708,6 +3949,12 @@
     
       
         
+          
+        
+      
+        
+      
+        
       
         
       
@@ -3727,8 +3974,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">
@@ -3742,8 +3990,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">
@@ -3757,6 +4011,8 @@
           <ul class="md-nav__list" data-md-scrollfix>
             
               
+            
+              
                 
   
   
@@ -3790,6 +4046,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">
         
@@ -3861,6 +4145,8 @@
       
         
       
+        
+      
         
       
     
@@ -3951,6 +4237,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../development/releases.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Branching & Releases
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -3977,7 +4291,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">
@@ -3999,14 +4313,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>
             
   
@@ -4177,11 +4491,33 @@
     <nav class="md-nav" aria-label="Paths">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#path-hints" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Path hints
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#adding-to-paths" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Adding to Paths
+        Adding to paths
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#same-named-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Same-named files
       
     </span>
   </a>
@@ -4202,6 +4538,28 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#testing-from-headers" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Testing from headers
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#destroying" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Destroying
+      
+    </span>
+  </a>
+  
 </li>
       
         <li class="md-nav__item">
@@ -4216,6 +4574,28 @@
     <nav class="md-nav" aria-label="Configuration">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#naming-convention" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Naming convention
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#default-paths" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Default paths
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#includes" class="md-nav__link">
     <span class="md-ellipsis">
@@ -4236,13 +4616,24 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#boilerplate-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Boilerplate files
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
   <a href="#test-defines" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Test Defines
+        Test defines
       
     </span>
   </a>
@@ -4250,10 +4641,10 @@
 </li>
         
           <li class="md-nav__item">
-  <a href="#naming-convention" class="md-nav__link">
+  <a href="#test-guards" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Naming Convention
+        Test guards
       
     </span>
   </a>
@@ -4334,212 +4725,405 @@
 
 
 <h1 id="module-generator">Module Generator</h1>
-<p>This plugin adds a pair of new commands to Ceedling allowing you to generate or remove 
-module skeletons according to predefined templates.</p>
+<p>This plugin adds commands to Ceedling that create a module’s source, header, and test
+files from templates; remove them again; and stub a source file from its header. Files
+land in your project’s <a href="../configuration/reference/paths.html"><code>:paths</code></a>, guided by optional hints.</p>
 <h2 id="overview">Overview</h2>
-<p>With a single call, Ceedling can generate a source, header, and test file for a new 
-module. If given a pattern, it can even create a series of submodules to support 
-specific design patterns. Finally, it can just as easily remove related modules, 
-avoiding the need to delete each individually.</p>
-<p>Let's say, for example, that you want to create a single module named <code>MadScience</code>.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>ceedling<span class="w"> </span>module:create<span class="o">[</span>MadScience<span class="o">]</span>
+<p>Enable the plugin by adding <code>module_generator</code> to the enabled <a href="../configuration/reference/plugins.html">plugins</a> list in
+your project configuration:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">:plugins</span><span class="p">:</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w">  </span><span class="nt">:enabled</span><span class="p">:</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">module_generator</span>
+</code></pre></div>
+<p>Then a single call creates a new module:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[MadScience]&quot;</span>
+</code></pre></div>
+<p>This creates <code>MadScience.c</code>, <code>MadScience.h</code>, and <code>test_MadScience.c</code>. The test file
+carries your project’s <a href="../configuration/reference/project.html#test_file_prefix"><code>:test_file_prefix</code></a>. Names keep the case you type unless you
+configure a <a href="#naming-convention">naming convention</a>.</p>
+<p>Several modules can be named in one call, separated by commas. Leave no spaces between
+the brackets or rely on surrounding quotes; your shell would otherwise split the command.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[MadScience,EvilGenius,SecretLair]&quot;</span>
 </code></pre></div>
-<p>It says we're speaking to the module plugin, and we want to create a new module. The
-name of that module is between the brackets. It will keep this case, unless you have
-specified a different default (see configuration). It will create three files:
-<code>MadScience.c</code>, <code>MadScience.h</code>, and <code>TestMadScience.c</code>. <em>NOTE</em> that it is important that
-there are no spaces between the brackets. We know, it's annoying... but it's the rules.</p>
+<p>The plugin’s three commands take the same arguments:</p>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Does</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>module:create[...]</code></td>
+<td>Creates each module’s files, skipping any that already exist and stopping when all of them do</td>
+</tr>
+<tr>
+<td><code>module:destroy[...]</code></td>
+<td>Removes each module’s files</td>
+</tr>
+<tr>
+<td><code>module:stub[...]</code></td>
+<td>Writes a source file of function stubs from each module’s header</td>
+</tr>
+<tr>
+<td><code>module:test[...]</code></td>
+<td>Writes a test file with a test for each function in each module’s header</td>
+</tr>
+</tbody>
+</table>
+<p>A name that begins with your test file prefix asks for a test file alone.
+<code>"module:create[test_MadScience]"</code> creates only <code>test_MadScience.c</code>. When the prefix ends
+in a letter or digit, as a prefix of <code>Test</code> does, the character after the prefix must
+not be a lowercase letter or digit. An uppercase letter starts the module name, so
+<code>TestMadScience</code> is a test file for <code>MadScience</code>, while <code>Testimony</code> and <code>Test2Widget</code>
+are modules. A prefix ending in a separator, like the default <code>test_</code>,
+needs no such check.</p>
 <h2 id="patterns">Patterns</h2>
-<p>You can also create an entire pattern of files. To do that, just add a second argument
-to the pattern ID. Something like this:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>ceedling<span class="w"> </span>module:create<span class="o">[</span>SecretLair,mch<span class="o">]</span>
+<p>A pattern creates a set of related modules at once. Name it after the module:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[SecretLair,mch]&quot;</span>
 </code></pre></div>
-<p>In this example, we'd create 9 files total: 3 headers, 3 source files, and 3 test files. These
-files would be named <code>SecretLairModel</code>, <code>SecretLairConductor</code>, and <code>SecretLairHardware</code>. Isn't
-that nice?</p>
+<p>This creates nine files: a source, header, and test file each for <code>SecretLair_Model</code>,
+<code>SecretLair_Conductor</code>, and <code>SecretLair_Hardware</code>. With <code>:naming</code> set to <code>:bumpy</code>, the
+same call creates <code>SecretLairModel</code>, <code>SecretLairConductor</code>, and <code>SecretLairHardware</code>.
+Each generated module includes the headers its role depends on, and each test includes
+the mocks of those headers.</p>
 <p>The module generator understands the following patterns:</p>
 <ul>
-<li><code>src</code> -- generate only a source file</li>
-<li><code>test</code> -- generate only a test file</li>
-<li><code>dh</code> -- generate 6 files for the driver-hardware pattern</li>
-<li><code>dih</code> -- generate 9 files for the driver-interrupt-hardware pattern</li>
-<li><code>mch</code> -- generate 9 files for the model-conductor-hardware pattern</li>
-<li><code>mvp</code> -- generate 9 files for the model-view-presenter pattern</li>
+<li><code>src</code> — a source, header, and test file (the default)</li>
+<li><code>test</code> — only a test file</li>
+<li><code>mch</code> — 9 files for the <a href="https://cdn.prod.website-files.com/628fcc1631ad0b25b32f223e/62e43a26764867e95fe5a138_ESC-413Paper_KarleskyWilliams.pdf">model-conductor-hardware (pdf)</a> pattern (<a href="https://www.methodsandtools.com/archive/archive.php?id=59">html</a>)</li>
+<li><code>mvp</code> — 9 files for the <a href="https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93presenter">model-view-presenter</a> pattern</li>
+<li><code>dh</code> — 6 files for the driver-hardware pattern</li>
+<li><code>dih</code> — 9 files for the driver-interrupt-hardware pattern</li>
 </ul>
+<p>The <code>dh</code> and <code>dih</code> patterns are alternate namings and conceptual organizations of the
+model-conductor-hardware pattern.</p>
+<p>A pattern applies to every module in the call, and a call takes one pattern. The first
+argument is always a module name, even one spelled like a pattern.</p>
 <h2 id="paths">Paths</h2>
-<p>The directories found in the project <code>:paths:</code> are reused. You can also specify an alternative default generation path using: </p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="nt">:module_generator</span><span class="p">:</span>
-<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w">  </span><span class="nt">:path_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/</span>
-<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w">  </span><span class="nt">:path_inc</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/</span>
-<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w">  </span><span class="nt">:path_tst</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test/</span>
+<p>Without any hint, each kind of file goes to the first path listed for it under
+<a href="../configuration/reference/paths.html"><code>:paths</code></a>. Source files go to the first <code>:source</code> path, headers to the first <code>:include</code>
+path, and tests to the first <code>:test</code> path. Headers go with the source when your project
+lists no include paths. To choose other default locations, configure them:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="nt">:module_generator</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="nt">:path_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/</span>
+<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w">  </span><span class="nt">:path_inc</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">include/</span>
+<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w">  </span><span class="nt">:path_tst</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test/</span>
 </code></pre></div>
-<p>But what if I don't want it to place my new files in the default location?</p>
-<p>It can do that too! You can give it a hint as to where to find your files. The pattern matching
-here is fairly basic, but it is usually sufficient. It works perfectly if your directory structure
-matches a common pattern. For example, let's say you issue this command:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>ceedling<span class="w"> </span>module:create<span class="o">[</span>lab:SecretLair,mch<span class="o">]</span>
+<h3 id="path-hints">Path hints</h3>
+<p>A hint before a colon steers a module toward matching paths:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[lab:SecretLair,mch]&quot;</span>
 </code></pre></div>
-<p>Say your directory structure looks like this:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="nt">:paths</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="nt">:source</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lab/src</span>
-<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lair/src</span>
-<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">other/src</span>
-<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="w">  </span><span class="nt">:test</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lab/test</span>
-<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lair/test</span>
-<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">other/test</span>
+<p>The hint is matched separately against your source, include, and test paths, and each
+kind of file goes to the path the hint matches best. A path matches best when its
+trailing folders match the hint. When the hint matches nothing among one kind of path,
+those files go to the first path of that kind. When it matches nothing at all, the
+command stops with an error and creates nothing.</p>
+<p>Say your project lists these paths:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="nt">:paths</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="nt">:source</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lab/src</span>
+<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lair/src</span>
+<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">other/src</span>
+<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a><span class="w">  </span><span class="nt">:test</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lab/test</span>
+<a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lair/test</span>
+<a id="__codelineno-6-9" name="__codelineno-6-9" href="#__codelineno-6-9"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">other/test</span>
 </code></pre></div>
-<p>In this case, the <code>lab:</code> hint would make the module generator guess you want your files here:</p>
+<p>The <code>lab:</code> hint places files here:</p>
 <ul>
-<li>source files: <code>lab/src</code> (because it's a close match)</li>
-<li>include files: <code>lab/src</code> (because no include paths were listed)</li>
-<li>test files: <code>lab/test</code> (because it's a close match)</li>
+<li>source files: <code>lab/src</code> (a close match)</li>
+<li>include files: <code>lab/src</code> (no include paths are listed, so headers go with the source)</li>
+<li>test files: <code>lab/test</code> (a close match)</li>
 </ul>
-<p>Instead, if your directory structure looks like this:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="nt">:paths</span><span class="p">:</span>
-<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w">  </span><span class="nt">:source</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/**</span><span class="w">   </span><span class="c1">#this might contain subfolders lab, lair, and other</span>
-<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w">  </span><span class="nt">:include</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">inc/**</span><span class="w">   </span><span class="c1">#again, this might contain subfolders lab, lair, other, and shared</span>
-<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="w">  </span><span class="nt">:test</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test</span>
+<p>Instead, say your paths look like this:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="nt">:paths</span><span class="p">:</span>
+<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="w">  </span><span class="nt">:source</span><span class="p">:</span>
+<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/**</span><span class="w">   </span><span class="c1"># might contain subfolders lab, lair, and other</span>
+<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="w">  </span><span class="nt">:include</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">inc/**</span><span class="w">   </span><span class="c1"># might contain subfolders lab, lair, other, and shared</span>
+<a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a><span class="w">  </span><span class="nt">:test</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test</span>
 </code></pre></div>
-<p>In this case, the <code>lab:</code> hint would make the module generator guess you want your files here:</p>
+<p>Now the <code>lab:</code> hint places files here:</p>
 <ul>
-<li>source files: <code>src/lab</code> (because it's a close match)</li>
-<li>include files: <code>inc/lab</code> (because it's a close match)</li>
-<li>test files: <code>test</code> (because there wasn't a close match, and this was the first entry on our list)</li>
+<li>source files: <code>src/lab</code> (a close match)</li>
+<li>include files: <code>inc/lab</code> (a close match)</li>
+<li>test files: <code>test</code> (no close match, so the first test path)</li>
 </ul>
-<p>You can see that more complicated structures will have files placed in the wrong place from time to
-time... no worries... you can move the file after it's created... but if your project has any kind of 
-consistent structure, the guessing engine does a good job of making it work.</p>
-<p>A few more quick notes about the path-matching:</p>
+<p>A few more notes about hints:</p>
 <ol>
-<li>
-<p>You can give multiple ordered hints that map roughly to folder nesting! <code>lab:secret:lair</code> will 
-   happily match to put <code>lair.c</code> in a folder like <code>my/lab/secret/</code>.</p>
-</li>
-<li>
-<p>If the matcher isn't given any path information or it finds multiple equally good candidates, 
-   it will always guess in the order you have the paths listed in your project.yml file</p>
-</li>
-<li>
-<p>If the matcher completely fails to find a good candidate, it will return an error, allowing you
-   to rectify the situation.</p>
-</li>
-<li>
-<p>What path is "first" when you're using <code>**</code> pattern in your <code>:paths:</code> specifications? The parent
-   folder is used first, then its children alphabetically, and so on. This is important when 
-   considering where files (or especially subfolders... see below) will be generated.</p>
-</li>
+<li>Several hints narrow the match through nested folders. <code>lab:secret:lair</code> places
+   <code>lair.c</code> in a folder like <code>my/lab/secret/</code>.</li>
+<li>Among equally good matches, and without any hint, the order of your paths in the
+   project file decides.</li>
+<li>With a <code>**</code> glob under <code>:paths</code>, the parent folder comes first, then its
+   subfolders alphabetically, and so on.</li>
+<li>A hint may be an absolute path, including one with a Windows drive letter, as in
+   <code>C:/project/lab:SecretLair</code>.</li>
 </ol>
-<h3 id="adding-to-paths">Adding to Paths</h3>
-<p>In addition to the pattern matching above, you can add slashes (<code>/</code>) to your filename specification.
-When a slash is used instead of a colon (<code>:</code>), it will stop using pattern matching and assume the
-subdirectory is supposed to be there. If the subdir is NOT there, it will automatically add it.</p>
-<p>Let's try an example with our previous path specification:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="nt">:paths</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="nt">:source</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/**</span><span class="w">   </span><span class="c1">#this might contain subfolders lab, lair, and other</span>
-<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="w">  </span><span class="nt">:include</span><span class="p">:</span>
-<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">inc/**</span><span class="w">   </span><span class="c1">#again, this might contain subfolders lab, lair, other, and shared</span>
-<a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a><span class="w">  </span><span class="nt">:test</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test</span>
-</code></pre></div>
-<p>Then, use the following command:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>ceedling<span class="w"> </span>module:create<span class="o">[</span>newlab/SecretLair<span class="o">]</span>
+<p>More complicated structures will sometimes place a file in the wrong folder, and you
+can move it afterward. A project with a consistent structure gets good placement.</p>
+<h3 id="adding-to-paths">Adding to paths</h3>
+<p>A slash in the name, rather than a colon, names a subdirectory to use as given. The
+module generator creates it if it does not exist. With the second set of paths above,
+this call:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[newlab/SecretLair]&quot;</span>
 </code></pre></div>
-<p>This will create the following 3 files:</p>
+<p>creates these files:</p>
 <ul>
 <li><code>src/newlab/SecretLair.c</code></li>
 <li><code>inc/newlab/SecretLair.h</code></li>
-<li><code>test/newlab/TestSecretLair.c</code></li>
+<li><code>test/newlab/test_SecretLair.c</code></li>
 </ul>
-<p>Technically, you can start with a colon and specify part of a path, then use a slash
-to specify the remainder of the path to use. In most circumstances, this should work... however
-it suffers from the same potential issues as the matcher above, with the added joy of creating 
-new subdirectories for you without asking. </p>
-<p>It's important to note the module generator doesn't care if these new subdirectories are covered 
-by the current path specification. This allows you to create the files before updating the
-<code>project.yml</code> file if desired, but it also means you might accidentally think you've created
-a file that Ceedling can see, when it can't. </p>
+<p>A hint and a slash can combine, as in <code>lab:newlab/SecretLair</code>. A hint picks among
+existing paths, and the slash then adds a subdirectory below the chosen path.</p>
+<p>The module generator does not check whether a new subdirectory is covered by your
+<code>:paths</code>. You can create files before updating your project file. You might also create
+a file Ceedling does not see until you add its folder to <code>:paths</code>.</p>
+<h3 id="same-named-files">Same-named files</h3>
+<p><code>module:create</code> warns about each existing source, header, or test file elsewhere in your
+project that shares a name with a file it is about to create, then creates the module.
+Ceedling distinguishes same-named files by their paths, so this is allowed. The warning
+catches the case where you meant to work with the existing module instead.</p>
 <h2 id="stubbing">Stubbing</h2>
-<p>Similarly, you can create stubs for all functions in a header file just by making a single call
-to your handy <code>stub</code> feature, like this:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>ceedling<span class="w"> </span>module:stub<span class="o">[</span>SecretLair<span class="o">]</span>
+<p><code>module:stub</code> writes a source file containing a stub for each function its header
+declares:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:stub[SecretLair]&quot;</span>
 </code></pre></div>
-<p>This call will look in <code>SecretLair.h</code> and will generate a file <code>SecretLair.c</code> that contains a stub
-for each function declared in the header! Even better, if <code>SecretLair.c</code> already exists, it will
-add only new functions, leaving your existing calls alone so that it doesn't cause any problems.</p>
+<p>This reads <code>SecretLair.h</code> from your include path and writes <code>SecretLair.c</code> to your
+source path. If <code>SecretLair.c</code> already exists, only stubs for newly declared functions
+are added, and your existing code is left alone.</p>
+<p>Hints and slashes work as they do for <code>module:create</code>. <code>"module:stub[lab:rev/SecretLair]"</code>
+reads <code>rev/SecretLair.h</code> below the include path <code>lab:</code> matches and writes
+<code>rev/SecretLair.c</code> below the matching source path.</p>
+<p>Headers are parsed with your project’s <a href="../configuration/reference/cmock.html"><code>:cmock</code></a> settings, the same ones that generate
+your mocks, so options like <code>:strippables</code> and <code>:treat_as</code> apply to stubs too.</p>
+<h2 id="testing-from-headers">Testing from headers</h2>
+<p><code>module:test</code> writes a test file containing an ignored test for each function its
+module’s header declares, a starting point for testing a module that already exists:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:test[SecretLair]&quot;</span>
+</code></pre></div>
+<p>This reads <code>SecretLair.h</code> from your include path and writes <code>test_SecretLair.c</code> to your
+test path, with a <code>test_&lt;function&gt;_NeedToImplement</code> test for each function. Each test
+calls <code>TEST_IGNORE_MESSAGE()</code> until you fill it in.</p>
+<p>Run it again after adding functions to the header, and only tests for the new functions
+are added, ahead of the file’s closing <code>#endif</code>. A function already counts as tested by
+any test named <code>test_&lt;function&gt;</code> or <code>test_&lt;function&gt;_&lt;anything&gt;</code>, so your own
+descriptive test names are respected and your existing tests are left alone.</p>
+<p>Hints and slashes work as they do for <code>module:create</code>. The test file uses your
+configured <a href="#includes">includes</a>, <a href="#boilerplates">boilerplate</a>,
+<a href="#test-defines">test define</a>, and <a href="#test-guards">test guard</a>. Headers are parsed with
+your project’s <a href="../configuration/reference/cmock.html"><code>:cmock</code></a> settings, as for <a href="#stubbing">stubbing</a>.</p>
+<h2 id="destroying">Destroying</h2>
+<p><code>module:destroy</code> removes the files <code>module:create</code> would make for the same arguments,
+pattern and hints included:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:destroy[lab:SecretLair,mch]&quot;</span>
+</code></pre></div>
+<p>A file that does not exist is reported and skipped.</p>
 <h2 id="configuration">Configuration</h2>
-<p>Enable the plugin in your project.yml by adding <code>module_generator</code>
-to the list of enabled plugins.</p>
-<p>Then, like much of Ceedling, you can just run as-is with the defaults, or you can override those
-defaults for your own needs. For example, new source and header files will be automatically
-placed in the <code>src/</code> folder while tests will go in the <code>test/</code> folder. That's great if your project
-follows the default ceedling structure... but what if you have a different structure?</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="nt">:module_generator</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="nt">:naming</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">:bumpy</span>
-<a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="w">  </span><span class="nt">:includes</span><span class="p">:</span><span class="w"> </span>
-<a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">:src</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[]</span>
-<a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">:inc</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[]</span>
-<a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">:tst</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[]</span>
-<a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a><span class="w">  </span><span class="nt">:boilerplates</span><span class="p">:</span>
-<a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">:src</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&quot;</span>
-<a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">:inc</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&quot;</span>
-<a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">:tst</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&quot;</span>
+<p>The module generator runs as-is with its defaults. Every setting lives under
+<code>:module_generator</code> in your project file:</p>
+<table>
+<thead>
+<tr>
+<th>Setting</th>
+<th>Purpose</th>
+<th>Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>:naming</code></td>
+<td>File <a href="#naming-convention">naming convention</a></td>
+<td>none (names keep their case)</td>
+</tr>
+<tr>
+<td><code>:path_src</code>, <code>:path_inc</code>, <code>:path_tst</code></td>
+<td><a href="#default-paths">Default locations when no hint is given</a></td>
+<td>first path of each <code>:paths</code> list</td>
+</tr>
+<tr>
+<td><code>:includes</code></td>
+<td><a href="#includes">Headers every generated file includes</a></td>
+<td>none</td>
+</tr>
+<tr>
+<td><code>:boilerplates</code></td>
+<td><a href="#boilerplates">Text at the top of every generated file</a></td>
+<td>none</td>
+</tr>
+<tr>
+<td><code>:boilerplate_files</code></td>
+<td><a href="#boilerplate-files">Files holding that text instead</a></td>
+<td>none</td>
+</tr>
+<tr>
+<td><code>:test_define</code></td>
+<td><a href="#test-defines">Symbol guarding each test file</a></td>
+<td><code>TEST</code></td>
+</tr>
+<tr>
+<td><code>:test_guard</code></td>
+<td><a href="#test-guards"><code>#ifdef</code> or <code>#if</code> around each test file</a></td>
+<td><code>:ifdef</code></td>
+</tr>
+</tbody>
+</table>
+<h3 id="naming-convention">Naming convention</h3>
+<p>A naming convention keeps everyone’s file names consistent, whatever case a name is
+typed in. Words are found at underscores, spaces, and changes of case, so
+<code>mad_science</code> and <code>MadScience</code> name the same module.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="nt">:module_generator</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="nt">:naming</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">:bumpy</span>
 </code></pre></div>
-<p>Now I've redirected the location where modules are going to be generated.</p>
+<p>The options for <code>:naming</code>, and the source file each creates for this command:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[mad_science]&quot;</span>
+</code></pre></div>
+<table>
+<thead>
+<tr>
+<th><code>:naming</code></th>
+<th>Style</th>
+<th>Source file</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>:bumpy</code></td>
+<td>BumpyFilesLookLikeSo</td>
+<td><code>MadScience.c</code></td>
+</tr>
+<tr>
+<td><code>:camel</code></td>
+<td>camelFilesAreSimilarButStartLow</td>
+<td><code>madScience.c</code></td>
+</tr>
+<tr>
+<td><code>:snake</code></td>
+<td>snake_case_is_all_lower_and_uses_underscores</td>
+<td><code>mad_science.c</code></td>
+</tr>
+<tr>
+<td><code>:caps</code></td>
+<td>CAPS_FEELS_LIKE_YOU_ARE_SCREAMING</td>
+<td><code>MAD_SCIENCE.c</code></td>
+</tr>
+</tbody>
+</table>
+<p>The header and test file follow the same convention, as do a pattern’s module names.
+Without <code>:naming</code>, names keep the case you type.</p>
+<h3 id="default-paths">Default paths</h3>
+<p><code>:path_src</code>, <code>:path_inc</code>, and <code>:path_tst</code> choose where files go when a command gives no
+<a href="#path-hints">hint</a>. A hint still matches against your <code>:paths</code> and ignores these
+settings.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="nt">:module_generator</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">:path_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/</span>
+<a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a><span class="w">  </span><span class="nt">:path_inc</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">include/</span>
+<a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a><span class="w">  </span><span class="nt">:path_tst</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">test/</span>
+</code></pre></div>
+<p>With these settings, this command:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[Widget]&quot;</span>
+</code></pre></div>
+<p>creates <code>src/Widget.c</code>, <code>include/Widget.h</code>, and <code>test/test_Widget.c</code>.</p>
 <h3 id="includes">Includes</h3>
-<p>You can make it so that all of your files are generated with a standard include list. This is done
-by adding to the <code>:includes</code> array. For example:</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">:module_generator</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">:includes</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="nt">:tst</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">defs.h</span>
-<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">board.h</span>
-<a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="w">    </span><span class="nt">:src</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">board.h</span>
+<p>Every generated file of a kind can include a standard list of headers. <code>:src</code> lists
+those for source files, <code>:inc</code> for headers, and <code>:tst</code> for tests:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="nt">:module_generator</span><span class="p">:</span>
+<a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a><span class="w">  </span><span class="nt">:includes</span><span class="p">:</span>
+<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a><span class="w">    </span><span class="nt">:src</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">board.h</span>
+<a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a><span class="w">    </span><span class="nt">:inc</span><span class="p">:</span>
+<a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-6"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">types.h</span>
+<a id="__codelineno-16-7" name="__codelineno-16-7" href="#__codelineno-16-7"></a><span class="w">    </span><span class="nt">:tst</span><span class="p">:</span>
+<a id="__codelineno-16-8" name="__codelineno-16-8" href="#__codelineno-16-8"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">defs.h</span>
+<a id="__codelineno-16-9" name="__codelineno-16-9" href="#__codelineno-16-9"></a><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">board.h</span>
 </code></pre></div>
+<p>With these settings, this command:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[Widget]&quot;</span>
+</code></pre></div>
+<p>creates <code>Widget.c</code> including <code>board.h</code>, <code>Widget.h</code> including <code>types.h</code>, and
+<code>test_Widget.c</code> including <code>defs.h</code> and <code>board.h</code>, each ahead of the module’s own
+includes.</p>
 <h3 id="boilerplates">Boilerplates</h3>
-<p>You can specify the actual boilerplate used for each of your files. This is the handy place to
-put that corporate copyright notice (or maybe a copyleft notice, if that's your preference?)</p>
-<p>Notice there is a separate template for source files, include files, and test files. Also, 
-your boilerplates can optionally contain <code>%1$s</code> which will inject the filename into that spot.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="nt">:module_generator</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="nt">:boilerplates</span><span class="p">:</span><span class="w"> </span>
-<a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a><span class="w">    </span><span class="nt">:src</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
-<a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="w">      </span><span class="no">/***************************</span>
-<a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a><span class="w">      </span><span class="no">* %1$s</span>
-<a id="__codelineno-11-6" name="__codelineno-11-6" href="#__codelineno-11-6"></a><span class="w">      </span><span class="no">* This file is Awesome.</span>
-<a id="__codelineno-11-7" name="__codelineno-11-7" href="#__codelineno-11-7"></a><span class="w">      </span><span class="no">* That is All.</span>
-<a id="__codelineno-11-8" name="__codelineno-11-8" href="#__codelineno-11-8"></a><span class="w">      </span><span class="no">***************************/</span>
-<a id="__codelineno-11-9" name="__codelineno-11-9" href="#__codelineno-11-9"></a><span class="w">    </span><span class="nt">:inc</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
-<a id="__codelineno-11-10" name="__codelineno-11-10" href="#__codelineno-11-10"></a><span class="w">      </span><span class="no">/***************************</span>
-<a id="__codelineno-11-11" name="__codelineno-11-11" href="#__codelineno-11-11"></a><span class="w">      </span><span class="no">* Header. Woo.             *</span>
-<a id="__codelineno-11-12" name="__codelineno-11-12" href="#__codelineno-11-12"></a><span class="w">      </span><span class="no">***************************/</span>
-<a id="__codelineno-11-13" name="__codelineno-11-13" href="#__codelineno-11-13"></a><span class="w">    </span><span class="nt">:tst</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
-<a id="__codelineno-11-14" name="__codelineno-11-14" href="#__codelineno-11-14"></a><span class="w">      </span><span class="no">/***************************</span>
-<a id="__codelineno-11-15" name="__codelineno-11-15" href="#__codelineno-11-15"></a><span class="w">      </span><span class="no">* My Awesome Test For %1$s</span>
-<a id="__codelineno-11-16" name="__codelineno-11-16" href="#__codelineno-11-16"></a><span class="w">      </span><span class="no">***************************/</span>
+<p>A boilerplate is text placed at the top of each generated file, the handy place for a
+copyright notice. Each kind of file has its own. A boilerplate may contain <code>%1$s</code>, which
+is replaced with the module name.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a><span class="nt">:module_generator</span><span class="p">:</span>
+<a id="__codelineno-18-2" name="__codelineno-18-2" href="#__codelineno-18-2"></a><span class="w">  </span><span class="nt">:boilerplates</span><span class="p">:</span>
+<a id="__codelineno-18-3" name="__codelineno-18-3" href="#__codelineno-18-3"></a><span class="w">    </span><span class="nt">:src</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
+<a id="__codelineno-18-4" name="__codelineno-18-4" href="#__codelineno-18-4"></a><span class="w">      </span><span class="no">/***************************</span>
+<a id="__codelineno-18-5" name="__codelineno-18-5" href="#__codelineno-18-5"></a><span class="w">      </span><span class="no">* %1$s</span>
+<a id="__codelineno-18-6" name="__codelineno-18-6" href="#__codelineno-18-6"></a><span class="w">      </span><span class="no">* This file is Awesome.</span>
+<a id="__codelineno-18-7" name="__codelineno-18-7" href="#__codelineno-18-7"></a><span class="w">      </span><span class="no">* That is All.</span>
+<a id="__codelineno-18-8" name="__codelineno-18-8" href="#__codelineno-18-8"></a><span class="w">      </span><span class="no">***************************/</span>
+<a id="__codelineno-18-9" name="__codelineno-18-9" href="#__codelineno-18-9"></a><span class="w">    </span><span class="nt">:inc</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
+<a id="__codelineno-18-10" name="__codelineno-18-10" href="#__codelineno-18-10"></a><span class="w">      </span><span class="no">/***************************</span>
+<a id="__codelineno-18-11" name="__codelineno-18-11" href="#__codelineno-18-11"></a><span class="w">      </span><span class="no">* Header. Woo.             *</span>
+<a id="__codelineno-18-12" name="__codelineno-18-12" href="#__codelineno-18-12"></a><span class="w">      </span><span class="no">***************************/</span>
+<a id="__codelineno-18-13" name="__codelineno-18-13" href="#__codelineno-18-13"></a><span class="w">    </span><span class="nt">:tst</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
+<a id="__codelineno-18-14" name="__codelineno-18-14" href="#__codelineno-18-14"></a><span class="w">      </span><span class="no">/***************************</span>
+<a id="__codelineno-18-15" name="__codelineno-18-15" href="#__codelineno-18-15"></a><span class="w">      </span><span class="no">* My Awesome Test For %1$s</span>
+<a id="__codelineno-18-16" name="__codelineno-18-16" href="#__codelineno-18-16"></a><span class="w">      </span><span class="no">***************************/</span>
 </code></pre></div>
-<h3 id="test-defines">Test Defines</h3>
-<p>You can specify the "#ifdef TEST" at the top of the test files with a custom define.
-This example will put a "#ifdef CEEDLING_TEST" at the top of the test files.  </p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="nt">:module_generator</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="nt">:test_define</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CEEDLING_TEST</span>
+<p>With these settings, this command:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[Widget]&quot;</span>
+</code></pre></div>
+<p>creates <code>Widget.c</code> beginning with the source boilerplate, its second line reading
+<code>* Widget</code>, and <code>test_Widget.c</code> beginning with <code>* My Awesome Test For Widget</code>.</p>
+<h3 id="boilerplate-files">Boilerplate files</h3>
+<p>A boilerplate can instead live in a file, which keeps long notices out of your project
+file. <code>:boilerplate_files</code> names a file for any kind, and that file’s contents replace
+the kind’s <code>:boilerplates</code> text. A named file that does not exist stops the command.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-20-1" name="__codelineno-20-1" href="#__codelineno-20-1"></a><span class="nt">:module_generator</span><span class="p">:</span>
+<a id="__codelineno-20-2" name="__codelineno-20-2" href="#__codelineno-20-2"></a><span class="w">  </span><span class="nt">:boilerplate_files</span><span class="p">:</span>
+<a id="__codelineno-20-3" name="__codelineno-20-3" href="#__codelineno-20-3"></a><span class="w">    </span><span class="nt">:src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">config/boilerplate_source.txt</span>
+<a id="__codelineno-20-4" name="__codelineno-20-4" href="#__codelineno-20-4"></a><span class="w">    </span><span class="nt">:tst</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">config/boilerplate_test.txt</span>
+</code></pre></div>
+<p>With these settings, this command:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[Widget]&quot;</span>
+</code></pre></div>
+<p>creates <code>Widget.c</code> beginning with the contents of <code>config/boilerplate_source.txt</code> and
+<code>test_Widget.c</code> beginning with the contents of <code>config/boilerplate_test.txt</code>. <code>Widget.h</code>
+uses the <code>:inc</code> boilerplate, if any.</p>
+<h3 id="test-defines">Test defines</h3>
+<p>Each generated test file is wrapped in <code>#ifdef TEST</code>. <code>:test_define</code> names a
+different symbol.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="nt">:module_generator</span><span class="p">:</span>
+<a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="w">  </span><span class="nt">:test_define</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CEEDLING_TEST</span>
+</code></pre></div>
+<p>With this setting, this command:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[Widget]&quot;</span>
+</code></pre></div>
+<p>creates <code>test_Widget.c</code> wrapped in <code>#ifdef CEEDLING_TEST</code> and <code>#endif // CEEDLING_TEST</code>.</p>
+<p>The symbol must be defined for your test builds, or every generated test compiles to
+nothing. Add it under <a href="../configuration/reference/defines.html"><code>:defines</code></a> ↳ <code>:test</code>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a><span class="nt">:defines</span><span class="p">:</span>
+<a id="__codelineno-24-2" name="__codelineno-24-2" href="#__codelineno-24-2"></a><span class="w">  </span><span class="nt">:test</span><span class="p">:</span>
+<a id="__codelineno-24-3" name="__codelineno-24-3" href="#__codelineno-24-3"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CEEDLING_TEST</span>
+</code></pre></div>
+<p><code>module:create</code> and <code>module:test</code> warn about each generated test file whose build would
+not define the symbol. Each file is checked as a test build would compile it, so a symbol
+under a per-test matcher counts only for the test files that matcher matches.</p>
+<h3 id="test-guards">Test guards</h3>
+<p>Each generated test file is guarded with <code>#ifdef</code>. Some coding standards forbid <code>#ifdef</code>
+in favor of <code>#if</code>, and <code>:test_guard</code> set to <code>:if</code> uses <code>#if</code> instead. The options are
+<code>:ifdef</code> (the default) and <code>:if</code>.</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a><span class="nt">:defines</span><span class="p">:</span>
+<a id="__codelineno-25-2" name="__codelineno-25-2" href="#__codelineno-25-2"></a><span class="w">  </span><span class="nt">:test</span><span class="p">:</span>
+<a id="__codelineno-25-3" name="__codelineno-25-3" href="#__codelineno-25-3"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">UNIT_TEST</span>
+<a id="__codelineno-25-4" name="__codelineno-25-4" href="#__codelineno-25-4"></a>
+<a id="__codelineno-25-5" name="__codelineno-25-5" href="#__codelineno-25-5"></a><span class="nt">:module_generator</span><span class="p">:</span>
+<a id="__codelineno-25-6" name="__codelineno-25-6" href="#__codelineno-25-6"></a><span class="w">  </span><span class="nt">:test_define</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">UNIT_TEST</span>
+<a id="__codelineno-25-7" name="__codelineno-25-7" href="#__codelineno-25-7"></a><span class="w">  </span><span class="nt">:test_guard</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">:if</span>
 </code></pre></div>
-<h3 id="naming-convention">Naming Convention</h3>
-<p>Finally, you can force a particular naming convention. Even if someone calls the generator
-with something like <code>MyNewModule</code>, if they have the naming convention set to <code>:caps</code>, it will
-generate files like <code>MY_NEW_MODULE.c</code>. This keeps everyone on your team behaving the same way.</p>
-<p>Your options for <code>:naming:</code> are as follows:</p>
-<div class="highlight"><pre><span></span><code>- `:bumpy` - BumpyFilesLooksLikeSo
-- `:camel` - camelFilesAreSimilarButStartLow
-- `:snake` - snake_case_is_all_lower_and_uses_underscores
-- `:caps`  - CAPS_FEELS_LIKE_YOU_ARE_SCREAMING
+<p>With these settings, this command:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a>ceedling<span class="w"> </span><span class="s2">&quot;module:create[Widget]&quot;</span>
 </code></pre></div>
+<p>creates <code>test_Widget.c</code> wrapped in <code>#if UNIT_TEST</code> and <code>#endif // UNIT_TEST</code>. With
+<code>#if</code>, the symbol must be defined to a nonzero value. A bare <code>UNIT_TEST</code> under <code>:defines</code>
+is defined as <code>1</code>.</p>
 <p><br/><br/></p>