ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/testing-guide/frameworks.md

@@ -0,0 +1,192 @@
+# Using Unity, CMock & CException
+
+If you jumped ahead to this section but do not follow some of the 
+lingo here, please jump back to an [earlier section for definitions
+and helpful links](../overview/tools-and-frameworks.md#so-many-tools-and-acronyms).
+
+## How Ceedling supports, well, its supporting frameworks
+
+If you are using Ceedling for unit testing, this means you are using Unity,
+the C testing framework. Unity is fully built-in and enabled for test builds.
+It cannot be disabled.
+
+If you want to use mocks in your test cases, you'll need to enable mocking 
+and configure CMock with `:project` ↳ `:use_mocks` and the `:cmock` section 
+of your project configuration respectively. CMock is fully supported by 
+Ceedling but generally requires some set up for your project’s needs.
+
+If you are incorporating CException into your release artifact, you'll need 
+to enable exceptions and configure CException with `:project` ↳ 
+`:use_exceptions` and the `:cexception` section of your project 
+configuration respectively. Enabling CException makes it available in both 
+release builds and test builds.
+
+This section provides a high-level view of how the various tools become
+part of your builds and fit into Ceedling’s configuration file. Ceedling’s 
+configuration file is discussed in detail in the next section.
+
+See [Unity], [CMock], and [CException]’s project documentation for all 
+your configuration options. Ceedling offers facilities for providing these
+frameworks their compilation and configuration settings. Discussing 
+these tools and all their options in detail is beyond the scope of Ceedling 
+documentation.
+
+## Unity Configuration
+
+Unity is wholly compiled C code. As such, its configuration is entirely 
+controlled by a variety of compilation symbols. These can be configured
+in Ceedling’s `:unity` project settings.
+
+### Example Unity configurations
+
+#### Itty bitty processor & toolchain with limited test execution options
+
+```yaml
+:unity:
+  :defines:
+    - UNITY_INT_WIDTH=16   # 16 bit processor without support for 32 bit instructions
+    - UNITY_EXCLUDE_FLOAT  # No floating point unit
+```
+
+#### Great big gorilla processor that grunts and scratches
+
+```yaml
+:unity:
+  :defines:
+    - UNITY_SUPPORT_64                    # Big memory, big counters, big registers
+    - UNITY_LINE_TYPE=\"unsigned int\"    # Apparently, we're writing lengthy test files,
+    - UNITY_COUNTER_TYPE=\"unsigned int\" # and we've got a ton of test cases in those test files
+    - UNITY_FLOAT_TYPE=\"double\"         # You betcha
+```
+
+#### Example Unity configuration header file
+
+Sometimes, you may want to funnel all Unity configuration options into a 
+header file rather than organize a lengthy `:unity` ↳ `:defines` list. Perhaps your
+symbol definitions include characters needing escape sequences in YAML that are 
+driving you bonkers.
+
+```yaml
+:unity:
+  :defines:
+    - UNITY_INCLUDE_CONFIG_H
+```
+
+```c
+// unity_config.h
+#ifndef UNITY_CONFIG_H
+#define UNITY_CONFIG_H
+
+#include "uart_output.h" // Helper library for your custom environment
+
+#define UNITY_INT_WIDTH 16
+#define UNITY_OUTPUT_START() uart_init(F_CPU, BAUD) // Helper function to init UART
+#define UNITY_OUTPUT_CHAR(a) uart_putchar(a)        // Helper function to forward char via UART
+#define UNITY_OUTPUT_COMPLETE() uart_complete()     // Helper function to inform that test has ended
+
+#endif
+```
+
+### Routing Unity’s report output
+
+Unity defaults to using `putchar()` from C’s standard library to 
+display test results.
+
+For more exotic environments than a desktop with a terminal — e.g. 
+running tests directly on a non-PC target — you have options.
+
+For instance, you could create a routine that transmits a character via 
+RS232 or USB. Once you have that routine, you can replace `putchar()` 
+calls in Unity by overriding the function-like macro `UNITY_OUTPUT_CHAR`. 
+
+Even though this override can also be defined in Ceedling YAML, most 
+shell environments do not handle parentheses as command line arguments
+very well. Consult your toolchain and shell documentation.
+
+If redefining the function and macros breaks your command line 
+compilation, all necessary options and functionality can be defined in 
+`unity_config.h`. Unity will need the `UNITY_INCLUDE_CONFIG_H` symbol in the
+`:unity` ↳ `:defines` list of your Ceedling project file (see example above).
+
+## CMock Configuration
+
+CMock is enabled in Ceedling by default. However, no part of it enters a
+test build unless mock generation is triggered in your test files. 
+Triggering mock generation is done by an `#include` convention. See the
+section on [Ceedling conventions and behaviors](conventions.md) for more.
+
+You are welcome to disable CMock in the `:project` block of your Ceedling
+configuration file. This is typically only useful in special debugging
+scenarios or for Ceedling development itself.
+
+CMock is a mixture of Ruby and C code. CMock’s Ruby components generate
+C code for your unit tests. CMock’s base C code is compiled and linked into 
+a test executable in the same way that any C file is — including Unity, 
+CException, and generated mock C code, for that matter. 
+
+CMock’s code generation can be configured using YAML similar to Ceedling 
+itself. Ceedling’s project file is something of a container for CMock’s 
+YAML configuration (Ceedling also uses CMock’s configuration, though).
+
+See the documentation for the top-level [`:cmock`][cmock-yaml-config] 
+section within Ceedling’s project file.
+
+[cmock-yaml-config]: ../configuration/reference/cmock.md
+
+Like Unity and CException, CMock’s C components are configured at 
+compilation with symbols managed in your Ceedling project file’s 
+`:cmock` ↳ `:defines` section.
+
+### Example CMock configurations
+
+```yaml
+:project:
+  # Shown for completeness -- CMock enabled by default in Ceedling
+  :use_mocks: TRUE
+
+:cmock:
+  :when_no_prototypes: :warn
+  :enforce_strict_ordering: TRUE
+  :defines:
+    # Memory alignment (packing) on 16 bit boundaries
+    - CMOCK_MEM_ALIGN=1
+  :plugins:
+    - :ignore
+  :treat_as:
+    uint8:    HEX8
+    uint16:   HEX16
+    uint32:   UINT32
+    int8:     INT8
+    bool:     UINT8
+```
+
+## CException Configuration
+
+Like Unity, CException is wholly compiled C code. As such, its 
+configuration is entirely controlled by a variety of `#define` symbols. 
+These can be configured in Ceedling’s `:cexception` ↳ `:defines` project 
+settings.
+
+Unlike Unity which is always available in test builds and CMock that 
+defaults to available in test builds, CException must be enabled
+if you wish to use it in your project.
+
+### Example CException configurations
+
+```yaml
+:project:
+  # Enable CException for both test and release builds
+  :use_exceptions: TRUE
+
+:cexception:
+  :defines:
+    # Possible exception codes of -127 to +127 
+    - CEXCEPTION_T='signed char'
+
+```
+
+[Unity]: http://github.com/ThrowTheSwitch/Unity
+[CMock]: http://github.com/ThrowTheSwitch/CMock
+[CException]: http://github.com/ThrowTheSwitch/CException
+
+<br/><br/>

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

@@ -0,0 +1,80 @@
+# Testing Guide
+
+!!! danger "Test file naming in Windows"
+    **_Test filenames should not include “patch” or “setup”_**.
+    Test filenames become test executables. Windows Installer Detection 
+    Technology (part of UAC) requires administrator privileges to run 
+    executables with this naming.
+
+## Test Cases & Test Suites
+
+<div class="grid cards" markdown>
+
+-   :material-help-circle: **[How Does a Test Case Even Work?][test-cases]**
+
+    ---
+
+    A brief overview of how test cases work with simple examples illustrating
+    assertions and mocks.
+
+-   :material-file-code: **[Commented Sample Test File][test-sample]**
+
+    ---
+
+    A sample test file illustrating the Ceedling conventions that make it go. 
+    Includes a discussion of what gets compiled and linked into a test executable.
+
+-   :material-layers: **[Anatomy of a Test Suite][test-suite-anatomy]**
+
+    ---
+
+    How a unit test grows up to become a test suite — what a test executable
+    is, why there are multiple, and Ceedling’s role in building and running them.
+
+</div>
+
+## Testing with Ceedling
+
+<div class="grid cards" markdown>
+
+-   :material-book-open-page-variant: **[Important Conventions & Behaviors][conventions]**
+
+    ---
+
+    Much of what Ceedling accomplishes is by convention. Code and file structures 
+    and naming trigger sophisticated test build features. Also covers search paths, 
+    file extensions, preprocessing, and more.
+
+-   :material-link-variant: **[Using Unity & CMock][frameworks]**
+
+    ---
+
+    Ceedling connects the Unity and CMock frameworks — each of which 
+    can require configuration of its own. Ceedling facilitates this.
+
+-   :material-content-cut: **[Partials][partials]**
+
+    ---
+
+    Partials are like a scalpel for your source code. A generated partial allows 
+    you to test and mock parts of your code you could not otherwise access
+    without rewriting it first.
+
+-   :material-pound: **[Build Directive Macros][build-directives]**
+
+    ---
+
+    In-test macros to accomplish build goals when Ceedling’s conventions aren’t
+    quite enough — adding source files, handling include paths, and more.
+
+</div>
+
+[test-cases]:         test-cases.md
+[test-sample]:        test-sample.md
+[test-suite-anatomy]: test-suite-anatomy.md
+[conventions]:        conventions.md
+[frameworks]:         frameworks.md
+[build-directives]:   build-directives.md
+[partials]:           partials/index.md
+
+<br/><br/>

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

@@ -0,0 +1,67 @@
+# Configuring Partials
+
+!!! note "Documentation convention"
+    `*` is a stand-in or wildcard to refer to all variations of a particular macro type.
+
+## Enabling Partials
+
+Enable Partials in your project YAML under the `:project:` block:
+
+```yaml
+:project:
+  :use_partials: true
+```
+
+See the [:project: configuration reference](../../configuration/reference/project.md#use_partials)
+for the full setting description.
+
+Enabling `:use_partials:` automatically:
+
+- Enables `:use_mocks` as Partials depend on CMock’s mocking infrastructure.
+- Supersedes CMock’s `:treat_inlines` setting. With Partials, Ceedling manages 
+  inline function exposure directly.
+
+## `#include "ceedling.h"`
+
+Every test file that uses Partials must include `ceedling.h` before any Partial
+directive macros:
+
+```c
+#include "unity.h"
+#include "ceedling.h" // Required -- defines all Partial directive macros
+```
+
+`ceedling.h` defines the `TEST_PARTIAL_*`, `MOCK_PARTIAL_*`, `*_CONFIG`, and
+`PARTIAL_LOCAL_VAR()` macros. Without this include, the macros are undefined.
+
+## Partials macro categories
+
+See the [Partials Macros Reference](../../reference/partials-macros.md) for the complete listing.
+
+### [Module selection](../../reference/partials-macros.md#module-selection-macros)
+
+`TEST_PARTIAL_*_MODULE(module)` / `MOCK_PARTIAL_*_MODULE(module)`
+
+Used as the argument to an `#include` directive to select which functions from a module 
+are gathered into a Test Partial or Mock Partial and establish the base function set.
+These macros also expand into the unique names of the generated Partials header files.
+
+### [Function list configuration](../../reference/partials-macros.md#function-list-configuration-macros)
+
+`TEST_PARTIAL_CONFIG(module, func...)` / `MOCK_PARTIAL_CONFIG(module, func...)`
+
+Statements (not `#include` arguments) that add or subtract individual functions
+from the base set established by the module selection macro.
+
+### [Static variable access](../../reference/partials-macros.md#promoted-static-variable-access)
+
+!!! note
+    Module-scope static variables are automatically `extern`ed in a generated Partial
+    and can be accessed directly in your test cases.
+
+`PARTIAL_LOCAL_VAR(function_name, variable_name)`
+
+Accesses a function-scoped `static` variable that Ceedling has promoted to
+module scope in a generated Partial.
+
+<br/><br/>

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

@@ -0,0 +1,68 @@
+# Conventions and Terminology
+
+## Modules
+
+In Ceedling Partials, a _module_ is a C source file, a C header file, or a matched
+source + header pair sharing the same base filename. The base filename —
+without its extension — is the _module name_.
+
+| Files present | Module name |
+|---|---|
+| `sensor.c` and `sensor.h` | `sensor` |
+| `sensor.h` only | `sensor` |
+| `sensor.c` only | `sensor` |
+
+When both a source file and a header file share a name, Ceedling treats them
+as a single unit. Both files are read when generating a Partial. When only 
+one file is present, only that file is read.
+
+All Partial directive macros take a module name — a bare filename stem with
+no extension, no path, and no quotation marks:
+
+```c
+// Module name: 'sensor'
+// Not "sensor.c" (no quotation marks) or "path/to/sensor"
+#include TEST_PARTIAL_PRIVATE_MODULE(sensor)
+```
+
+## Public / Private Functions
+
+C has no access modifiers. Every function with external linkage is — from the
+language's perspective — equally visible at link time. In the context of
+Partials, Ceedling uses the more modern terms _public_ and _private_ to 
+describe a practical distinction based on function decorators:
+
+### Private functions
+
+“Private” functions carry one or more of the following keywords anywhere in
+their declaration or definition:
+
+* `static`
+* `inline`
+* `__inline`
+* `__inline__`
+* `__forceinline`
+
+A `static` function has internal linkage. It is invisible to the linker
+outside its containing translation unit, and therefore cannot be called or 
+mocked from a test build without special handling. `inline` functions may be 
+folded away by the compiler entirely. Partials use decorators to organize
+lists of functions for testing and mocking, but the decorators are stripped
+in the resulting generated code.
+
+!!! note "Because of preproccesing only the “private” keywords are recognized"
+    The preprocesing steps that are part of generating Partials expand any
+    macros (e.g. `INLINE` or `STATICINLINE`) to the actual keywords decorating
+    function signatures. As such, only the keywords above must be handled.
+
+### Public functions
+
+“Public” functions are everything else — functions with no visibility-
+restricting decorator and ordinary external linkage.
+
+This public/private distinction is one set of filters for assembling a list
+of functions each `_MODULE` macro selects. The filtering and collection is 
+documented in detail in the 
+[Partials function-selection by macro](directives.md#partials-function-selection-by-macro) section.
+
+<br/><br/>

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

@@ -0,0 +1,212 @@
+# Partial Directive Macros
+
+!!! note "Documentation convention"
+    - `*` is a stand-in or wildcard to refer to all variations of a particular macro type.
+    - For brevity, some classes of directive macros are referred to simply by their common
+      suffix (e.g `_MODULE` refers to all the macros with this suffix.)
+
+All Partial configuration is expressed through C macros placed
+in your test file. No separate configuration file is required. The macros
+require `#include "ceedling.h"` present in the test file above and before
+their use.
+
+The [Partial `_MODULE` macros](#partials-function-selection-by-macro) accomplish the following:
+
+1. Expand to a filename for the preceding `#include` directive.
+1. Provide a module name for Ceedling to process for the resulting Partial.
+1. Assemble a base set of functions to test or mock.
+
+The optional Partial `_CONFIG` macros modify the base set of functions 
+from (3). Modifying a base set of functions is documented in detail in the
+[Partials function list configuration macros](#partials-function-list-configuration-macros)
+section.
+
+!!! tip "Configuring Partials"
+    For enabling and configuring Partials, see [Configuring Partials](configuration.md).
+
+## Directive Macros Example
+
+```c
+// Required before we can use the Partials directive macros
+#include "ceedling.h"
+
+// Mock all `static` and/or `inline` functions of `mymodule`
+#include MOCK_PARTIAL_PRIVATE_MODULE(mymodule)
+
+// But, remove `InternalHelper()` from the mocks
+MOCK_PARTIAL_CONFIG(mymodule, -_InternalHelper)
+```
+
+!!! tip "Enable obnoxious level logging to inspect Partials generation"
+    Add `--verbosity obnoxious` (or `-v 4`) to your `test:` command line invocation
+    for detailed logging of the C extraction and Partials generations for your test
+    build. The logged lists of functions and variables can help you fine tune or
+    troubleshoot your Partials configuration.
+
+## `#include` conventions
+
+The `_MODULE` macros each expand to a **string literal** that names a
+generated header file. This means you use them as the argument to `#include`:
+
+```c
+// Must come first -- defines all Partial macros
+#include "ceedling.h"
+
+#include TEST_PARTIAL_*_MODULE(sensor)
+// ↑ Expands to: #include "ceedling_partial_sensor_impl.h"
+```
+
+A `TEST_PARTIAL_*_MODULE` macro always names an implementation header.
+
+```c
+#include "ceedling.h"
+
+#include MOCK_PARTIAL_*_MODULE(sensor)
+// ↑ Expands to: #include "mock_ceedling_partial_sensor_interface.h"
+```
+
+A `MOCK_PARTIAL_*_MODULE` macro always names a mockable interface header.
+
+The filters in place of `*` in the macro names — `PUBLIC`, `PRIVATE`, `ALL`, 
+and none — tell Ceedling how to initialize internal function lists (that 
+can be optionally modified) towards injecting the collected functions into 
+each Partial. 
+
+## Partials function-selection by macro
+
+Each test or mock Partial is independently configured by exactly
+one `_MODULE` macro call. The macro determines the _base set_ of
+functions that Ceedling collects towards generating a Partial. Once
+the base set of functions is determined, explicit additions or 
+subtractions can be applied with `_CONFIG` macros.
+
+This scheme gives you the, test author, full control of which functions
+are injected into which type of Partial while avoiding laboriously
+listing each function individually.
+
+### Partials base function filters
+
+* `[TEST/MOCK]_PARTIAL_ALL_MODULE()`
+* `[TEST/MOCK]_PARTIAL_PUBLIC_MODULE()`
+* `[TEST/MOCK]_PARTIAL_PRIVATE_MODULE()`
+* `[TEST/MOCK]_PARTIAL_MODULE()`
+
+| Macro | Base set of functions | Additions | Subtractions |
+|---:|---|---|---|
+| `_ALL_MODULE` | All functions | Forbidden | Any function |
+| `_PUBLIC_MODULE` | All public functions | Add private | Remove public |
+| `_PRIVATE_MODULE` | All private functions | Add public | Remove private |
+| `_MODULE` | Empty | Any function (at least one) | Forbidden |
+
+#### Example base sets of function by filter
+
+| Functions | `ALL` | `PUBLIC` | `PRIVATE` | None |
+|---:|---|---|---|---|
+| void foo(void) | ✅ | ✅ |  | |
+| static void bar(void) | ✅ | | ✅ | |
+| int baz(void) | ✅ | ✅ | | |
+| inline int oof(int) | ✅ | | ✅ | |
+
+**Notes:**
+
+* `*_PARTIAL_MODULE` requires at least one addition via `*_PARTIAL_CONFIG` 
+  (see next section).
+* `*_PARTIAL_ALL_MODULE` with no subtractions adds every module function to
+  base set of functions.
+* Each module can appear in **at most one** `TEST_PARTIAL_*_MODULE` and 
+  `MOCK_PARTIAL_*_MODULE` macro within a given test file.
+
+### Partials function list configuration macros
+
+`TEST_PARTIAL_CONFIG` and `MOCK_PARTIAL_CONFIG` refine the base set of functions
+filtered by the corresponding `_MODULE` macro. Both `_CONFIG` macros require at 
+least one function name argument beyond the module name.
+
+Note that no quotation marks are needed.
+
+```c
+TEST_PARTIAL_CONFIG(module, func1, func2, ...)
+MOCK_PARTIAL_CONFIG(module, func1, func2, ...)
+```
+
+Similar to the convenion in Ceedling‘s `paths:` and `files:` YAML configuration 
+sections, each function name argument is treated as an **addition** or a 
+**subtraction** depending on an optional prefix character:
+
+| Prefix | Meaning |
+|---:|---|
+| _(none)_ or `+` | Add this function to the Partial<br/>(`<function>` or `+<function>`) |
+| `-` | Exclude this function from the Partial<br/>(`-<function>`) |
+
+```c
+TEST_PARTIAL_CONFIG(module, +func1, +func2, -func3)
+MOCK_PARTIAL_CONFIG(module,  func1,  func2, -func3)
+```
+
+#### Addition & subtraction rules by mode
+
+| Macro | Filter | Subtraction target | Addition target |
+|---:|---|---|---|
+| `_PUBLIC_MODULE` | Public | Public functions only | Private functions |
+| `_PRIVATE_MODULE` | Private | Private functions only | Public functions |
+| `_MODULE` | Accumulate | Forbidden | Any function (one required) |
+| `_ALL_MODULE` | Deduct | Any function | Forbidden |
+
+## `TEST_` / `MOCK_` Partials exclusion
+
+Any function explicitly added on one side via a Partial `_CONFIG` macro is 
+**automatically removed** from the complementary function list (if it exists).
+This prevents the same function from accidentally appearing both in a Partial 
+implementation and Partial mock, which would produce a duplicate symbol linker 
+error.
+
+```c
+// `_InternalHelper()` added to the test side
+// while automatically removed from the mock side.
+#include TEST_PARTIAL_PRIVATE_MODULE(mymodule)
+TEST_PARTIAL_CONFIG(mymodule, _InternalHelper)
+
+// `_InternalHelper()` will NOT appear in the mock.
+#include MOCK_PARTIAL_PUBLIC_MODULE(mymodule)
+```
+
+## Partials configuration examples
+
+### Test a specific private function; Mock everything else
+
+```c
+#include "ceedling.h"
+
+#include TEST_PARTIAL_MODULE(sensor)     // Starts empty
+TEST_PARTIAL_CONFIG(sensor, _ConvertRaw) // Add exactly this one function
+
+#include MOCK_PARTIAL_ALL_MODULE(sensor) // Starts with all functions
+// `_ConvertRaw()` is automatically excluded from the Partial mock
+```
+
+### Test all functions except one; Mock nothing
+
+```c
+#include "ceedling.h"
+
+#include TEST_PARTIAL_ALL_MODULE(sensor)  // All functions
+TEST_PARTIAL_CONFIG(sensor, -Sensor_Init) // Subtract one
+```
+
+### Test public functions plus one private helper; Mock selected private functions
+
+```c
+#include "ceedling.h"
+
+// Test: Start with all public functions
+//       and add one private function
+#include TEST_PARTIAL_PUBLIC_MODULE(sensor)
+TEST_PARTIAL_CONFIG(sensor, _ConvertRaw)
+
+// Mock: Start with no functions
+//       and add a private function
+#include MOCK_PARTIAL_MODULE(sensor)
+MOCK_PARTIAL_CONFIG(sensor, _ReadIOValue)
+```
+
+<br/><br/>