ceedling 1.1.10 → 1.2.1

data/docs/mkdocs/plugins/valgrind.md

@@ -1,198 +0,0 @@
-# Valgrind
-
-Adds Ceedling tasks to run test executables under [Valgrind] memory error
-detection to help find memory leaks, invalid memory accesses, and
-use-after-free bugs in your C code.
-
-!!! note
-    The Valgrind plugin creates a duplicate test build with `valgrind:` 
-    command line plugin tasks. [This is intentional and needed](index.md#understanding-plugin-build-duplication).
-
----
-
-## Plugin overview
-
-!!! note "Linux only"
-    Valgrind runs on Linux and other Unix-like systems. It is not available
-    on Windows or macOS (ARM).
-
-The Valgrind plugin integrates [Valgrind] dynamic analysis into Ceedling,
-building and then running test executables under Valgrind’s Memcheck tool.
-
-The plugin provides two invocation modes mirroring standard `test:` tasks.
-
-- **Whole test suite**: By running `ceedling valgrind:all`, all test
-  executables are built and then each is run under Valgrind. A separate log
-  file is produced for each test executable in `build/artifacts/valgrind/`.
-- **Single test file**: By running `ceedling valgrind:<filename>`, a single
-  test executable is built and run under Valgrind, producing one log file.
-
-The plugin triggers standard `test` task builds but hands each test fixture
-executable off to Valgrind along with configurable arguments.
-
-By default the build runs all test binaries to completion and is marked as
-failed if any Valgrind memory errors are found. The optional `:fail_build:`
-setting can be set to `false` to log errors without failing the build.
-
-## Installation & set up
-
-### Installation
-
-You have at least 3 options for getting the `valgrind` tool working on your
-system, including one readymade option.
-
-#### Linux package manager
-
-Install Valgrind from your Linux distribution’s package manager:
-
-```shell
-sudo apt-get install valgrind   # Debian / Ubuntu
-sudo dnf install valgrind       # Fedora / RHEL
-```
-
-#### Build from source
-
-Or build from source from [valgrind.org/downloads/](https://valgrind.org/downloads/).
-
-#### _MadScienceLab_ Docker images
-
-Fully packaged [_MadScienceLab_ Docker images][docker-hub] containing Ruby, 
-Ceedling, the GCC toolchain, and more are available. The `-plugins` variants 
-of the images come with all of Ceedling’s plugin tools preinstalled.
-
-[docker-hub]: https://hub.docker.com/repository/docker/throwtheswitch/
-
-### Enable the plugin
-
-Enable the plugin by adding `valgrind` to the enabled plugins list in your
-project configuration:
-
-```yaml
-:plugins:
-  :enabled:
-    - valgrind
-```
-
-## Configuration
-
-The plugin ships with sensible defaults that enable full leak checking. By
-default the build runs all test binaries to completion and is marked as failed
-if any memory errors are found. Set `:fail_build: false` to log errors without
-failing the build.
-
-You can change the Valgrind configuration in your project configuration 
-under an optional `:valgrind` section.
-
-### Default configuration
-
-In the default configuration, the Valgrind plugin will run the entire test 
-suite, collecting Valgrind reports for each test fixture executable.
-
-By default, the plugin runs with these command line arguments for `valgrind`:
-
-- `--leak-check=full`
-- `--show-leak-kinds=all`
-- `--track-origins=yes`
-- `--errors-for-leak-kinds=all`
-
-### `:arguments:`
-
-The list of flags passed to Valgrind for every test binary. To override the
-defaults, redefine the argument list in your project configuration:
-
-```yaml
-:valgrind:
-  :arguments:
-    # A subset of the default arguments
-    - "--leak-check=full"
-    - "--show-leak-kinds=all"
-```
-
-### `:fail_build:`
-
-When `true` (the default), any memory errors are logged immediately after 
-running a test executable. After all test binaries complete execution, if 
-any memory errors were found across the run, the build is marked as failed 
-with a total count of memory errors and test files processed.
-
-When `false`, memory errors are still logged per test binary but the build is
-not marked as failed.
-
-```yaml
-:valgrind:
-  :fail_build: false
-```
-
-!!! note "Detection uses log parsing, not Valgrind’s exit code"
-    Valgrind’s `--error-exitcode` flag is not used because its exit code would
-    overlap with Unity’s own exit code, which equals the number of failing test
-    cases. Instead, the plugin parses the `ERROR SUMMARY: N errors` line written
-    to the Valgrind log file.
-
-## Usage
-
-The Valgrind plugin follows the conventions of `test:` tasks.
-
-### Run Valgrind for all tests
-
-Build all test executables and run each under Valgrind:
-
-```shell
-$ ceedling valgrind:all
-```
-
-### Run Valgrind for a single test file
-
-Build and run Valgrind for one test file (pass the filename, no path):
-
-```shell
-$ ceedling valgrind:test_my_module.c
-```
-
-You can also pass just the source filename; Ceedling will locate the
-corresponding test file automatically:
-
-```shell
-$ ceedling valgrind:my_module.c
-```
-
-## Artifacts
-
-Each test executable produces a Valgrind log file at:
-
-```
-build/artifacts/valgrind/<test_name>.log
-```
-
-For example, running `ceedling valgrind:test_my_module.c` produces:
-
-```
-build/artifacts/valgrind/test_my_module.log
-```
-
-These log files contain the full Valgrind Memcheck output, including any
-detected memory errors, leak summaries, and (with `--track-origins=yes`)
-the origin of uninitialized values.
-
-The log files are included in `ceedling clean` targets.
-
-## Interpreting results
-
-To review the log for a specific test:
-
-```shell
-cat build/artifacts/valgrind/test_my_module.log
-```
-
-Common Valgrind findings include:
-
-| Finding | Description |
-|---------|-------------|
-| `definitely lost` | Memory was allocated but never freed — a confirmed leak |
-| `indirectly lost` | Memory reachable only through another leaked block |
-| `Invalid read/write` | Access outside allocated memory bounds |
-| `Use of uninitialised value` | Reading memory before it was written |
-
-See [Valgrind] documentation for more details.
-
-[Valgrind]: https://valgrind.org

data/docs/mkdocs/project/release-history.md

@@ -1,61 +0,0 @@
-# Release History
-
-## Versioned Release Artifacts
-Ceedling releases are available as:
-
-* [Repository build artifacts](https://github.com/ThrowTheSwitch/Ceedling/releases) (downloadable 
-  Ruby .gem files).
-* [Ruby gems](https://rubygems.org/gems/ceedling) for installation from the RubyGems registry by 
-  the `gem` command line tool.
-* [Docker images](https://hub.docker.com/r/throwtheswitch/madsciencelab) with the `ceedling` tool 
-  ready to run from the command line.
-
-Ceedling is known to be compatible with Ruby 3.0 – 3.4. It is ready for use with Ruby 3.5 but has 
-had little real world use with Ruby 3.5.
-
-## History
-
-Ceedling’s release history is documented in four files that live in the
-repository and follow [keepachangelog.com](https://keepachangelog.com/en/1.0.0/)
-conventions. These documents span the cumulative project history and are
-maintained standalone rather than versioned with this documentation.
-
-<div class="grid cards" markdown>
-
--   :material-bullhorn-outline: **[Release Notes][release-notes]**
-
-    ---
-
-    Detailed [release notes][release-notes] for announcements, education, and acknowledgements. 
-    This is the primary reference for quickly understanding what changed between versions.
-
--   :material-history: **[Changelog][changelog]**
-
-    ---
-
-    A detailed, chronological log of [all changes][changelog] — additions, fixes, changes, and
-    anything removed.
-
--   :material-alert-octagon-outline: **[Breaking Changes][breaking-changes]**
-
-    ---
-
-    A focused list of [breaking changes][breaking-changes] across releases. Consult this document
-    when upgrading to understand what in your project configuration or test
-    code may need to be updated.
-
--   :material-bug-outline: **[Known Issues][known-issues]**
-
-    ---
-
-    A high-level list of [presently known problems][known-issues] and limitations for each
-    release.
-
-</div>
-
-[release-notes]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/ReleaseNotes.md
-[breaking-changes]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/BreakingChanges.md
-[changelog]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/Changelog.md
-[known-issues]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/KnownIssues.md
-
-<br/><br/>

data/docs/mkdocs/project/upgrade.md

@@ -1,85 +0,0 @@
-# Upgrading Ceedling
-
-You'd like to stay in sync with the latest Ceedling... and who wouldn't? Depending on 
-how you've made use of Ceedling, that may vary slightly. No matter what, though, our first
-step is to update Ceedling itself.
-
-## Step 1: Update Ceedling Itself
-
-```
-gem update ceedling
-```
-
-That should do it... unless you don't have a valid connection to the internet. In that case,
-you might have to download the gem from rubygems.org and then install it manually:
-
-```
-gem update ceedling --local=ceedling-filename.zip
-```
-
-## Step 2: Update Projects Using Ceedling
-
-When you set up your project(s), it was either configured to use the gem directly, or it was
-configured to install itself locally (often into a vendor directory).
-
-For projects that are of the first type, congratulations, you're finished. The project will
-automatically use the new ceedling. There MAY be things that need to be tweaked if features have
-moved significantly. (And we apologize if that's your situation... as we get to version 1, we're
-going to have a stronger focus on backwards compatibility). If your project isn't working perfectly, 
-skip down to Step 3.
-
-If the project was installed to have a copy of ceedling locally, you have a choice. You may 
-choose to continue to run THIS project on the old version of Ceedling. Often this is the
-preferred method for legacy projects which only get occasional focus. Why go through the effort 
-of updating for new tools if it's serving its purpose and you're unlikely to actually use the new
-features?
-
-The other choice, of course, is to update it. To do so, we open a command prompt and address ceedling 
-from *outside* the project. For example, let's say we have the following structure:
-
-```
-projects/
-└── myproject/
-    ├── project.yml
-    ├── src/
-    ├── tgt/
-    └── vendor/
-```
-
-In this case, we'd want to be in the `projects` directory. At that point, we can ask Ceedling to
-update our project.
-
-```
-ceedling upgrade myproject
-```
-
-Ceedling will automatically look for your project yaml file and do its best to determine what needs
-to be updated. If installed locally, this will mean copying the latest copy of Unity, CMock, and
-Ceedling. It will also involve copying documentation, if you had that installed.
-
-## Step 3: Solving Problems
-
-We wish every project would update seamlessly... unfortunately there is a lot of customization that
-goes into each project, and Ceedling often isn't aware of all of these. To make matter worse, Ceedling
-has been in pre-release for awhile, meaning it occasionally has significant changes that may break
-current installations. We've tried to capture the common ones here:
-
-### rakefile
-
-Ceedling is built in a utility called Rake. In the past, rake was the method that the user actually
-interacted with Ceedling. That's no longer the case. Using a modern version of Ceedling means that
-you issue commands like `ceedling test:all` instead of `rake test:all`. If you have a continuous 
-integration server or other calling service, it may need to be updated to comply.
-
-Similarly, older versions of Ceedling actually placed a rakefile in the project directory, allowing 
-the project to customize its own flow. For the most part this went unused and better ways were later
-introduced. At this point, the `rakefile` is more trouble than its worth and often should just be 
-removed. 
-
-### plugins
-
-If you have custom plugins installed to your project, the plugin architecture has gone through some 
-revisions and it may or may not be compatible at this time. Again, this is a problem which should
-not exist soon.
-
-<br/><br/>

data/docs/mkdocs/reference/build-directives.md

@@ -1,37 +0,0 @@
-# Test Build Directive Macros Reference
-
-For detailed usage guidance, purpose explanations, and examples for these
-macros, see [Test Build Directive Macros](../testing-guide/build-directives.md).
-
-Both macros are defined in `unity.h` and evaluate to empty strings at compile
-time — they serve only as text markers for Ceedling's scanner. `#include "unity.h"`
-must appear above their use in a test file.
-
-!!! warning "Incompatible with conditional preprocessor blocks"
-    `TEST_SOURCE_FILE()` and `TEST_INCLUDE_PATH()` cannot be enclosed in
-    `#ifdef` or other conditional compilation preprocessor statements. See
-    [preprocessing gotchas](../testing-guide/conventions.md#preprocessing-gotchas)
-    for details.
-
-## `TEST_SOURCE_FILE("filepath")`
-
-Inject a specific source file into a test executable's build. Use this when
-a source file has no corresponding header file that Ceedling can discover by
-convention, or when you need to explicitly include an assembly file (`.s`) in
-a test build that has assembly support enabled.
-
-- Argument: a filepath string using forward slashes
-- The file must exist within Ceedling's source file collection
-- Multiple uses per test file are allowed, one per line
-
-## `TEST_INCLUDE_PATH("path")`
-
-Add a header search path to an individual test executable's compiler
-invocation. This supplements — it does not replace — the `:paths` ↳ `:include`
-entries from your project file.
-
-- Argument: a path string using forward slashes
-- Paths are relative to the working directory from which `ceedling` is executed
-- Multiple uses per test file are allowed, one per line
-
-<br/><br/>

data/docs/mkdocs/reference/command-line.md

@@ -1,323 +0,0 @@
-# Command Line Reference
-
-See [_Getting started: The command line_](../getting-started/command-line.md)
-for:
-
-- A conceptual overview of how application commands and build & plugin 
-  tasks work together.
-- Quick-start command line examples.
-- In-depth details for each of the reference entries below (each heading
-  links back to richer documentation).
-
-!!! note "Documentation convention"
-    The `*` used in this reference is a stand-in for:
-
-    * One of several available options
-    * A matching string (e.g. test filename)
-    * A regex
-
-## Application commands
-
-!!! tip "Detailed command line help at the, well, command line"
-    Ceedling provides robust 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 
-    reference includes brief entries.
-
----
-
-### [`ceedling [no arguments]`](../getting-started/command-line.md#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). 
-
----
-
-### [`ceedling <tasks...>`](../getting-started/command-line.md#ceedling-tasks)
-
-Runs the named build tasks (i.e. `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. Run `ceedling help build` 
-to understand all the command line flags that work with build & plugin tasks.
-
----
-
-### [`ceedling build <tasks...>`](../getting-started/command-line.md#ceedling-build-tasks)
-
-`ceedling build` is a verbose alias for the preceding. `build` is optional 
-(i.e. `ceedling test:all` is equivalent to `ceedling build test:all`).
-
----
-
-### [`ceedling check`](../getting-started/command-line.md#ceedling-check)
-
-Process project configuration for validity and to check for any warnings
-or automated overrides. No builds occur. Various option flags exist to 
-control project configuration loading and configuration manipulation.
-
----
-
-### [`ceedling dumpconfig`](../getting-started/command-line.md#ceedling-dumpconfig-filepath-sections)
-
-Process project configuration and write final result to a YAML file. 
-Various option flags exist to control project configuration loading,
-configuration manipulation, and configuration sub-section extraction.
-
----
-
-### [`ceedling environment`](../getting-started/command-line.md#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.
-* All existing Ceedling-related environment variables set before you
-  ran Ceedling from the command line.
-
----
-
-### [`ceedling example`](../getting-started/command-line.md#ceedling-example-name-dest)
-
-Extracts an example project from within Ceedling to your local 
-filesystem. The available examples are listed with 
-`ceedling examples`. Various option flags control whether the example
-contains vendored Ceedling and/or a documentation bundle.
-
----
-
-### [`ceedling examples`](../getting-started/command-line.md#ceedling-examples)
-
-Lists the available examples within Ceedling. To extract an example,
-use `ceedling example`.
-
----
-
-### [`ceedling help`](../getting-started/command-line.md#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. 
-  Various option flags control what project configuration is loaded.
-
----
-
-### [`ceedling new`](../getting-started/command-line.md#ceedling-new-dest)
-
-  Creates a new project structure. Various option flags control whether 
-  the new project contains vendored Ceedling, a documentation bundle,
-  and/or a starter project configuration file.
-
----
-
-### [`ceedling upgrade`](../getting-started/command-line.md#ceedling-upgrade-path)
-
-  Upgrade vendored installation of Ceedling for an existing project 
-  along with any locally installed documentation bundles.
-
----
-
-### [`ceedling version`](../getting-started/command-line.md#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 Ruby Gem at the time of Ceedling’s 
-automated build in CI.
-
-## 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](#ceedling-build-tasks)
-(but the `build` keyword can be omitted — see above).
-
-!!! warning "Quotes in shell command line parsing"
-    Quotes may be necessary around any tasks using bracket notation or that
-    can make use of wildcards or regexes. Your shell will likely need quotes
-    to distinguish the parameter’s characters from shell command line
-    operators.
-
----
-
-### [`ceedling paths:*`](../getting-started/command-line.md#ceedling-paths)
-
-* `ceedling paths:header`
-* `ceedling paths:source`
-* `ceedling paths:support`
-* `ceedling paths:test`
-
-List all paths collected from `paths` entries in your YAML config
-file 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 config file.
-
----
-
-### [`ceedling files:*`](../getting-started/command-line.md#ceedling-files)
-
-* `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 YAML config file.
-
-The `files:assembly` task will only be available if assembly support 
-is enabled in the [`:release_build`](../configuration/reference/release-build.md) 
-or [`:test_build`](../configuration/reference/test-build.md)
-sections of your configuration file.
-
----
-
-### [`ceedling test:all`](../getting-started/command-line.md#ceedling-testall)
-
-Run all unit tests.
-
----
-
-### [`ceedling test:build_only`](../getting-started/command-line.md#ceedling-testbuild_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:*`](../getting-started/command-line.md#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>`](../getting-started/command-line.md#ceedling-test-test-casetest_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`
-
-!!! note
-    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>`](../getting-started/command-line.md#ceedling-test-exclude_test_casetest_case_name)
-Execute test cases which do not match `test_case_name`.
-
-For instance, if you have file test_gpio.c with defined 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`
-
-!!! note
-    Exclude matching follows the same sub-string logic as discussed in the
-    preceding section.
-
----
-
-### [`ceedling test:pattern[*]`](../getting-started/command-line.md#ceedling-testpattern)
-
-Execute any tests whose name and/or path match the regular expression
-pattern (case sensitive). Example: `ceedling "test:pattern[(I|i)nit]"` 
-will execute all tests named for initialization testing.
-
----
-
-### [`ceedling test:path[*]`](../getting-started/command-line.md#ceedling-testpath)
-
-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.
-
-Both directory separator characters `/` and `\` are valid.
-
----
-
-### [`ceedling release`](../getting-started/command-line.md#ceedling-release)
-
-Build all source into a release artifact (if the release build option
-is configured).
-
----
-
-### [`ceedling release:compile:*`](../getting-started/command-line.md#ceedling-releasecompile)
-
-Sometimes you just need to compile a single file dagnabit.
-
-Example: `ceedling release:compile:foo.c`
-
----
-
-### [`ceedling release:assemble:*`](../getting-started/command-line.md#ceedling-releaseassemble)
-
-Sometimes you just need to assemble a single file doggonit. Example:
-`ceedling release:assemble:foo.s`
-
----
-
-### [`ceedling summary`](../getting-started/command-line.md#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`](../getting-started/command-line.md#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`](../getting-started/command-line.md#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.
-
-<br/><br/>