ceedling 1.1.10 → 1.2.0

data/docs/mkdocs/reference/global-collections.md

@@ -1,160 +0,0 @@
-# Global Collections Reference
-
-Collections are Ruby arrays and Rake FileLists (that act like 
-arrays). Ceedling populates and assembles these by
-processing the project configuration, using internal knowledge, 
-expanding path globs, etc. at startup.
-
-Collections are globally available Ruby constants and are 
-typically used in Rakefiles, plugins, and Ruby scripts where 
-the contents tend to be especially handy for crafting custom 
-functionality.
-
-!!! warning "Collections are no longer a core component of Ceedling"
-    As Ceedling has grown in sophistication and as many of its 
-    features now operate per test executable, the utility of and
-    number of collections has dwindled.
-    
-    Once upon a time, nearly all Ceedling actions happened in 
-    bulk and with the same collections used for all tasks. This 
-    is no longer true.
-
-## File collections
-
-* `COLLECTION_PROJECT_OPTIONS`:
-
-    All project option files with path found in the configured 
-    options paths having the configured YAML file extension.
-
-* `COLLECTION_ALL_TESTS`:
-
-    All files with path found in the configured test paths 
-    having the configured source file extension. 
-
-* `COLLECTION_ALL_ASSEMBLY`:
-
-    All files with path found in the configured source and 
-    test support paths having the configured assembly file 
-    extension. 
-
-* `COLLECTION_ALL_SOURCE`:
-
-    All files with path found in the configured source paths 
-    having the configured source file extension. 
-
-* `COLLECTION_ALL_HEADERS`:
-
-    All files with path found in the configured include, 
-    support, and test paths having the configured header file 
-    extension. 
-
-* `COLLECTION_ALL_SUPPORT`:
-
-    All files with path found in the configured test support 
-    paths having the configured source file extension. 
-
-## Path collections
-
-* `COLLECTION_PATHS_INCLUDE`:
-
-    All configured include paths.
-
-* `COLLECTION_PATHS_SOURCE`:
-
-    All configured source paths.
-
-* `COLLECTION_PATHS_SUPPORT`:
-
-    All configured support paths.
-
-* `COLLECTION_PATHS_TEST`:
-
-    All configured test paths.
-
-* `COLLECTION_PATHS_SOURCE_AND_INCLUDE`:
-
-    All configured source and include paths.
-
-* `COLLECTION_PATHS_SOURCE_INCLUDE_VENDOR`:
-
-    All configured source and include paths plus applicable 
-    vendor paths (Unity's source path plus CMock and 
-    CException's source paths if mocks and exceptions are 
-    enabled).
-
-* `COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE`:
-
-    All configured test, support, source, and include paths.
-
-* `COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR`:
-
-    All test, support, source, include, and applicable 
-    vendor paths (Unity's source path plus CMock and 
-    CException's source paths if mocks and exceptions are 
-    enabled).
-
-* `COLLECTION_PATHS_RELEASE_TOOLCHAIN_INCLUDE`:
-
-    All configured release toolchain include paths.
-
-* `COLLECTION_PATHS_TEST_TOOLCHAIN_INCLUDE`:
-
-    All configured test toolchain include paths.
-
-* `COLLECTION_PATHS_VENDOR`:
-
-    Unity's source path plus CMock and CException's source 
-    paths if mocks and exceptions are enabled.
-
-## Build input collections
-
-* `COLLECTION_RELEASE_BUILD_INPUT`:
-
-    * All files with path found in the configured source 
-      paths having the configured source file extension.
-    * If exceptions are enabled, the source files for 
-      CException.
-    * If assembly support is enabled, all assembly files 
-      found in the configured paths having the configured 
-      assembly file extension.
-
-* `COLLECTION_EXISTING_TEST_BUILD_INPUT`:
-
-    * All files with path found in the configured source 
-      paths having the configured source file extension.
-    * All files with path found in the configured test 
-      paths having the configured source file extension.
-    * Unity's source files.
-    * If exceptions are enabled, the source files for 
-      CException.
-    * If mocks are enabled, the C source files for CMock.
-    * If assembly support is enabled, all assembly files 
-      found in the configured paths having the configured 
-      assembly file extension.
-
-    This collection does not include .c files generated by 
-    Ceedling and its supporting frameworks at build time 
-    (e.g. test runners and mocks). Further, this collection 
-    does not include source files added to a test 
-    executable's build list with the `TEST_SOURCE_FILE()` 
-    build directive macro.
-
-## Options and artifacts
-
-* `COLLECTION_VENDOR_FRAMEWORK_SOURCES`:
-
-    Unity plus CMock, and CException's .c filenames (without 
-    paths) if mocks and exceptions are enabled.
-
-* `COLLECTION_RELEASE_ARTIFACT_EXTRA_LINK_OBJECTS`:
-
-    If exceptions are enabled, CException's .c filenames 
-    (without paths) remapped to configured object file 
-    extension.
-
-* `COLLECTION_TEST_FIXTURE_EXTRA_LINK_OBJECTS`:
-
-    All test support source filenames (without paths) 
-    remapped to configured object file extension.
-
-<br/><br/>

data/docs/mkdocs/reference/index.md

@@ -1,65 +0,0 @@
-# Reference
-
-The Reference section is a quick-lookup companion to Ceedling's narrative
-documentation. Where the other sections explain concepts and walk you through
-workflows, these pages collect every command, macro, variable, constant, and
-configuration section into compact, scannable lists.
-
-<div class="grid cards" markdown>
-
--   :material-console: **[Command Line][command-line]**
-
-    ---
-
-    All application commands and build task syntax.
-
--   :material-book-open-variant: **[Project Configuration][project-configuration]**
-
-    ---
-
-    Project configuration sections, project loading, and modifying 
-    a project configuration with mixins.
-
--   :material-pound: **[Test Build Directives][build-directives]**
-
-    ---
-
-    Macros for affecting the build configuration for an individual test file.
-
--   :material-variable: **[Environment Variables][environment-vars]**
-
-    ---
-
-    Environment variables recognized by Ceedling.
-
--   :material-pound: **[Partials Macros][partials-macros]**
-
-    ---
-
-    All function selection and static variable access macros used with 
-    [Partials](../testing-guide/partials/index.md)
-
--   :material-chart-bar: **[Coverage Reporting][coverage-reporting]**
-
-    ---
-
-    All [GCov plugin](../plugins/gcov/index.md) configuration options including 
-    those for advanced reports with GCovr and ReportGenerator.
-
--   :material-database: **[Global Collections][global-collections]**
-
-    ---
-
-    All globally-accessible Ruby constants assembled at startup.
-
-</div>
-
-[command-line]:          command-line.md
-[project-configuration]: project-configuration.md
-[build-directives]:      build-directives.md
-[environment-vars]:      environment-vars.md
-[partials-macros]:       partials-macros.md
-[global-collections]:    global-collections.md
-[coverage-reporting]:    gcov-plugin.md
-
-<br/><br/>

data/docs/mkdocs/reference/partials-macros.md

@@ -1,79 +0,0 @@
-# Partials Macros Reference
-
-!!! note "Documentation convention"
-    `*` is a stand-in or wildcard to refer to all variations of a particular macro type.
-
----
-
-## Partial directive macros
-
-!!! tip
-    For detailed usage guidance, conventions, and examples, see [Partial Directive Macros](../testing-guide/partials/directives.md).
-
-### Module selection macros
-
-#### Test Partials macros
-
-These macros expand to a string literal that names a generated header
-file to be used with `#include`. `#include "ceedling.h"` must precede
-their use.
-
-* **`TEST_PARTIAL_ALL_MODULE(module)`**<br/>Select all functions in the module to be testable by Partial.
-* **`TEST_PARTIAL_PUBLIC_MODULE(module)`**<br/>Select all public (non-`static`, non-`inline`) functions in the module to be testable by Partial.
-* **`TEST_PARTIAL_PRIVATE_MODULE(module)`**<br/>Select all private (`static` and `inline`) functions in the module to be testable by Partial.
-* **`TEST_PARTIAL_MODULE(module)`**<br/>Begin with an empty function set to be testable by Partial; functions must be added explicitly via `TEST_PARTIAL_CONFIG`.
-
-`TEST_PARTIAL_*` macros expand to an implementation header filename.
-
-#### Mock Partials macros
-
-* **`MOCK_PARTIAL_ALL_MODULE(module)`**<br/>Select all functions in the module to be mockable by Partial.
-* **`MOCK_PARTIAL_PUBLIC_MODULE(module)`**<br/>Select all public (non-`static`, non-`inline`) functions in the module to be mockable by Partial.
-* **`MOCK_PARTIAL_PRIVATE_MODULE(module)`**<br/>Select all private (`static` and `inline`) functions in the module to be mockable by Partial.
-* **`MOCK_PARTIAL_MODULE(module)`**<br/>Begin with an empty function set to be mockable by Partial; functions must be added explicitly via `MOCK_PARTIAL_CONFIG`.
-
-`MOCK_PARTIAL_*` macros expand to a mockable interface header filename.
-
-### Function list configuration macros
-
-These macros are statements (not to be used with `#include` directives) 
-that refine the set of functions selected by the use of any module selection 
-macro above.
-
-* **`TEST_PARTIAL_CONFIG(module, func...)`**<br/>Add or subtract functions from the test Partial’s function set.
-* **`MOCK_PARTIAL_CONFIG(module, func...)`**<br/>Add or subtract functions from the mock Partial’s function set.
-
-### Function list addition and subtraction
-
-!!! tip
-    For the full rules on which additions and subtractions are valid with 
-    each `*_MODULE` variant, see
-    [Partial directive macros](../testing-guide/partials/directives.md#partials-function-list-configuration-macros).
-
-* Prefix a function name with `-` (`-func`) to exclude it from the Partial.
-* Use no prefix or `+` (`+func`) to include it.
-
-A function explicitly added to one side is automatically removed from the 
-complementary Partial to prevent duplicate symbol linker errors.
-
----
-
-## Promoted static variable access
-
-!!! tip
-    For the full explanation of how Ceedling promotes function-scoped `static` 
-    variables to module scope and when to use this macro, see
-    [Accessing Static Variables](../testing-guide/partials/variables.md).
-
-**`PARTIAL_LOCAL_VAR(function_name, variable_name)`**
-
-Access a function-scoped `static` variable that Ceedling has promoted to
-module scope in a generated Partial. The macro expands to the promoted
-identifier `partial_<function_name>_<variable_name>`.
-
-- Defined in `ceedling.h`; requires `#include "ceedling.h"` above its use
-- Both arguments must be literal C identifiers — not strings or runtime values
-- Can appear anywhere a variable name is legal: expressions, assertions,
-  assignments
-
-<br/><br/>

data/docs/mkdocs/reference/project-configuration.md

@@ -1,46 +0,0 @@
-# Project Configuration Reference
-
-Ceedling's project configuration is assembled from one or more sources and
-merged into a single in-memory data structure before any build begins. The
-base configuration comes from a YAML project file. That base can be extended
-by [Mixins](../configuration/reference/mixins.md) — additional YAML files
-merged in after the base is loaded. Mixins can be specified from the command
-line, via environment variables, or from within the project file using the
-`:mixins:` section listed below.
-
-For the full details on how loading and merging work — including the search
-order for the default project file and all Mixin sources — see
-[Loading Configuration](../configuration/loading.md). For the environment
-variables that influence configuration loading, see
-[Environment Variables](../configuration/environment-vars.md).
-
-For conceptual overview and project file conventions, see
-[Configuration](../configuration/index.md).
-
-## Configuration sections
-
-Each top-level key in your project YAML file corresponds to one configuration
-section. All sections are optional; Ceedling supplies defaults for anything
-left unset.
-
-| Section | Description |
-|---|---|
-| **[`:project`](../configuration/reference/project.md)** | Build root, build modes, version info, and global project switches |
-| **[`:mixins`](../configuration/reference/mixins.md)** | Load and merge additional YAML configuration files into the base project configuration |
-| **[`:test_build`](../configuration/reference/test-build.md)** | Test-specific build options: assembly support, mock generation, preprocessor use, and more |
-| **[`:release_build`](../configuration/reference/release-build.md)** | Release artifact build options and output settings |
-| **[`:paths`](../configuration/reference/paths.md)** | Source, test, include, support, library, and vendor path globs |
-| **[`:files`](../configuration/reference/files.md)** | Explicit file inclusion and exclusion overrides |
-| **[`:environment`](../configuration/reference/environment.md)** | Set and export environment variables from within the project configuration |
-| **[`:extension`](../configuration/reference/extension.md)** | File extension strings for source, header, object, binary, and other file types |
-| **[`:defines`](../configuration/reference/defines.md)** | Per-context, per-file preprocessor symbol definitions |
-| **[`:flags`](../configuration/reference/flags.md)** | Compiler, linker, assembler, and preprocessor flags per build context |
-| **[`:libraries`](../configuration/reference/libraries.md)** | Test and release libraries plus linker search paths |
-| **[`:unity`](../configuration/reference/unity.md)** | Unity test framework configuration (defines, helper file paths, etc.) |
-| **[`:cmock`](../configuration/reference/cmock.md)** | CMock mock generation configuration |
-| **[`:test_runner`](../configuration/reference/test-runner.md)** | Test runner generation configuration |
-| **[`:cexception`](../configuration/reference/cexception.md)** | CException configuration |
-| **[`:plugins`](../configuration/reference/plugins.md)** | Enable built-in plugins and configure custom plugin load paths |
-| **[`:tools`](../configuration/reference/tools.md)** | Define or override compiler, linker, and other tool invocations |
-
-<br/><br/>

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

@@ -1,210 +0,0 @@
-# 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!
-```