ceedling 1.1.10 → 1.2.1

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

@@ -1,145 +0,0 @@
-# Plugin Overview
-
-!!! note
-    When enabled, this plugin creates a new set of `gcov:` tasks that mirror
-    Ceedling’s existing `test:` tasks. A `gcov:` task executes one or more tests
-    with coverage enabled for the source files exercised by those tests.
-
-    `gcov:` tasks entirely duplicate `test:` tasks and test builds because of 
-    the needs of coverage instrumentation at compile time.
-
-This plugin also provides an extensive set of options for generating various
-coverage reports for your project. The simplest is text-based coverage 
-summaries printed to the console after a `gcov:` test task is executed.
-
-## Simple Coverage Summaries
-
-In its simplest usage, this plugin outputs coverage statistics to the console
-for each source file exercised by a test. These console-based coverage 
-summaries are provided after the standard Ceedling test results summary. Other 
-than enabling the plugin and ensuring `gcov` is installed, no further set up 
-is necessary to produce these summaries.
-
-!!! tip
-    [Automatic summaries may be disabled](setup.md#disabling-automatic-coverage-summaries).
-
-When the Gcov plugin is active it enables Ceedling tasks like this:
-
-```shell
- > ceedling gcov:Model
-```
-
-… that then generate output like this:
-
-```
---------------------------
-GCOV: OVERALL TEST SUMMARY
---------------------------
-TESTED:  1
-PASSED:  1
-FAILED:  0
-IGNORED: 0
-
----------------------------
-GCOV: CODE COVERAGE SUMMARY
----------------------------
-
-TestModel
----------
-Model.c | Lines executed:100.00% of 4
-Model.c | No branches
-Model.c | No calls
-TimerModel.c | Lines executed:0.00% of 3
-TimerModel.c | No branches
-TimerModel.c | No calls
-```
-
-## Advanced Coverage Reports
-
-For more advanced visualizations and reporting, this plugin also supports a 
-variety of report generation options.
-
-Advanced report generation uses [gcovr] and / or [ReportGenerator] to generate
-HTML, XML, JSON, or text-based reports from coverage-instrumented test runs. 
-See the tools' respective sites for examples of the reports they can generate.
-
-In the default configuration, if reports are enabled, this plugin automatically
-generates reports in the build’s `artifacts/` directory after each execution of
-a `gcov:` task.
-
-An optional setting documented below disables automatic report generation, 
-providing a separate Ceedling task instead. Reports can then be generated
-on demand after test suite runs.
-
-[gcovr]: https://www.gcovr.com/
-[ReportGenerator]: https://reportgenerator.io
-
-## Summaries vs. Reports
-
-Coverage summaries and coverage reports provide different levels of fidelity
-and usability. Summaries are relatively unsophisticated while reports are 
-sophisticated. As such, both provide different capabilities and levels of 
-usability.
-
-### Coverage summaries
-
-Optional coverage summaries are intentionally simple. They require no
-configuration and, to oversimplify, are largely filtered output from the `gcov`
-tool.
-
-Coverage summaries are reported to the console for each source file exercised by
-the tests executed by `gcov:` tasks. That is, coverage summaries correspond to
-the tests executed, and in turn, the source code that your tests call. This
-could be all tests (and thus all source code) or a subset of tests (and some
-subset of source code). The `gcov` tool is run multiple times after test suite
-execution in direct relation to the set of tests you ran with `gcov:` testing 
-tasks. In short, the scope of coverage summaries is guaranteed to match the
-test suite you run.
-
-Coverage summaries do not include any sort of grand total, final tallies. This 
-is the domain of full coverage reports.
-
-Note that Ceedling can exercise the same source code under multiple scenarios
-using multiple test files. Practically, this means that the same source file
-may be listed in the coverage summaries more than once. That said, its coverage
-statistics will be the same each time — the aggregate result of all tests that
-exercised it.
-
-### Coverage reports
-
-Coverage reports provide both much more detail and better overviews of coverage
-than the console-based coverage summaries. However, with this comes the need
-for more sophisticated configuration and certain caveats on what is reported.
-
-Later sections detail how to configure the reports this plugin can generate.
-
-Of note is a consequence of how reports are generated and the limits of the
-tools that do so. Reports are generated using coverage results on disk. The
-report generation tools slurp up the coverage results they find in the `gcov/`
-build output directory. This means that previous test suite runs can "pollute"
-coverage reports. The solution is simple if blunt — run the `clobber` task
-before running a coverage-instrumented test suite. This will yield a coverage
-report with scope that matches that of the test suite you run.
-
-Both the `gcovr` and `reportgeneator` reporting utilities include powerful
-filters that can limit the scope of reports. Hypothetically, it’s possible for
-coverage reports to have the same clear scope as coverage summaries. However,
-in large projects, these filters would cause impractically long command lines.
-Both tools provide configuration file options that would solve the command line
-problem. However, this feature is "experimental" for `gcovr` and considerable 
-work to implement for both reporting utilities. At present, running 
-`ceedling clobber` before generating reports is the best option to ensure 
-accurate reports.
-
-## References
-
-Much of the text describing report generations options in this document was 
-taken from the [Gcovr User Guide][gcovr-user-guide] and the
-[ReportGenerator Wiki][report-generator-wiki].
-
-The text is repeated here to provide as useful documenation as possible.
-
-[gcovr-user-guide]: https://www.gcovr.com/en/stable/guide.html
-[report-generator-wiki]: https://github.com/danielpalme/ReportGenerator/wiki
-
-<br/><br/>

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

@@ -1,246 +0,0 @@
-# ReportGenerator Configuration
-
-The `ReportGenerator` utility may be configured with the following configuration items.
-
-All generated reports are found in `<build root>/artifacts/gcov/ReportGenerator/`.
-
-## Example configuration
-
-```yaml
-:gcov:
-  :report_generator:
-    :history_directory: build/artifacts/gcov/history
-    :file_filters: "-./vendor/*;-./build/*;-./test/*;+./src/*"
-    :verbosity: Warning
-    :tag: "release-1.4.0"
-    :num_parallel_threads: 4
-    :gcov_exclude:
-      - some_excluded_file
-    :custom_args:
-      - "-title:MyProject"
-```
-
-## Results filtering
-
-This plugin filters coverage results for `reportgenerator` coverage reporting
-in two separate stages, each with its own defaults.
-
-### Coverage generation filtering
-
-Before `reportgenerator` ever runs, this plugin runs `gcov` itself against each
-`.gcno` file produced by the coverage test build, skipping any that match an 
-exclusion pattern — no `.gcov` data is ever produced for a skipped file, so 
-nothing downstream can put it back into a report.
-
-By default this skips:
-
-- **Test files** — matched by `:test_file_prefix`.
-- **Mocks** — matched by `:mock_prefix`.
-- **Test runners** — any filename containing `_runner`.
-- **Vendored Unity and CMock sources** — `unity.gcno` and `cmock.gcno` by
-  name.
-
-Given `:test_file_prefix` ⇒ `test_` and CMock's default `:mock_prefix` ⇒
-`Mock`, the equivalent filename-fragment patterns are:
-
-```
-test_[^\/\\]*
-Mock[^\/\\]*
-[^\/\\]*_runner[^\/\\]*
-unity
-cmock
-```
-
-These combine with whatever you add via [`:gcov_exclude`](#gcov_exclude)
-below. Your patterns extend this list, they don't replace it.
-
-### Report filtering
-
-Separately, once `.gcov` files exist, ReportGenerator's own `-filefilters:`
-argument controls which of them actually appear in the generated report(s).
-By default this excludes:
-
-1.  **Test paths** — every file anywhere under each of your configured
-    `:paths` ↳ `:test` directories, not only files matching
-    `:test_file_prefix`. A support subdirectory nested under a test path
-    (e.g. `test/support/`) is excluded as a side effect of this — the whole
-    tree goes, not just prefixed test files.
-
-    Given a `:paths` ↳ `:test` entry of `test/`:
-    ```
-    -./test/**/*
-    ```
-
-1.  **The build root** — every generated and vendored file: mocks, test
-    runners, Partials output, Unity, CMock, CException.
-
-    Given `:build_root` ⇒ `build/`:
-    ```
-    -./build/**/*
-    ```
-
-1.  **Partial-generated files** — only when `:use_partials` is enabled, any
-    file whose name starts with Ceedling's Partial filename prefix, wherever
-    it's found (not only under the build root).
-
-    ```
-    -ceedling_partial_*
-    ```
-
-These patterns are generated automatically and placed ahead of whatever you
-provide via [`:file_filters`](#file_filters) below.
-
-### Overriding the defaults
-
-Neither filtering stage above can be overridden or narrowed by plugin
-configuration — only added to.
-
-For [coverage generation filtering](#coverage-generation-filtering),
-[`:gcov_exclude`](#gcov_exclude) only ever adds more exclusion patterns; there
-is no plugin option to disable one of the built-in exclusions, and no way to
-resurrect `.gcov` data for a file `gcov` was never run against in the first
-place.
-
-For [report filtering](#report-filtering), the natural instinct is to reach
-for [`:custom_args`](#custom_args) to pass a second, conflicting
-`-filefilters:` argument, but this is not an option because of ReportGenerator's
-rules and the order in which the filters are provided by the plugin.
-
-In short, there's no supported way to broaden what this plugin reports
-beyond its defaults. If you need to override coverage reporting filtering, 
-use the [Gcovr option for this pluing](gcovr.md) instead. Its
-`:config_file` option hands full control to a `gcovr` configuration file,
-bypassing Ceedling's generated exclusions entirely (see
-[Gcovr's Results filtering](gcovr.md#results-filtering)).
-
-## Plugin configuration
-
-### `:history_directory`
-
-Optional directory for storing persistent coverage information. Can be used
-in future reports to show coverage evolution.
-
----
-
-### `:plugins`
-
-Optional plugin files for custom reports or custom history storage (separated
-by semicolon).
-
-**Example:** `plugin.dll;*.dll`
-
----
-
-### `:assembly_filters`
-
-Optional list of assemblies that should be included or excluded in the
-report (separated by semicolon). Exclusion filters take precedence over
-inclusion filters. Wildcards are allowed, but not regular expressions.
-
-**Example:** `+<included>;-<excluded>`
-
----
-
-### `:class_filters`
-
-Optional list of classes that should be included or excluded in the report
-(separated by semicolon). Exclusion filters take precedence over inclusion
-filters. Wildcards are allowed, but not regular expressions.
-
-**Example:** `+<included>;-<excluded>`
-
----
-
-### `:file_filters`
-
-Optional list of files that should be included or excluded in the report
-(separated by semicolon). Exclusion filters take precedence over inclusion
-filters regardless of order. Wildcards are allowed, but not regular
-expressions.
-
-This plugin places your own patterns first, ahead of the exclusions it
-generates automatically for test paths, the build root, and (when Partials
-are in use) Partial-generated files (see
-[Report filtering](#report-filtering) above for exactly what those defaults
-cover). Because exclusions always win, your patterns can add further
-exclusions or includes but cannot override or remove one of those defaults;
-see [Overriding the defaults](#overriding-the-defaults) above.
-
-**Example:** `"-./vendor/*;-./build/*;-./test/*;-./lib/*;+./src/*"`
-
----
-
-### `:verbosity`
-
-The verbosity level of the log messages.
-
-**Values:** `Verbose`, `Info`, `Warning`, `Error`, `Off`
-
-**Default:** `Warning`
-
----
-
-### `:tag`
-
-Optional tag or build version.
-
----
-
-### `:gcov_exclude`
-
-Optional list of one or more regular expressions to exclude gcov notes
-(`.gcno`) files that match these filters from coverage processing — these
-files are never run through `gcov` at all. A trailing `.gcov` or `.gcno`
-suffix on a pattern is stripped automatically, so either form works.
-
-Ceedling combines your patterns with exclusions it generates automatically
-for test files, mocks, test runners, and vendored Unity/CMock sources (see
-[Coverage generation filtering](#coverage-generation-filtering) above for
-exactly what these cover). Your patterns can only add further exclusions;
-there's no way to override or remove one of the defaults — see
-[Overriding the defaults](#overriding-the-defaults) above.
-
-```yaml
-:gcov:
-  :report_generator:
-    :gcov_exclude:
-      - <regex>
-      - ...
-```
-
-**Default:** `[]`
-
----
-
-### `:num_parallel_threads`
-
-Optionally set the number of threads ReportGenerator uses in parallel. Drives
-both of ReportGenerator's own `numberOfReportsParsedInParallel` and
-`numberOfReportsMergedInParallel` settings together.
-
-**Default:** unset (ReportGenerator's own default applies)
-
----
-
-### `:custom_args`
-
-Optional list of one or more command line arguments to pass to Report
-Generator. Useful for configuring Risk Hotspots and other settings not
-covered by the options above. See the
-[ReportGenerator settings wiki](https://github.com/danielpalme/ReportGenerator/wiki/Settings).
-
-Note: This can be accomplished with Ceedling's tool configuration options
-outside of plugin configuration but is supported here to collect
-configuration options in one place.
-
-```yaml
-:gcov:
-  :report_generator:
-    :custom_args:
-      - <argument>
-      - ...
-```
-
-**Default:** `[]`
-
-<br/><br/>

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

@@ -1,147 +0,0 @@
-# Reporting Configuration
-
-Various reports are available. Each must be enabled in `:gcov` ↳ `:reports`.
-
-If no report types are specified, report generation (but not coverage summaries) 
-is disabled regardless of any other setting.
-
-Most report types can only be generated by `gcovr` or `ReportGenerator`. Some 
-can be generated by both. This means that your selection of report is impacted by
-which generation utility is enabled. In fact, in some cases, the same report type 
-could be generated by each utility (to different artifact build output folders).
-
-!!! note
-    Coverage results are cumulative across builds. That is, if you run a single
-    test file after having run a previous test file, coverage results for both
-    will be present in generated reporting.
-
-    For clean and clear results, run `ceedling clobber` before any coverage 
-    tasks.
-
-Reports are configured with:
-
-1. General or common options for each report generation utility
-1. Specific options for types of report per each report generation utility
-
-For tool-specific plugin configuration options, see:
-
-- [GCovr Configuration](gcovr.md)
-- [ReportGenerator Configuration](reportgenerator.md)
-
-See the [GCovr User Guide][gcovr-user-guide] and the 
-[ReportGenerator Wiki][report-generator-wiki] for full details on using
-these tools.
-
-[gcovr-user-guide]: https://www.gcovr.com/en/stable/guide.html
-[report-generator-wiki]: https://github.com/danielpalme/ReportGenerator/wiki
-
-| Report option | gcovr | ReportGenerator |
-|---|:---:|:---:|
-| `HtmlBasic` | ✓ | ✓ |
-| `HtmlDetailed` | ✓ | ✓ |
-| `Text` | ✓ | ✓ |
-| `Cobertura` | ✓ | ✓ |
-| `SonarQube` | ✓ | ✓ |
-| `JSON` | ✓ | |
-| `HtmlInline` | | ✓ |
-| `HtmlInlineAzure` | | ✓ |
-| `HtmlInlineAzureDark` | | ✓ |
-| `HtmlChart` | | ✓ |
-| `MHtml` | | ✓ |
-| `Badges` | | ✓ |
-| `CsvSummary` | | ✓ |
-| `Latex` | | ✓ |
-| `LatexSummary` | | ✓ |
-| `PngChart` | | ✓ |
-| `TeamCitySummary` | | ✓ |
-| `lcov` | | ✓ |
-| `Xml` | | ✓ |
-| `XmlSummary` | | ✓ |
-
-```yaml
-:gcov:
-  # Specify one or more reports to generate.
-  # Defaults to HtmlBasic.
-  :reports:
-    # Generate an HTML summary report.
-    # Supported utilities: gcovr, ReportGenerator
-    - HtmlBasic
-
-    # Generate an HTML report with line by line coverage of each source file.
-    # Supported utilities: gcovr, ReportGenerator
-    - HtmlDetailed
-
-    # Generate a Text report, which may be output to the console with gcovr or a file in both gcovr and ReportGenerator.
-    # Supported utilities: gcovr, ReportGenerator
-    - Text
-
-    # Generate a Cobertura XML report.
-    # Supported utilities: gcovr, ReportGenerator
-    - Cobertura
-
-    # Generate a SonarQube XML report.
-    # Supported utilities: gcovr, ReportGenerator
-    - SonarQube
-
-    # Generate a JSON report.
-    # Supported utilities: gcovr
-    - JSON
-
-    # Generate a detailed HTML report with CSS and JavaScript included in every HTML page. Useful for build servers.
-    # Supported utilities: ReportGenerator
-    - HtmlInline
-
-    # Generate a detailed HTML report with a light theme and CSS and JavaScript included in every HTML page for Azure DevOps.
-    # Supported utilities: ReportGenerator
-    - HtmlInlineAzure
-
-    # Generate a detailed HTML report with a dark theme and CSS and JavaScript included in every HTML page for Azure DevOps.
-    # Supported utilities: ReportGenerator
-    - HtmlInlineAzureDark
-
-    # Generate a single HTML file containing a chart with historic coverage information.
-    # Supported utilities: ReportGenerator
-    - HtmlChart
-
-    # Generate a detailed HTML report in a single file.
-    # Supported utilities: ReportGenerator
-    - MHtml
-
-    # Generate SVG and PNG files that show line and / or branch coverage information.
-    # Supported utilities: ReportGenerator
-    - Badges
-
-    # Generate a single CSV file containing coverage information per file.
-    # Supported utilities: ReportGenerator
-    - CsvSummary
-
-    # Generate a single TEX file containing a summary for all files and detailed reports for each files.
-    # Supported utilities: ReportGenerator
-    - Latex
-
-    # Generate a single TEX file containing a summary for all files.
-    # Supported utilities: ReportGenerator
-    - LatexSummary
-
-    # Generate a single PNG file containing a chart with historic coverage information.
-    # Supported utilities: ReportGenerator
-    - PngChart
-
-    # Command line output interpreted by TeamCity.
-    # Supported utilities: ReportGenerator
-    - TeamCitySummary
-
-    # Generate a text file in lcov format.
-    # Supported utilities: ReportGenerator
-    - lcov
-
-    # Generate a XML file containing a summary for all classes and detailed reports for each class.
-    # Supported utilities: ReportGenerator
-    - Xml
-
-    # Generate a single XML file containing a summary for all files.
-    # Supported utilities: ReportGenerator
-    - XmlSummary
-```
-
-<br/><br/>