ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/snapshot/examples/cipher_quest/README.md

@@ -0,0 +1,210 @@
+# Ceedling Cipher Quest Project
+
+A small field-text toolkit for the discerning intelligence agent. Cipher Quest
+encodes messages, decodes intercepted communications, and analyzes text — but
+only if you tell it which tools to pack.
+
+This example project illustrates:
+
+- **Test builds and release builds of the same project** using Ceedling
+- **Per-test-file symbol definitions** via the `:defines` matcher section in
+  `project.yml`
+- **Conditional compilation** with `#ifdef` to enable/disable feature modules
+- **Release build variants** driven by mixins — the project file itself has no
+  release symbols; each variant is supplied externally
+- **A compile-time `#error`** that prevents building a featureless release binary
+
+This project is limited to string manipulation and relies solely on basic 
+assertions for its test suite (i.e. no mocks or Partials).
+
+---
+
+## Project Structure
+
+```
+cipher_quest/
+├── project.yml          # Ceedling configuration
+├── mixin/               # Release build variant mixins
+│   ├── release_rot13.yml
+│   ├── release_caesar.yml
+│   ├── release_analyze.yml
+│   └── release_full.yml
+├── src/
+│   ├── main.c           # CLI entry point (NOT unit tested)
+│   ├── text_utils.c/.h  # Core string utilities (always compiled)
+│   ├── cipher.c/.h      # Cipher operations (CIPHER_ROT13 / CIPHER_CAESAR)
+│   └── analyzer.c/.h    # Text analysis (ANALYZER_ENABLED)
+└── test/
+    ├── TestTextUtils.c      # Tests core utilities — needs only TEST
+    ├── TestCipherRot13.c    # Tests ROT13    — needs TEST + CIPHER_ROT13
+    ├── TestCipherCaesar.c   # Tests Caesar   — needs TEST + CIPHER_CAESAR
+    └── TestAnalyzer.c       # Tests analysis — needs TEST + ANALYZER_ENABLED
+```
+
+---
+
+## Feature Symbols
+
+| Symbol             | Enables                              |
+|--------------------|--------------------------------------|
+| `CIPHER_ROT13`     | ROT13 encode/decode                  |
+| `CIPHER_CAESAR`    | Caesar cipher encrypt/decrypt        |
+| `ANALYZER_ENABLED` | Character count, frequency, palindrome detection |
+
+Both `CIPHER_ROT13` and `CIPHER_CAESAR` can be defined simultaneously.
+If none of the three symbols is defined at compile time, `main.c` raises
+a `#error` to prevent building a binary that can't do anything useful.
+
+---
+
+## Test Build
+
+Run all unit tests (no feature symbols needed beyond `TEST`, which Ceedling
+applies automatically via the `'*'` matcher in `project.yml`):
+
+```sh
+ceedling test:all
+```
+
+Each test file that exercises a conditionally compiled feature gets its
+own symbol via the `:defines` matcher in `project.yml`:
+
+```yaml
+:defines:
+  :test:
+    '*':
+      - TEST
+    :TestCipherRot13:
+      - CIPHER_ROT13
+    :TestCipherCaesar:
+      - CIPHER_CAESAR
+    :TestAnalyzer:
+      - ANALYZER_ENABLED
+```
+
+This means each test executable sees only the symbols it needs. The ROT13
+tests compile `cipher.c` with `CIPHER_ROT13` defined; the Caesar tests
+compile it with `CIPHER_CAESAR`; neither affects the other.
+
+You can also run a single test file:
+
+```sh
+ceedling test:TestCipherRot13
+ceedling test:TestAnalyzer
+```
+
+Or all tests matching a pattern:
+
+```sh
+ceedling test:pattern[Cipher]
+```
+
+---
+
+## Release Build
+
+The `:defines: :release:` section in `project.yml` is intentionally empty.
+A plain `ceedling release` will **fail** at the compilation of `main.c` with
+a descriptive error:
+
+```
+error: "cipher_quest: No feature defined. An agent needs tools. ..."
+```
+
+To build a release binary, supply one or more feature symbols via a mixin.
+
+---
+
+Below is example help output produced by running the executable with no
+command line arguments. This executable was a result of a release build 
+with `CIPHER_ROT13` defined.
+
+```shell
+> build/release/cipher_quest.out
+
+Usage: cipher_quest <command> [args...]
+
+Core commands (always available):
+  reverse <text>             Reverse the characters
+  upper <text>               Convert to uppercase
+  lower <text>               Convert to lowercase
+  trim <text>                Strip leading/trailing whitespace
+  palindrome <text>          Simple palindrome check (exact characters)
+  wordcount <text>           Count words
+
+Cipher: ROT13
+  rot13 <text>               Encode or decode (ROT13 is its own inverse)
+```
+
+### Using a mixin file (optional `@` sigil)
+
+```sh
+# ROT13 variant
+ceedling release --mixin=@mixin/release_rot13.yml
+
+# Caesar cipher variant
+ceedling release --mixin=@mixin/release_caesar.yml
+
+# Analysis variant
+ceedling release --mixin=@mixin/release_analyze.yml
+
+# Full-featured: All capabilities enabled
+ceedling release --mixin=@mixin/release_full.yml
+```
+
+Mixin files are simple YAML fragments that merge into the project
+configuration. For example, `mixin/release_rot13.yml` contains:
+
+```yaml
+:defines:
+  :release:
+    - CIPHER_ROT13
+```
+
+Ceedling deep-merges this with `project.yml`, adding `CIPHER_ROT13` to the
+release compilation flags without modifying the base project file.
+
+### Using inline YAML mixin (`=` sigil)
+
+Rather than referencing a file, YAML can be supplied directly on the command
+line using the `=` sigil prefix. Quote the value to protect YAML special
+characters (colons, brackets, spaces) from shell interpretation:
+
+```sh
+# ROT13 variant
+ceedling release --mixin "=defines: {release: [CIPHER_ROT13]}"
+
+# Caesar cipher variant
+ceedling release --mixin "=defines: {release: [CIPHER_CAESAR]}"
+
+# All features enabled
+ceedling release --mixin "=defines: {release: [CIPHER_ROT13, CIPHER_CAESAR, ANALYZER_ENABLED]}"
+```
+
+Multiple `--mixin` values can be combined and are processed left-to-right:
+
+```sh
+ceedling release --mixin @mixin/release_rot13.yml --mixin "=project: {build_root: ci_build}"
+```
+
+---
+
+## Example Session
+
+```sh
+# Build and run with ROT13 enabled
+ceedling release --mixin=mixin/release_rot13.yml
+./build/release/cipher_quest.out rot13 "Attack at dawn"
+# => Nggnpx ng qnja
+
+./build/release/cipher_quest.out rot13 "Nggnpx ng qnja"
+# => Attack at dawn
+
+# Build with all features and try the analyzer
+ceedling release --mixin=mixin/release_full.yml
+./build/release/cipher_quest.out ispalindrome "A man a plan a canal Panama"
+# => Yes, it is a palindrome.
+
+./build/release/cipher_quest.out caesar 13 "Hello, World!"
+# => Uryyb, Jbeyq!
+```

data/docs/mkdocs/snapshot/examples/temp_sensor/README.md

@@ -0,0 +1,283 @@
+# Ceedling Temperature Sensor Project
+
+An imagined temperature sensor accessory with ADC, timer, and USART
+subsystems — firmware organized in C layers.
+
+This project is test-suite only (no release build).
+
+---
+
+This example project illustrates:
+
+- **CMock mocks** for isolating hardware modules under test.
+- **Platform standin technique** to resolve hardware peripheral access as simple memory 
+  access for test assertions (see [Testing with a Hardware Standin](#testing-with-a-hardware-standin)).
+- **Custom Unity assertions** for project-specific data types, defined in _test/support/_.
+- **Subdirectory test organization** with ADC tests grouped in their own subfolder.
+- **Integration tests** alongside unit tests. Unit tests test modules in isolation.
+  Integration tests combine modules to test for results achieved through cooperation.
+    - _TestTimerIntegrated.c_
+    - _TestUsartIntegrated.c_
+    - _adc/TestAcdPlatformStandin.c_
+    - _TestTimerPlatformStandin.c_
+    - _TestUsartPlatformstandin.c_
+- **Per-file symbol definitions** via the `:defines` matcher section in _project.yml_.
+- **Per-file compiler flags** via the `:flags` section in _project.yml_.
+- **Test preprocessor** enabled for all files (`:use_test_preprocessor: :all`).
+- **Optional add-ons** via Mixins:
+    - `gcov` plugin coverage reporting.
+    - Custom Unity assertion activation for more detailed failure messages.
+
+---
+
+In addition, this project implements the [Model-Conductor-Hardware design pattern][mocking-the-embedded-world]:
+
+* Model modules manage state and logic.
+* Hardware modules abstract hardware interfaces.
+* Conductors link the two together and service them.
+
+Mocks generated by CMock isolate each component for unit testing, and 
+example integration tests demonstrate exercising cross-module and integrated
+behavior.
+
+[mocking-the-embedded-world]: https://static1.squarespace.com/static/50fdbec3e4b0dc8c8e313271/t/5d962ba1e9079c36018e99fa/1570122657926/ESC+2007+Mocking+the+Embedded+World.pdf
+
+---
+
+## Project Structure
+
+```
+temp_sensor/
+├── project.yml              # Ceedling configuration
+├── mixin/                   # Optional add-on configuration
+│   ├── add_gcov.yml         # Enables gcov coverage collection and reporting
+│   └── add_unity_helper.yml # Enables custom assertions for project-specific types
+├── src/
+│   ├── Main.c/.h            # Application entry point
+│   ├── Executor.c/.h        # Task execution loop
+│   ├── TaskScheduler.c/.h   # Cooperative task scheduler
+│   ├── Model.c/.h           # Application data model
+│   ├── TemperatureFilter.c/.h
+│   ├── Adc*.c/.h            # ADC conductor, hardware, and model layers
+│   ├── Timer*.c/.h          # Timer conductor, hardware, and model layers
+│   ├── Usart*.c/.h          # USART conductor, hardware, and model layers
+│   ├── IntrinsicsWrapper.c/.h
+│   ├── Types.h              # Shared type definitions
+│   └── calculators/         # Calculation utilities
+│       ├── TemperatureCalculator.c/.h
+│       └── UsartBaudRateRegisterCalculator.c/.h
+└── test/
+    ├── Test*.c              # Unit and integration tests
+    ├── adc/                 # ADC subsystem tests
+    │   └── TestAdc*.c
+    ├── support/             # Custom assertion helpers (not executed as tests)
+    │   ├── UnityHelper.c    # More assertion failure details than the default comparison
+    │   └── UnityHelper.h
+    └── platform/            # Hardware register standin (not executed as tests)
+        ├── at91sam7s256.c   # Standin peripheral register struct instances
+        └── at91sam7s256.h   # Structs, base-address macros, and bit-mask constants
+```
+
+---
+
+## Running the Tests
+
+Run all unit and integration tests:
+
+```sh
+ceedling test:all
+```
+
+Run a single test file:
+
+```sh
+ceedling test:TestAdcConductor
+ceedling test:TestTimerIntegrated
+```
+
+Run all tests matching a pattern:
+
+```sh
+ceedling test:pattern[Adc]
+ceedling test:pattern[Integrated]
+```
+
+---
+
+## Testing with a Hardware Standin
+
+### The Problem
+
+Embedded source files that drive hardware peripherals typically rely on creative linkage 
+from C to the actual hardware through vendor-defined symbols and chip features (e.g. 
+memory mapped registers):
+
+```c
+/* AdcHardwareConfigurator.c */
+void Adc_Reset(void)
+{
+  AT91C_BASE_ADC->ADC_CR = AT91C_ADC_SWRST;
+}
+```
+(Once upon a time it was fairly common for vendors to add C language extensions for
+their hardware access in code.)
+
+`AT91C_BASE_ADC`, `AT91C_ADC_SWRST`, and the `ADC_CR` field all come from
+the chip vendor’s SDK (_at91sam7s256.h_ for this imagined AT91SAM7S256 
+project). These vendor source files are non-portable.
+
+Further, and more importantly, the underlying peripherals doe not exist 
+apart from the target hardware or an emulator. On the surface, you might think this 
+prevents testing. But, oh no, it does not. There is a way.
+
+### The Standin Approach
+
+A platform standin provides a host-compilable substitute for the vendor
+bridge from C to hardware. The magic of C is that it does not care what is behind a symbol
+so long as the defined symbol meets expectations.
+
+The platform standin approach simply recreates the symbols used to access
+hardware peripherals and points them at a generic block of memory. Reads
+and writes through those symbols to that memory can be tested. The source
+code depending on these symbols remains unchanged.
+
+Two files in _test/platform/_ cover everything the `temp_sensor` hardware 
+source files need:
+
+**_test/platform/at91sam7s256.h_** declares:
+
+1. **Peripheral register structs** — Plain C `typedef struct` types with one
+   field per register used by this project (e.g. `AT91S_ADC`, `AT91S_TC`,
+   `AT91S_US`). Fields match the vendor register names exactly.
+
+2. **Global standin instances** — One `extern` instance per peripheral
+   (`AdcStandin`, `TimerStandin`, `UsartStandin`, …), defined in the
+   accompanying `.c` file and allocated in ordinary program memory.
+
+3. **Base-address macros** — The `AT91C_BASE_*` macros, which in the real
+   SDK expand to hardware addresses, are redefined here to point to the
+   corresponding standin instances:
+   ```c
+   #define AT91C_BASE_ADC  (&AdcStandin)
+   #define AT91C_BASE_TC0  (&TimerStandin)
+   ```
+
+4. **Bit-mask constants** — All `AT91C_*` register bit-field constants
+   (`AT91C_ADC_SWRST`, `AT91C_TC_CPCS`, `AT91C_US_TXRDY`, …) defined with
+   their real AT91SAM7S256 datasheet values.
+
+**_test/platform/at91sam7s256.c_** defines the global structs (i.e. memory)
+that the accessors in _test/platform/at91sam7s256.h_ point to.
+
+Each hardware source file adds `#include "at91sam7s256.h"` — exactly what it
+would include in a real embedded build where the vendor header lives in the
+toolchain’s system include path. Ceedling’s support path (_test/platform/_)
+makes this header resolvable during test builds.
+
+By carefully segmenting include paths between release and test builds and
+selectively swapping in certain symbol definitions in a testing-only C source 
+file, we can cleanly create a portable hardware stand-in suitable for test purposes.
+
+NOTE: This technique only validates what is read and written to the stand-in
+peripherals. It cannot validate that the correct functionality is triggered.
+That requires on-hardware validation.
+
+### What This Enables
+
+Production code runs on the host unchanged. A test calls the real
+hardware-layer function and then inspects the standin struct to verify the
+correct register bits were written:
+
+```c
+void testResetWritesSwrstBitToControlRegister(void)
+{
+  Adc_Reset();
+  TEST_ASSERT_EQUAL_UINT32(AT91C_ADC_SWRST, AdcStandin.ADC_CR);
+}
+```
+
+This catches logic bugs that mocking the hardware function interfaces cannot —
+all without touching real hardware:
+
+* Wrong bit positions
+* Missing enable steps
+* Off-by-one prescaler values
+* Incorrect bitmask combinations
+* Etc.
+
+### The Role of setUp()
+
+Each standin test file’s `setUp()` calls `memset()` to zero all standin structs
+before every test (below). Alternatively, as needed you can also initialize with
+non-zero values to represent hardware specific behaviors.
+
+```c
+void setUp(void)
+{
+  memset(&AdcStandin, 0, sizeof(AdcStandin));
+}
+```
+
+This guarantees a clean slate. If a test finds a non-zero register field, it
+was written there by the code under test during that test — not left over from
+a previous run or from C’s zero-initialization of global storage.
+
+For read-dependent behavior (such as `Usart_PutChar()`, which spins on
+`Usart_ReadyToTransmit()` before transmitting), the test sets the relevant
+standin field to a known value so the production code sees the expected
+hardware state:
+
+```c
+void testPutCharWritesByteToTransmitHoldingRegisterWhenReady(void)
+{
+  UsartStandin.US_CSR = AT91C_US_TXRDY; // Make the ready-check pass
+  Usart_PutChar('Z');
+  TEST_ASSERT_EQUAL_UINT32('Z', UsartStandin.US_THR);
+}
+```
+
+### Where This Fits
+
+A platform standin is not a replacement for on-hardware integration testing.
+It cannot exercise timing, DMA, real interrupt delivery, or silicon errata.
+What it does well:
+
+- **Register configuration logic** — verifies the exact bit patterns written
+  during peripheral initialization sequences.
+- **Status-flag branching** — exercises the code paths that read status
+  registers (e.g. `TC_SR & AT91C_TC_CPCS`) by pre-loading the standin field.
+- **Math and conversion code** — any calculation layered on top of a hardware
+  read (ADC counts → millivolts) is fully exercisable.
+
+Used alongside CMock-based unit tests for the higher architectural layers, the
+standin tests give you meaningful coverage of the hardware-touching code
+without requiring the target board to be present.
+
+### Running the Standin Tests
+
+```sh
+# Run only the platform standin tests
+ceedling test:pattern[PlatformStandin]
+```
+---
+
+## Optional Mixins
+
+### Coverage with gcov
+
+Collect and report test coverage (requires `gcov` and `gcovr`):
+
+```sh
+ceedling gcov:all --mixin=mixin/add_gcov.yml
+```
+
+### Custom Unity assertions
+
+The project defines a custom assertion for `EXAMPLE_STRUCT_T` in
+`test/support/UnityHelper.h`. It is conditionally compiled and activated
+by the `add_unity_helper` mixin, which adds the required define and
+registers the helper with CMock:
+
+```sh
+ceedling test:all --mixin=mixin/add_unity_helper.yml
+```

data/docs/mkdocs/snapshot/examples/wondrous_forest/README.md

@@ -0,0 +1,92 @@
+# Ceedling Wondrous Forest Project
+
+An imagined forest environmental monitoring station that reads temperature,
+humidity, light, and soil moisture from a network of sensors — raising
+alerts when conditions exceed thresholds. The project exists to showcase
+Ceedling's Partials feature alongside traditional mock-based testing.
+
+This example project illustrates:
+
+- **Partials** — testing `static`, `inline`, and `static inline` C functions
+  and `static` variables that are normally inaccessible to the linker
+- **Every major Partials pattern** across a range of sensor and system modules
+- **Partials and mocks used together** in the same test suite
+
+This project is test-suite only (no release build).
+
+---
+
+## Project Structure
+
+```
+wondrous_forest/
+├── project.yml        # Ceedling configuration (note :use_partials: TRUE)
+├── mixin/             # Optional add-on configuration
+│   └── add_gcov.yml   # Enables gcov coverage collection and reporting
+├── src/               # Source modules
+│   ├── TemperatureSensor.c/.h
+│   ├── HumiditySensor.c/.h
+│   ├── LightSensor.c/.h
+│   ├── SoilMoisture.c/.h
+│   ├── AlertManager.c/.h
+│   ├── EventQueue.c/.h
+│   ├── ForestMonitor.c/.h
+│   ├── SensorHal.c/.h
+│   ├── UartDriver.c/.h
+│   └── Types.h
+└── test/              # Test files — Using Partials and traditional assertions/mocks
+    ├── TestTemperatureSensor.c
+    ├── TestHumiditySensor.c
+    ├── TestLightSensor.c
+    ├── TestSoilMoisture.c
+    ├── TestAlertManager.c
+    ├── TestEventQueue.c
+    ├── TestForestMonitor.c
+    ├── TestSensorHal.c
+    └── TestUartDriver.c
+```
+
+---
+
+## Partials Patterns Used
+
+| Test File               | Pattern                                                       |
+|-------------------------|---------------------------------------------------------------|
+| TestTemperatureSensor.c | `TEST_PARTIAL_ALL_MODULE` — public + private functions        |
+| TestHumiditySensor.c    | `TEST_PARTIAL_ALL_MODULE` + `PARTIAL_LOCAL_VAR()`             |
+| TestLightSensor.c       | `TEST_PARTIAL_PUBLIC_MODULE` + `MOCK_PARTIAL_PRIVATE_MODULE`  |
+| TestSoilMoisture.c      | `TEST_PARTIAL_ALL_MODULE` + `PARTIAL_LOCAL_VAR()`             |
+| TestAlertManager.c      | `TEST_PARTIAL_ALL_MODULE` + traditional mock alongside        |
+| TestEventQueue.c        | `TEST_PARTIAL_ALL_MODULE` + file-scope static access          |
+| TestForestMonitor.c     | `TEST_PARTIAL_PUBLIC_MODULE` + `MOCK_PARTIAL_PRIVATE_MODULE`  |
+| TestSensorHal.c         | Traditional — HAL has no private statics                      |
+| TestUartDriver.c        | Traditional — UART driver has no private statics              |
+
+---
+
+## Running the Tests
+
+Run all tests:
+
+```sh
+ceedling test:all
+```
+
+Run a single test file:
+
+```sh
+ceedling test:TestTemperatureSensor
+ceedling test:TestForestMonitor
+```
+
+---
+
+## Optional Mixins
+
+### Coverage with gcov
+
+Collect and report test coverage (requires `gcov` and `gcovr`):
+
+```sh
+ceedling gcov:all --mixin=mixin/add_gcov.yml
+```

data/docs/mkdocs/snapshot/plugins/gcov/config/defaults.yml

@@ -0,0 +1,33 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+---
+:gcov:
+  :summaries: TRUE                # Enable simple coverage summaries to console after tests
+  :report_task: FALSE             # Disabled dedicated report generation task (this enables automatic report generation)
+  :untested_sources: :list        # :ignore (skip entirely), :list (log filepaths not in report), :compile (compile all for 0% coverage)
+  :mcdc: FALSE                    # MC/DC (modified condition/decision) coverage — requires GCC 14+ and gcovr 8+
+
+  :utilities:
+    - gcovr                       # Defaults to `gcovr` as report generation utility
+
+  :reports: []                    # User must specify a report to enable report generation
+
+  :gcovr:
+    :report_root: "."             # Gcovr defaults to scanning for results starting in working directory
+    :config_file: ~               # Specify the location of the GCOVR configuration file to use instead of settings config here
+
+                                  # For v6.0+ merge coverage results for same function tested multiple times
+                                  # The default behavior is 'strict' which will cause a gcovr exception for many users
+    :merge_mode_function: merge-use-line-max
+
+  :report_generator:
+    :verbosity: Warning           # Default verbosity
+    :collection_paths_source: []  # Explicitly defined as default empty array to simplify option validation code
+    :custom_args: []              # Explicitly defined as default empty array to simplify option validation code
+    :gcov_exclude: []             # Explicitly defined as default empty array to simplify option validation code
+...