ceedling 1.1.9 → 1.2.0

data/docs/mkdocs/plugins/report-tests-teamcity-stdout.md

@@ -1,96 +0,0 @@
-# TeamCity Test Suite Console Report
-
-Prints to the console ($stdout) test suite build events and results in a format understood by the CI product TeamCity.
-
-## Plugin Overview
-
-This plugin is intended to be used within [TeamCity] Continuous Integration
-(CI) builds. It processes Ceedling test suites and executable output into
-TeamCity [service messages][service-messages]. Service messages are a specially
-formatted type of log output that a TeamCity build server picks out of build
-output to collect progress and metrics of various sorts.
-
-Typically, this plugin is used only in CI builds. Its output is unhelpful in
-development builds locally. See the [Configuration](#configuration) section for
-options on enabling the build in CI but disabling it locally.
-
-[TeamCity]: https://www.jetbrains.com/teamcity/
-[service-messages]:
-https://www.jetbrains.com/help/teamcity/service-messages.html
-
-## Setup
-
-Enable the plugin in your Ceedling project file by adding 
-`report_tests_teamcity_stdout`.
-
-``` YAML
-:plugins:
-  :enabled:
-    - report_tests_teamcity_stdout
-```
-
-## Configuration
-
-All the `report_tests_*_stdout` plugins may be enabled in various combinations.
-But, some combinations may not make a great deal of sense. The TeamCity
-plugin “plays nice” with all the others but is generally most appropriate 
-running in a CI build on a TeamCity server. Its output will clutter and obscure
-console logging at a local development environment command line.
-
-You may enable the TeamCity plugin (above) but disable its operation using the
-following.
-
-```YAML
-:teamcity:
-  :build: FALSE
-```
-
-This may seem silly, right? Why enable the plugin and then disable it,
-cancelling it out? The answer has to do with _where_ you use the second YAML
-blurb configuration setting.
-
-Ceedling provides Mixins for applying configurations settings on top of your
-base project configuraiton file. 
-See the [Mixins documentation][ceedling-mixins] for full details.
-
-[ceedling-mixins]: ../configuration/mixins.md#base-configuration-mixins-entries
-
-As an example, you might enable the plugin in the main project file that is
-committed to your repository while disabling the plugin in your local user
-project file that is ignored by your repository. In this way, the plugin would
-run on a TeamCity build server but not in your local development environment.
-
-## Example Output
-
-TeamCity's convention for identifying tests uses the naming convention of the
-underlying Java language in which TeamCity is written,
-`package_or_namespace.ClassName.TestName`.
-
-This plugin maps Ceedling conventions to TeamCity test service messages as
-`context.TestFilepath.TestCaseName`.
-
-* `context` Your build's context defaults to `test`. Certain other test build 
-  plugins (e.g. GCov) provide a different context (`gcov`) for test builds, 
-  generally named after themselves.
-* `TestFilepath` This identifier is the relative filepath of the relevant test
-  file without a file extension (e.g. no `.c`).
-* `TestCaseName` This identifier is a test case function name within a Ceedling test file.
-
-```sh
- > ceedling test:UsartModel
-```
-
-```
-##teamcity[testSuiteStarted name='TestUsartModel' flowId='15']
-##teamcity[testStarted name='test.test/TestUsartModel.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting' flowId='15']
-##teamcity[testFinished name='test.test/TestUsartModel.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting' duration='81' flowId='15']
-##teamcity[testStarted name='test.test/TestUsartModel.testShouldReturnErrorMessageUponInvalidTemperatureValue' flowId='15']
-##teamcity[testFinished name='test.test/TestUsartModel.testShouldReturnErrorMessageUponInvalidTemperatureValue' duration='81' flowId='15']
-##teamcity[testStarted name='test.test/TestUsartModel.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately' flowId='15']
-##teamcity[testFailed name='test.test/TestUsartModel.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately' message='Function TemperatureFilter_GetTemperatureInCelcius() called more times than expected.' details='File: test/TestUsartModel.c Line: 25' flowId='15']
-##teamcity[testFinished name='test.test/TestUsartModel.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately' duration='81' flowId='15']
-##teamcity[testIgnored name='test.test/TestUsartModel.testShouldReturnWakeupMessage' flowId='15']
-##teamcity[testSuiteFinished name='TestUsartModel' flowId='15']
-```
-
-<br/><br/>

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/>