ceedling 1.0.1 → 1.1.0

data/{plugins/fff/README.md → docs/mkdocs/plugins/fff.md}

@@ -1,35 +1,29 @@
-# A Fake Function Framework Plug-in for Ceedling
+# Fake Function Framework for Ceedling
 
-This is a plug-in for [Ceedling](https://github.com/ThrowTheSwitch/Ceedling) to use the [Fake Function Framework](https://github.com/meekrosoft/fff) for mocking instead of CMock.
+This plugin causes Ceedling to use the [Fake Function Framework](https://github.com/meekrosoft/fff) for mocking instead of CMock, the default mocking framework packaged with Ceedling.
 
-Using _fff_ provides less strict mocking than CMock, and can allow for more loosely-coupled tests.
+Using _FFF_ provides less strict mocking than CMock and affords more loosely-coupled tests.
 
-This Ceedling 1.x plugin wraps a snapshot of _FFF_, version 0.1.1.
+This Ceedling 1.x plugin incorporates a snapshot of _FFF_ version 0.1.1 and supersedes a separately available [FFF Ceedling plugin project](https://github.com/ElectronVector/fake_function_framework). The built-in _FFF_ plugin that now comes with Ceedling was derived from the ElectronVector project and is now maintained along with Ceedling and tracks its updates.
 
-### Thanks
+!!! note "Special thanks to Matt Chernosky"
+    [Matt Chernosky](http://www.electronvector.com) originally developed this plugin 
+    as an adapter for _FFF_. It's a well-loved piece of the Ceedling ecosystem,
+    and we really appreciate his support through the years.
 
-A special thanks to [Matt Chernosky](http://www.electronvector.com) for developing this plugin originally. It's a well-loved piece of the Ceedling 
-ecosystem and we really appreciate his support through the years.
+## Enable the plugin
 
-### Enable the plug-in.
-
-The plug-in is enabled from within your project.yml file.
+The plugin is enabled from within your project.yml file.
 
 In the `:plugins` configuration, add `fff` to the list of enabled plugins:
 
 ```yaml
 :plugins:
-  :load_paths:
-    - vendor/ceedling/plugins
   :enabled:
-    - report_tests_pretty_stdout
-    - module_generator
     - fff
 ```
-*Note that you could put the plugin source in some other loaction.
-In that case you'd need to add a new path the `:load_paths`.*
 
-## How to use it
+## How to use
 
 You use fff with Ceedling the same way you used to use CMock.
 
@@ -77,7 +71,7 @@ test_whenThePowerReadingIsLessThan5_thenTheStatusLedIsNotTurnedOn(void)
 }
 ```
 
-## Test that a single function was called with the correct argument
+### Test that a single function was called with the correct argument
 
 ```c
 void
@@ -92,7 +86,7 @@ test_whenTheVolumeKnobIsMaxed_thenVolumeDisplayIsSetTo11(void)
 }
 ```
 
-## Test that calls are made in a particular sequence
+### Test that calls are made in a particular sequence
 
 ```c
 void
@@ -110,7 +104,7 @@ test_whenTheModeSelectButtonIsPressed_thenTheDisplayModeIsCycled(void)
 }
 ```
 
-## Fake a return value from a function
+### Fake a return value from a function
 
 ```c
 void
@@ -127,7 +121,7 @@ test_givenTheDisplayHasAnError_whenTheDeviceIsPoweredOn_thenTheDisplayIsPoweredD
 }
 ```
 
-## Fake a function with a value returned by reference
+### Fake a function with a value returned by reference
 
 ```c
 void
@@ -152,9 +146,9 @@ test_givenTheUserHasTypedSleep_whenItIsTimeToCheckTheKeyboard_theDisplayIsPowere
 }
 ```
 
-## Fake a function with a function pointer parameter
+### Fake a function with a function pointer parameter
 
-```
+```c
 void
 test_givenNewDataIsAvailable_whenTheDisplayHasUpdated_thenTheEventIsComplete(void)
 {
@@ -209,34 +203,45 @@ test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
 
 ## Test setup
 
-All of the fake functions, and any fff global state are all reset automatically between each test.
+All of the fake functions and any fff global state are all reset automatically between each test.
 
 ## CMock configuration
 
-Use still use some of the CMock configuration options for setting things like the mock prefix, and for including additional header files in the mock files.
+We still use some CMock configuration options for setting things like the mock prefix and for including additional header files in the mock files.
 
 ```yaml
 :cmock:
     :mock_prefix: mock_
         :includes:
-            -
+            - ...
         :includes_h_pre_orig_header:
-            -
+            - ...
         :includes_h_post_orig_header:
-            -
+            - ...
         :includes_c_pre_header:
-            -
+            - ...
         :includes_c_post_header:
 ```
 
-## Running the tests
+## FFF examples
+
+See the [FFF example project][fff-example-project]. This project illustrates how to use the plugin with full-size examples.
+
+!!! warning "Versioning"
+    The example project link is to the latest in the repository.
+    It is not explicitly versioned to correspond to this documentation.
+    That said, FFF and the plugin are relatively stable.
+
+### Running example tests
+
+Unit and integration tests exist for the plugin itself.
+
+These tests are run with the default `rake` task packaged in the [FFF plugin][fff-plugin].
 
-There are unit and integration tests for the plug-in itself.
-These are run with the default `rake` task.
-The integration test runs the tests for the example project in examples/fff_example.
-For the integration tests to succeed, this repository must be placed in a Ceedling tree in the plugins folder.
+The integration test runs the FFF-based unit tests within the [example project][fff-example-project].
+That is, the FFF examples are executed as part of Ceedling continuous integration.
 
-## More examples
+[fff-example-project]: https://github.com/ThrowTheSwitch/Ceedling/tree/master/plugins/fff/examples/fff_example
+[fff-plugin]:          https://github.com/ThrowTheSwitch/Ceedling/tree/master/plugins/fff
 
-There is an example project in examples/fff_example.
-It shows how to use the plug-in with some full-size examples.
+<br/><br/>

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

@@ -0,0 +1,92 @@
+# Example Usage
+
+!!! note
+    Unless disabled, basic coverage summaries are always printed to the 
+    console regardless of report generation options.
+
+## Automatic report generation (default)
+
+If coverage report generation is configured, the plugin defaults to running 
+reports after any `gcov:` task.
+
+```yaml
+:plugins:
+  :enabled:
+    - gcov
+
+:gcov:
+  :utilities:
+    - gcovr            # Enabled by default -- shown for completeness
+  :report_task: FALSE  # Disabled by default -- shown for completeness
+  :reports:            # See later section for report configuration
+    - HtmlBasic
+
+  ...                  # Further configuration for reporting (not shown)
+
+```
+
+```shell
+ > ceedling gcov:all
+```
+
+## Report generation manual task
+
+If the `:report_task:` configuration option is enabled, reports are not 
+automatically generaed after test suite coverage builds. Instead, report 
+generation is triggered by the `report:gcov` task.
+
+```yaml
+:plugins:
+  :enabled:
+    - gcov
+
+:gcov:
+  :utilities:
+    - gcovr            # Enabled by default -- shown for completeness
+  :report_task: TRUE
+  :reports:            # See later section for report configuration
+    - HtmlBasic        # Enabled by default -- shown for completeness
+
+  ...                  # Further configuration for reporting (not shown)
+
+```
+
+With the separate reporting task enabled, it can be used like any other Ceedling task.
+
+```shell
+ > ceedling gcov:all report:gcov
+```
+
+or 
+
+```shell
+ > ceedling gcov:all
+
+ > ceedling report:gcov
+```
+
+## Full report generation
+
+```yaml
+:plugins:
+  :enabled:
+    - gcov
+
+:gcov:
+  :summaries: FALSE              # Simple coverage summaries to console disabled
+  :reports:                      # `gcovr` tool enabled by default
+    - HtmlDetailed
+    - Text
+    - Cobertura
+  :gcovr:                        # `gcovr` common and report-specific options
+    :report_root: "../../"       # Atypical layout -- project.yml is inside a subdirectoy below <build root>
+    :sort_percentage: TRUE
+    :sort_uncovered: FALSE
+    :html_medium_threshold: 60
+    :html_high_threshold: 85
+    :print_summary: TRUE
+    :threads: 4
+    :keep: FALSE
+```
+
+<br/><br/>

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

@@ -0,0 +1,251 @@
+# GCovr Configuration
+
+All reports generated by `gcovr` are found in `<build root>/artifacts/gcov/gcovr/`.
+
+## HTML reports
+
+Generation of HTML reports may be modified with the following configuration items.
+
+```yaml
+:gcov:
+  :gcovr:
+    # HTML report filename.
+    :html_artifact_filename: <filename>
+
+    # Use 'title' as title for the HTML report.
+    # Default is 'Head'. (gcovr --html-title)
+    :html_title: <title>
+
+    # If the coverage is below MEDIUM, the value is marked as low coverage in the HTML report.
+    # MEDIUM has to be lower than or equal to value of html_high_threshold.
+    # If MEDIUM is equal to value of html_high_threshold the report has only high and low coverage.
+    # Default is 75.0. (gcovr --html-medium-threshold)
+    :html_medium_threshold: 75
+
+    # If the coverage is below HIGH, the value is marked as medium coverage in the HTML report.
+    # HIGH has to be greater than or equal to value of html_medium_threshold.
+    # If HIGH is equal to value of html_medium_threshold the report has only high and low coverage.
+    # Default is 90.0. (gcovr -html-high-threshold)
+    :html_high_threshold: 90
+
+    # Set to 'true' to use absolute paths to link the 'detailed' reports.
+    # Defaults to relative links. (gcovr --html-absolute-paths)
+    :html_absolute_paths: <true|false>
+
+    # Override the declared HTML report encoding. Defaults to UTF-8. (gcovr --html-encoding)
+    :html_encoding: <html_encoding>
+```
+
+## Cobertura XML reports
+
+Generation of Cobertura XML reports may be modified with the following configuration items.
+
+```yaml
+:gcov:
+  :gcovr:
+    # Set to 'true' to pretty-print the Cobertura XML report, otherwise set to 'false'.
+    # Defaults to disabled. (gcovr --xml-pretty)
+    :cobertura_pretty: <true|false>
+
+    # Override default Cobertura XML report filename.
+    :cobertura_artifact_filename: <filename>
+```
+
+## SonarQube XML reports
+
+Generation of SonarQube XML reports may be modified with the following configuration items.
+
+```yaml
+:gcov:
+  :gcovr:
+    # Override default SonarQube XML report filename.
+    :sonarqube_artifact_filename: <filename>
+```
+
+## JSON reports
+
+Generation of JSON reports may be modified with the following configuration items.
+
+```yaml
+:gcov:
+  :gcovr:
+    # Set to 'true' to pretty-print the JSON report, otherwise set 'false'.
+    # Defaults to disabled. (gcovr --json-pretty)
+    :json_pretty: <true|false>
+
+    # Override default JSON report filename.
+    :json_artifact_filename: <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.
+
+```yaml
+:gcov:
+  :gcovr:
+    # Override default text report filename.
+    :text_artifact_filename: <filename>
+```
+
+## Common GCovr options
+
+A number of options exist to control which files are considered part of a 
+coverage report. This Ceedling gcov plugin itself handles the most important 
+aspect — only source files under test are compiled with coverage. Tests, mocks,
+and test runners, are not compiled with coverage.
+
+!!! note "`gcovr` accepts only one report root path"
+    `gcovr` will only accept a single path for `:report_root`. In typical usage,
+    this is of no concern as it is handled automatically. In unusual project
+    layouts, you may need to specify a folder that encompasses _all_ build folders
+    containing coverage result files and optionally, selectively exclude patterns
+    of paths or files. For instance, if your Ceedling project file is not at the
+    root of your project, you may need set `:report_root` as well as
+    `:report_exclude` and `:exclude_directories`.
+
+!!! note "Using a gcovr configuration file"
+    When `:config_file:` is set, Ceedling passes only `--root` and `--config`
+    to gcovr and defers all other settings to that file. This prevents Ceedling
+    from overriding config file values with its CLI arguments. Only `:report_root:`
+    is still applied because Ceedling may invoke gcovr from a different working
+    directory than your project root.
+
+    To preserve the plugin's default filtering of test and build files, include
+    equivalent exclusion patterns in your gcovr config file (adjust for your
+    project's `:test_file_prefix`, test paths, and `:build_root` settings):
+
+    ```ini
+    [gcovr]
+    exclude = .*test.*/test_.+\.c$
+    exclude = .*build/.+\.c$
+    ```
+
+```yaml
+:gcov:
+  :gcovr:
+    # The root directory of your source files. Defaults to ".", the current directory.
+    # File names are reported relative to this root. The report_root is the default report_include.
+    # Default if unspecified: "."
+    :report_root: <path>
+
+    # Load the specified configuration file. (gcovr --config)
+    # Defaults to gcovr.cfg in the report_root directory if that file exists.
+    #
+    # 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. Only
+    # :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 the following
+    # patterns in your config file (adjust paths to match your project's
+    # :test_file_prefix, test paths, and :build_root settings):
+    #
+    #   [gcovr]
+    #   exclude = .*test.*/test_.+\.c$
+    #   exclude = .*build/.+\.c$
+    :config_file: <config_file>
+
+    # Exit with a status of 2 if the total line coverage is less than MIN percentage.
+    # Can be ORed with exit status of other fail options. (gcovr --fail-under-line)
+    :fail_under_line: <1-100>
+
+    # Exit with a status of 4 if the total branch coverage is less than MIN percentage.
+    # Can be ORed with exit status of other fail options. (gcovr --fail-under-branch)
+    :fail_under_branch: <1-100>
+
+    # Exit with a status of 8 if the total decision coverage is less than MIN percentage.
+    # Can be ORed with exit status of other fail options. (gcovr --fail-under-decision)
+    :fail_under_decision: <1-100>
+
+    # Exit with a status of 16 if the total function coverage is less than MIN percentage.
+    # Can be ORed with exit status of other fail options. (gcovr --fail-under-function)
+    :fail_under_function: <1-100>
+
+    # If the fail options above are set, specify whether those conditions should break a build.
+    # The default option is false and simply logs a warning without breaking the build.
+    :exception_on_fail: <true|false>
+
+    # Select the source file encoding.
+    # Defaults to the system default encoding (UTF-8). (gcovr --source-encoding)
+    :source_encoding: <encoding>
+
+    # Report the branch coverage instead of the line coverage. For text report only. (gcovr --branches).
+    :branches: <true|false>
+
+    # Sort entries by increasing number of uncovered lines.
+    # For text and HTML report. (gcovr --sort-uncovered)
+    :sort_uncovered: <true|false>
+
+    # Sort entries by increasing percentage of uncovered lines.
+    # For text and HTML report. (gcovr --sort-percentage)
+    :sort_percentage: <true|false>
+
+    # Print a small report to stdout with line & branch percentage coverage.
+    # This is in addition to other reports. (gcovr --print-summary).
+    :print_summary: <true|false>
+
+    # Keep only source files that match this filter. (gcovr --filter).
+    # Filters are regular expressions (ex: "^src")
+    :report_include: <filter>
+
+    # Exclude source files that match this filter. (gcovr --exclude).
+    # Filters are regular expressions (ex: "^vendor.*|^build.*|^test.*|^lib.*")
+    :report_exclude: <filter>
+
+    # Keep only gcov data files that match this filter. (gcovr --gcov-filter).
+    # Filters are regular expressions
+    :gcov_filter: <filter>
+
+    # Exclude gcov data files that match this filter. (gcovr --gcov-exclude).
+    # Filters are regular expressions
+    :gcov_exclude: <filter>
+
+    # Exclude directories that match this filter while searching 
+    # raw coverage files. (gcovr --exclude-directories).
+    # Filters are regular expressions
+    :exclude_directories: <filters>
+
+    # Use a particular gcov executable. (gcovr --gcov-executable).
+    # (This may be appropriate and necessary in special circumstances.
+    #  Please review Ceedling's options for modifying tools first.)
+    :gcov_executable: <cmd>
+
+    # Exclude branch coverage from lines without useful
+    # source code. (gcovr --exclude-unreachable-branches).
+    :exclude_unreachable_branches: <true|false>
+
+    # For branch coverage, exclude branches that the compiler
+    # generates for exception handling. (gcovr --exclude-throw-branches).
+    :exclude_throw_branches: <true|false>
+
+    # 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 bad.
+    # Default value for Gcov plugin is 'merge-use-line-max'. See Gcovr docs for more.
+    # https://gcovr.com/en/stable/guide/merging.html
+    :merge_mode_function: <...>
+
+    # Use existing gcov files for analysis. Default: False. (gcovr --use-gcov-files)
+    :use_gcov_files: <true|false>
+
+    # Skip lines with parse errors in GCOV files instead of
+    # exiting with an error. (gcovr --gcov-ignore-parse-errors).
+    :gcov_ignore_parse_errors: <true|false>
+
+    # Override normal working directory detection. (gcovr --object-directory)
+    :object_directory: <path>
+
+    # Keep gcov files after processing. (gcovr --keep).
+    :keep: <true|false>
+
+    # Delete gcda files after processing. (gcovr --delete).
+    :delete: <true|false>
+
+    # Set the number of threads to use in parallel. (gcovr -j).
+    :threads: <count>
+```
+
+<br/><br/>

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

@@ -0,0 +1,68 @@
+# 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.
+
+<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/>