ceedling 1.1.10 → 1.2.1

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

@@ -1,283 +0,0 @@
-# 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

@@ -1,92 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# =========================================================================
-#   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
-    :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
-...

data/docs/mkdocs/snapshot/plugins/gcov/config/defaults_gcov.rb

@@ -1,136 +0,0 @@
-# =========================================================================
-#   Ceedling - Test-Centered Build System for C
-#   ThrowTheSwitch.org
-#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
-#   SPDX-License-Identifier: MIT
-# =========================================================================
-
-DEFAULT_GCOV_COMPILER_TOOL = {
-  :executable => FilePathUtils.os_executable_ext('gcc').freeze,
-  :name => 'default_gcov_compiler'.freeze,
-  :optional => false.freeze,
-  :arguments => [
-    "-g".freeze,
-    "-fprofile-arcs".freeze,
-    "-ftest-coverage".freeze,
-    "-I\"${5}\"".freeze, # Per-test executable search paths
-    "-D\"${6}\"".freeze, # Per-test executable defines
-    "-DGCOV_COMPILER".freeze,
-    "-DCODE_COVERAGE".freeze,
-    "-c \"${1}\"".freeze,
-    "-o \"${2}\"".freeze,
-    # gcc's list file output options are complex; no use of ${3} parameter in default config
-    "-MMD".freeze,
-    "-MF \"${4}\"".freeze,
-    ].freeze
-  }
-
-DEFAULT_GCOV_LINKER_TOOL = {
-  :executable => FilePathUtils.os_executable_ext('gcc').freeze,
-  :name => 'default_gcov_linker'.freeze,
-  :optional => false.freeze,
-  :arguments => [
-    "-g".freeze,
-    "-fprofile-arcs".freeze,
-    "-ftest-coverage".freeze,
-    "${1}".freeze,
-    "${5}".freeze,
-    "-o \"${2}\"".freeze,
-    "${4}".freeze,
-    ].freeze
-  }
-
-DEFAULT_GCOV_FIXTURE_TOOL = {
-  :executable => '${1}'.freeze,
-  :name => 'default_gcov_fixture'.freeze,
-  :optional => false.freeze,
-  :arguments => [].freeze
-  }
-
-# Produce summaries printed to console
-DEFAULT_GCOV_SUMMARY_TOOL = {
-  :executable => FilePathUtils.os_executable_ext('gcov').freeze,
-  :name => 'default_gcov_summary'.freeze,
-  :optional => true.freeze,
-  :arguments => [
-    "-n".freeze,          # --no-output
-    "-p".freeze,          # --preserve-paths
-    "-b".freeze,          # --branch-probabilities
-    "-o \"${2}\"".freeze, # --object-directory
-    "\"${1}\"".freeze
-    ].freeze
-  }
-
-# Produce .gcov files (used in conjunction with ReportGenerator)
-DEFAULT_GCOV_REPORT_TOOL = {
-  :executable => FilePathUtils.os_executable_ext('gcov').freeze,
-  :name => 'default_gcov_report'.freeze,
-  :optional => true.freeze,
-  :arguments => [
-    "-b".freeze,            # --branch-probabilities
-    "-c".freeze,            # --branch-counts
-    "-r".freeze,            # --relative-only: skip files with absolute paths (excludes system headers)
-    "-s \"${2}\"".freeze,   # --source-prefix: strip project root so -r accepts project sources recorded with absolute paths
-    "-x".freeze,            # --hash-filenames: unique .gcov name per source path, no collision for same-basename files in different directories
-    "${1}".freeze           # .gcno filepath
-    ].freeze
-  }
-
-# Produce reports with `gcovr`
-DEFAULT_GCOV_GCOVR_REPORT_TOOL = {
-  # No extension handling -- `gcovr` is generally an extensionless Python script
-  :executable => 'gcovr'.freeze,
-  :name => 'default_gcov_gcovr_report'.freeze,
-  :optional => true.freeze,
-  :arguments => [
-    "--root \"${1}\"".freeze,    # ${1}: project root path for gcovr coverage scanning
-    "--exclude \"${2}\"".freeze, # ${2}: exclusion pattern array (one --exclude flag per entry)
-    "${3}".freeze                # ${3}: remaining optional arguments string
-    ].freeze
-  }
-
-# Produce reports with `reportgenerator`
-DEFAULT_GCOV_REPORTGENERATOR_REPORT_TOOL = {
-  :executable => FilePathUtils.os_executable_ext('reportgenerator').freeze,
-  :name => 'default_gcov_reportgenerator_report'.freeze,
-  :optional => true.freeze,
-  :arguments => [
-    "\"-reports:${1}\"".freeze,      # ${1}: .gcov files glob beneath the gcov build output path
-    "\"-targetdir:${2}\"".freeze,    # ${2}: report artifacts output path
-    "\"-reporttypes:${3}\"".freeze,  # ${3}: semicolon-joined ReportGenerator report type names
-    "\"-sourcedirs:${4}\"".freeze,   # ${4}: semicolon-joined source directories (leading . included)
-    "\"-filefilters:${5}\"".freeze,  # ${5}: semicolon-joined file filter expressions
-    "${6}".freeze                    # ${6}: optional arguments (historydir, plugins, verbosity, etc.)
-    ].freeze
-  }
-
-# Used internally to query GCC version at startup
-DEFAULT_GCOV_GCC_VERSION_TOOL = {
-  :executable => FilePathUtils.os_executable_ext('gcc').freeze,
-  :name => 'default_gcov_gcc_version'.freeze,
-  :optional => false.freeze,
-  :arguments => ["--version"].freeze
-  }
-
-# Used internally to query gcovr version at startup
-DEFAULT_GCOV_GCOVR_VERSION_TOOL = {
-  # No extension handling -- `gcovr` is generally an extensionless Python script
-  :executable => 'gcovr'.freeze,
-  :name => 'default_gcov_gcovr_version'.freeze,
-  :optional => true.freeze,
-  :arguments => ["--version"].freeze
-  }
-
-def get_default_config
-  return :tools => {
-    :gcov_compiler => DEFAULT_GCOV_COMPILER_TOOL,
-    :gcov_linker   => DEFAULT_GCOV_LINKER_TOOL,
-    :gcov_fixture  => DEFAULT_GCOV_FIXTURE_TOOL,
-    :gcov_summary  => DEFAULT_GCOV_SUMMARY_TOOL,
-    :gcov_gcc_version => DEFAULT_GCOV_GCC_VERSION_TOOL,
-    :gcov_gcovr_version => DEFAULT_GCOV_GCOVR_VERSION_TOOL,
-    :gcov_report => DEFAULT_GCOV_REPORT_TOOL,
-    :gcov_gcovr_report => DEFAULT_GCOV_GCOVR_REPORT_TOOL,
-    :gcov_reportgenerator_report => DEFAULT_GCOV_REPORTGENERATOR_REPORT_TOOL,
-  }
-end

data/docs/mkdocs/snapshot.yml

@@ -1,20 +0,0 @@
-# =========================================================================
-#   Ceedling - Test-Centered Build System for C
-#   ThrowTheSwitch.org
-#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
-#   SPDX-License-Identifier: MIT
-# =========================================================================
-
-# Files snapshotted from the project tree into docs/snapshot/ for versioned documentation.
-# Paths are relative to the project root. Each file or directory is copied to docs/snapshot/<path>,
-# preserving directory structure.
-#
-# Run `rake docs:snapshot` (or `rake docs:build`) to refresh.
-
-files:
-  - assets/project.yml
-  - plugins/gcov/config/defaults_gcov.rb
-  - plugins/gcov/config/defaults.yml
-  - examples/temp_sensor/README.md
-  - examples/wondrous_forest/README.md
-  - examples/cipher_quest/README.md