ceedling 1.1.10 → 1.2.1

data/site-local/getting-started/command-line.html

@@ -14,14 +14,14 @@
         <link rel="prev" href="installation.html">
       
       
-        <link rel="next" href="example-projects/index.html">
+        <link rel="next" href="builds.html">
       
       
         
       
       
       <link rel="icon" href="../assets/images/favicon.png">
-      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.7">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
     
     
       
@@ -29,10 +29,10 @@
       
     
     
-      <link rel="stylesheet" href="../assets/stylesheets/main.ec1eaa64.min.css">
+      <link rel="stylesheet" href="../assets/stylesheets/main.57a0d79d.min.css">
       
         
-        <link rel="stylesheet" href="../assets/stylesheets/palette.ab4e12ef.min.css">
+        <link rel="stylesheet" href="../assets/stylesheets/palette.fb2fffe2.min.css">
       
       
 
@@ -93,6 +93,16 @@
     
       <div data-md-color-scheme="default" data-md-component="outdated" hidden>
         
+          <aside class="md-banner md-banner--warning">
+            <div class="md-banner__inner md-grid md-typeset">
+              You are not viewing the latest version.
+    <a href="../..">
+      <strong>Click here to go to latest.</strong>
+    </a>
+            </div>
+            <script>var el=document.querySelector("[data-md-component=outdated]"),base=new URL(".."),outdated=__md_get("__outdated",sessionStorage,base);!0===outdated&&el&&(el.hidden=!1)</script>
+          </aside>
+        
       </div>
     
     
@@ -332,7 +342,7 @@
     
     
       <li class="md-tabs__item">
-        <a href="../project/release-history.html" class="md-tabs__link">
+        <a href="../project/index.html" class="md-tabs__link">
           
   
   
@@ -643,6 +653,8 @@
         
       
         
+      
+        
       
         
       
@@ -885,7 +897,7 @@
   <a href="#ceedling-dumpconfig-filepath-sections" class="md-nav__link">
     <span class="md-ellipsis">
       
-        ceedling dumpconfig FILEPATH [SECTIONS...]
+        ceedling dumpconfig [FILEPATH] [SECTIONS...]
       
     </span>
   </a>
@@ -1105,6 +1117,50 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-genmocksall" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:mocks:all
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-genmocks" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:mocks:*
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-gentest_runnerall" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:test_runner:all
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-gentest_runner" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:test_runner:*
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -1232,6 +1288,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="builds.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Builds
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -1261,7 +1345,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">
@@ -1283,14 +1367,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_3_5" id="__nav_3_5_label" tabindex="">
+              <label class="md-nav__link " for="__nav_3_6" id="__nav_3_6_label" tabindex="">
                 <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>
             
   
@@ -2857,6 +2941,8 @@
         
       
         
+      
+        
       
         
       
@@ -3488,16 +3574,113 @@
   
   
     <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">
+    
+  
+    Bullseye (Coverage)
+  
+
+    
+  </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>
   
@@ -3509,6 +3692,14 @@
 
               
             
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+              
+            
               
                 
   
@@ -3978,6 +4169,12 @@
     
       
         
+          
+        
+      
+        
+      
+        
       
         
       
@@ -3997,8 +4194,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">
@@ -4012,8 +4210,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">
@@ -4027,6 +4231,8 @@
           <ul class="md-nav__list" data-md-scrollfix>
             
               
+            
+              
                 
   
   
@@ -4060,6 +4266,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">
         
@@ -4131,6 +4365,8 @@
       
         
       
+        
+      
         
       
     
@@ -4221,6 +4457,34 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../development/releases.html" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Branching & Releases
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     
     
       
@@ -4247,7 +4511,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">
@@ -4269,14 +4533,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>
             
   
@@ -4473,7 +4737,7 @@
   <a href="#ceedling-dumpconfig-filepath-sections" class="md-nav__link">
     <span class="md-ellipsis">
       
-        ceedling dumpconfig FILEPATH [SECTIONS...]
+        ceedling dumpconfig [FILEPATH] [SECTIONS...]
       
     </span>
   </a>
@@ -4693,6 +4957,50 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-genmocksall" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:mocks:all
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-genmocks" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:mocks:*
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-gentest_runnerall" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:test_runner:all
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#ceedling-gentest_runner" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        ceedling gen:test_runner:*
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -5011,6 +5319,12 @@ configuration. If no tasks are provided, built-in default tasks or your
 <td><code>''</code> (none)</td>
 </tr>
 <tr>
+<td><code>--force-test-rerun</code></td>
+<td></td>
+<td>Run test executables and report fresh results even if unchanged</td>
+<td><code>false</code> (disabled)</td>
+</tr>
+<tr>
 <td><code>--ruby-replacement</code></td>
 <td></td>
 <td>Enables inline Ruby string expansion (<code>#{...}</code>) in project configuration</td>
@@ -5019,10 +5333,10 @@ configuration. If no tasks are provided, built-in default tasks or your
 </tbody>
 </table>
 <hr />
-<h3 id="ceedling-dumpconfig-filepath-sections"><code>ceedling dumpconfig FILEPATH [SECTIONS...]</code></h3>
+<h3 id="ceedling-dumpconfig-filepath-sections"><code>ceedling dumpconfig [FILEPATH] [SECTIONS...]</code></h3>
 <p>Process project configuration and write final result to a YAML file.</p>
-<p><code>FILEPATH</code> is a required path to a destination YAML file. A nonexistent 
-path will be created.</p>
+<p><code>FILEPATH</code> is a required path to a destination YAML file, unless <code>--stdout</code> is 
+set (see below). A nonexistent path will be created.</p>
 <p><code>SECTIONS</code> is an optional config “path” that extracts a portion of a 
 configuration. The top-level YAML container will be the path’s last 
 element. Example: <code>ceedling dumpconfig my/path/config.yml tools test_compiler</code>.</p>
@@ -5055,6 +5369,12 @@ element. Example: <code>ceedling dumpconfig my/path/config.yml tools test_compil
 <td><code>true</code></td>
 </tr>
 <tr>
+<td><code>--stdout</code></td>
+<td></td>
+<td>Writes YAML to standard output instead of <code>FILEPATH</code>, for consuming tools</td>
+<td><code>false</code> (disabled)</td>
+</tr>
+<tr>
 <td><code>--ruby-replacement</code></td>
 <td></td>
 <td>Enables inline Ruby string expansion (<code>#{...}</code>) in project configuration</td>
@@ -5062,6 +5382,12 @@ element. Example: <code>ceedling dumpconfig my/path/config.yml tools test_compil
 </tr>
 </tbody>
 </table>
+<p>Use <code>--stdout</code> when a consuming tool wants Ceedling’s fully resolved 
+configuration piped directly into its own process rather than written to 
+a temp file and read back. Omit <code>FILEPATH</code> when using this flag — any 
+positional arguments given are treated as <code>SECTIONS</code> instead:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>ceedling dumpconfig --stdout tools test_compiler
+</code></pre></div>
 <hr />
 <h3 id="ceedling-check"><code>ceedling check</code></h3>
 <p>Loads and processes your project configuration with full logging — the 
@@ -5248,6 +5574,12 @@ new project (default is your working directory).</p>
 <td><code>true</code></td>
 </tr>
 <tr>
+<td><code>--ceedling-yml</code></td>
+<td></td>
+<td>Name starter project file <code>ceedling.yml</code> instead of historical default of <code>project.yml</code></td>
+<td><code>false</code></td>
+</tr>
+<tr>
 <td><code>--force</code></td>
 <td></td>
 <td>Ignore any existing project and recreate destination</td>
@@ -5292,17 +5624,17 @@ an optional destination path (default is your working directory).</p>
 <hr />
 <h3 id="ceedling-version"><code>ceedling version</code></h3>
 <p>Displays version information for Ceedling and its components. Version output for Ceedling includes the Git Commit short SHA in Ceedling’s build identifier and Ceedling’s path of origin.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>🌱 Welcome to Ceedling!
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>  Ceedling =&gt; #.#.#-&lt;Short SHA&gt;
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>  ----------------------
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>  &lt;Ceedling install path&gt;
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>  Build Frameworks
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>  ----------------------
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>       CMock =&gt; #.#.#
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>       Unity =&gt; #.#.#
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>  CException =&gt; #.#.#
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>🌱 Welcome to Ceedling!
+<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>
+<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>  Ceedling =&gt; #.#.#-&lt;Short SHA&gt;
+<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>  ----------------------
+<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>  &lt;Ceedling install path&gt;
+<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a>
+<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a>  Build Frameworks
+<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>  ----------------------
+<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a>       CMock =&gt; #.#.#
+<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a>       Unity =&gt; #.#.#
+<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a>  CException =&gt; #.#.#
 </code></pre></div>
 <p>If the short SHA information is unavailable such as in local development, the SHA is omitted. The source for this string is generated and captured in the Gem at the time of Ceedling’s automated build in CI.</p>
 <p><em>No parameters.</em></p>
@@ -5349,9 +5681,20 @@ configuration file.</p>
 validation of code and configuration via your toolchain.</p>
 <hr />
 <h3 id="ceedling-test"><code>ceedling test:*</code></h3>
-<p>Execute the named test file or the named source file that has an
-accompanying test. No path. Examples: <code>ceedling test:foo</code>, <code>ceedling 
-test:foo.c</code> or <code>ceedling test:test_foo.c</code></p>
+<p>Build and execute the named test executable or the named source file that has an
+accompanying test file. Examples: <code>ceedling test:foo</code>, <code>ceedling test:foo.c</code>
+or <code>ceedling test:test_foo.c</code></p>
+<div class="admonition tip">
+<p class="admonition-title">Disambiguating test files with the same name</p>
+<p>If more than one test file shares that filename in different test
+directories, add enough of the trailing path to identify the file you
+want. <code>/</code> and <code>\</code> are both acceptable path separators.</p>
+<p>For example, given <em>test/unit/test_foo.c</em> and <em>test/integration/test_foo.c</em>, 
+run <code>ceedling test:unit/test_foo.c</code> at the command line to identify
+the first test file.</p>
+<p>When Ceedling is unable to uniquely identify a file path, it raises 
+an error naming every matching file.</p>
+</div>
 <hr />
 <h3 id="ceedling-test-test-casetest_case_name"><code>ceedling test:* --test-case=&lt;test_case_name&gt;</code></h3>
 <p>Execute individual test cases which match <code>test_case_name</code>.</p>
@@ -5408,6 +5751,33 @@ whose path contains foo/bar. <em>Notes:</em></p>
    characters from shell command line operators.</li>
 </ol>
 <hr />
+<h3 id="ceedling-genmocksall"><code>ceedling gen:mocks:all</code></h3>
+<p>Generate the mock files in the project build directory for all tests. The
+test build pipeline terminates after the mock generation stage.</p>
+<hr />
+<h3 id="ceedling-genmocks"><code>ceedling gen:mocks:*</code></h3>
+<p>Generate the mock files in the project build directory for only the given 
+test or the named source file that has an accompanying test. The test 
+build pipeline terminates after the mock generation stage.
+Examples: <code>ceedling gen:mocks:foo</code>, <code>ceedling gen:mocks:foo.c</code> or 
+<code>ceedling gen:mocks:test_foo.c</code></p>
+<p>Like the <code>test:</code> tasks, the test specifier for duplicate test filenames
+can be disambiguated with a trailing path before the test name.</p>
+<hr />
+<h3 id="ceedling-gentest_runnerall"><code>ceedling gen:test_runner:all</code></h3>
+<p>Generate up through test runners in the project build directory for all 
+tests. The test build pipeline terminates after the test runner generation 
+stage.</p>
+<hr />
+<h3 id="ceedling-gentest_runner"><code>ceedling gen:test_runner:*</code></h3>
+<p>Generate the test runner files in the project build directory for only 
+the given test or the named source file that has an accompanying test. 
+The test build pipeline terminates after the test runner generation stage.
+Examples: <code>ceedling gen:test_runner:foo</code>, <code>ceedling gen:test_runner:foo.c</code>
+or <code>ceedling gen:test_runner:test_foo.c</code></p>
+<p>Like the <code>test:</code> tasks, the test specifier for duplicate test filenames
+can be disambiguated with a trailing path before the test name.</p>
+<hr />
 <h3 id="ceedling-release"><code>ceedling release</code></h3>
 <p>Build all source into a release artifact (if the release build option
 is configured).</p>
@@ -5518,10 +5888,10 @@ leave anything Ceedling &amp; its accompanying tools generate out of source cont
     
       
       
-      <script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
+      <script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
     
     
-      <script src="../assets/javascripts/bundle.d7400e89.min.js"></script>
+      <script src="../assets/javascripts/bundle.c21346df.min.js"></script>
       
     
   </body>