ceedling 1.2.1 → 1.2.2

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

@@ -5595,9 +5595,16 @@ new project (default is your working directory).</p>
 </table>
 <hr />
 <h3 id="ceedling-upgrade-path"><code>ceedling upgrade PATH</code></h3>
-<p>Upgrade vendored installation of Ceedling for an existing project 
-along with any locally installed documentation bundles. <code>PATH</code> is 
-required and should be the root of the project to upgrade.</p>
+<p>Upgrade vendored installation of Ceedling for an existing project. <code>PATH</code>
+is required and should be the root of the project to upgrade.</p>
+<p>If the project holds documentation that <code>new --docs</code> or <code>example --docs</code>
+exported, <code>upgrade</code> replaces it with the documentation of the Ceedling it
+copies. It replaces only what the export wrote, and leaves your own files in
+<code>docs/</code>. If that Ceedling has no HTML documentation bundle (a <code>--local</code> copy
+carries none), <code>upgrade</code> keeps the project’s existing bundle.</p>
+<p><code>upgrade</code> copies the Ceedling you run, or the installation the
+<code>WHICH_CEEDLING</code> environment variable names. It never copies from a
+<code>vendor/ceedling/</code> it finds in your working directory.</p>
 <table>
 <thead>
 <tr>
@@ -5620,6 +5627,10 @@ required and should be the root of the project to upgrade.</p>
 <h3 id="ceedling-docs-dest"><code>ceedling docs [DEST]</code></h3>
 <p>Exports the Ceedling documentation bundle to the filesystem. <code>DEST</code> is 
 an optional destination path (default is your working directory).</p>
+<p><code>docs</code> exports the documentation of the installation <a href="../configuration/which-ceedling.html"><em>Which Ceedling</em></a>
+selects. A <code>--local</code> copy carries no documentation bundle, so for a vendored
+copy <code>docs</code> exports the documentation of the <code>ceedling</code> command you ran, with a
+notice naming both installations.</p>
 <p><em>No parameters.</em></p>
 <hr />
 <h3 id="ceedling-version"><code>ceedling version</code></h3>
@@ -5637,7 +5648,48 @@ an optional destination path (default is your working directory).</p>
 <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>
+<p><code>version</code> reads your project file when one is available. When your project selects another Ceedling installation through <a href="../configuration/which-ceedling.html"><em>Which Ceedling</em></a>, <code>version</code> reports the <code>ceedling</code> command you ran and the selected installation separately, each with its own version:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>🌱 Welcome to Ceedling!
+<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>
+<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>  Ceedling Launcher =&gt; #.#.#-&lt;Short SHA&gt;
+<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a>  ----------------------
+<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a>  &lt;Ceedling launcher install path&gt;
+<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a>
+<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a>  Ceedling App =&gt; #.#.#-&lt;Short SHA&gt;
+<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a>  ----------------------
+<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a>  &lt;Ceedling application install path&gt;
+<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a>
+<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a>  Build Frameworks
+<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a>  ----------------------
+<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a>       CMock =&gt; #.#.#
+<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a>       Unity =&gt; #.#.#
+<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a>  CException =&gt; #.#.#
+</code></pre></div>
+<p>The build frameworks are always those of the Ceedling application.</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Alias</th>
+<th>Description</th>
+<th>Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--project</code></td>
+<td><code>-p</code></td>
+<td>Project filepath. A project file named this way must load. Without it, a default project file that cannot be loaded is skipped.</td>
+<td><code>project.yml</code> or <code>ceedling.yml</code> in your working directory</td>
+</tr>
+<tr>
+<td><code>--mixin</code></td>
+<td><code>-m</code></td>
+<td>Merge a mixin into the project configuration. Repeatable.</td>
+<td></td>
+</tr>
+</tbody>
+</table>
 <hr />
 <h2 id="build-plugin-tasks">Build &amp; plugin tasks</h2>
 <p>Build task are loaded from your project configuration. Unlike 

data/site-local/plugins/dependencies.html

@@ -5064,8 +5064,9 @@ project’s own files.</p>
 <p>If the dependency is part of your repository (its fetch <code>:method</code> is <code>:none</code>), <code>:source</code>
 is where its code already lives. Paths may lie outside your project, such as
 <code>../shared/lib</code>, and headers found there work in test and release builds alike.</p>
-<p>Every artifact is relative to the <code>:artifact</code> path. With several include directories,
-choose the highest level and list the rest relative to it.</p>
+<p>Every artifact is relative to the <code>:artifact</code> path, unless it is an absolute path, which
+names the artifact itself. With several include directories, choose the highest level
+and list the rest relative to it. A path may begin with <code>~</code> to name your home directory.</p>
 <h2 id="fetching-dependencies">Fetching dependencies</h2>
 <p>The plugin fetches a dependency with one of several common methods, configured under its
 <code>:fetch</code>:</p>
@@ -5237,7 +5238,9 @@ under <code>:tools</code>:</p>
 <p>The compiler, assembler, and archiver are checked just before <code>:build_lib</code> uses them, so
 a project without <code>:build_lib</code> needs none of them.</p>
 <p><code>:build_lib</code> compiles every C file anywhere under the dependency’s <code>:source</code> path, with
-every directory holding a header there as a search path. It then archives the objects
+every directory holding a header there as a search path. Each object, and its list file,
+sits in the <code>:build</code> path at its source’s path below the <code>:source</code> path, so same-named
+sources in different directories keep apart. It then archives the objects
 into the first library under <code>:artifacts</code> ↳ <code>:static_libraries</code>, built in the <code>:build</code>
 path and copied to the <code>:artifact</code> path when the two differ. A dependency’s own
 <code>:defines</code> and <code>:flags</code> apply to its compilation, and <code>:libraries</code> and <code>:libpaths</code> to its

data/site-local/plugins/fff.html

@@ -4844,19 +4844,50 @@ Each example uses fakes for a "display" module, created from a display.h file wi
 <h2 id="test-setup">Test setup</h2>
 <p>All of the fake functions and any fff global state are all reset automatically between each test.</p>
 <h2 id="cmock-configuration">CMock configuration</h2>
-<p>We still use some CMock configuration options for setting things like the mock prefix and for including additional header files in the mock files.</p>
+<p>Fakes still use some CMock settings, such as the mock prefix and the extra
+header files to include.</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">:cmock</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">:mock_prefix</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mock_</span>
-<a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="w">        </span><span class="l l-Scalar l-Scalar-Plain">:includes</span><span class="p p-Indicator">:</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="l l-Scalar l-Scalar-Plain">...</span>
-<a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="w">    </span><span class="w w-Error">    </span><span class="nt">:includes_h_pre_orig_header</span><span class="p">:</span>
-<a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a><span class="w">            </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
-<a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a><span class="w">        </span><span class="nt">:includes_h_post_orig_header</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="l l-Scalar l-Scalar-Plain">...</span>
-<a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="w">        </span><span class="nt">:includes_c_pre_header</span><span class="p">:</span>
-<a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="w">            </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
-<a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></a><span class="w">        </span><span class="nt">:includes_c_post_header</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">:mock_prefix</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mock_</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>
+<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="l l-Scalar l-Scalar-Plain">...</span>
+<a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="w">  </span><span class="nt">:includes_h_pre_orig_header</span><span class="p">:</span>
+<a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
+<a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a><span class="w">  </span><span class="nt">:includes_h_post_orig_header</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="l l-Scalar l-Scalar-Plain">...</span>
+<a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="w">  </span><span class="nt">:includes_c_pre_header</span><span class="p">:</span>
+<a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
+<a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></a><span class="w">  </span><span class="nt">:includes_c_post_header</span><span class="p">:</span>
+<a id="__codelineno-9-12" name="__codelineno-9-12" href="#__codelineno-9-12"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
 </code></pre></div>
+<p>Each include setting puts its headers in a fake where CMock puts them in a mock.</p>
+<table>
+<thead>
+<tr>
+<th>Setting</th>
+<th>Where the <code>#include</code> goes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>:includes</code>, <code>:includes_h_pre_orig_header</code></td>
+<td>The fake’s header, before the original header</td>
+</tr>
+<tr>
+<td><code>:includes_h_post_orig_header</code></td>
+<td>The fake’s header, after the original header</td>
+</tr>
+<tr>
+<td><code>:includes_c_pre_header</code></td>
+<td>The fake’s source, before the fake’s header</td>
+</tr>
+<tr>
+<td><code>:includes_c_post_header</code></td>
+<td>The fake’s source, after the fake’s header</td>
+</tr>
+</tbody>
+</table>
+<p>A <a href="../configuration/reference/cmock.html#unity_helper_path">Unity helper</a> is
+included in a fake’s header and source, as it is in a mock’s.</p>
 <h3 id="fakes-of-same-named-headers">Fakes of same-named headers</h3>
 <p>With <code>:cmock</code> ↳ <code>:mock_name_include_folder</code> enabled, Ceedling’s default, a fake
 included through a folder is named by that folder, as a CMock mock is. A fake

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

@@ -5777,7 +5777,7 @@ settings with other CLI arguments derived from plugin configuration. You must
 provide any settings that would have been provided by the Gcov plugin, either 
 in the config file itself or via <code>:custom_args:</code>.</p>
 </div>
-<p>A Gcovr config file replaces Ceedling's own automatically generated exclusion
+<p>A Gcovr config file replaces Ceedling’s own automatically generated exclusion
 patterns (see <a href="#results-filtering">Results filtering</a> below) entirely — it is
 the only way to override or remove one of those defaults, since the
 project-configuration <code>:report_exclude</code> option can only add further
@@ -5812,7 +5812,7 @@ Ceedling itself generates as part of a build all skew that number if left in.</p
 <code>test/</code>:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>.*(?:^|/)test/(?:.*/)?test_[^/]+(?:\.c)$
 </code></pre></div>
-<p>A project's <code>:extension</code> ↳ <code>:source</code> can list more than one source
+<p>A project’s <code>:extension</code> ↳ <code>:source</code> can list more than one source
 extension; every configured extension is joined into this same
 alternation. Given <code>:extension</code> ↳ <code>:source</code> ⇒ <code>['.c', '.C']</code>:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>.*(?:^|/)test/(?:.*/)?test_[^/]+(?:\.c|\.C)$
@@ -5836,7 +5836,7 @@ the alternation. Given <code>:extension</code> ↳ <code>:source</code> ⇒ <cod
     <code>:build_root</code>: generated mocks, test runners, Partials output, and the
     vendored Unity/CMock/CException framework sources Ceedling copies in to
     build against. Unlike the two patterns above, this one always matches a
-    literal <code>.c</code> extension regardless of your project's own <code>:extension</code> ↳
+    literal <code>.c</code> extension regardless of your project’s own <code>:extension</code> ↳
     <code>:source</code> setting, since every file it catches is one Ceedling itself
     writes in plain C.</p>
 <p>Given <code>:build_root</code> ⇒ <code>build/</code>:</p>
@@ -5849,7 +5849,7 @@ provide via <a href="#report_exclude"><code>:report_exclude</code></a> below —
 (and normally shouldn't) duplicate them yourself.</p>
 <div class="admonition warning">
 <p class="admonition-title">Not applied when using a Gcovr configuration file</p>
-<p>These defaults are only generated when Ceedling builds <code>gcovr</code>'s command
+<p>These defaults are only generated when Ceedling builds <code>gcovr</code>’s command
 line directly. As covered in
 <a href="#gcovr-configuration-file">Gcovr configuration file</a> above, setting
 <code>:config_file</code> bypasses this entirely — none of the three patterns above
@@ -5865,7 +5865,7 @@ own three patterns ahead of anything you configure there. Neither
 either: <code>:report_include</code> narrows which files are considered at all, but an
 exclude pattern still wins over it for any file matching both; <code>:custom_args</code>
 lets you pass additional raw <code>gcovr</code> flags, but a raw <code>--filter</code>/<code>--exclude</code>
-of your own is just as additive as <code>:report_exclude</code> — there's no <code>gcovr</code>
+of your own is just as additive as <code>:report_exclude</code> — there’s no <code>gcovr</code>
 flag that removes or replaces an exclusion already given, only ones that add
 more.</p>
 <p>The only way to actually remove or replace one of these defaults — for
@@ -5912,7 +5912,7 @@ Ceedling from overriding config file values with its CLI arguments.
 different working directory than your project root, and <code>:custom_args:</code> is
 still applied too — the one way to pass Gcovr flags of your own alongside a
 config file (see <code>:custom_args</code> below).</p>
-<p>To preserve the plugin's base filtering behavior, include exclusion patterns
+<p>To preserve the plugin’s base filtering behavior, include exclusion patterns
 matching your project layout in the config file itself — see
 <a href="#gcovr-configuration-file">Gcovr configuration file</a> above.</p>
 <p><strong>Default:</strong> unset — Ceedling does not look for or autodetect a config file
@@ -5937,7 +5937,10 @@ percentage. Can be ORed with the exit status of other <code>:fail_under_*</code>
 (<code>gcovr --fail-under-decision</code>)</p>
 <p><code>gcovr</code> treats <code>--fail-under-decision</code> as a no-op without <code>--decisions</code> also
 present — setting this option implies <code>:decisions</code> (below) automatically, so
-it's never silently non-functional.</p>
+it’s never silently non-functional.</p>
+<p>From <code>gcovr</code> 8.7, <code>--fail-under-decision</code> also checks condition coverage, which
+<code>:mcdc</code> produces. A run below the minimum for either reports each failure on its
+own line of the build failure summary.</p>
 <p><strong>Values:</strong> <code>1</code>–<code>100</code></p>
 <p><strong>Requires:</strong> <code>gcovr</code> 7.0 or higher</p>
 <hr />
@@ -5987,7 +5990,7 @@ is in addition to any other configured reports. (<code>gcovr --print-summary</co
 <p>Keep only source files that match this filter. Filters are regular
 expressions. (<code>gcovr --filter</code>)</p>
 <p>This narrows which files are considered at all, but does not override
-<a href="#results-filtering">Results filtering</a>'s automatic exclusion defaults — a
+<a href="#results-filtering">Results filtering</a>’s automatic exclusion defaults — a
 file excluded by one of those three default patterns stays excluded even if
 it also matches <code>:report_include</code>. See
 <a href="#overriding-the-defaults">Overriding the defaults</a> if you need to remove one
@@ -6021,7 +6024,7 @@ files. Filters are regular expressions. (<code>gcovr --exclude-directories</code
 <hr />
 <h3 id="gcov_executable"><code>:gcov_executable</code></h3>
 <p>Use a particular <code>gcov</code> executable. This may be appropriate and necessary in
-special circumstances — review Ceedling's options for modifying tools first.
+special circumstances — review Ceedling’s options for modifying tools first.
 (<code>gcovr --gcov-executable</code>)</p>
 <hr />
 <h3 id="exclude_unreachable_branches"><code>:exclude_unreachable_branches</code></h3>
@@ -6039,7 +6042,7 @@ the same source function, this is a real risk. This option controls how
 <code>gcovr</code> merges those repeated entries. See the
 <a href="https://gcovr.com/en/stable/guide/merging.html">gcovr merging docs</a> for all
 valid values. Ignored on <code>gcovr</code> versions below 6.0.</p>
-<p><strong>Default:</strong> <code>merge-use-line-max</code> (<code>gcovr</code>'s own default, <code>strict</code>, raises an
+<p><strong>Default:</strong> <code>merge-use-line-max</code> (<code>gcovr</code>’s own default, <code>strict</code>, raises an
 exception for many Ceedling projects)</p>
 <hr />
 <h3 id="use_gcov_files"><code>:use_gcov_files</code></h3>
@@ -6067,12 +6070,12 @@ error. (<code>gcovr --gcov-ignore-parse-errors</code>)</p>
 <h3 id="custom_args"><code>:custom_args</code></h3>
 <p>Optional list of one or more raw command line arguments to pass to <code>gcovr</code>.
 Useful as an escape hatch for any <code>gcovr</code> flag Ceedling has no named option
-for (e.g. limiting <code>gcovr</code>'s search root).</p>
+for (e.g. limiting <code>gcovr</code>’s search root).</p>
 <p>Unlike every other option above, these arguments are still applied even when
 <code>:config_file</code> is set — the one way to pass <code>gcovr</code> flags of your own
 alongside a config file.</p>
 <p>This does not, on its own, let you override
-<a href="#results-filtering">Results filtering</a>'s automatic exclusion defaults when
+<a href="#results-filtering">Results filtering</a>’s automatic exclusion defaults when
 <code>:config_file</code> is unset — a raw <code>--filter</code>/<code>--exclude</code> passed here is just as
 additive as <a href="#report_exclude"><code>:report_exclude</code></a>; see
 <a href="#overriding-the-defaults">Overriding the defaults</a> for the one option that

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

@@ -4694,7 +4694,8 @@ are not exercised by any test. It takes one of three values:</p>
   appear in the final report with 0% coverage (since no test exercises
   them). This causes all source files to appear in any generated reporting.
   If a source file fails to compile, Ceedling logs guidance at the console,
-  and the build fails.</li>
+  and the build fails. Each untested source’s object sits below <code>build/gcov/out/</code>
+  at the source’s path from your project’s root.</li>
 </ul>
 <p><div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="nt">:plugins</span><span class="p">:</span>
 <a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="w">  </span><span class="nt">:enabled</span><span class="p">:</span>

data/site-local/plugins/report-tests-raw-output-log.html

@@ -4458,7 +4458,9 @@ expected Unity test results as described above. Log files are named for the
 respective test executables.</p>
 <p>Builds are differentiated by build context — <code>test</code>, <code>release</code>, or
 plugin-modified build (e.g. <code>gcov</code>). Log files are written to <code>&lt;build
-root&gt;/artifacts/&lt;context&gt;/&lt;test file&gt;.raw.log</code>.</p>
+root&gt;/artifacts/&lt;context&gt;/&lt;test name&gt;.raw.log</code>. A <a href="../testing-guide/conventions.html#test-names-build-output">test’s name</a> is its path
+from your project’s root, so <code>test/unit/test_calc.c</code> logs to
+<code>build/artifacts/test/test/unit/test_calc.raw.log</code>.</p>
 <h2 id="setup">Setup</h2>
 <p>Enable the plugin in your Ceedling project:</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>

data/site-local/plugins/report-tests-teamcity-stdout.html

@@ -4444,7 +4444,10 @@ run on a TeamCity build server but not in your local development environment.</p
 underlying Java language in which TeamCity is written,
 <code>package_or_namespace.ClassName.TestName</code>.</p>
 <p>This plugin maps Ceedling conventions to TeamCity test service messages as
-<code>context.TestFilepath.TestCaseName</code>.</p>
+<code>context.TestFilepath.TestCaseName</code>. Each test suite is named by its test file’s
+path from your project’s root, without its file extension (e.g.
+<code>test/TestUsartModel</code>), so same-named test files in different directories are
+distinct suites.</p>
 <ul>
 <li><code>context</code> Your build's context defaults to <code>test</code>. Certain other test build 
   plugins (e.g. GCov) provide a different context (<code>gcov</code>) for test builds, 
@@ -4455,7 +4458,7 @@ underlying Java language in which TeamCity is written,
 </ul>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="w"> </span>&gt;<span class="w"> </span>ceedling<span class="w"> </span>test:UsartModel
 </code></pre></div>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>##teamcity[testSuiteStarted name='TestUsartModel' flowId='15']
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>##teamcity[testSuiteStarted name='test/TestUsartModel' flowId='15']
 <a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>##teamcity[testStarted name='test.test/TestUsartModel.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting' flowId='15']
 <a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>##teamcity[testFinished name='test.test/TestUsartModel.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting' duration='81' flowId='15']
 <a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>##teamcity[testStarted name='test.test/TestUsartModel.testShouldReturnErrorMessageUponInvalidTemperatureValue' flowId='15']
@@ -4464,7 +4467,7 @@ underlying Java language in which TeamCity is written,
 <a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a>##teamcity[testFailed name='test.test/TestUsartModel.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately' message='Function TemperatureFilter_GetTemperatureInCelcius() called more times than expected.' details='File: test/TestUsartModel.c Line: 25' flowId='15']
 <a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a>##teamcity[testFinished name='test.test/TestUsartModel.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately' duration='81' flowId='15']
 <a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a>##teamcity[testIgnored name='test.test/TestUsartModel.testShouldReturnWakeupMessage' flowId='15']
-<a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a>##teamcity[testSuiteFinished name='TestUsartModel' flowId='15']
+<a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a>##teamcity[testSuiteFinished name='test/TestUsartModel' flowId='15']
 </code></pre></div>
 <p><br/><br/></p>
 

data/site-local/plugins/sanitize.html

@@ -5103,10 +5103,10 @@ as much of the file’s path as needed to tell same-named test files apart:</p>
 </ul>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>☠️ ERROR: Test executable `test_buffer.out` was stopped by a sanitizer finding.
 <a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a>&gt; AddressSanitizer heap-buffer-overflow at test/test_buffer.c:21
-<a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a>&gt; Boom log: build/artifacts/sanitize/sanitize/test_buffer.log
+<a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a>&gt; Boom log: build/artifacts/sanitize/sanitize/test/test_buffer.log
 </code></pre></div>
 <p>The test’s failure message carries the same on one line:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>AddressSanitizer heap-buffer-overflow at test/test_buffer.c:21 (Boom log: build/artifacts/sanitize/sanitize/test_buffer.log)
+<div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>AddressSanitizer heap-buffer-overflow at test/test_buffer.c:21 (Boom log: build/artifacts/sanitize/sanitize/test/test_buffer.log)
 </code></pre></div>
 <ul>
 <li>
@@ -5128,12 +5128,12 @@ counts the findings and names the reports written:</p>
 <p>A halted test, with <code>:reports</code> set to <code>[:text, :json, :sarif]</code>:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a>☠️ ERROR: Test executable `test_nosanitize_heap_buffer_overflow.out` was stopped by a sanitizer finding.
 <a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a>&gt; AddressSanitizer heap-buffer-overflow at test/test_nosanitize_heap_buffer_overflow.c:29
-<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a>&gt; Boom log: build/artifacts/sanitize/sanitize/test_nosanitize_heap_buffer_overflow.log
+<a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-3"></a>&gt; Boom log: build/artifacts/sanitize/sanitize/test/test_nosanitize_heap_buffer_overflow.log
 <a id="__codelineno-16-4" name="__codelineno-16-4" href="#__codelineno-16-4"></a>
 <a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a>SANITIZE: FAILED TEST SUMMARY
 <a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-6"></a>[test/test_nosanitize_heap_buffer_overflow.c]
 <a id="__codelineno-16-7" name="__codelineno-16-7" href="#__codelineno-16-7"></a>  Test: test_writes_past_its_buffer
-<a id="__codelineno-16-8" name="__codelineno-16-8" href="#__codelineno-16-8"></a>  At line (27): "AddressSanitizer heap-buffer-overflow at test/test_nosanitize_heap_buffer_overflow.c:29 (Boom log: build/artifacts/sanitize/sanitize/test_nosanitize_heap_buffer_overflow.log)"
+<a id="__codelineno-16-8" name="__codelineno-16-8" href="#__codelineno-16-8"></a>  At line (27): "AddressSanitizer heap-buffer-overflow at test/test_nosanitize_heap_buffer_overflow.c:29 (Boom log: build/artifacts/sanitize/sanitize/test/test_nosanitize_heap_buffer_overflow.log)"
 <a id="__codelineno-16-9" name="__codelineno-16-9" href="#__codelineno-16-9"></a>
 <a id="__codelineno-16-10" name="__codelineno-16-10" href="#__codelineno-16-10"></a>SANITIZE: ❌ OVERALL TEST SUMMARY
 <a id="__codelineno-16-11" name="__codelineno-16-11" href="#__codelineno-16-11"></a>TESTED:  2
@@ -5147,7 +5147,7 @@ counts the findings and names the reports written:</p>
 </code></pre></div>
 <p>A leak. Every test passes, and the leak alone fails the build. The test’s
 own output section shows the sanitizer’s report:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a>🪲 ERROR: test_nosanitize_leak: LeakSanitizer memory-leak at test/test_nosanitize_leak.c:32 ➡️ see build/artifacts/sanitize/sanitize/test_nosanitize_leak.log
+<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a>🪲 ERROR: test/test_nosanitize_leak: LeakSanitizer memory-leak at test/test_nosanitize_leak.c:32 ➡️ see build/artifacts/sanitize/sanitize/test/test_nosanitize_leak.log
 <a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a>
 <a id="__codelineno-17-3" name="__codelineno-17-3" href="#__codelineno-17-3"></a>SANITIZE: TEST OUTPUT
 <a id="__codelineno-17-4" name="__codelineno-17-4" href="#__codelineno-17-4"></a>[test/test_nosanitize_leak.c]
@@ -5179,7 +5179,8 @@ named by its own finding.</p>
 The leak sanitizer cannot run under a debugger, and a sanitizer’s own report
 already includes the stack.</p>
 <h2 id="artifacts">Artifacts</h2>
-<p>Each test with findings has a log of its sanitizer reports:</p>
+<p>Each test with findings has a log of its sanitizer reports, placed by the
+<a href="../testing-guide/conventions.html#test-names-build-output">test’s name</a>, its path from your project’s root:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a>build/artifacts/sanitize/sanitize/&lt;test_name&gt;.log
 </code></pre></div>
 <p>The configured reports are written beside the logs:</p>

data/site-local/plugins/valgrind.html

@@ -4729,7 +4729,7 @@ building and then running test executables under Valgrind’s Memcheck tool.</p>
 <ul>
 <li><strong>Whole test suite</strong>: By running <code>ceedling valgrind:all</code>, all test
   executables are built and then each is run under Valgrind. A separate log
-  file is produced for each test executable in <code>build/artifacts/valgrind/</code>.</li>
+  file is produced for each test executable beneath <code>build/artifacts/valgrind/</code>.</li>
 <li><strong>Single test file</strong>: By running <code>ceedling valgrind:&lt;filename&gt;</code>, a single
   test executable is built and run under Valgrind, producing one log file.</li>
 </ul>
@@ -4861,8 +4861,9 @@ as much of the file’s path as needed to tell same-named test files apart:</p>
 beside it:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a>build/artifacts/valgrind/&lt;test_name&gt;.xml
 </code></pre></div>
-<p>For example, running <code>ceedling valgrind:test_my_module.c</code> produces:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a>build/artifacts/valgrind/test_my_module.log
+<p>A <a href="../testing-guide/conventions.html#test-names-build-output">test’s name</a> is its path from your project’s root. For example,
+running <code>ceedling valgrind:test/test_my_module.c</code> produces:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a>build/artifacts/valgrind/test/test_my_module.log
 </code></pre></div>
 <p>These log files contain the full Valgrind Memcheck output, including any
 detected memory errors, leak summaries, and (with <code>--track-origins=yes</code>)
@@ -4883,7 +4884,7 @@ the origin of uninitialized values.</p>
 report. It replaces Ceedling’s generic crash notice:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>☠️ ERROR: Test executable `test_nosanitize_crash_sigsegv.out` terminated with Valgrind memory errors.
 <a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>&gt; Invalid read of size 4 at test_nosanitize_crash_sigsegv.c:32
-<a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a>&gt; Boom log: build/artifacts/valgrind/test_nosanitize_crash_sigsegv.log
+<a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a>&gt; Boom log: build/artifacts/valgrind/test/test_nosanitize_crash_sigsegv.log
 <a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a>
 <a id="__codelineno-14-5" name="__codelineno-14-5" href="#__codelineno-14-5"></a>VALGRIND: FAILED TEST SUMMARY
 <a id="__codelineno-14-6" name="__codelineno-14-6" href="#__codelineno-14-6"></a>[test/test_nosanitize_crash_sigsegv.c]
@@ -4905,15 +4906,15 @@ report. It replaces Ceedling’s generic crash notice:</p>
 <p>With <a href="#fail_build"><code>:fail_build:</code></a> set to <code>false</code>, the same run omits the last
 line. Only the test failure fails the build.</p>
 <p>A test that completes despite memory errors logs one line as it runs:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a>🪲 ERROR: Valgrind detected 2 memory errors in test_example ➡️ see build/artifacts/valgrind/test_example.log
+<div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a>🪲 ERROR: Valgrind detected 2 memory errors in test/test_example ➡️ see build/artifacts/valgrind/test/test_example.log
 </code></pre></div>
 <p>A test whose report is missing logs a warning, since its memory error status
 is unknown:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a>⚠️ WARNING: Valgrind wrote no report for test_example at build/artifacts/valgrind/test_example.log. Memory error status is unknown.
+<div class="highlight"><pre><span></span><code><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a>⚠️ WARNING: Valgrind wrote no report for test/test_example at build/artifacts/valgrind/test/test_example.log. Memory error status is unknown.
 </code></pre></div>
 <h2 id="interpreting-results">Interpreting results</h2>
 <p>To review the log for a specific test:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a>cat<span class="w"> </span>build/artifacts/valgrind/test_my_module.log
+<div class="highlight"><pre><span></span><code><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a>cat<span class="w"> </span>build/artifacts/valgrind/test/test_my_module.log
 </code></pre></div>
 <p>Common Valgrind findings include:</p>
 <table>

data/site-local/project/upgrade.html

@@ -4468,6 +4468,9 @@ update our project.</p>
 <p>Ceedling will automatically look for your project yaml file and do its best to determine what needs
 to be updated. If installed locally, this will mean copying the latest copy of Unity, CMock, and
 Ceedling. It will also involve copying documentation, if you had that installed.</p>
+<p><code>upgrade</code> copies the Ceedling you run, or the installation the <code>WHICH_CEEDLING</code> environment
+variable names. As of 1.2.2, it never copies from your project’s own vendored Ceedling, so
+<code>ceedling upgrade .</code> from inside the project works too.</p>
 <h2 id="step-3-solving-problems">Step 3: Solving Problems</h2>
 <p>We wish every project would update seamlessly... unfortunately there is a lot of customization that
 goes into each project, and Ceedling often isn't aware of all of these. To make matter worse, Ceedling

data/site-local/reference/command-line.html

@@ -5102,8 +5102,9 @@ use <code>ceedling example</code>.</p>
   and/or a starter project configuration file.</p>
 <hr />
 <h3 id="ceedling-upgrade"><a href="../getting-started/command-line.html#ceedling-upgrade-path"><code>ceedling upgrade</code></a></h3>
-<p>Upgrade vendored installation of Ceedling for an existing project 
-  along with any locally installed documentation bundles.</p>
+<p>Upgrade vendored installation of Ceedling for an existing project, from
+  the version of Ceedling you run, along with any documentation <code>--docs</code> 
+  exported.</p>
 <hr />
 <h3 id="ceedling-version"><a href="../getting-started/command-line.html#ceedling-version"><code>ceedling version</code></a></h3>
 <p>Displays version information for Ceedling and its components. Version 
@@ -5121,6 +5122,12 @@ build identifier and Ceedling’s path of origin.</p>
 <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; #.#.#
 </code></pre></div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>For a project configuration that selects another Ceedling installation
+different from the installation that launched Ceedling, <code>version</code> reports 
+the launcher and the selected application versions separately.</p>
+</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 Ruby Gem at the time of Ceedling’s 

data/site-local/snapshot/plugins/bullseye/config/defaults_bullseye.rb

@@ -51,7 +51,7 @@ DEFAULT_BULLSEYE_LINKER_TOOL = {
   }
 
 DEFAULT_BULLSEYE_FIXTURE_TOOL = {
-  :executable => '${1}'.freeze,
+  :executable => '"${1}"'.freeze, # Test executable, quoted as a path
   :name => 'default_bullseye_fixture'.freeze,
   :optional => false.freeze,
   :arguments => [].freeze

data/site-local/snapshot/plugins/gcov/config/defaults_gcov.rb

@@ -41,7 +41,7 @@ DEFAULT_GCOV_LINKER_TOOL = {
   }
 
 DEFAULT_GCOV_FIXTURE_TOOL = {
-  :executable => '${1}'.freeze,
+  :executable => '"${1}"'.freeze, # Test executable, quoted as a path
   :name => 'default_gcov_fixture'.freeze,
   :optional => false.freeze,
   :arguments => [].freeze

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

@@ -1334,6 +1334,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#test-names-build-output" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Test names &amp; build output
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -4705,6 +4716,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#test-names-build-output" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Test names &amp; build output
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -5240,6 +5262,37 @@ of its own. Whether yours does depends on your toolchain.</p>
 <p>Before 1.2.0, Ceedling wrote no manifest. With a toolchain that embeds none,
 test files with these words in their names could not be run on Windows without
 administrator privileges.</p>
+<h3 id="test-names-build-output">Test names &amp; build output</h3>
+<p>Ceedling names each test by its path from your project’s root, without its
+file extension. <code>test/unit/test_calc.c</code> is named <code>test/unit/test_calc</code>. Every
+test gets its own build output, even when test files share a filename.</p>
+<p>The name places a test’s output beneath each build directory:</p>
+<ul>
+<li>Executable: <code>build/test/out/test/unit/test_calc/</code></li>
+<li>Results: <code>build/test/results/test/unit/test_calc.pass</code></li>
+<li>Logs from plugins and backtraces, such as
+  <code>build/artifacts/valgrind/test/unit/test_calc.log</code> or
+  <code>build/logs/test/test/unit/test_calc/&lt;test case&gt;.gdb.log</code></li>
+</ul>
+<p>Within a test’s directory, each object sits at its source’s own path from your
+project’s root, so same-named sources never share a path. <code>src/drivers/uart.c</code>
+compiles to <code>build/test/out/test/unit/test_calc/src/drivers/uart.o</code>. Preprocessed
+files and dependency files follow the same layout, and a release build places its
+objects the same way below <code>build/release/out/</code>. Mocks sit below their test’s own
+mock directory, and runners and Unity, CMock, and CException objects sit directly in
+the test’s directory.</p>
+<p>A test or source outside your project keeps its whole path. Each <code>..</code> becomes
+<code>_up_</code>, so <code>../shared/test/test_io.c</code> is named <code>_up_/shared/test/test_io</code>. A path
+with no relative form, such as one on another Windows drive, sits beneath <code>_abs_</code>,
+and a file of the running Ceedling installation outside your project, such as a
+plugin’s source, beneath <code>_ceedling_</code>. None of these reaches outside the build
+directory. A directory of your project that is itself named like one of these
+gains a leading <code>_</code> (e.g. <code>__up_/</code>), so it never shares a name with a path outside
+your project.</p>
+<p>Two tests share a name only if their paths differ in extension alone (e.g.
+<code>test_a.c</code> and <code>test_a.cpp</code>). A build that includes either test stops with an
+error naming both files. Two sources that would build to one file stop a build the
+same way.</p>
 <h3 id="source-mock-files-to-compile-and-link">Source &amp; mock files to compile and link</h3>
 <p>Ceedling knows what files to compile and link into each individual
 test executable by way of the <code>#include</code> list contained in each