ceedling 1.1.10 → 1.2.0

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

@@ -1,526 +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.
-
-A Gcovr config file replaces Ceedling's own automatically generated exclusion
-patterns (see [Results filtering](#results-filtering) below) entirely — it is
-the only way to override or remove one of those defaults, since the
-project-configuration `:report_exclude` option can only add further
-exclusions on top of them, never take one away. To preserve the same
-filtering of test and build files when switching to a Gcovr config file, you
-must provide equivalent explicit exclusion patterns matching your project
-layout yourself (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$
-```
-
-## Results filtering
-
-By default, this plugin configures `gcovr` to excludes three categories of 
-`.c` files from coverage results. These defaults exist because a
-coverage percentage is typically only meaningful over the production code 
-you're actually trying to exercise with test coverage. Test code, test 
-support code, and every file Ceedling itself generates as part of a build 
-will skew that number if left in coverage reporting.
-
-The list that follows details the filtering this plugin injects into 
-Gcovr coverage report generation. The examples are usable regular 
-expressions that mirror the defaults in use. The plugin dynamically 
-generates these regular expressions from your project configuration.
-When creating them youself, you will need to match your project 
-configuration settings with static strings.
-
-1.  **Test files** — matched by `:test_file_prefix` within your configured
-    `:paths` ↳ `:test` directories.
-
-    Given `:test_file_prefix` ⇒ `test_` and a `:paths` ↳ `:test` entry of
-    `test/`:
-
-    ```
-    .*test/.*/test_.+\.c$
-    ```
-
-2.  **Test support files** — any `.c` file within your configured `:paths` ↳
-    `:support` directories, regardless of name. Helpers, stubs, and fixtures
-    living there are no more production code than the test files themselves.
-
-    Given a `:paths` ↳ `:support` entry of `test/support/`:
-
-    ```
-    .*test/support/.+\.c$
-    ```
-
-3.  **Generated and vendored files** — any `.c` file anywhere below your
-    `:build_root`: generated mocks, test runners, Partials output, and the
-    vendored Unity/CMock/CException framework sources Ceedling copies in to
-    build against. This pattern always matches a literal `.c` extension
-    regardless of your project's own `:extension` ↳ `:source` setting, since
-    every file it catches is one Ceedling itself writes in plain C.
-
-    Given `:build_root` ⇒ `build/`:
-
-    ```
-    .*build/.+\.c$
-    ```
-
-These patterns are generated automatically and combined with whatever you
-provide via [`:report_exclude`](#report_exclude) below.
-
-!!! warning "Not applied when using a Gcovr configuration file"
-    These defaults are only generated when Ceedling builds `gcovr`'s command
-    line directly. As covered in
-    [Gcovr configuration file](#gcovr-configuration-file) above, setting
-    `:config_file` bypasses this entirely — none of the three patterns above
-    are applied, and you must supply equivalent exclusions in the config file
-    yourself.
-
-### Overriding the defaults
-
-[`:report_exclude`](#report_exclude) can only add exclusions on top of the
-three defaults above — `gcovr --exclude` is a deny-list with no way to
-"un-exclude" a pattern already passed to it, and this plugin always passes its
-own three patterns ahead of anything you configure there. Setting
-[`:report_include`](#report_include) doesn't help either; it narrows which
-files are considered at all, but an exclude pattern still wins over it for
-any file matching both.
-
-The only way to actually remove or replace one of these defaults — for
-example, to include test files in coverage results so you can confirm a
-conditional test build compiled the branches you expect — is a
-[Gcovr configuration file](#gcovr-configuration-file). Setting `:config_file`
-stops Ceedling from generating any of the three patterns at all, handing you
-full control:
-
-```ini
-; gcovr.cfg — omits the test-file exclude pattern so test files remain in
-; coverage results, while still keeping generated/vendored build output out.
-exclude = .*build/.+\.c$
-```
-
-```yaml
-:gcov:
-  :gcovr:
-    :config_file: gcovr.cfg
-```
-
-Note that this isn't scoped per category. Once a default is dropped, any
-file it would have excluded is folded into the same combined report as your
-production code, not broken out separately.
-
-## 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`)
-
-This narrows which files are considered at all, but does not override
-[Results filtering](#results-filtering)'s automatic exclusion defaults — a
-file excluded by one of those three default patterns stays excluded even if
-it also matches `:report_include`. See
-[Overriding the defaults](#overriding-the-defaults) if you need to remove one
-of them.
-
-**Example:** `"^src"`
-
----
-
-### `:report_exclude`
-
-Exclude source files that match this filter. Filters are regular expressions.
-(`gcovr --exclude`)
-
-Ceedling automatically generates and prepends its own exclusion patterns for
-test files, test support files, and generated/vendored build files — see
-[Results filtering](#results-filtering) above for exactly what these cover
-and why. Anything you provide here is combined with those defaults, not a
-replacement for them. This option can only add further exclusions, never
-remove or override one of the three defaults.
-See [Overriding the defaults](#overriding-the-defaults) for how to do 
-that instead.
-
-**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/>