ceedling 1.1.10 → 1.2.1

data/docs/mkdocs/plugins/gcov/setup.md

@@ -1,232 +0,0 @@
-# Set up & Configuration
-
-## Toolchain dependencies
-
-### GNU Compiler Collection
-
-This plugin relies on the GNU compiler collection. Coverage instrumentation
-is enabled through `gcc` compiler flags. Coverage-insrumented executables 
-(i.e. test suites) output coverage result files to disk when run. `gcov`,
-`gcovr`, and `reportgenerator` (the tools managed by this plugin) all produce
-their coverage tallies from these files. `gcov` is part of the GNU compiler
-collection. The other tools — detailed below — require separate installation.
-
-Ceedling’s default toolchain is the same as needed by this plugin. If you
-are already running Ceedling test suites with the GNU compiler toolchain, 
-you are good to go. If you are using another toolchain for test suite and/or
-release builds you will need to install the GNU compiler collection to use
-this plugin. Depending on your needs you may also need to install the reporting
-utilities, `gcovr` and/or `reportgenerator`.
-
-### `gcovr` and `reportgenerator`’s dependence on `gcov`
-
-Both the `gcovr` and `reportgenerator` tools depend on the `gcov` tool. This
-dependency plays out in two different ways. In both cases, the report
-generation utilities ingest `gcov`’s output to produce their artifacts. As
-such, `gcov` must be available in your environment if using report generation.
-
-1. `gcovr` calls `gcov` directly.
-
-    Because it calls `gcov` directly, you are limited as to the
-    advanced Ceedling features you can employ to modify `gcov`’s execution.
-    However, with a configuration option (see below) you can instruct `gcovr`
-    to call something other than `gcov` (e.g. a script that intercepts and
-    modifies how `gcovr` calls out to `gcov`).
-
-    `gcovr` instructs `gcov` to generate `.gcov` files that it processes and
-    discards. A `gcovr` option documented below will retain the `.gcov` files.
-
-2. `reportgenerator` expects the existence of `.gcov` files to do its work.
-
-    This Ceedling plugin calls `gcov` appropriately to generate the `.gcov` 
-    files `reportgenerator` needs before then calling the report utility. 
-
-    You can use Ceedling’s features to modify how `gcov` is run before 
-    `reportgenerator`.
-
-## Enable this plugin
-
-To use this plugin it must be enabled in your Ceedling project file:
-
-```yaml
-:plugins:
-  :enabled:
-    - gcov
-```
-
-This simple configuration will create new `gcov:` command line tasks to run 
-tests with source coverage and output simple coverage summaries to the console 
-as above.
-
-## Disabling automatic coverage summaries
-
-To disable the coverage summaries generated immediately following `gcov:` tasks,
-simply add the following to a top-level `:gcov:` section in your project
-configuration file.
-
-```yaml
-:plugins:
-  :enabled:
-    - gcov
-
-:gcov:
-  :summaries: FALSE
-```
-
-## Report generation
-
-To generate reports:
-
-1. GCovr and / or ReportGenerator must installed or otherwise ready to run in
-   Ceedling’s environment.
-1. Reporting options must be configured in your project file beneath a `:gcov:`
-   entry.
-
-The next sections explain each of these steps.
-
-### Modified Condition / Decision Coverage
-
-As of version 14, the GNU Compiler Collection supports MC/DC. If your environment
-contains a minimum of GCC 14 you can enable MC/DC in coverage summaries.
-
-If your environment contains a minimum of GCC 14 and GCovr 8, you can enable MC/DC 
-in your generated coverage reports.
-
-NOTE: ReportGenerator does not support MC/DC reporting.
-
-```yaml
-:plugins:
-  :enabled:
-    - gcov
-
-:gcov:
-  :mcdc: TRUE
-```
-**Default:** `FALSE`
-
-### Coverage for untested sources
-
-This setting controls how the GCov plugin handles project source files that
-are not exercised by any test. It takes one of three values:
-
-* `:ignore` — Untested source files are not processed at all. Nothing is
-  logged, nothing is compiled, and these files are simply absent from the
-  coverage report.
-* `:list` — Untested source files are not compiled with coverage, but their
-  filepaths are logged as a warning so you know which files will not appear
-  in the coverage report.
-* `:compile` — All untested source files are compiled with coverage so they
-  appear in the final report with 0% coverage (since no test exercises
-  them). This causes all source files to appear in any generated reporting.
-  If a source file fails to compile, Ceedling logs guidance at the console,
-  and the build fails.
-
-```yaml
-:plugins:
-  :enabled:
-    - gcov
-
-:gcov:
-  :untested_sources: :list
-```
-**Default:** `:list`
-
-!!! warning
-    **Compiling all untested sources for 0% coverage reporting (`:compile`) will likely require additional work.**
-
-    Successful compilation of untested source files may require certain symbols 
-    to be defined, certain flags to be set, or entire stand-in shims for platform 
-    headers and code.
-    
-    Ceedling’s 
-    [`:defines`](../../configuration/reference/defines.md)
-    and 
-    [`:flags`](../../configuration/reference/flags.md)
-    matchers can provide these. For GCov tasks, symbols and flags are extracted from
-    the `:test` context beneath the `:defines` and `:flags` configuration sections 
-    by default. If you need something special for coverage builds, use the `:gcov` 
-    context for these matchers instead.
-
-Notes:
-
-* Versions of GCovr before 7.0 do not include the necessary options to produce 
-  0% coverage results for source files only compiled (but never executed).
-
----
-
-When `:untested_sources` is `:compile`, an additional `gcov:untested_sources`
-build task becomes available:
-
-```shell
- > ceedling gcov:untested_sources
-```
-
-This task exists to let you work through the compilation problems described
-in the warning above — missing symbols, flags, or platform header/code
-stand-ins — by re-running just the untested-source compilation step
-directly. No test suite build is needed while iterating on source compilation 
-fixes.
-
-### Reporting utilities installation
-
-!!! tip "Variants of the `madsciencelab` Docker images come with these tools preinstalled"
-    See [the Docker image options](../../getting-started/installation.md#madsciencelab-docker-images)
-    for running Ceedling.
-
-[gcovr] is available on any platform supported by Python.
-
-`gcovr` can be installed via pip like this:
-
-```shell
- > pip install gcovr
-```
-
-[ReportGenerator] is available on any platform supported by .Net.
-
-`ReportGenerator` can be installed via .NET Core like so:
-
-```shell
- > dotnet tool install -g dotnet-reportgenerator-globaltool
-```
-
-Either or both of `gcovr` or `ReportGenerator` may be used. Only one must 
-be installed for advanced report generation.
-
-[gcovr]: https://www.gcovr.com/
-[ReportGenerator]: https://reportgenerator.io
-
-### Enabling reporting utilities
-
-If reports are configured (see next sections) but no `:utilities:` subsection 
-exists, this plugin defaults to using `gcovr` for report generation.
-
-Otherwise, enable Gcovr and / or ReportGenerator to create coverage reports.
-
-```yaml
-:gcov:
-  :utilities:
-    - gcovr           # Use `gcovr` to create reports (default if no :utilities set).
-    - ReportGenerator # Use `ReportGenerator` to create reports.
-```
-
-### Automatic and manual report generation
-
-By default, if reports are specified, this plugin automatically generates 
-reports after any `gcov:` task is executed. To disable this behavior, add
-`:report_task: TRUE` to your project file’s `:gcov:` configuration.
-
-With this setting enabled, an additional Ceedling task `report:gcov` is enabled.
-It may be executed after `gcov:` tasks to generate the configured reports.
-
-For small projects, the default behavior is likely preferred. This alernative 
-setting allows large or complex projects to execute potentially time intensive 
-report generation only when desired.
-
-Enabling the manual report generation task looks like this:
-
-```yaml
-:gcov:
-  :report_task: TRUE
-```
-
-<br/><br/>

data/docs/mkdocs/plugins/gcov/tool-versions.md

@@ -1,60 +0,0 @@
-# Supported tool versions
-
-_**Last updated:**_ May 17, 2026
-
-At the time of the last major updates to the Gcov plugin, the following notes
-on version compatibility were known to be accurate.
-
-Keep in mind that for proper functioning, you do not necessarily need to
-install all the tooks the Gcov plugin works with. Depending on configuration
-options documented in later sections, any of the following tool combinations
-may be sufficient for your needs:
-
-1. `gcov`
-1. `gcov` + `gcovr`
-1. `gcov` + `reportgenerator`
-1. `gcov` + `gcovr` + `reportgenerator`
-
-## `gcov`
-
-The Gcov plugin is known to work with `gcov` packaged with GNU Compiler
-Collection 12 through at least 15.
-
-The maintainers of `gcov` introduced significant behavioral changes for
-version 12. Previous versions of `gcov` had a simple exit code scheme with only a
-single non-zero exit code upon fatal errors. Since version 12 `gcov` emits a
-variety of exit codes even if the noted issue is a non-fatal error. The Gcov
-plugin's logic assumes version 12 behavior and processes failure messages and
-exit codes appropriately, taking into account plugin configuration options.
-
-The Gcov plugin should be compatible with versions of `gcov` before version 12.
-That is, its improved `gcov` exit handling should not be broken by the prior
-simpler behavior. The Gcov plugin dependes on the `gcov` command line and has
-been compatible with it as far back as `gcov` version 7.
-
-Because long file paths are quite common in software development scenarios, by
-default, the Gcov plugin depends on the `gcov` `-x` flag. This flag hashes long
-file paths to ensure they are not a problem for certain platforms' file
-systems. This flag became available with `gcov` version 7. We do not recommend 
-using `gcov` version 6 and earlier. And, in fact, because of the Gcov plugin's 
-dependence on the `gcov` `-x` flag, attempting to use it will fail.
-
-GNU Compiler Collection 14 introduced changes in how coverage is instrumented.
-The `gcov` plugin implemented a revised means of processing coverage that is
-forward compatible with GCC 14+ and backwards compatible to the earliest
-versions of the collection.
-
-## `gcovr`
-
-The Gcov plugin is known to work with `gcovr` 5.2 through `gcovr` 8.x. The
-Gcov plugin supports `gcovr` command line conventions since version 4.2 and
-attempts to support `gcovr` command lines before version 4.2. We recommend 
-using `gcovr` 5 and later.
-
-## `reportgenerator`
-
-The Gcov plugin is known to work with `reportgenerator` 5.2.4. The command line
-for executing `reportgenerator` that the Gcov plugin relies on has largely been
-stable since version 4. We recommend using `reportgenerator` 5.0 and later.
-
-<br/><br/>

data/docs/mkdocs/plugins/gcov/troubleshooting.md

@@ -1,78 +0,0 @@
-# Advanced & Troubleshooting
-
-## Advanced usage
-
-Details of interest for this plugin to be modified or made use of using 
-Ceedling’s advanced features are primarily contained in 
-[defaults_gcov.rb](../../snapshot/plugins/gcov/config/defaults_gcov.rb) and [defaults.yml](../../snapshot/plugins/gcov/config/defaults.yml).
-
-## "gcovr not found"
-
-`gcovr` is a Python-based application. Depending on the particulars of its 
-installation and your platform, you may encounter a "gcovr not found" error. 
-This is usually related to complications of running a Python script as an 
-executable.
-
-### Check your `PATH`
-
-The problem may be as simple to solve as ensuring your user or system path 
-include the path to `python` and/or the `gcovr` script. `gcovr` may be 
-successfully installed and findable by Python; this does not necessarily 
-mean that shell commands Ceedling spawns can find these tools.
-
-Options:
-
-1. Modify your user or system path to include your Python installation, `gcovr`
-   location, or both.
-1. Use Ceedling’s `:environment` project configuration with its special 
-   handling of `PATH` to modify the search path Ceedling accesses when it 
-   executes shell commands. xample below.
-
-```yaml
-:environment:
-  - :path:               # Concatenates the following with OS-specific path separator             
-     - <path to add>     # Add Python and/or `gcovr` path
-     - "#{ENV['PATH']}"  # Fetch existing path entries
-```
-
-### Redefine `gcovr` to call Python directly
-
-Another solution is simple in concept. Instead of calling `gcovr` directly, call 
-`python` with the `gcovr` script as a command line argument (followed by all of 
-the configured `gcovr` arguments).
-
-To implement the solution, we make use of two features:
-
-* `gcovr`’s tool `:executable` definition that looks up an environment variable.
-* Ceedling’s `:environment` settings to redefine `gcovr`.
-
-Gcovr’s tool defintion, like many of Ceedling’s tool defintions, defaults to an
-environment variable (`GCOVR`) if it is defined. If we set that environment
-variable to call Python with the path to the `gcovr` script, Ceedling will call
-that instead of only `gcovr`. Ceedling enables you to set environment variables
-that only exist while it runs.
-
-In your project file:
-
-```yaml
-:environment:
-  # Fill in / omit paths on your system as appropritate to your circumstances
-  - :gcovr: <path>/python <path>/gcovr
-```
-
-Alternatively, a slightly more elegant approach may work in some cases:
-
-```yaml
-:environment:
-  - ":gcovr: python #{`which gcovr`}" # Shell out to look up the path to gcovr
-```
-
-A variation of this concept relies on Python’s knowledge of its runtime
-environment and packages:
-
-```yaml
-:environment:
-  - :gcovr: python -m gcovr # Call the gcovr module
-```
-
-<br/><br/>

data/docs/mkdocs/plugins/index.md

@@ -1,261 +0,0 @@
-# Ceedling Plugins
-
-Ceedling includes a number of built-in plugins. Each plugin linked below
-includes full documentation of its capabilities and configuration options.
-
-!!! tip "Need a CI test build report?"
-    [Test Suite Report Log Factory](report-tests-log-factory.md) provides
-    a handful of popular reports and the ability to create your own.
-
-!!! tip "Have custom needs?"
-    Many find the handy-dandy [Command Hooks plugin](command-hooks.md)
-    is often enough as it allows you to connect your own scripts and tools 
-    to Ceedling build steps. Alternatively, you can 
-    [create your own plugins](../development/plugins/index.md).
-
-See the [`:plugins` configuration reference](../configuration/reference/plugins.md) 
-for how to enable built-in plugins and load custom plugins in your project.
-
----
-
-## Understanding plugin build duplication
-
-!!! warning
-    Build-related plugins intentionally execute duplicated builds.
-
-Plugins including [Gcov](gcov/index.md), [Bullseye](bullseye.md), and [Valgrind](valgrind.md)
-recreate test build tasks. That is, the command line build task `test:foo` also exists 
-as `gcov:foo`, `bullseye:foo`, and/or `valgrind:foo` if these plugins are enabled.
-Each of these triggers a full rebuild of the named test with instrumentation 
-activated. **This duplication is intentional and very necessary.**
-
-These plugins modify executable code or the environment in which a test suite 
-executable runs. Duplicating and segregating the build tasks addresses several 
-important issues:
-
-1. **Conflicting interactions**. Enabling multiple plugins without 
-   duplicated tasks (i.e. integrated build tasks) can bring about conflicts and
-   undefined behavior. For instance, Gcov’s instrumentation does not
-   necessarily play nice with Valgrind’s memory-instrumented emulation
-   runtime, and the two should be kept entirely segregated.
-2. **Unforeseen effects**. These plugins can directly alter the functioning of
-   the code under test. For instance, coverage instrumentation inserted into
-   your compiled code can alter its function or timing. As such, it is vital
-   to maintain distinct builds to compare them. Your vanilla test suite build
-   may function slightly differently than the coverage-instrumented build.
-3. **Optional instrumentation**. The `<plugin>:` command line task convention
-   also provides a very simple opt-in scheme. Plugins automatically enabled 
-   for every build drives the desire to optional disable them. Valgrind testing
-   can require 25-50x the execution time of a test suite, and you likely will
-   want the option to easily disable it. While Ceedling could certainly provide
-   that option at the command line for otherwise always-on plugins, this
-   plugin task namespacing scheme naturally accomplished this along with the
-   needs of (1) and (2).
-
----
-
-## Directory
-
-### Console Test Results
-
-<div class="grid cards" markdown>
-
--   :material-monitor-screenshot: **[`report_tests_pretty_stdout`](report-tests-pretty-stdout.md)**
-
-    ---
-
-    The default plugin for printing test results to the console. Produces a
-    well-formatted list of summary statistics, ignored and failed tests, and
-    any extraneous output collected from test fixtures.
-
--   :material-monitor-screenshot: **[`report_tests_ide_stdout`](report-tests-ide-stdout.md)**
-
-    ---
-
-    Formats test results for the console such that an IDE executing Ceedling
-    tasks can recognize file paths and line numbers in test failures and link
-    them for direct file navigation.
-
--   :material-monitor-screenshot: **[`report_tests_gtestlike_stdout`](report-tests-gtestlike-stdout.md)**
-
-    ---
-
-    Prints test results to the console in a format that mimics
-    [Google Test's output][gtest-sample-output] — both human readable and
-    recognized by a variety of reporting tools, IDEs, and CI servers.
-
--   :material-monitor-screenshot: **[`report_tests_teamcity_stdout`](report-tests-teamcity-stdout.md)**
-
-    ---
-
-    Processes test results into [TeamCity] service messages printed to the
-    console, allowing the CI server to extract build steps and test results
-    from software builds.
-
-</div>
-
-### Test Results Reports
-
-<div class="grid cards" markdown>
-
--   :material-file-chart: **[`report_tests_log_factory`](report-tests-log-factory.md)**
-
-    ---
-
-    Produces any or all of four useful test suite reports in JSON, JUnit XML,
-    CppUnit XML, or HTML format. Also provides a mechanism for custom reports 
-    with a small amount of Ruby rather than a full plugin.
-
--   :material-file-chart: **[`report_tests_raw_output_log`](report-tests-raw-output-log.md)**
-
-    ---
-
-    Captures extraneous console output generated by test executables —
-    typically for debugging — to log files named after the test executables.
-
--   :material-file-chart: **[`report_build_warnings_log`](report-build-warnings-log.md)**
-
-    ---
-
-    Scans the output of build tools for console warning notices and produces
-    a simple text file that collects all such warning messages.
-
-</div>
-
-### Static & Dynamic Analysis
-
-!!! tip "Ceedling includes integrated `gdb` support"
-    Tracking down weird test failures can require multiple approaches and tools. 
-    Diagnosing a bug causing a test executable crash can benefit from either or 
-    both of these plugins plus Ceedling’s 
-    [backtrace feature](../configuration/reference/project.md#use_backtrace).
-
-<div class="grid cards" markdown>
-
--   :material-file-check: **[`cppcheck`](cppcheck.md)**
-
-    ---
-
-    Adds Ceedling tasks to execute static analysis with [Cppcheck]. Cppcheck helps
-    find bugs related to undefined behavior, dangerous code patterns, and
-    coding style. Cppcheck is even able to analyze non-standard syntax C/C++ code, 
-    as is common in embedded projects. The plugin can produce various reports.
-
--   :material-memory: **[`valgrind`](valgrind.md)**
-
-    ---
-
-    Adds Ceedling tasks to run test executables under [Valgrind] memory error
-    detection. Valgrind catches memory leaks, invalid accesses, and use-after-free
-    bugs. The plugin produces per-test log files in the build artifacts directory.
-
-</div>
-
-### Code Coverage
-
-<div class="grid cards" markdown>
-
--   :material-percent: **[`gcov`](gcov/index.md)**
-
-    ---
-
-    Adds Ceedling tasks to execute tests with GNU code coverage
-    instrumentation. Manages use of [gcov], optional Python-based [GCovr],
-    and .Net-based [ReportGenerator] to produce coverage reports in a
-    variety of formats.
-
--   :material-percent: **[`bullseye`](bullseye.md)**
-
-    ---
-
-    Adds Ceedling tasks to execute tests with code coverage instrumentation
-    provided by the commercial [Bullseye] tool, which provides visualization
-    and report generation from the coverage results.
-
-</div>
-
-### Mocking & Test Doubles
-
-<div class="grid cards" markdown>
-
--   :material-ghost: **[`fff`](fff.md)**
-
-    ---
-
-    Replaces Ceedling’s CMock-based mock generation with the
-    [Fake Function Framework][FFF] — an alternative approach to
-    [test doubles][test-doubles] using simple fake functions.
-
-<!--Spacer so the single fff card does not stretch across multiple grid columns-->
-<div style="visibility:hidden"></div>
-
-</div>
-
-### Build Integration
-
-<div class="grid cards" markdown>
-
--   :material-script-text-play: **[`command_hooks`](command-hooks.md)**
-
-    ---
-
-    Connects Ceedling's build events to tool entries you define in your
-    project configuration. Easily attach your own scripts or command line
-    utilities to build steps without writing a full custom plugin.
-
--   :material-database: **[`compile_commands_json_db`](compile-commands-json-db.md)**
-
-    ---
-
-    Creates a [JSON Compilation Database][json-compilation-database] — a
-    `compile_commands.json` file useful to any editor or IDE that implements
-    [`clangd`][clangd] Language Server Protocol support.
-
--   :material-bell-ring: **[`beep`](beep.md)**
-
-    ---
-
-    Provides a simple audio notification when a test build completes suite
-    execution or fails due to a build error, intended to support developers
-    running time-consuming test suites locally in the background.
-
-</div>
-
-### Project & Release Builds
-
-<div class="grid cards" markdown>
-
--   :material-package-variant-closed: **[`module_generator`](module-generator.md)**
-
-    ---
-
-    Saves time in Test-Driven Development by generating a templated triplet
-    of source file, header file, and test file — scaffolded such that they
-    refer to one another — with convenient command line tasks.
-
--   :material-package-variant-closed: **[`dependencies`](dependencies.md)**
-
-    ---
-
-    Manages release build dependencies (e.g. static libraries) including 
-    fetching those dependencies and calling a given dependency‘s build 
-    process to generate the components needed by your Ceedling release 
-    build target.
-
-</div>
-
-[gtest-sample-output]: https://subscription.packtpub.com/book/programming/9781800208988/11/ch11lvl1sec31/controlling-output-with-google-test
-[TeamCity]: https://jetbrains.com/teamcity
-[Cppcheck]: https://cppcheck.sourceforge.io
-[Valgrind]: https://valgrind.org
-[gcov]: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
-[GCovr]: https://www.gcovr.com/
-[ReportGenerator]: https://reportgenerator.io
-[Bullseye]: http://www.bullseye.com
-[FFF]: https://github.com/meekrosoft/fff
-[test-doubles]: https://blog.pragmatists.com/test-doubles-fakes-mocks-and-stubs-1a7491dfa3da
-[json-compilation-database]: https://clang.llvm.org/docs/JSONCompilationDatabase.html
-[clangd]: https://clangd.llvm.org
-[IDEs]: https://www.throwtheswitch.org/ide
-
-<br/><br/>