ceedling 1.1.9 → 1.2.0

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

@@ -1,412 +0,0 @@
-# GCovr Configuration
-
-!!! note
-    All reports generated by `gcovr` are found in `<build root>/artifacts/gcov/gcovr/`.
-
-The following sections first discuss GCovr options in common across reports
-and then break out report-specific options.
-
-## GCovr options
-
-### Project config vs. GCovr config file
-
-GCovr can be configured in two ways:
-
-1. Using one or more of the options documented below in the `:gcov` section
-   of your project configuration.
-1. Through a Gcovr configuration file (.ini format) provided to Gcovr via
-   the speciial `:config_file` value in the `:gcov` section of your project
-   configuration.
-
-### Gcovr configuration file
-
-!!! warning "Using a gcovr configuration file"
-    When `:config_file` is set, Ceedling passes only `--root` (`:report_root`) 
-    and `--config` (`:config_file`) to `gcovr` at the command line from your
-    plugin configuration. This prevents overriding config file settings with 
-    CLI arguments. You must provide any settings that would have been provided 
-    by the Gcov plugin.
-
-To preserve filtering of test and build files from coverage results when
-using a Gcovr config file, you must provide explicit exclusion patterns matching 
-your project layout (example below).
-
-```ini
-; You will need to revise these example exclude patterns to match your
-; project directories and file naming as they cannot be automatically 
-; provided to Gcovr when a Gcovr configuration file is in use.
-;
-; Note: Format is flat `key = value` lines with no `[section]` header.
-
-; Test path(s) exclusions for 'test_' files with .c extensions. 
-exclude = .*test.*/test_.+\.c$
-
-; Build path exlcude for all generated C files (runners, mocks, partials).
-exclude = .*build/.+\.c$
-```
-
-## Plugin configuration
-
-The following options are exposed through your project configuration file, all
-beneath `:gcov` ↳ `:gcovr`. Only specify those you need or those whose defaults
-you need to override. You do not need to include all these options in your
-Gcov plugin configuration.
-
-### `:report_root`
-
-The root directory of your source files. File names are reported relative to
-this root. `:report_root` is also the default `:report_include`.
-
-!!! warning "`gcovr` accepts only one reporting root path"
-    `gcovr` accepts only a single path for `:report_root`. In unusual project
-    layouts, you may need to specify as root a parent folder that includes 
-    _all_ source files and selectively exclude paths or files from coverage 
-    reporting (see `:report_exclude` and `:exclude_directories`).
-
-**Default:** `"."` (the current directory)
-
----
-
-### `:config_file`
-
-Load the specified `gcovr` configuration file. (`gcovr --config`)
-
-When `:config_file` is set, Ceedling passes only `--root` and `--config` to
-`gcovr` and defers all other configuration to the file. This prevents
-Ceedling from overriding config file values with its CLI arguments.
-`:report_root` is still applied because Ceedling may invoke `gcovr` from a
-different working directory than your project root.
-
-To preserve the plugin's base filtering behavior, include exclusion patterns
-matching your project layout in the config file itself — see
-[Gcovr configuration file](#gcovr-configuration-file) above.
-
-**Default:** `gcovr.cfg` in the `:report_root` directory, if that file exists.
-
----
-
-### `:fail_under_line`
-
-Exit with a status of 2 if the total line coverage is less than this minimum
-percentage. Can be ORed with the exit status of other `:fail_under_*` options.
-(`gcovr --fail-under-line`)
-
-**Values:** `1`–`100`
-
----
-
-### `:fail_under_branch`
-
-Exit with a status of 4 if the total branch coverage is less than this minimum
-percentage. Can be ORed with the exit status of other `:fail_under_*` options.
-(`gcovr --fail-under-branch`)
-
-**Values:** `1`–`100`
-
----
-
-### `:fail_under_decision`
-
-Exit with a status of 8 if the total decision coverage is less than this minimum
-percentage. Can be ORed with the exit status of other `:fail_under_*` options.
-(`gcovr --fail-under-decision`)
-
-`gcovr` treats `--fail-under-decision` as a no-op without `--decisions` also
-present — setting this option implies `:decisions` (below) automatically, so
-it's never silently non-functional.
-
-**Values:** `1`–`100`
-
-**Requires:** `gcovr` 7.0 or higher
-
----
-
-### `:decisions`
-
-Report the decision coverage. For HTML, JSON, and the summary report.
-(`gcovr --decisions`)
-
-Implied automatically whenever `:fail_under_decision` is set.
-
-**Requires:** `gcovr` 5.1 or higher
-
----
-
-### `:fail_under_function`
-
-Exit with a status of 16 if the total function coverage is less than this minimum
-percentage. Can be ORed with the exit status of other `:fail_under_*` options.
-(`gcovr --fail-under-function`)
-
-**Values:** `1`–`100`
-
----
-
-### `:exception_on_fail`
-
-If any `:fail_under_*` option above is set and its condition is met, specifies
-whether that condition should break the build. When disabled, Ceedling simply
-logs a warning without breaking the build.
-
-**Default:** `false`
-
----
-
-### `:source_encoding`
-
-Select the source file character encoding. (`gcovr --source-encoding`)
-
-**Default:** the system default encoding (typically `UTF-8`)
-
----
-
-### `:branches`
-
-Report the branch coverage instead of the line coverage. Applies to the text
-report only. Uses `gcovr --txt-metric branch` on `gcovr` 7.0+ (`--branches` is
-deprecated as of 7.0, though still functional); `gcovr --branches` below it.
-
----
-
-### `:sort_uncovered`
-
-Sort entries by increasing number of uncovered lines. Applies to text and HTML
-reports. Uses `gcovr --sort uncovered-number` on `gcovr` 7.0+
-(`--sort-uncovered` is deprecated as of 7.0, though still functional);
-`gcovr --sort-uncovered` below it.
-
----
-
-### `:sort_percentage`
-
-Sort entries by increasing percentage of uncovered lines. Applies to text and
-HTML reports. Uses `gcovr --sort uncovered-percent` on `gcovr` 7.0+
-(`--sort-percentage` is deprecated as of 7.0, though still functional);
-`gcovr --sort-percentage` below it.
-
----
-
-### `:print_summary`
-
-Print a small report to stdout with line and branch percentage coverage. This
-is in addition to any other configured reports. (`gcovr --print-summary`)
-
----
-
-### `:report_include`
-
-Keep only source files that match this filter. Filters are regular
-expressions. (`gcovr --filter`)
-
-**Example:** `"^src"`
-
----
-
-### `:report_exclude`
-
-Exclude source files that match this filter. Filters are regular expressions.
-(`gcovr --exclude`)
-
-**Example:** `"^vendor.*|^build.*|^test.*|^lib.*"`
-
----
-
-### `:gcov_filter`
-
-Keep only `.gcov` data files that match this filter. Filters are regular
-expressions. (`gcovr --gcov-filter`)
-
----
-
-### `:gcov_exclude`
-
-Exclude `.gcov` data files that match this filter. Filters are regular
-expressions. (`gcovr --gcov-exclude`)
-
----
-
-### `:exclude_directories`
-
-Exclude directories that match this filter while searching for raw coverage
-files. Filters are regular expressions. (`gcovr --exclude-directories`)
-
----
-
-### `:gcov_executable`
-
-Use a particular `gcov` executable. This may be appropriate and necessary in
-special circumstances — review Ceedling's options for modifying tools first.
-(`gcovr --gcov-executable`)
-
----
-
-### `:exclude_unreachable_branches`
-
-Exclude branch coverage from lines without useful source code.
-(`gcovr --exclude-unreachable-branches`)
-
----
-
-### `:exclude_throw_branches`
-
-For branch coverage, exclude branches that the compiler generates for
-exception handling. (`gcovr --exclude-throw-branches`)
-
----
-
-### `:merge_mode_function`
-
-For `gcovr` 6.0+, multiple instances of the same function in coverage results
-can cause a fatal error. Since Ceedling can test multiple build variations of
-the same source function, this is a real risk. This option controls how
-`gcovr` merges those repeated entries. See the
-[gcovr merging docs](https://gcovr.com/en/stable/guide/merging.html) for all
-valid values. Ignored on `gcovr` versions below 6.0.
-
-**Default:** `merge-use-line-max` (`gcovr`'s own default, `strict`, raises an
-exception for many Ceedling projects)
-
----
-
-### `:use_gcov_files`
-
-Use existing `.gcov` files for analysis instead of running `gcov` again.
-(`gcovr --use-gcov-files`)
-
-**Default:** `false`
-
----
-
-### `:gcov_ignore_parse_errors`
-
-Skip lines with parse errors in `.gcov` files instead of exiting with an
-error. (`gcovr --gcov-ignore-parse-errors`)
-
----
-
-### `:object_directory`
-
-Override normal working directory detection for `.gcda`/`.gcno` files.
-(`gcovr --object-directory`)
-
----
-
-### `:keep`
-
-Keep intermediate `.gcov` files after processing. (`gcovr --keep`)
-
----
-
-### `:delete`
-
-Delete `.gcda` files after processing. (`gcovr --delete`)
-
----
-
-### `:threads`
-
-Set the number of threads `gcovr` uses in parallel. (`gcovr -j`)
-
-## HTML reports
-
-Generation of HTML reports may be modified with the following configuration items.
-
-### `:html_artifact_filename`
-
-Override the default HTML report output filename.
-
----
-
-### `:html_title`
-
-Use `title` as the title for the HTML report. (`gcovr --html-title`)
-
-**Default:** `Head`
-
----
-
-### `:html_medium_threshold`
-
-If the coverage is below this value, it is marked as low coverage in the HTML
-report. Must be lower than or equal to `:html_high_threshold`. If equal to
-`:html_high_threshold`, the report has only high and low coverage.
-(`gcovr --html-medium-threshold`)
-
-**Default:** `75.0`
-
----
-
-### `:html_high_threshold`
-
-If the coverage is below this value, it is marked as medium coverage in the
-HTML report. Must be greater than or equal to `:html_medium_threshold`. If
-equal to `:html_medium_threshold`, the report has only high and low coverage.
-(`gcovr --html-high-threshold`)
-
-**Default:** `90.0`
-
----
-
-### `:html_absolute_paths`
-
-Use absolute paths to link the "detailed" reports. Defaults to relative
-links. (`gcovr --html-absolute-paths`)
-
----
-
-### `:html_encoding`
-
-Override the declared HTML report encoding. (`gcovr --html-encoding`)
-
-**Default:** `UTF-8`
-
-## Cobertura XML reports
-
-Generation of Cobertura XML reports may be modified with the following configuration items.
-
-### `:cobertura_pretty`
-
-Pretty-print the Cobertura XML report. (`gcovr --xml-pretty`)
-
-**Default:** `false`
-
----
-
-### `:cobertura_artifact_filename`
-
-Override the default Cobertura XML report output filename.
-
-## SonarQube XML reports
-
-Generation of SonarQube XML reports may be modified with the following configuration items.
-
-### `:sonarqube_artifact_filename`
-
-Override the default SonarQube XML report output filename.
-
-## JSON reports
-
-Generation of JSON reports may be modified with the following configuration items.
-
-### `:json_pretty`
-
-Pretty-print the JSON report. (`gcovr --json-pretty`)
-
-**Default:** `false`
-
----
-
-### `:json_artifact_filename`
-
-Override the default JSON report output filename.
-
-## Text reports
-
-Generation of text reports may be modified with the following configuration items.
-Text reports may be printed to the console or output to a file.
-
-### `:text_artifact_filename`
-
-Override the default text report output filename.
-
-<br/><br/>

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

@@ -1,74 +0,0 @@
-# GCov
-
-The `gcov` plugin integrates the code coverage abilities of the GNU compiler 
-collection with test builds. It provides simple coverage metrics by default and
-can optionally produce sophisticated coverage reports.
-
-!!! note
-    The Gcov plugin creates a duplicate test build with `gcov:` command line
-    plugin tasks. [This is intentional and needed](../index.md#understanding-plugin-build-duplication).
-
----
-
-<div class="grid cards" markdown>
-
--   :material-information-outline: **[Overview][overview]**
-
-    ---
-
-    How the plugin works, task types, summaries vs. reports.
-
--   :material-tag-outline: **[Tool Versions][tool-versions]**
-
-    ---
-
-    Compatibility notes for `gcov`, `gcovr`, and `ReportGenerator`.
-
--   :material-cog-outline: **[Set Up & Configuration][setup]**
-
-    ---
-
-    Toolchain requirements, enabling the plugin, and report generation setup.
-
--   :material-lightning-bolt: **[Example Usage][examples]**
-
-    ---
-
-    Examples for automatic and manual report generation.
-
--   :material-file-chart-outline: **[Reporting Configuration][reporting]**
-
-    ---
-
-    Available report types and the `:reports` YAML option.
-
--   :material-wrench-outline: **[GCovr Configuration][gcovr]**
-
-    ---
-
-    All `:gcovr` YAML options for HTML, XML, JSON, text, and common settings.
-
--   :material-file-cog-outline: **[ReportGenerator Configuration][reportgenerator]**
-
-    ---
-
-    All `:report_generator` YAML options.
-
--   :material-lifebuoy: **[Advanced & Troubleshooting][troubleshooting]**
-
-    ---
-
-    Advanced configuration and troubleshooting solutions.
-
-</div>
-
-[overview]:          overview.md
-[tool-versions]:     tool-versions.md
-[setup]:             setup.md
-[examples]:          examples.md
-[reporting]:         reporting.md
-[gcovr]:             gcovr.md
-[reportgenerator]:   reportgenerator.md
-[troubleshooting]:   troubleshooting.md
-
-<br/><br/>

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