ceedling 1.0.0 → 1.1.0

data/docs/mkdocs/getting-started/command-line.md

@@ -0,0 +1,477 @@
+# Ceedling’s Command Line
+
+**Now what? How do I make it _Go_?**
+
+Every action in Ceedling is accomplished via the command line. We'll 
+cover project conventions and how to actually configure your project 
+in other sections.
+
+For now, let’s talk about the command line.
+
+To run tests, build your release artifact, etc., you will be using the
+trusty command line. Ceedling is transitioning away from being built
+around Rake. As such, right now, interacting with Ceedling at the 
+command line involves two different conventions:
+
+1. **Application Commands.** Application commands tell Ceedling what to
+   to do with your project. These create projects, load project files, 
+   begin builds, output version information, etc. These include rich 
+   help and operate similarly to popular command line tools like `git`.
+1. **Build & Plugin Tasks.** Build tasks actually execute test suites, 
+   run release builds, etc. These tasks are created from your project 
+   file. These are generated through Ceedling’s Rake-based code and 
+   conform to its conventions — simplistic help, no option flags, but 
+   bracketed arguments.
+
+In the case of running builds, both come into play at the command line.
+
+The two classes of command line arguments are clearly labelled in the
+summary of all commands provided by `ceedling help`.
+
+!!! note "Documentation convention"
+    The `*` used in the headings below is a stand-in for documentation 
+    purposes. It signifies either:
+
+    - Freeform text provided by the user at the command line (e.g. a filename
+      or matching pattern).
+    - A variant of the command itself (e.g. naming a subsection beneath `:paths`
+      in your project configuration.)
+
+## Quick command line example
+
+To exercise the Ceedling command line quickly, follow these steps after 
+[installing Ceedling](installation.md):
+
+1. Open a terminal and chnage directories to a location suitable for
+   an example project.
+1. Execute `ceedling example temp_sensor` in your terminal. The `example`
+   argument is an application command.
+1. Change directories into the new _temp_sensor/_ directory.
+1. Execute `ceedling test:all` in your terminal. The `test:all` is a
+   build task executed by the default `build` application command
+   (`build` is an optional keyword for this command line).
+1. Take a look at the build and test suite console output as well as 
+   the _project.yml_ file in the root of the example project.
+
+## Application commands
+
+Ceedling provides robust command line help for application commands.
+Execute `ceedling help` for a summary view of all application commands.
+Execute `ceedling help <command>` for detailed help.
+
+Because the built-in command line help is thorough, the following sections
+do not provide exhaustive details.
+
+### `ceedling [no arguments]`
+
+Runs the default build tasks. Unless set in the project file, Ceedling 
+uses a default task of `test:all`. To override this behavior, set your 
+own default tasks in the project file (see later section).
+
+_No parameters._
+
+---
+
+### `ceedling <tasks...>`
+
+Runs the named tasks (e.g. `ceedling test:all`). Various option flags exist 
+to control project configuration loading, verbosity levels, logging, test 
+task filters, etc.
+
+See [next section](#build-plugin-tasks) to understand the build & 
+plugin tasks this application command is able to execute. Parameters are 
+the same as those for `ceedling build`, below.
+
+---
+
+### `ceedling build [TASKS...]`
+
+`build` is an optional alias for the preceding (i.e. `ceedling test:all` 
+is equivalent to `ceedling build test:all`). The command actually executed
+is `ceedling build` under-the-hood. To maintain Ceedling’s historical
+command line convention, special rigging causes the `build` application
+command to be optional.
+
+`TASKS` are zero or more build operations created from your project 
+configuration. If no tasks are provided, built-in default tasks or your 
+`:project` ↳ `:default_tasks` will be executed.
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--project` | `-p` | Loads the filepath as your base project configuration | none |
+| `--mixin` | `-m` | Merges the configuration mixin by name, filepath, or inline YAML (`=` sigil). Repeatable. | `[]` |
+| `--verbosity` | `-v` | Sets logging level | `normal` |
+| `--log` | | Enable logging to `<build path>/logs/ceedling.log` | unset |
+| `--logfile` | `-l` | Enables logging to specified filepath (supersedes `--log`) | `''` (none) |
+| `--graceful-fail` | | Force exit code of 0 for unit test failures | unset |
+| `--test-case` | | Filter for individual unit test names | `''` (none) |
+| `--exclude-test-case` | | Prevent matched unit test names from running | `''` (none) |
+| `--ruby-replacement` | | Enables inline Ruby string expansion (`#{...}`) in project configuration | `false` (disabled) |
+
+---
+
+### `ceedling dumpconfig FILEPATH [SECTIONS...]`
+
+Process project configuration and write final result to a YAML file.
+
+`FILEPATH` is a required path to a destination YAML file. A nonexistent 
+path will be created.
+
+`SECTIONS` is an optional config “path” that extracts a portion of a 
+configuration. The top-level YAML container will be the path’s last 
+element. Example: `ceedling dumpconfig my/path/config.yml tools test_compiler`.
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--project` | `-p` | Loads the filepath as your base project configuration | none |
+| `--mixin` | `-m` | Merges the configuration mixin by name, filepath, or inline YAML (`=` sigil). Repeatable. | `[]` |
+| `--app` | | Runs Ceedling application and its config manipulations | `true` |
+| `--ruby-replacement` | | Enables inline Ruby string expansion (`#{...}`) in project configuration | `false` (disabled) |
+
+---
+
+### `ceedling check`
+
+Loads and processes your project configuration with full logging — the 
+same loading, merging, manipulation, and validation a real build would 
+perform — but executes no build tasks and writes no files. Useful for 
+confirming a configuration is well-formed.
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--project` | `-p` | Loads the filepath as your base project configuration | none |
+| `--mixin` | `-m` | Merges the configuration mixin by name, filepath, or inline YAML (`=` sigil). Repeatable. | `[]` |
+| `--ruby-replacement` | | Enables inline Ruby string expansion (`#{...}`) in project configuration | `false` (disabled) |
+
+---
+
+### `ceedling environment`
+
+Lists project related environment variables:
+
+* All environment variable names and string values added to your 
+  environment from within Ceedling and through the `:environment`
+  section of your configuration. This is especially helpful in 
+  verifying the evaluation of any string replacement expressions in
+  your `:environment` config entries. (Requires the `--ruby-replacement`
+  flag if any [inline Ruby string expansion][inline-ruby-string-expansion]
+  is present — see linked section for details.)
+* All existing Ceedling-related environment variables set before you
+  ran Ceedling from the command line.
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--project` | `-p` | Loads the filepath as your base project configuration | none |
+| `--mixin` | `-m` | Merges the configuration mixin by name, filepath, or inline YAML (`=` sigil). Repeatable. | `[]` |
+| `--ruby-replacement` | | Enables inline Ruby string expansion (`#{...}`) in project configuration | `false` (disabled) |
+
+---
+
+### `ceedling example NAME [DEST]`
+
+Extracts an example project from within Ceedling to your local 
+filesystem. The available examples are listed with `ceedling examples`.
+
+`NAME` is required to specify the example to extract and becomes the 
+containing directory for the extracted project. `DEST` is an optional 
+containing directory path (default is your working directory).
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--local` | | Install Ceedling plus supporting tools to vendor/ | `false` |
+| `--docs` | | Copy all documentation to docs/ subdirectory of project | `false` |
+
+---
+
+### `ceedling examples`
+
+Lists the available examples within Ceedling. To extract an example,
+use `ceedling example`.
+
+_No parameters._
+
+---
+
+### `ceedling help [COMMAND]`
+
+Displays summary help for all application commands and detailed help 
+for each command. `ceedling help` also loads your project 
+configuration (if available) and lists all build tasks from it. 
+`COMMAND` is optional and produces detailed help for a specific 
+application command.
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--project` | `-p` | Loads the filepath as your base project configuration | none |
+| `--mixin` | `-m` | Merges the configuration mixin by name, filepath, or inline YAML (`=` sigil). Repeatable. | `[]` |
+| `--ruby-replacement` | | Enables inline Ruby string expansion (`#{...}`) in project configuration | `false` (disabled) |
+
+---
+
+### `ceedling new [DEST]`
+
+Creates a new project structure. `DEST` is an optional root path for the 
+new project (default is your working directory).
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--local` | | Install Ceedling plus supporting tools to vendor/ | `false` |
+| `--docs` | | Copy all documentation to docs/ subdirectory of project | `false` |
+| `--configs` | | Install starter project file in project root | `true` |
+| `--force` | | Ignore any existing project and recreate destination | `false` |
+| `--gitsupport` | | Create .gitignore / .gitkeep files for convenience | `false` |
+
+---
+
+### `ceedling upgrade PATH`
+
+Upgrade vendored installation of Ceedling for an existing project 
+along with any locally installed documentation bundles. `PATH` is 
+required and should be the root of the project to upgrade.
+
+| Flag | Alias | Description | Default |
+|---|---|---|---|
+| `--project` | | Project filename used in the project-existence check | `project.yml` |
+
+---
+
+### `ceedling docs [DEST]`
+
+Exports the Ceedling documentation bundle to the filesystem. `DEST` is 
+an optional destination path (default is your working directory).
+
+_No parameters._
+
+---
+
+### `ceedling version`
+
+Displays version information for Ceedling and its components. Version output for Ceedling includes the Git Commit short SHA in Ceedling’s build identifier and Ceedling’s path of origin.
+
+```
+🌱 Welcome to Ceedling!
+
+  Ceedling => #.#.#-<Short SHA>
+  ----------------------
+  <Ceedling install path>
+
+  Build Frameworks
+  ----------------------
+       CMock => #.#.#
+       Unity => #.#.#
+  CException => #.#.#
+```
+
+If the short SHA information is unavailable such as in local development, the SHA is omitted. The source for this string is generated and captured in the Gem at the time of Ceedling’s automated build in CI.
+
+_No parameters._
+
+---
+
+## Build & plugin tasks
+
+Build task are loaded from your project configuration. Unlike 
+application commands that are fixed, build tasks vary depending on your
+project configuration and the files within your project structure.
+
+Ultimately, build & plugin tasks are executed by the `build` application
+command (but the `build` keyword can be omitted — see above).
+
+### `ceedling paths:*`
+
+Variants:
+
+* `ceedling files:header`
+* `ceedling files:source`
+* `ceedling files:support`
+* `ceedling files:test`
+
+List all paths collected from `:paths` entries in your project configuration
+where `*` is the name of any section contained in `:paths`.
+
+This task is helpful in verifying the expansion of path wildcards / globs
+specified in the `:paths` section of your configuration.
+
+---
+
+### `ceedling files:*`
+
+Variants:
+
+* `ceedling files:header`
+* `ceedling files:source`
+* `ceedling files:support`
+* `ceedling files:test`
+* `ceedling files:assembly`
+
+List all files and file counts collected from the relevant search
+paths specified by the `:paths` entries of your project configuration.
+
+The `files:assembly` task will only be available if assembly support is
+enabled in the `:release_build` or `:test_build` sections of your 
+configuration file.
+
+---
+
+### `ceedling test:all`
+
+Run all unit tests.
+
+---
+
+### `ceedling test:build_only`
+
+Build the entire test suite but do not execute it. This is a simple 
+validation of code and configuration via your toolchain.
+
+---
+
+### `ceedling test:*`
+
+Execute the named test file or the named source file that has an
+accompanying test. No path. Examples: `ceedling test:foo`, `ceedling 
+test:foo.c` or `ceedling test:test_foo.c`
+
+---
+
+### `ceedling test:* --test-case=<test_case_name>`
+
+Execute individual test cases which match `test_case_name`.
+
+For instance, if you have a test file _test_gpio.c_ containing the following 
+test cases (test cases are simply `void test_name(void)`):
+
+- `test_gpio_start`
+- `test_gpio_configure_proper`
+- `test_gpio_configure_fail_pin_not_allowed`
+
+… and you want to run only `configure` tests, you can call:
+
+  `ceedling test:gpio --test-case=configure`
+
+**Test case matching notes**
+
+* Test case matching is on sub-strings. `--test_case=configure` matches on
+  the test cases including the word _configure_, naturally. 
+  `--test-case=gpio` would match all three test cases.
+
+---
+
+### `ceedling test:* --exclude_test_case=<test_case_name>`
+
+Execute test cases which do not match `test_case_name`.
+
+For instance, if you have file _test_gpio.c_ with 3 tests:
+
+- `test_gpio_start`
+- `test_gpio_configure_proper`
+- `test_gpio_configure_fail_pin_not_allowed`
+
+… and you want to run only `start` tests, you can call:
+
+  `ceedling test:gpio --exclude_test_case=configure`
+
+**Test case exclusion matching notes**
+
+* Exclude matching follows the same sub-string logic as discussed in the
+  preceding section.
+
+---
+
+### `ceedling test:pattern[*]`
+
+Execute any tests whose name and/or path match the regular expression
+pattern between the brackets (case sensitive).
+
+Example: `ceedling "test:pattern[(I|i)nit]"` will execute all tests named for 
+initialization testing.
+
+!!! note
+    Quotes are likely necessary around the regex characters or 
+    entire task to distinguish characters from shell command line operators.
+
+---
+
+### `ceedling test:path[*]`
+
+Execute any tests whose path contains the given string (case
+sensitive). Example: `ceedling test:path[foo/bar]` will execute all tests
+whose path contains foo/bar. _Notes:_
+
+1. Both directory separator characters `/` and `\` are valid.
+1. Quotes may be necessary around the task to distinguish the parameter’s
+   characters from shell command line operators.
+
+---
+
+### `ceedling release`
+
+Build all source into a release artifact (if the release build option
+is configured).
+
+---
+
+### `ceedling release:compile:*`
+
+Sometimes you just need to compile a single file dagnabit. Example:
+`ceedling release:compile:foo.c`
+
+---
+
+### `ceedling release:assemble:*`
+
+Sometimes you just need to assemble a single file doggonit. Example:
+`ceedling release:assemble:foo.s`
+
+---
+
+### `ceedling summary`
+
+If plugins are enabled, this task will execute the summary method of
+any plugins supporting it. This task is intended to provide a quick
+roundup of build artifact metrics without re-running any part of the
+build.
+
+---
+
+### `ceedling clean`
+
+Deletes all toolchain binary artifacts (object files, executables),
+test results, and any temporary files. Clean produces no output at the
+command line unless verbosity has been set to an appreciable level.
+
+---
+
+### `ceedling clobber`
+
+Extends clean task’s behavior to also remove generated files: test
+runners, mocks, preprocessor output. Clobber produces no output at the
+command line unless verbosity has been set to an appreciable level.
+
+---
+
+## Command line extra credit
+
+### Combining tasks
+
+Multiple build tasks can be executed at the command line.
+
+For example, `ceedling clobber test:all release` will remove all generated
+files; build and run all tests; and then build all source — in that order. If
+any task fails along the way, execution halts before the next task.
+
+Task order is executed as provided and can be important! Running `clobber` after
+a `test:` or `release:` task will not accomplish much.
+
+### Builds & Revision Control
+
+The `clobber` task removes certain build directories in the course of 
+deleting generated files.
+
+In general, it’s best not to add to source control any Ceedling generated 
+directories below the root of your top-level project build directory. That is, 
+leave anything Ceedling & its accompanying tools generate out of source control.
+
+[inline-ruby-string-expansion]: ../configuration/project-file.md#inline-ruby-string-expansion
+
+<br/><br/>

data/docs/mkdocs/getting-started/example-projects/cipher-quest.md

@@ -0,0 +1,65 @@
+# `cipher_quest`
+
+An imagined intelligence agent’s command line string manipulation toolkit.
+This project can be run both as a test suite and as a release build.
+
+See the [project README](../../snapshot/examples/cipher_quest/README.md) 
+for full details. The README is linked here for convenience but is also 
+exported with the example project.
+
+## Exporting
+
+```shell
+ceedling example cipher_quest [destination]
+```
+
+After exporting, run `ceedling test:all` from the project root to execute the
+full test suite, or `ceedling release` to produce a release binary. Note that
+the release build requires configuration from you to provide needed symbols.
+
+## About
+
+`cipher_quest` simulates a command line toolkit for encoding and decoding
+secret messages. Unlike the other example projects, it supports both a test
+build and a release build, demonstrating Ceedling’s dual build capabilities.
+
+## Release builds
+
+The release build requires symbol definitions not active in the default project
+configuration. That is, without specifying at least one symbol corresponding to
+a feature set, the release build will fail. The test build is configured such
+that each set of tests enables the symbol needed by the source under test.
+
+Symbols needed by the release build can be provided by:
+
+1. Editing the [`:defines` section](../../configuration/reference/defines.md)
+   of the example project file.
+2. Making use of [Mixins](../../configuration/mixins.md)
+   to selectively enable the needed symbols. The example project includes 
+   mixin files, and the project README provides examples of enacting all 
+   availble Mixin features.
+
+---
+
+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)
+```
+
+<br/><br/>

data/docs/mkdocs/getting-started/example-projects/index.md

@@ -0,0 +1,49 @@
+# Example projects
+
+Ceedling comes with entire example projects you can export. These include
+reasonable approximations of real world code for learning and reference.
+
+## How to export projects
+
+1. Execute `ceedling examples` in your terminal to list available example 
+   projects.
+1. Execute `ceedling example <project> [destination]` to extract the 
+   named example project to an optional destination directory (defaults
+   to current working directory).
+
+## Available projects
+
+Once you’ve exported a project you can inspect the _project.yml_ file and 
+source & test code. Run `ceedling help` from the root of an example project
+to see what you can do, or just go nuts with `ceedling test:all`.
+
+<div class="grid cards" markdown>
+
+-   :material-memory: **[`temp_sensor`](temp-sensor.md)**
+
+    ---
+
+    An imagined temperature sensor project containing assertions, 
+    mocks, and code techniques representative of testing in embedded 
+    development. Test suite only.
+
+-   :material-forest-outline: **[`wondrous_forest`](wondrous-forest.md)**
+
+    ---
+
+    An imagined forest monitoring system project illustrating the
+    use of [Partials](../../testing-guide/partials/index.md) in a test suite.
+    Test suite only.
+
+-   :material-incognito: **[`cipher_quest`](cipher-quest.md)**
+
+    ---
+
+    An imagined spy’s command line string manipulation toolkit. This
+    project can be run both as a test suite and as a release build. It
+    demonstrates build options around conditional compilation (`ifdef`) 
+    and defining symbols with Ceedling including with Mixins.
+
+</div>
+
+<br/><br/>

data/docs/mkdocs/getting-started/example-projects/temp-sensor.md

@@ -0,0 +1,60 @@
+# `temp_sensor`
+
+An imagined temperature sensor peripheral with ADC, timer, and USART
+subsystems. The firmware is organized in classic embedded C layers using
+a design patterns and hardware stand-ins to enable testing. Test suite only.
+
+See the [project README](../../snapshot/examples/temp_sensor/README.md)
+for full details. The README is linked here for convenience but is also
+exported with the example project.
+
+## Exporting
+
+```shell
+ceedling example temp_sensor [destination]
+```
+
+After exporting, run `ceedling test:all` from the project root to execute the
+full test suite.
+
+## About
+
+`temp_sensor` demonstrates a range of Ceedling test-build features using a
+layered architecture typical of embedded development with the benefit of a
+design pattern to enable testing. Mocks generated by CMock isolate each component 
+among the MCH design pattern implementation for unit testing.
+
+The project also illustrates a pure-C approach to resolving hardware peripheral 
+accesses for testing using the same symbol names as provided by a vendor.
+
+Example integration tests demonstrate exercising cross-module and integrated
+behavior.
+
+### Platform standin technique
+This project demonstrates the practice of creating custom structs as standins for
+real hardware access by coopting the macros, symbol names, and operations provided 
+by the platform vendor.
+
+### MCH design pattern
+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
+
+[mocking-the-embedded-world]: https://static1.squarespace.com/static/50fdbec3e4b0dc8c8e313271/t/5d962ba1e9079c36018e99fa/1570122657926/ESC+2007+Mocking+the+Embedded+World.pdf
+
+## Optional mixins
+
+The project ships two mixin files that activate optional features:
+
+- **`add_gcov`** — enables gcov coverage collection and reporting (requires
+  `gcov` and `gcovr`). Run with `ceedling gcov:all --mixin=mixin/add_gcov.yml`.
+- **`add_unity_helper`** — activates a custom Unity assertion for
+  `EXAMPLE_STRUCT_T`, enabling more detailed failure messages for struct
+  comparisons. Run with `ceedling test:all --mixin=mixin/add_unity_helper.yml`.
+
+See the [Mixins](../../configuration/mixins.md)
+documentation for more on how to use and write mixin files.
+
+<br/><br/>

data/docs/mkdocs/getting-started/example-projects/wondrous-forest.md

@@ -0,0 +1,45 @@
+# `wondrous_forest`
+
+An imagined forest environmental monitoring station that reads temperature,
+humidity, light, and soil moisture — raising alerts when conditions exceed
+thresholds. Test suite only.
+
+See the [project README](../../snapshot/examples/wondrous_forest/README.md)
+for full details. The README is linked here for convenience but is also
+exported with the example project.
+
+## Exporting
+
+```shell
+ceedling example wondrous_forest [destination]
+```
+
+After exporting, run `ceedling test:all` from the project root to execute the
+full test suite.
+
+## About
+
+`wondrous_forest` demonstrates Ceedling's [Partials](../../testing-guide/partials/index.md)
+feature — the ability to test `static`, `inline`, and `static inline` C
+functions and `static` variables that are otherwise inaccessible under normal
+C linkage rules. Every major Partials pattern appears somewhere in the project,
+alongside traditional mock-based tests.
+
+## Partials patterns
+
+Each sensor module uses a different Partials pattern, making the project a
+comprehensive reference:
+
+| 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             |
+
+<br/><br/>