ceedling 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93ed7bddc71b165a08a89d3367cfcd2ca2ec906950d29af5f39d9bd273b1ab14
-  data.tar.gz: a65452f847a9303a3162cdd24da3b9872c4273f3acb47caf2536e86f0728b04e
+  metadata.gz: 56f073ff96051065c1f390744785a8e933cbfa700d81a585495b49d44b318f1c
+  data.tar.gz: 3d9567c9ebb1477eb215fb9cb8cdfd42f76b7b8c5cdfd9cce1010eff89e49ea3
 SHA512:
-  metadata.gz: 5d58a6e9a68dfd282531091e73fad76fa4ffaa3ad4c3394a7a709cbdf3fceaea90309d7895a4682d038a64bd86b3fdbb755a00c6966b82fa956ed96ddada6953
-  data.tar.gz: 11a0af1b9cfcc95848ea25c50f78693c3486c97f3537b59282e766beb204c72ebcf8c561fb46b85c216030f70bb5d215abe6e5c84ba43f032a6ea508fd57f312
+  metadata.gz: 3e108e84bc09d28d53ca336b49cea22e970d6319810b8b68dab3f1dadb9793eb40948589fb771f8f1d6f731ce2319f9ee32b9cc8a12a8f54d32061e4a052c948
+  data.tar.gz: 6e21e05a55622e2836e52feccd2db2c99a2827db4c6b1179f6ed30c702db8a59dc888fd460d23976d07b3c36237e400b0e553ee9493b3f287456bd10099eae29

data/GIT_COMMIT_SHA

@@ -1 +1 @@
-5bbbc8f
+e7770cc

data/README.md

@@ -16,6 +16,8 @@ from the same source module in a single test file and enables testing of
 * Ceedling is now complemented by a full, searchable [documentation site][ceedling-docs-site]
   available both online and as a local bundle exported from Ceedling’s 
   command line.
+* A new [Discourse community forum](https://throwtheswitch.discourse.group) to 
+  supersede the old, spammy Google Group and handful of disparate support channels.
 * More and expanded [example projects][example-projects].
 * New stock plugins for [Valgrind memory checking][valgrind-plugin] and 
 [Cppcheck static analysis][cppcheck-plugin].
@@ -23,7 +25,8 @@ from the same source module in a single test file and enables testing of
    * _Finally_ supports coverage reports for all sources.
    * Adds support for Modified Condition / Decision Coverage.
 * Mixins improvements including an option for [inline YAML at the command line][mixins-inline-yaml].
-* Ceedling’s test preprocessing is once again compatible with Unity’s parameterized test cases (support was temporarily removed with 1.0.0).
+* Ceedling’s test preprocessing is once again compatible with Unity’s 
+  parameterized test cases (support was temporarily removed with 1.0.0).
 * Incorporates the latest updates to [CMock] and [Unity].
 
 [partials-docs]: https://throwtheswitch.github.io/Ceedling/1.1.0/testing-guide/partials/
@@ -136,7 +139,7 @@ Releases have a version number `#.#.#` (`<major>.<minor>.<patch>`). Production s
 
 Official releases are available as:
 
-1. A prepackaged Ruby Gem available through the public [RubyGems repository](https://rubygems.org/gems/ceedling) (installable with `gem install ceedling` at the command line).
+1. A prepackaged Ruby Gem available through the public [RubyGems repository](https://rubygems.org/gems/ceedling) (installable with `gem install ceedling --no-document` at the command line).
 1. Ready-to-run [Docker images](https://hub.docker.com/u/throwtheswitch).
 
 The latest `<major>.<minor>` version is supported with limited support for earlier minor releases.
@@ -161,7 +164,7 @@ Prereleases are not officially supported, but feedback through submitting issues
 * Found a bug or want to suggest a feature?
   **[Submit an issue][ceedling-issues]** at this repo.
 * Trying to understand features or solve a testing problem? Hit the
-  **[discussion forums][forums]**.
+  **[Discourse forums][forums]**.
 * Paid training, customizations, and support contracts are available through 
   **[Ceedling Assist][ceedling-assist]**.
 
@@ -172,7 +175,7 @@ Please familiarize yourself with our guidelines for **[contributing](docs/CONTRI
 Yes, work has begun on **[Ceedling Certified][ceedling-certified]**, a validated version of Ceedling to meet the needs of industry software certification.
 
 [ceedling-issues]: https://github.com/ThrowTheSwitch/Ceedling/issues
-[forums]: https://www.throwtheswitch.org/forums
+[forums]: https://throwtheswitch.discourse.group
 [ceedling-certified]: https://www.thingamabyte.com/ceedlingcertified
 
 <br/>

data/docs/Changelog.md

@@ -10,6 +10,32 @@ This changelog is complemented by three other documents:
 
 ---
 
+# [1.1.1] — 2026-07-23
+
+## 🌟 Added
+
+- Gcov plugin ➡️ Warning logging for disallowed Gcovr configuration values set at the same time as a Gcovr configuration file (`:config_file`) is in use. Disallowed values are ignored. See clarified discussion of [Gcovr options](https://throwtheswitch.github.io/Ceedling/1.1.0/plugins/gcov/gcovr/#gcovr-options) for more.
+
+## 💪 Fixed
+
+New since 1.1.0:
+
+- [#1180](https://github.com/ThrowTheSwitch/Ceedling/issues/1180) Fixed `gcovr` illegal `--exclude` flag when Gcovr configuration file in use.
+- [#1181](https://github.com/ThrowTheSwitch/Ceedling/issues/1181) Fixed linker error when test files contain no test cases (fix was implemented in Unity and vendored into Ceedling).
+
+Backlog bug fixes predating 1.1.0:
+
+- [#1064](https://github.com/ThrowTheSwitch/Ceedling/issues/1064) Fixed include guard handling that in a certain combination of preprocessing and CMock options led to duplicated symbols breaking a test build.
+- [#1098](https://github.com/ThrowTheSwitch/Ceedling/issues/1098) Fixed :test_compiler used instead of :test_assembler for assembly file.
+- [#1009](https://github.com/ThrowTheSwitch/Ceedling/issues/1009) Fixed tool name handling for `command_hooks` plugin.
+
+## ⚠️ Changed
+
+- Clarified and reorganized [Gcovr configuration documentation](https://throwtheswitch.github.io/Ceedling/1.1.0/plugins/gcov/gcovr/) for the Gcov plugin.
+- Added to plugin documentation explanation of necessary plugin task separation (e.g. why `gcov:` is a separate set of tasks that largely duplicates `test:` builds).
+
+---
+
 # [1.1.0] — 2026-07-16
 
 ## 🌟 Added
@@ -18,7 +44,7 @@ This changelog is complemented by three other documents:
 
 [A Partial](https://throwtheswitch.github.io/Ceedling/1.1.0/testing-guide/partials/) is a new feature that allows a test author to work with portions of the same C module under test differently from within the same test file.
 
-With Partials, a test can now cause some functions in the source module under test to be mocked while other source functions are executed against assertions (see #936). Partials also allow testing of `static` and `inline` functions with no modification of your source code under test.
+With Partials, a test can now cause some functions in the source module under test to be mocked while other source functions are executed against assertions (see [#936](https://github.com/ThrowTheSwitch/Ceedling/issues/936)). Partials also allow testing of `static` and `inline` functions with no modification of your source code under test.
 
 💲 The Partials feature made possible thanks to a generous corporate sponsor via a [Ceedling Assist](https://www.thingamabyte.com/ceedling) engagement.
 
@@ -67,7 +93,7 @@ _NOTE:_ The `ReportGenerator` tool does not support extracting MC/DC even if tho
 
 #### Code coverage for all source files, not just those under test
 
-This feature addition resolves a longstanding feature request for coverage reporting (#329 and others).
+This feature addition resolves a longstanding feature request for coverage reporting ([#329](https://github.com/ThrowTheSwitch/Ceedling/issues/329) and others).
 
 The Gcov plugin now includes an `:untested_sources` option that controls how source files not exercised by any test are handled in coverage reporting — from full omission (`:ignore`), to a warning-level filepath listing of files not present in the coverage report (`:list`), to full compile-for-0%-coverage (`:compile`). The default is `:list`.
 
@@ -96,41 +122,43 @@ When test preprocessing is enabled, Ceedling discovers whether your toolchain su
 
 ## 💪 Fixed
 
-- #1011 Performance Improvements.
-- #1014 Line Continuations not working in test name.
-- #1024 Fixed bug in options-handling for warnings log report.
+- [#1011](https://github.com/ThrowTheSwitch/Ceedling/issues/1011) Performance Improvements.
+- [#1014](https://github.com/ThrowTheSwitch/Ceedling/issues/1014) Line Continuations not working in test name.
+- [#1024](https://github.com/ThrowTheSwitch/Ceedling/issues/1024) Fixed bug in options-handling for warnings log report.
 - Now properly reports timing for single-batch builds (i.e. non-parallel builds).
 - Type handling in example `temp_sensor` project compatible with C23 (and previous C standards).
-- #1120 Fixed (by removal) an overly “helpful” holdover from Ceedling’s earliest days causing certain temporary and backup files to be cleaned that were needed by the user’s IDE and text editing tooling.
-- #1162 Fixes to Partials handling for file encoding / multi-byte characters (e.g. ©) in comment blocks.
-- #1160 Proper handling of locales and file encoding.
-- #1135 Fixed test fixture results handling to properly process Unity’s colored output when enabled.
-- #1114 Fixed `:default_tasks` handling.
-- #1144 Fixed flags for release build linking.
-- #1169 Fixed linking with :libraries ↳ :release.
-- #1112 Fixed (via PR #1171) test failures incorrectly returning exit code 0 when the stdout pretty printer plugin is disabled ([Cory Todd](https://github.com/corytodd)).
+- [#1120](https://github.com/ThrowTheSwitch/Ceedling/issues/1120) Fixed (by removal) an overly “helpful” holdover from Ceedling’s earliest days causing certain temporary and backup files to be cleaned that were needed by the user’s IDE and text editing tooling.
+- [#1162](https://github.com/ThrowTheSwitch/Ceedling/issues/1162) Fixes to Partials handling for file encoding / multi-byte characters (e.g. ©) in comment blocks.
+- [#1160](https://github.com/ThrowTheSwitch/Ceedling/issues/1160) Proper handling of locales and file encoding.
+- [#1135](https://github.com/ThrowTheSwitch/Ceedling/issues/1135) Fixed test fixture results handling to properly process Unity’s colored output when enabled.
+- [#1114](https://github.com/ThrowTheSwitch/Ceedling/issues/1114) Fixed `:default_tasks` handling.
+- [#1144](https://github.com/ThrowTheSwitch/Ceedling/issues/1144) Fixed flags for release build linking.
+- [#1169](https://github.com/ThrowTheSwitch/Ceedling/issues/1169) Fixed linking with :libraries ↳ :release.
+- [#1112](https://github.com/ThrowTheSwitch/Ceedling/issues/1112) Fixed (via [PR #1171](https://github.com/ThrowTheSwitch/Ceedling/pull/1171)) test failures incorrectly returning exit code 0 when the stdout pretty printer plugin is disabled ([Cory Todd](https://github.com/corytodd)).
+- [#1102](https://github.com/ThrowTheSwitch/Ceedling/issues/1102) Removing a test file using `:files` section causes crash.
 - Restored build failure registration and final build failure summary. Replaced test build failures by exception with build failure registration.
 
 ### Mixins
-- #1128 Command line mixin precedence.
+- [#984](https://github.com/ThrowTheSwitch/Ceedling/issues/1128) Resolve differing "shapes" of `:defines` when Mixins in use.
+- [#1128](https://github.com/ThrowTheSwitch/Ceedling/issues/1128) Command line mixin precedence.
 - Revisions to [Mixin documentation](https://throwtheswitch.github.io/Ceedling/latest/configuration/mixins) to correct merge order explanations and clarify Mixins generally.
 
 ### `#include`s handling and preprocessing
 - Extensive improvements throughout.
-- PR #1126 Fix for race condition in cache handling of `#include` listings in YAML files.
-- #1015 Probing toolchain for presence of preprocessor directives-only ability.
-- #1085 Fix relative `#include` path handling that broke test build convention.
-- #358 Mocks with relative path in `#include` directive.
-- PR #1056 Fix for extracting `#include` directive filenames that contain dashes.
-- #1127 Fixes to path handling in `#include` directives.
-- #1158 Fixes for `#include` filtering in test runner generation.
+- [PR #1126](https://github.com/ThrowTheSwitch/Ceedling/pull/1126) Fix for race condition in cache handling of `#include` listings in YAML files.
+- [PR #1015](https://github.com/ThrowTheSwitch/Ceedling/pull/1015) Probing toolchain for presence of preprocessor directives-only ability.
+- [#1085](https://github.com/ThrowTheSwitch/Ceedling/issues/1085) Fix relative `#include` path handling that broke test build convention.
+- [#358](https://github.com/ThrowTheSwitch/Ceedling/issues/358) Mocks with relative path in `#include` directive.
+- [PR #1056](https://github.com/ThrowTheSwitch/Ceedling/pull/1056) Fix for extracting `#include` directive filenames that contain dashes.
+- [#1127](https://github.com/ThrowTheSwitch/Ceedling/issues/1127) Fixes to path handling in `#include` directives.
+- [#1158](https://github.com/ThrowTheSwitch/Ceedling/issues/1158) Fixes for `#include` filtering in test runner generation.
 
 ### GCov plugin
 - `:gcov` section of `:flags` is able to use filename matchers again (like `:test` section).
-- #1115 Fixed Gcov plugin for Gcovr configuration file handling.
-- #1161 Fixed “Found no coverage results” when system headers are processed by coverage.
-- #1170 GCovr summary not passed through to NORMAL logging at end of a GCov plugin build.
-- #1081 Fixes for Gcovr summary cooperating with coverage threshold failures.
+- [#1115](https://github.com/ThrowTheSwitch/Ceedling/issues/1115) Fixed Gcov plugin for Gcovr configuration file handling.
+- [#1161](https://github.com/ThrowTheSwitch/Ceedling/issues/1161) Fixed “Found no coverage results” when system headers are processed by coverage.
+- [#1170](https://github.com/ThrowTheSwitch/Ceedling/issues/1170) GCovr summary not passed through to NORMAL logging at end of a GCov plugin build.
+- [#1081](https://github.com/ThrowTheSwitch/Ceedling/issues/1081) Fixes for Gcovr summary cooperating with coverage threshold failures.
 - Prevention of coverage corruption during `ReportGenerator` reporting runs.
 
 ## ⚠️ Changed
@@ -140,7 +168,7 @@ When test preprocessing is enabled, Ceedling discovers whether your toolchain su
 - Resolved ambiguity in updated `ceedling new` handling from 0.31.1 to 1.0.0.
 - Release build logging now matches test build logging.
 - Fixes for typos and grammar in documentation and logging.
-- Added documentation / commented sample in example _project.yml_ for CMock `:treat_inlines` inline function patterns option (PR #1096).
+- Added documentation / commented sample in example _project.yml_ for CMock `:treat_inlines` inline function patterns option ([PR #1096](https://github.com/ThrowTheSwitch/Ceedling/pull/1096)).
 - Integrates latest [Unity](https://github.com/ThrowTheSwitch/Unity) ([2.7.0](https://github.com/ThrowTheSwitch/Unity/blob/master/docs/UnityChangeLog.md)).
 - Integrates latest [CMock](https://github.com/ThrowTheSwitch/CMock) ([2.7.0](https://github.com/ThrowTheSwitch/CMock/blob/master/docs/CMockChangeLog.md)).
 
@@ -149,7 +177,7 @@ When test preprocessing is enabled, Ceedling discovers whether your toolchain su
 - `:gdb` option captures a full log file from `gdb` output and provides that filepath in the test case crash report.
 
 ### Mixins
-- PR #1003 improvements for Mixin merges — clearer logging and edge case handling.
+- [PR #1003](https://github.com/ThrowTheSwitch/Ceedling/pull/1003) improvements for Mixin merges — clearer logging and edge case handling.
 - Added warning logging if a Mixin contains mixins (nesting is not supported).
 - Mixins now merge list content according to mixin priority. In all cases but one, a higher priority mixin inserts its list content before the content of the existing list to which it is merging. In the case of `:tools` `:arguments` lists, insertion occurs at the end of the arguments list to enable the typical CLI convention of rightmost argument having the highest priority.
 
@@ -182,17 +210,17 @@ When test preprocessing is enabled, Ceedling discovers whether your toolchain su
 
 ## 💪 Fixed
 
-- `#978` -- Ceedling attempts to link source files that are commented out and/or removed by preprocessor directives
-- `#979` -- FFF plugin generates "warning: already initialized constant CMock" on some platforms
-- `#980` -- FFF original plugin should not be part of release build (le sigh)
-- `#981` -- Ceedling could not find header file to mock when using preprocessor
-- `#982` -- Ceedling did not inject required header file into mock when using preprocessor
-- `#985` -- Macros not being properly hidden from CMock’s parser when using preprocessor
-- `#988` -- Parsing of `TEST_SOURCE_FILE` did not support special characters (like `.`) in filenames
-- `#888` & `#977` -- Unicode characters produce crashes in various places
-- `#996` -- Improved handling and documentation of module generator path options
-- `#998` -- FFF plugin missing required stringio
-- `#1005` -- Additional handling of preprocessing extraction improvements
+- [#978](https://github.com/ThrowTheSwitch/Ceedling/issues/978) -- Ceedling attempts to link source files that are commented out and/or removed by preprocessor directives
+- [#979](https://github.com/ThrowTheSwitch/Ceedling/issues/979) -- FFF plugin generates "warning: already initialized constant CMock" on some platforms
+- [#980](https://github.com/ThrowTheSwitch/Ceedling/issues/980) -- FFF original plugin should not be part of release build (le sigh)
+- [#981](https://github.com/ThrowTheSwitch/Ceedling/issues/981) -- Ceedling could not find header file to mock when using preprocessor
+- [#982](https://github.com/ThrowTheSwitch/Ceedling/issues/982) -- Ceedling did not inject required header file into mock when using preprocessor
+- [#985](https://github.com/ThrowTheSwitch/Ceedling/issues/985) -- Macros not being properly hidden from CMock’s parser when using preprocessor
+- [#988](https://github.com/ThrowTheSwitch/Ceedling/issues/988) -- Parsing of `TEST_SOURCE_FILE` did not support special characters (like `.`) in filenames
+- [#888](https://github.com/ThrowTheSwitch/Ceedling/issues/888) & [#977](https://github.com/ThrowTheSwitch/Ceedling/issues/977) -- Unicode characters produce crashes in various places
+- [#996](https://github.com/ThrowTheSwitch/Ceedling/issues/996) -- Improved handling and documentation of module generator path options
+- [#998](https://github.com/ThrowTheSwitch/Ceedling/issues/998) -- FFF plugin missing required stringio
+- [PR #1005](https://github.com/ThrowTheSwitch/Ceedling/pull/1005) -- Additional handling of preprocessing extraction improvements
 - Restored `:use_mocks` default to `true` in Ceedling defaults to match documentation and other mocking defaults in template projects.
 - Resolved a preprocessing issue that could cause the content of a file having a similar filename to that of the file `#include`ing it to become mixed with that file.
 - additional documentation improvements

data/docs/KnownIssues.md

@@ -8,10 +8,17 @@ Known issues are complemented by three other documents:
 
 ---
 
+## All versions
+
+- Ceedling installation as a gem (variations of `gem install ceedling`) can fail if installation is allowed to run the default step of RDoc scanning. **Always use `--no-document` to opt out of the RDoc tool’s code scanning during Ceedling installation.** This documentation step is not needed by a user, and, more importantly, RDoc can cause installation failures due to bugs or language incompatibilities in RDoc’s custom language parser. The prepackaged _MadScienceLab_ Docker images avoid this issue entirely.
+
+---
+
 ## 1.1.0 — 2026-07-16
 
 1. The new internal pipeline as of 1.0.0 that allows builds to be parallelized and configured per-test-executable can mean a fair amount of duplication of steps. A header file may be mocked identically multiple times. The same source file may be compiled identically multiple times. The speed gains due to parallelization help make up for this. Future releases will concentrate on optimizing away duplication of build steps.
 1. While header file search paths are now customizable per executable, this currently only applies to the search paths the compiler uses. Distinguishing test files or header files of the same name in different directories for test runner and mock generation respectively continues to rely on educated guesses in Ceedling code.
+1. All header files needed for test compilation must be within the `:includes` path collection. Relative paths in include directives that extend outside the path collection will cause build problems.
 1. Any path for a C file specified with `TEST_SOURCE_FILE(...)` is in relation to **_project root_** — that is, from where you execute `ceedling` at the command line. If you move source files or change your directory structure, many of your `TEST_SOURCE_FILE(...)` calls may need to be updated. A more flexible and dynamic approach to path handling will come in a future update.
 1. The Bullseye code coverage plugin has been temporarily disabled as of 1.0.0. The makers of Bullseye have generously provided a license for development, and the plugin will be available in the next minor release.
 
@@ -21,6 +28,8 @@ Known issues are complemented by three other documents:
 
 1. The new internal pipeline that allows builds to be parallelized and configured per-test-executable can mean a fair amount of duplication of steps. A header file may be mocked identically multiple times. The same source file may be compiled identically multiple times. The speed gains due to parallelization help make up for this. Future releases will concentrate on optimizing away duplication of build steps.
 1. While header file search paths are now customizable per executable, this currently only applies to the search paths the compiler uses. Distinguishing test files or header files of the same name in different directories for test runner and mock generation respectively continues to rely on educated guesses in Ceedling code.
+1. All header files needed for test compilation must be within the `:includes` path collection. Relative paths in include directives that extend outside the path collection will cause build problems.
+1. System header includes `#include <system.h>` may not be properly distinguished from user includes `#include "user.h"` in many test preprocessing scenarios.
 1. Any path for a C file specified with `TEST_SOURCE_FILE(...)` is in relation to **_project root_** — that is, from where you execute `ceedling` at the command line. If you move source files or change your directory structure, many of your `TEST_SOURCE_FILE(...)` calls may need to be updated. A more flexible and dynamic approach to path handling will come in a future update.
 1. Ceedling’s many test preprocessing improvements are not presently able to preserve Unity’s special `TEST_CASE()` and `TEST_RANGE()` features. However, preprocessing of test files is much less frequently needed than preprocessing of mockable header files. Test preprocessing can now be configured to enable only one or the other. As such, these advanced Unity features can still be used in even sophisticated projects.
 1. The Bullseye code coverage plugin has been temporarily disabled until a license can be procured that will allow updates and improvements.

data/docs/ReleaseNotes.md

@@ -24,7 +24,7 @@ The incomplete list of goodies:
    * _Finally_ supports coverage reports for all sources.
    * Adds support for Modified Condition / Decision Coverage.
 * Mixins improvements including an option for [inline YAML at the command line][mixins-inline-yaml].
-* Test preprocessing has undergone significant improvements (again) and is faster, more robust, and handles more testing needs.
+* Test preprocessing has undergone significant improvements (again) and is both more robust and handles more testing needs.
 * Ceedling’s test preprocessing is once again compatible with Unity’s parameterized test cases (support was temporarily removed with 1.0.0).
 * Helpful logging at start up flagging automatic configuration changes or problematic combinations of settings.
 * Integrates latest [Unity](https://github.com/ThrowTheSwitch/Unity) ([2.7.0](https://github.com/ThrowTheSwitch/Unity/blob/master/docs/UnityChangeLog.md)).
@@ -52,6 +52,10 @@ The following is not a complete project configuration. But, for those already fa
 
 ```yaml
 :project:
+  # Optional field that when set with a non-blank string adds a banner with project name
+  # to build logging and to plugin report fields that make use of it.
+  :name: "Q-36 Space Modulator"
+
   # When TRUE enables a significant new set of testing abilities (see Partials documentation).
   # Because this feature depends on test preprocessing and uses mocking, it automatically
   # enables those settings, overriding any user settings disabling them.

data/docs/mkdocs/getting-started/installation.md

@@ -30,9 +30,16 @@ tools lickety split. Install Docker, pull down one of the
 
 ## Installation as a [Ruby Gem][ruby-gem]
 
+!!! warning "Use `--no-document` for gem installation"
+    `--no-document` opts out of the RDoc tool’s automatic scanning of
+    Ceedling source code during installation. This documentation step is not 
+    needed by a user, and, more importantly, RDoc can cause installation 
+    failures due to bugs or language incompatibilities in RDoc’s custom 
+    language parser.
+
 1. [Download and install Ruby][ruby-install]. Ruby 3 is required.
 1. Use Ruby‘s command line gem package manager to install Ceedling from
-   the public [RubyGems repository][rubygems-repo]: `gem install ceedling`.
+   the public [RubyGems repository][rubygems-repo]: `gem install ceedling --no-document`.
     * Unity and CMock come along with Ceedling at no extra charge.
     * Installing from the official RubyGems repository will automatically 
       install Ceedling‘s dependencies.

data/docs/mkdocs/getting-started/quick-start.md

@@ -1,5 +1,25 @@
 # Quick Start
 
+For a test suite project using the default toolchain `gcc`, Ceedling’s
+configuration file could be as simple as this:
+
+```yaml
+:project:
+  :build_root: project/build/
+
+:paths:
+  :test:
+    - tests/**
+  :source:
+    - source/**
+  :include:
+    - inc/**
+```
+
+To execute all your unit tests, you would run `ceedling test:all`.
+
+---
+
 ## Handy Documentation
 
 * [Installation](installation.md)
@@ -9,8 +29,6 @@
 * [Ceedling at the command line](command-line.md)
 * [All your project configuration file options](../configuration/index.md)
 
----
-
 ## Quick Start Steps
 
 Below is a quick overview of how to get started from Ceedling installation 

data/docs/mkdocs/help.md

@@ -15,7 +15,7 @@
     Found a bug or want to suggest a feature? Open an issue in the Ceedling
     GitHub repository.
 
--   :material-forum: **[Discussion Forums][forums]**
+-   :material-forum: **[Discourse Forums][forums]**
 
     ---
 
@@ -40,7 +40,7 @@
 </div>
 
 [ceedling-issues]:       https://github.com/ThrowTheSwitch/Ceedling/issues
-[forums]:                https://www.throwtheswitch.org/forums
+[forums]:                https://throwtheswitch.discourse.group
 [ceedling-assist]:       https://www.thingamabyte.com/ceedlingassist
 [ThingamaByte]:          https://www.thingamabyte.com/
 [thingamabyte-ceedling]: https://www.thingamabyte.com/ceedling

data/docs/mkdocs/index.md

@@ -1,19 +1,24 @@
 # Ceedling Packet
 
 Ceedling is a fancypants build system that greatly simplifies building 
-C projects. While it can certainly build release targets, it absolutely 
+C projects. While it can certainly build release targets, it 
 shines at running unit test suites.
 
-Ceedling and its suite of frameworks, including Unity and CMock, were developed 
-for use on platforms from heavy duty workstations to teeny tiny microcontrollers. 
-Features handy for low-level development have made these tools popular with 
-embedded systems developers.
-
 !!! tip "New to Ceedling?"
     <img src="assets/images/ceedling.svg" width="130"><br/>
     Jump straight to the [Quick Start][quick-start] — installation,
     project set up, and your first build tasks all in one place.
 
+In essence, Ceedling is a project configuration in YAML and a command line
+tool that executes from it. Code conventions and supporting features produce 
+executable test suites and/or release artifacts.
+Plugins provide reporting, code coverage, static analysis, and more.
+
+Ceedling and its suite of frameworks, including Unity and CMock, were developed 
+for use on platforms from heavy duty workstations to teeny tiny microcontrollers. 
+Features handy for low-level development have made these tools popular with 
+embedded systems developers.
+
 !!! feature "New in Ceedling 1.1.0 — Partials"
     A [_Partial_](testing-guide/partials/index.md) is your C code sliced and diced
     to expose functional elements for testing that you could not otherwise 
@@ -23,6 +28,8 @@ embedded systems developers.
     👀 See the [Changelog](https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/Changelog.md)
     for all the new goodness in 1.1.0.
 
+---
+
 ## Overview
 
 <div class="grid cards" markdown>

data/docs/mkdocs/overview/build-system.md

@@ -36,15 +36,15 @@ toolchain `gcc`, the configuration file could be as simple as this:
     - inc/**
 ```
 
+From the command line, to run all your unit tests, you would run 
+`ceedling test:all`. To build the release version of your project,
+you would simply run `ceedling release`. That's it!
+
 !!! tip "Want to see a real world project configuration?"
     See this [commented project file][example-config-file] 
     for a much more complete and sophisticated example of a project 
     configuration.
 
-From the command line, to run all your unit tests, you would run 
-`ceedling test:all`. To build the release version of your project,
-you would simply run `ceedling release`. That's it!
-
 Of course, many more advanced options allow you to configure
 your project with a variety of features to meet a variety of needs.
 Ceedling can work with practically any command line toolchain

data/docs/mkdocs/plugins/bullseye.md

@@ -9,6 +9,12 @@ project configuration.
     [June 1, 2024] Until the Bullseye Plugin can be updated for compatibility 
     with Ceedling >= 1.0.0, it has been disabled.
 
+!!! note
+    The Bullseye plugin creates a duplicate test build with `bullseye:` 
+    command line plugin tasks. [This is intentional and needed](index.md#understanding-plugin-build-duplication).
+
+---
+
 ## Configuration
 
 The bullseye plugin supports configuration options via your `project.yml` provided

data/docs/mkdocs/plugins/command-hooks.md

@@ -4,7 +4,7 @@ Easily run command line tools and scripts at various points in a Ceedling build.
 
 ## Plugin Overview
 
-This plugin allows you to skip creating a full Ceedling plugin for many common use cases. It links Ceedling's programmatic `Plugin` code hooks to easily managed tool definitions. 
+This plugin allows you to skip creating a full Ceedling plugin for many common use cases. It links Ceedling’s programmatic `Plugin` code hooks to easily managed tool definitions. 
 
 ## Setup
 
@@ -40,7 +40,9 @@ See the commented examples below.
 
 Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See the [`:tools` configuration reference][tools-doc] to understand how to craft your argument list and other tool options.
 
-This plugin passes one or two runtime parameters for use in a hook's tool argument list depending on the hook. These parameters are referenced with Ceedling tool argument expansion identifiers `${1}`, `${2}`, etc. Wherever you place `${1}` or `${2}` in your tool argument list, they expand in the command line Ceedling constructs with the parameters this plugin provides for that build step hook. The list of build step hooks below documents which parameters are available for each hook.
+This plugin passes one or two runtime parameters for use in a hook’s tool argument list depending on the hook. These parameters are referenced with Ceedling tool argument expansion identifiers `${1}`, `${2}`, etc. Wherever you place `${1}` or `${2}` in your tool argument list, they expand in the command line Ceedling constructs with the parameters this plugin provides for that build step hook. The list of build step hooks below documents which parameters are available for each hook.
+
+Each tool may optionally include a `:name` — a simple nickname used in log and error messages. If omitted, the plugin forms a default name from the hook’s key (e.g. `pre_mock_generate`). For a hook configured with a list of tools, the default name additionally includes the tool’s position in the list (e.g. `post_link_execute_0`, `post_link_execute_1`). See the commented examples below.
 
 [tools-doc]: ../configuration/reference/tools.md
 
@@ -65,6 +67,7 @@ When logging is enabled and logging conditions are appropriate, any output from
   :pre_mock_generate:
     # This tool is organized as a sub-hash beneath the command hook key
     :executable: python
+    :name: 'mock prep script' # Explicit nickname used in log/error messages
     :arguments:
       - my_script.py
       - --some-arg
@@ -74,18 +77,20 @@ When logging is enabled and logging conditions are appropriate, any output from
   # Hook called for each linking operation
   # Here, we are performing two tasks for the same build step hook, converting a
   # binary executable to S-record format and, then, archiving with other artifacts.
+  # Neither tool below is given a :name -- the plugin defaults them to
+  # "post_link_execute_0" and "post_link_execute_1"
   :post_link_execute:
     # These tools are organized in a YAML list beneath the command hook key
     - :executable: objcopy.exe
       :arguments:
-        - ${1} # Replaced with the filepath to the linker's binary artifact output
+        - ${1} # Replaced with the filepath to the linker’s binary artifact output
         - output.srec
         - --strip-all
     - :executable: 
       :arguments: tar.exe
         - -acf
         - awesome_build.zip
-        - ${1} # Replaced with the filepath to the linker's binary artifact output
+        - ${1} # Replaced with the filepath to the linker’s binary artifact output
         - memory_report.txt
 ```
 
@@ -102,7 +107,7 @@ As an example, consider a Ceedling project with ten test files and seventeen moc
 * 10 occurrences of the `:pre_test` and `:post_test` hooks.
 * 17 occurrences of the `:pre_mock_generate` and `:post_mock_generate` hooks.
 * 10 occurrences of the `:pre_test_runner_generate` and `:post_test_runner_generate` hooks.
-* 27(+) occurrences of the `:pre_compile` and `:post_compile` hooks. These hooks would be called 27 times for test file and mock file compilation. A test suite build will also include compilation of the source files under tests, Unity's source, CMock's source, and generated test runner C files -- easily more than another two dozen compilation hook calls.
+* 27(+) occurrences of the `:pre_compile` and `:post_compile` hooks. These hooks would be called 27 times for test file and mock file compilation. A test suite build will also include compilation of the source files under tests, Unity’s source, CMock’s source, and generated test runner C files -- easily more than another two dozen compilation hook calls.
 * 10 occurrences of the `:pre_link` and `:post_link` hooks for test executable creation.
 * 10 occurrences of the `:pre_test_fixture_execute` and `:post_test_fixture_execute` hooks for running test executables and gathering the results of the tests cases they contain.
 * 1 occurrence of the `:post_test_build` hook.
@@ -130,17 +135,17 @@ The parameter available to a tool (`${1}`) when the hook is called is a floating
 
 Called just before each test begins its build pipeline and just after all context for that build has been gathered.
 
-The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
 
 ### `:post_test`
 
 Called just after each test completes its build and execution.
 
-The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
 
 ### `:pre_test_build`
 
-Called once just before the full test build pipeline begins (before any individual test's configure, preprocess, compile, link, or execute steps).
+Called once just before the full test build pipeline begins (before any individual test’s configure, preprocess, compile, link, or execute steps).
 
 Two parameters are available to a tool when the hook is called:
 
@@ -200,7 +205,7 @@ The parameter available to a tool (`${1}`) when the hook is called is the filepa
 
 If preprocessing is in use, this is called just before each test file is preprocessed before runner generation.
 
-The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
 
 See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
 
@@ -208,7 +213,7 @@ See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling prepr
 
 If preprocessing is in use, this is called just after each test file is preprocessed.
 
-The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
 
 See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
 
@@ -216,13 +221,13 @@ See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling prepr
 
 Called just before each test file is processed by test runner generation.
 
-The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
 
 ### `:post_runner_generate`
 
 Called just after each test runner is generated.
 
-The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
 
 ### `:pre_compile_execute`
 
@@ -240,13 +245,13 @@ The parameter available to a tool (`${1}`) when the hook is called is the filepa
 
 Called just before any binary artifact—test or release—is linked.
 
-The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact’s filepath.
 
 ### `:post_link_execute`
 
 Called just after a binary artifact is linked.
 
-The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
+The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact’s filepath.
 
 ### `:pre_test_fixture_execute`
 
@@ -256,7 +261,7 @@ The parameter available to a tool (`${1}`) when the hook is called is the filepa
 
 ### `:post_test_fixture_execute`
 
-Called just after each test's fixture is executed and test results are collected.
+Called just after each test’s fixture is executed and test results are collected.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact that was executed by the fixture.