ceedling 1.1.10 → 1.2.0

data/docs/mkdocs/reference/environment-vars.md

@@ -1,60 +0,0 @@
-# Environment Variables Reference
-
-See [Getting Started → Environment Variables](../configuration/environment-vars.md)
-for context on when and why to use these variables.
-
-## Project configuration
-
-### `CEEDLING_PROJECT_FILE`
-
-Points Ceedling at your project configuration file. This is
-[one of several options](../configuration/loading.md) for specifying the
-project file location.
-
-### `CEEDLING_MIXIN_#`
-
-Environment variables named `CEEDLING_MIXIN_#` — where `#` is any positive
-integer — specify filepaths to mixin YAML files to be merged into your base
-project configuration. Multiple mixin environment variables are merged in
-ascending numeric order (e.g. `CEEDLING_MIXIN_1` before `CEEDLING_MIXIN_5`
-before `CEEDLING_MIXIN_99`).
-
-See [_Loading Configuration_](../configuration/mixins.md#environment-variables)
-for the full details on Mixin environment variables.
-
-## Console output — `CEEDLING_DECORATORS`
-
-Forces Ceedling's console logging decorators (fancy Unicode characters, emoji,
-and color) on or off.
-
-!!! warning "`CEEDLING_DECORATORS` cannot be set with `:environment`"
-    Ceedling's logger must load before any environment variables are processed 
-    in your project configuration. As such, `CEEDLING_DECORATORS` can only be set 
-    in your environment before Ceedling runs.
-
-By default, Ceedling makes an educated guess as to which platforms can best
-support decorators. Some platforms (we're looking at you, Windows) do not
-typically have default font support in their terminals for these features. So,
-by default this feature is disabled on problematic platforms while enabled on
-others.
-
-Set `CEEDLING_DECORATORS` to `true` (`1`) to force decorators on, or `false`
-(`0`) to force them off.
-
-Example with decorators enabled:
-
-```
------------------------
-❌ OVERALL TEST SUMMARY
------------------------
-TESTED:  6
-PASSED:  5
-FAILED:  1
-IGNORED: 0
-```
-
-If you find a monospaced font that provides emojis, etc. and works with Windows'
-command prompt, you can (1) Install the font (2) change your command prompt's
-font (3) set `CEEDLING_DECORATORS` to `true`.
-
-<br/><br/>

data/docs/mkdocs/reference/gcov-plugin.md

@@ -1,600 +0,0 @@
-# Coverage Reporting
-
-The `gcov` plugin is one of Ceedling’s most used features. It orchestrates GCC 
-coverage instrumentation and use of the `gcov` tool to generate code coverage 
-for test builds. Optionally, it can generate HTML, XML, JSON, and text reports 
-via the GCovr and/or ReportGenerator reporting tools.
-
-See the full [Gcov Plugin documentation](../plugins/gcov/index.md) for concepts, 
-installation, troubleshooting, and worked examples.
-
-```yaml
-:plugins:
-  :enabled:
-    - gcov
-
-:gcov:
-  :summaries: FALSE
-
-:gcov:
-  :utilities:
-    - gcovr
-
-:gcov:
-  :reports:
-    - HtmlBasic
-```
-
----
-
-## `gcov` Plugin Settings
-
-Options avialable directly beneath `:gcov`.
-
-### `:summaries`
-
-Enable or disable automatic console coverage summaries printed after each
-`gcov:` task.
-
-**Default:** `TRUE`
-
-```yaml
-:gcov:
-  :summaries: FALSE
-```
-
----
-
-### `:mcdc`
-
-Enable or disable Modified Condition / Decision Coverage in coverage results.
-This feature is dependent on minimum tool versions.
-
-**Default:** `FALSE`
-
-```yaml
-:gcov:
-  :mcdc: TRUE
-```
-
----
-
-### `:untested_sources`
-
-!!! 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.
-
-Controls handling of source files not exercised by any test. Valid values:
-
-* `:ignore` — Skip untested sources entirely (no logging, no compilation).
-* `:list` — Log the filepaths of untested sources as a warning; do not compile them.
-* `:compile` — Compile all untested sources with coverage so they appear in
-  the report at 0% coverage. On compilation failure, Ceedling logs
-  guidance and fails the build.
-
-**Default:** `:list`
-
-```yaml
-:gcov:
-  :untested_sources: :list
-```
-
-When `:untested_sources` is set to `:compile`, a `gcov:untested_sources` task is
-also available, letting you re-run just the untested-source compilation step
-on its own — without a full `gcov:` test suite run — while iterating on source
-compilation fixes.
-
----
-
-### `:utilities`
-
-List of report generation utilities to enable. Valid values are `gcovr` and
-`ReportGenerator`. Either or both may be specified.
-
-**Default:** `[gcovr]` (when `:reports:` is configured and `:utilities:` is absent)
-
-```yaml
-:gcov:
-  :utilities:
-    - gcovr
-    - ReportGenerator
-```
-
----
-
-### `:report_task`
-
-When `TRUE`, disables automatic report generation after `gcov:` tasks and
-instead enables a separate `report:gcov` Ceedling task for on-demand report
-generation.
-
-**Default:** `FALSE`
-
-```yaml
-:gcov:
-  :report_task: TRUE
-```
-
----
-
-### `:reports`
-
-List of report types to generate. When empty or absent, report generation
-(but not coverage summaries) is disabled.
-
-```yaml
-:gcov:
-  :reports:
-    - HtmlBasic
-    - HtmlDetailed
-    - ...
-```
-
-| Report option | gcovr | ReportGenerator |
-|---|:---:|:---:|
-| `HtmlBasic` | ✓ | ✓ |
-| `HtmlDetailed` | ✓ | ✓ |
-| `Text` | ✓ | ✓ |
-| `Cobertura` | ✓ | ✓ |
-| `SonarQube` | ✓ | ✓ |
-| `JSON` | ✓ | |
-| `HtmlInline` | | ✓ |
-| `HtmlInlineAzure` | | ✓ |
-| `HtmlInlineAzureDark` | | ✓ |
-| `HtmlChart` | | ✓ |
-| `MHtml` | | ✓ |
-| `Badges` | | ✓ |
-| `CsvSummary` | | ✓ |
-| `Latex` | | ✓ |
-| `LatexSummary` | | ✓ |
-| `PngChart` | | ✓ |
-| `TeamCitySummary` | | ✓ |
-| `lcov` | | ✓ |
-| `Xml` | | ✓ |
-| `XmlSummary` | | ✓ |
-
----
-
-## GCovr Settings
-
-All options below live under `:gcov:` ↳ `:gcovr:`. Reports are written to
-`<build root>/artifacts/gcov/gcovr/`.
-
-### `:report_root`
-
-Root directory of your source files; file names in reports are relative to
-this path.
-
-**Default:** `"."` (current directory)
-
----
-
-### `:config_file`
-
-Load a `gcovr` configuration file. (`gcovr --config`)
-
-**Default:** `gcovr.cfg` in the `:report_root` directory, if present.
-
----
-
-### `:fail_under_line`
-
-Exit with status 2 if total line coverage is below this percentage.
-(`gcovr --fail-under-line`)
-
-**Values:** `1`–`100`
-
----
-
-### `:fail_under_branch`
-
-Exit with status 4 if total branch coverage is below this percentage.
-(`gcovr --fail-under-branch`)
-
-**Values:** `1`–`100`
-
----
-
-### `:fail_under_decision`
-
-Exit with status 8 if total decision coverage is below this percentage.
-(`gcovr --fail-under-decision`)
-
-`gcovr` treats `--fail-under-decision` as a no-op without `--decisions` also
-present — setting this option implies `:decisions` (below) automatically.
-
-**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 status 16 if total function coverage is below this percentage.
-(`gcovr --fail-under-function`)
-
-**Values:** `1`–`100`
-
----
-
-### `:exception_on_fail`
-
-When any `:fail_under_*` threshold is set, raise a build-breaking exception
-instead of only logging a warning.
-
-**Default:** `FALSE`
-
----
-
-### `:source_encoding`
-
-Source file character encoding. (`gcovr --source-encoding`)
-
-**Default:** system default (typically `UTF-8`)
-
----
-
-### `:branches`
-
-Report branch coverage instead of line coverage. Applies to text reports 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 report 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 report 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 brief line- and branch-coverage summary to stdout in addition to any
-other reports. (`gcovr --print-summary`)
-
----
-
-### `:report_include`
-
-Keep only source files matching this regular expression filter.
-(`gcovr --filter`)
-
-**Example:** `"^src"`
-
----
-
-### `:report_exclude`
-
-Exclude source files matching this regular expression filter.
-(`gcovr --exclude`)
-
-**Example:** `"^vendor.*|^build.*|^test.*|^lib.*"`
-
----
-
-### `:gcov_filter`
-
-Keep only `.gcov` data files matching this regular expression filter.
-(`gcovr --gcov-filter`)
-
----
-
-### `:gcov_exclude`
-
-Exclude `.gcov` data files matching this regular expression filter.
-(`gcovr --gcov-exclude`)
-
----
-
-### `:exclude_directories`
-
-Exclude directories matching this regular expression filter when searching for
-raw coverage files. (`gcovr --exclude-directories`)
-
----
-
-### `:gcov_executable`
-
-Use a specific `gcov` executable instead of the one on `PATH`.
-(`gcovr --gcov-executable`)
-
----
-
-### `:exclude_unreachable_branches`
-
-Exclude branch coverage from lines without useful source code.
-(`gcovr --exclude-unreachable-branches`)
-
----
-
-### `:exclude_throw_branches`
-
-Exclude compiler-generated exception-handling branches from branch coverage.
-(`gcovr --exclude-throw-branches`)
-
----
-
-### `:merge_mode_function`
-
-Controls how `gcovr` handles multiple coverage entries for the same function
-(e.g. when Ceedling tests the same source under multiple build configurations).
-
-**Default:** `merge-use-line-max`
-
-See the [gcovr merging docs](https://gcovr.com/en/stable/guide/merging.html)
-for all valid values.
-
----
-
-### `:use_gcov_files`
-
-Use existing `.gcov` files on disk instead of running `gcov` again.
-(`gcovr --use-gcov-files`)
-
-**Default:** `FALSE`
-
----
-
-### `:gcov_ignore_parse_errors`
-
-Skip lines with parse errors in `.gcov` files rather than exiting with an
-error. (`gcovr --gcov-ignore-parse-errors`)
-
----
-
-### `:object_directory`
-
-Override normal working-directory detection for `.gcda` / `.gcno` files.
-(`gcovr --object-directory`)
-
----
-
-### `:keep`
-
-Retain intermediate `.gcov` files after processing. (`gcovr --keep`)
-
----
-
-### `:delete`
-
-Delete `.gcda` files after processing. (`gcovr --delete`)
-
----
-
-### `:threads`
-
-Number of parallel threads to use during report generation. (`gcovr -j`)
-
----
-
-### `:html_artifact_filename`
-
-Override the default HTML report output filename.
-
----
-
-### `:html_title`
-
-Title text for the HTML report. (`gcovr --html-title`)
-
-**Default:** `Head`
-
----
-
-### `:html_medium_threshold`
-
-Coverage percentage below which a value is marked as low coverage in the HTML
-report. Must be ≤ `:html_high_threshold`. (`gcovr --html-medium-threshold`)
-
-**Default:** `75.0`
-
----
-
-### `:html_high_threshold`
-
-Coverage percentage below which a value is marked as medium coverage in the
-HTML report. Must be ≥ `:html_medium_threshold`. (`gcovr --html-high-threshold`)
-
-**Default:** `90.0`
-
----
-
-### `:html_absolute_paths`
-
-Use absolute paths when linking to detailed reports in the HTML output.
-(`gcovr --html-absolute-paths`)
-
-**Default:** relative links
-
----
-
-### `:html_encoding`
-
-Override the declared character encoding in the HTML report.
-(`gcovr --html-encoding`)
-
-**Default:** `UTF-8`
-
----
-
-### `: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_artifact_filename`
-
-Override the default SonarQube XML report output filename.
-
----
-
-### `:json_pretty`
-
-Pretty-print the JSON report. (`gcovr --json-pretty`)
-
-**Default:** `FALSE`
-
----
-
-### `:json_artifact_filename`
-
-Override the default JSON report output filename.
-
----
-
-### `:text_artifact_filename`
-
-Override the default text report output filename. When unset the text report
-is printed to the console.
-
----
-
-## ReportGenerator Settings
-
-All options below live under `:gcov:` ↳ `:report_generator:`. Reports are
-written to `<build root>/artifacts/gcov/ReportGenerator/`.
-
-### `:history_directory`
-
-Optional directory for storing persistent coverage history, enabling
-coverage-trend charts across builds.
-
----
-
-### `:plugins`
-
-Optional semicolon-separated list of plugin DLL files for custom report types
-or custom history storage.
-
-**Example:** `plugin.dll;*.dll`
-
----
-
-### `:assembly_filters`
-
-Optional semicolon-separated list of assembly inclusion/exclusion filters.
-Prefix `+` to include, `-` to exclude. Exclusions take precedence. Wildcards
-allowed (not regular expressions).
-
-**Example:** `+MyLib;-ThirdParty`
-
----
-
-### `:class_filters`
-
-Optional semicolon-separated list of class inclusion/exclusion filters. Same
-prefix and wildcard rules as `:assembly_filters`.
-
----
-
-### `:file_filters`
-
-Optional semicolon-separated list of file inclusion/exclusion filters. Same
-prefix and wildcard rules as `:assembly_filters`.
-
-**Example:** `"-./vendor/*;-./build/*;-./test/*;+./src/*"`
-
----
-
-### `:verbosity`
-
-Verbosity level for ReportGenerator log output.
-
-**Values:** `Verbose`, `Info`, `Warning`, `Error`, `Off`
-
-**Default:** `Warning`
-
----
-
-### `:tag`
-
-Optional build tag or version label embedded in the report.
-
----
-
-### `:gcov_exclude`
-
-Optional list of regular expressions; `.gcov` notes files whose paths match
-are excluded from report generation.
-
-```yaml
-:gcov:
-  :report_generator:
-    :gcov_exclude:
-      - <regex>
-```
-
----
-
-### `:num_parallel_threads`
-
-Number of parallel threads to use during report generation. Drives both
-ReportGenerator's own `numberOfReportsParsedInParallel` and
-`numberOfReportsMergedInParallel` settings together.
-
-**Default:** unset (ReportGenerator's own default applies)
-
----
-
-### `:custom_args`
-
-Optional list of additional command-line arguments passed directly to
-ReportGenerator. 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).
-
-```yaml
-:gcov:
-  :report_generator:
-    :custom_args:
-      - <argument>
-```
-
-<br/><br/>