ceedling 1.0.0 → 1.1.0

data/docs/mkdocs/testing-guide/partials/example.md

@@ -0,0 +1,149 @@
+# Partials Walk-Through Example
+
+!!! tip "Configuring Partials"
+    Before writing test files that use Partials, see [Configuring Partials](configuration.md)
+    to enable the feature in your project and learn how to configure Partials.
+
+## Temperature sensor module
+
+Imagine a temperature sensor code module…
+
+```c
+// sensor.h -----------------------------------------------
+void Sensor_Init(void);
+int  Sensor_ReadCelsius(void);
+```
+
+```c
+// sensor.c -----------------------------------------------
+#include "sensor.h"
+#include "hal.h" // Hardware Abstraction Layer (to be mocked)
+
+// Private helper -- static, not visible outside this translation unit
+static int _ConvertRawToMilliCelsius(uint16_t raw)
+{
+    return (int)raw * 10 - 40000;
+}
+
+void Sensor_Init(void)
+{
+    HAL_SensorEnable();
+}
+
+int Sensor_ReadCelsius(void)
+{
+    uint16_t raw = HAL_SensorRead();
+    return _ConvertRawToMilliCelsius(raw) / 1000;
+}
+```
+
+## Testing & mocking a `static` helper
+
+!!! tip
+    Ceedling comes with example projects. The example project `wondrous_forest`
+    demonstrates the use of Partials in realistic code.
+    Use [`ceedling example`](../../getting-started/command-line.md#application-commands)
+    to export the `wondrous_forest` project.
+
+You as a test author want to:
+
+1. Test the `static` helper `_ConvertRawToMilliCelsius()` directly
+2. Mock the `static` helper `_ConvertRawToMilliCelsius()` while testing `Sensor_ReadCelsius()`
+
+Partials allows you to accomplish both of these goals with no changes to
+_sensor.c_ even though `_ConvertRawToMilliCelsius()` is static.
+
+!!! warning "A function cannot be both tested and mocked in the same test file"
+    A core restriction of the C language remains here! `_ConvertRawToMilliCelsius()`
+    cannot be both tested and mocked in the same test. Attempting to do so would
+    duplicate the function and cause a doubly-defined symbol failure during linking.
+
+    We solve this by simply creating two peer test files for the different Partials
+    usage scenarios.
+
+## Using the testable partial
+
+```c
+// test_sensor_partials_test.c -----------------------------------
+#include "unity.h"
+#include "ceedling.h" // Required -- defines Partial directive macros
+#include "mock_hal.h" // Traditional mocking still available
+
+// Make all functions in the sensor module available for direct testing
+#include TEST_PARTIAL_ALL_MODULE(sensor)
+
+// Test the `static` conversion helper internal to source module under test
+void test_ConvertRawToMilliCelsius(void)
+{
+    // `_ConvertRawToMilliCelsius()` is accessible in the Partial 
+    // linked in this test executable build
+    TEST_ASSERT_EQUAL_INT(-40000, _ConvertRawToMilliCelsius(0));
+}
+```
+
+### Partials processing step-by-step
+
+1. Reads `sensor.c` and `sensor.h` and extracts all function definitions.
+1. `TEST_PARTIAL_ALL_MODULE()` instructs Partial generation to gather and 
+   expose all functions from the `sensor` module to be made testable.
+1. Generates `ceedling_partial_sensor_impl.c` containing all source functions
+   including `_ConvertRawToMilliCelsius()` (stripped of `static` decorator).
+1. Compiles and links the Partial implementation source (in place of the original 
+   `sensor` source module) and the test file into the test executable. The 
+   symbols and includes of `sensor.h` and `sensor.c` are duplicated in the 
+   Partials while the original `sensor.c` is omitted from the build.
+
+## Using the mockable partial
+
+```c
+// test_sensor_partials_mocks.c -----------------------------------
+#include "unity.h"
+#include "ceedling.h" // Required -- defines Partial directive macros
+#include "mock_hal.h" // Traditional mocking still available
+
+// Create two complementary Partials:
+//  1. All the non-static functions for testing
+//  2. Mocked static functions to be used in test cases
+//
+// We need both Partials with non-overlapping lists of functions in
+// order to separate the testable functions from the mocked functions
+// extracted from the same source module.
+
+// Make all the non-static functions available for testing
+#include TEST_PARTIAL_PUBLIC_MODULE(sensor)
+
+// Make the static helper function available as a mock
+#include MOCK_PARTIAL_PRIVATE_MODULE(sensor)
+
+// Test Sensor_ReadCelsius() using a mock of the helper function
+void test_Sensor_ReadCelsius(void)
+{
+    // Traditional mock of external HAL interface
+    HAL_SensorRead_ExpectAndReturn(1234);
+
+    // Partial mock of `static` function internal to source module under test
+    _ConvertRawToMilliCelsius_ExpectAndReturn(1234, 1000);
+
+    TEST_ASSERT_EQUAL_INT(1, Sensor_ReadCelsius());
+}
+```
+
+### Partials processing step-by-step
+
+1. Reads `sensor.c` and `sensor.h`, extracts all function definitions.
+1. Classifies `_ConvertRawToMilliCelsius` as **private** (from the `static`
+   decorator).
+1. Generates `ceedling_partial_sensor_interface.h` containing only
+   `_ConvertRawToMilliCelsius()`.
+1. Collects all non-static functions in the `sensor` module and
+   generates `ceedling_partial_sensor_impl.h` and 
+   `ceedling_partial_sensor_impl.c` containing those functions segregated
+   from the mockable function signature organized in (3).
+1. Runs CMock on the Partial interface header to produce mock source.
+1. Compiles and links the mocked Partial interface source from (3), the 
+   Partial implementation source from (4) in place of the original `sensor` 
+   source module, and the test file into the test executable. The 
+   symbols and includes of `sensor.h` and `sensor.c` are duplicated in the 
+   Partials while the original `sensor.c` is omitted from the build.
+
+<br/><br/>

data/docs/mkdocs/testing-guide/partials/index.md

@@ -0,0 +1,79 @@
+# Partials
+
+A _Partial_ is your C code sliced and diced to expose elements for testing 
+that you could not otherwise access without rewriting your source code. 
+Think of Partials as a unit testing scalpel.
+
+Partials are useful when a module under test contains:
+
+* **`static` or `inline` functions** — These become accessible within 
+  your test code.
+* **File-scoped `static` variables** — The `static` keyword is stripped, 
+  and the variable is automatically made `extern` for easy access within 
+  your test code.
+* **Function-scoped `static` variables** — These are promoted from
+  function scope to module scope so they can be accessed in your
+  test code. Apart from necessary renaming, this works identically to
+  file-scoped `static` variables.
+
+!!! warning "Limitations of Partials"
+    Partials are new to Ceedling with 1.1.0. Carving up C code is tricky
+    business. Complex code _may_ break Ceedling’s lexing or its assumptions 
+    on symbol ordering. Some issues may be [bugs to be reported](../../help.md) 
+    while others may be complexities that Partials are simply unable to resolve.
+
+---
+
+<div class="grid cards" markdown>
+
+-   :material-magnify: **[What Is a Partial?][overview]**
+
+    ---
+
+    How Ceedling generates testable and mockable Partials from your C source
+    under test with a step-by-step simple example.
+
+-   :material-format-list-text: **[Conventions & Terminology][conventions]**
+
+    ---
+
+    What is a _module_? _“Public”_ and _“private”_ functions in a programming
+    language that has no such terminology.
+
+-   :material-cog: **[Configuration][configuration]**
+
+    ---
+
+    How to enable Partials in your project, include `ceedling.h`, and an
+    overview of directive macro categories.
+
+-   :material-school: **[Walk-Through Example][example]**
+
+    ---
+
+    A complete end-to-end demonstration of Test Partials and Mock Partials.
+
+-   :material-pound: **[Partial Directive Macros][directives]**
+
+    ---
+
+    * Generation macros used with `#include` for creating Partials.
+    * Config macros for fine-tuning your Partials.
+
+-   :material-variable: **[Accessing Static Variables][variables]**
+
+    ---
+
+    How to test file-scoped and function-scoped `static` variables 
+    via Partials.
+
+</div>
+
+[overview]:        overview.md
+[conventions]:     conventions.md
+[directives]:      directives.md
+[variables]:       variables.md
+[configuration]:   configuration.md
+[example]:         example.md
+
+<br/><br/>

data/docs/mkdocs/testing-guide/partials/overview.md

@@ -0,0 +1,81 @@
+# What Is a Partial?
+
+## Slicing and dicing your C code
+
+Ceedling reads your real source and header files, extracts their C contents,
+and generates new C files that comprise a Partial.
+
+Ceedling can create two kinds of Partials:
+
+1. A **_Test Partial_** for exposing otherwise inaccessible functions and 
+   variables to your test case assertions.
+1. A **_Mock Partial_** for mocking otherwise inaccessible functions in your
+   source code.
+
+!!! warning "A function cannot be both tested and mocked in the same test file"
+    A core restriction of the C language remains. A partialized function cannot
+    be both tested and mocked in the same test. Attempting to do so would duplicate
+    the function and cause a doubly-defined symbol failure during linking.
+    
+    We solve this by simply creating two peer test files for the different Partials
+    usage scenarios.
+
+When a test file references a Partial, Ceedling excludes the original source
+file from that test executable's build. The generated Partial 
+source is compiled and linked in place of the original source C.
+
+!!! note "Purpose-specific C language handling"
+    Ceedling includes its own custom, purpose-specific lexing for recognizing
+    C language elements. This was the best way to handle all cases across
+    platforms. This custom lexer even handles many compiler extensions 
+    (e.g. Microsoft's `__declspec` and GCC's `__attribute__()`).
+    
+    On the upside, this approach provides everything Partials need. On the 
+    downside, until exercised by a great deal of real world code, this custom 
+    C handling will likely have failings and gaps.
+
+## Partials creation step-by-step
+
+When creating a Partial, Ceedling:
+
+1. Runs your source code under test through the preprocessor to:
+    1. Handle `#ifdef` blocks and strip comments.
+    1. Collect the `#include` directives.
+    1. Expand decorator macros (e.g. `STATICINLINE`) in function signatures.
+1. Lexes the code under test to collect its individual C language elements
+   (e.g. `typedef`s, macros, functions, variables, etc.).
+1. Generates a new set of C files in a _partials/_ build directory. The 
+   contents of these new files are:
+    1. Reconstructed with the `#include` directives from (1) and elements 
+       from (2).
+    1. Reorganized and slightly altered so the C elements can be accessed by 
+       assertions and mocks in your test cases. Functions are stripped of 
+       `static` and `inline`. Variables are stripped of `static` and `extern`ed.
+1. Structures the test build to omit the original source file from the 
+   resulting test executable. Generated Partials are self-sufficient stand-ins 
+   for the original C code from which the Partials are derived.
+1. Maps the reorganized functions in generated Partials back to the 
+   original source module's filepath and line numbers (using GCC's `#line` 
+   directive) for correct test coverage reporting.
+
+!!! tip "Walk-through example"
+    See [Partials Walk-Through Example](example.md) for a complete end-to-end
+    demonstration of Test Partials and Mock Partials.
+
+## Generated files
+
+| Partial | Purpose | Generated filename pattern |
+|---|---|---|
+| Testable header | <ul><li>Declares functions</li><li>`extern`s variables</li></ul> | `ceedling_partial_<module>_impl.h` |
+| Testable source | <ul><li>Defines functions</li><li>Defines `static`-less variables</li></ul> | `ceedling_partial_<module>_impl.c` |
+| Mockable header | <ul><li>Declares function signatures</li></ul> | `ceedling_partial_<module>_interface.h` |
+
+Ceedling uses CMock to generate mocks from Partials interface header files
+just as it does for any other mockable header files.
+
+!!! danger "Do not directly access generated Partials files"
+    You as the test author will never directly interact with generated 
+    Partials C files. Do not modify these generated files or 
+    incorporate them into your tests except with the accompanying macros.
+
+<br/><br/>

data/docs/mkdocs/testing-guide/partials/variables.md

@@ -0,0 +1,244 @@
+# Accessing Static Variables
+
+## File-Scoped Static Variables
+
+A file-scoped `static` variable is declared at the top level of a `.c` file
+with the `static` keyword. Like a `static` function, it has _internal linkage_ 
+-- the linker cannot see it outside the translation unit in which it is defined.
+This means test code in a separate translation unit cannot read or write it,
+making it impossible to inspect state or reset it between test cases without
+modifying the production source.
+
+When Ceedling generates a Partial it automatically copies every file-scoped 
+`static` variable found in the source module into the Partial and strips the 
+`static` keyword. The resulting definition in the generated `_impl.c` file 
+has external linkage. A matching `extern` declaration is emitted in the 
+generated `_impl.h` header. Including any `TEST_PARTIAL_*_MODULE` macro brings 
+that `extern` declaration into scope, causing the variable to accessible in 
+test code directly by its **original name** — no renaming or helper macro is 
+required.
+
+### Partial file-scoped static variable example
+
+Extending the sensor module with a file-scoped error counter:
+
+```c
+// sensor.c -----------------------------------------------
+// File-scoped; invisible outside sensor.c
+static uint32_t g_error_count = 0;
+
+int Sensor_ReadCelsius(void)
+{
+    uint16_t raw = HAL_SensorRead();
+    // Sentinel value signals hardware error
+    if (raw == 0xFFFF) {
+        g_error_count++;
+        return -1;
+    }
+    return _ConvertRawToMilliCelsius(raw) / 1000;
+}
+```
+
+Ceedling strips `static` when generating the test Partial:
+
+```c
+// ceedling_partial_sensor_impl.c (generated) ---------------
+// `static` stripped -- now has external linkage
+uint32_t g_error_count = 0;
+// ...
+int Sensor_ReadCelsius(void)
+{
+    uint16_t raw = HAL_SensorRead();
+    if (raw == 0xFFFF) {
+        g_error_count++;
+        return -1;
+    }
+    return _ConvertRawToMilliCelsius(raw) / 1000;
+}
+```
+
+```c
+// ceedling_partial_sensor_impl.h (generated) ---------------
+// `extern` declaration -- immediately available in test code
+extern uint32_t g_error_count;
+// ...
+```
+
+Because `#include TEST_PARTIAL_*_MODULE()` automatically causes the generated
+Partial header file to be included in your test, the `extern`ed variable is
+immediately available to you in your test.
+
+In the test file, the variable is accessed directly by its original name:
+
+```c
+// test_sensor_partial.c -----------------------------------
+#include "unity.h"
+#include "ceedling.h"
+#include "mock_hal.h"
+
+// Brings `extern g_error_count` into scope
+#include TEST_PARTIAL_ALL_MODULE(sensor)
+
+void setUp(void) {
+    // Reset to known state before each test
+    g_error_count = 0;
+}
+
+void test_ReadCelsius_counts_hardware_errors(void)
+{
+    // Simulate hardware error
+    HAL_SensorRead_ExpectAndReturn(0xFFFF);
+    TEST_ASSERT_EQUAL_INT(-1, Sensor_ReadCelsius());
+    // Access the previously inaccessible `g_error_count`
+    TEST_ASSERT_EQUAL_UINT32(1, g_error_count);
+}
+```
+
+## Function-scoped static variables
+
+C allows variables to be declared `static` inside a function body. Unlike a
+local variable, a function-scoped `static` variable persists across calls —
+its storage is allocated once and retains its value for the lifetime of the
+program. This persistence makes these variables useful for call counters, 
+cached state, accumulated error totals, etc.
+
+In ordinary C, a function-scoped `static` variable is completely inaccessible
+outside its containing function; the C standard does not provide any way to
+take its address or read its value from another translation unit. This makes
+it impossible to inspect or reset it from a test.
+
+When Ceedling generates a Partial, it automatically promotes all function-scoped
+`static` variables to module scope in the generated implementation files.
+The original declaration inside the function body is replaced with a no-op
+statement so that source line mappings for coverage reporting remain accurate.
+
+### Renaming to prevent collisions
+
+Multiple functions in the same module may each contain a function-scoped
+`static` variable with the same name — for example, both `Foo_Init()` and
+`Foo_Reset()` might each have `static uint32_t call_count = 0;`. Promoting
+both to module scope without renaming would produce a duplicate symbol error
+at compilation.
+
+Ceedling resolves this by prepending a prefix of `partial_` and the containing
+function's name to each promoted variable's name:
+
+```
+partial_<function_name>_<variable_name>
+```
+
+Example renaming:
+
+| Original declaration (inside function) | Containing function | Promoted name |
+|---|---|---|
+| `static uint32_t call_count = 0;` | `Sensor_ReadCelsius` | `partial_Sensor_ReadCelsius_call_count` |
+| `static bool initialized = false;` | `Sensor_Init` | `partial_Sensor_Init_initialized` |
+| `static int error_count;` | `Sensor_Init` | `partial_Sensor_Init_error_count` |
+
+The promoted variable is defined in the generated implementation source
+(`ceedling_partial_<module>_impl.c`) and declared `extern` in the generated
+implementation header (`ceedling_partial_<module>_impl.h`). Including the
+implementation header via a `TEST_PARTIAL_*_MODULE` macro therefore makes all
+promoted variables available to your test code.
+
+### `PARTIAL_LOCAL_VAR()` macro to access promoted function-scoped static variables
+
+Typing `partial_Sensor_ReadCelsius_call_count` throughout a test file is
+error-prone. The `PARTIAL_LOCAL_VAR` macro, defined in `ceedling.h`, assembles
+the promoted name from its two components:
+
+```c
+PARTIAL_LOCAL_VAR(function_name, variable_name)
+// Expands to: partial_<function_name>_<variable_name>
+```
+
+`PARTIAL_LOCAL_VAR()` is not a function call. The macro Expands to a simple 
+C identifier. It can appear anywhere a variable name is legal — in expressions, 
+assertions, and assignments.
+
+### Example use of `PARTIAL_LOCAL_VAR()`
+
+Extending the sensor module from earlier examples:
+
+```c
+// sensor.c -----------------------------------------------
+int Sensor_ReadCelsius(void)
+{
+    // Function-scoped static variable that tracks total calls
+    static uint32_t sample_count = 0;
+    sample_count++;
+
+    uint16_t raw = HAL_SensorRead();
+    return _ConvertRawToMilliCelsius(raw) / 1000;
+}
+```
+
+Ceedling promotes `sample_count` to `partial_Sensor_ReadCelsius_sample_count`.
+
+In the copy of `Sensor_ReadCelsius()` organized in a generated Partial, 
+Ceedling replaces the variable declaration inside the function with a no-op
+to preserve code coverage line tracking.
+
+```c
+// ceedling_partial_sensor_impl.c (generated) ---------------
+// ...
+int Sensor_ReadCelsius(void)
+{
+    (void)0; /* static uint32_t sample_count = 0 */
+    partial_Sensor_ReadCelsius_sample_count++;
+
+    uint16_t raw = HAL_SensorRead();
+    return _ConvertRawToMilliCelsius(raw) / 1000;
+}
+```
+
+Ceedling simultaneously organizes an `extern` statement in the generated 
+Partial header file.
+
+```c
+// ceedling_partial_sensor_impl.h (generated) ---------------
+// ...
+extern uint32_t partial_Sensor_ReadCelsius_sample_count;
+// ...
+```
+
+Because `#include TEST_PARTIAL_*_MODULE()` automatically causes the generated
+Partial header file to be included in your test, the promoted, renamed, and
+`extern`ed variable is immediately available to you in your test.
+
+In your test file, `PARTIAL_LOCAL_VAR()` makes the variable accessible for both
+reset and assertion:
+
+```c
+// test_sensor_partial.c -----------------------------------
+#include "unity.h"
+#include "ceedling.h"
+#include TEST_PARTIAL_PRIVATE_MODULE(sensor)
+
+void setUp(void)
+{
+    // Reset promoted static back to its initial value before each test
+    PARTIAL_LOCAL_VAR(Sensor_ReadCelsius, sample_count) = 0;
+}
+
+void test_ReadCelsius_increments_sample_count_on_each_call(void)
+{
+    HAL_SensorRead_ExpectAndReturn(1000);
+    Sensor_ReadCelsius();
+    TEST_ASSERT_EQUAL_UINT32(1, PARTIAL_LOCAL_VAR(Sensor_ReadCelsius, sample_count));
+
+    HAL_SensorRead_ExpectAndReturn(2000);
+    Sensor_ReadCelsius();
+    TEST_ASSERT_EQUAL_UINT32(2, PARTIAL_LOCAL_VAR(Sensor_ReadCelsius, sample_count));
+}
+```
+
+### What `PARTIAL_LOCAL_VAR()` cannot do
+
+`PARTIAL_LOCAL_VAR` is a token-pasting macro — it constructs a C identifier at
+compile time. It cannot be used with a runtime string or a variable holding a
+function name. Both arguments must be literal tokens that match the original
+C identifiers exactly (the function name and the variable name as they appear
+in the source file).
+
+<br/><br/>