ceedling 0.29.1 → 0.30.0

data/plugins/fake_function_framework/src/fff_unity_helper.h

@@ -1,33 +1,33 @@
-#ifndef fff_unity_helper_H
-#define fff_unity_helper_H
-
-/*
-    FFF helper macros for Unity.
-*/
-
-/*
-    Fail if the function was not called the expected number of times.
-*/
-#define TEST_ASSERT_CALLED_TIMES(times_, function_)                         \
-    TEST_ASSERT_EQUAL_MESSAGE(times_,                                       \
-        function_ ## _fake.call_count,                                      \
-        "Function " #function_ " called the incorrect number of times.")
-/*
-    Fail if the function was not called exactly once.
-*/
-#define TEST_ASSERT_CALLED(function_) TEST_ASSERT_CALLED_TIMES(1, function_)
-
-/*
-    Fail if the function was called 1 or more times.
-*/
-#define TEST_ASSERT_NOT_CALLED(function_) TEST_ASSERT_CALLED_TIMES(0, function_)
-
-/*
-    Fail if the function was not called in this particular order.
-*/
-#define TEST_ASSERT_CALLED_IN_ORDER(order_, function_)                      \
-    TEST_ASSERT_EQUAL_PTR_MESSAGE((void *) function_,                       \
-        fff.call_history[order_],                                           \
-        "Function " #function_ " not called in order " #order_ )
-
+#ifndef fff_unity_helper_H
+#define fff_unity_helper_H
+
+/*
+    FFF helper macros for Unity.
+*/
+
+/*
+    Fail if the function was not called the expected number of times.
+*/
+#define TEST_ASSERT_CALLED_TIMES(times_, function_)                         \
+    TEST_ASSERT_EQUAL_MESSAGE(times_,                                       \
+        function_ ## _fake.call_count,                                      \
+        "Function " #function_ " called the incorrect number of times.")
+/*
+    Fail if the function was not called exactly once.
+*/
+#define TEST_ASSERT_CALLED(function_) TEST_ASSERT_CALLED_TIMES(1, function_)
+
+/*
+    Fail if the function was called 1 or more times.
+*/
+#define TEST_ASSERT_NOT_CALLED(function_) TEST_ASSERT_CALLED_TIMES(0, function_)
+
+/*
+    Fail if the function was not called in this particular order.
+*/
+#define TEST_ASSERT_CALLED_IN_ORDER(order_, function_)                      \
+    TEST_ASSERT_EQUAL_PTR_MESSAGE((void *) function_,                       \
+        fff.call_history[order_],                                           \
+        "Function " #function_ " not called in order " #order_ )
+
 #endif

data/plugins/gcov/README.md

@@ -1,101 +1,412 @@
-ceedling-gcov
-=============
-
-# Plugin Overview
-
-Plugin for integrating GNU GCov code coverage tool into Ceedling projects.
-Currently only designed for the gcov command (like LCOV for example). In the
-future we could configure this to work with other code coverage tools.
-
-This plugin currently uses `gcovr` to generate HTML and/or XML reports as a
-utility. The normal gcov plugin _must_ be run first for this report to generate.
-
-## Installation
-
-Gcovr can be installed via pip like so:
-
-```
-pip install gcovr
-```
-
-## Configuration
-
-The gcov plugin supports configuration options via your `project.yml` provided
-by Ceedling.
-
-Generation of HTML reports may be enabled or disabled with the following
-config. Set to `true` to enable or set to `false` to disable.
-
-```
-:gcov:
-  :html_report: true
-```
-
-Generation of XML reports may be enabled or disabled with the following
-config. Set to `true` to enable or set to `false` to disable.
-
-```
-:gcov:
-  :xml_report: true
-```
-
-There are two types of gcovr HTML reports that can be configured in your
-`project.yml`. To create a basic HTML report, with only the overall file
-information, use the following config.
-
-```
-:gcov:
-  :html_report_type: basic
-```
-
-To create a detailed HTML report, with line by line breakdown of the
-coverage, use the following config.
-
-```
-:gcov:
-  :html_report_type: detailed
-```
-
-There are a number of options to control which files are considered part of
-the coverage report. Most often, we only care about coverage on our source code, and not
-on tests or automatically generated mocks, runners, etc. However, there are times 
-where this isn't true... or there are times where we've moved ceedling's directory 
-structure so that the project file isn't at the root of the project anymore. In these
-cases, you may need to tweak the following:
-
-```
-:gcov:
-  :report_root: "."
-  :report_exclude: "^build|^vendor|^test|^support"
-  :report_include: "^src"
-```
-
-One important note about html_report_root: gcovr will only take a single root folder, unlike 
-Ceedling's ability to take as many as you like. So you will need to choose a folder which is 
-a superset of ALL the folders you want, and then use the include or exclude options to set up
-patterns of files to pay attention to or ignore. It's not ideal, but it works.
-
-Finally, there are a number of settings which can be specified in order to adjust the
-default behaviors of gcov:
-
-```
-:gcov:
-  :html_medium_threshold: 75
-  :html_high_threshold: 90
-  :fail_under_line: 30
-  :fail_under_branch: 30
-```
-
-These HTML and XML reports will be found in `build/artifacts/gcov`.
-
-## Example Usage
-
-```
-ceedling gcov:all utils:gcov
-```
-
-## To-Do list
-
-- Generate overall report (combined statistics from all files with coverage)
-- Generate coverage output files
-- Easier option override for better customisation 
+ceedling-gcov
+=============
+
+# Plugin Overview
+
+Plugin for integrating GNU GCov code coverage tool into Ceedling projects.
+Currently only designed for the gcov command (like LCOV for example). In the
+future we could configure this to work with other code coverage tools.
+
+This plugin currently uses [gcovr](https://www.gcovr.com/) and / or
+[ReportGenerator](https://danielpalme.github.io/ReportGenerator/)
+as utilities to generate HTML, XML, JSON, or Text reports. The normal gcov
+plugin _must_ be run first for these reports to generate.
+
+## Installation
+
+gcovr can be installed via pip like so:
+
+```sh
+pip install gcovr
+```
+
+ReportGenerator can be installed via .NET Core like so:
+
+```sh
+dotnet tool install -g dotnet-reportgenerator-globaltool
+```
+
+It is not required to install both `gcovr` and `ReportGenerator`. Either utility
+may be installed to create reports.
+
+## Configuration
+
+The gcov plugin supports configuration options via your `project.yml` provided
+by Ceedling.
+
+### Utilities
+
+Gcovr and / or ReportGenerator may be enabled to create coverage reports.
+
+```yaml
+:gcov:
+  :utilities:
+    - gcovr           # Use gcovr to create the specified reports (default).
+    - ReportGenerator # Use ReportGenerator to create the specified reports.
+```
+
+### Reports
+
+Various reports are available and may be enabled with the following
+configuration item. See the specific report sections in this README
+for additional options and information. All generated reports will be found in `build/artifacts/gcov`.
+
+```yaml
+:gcov:
+  # Specify one or more reports to generate.
+  # Defaults to HtmlBasic.
+  :reports:
+    # Make an HTML summary report.
+    # Supported utilities: gcovr, ReportGenerator
+    - HtmlBasic
+
+    # Make an HTML report with line by line coverage of each source file.
+    # Supported utilities: gcovr, ReportGenerator
+    - HtmlDetailed
+
+    # Make 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
+
+    # Make a Cobertura XML report.
+    # Supported utilities: gcovr, ReportGenerator
+    - Cobertura
+
+    # Make a SonarQube XML report.
+    # Supported utilities: gcovr, ReportGenerator
+    - SonarQube
+
+    # Make a JSON report.
+    # Supported utilities: gcovr
+    - JSON
+
+    # Make a detailed HTML report with CSS and JavaScript included in every HTML page. Useful for build servers.
+    # Supported utilities: ReportGenerator
+    - HtmlInline
+
+    # Make a detailed HTML report with a light theme and CSS and JavaScript included in every HTML page for Azure DevOps.
+    # Supported utilities: ReportGenerator
+    - HtmlInlineAzure
+
+    # Make a detailed HTML report with a dark theme and CSS and JavaScript included in every HTML page for Azure DevOps.
+    # Supported utilities: ReportGenerator
+    - HtmlInlineAzureDark
+
+    # Make a single HTML file containing a chart with historic coverage information.
+    # Supported utilities: ReportGenerator
+    - HtmlChart
+
+    # Make a detailed HTML report in a single file.
+    # Supported utilities: ReportGenerator
+    - MHtml
+
+    # Make SVG and PNG files that show line and / or branch coverage information.
+    # Supported utilities: ReportGenerator
+    - Badges
+
+    # Make a single CSV file containing coverage information per file.
+    # Supported utilities: ReportGenerator
+    - CsvSummary
+
+    # Make a single TEX file containing a summary for all files and detailed reports for each files.
+    # Supported utilities: ReportGenerator
+    - Latex
+
+    # Make a single TEX file containing a summary for all files.
+    # Supported utilities: ReportGenerator
+    - LatexSummary
+
+    # Make 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
+
+    # Make a text file in lcov format.
+    # Supported utilities: ReportGenerator
+    - lcov
+
+    # Make a XML file containing a summary for all classes and detailed reports for each class.
+    # Supported utilities: ReportGenerator
+    - Xml
+
+    # Make a single XML file containing a summary for all files.
+    # Supported utilities: ReportGenerator
+    - XmlSummary
+```
+
+### Gcovr HTML Reports
+
+Generation of Gcovr HTML reports may be modified with the following configuration items.
+
+```yaml
+:gcov:
+  # Set to 'true' to enable HTML reports or set to 'false' to disable.
+  # Defaults to enabled. (gcovr --html)
+  # Deprecated - See the :reports: configuration option.
+  :html_report: [true|false]
+
+  # Gcovr supports generating two types of HTML reports. Use 'basic' to create
+  # an HTML report with only the overall file information. Use 'detailed' to create
+  # an HTML report with line by line coverage of each source file.
+  # Defaults to 'basic'. Set to 'detailed' for (gcovr --html-details).
+  # Deprecated - See the :reports: configuration option.
+  :html_report_type: [basic|detailed]
+
+
+  :gcovr:
+    # HTML report filename.
+    :html_artifact_filename: <output>
+
+    # 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:
+  # Set to 'true' to enable Cobertura XML reports or set to 'false' to disable.
+  # Defaults to disabled. (gcovr --xml)
+  # Deprecated - See the :reports: configuration option.
+  :xml_report: [true|false]
+
+
+  :gcovr:
+    # Set to 'true' to pretty-print the Cobertura XML report, otherwise set to 'false'.
+    # Defaults to disabled. (gcovr --xml-pretty)
+    :xml_pretty: [true|false]
+    :cobertura_pretty: [true|false]
+
+    # Cobertura XML report filename.
+    :xml_artifact_filename: <output>
+    :cobertura_artifact_filename: <output>
+```
+
+### SonarQube XML Reports
+
+Generation of SonarQube XML reports may be modified with the following configuration items.
+
+```yaml
+:gcov:
+  :gcovr:
+    # SonarQube XML report filename.
+    :sonarqube_artifact_filename: <output>
+```
+
+### 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]
+
+    # JSON report filename.
+    :json_artifact_filename: <output>
+```
+
+### 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:
+    # Text report filename.
+    # The text report is printed to the console when no filename is provided.
+    :text_artifact_filename: <output>
+```
+
+### Common Report Options
+
+There are a number of options to control which files are considered part of
+the coverage report. Most often, we only care about coverage on our source code, and not
+on tests or automatically generated mocks, runners, etc. However, there are times
+where this isn't true... or there are times where we've moved ceedling's directory
+structure so that the project file isn't at the root of the project anymore. In these
+cases, you may need to tweak `report_include`, `report_exclude`, and `exclude_directories`.
+
+One important note about `report_root`: gcovr will take only a single root folder, unlike
+Ceedling's ability to take as many as you like. So you will need to choose a folder which is
+a superset of ALL the folders you want, and then use the include or exclude options to set up
+patterns of files to pay attention to or ignore. It's not ideal, but it works.
+
+Finally, there are a number of settings which can be specified to adjust the
+default behaviors of gcovr:
+
+```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.
+    :report_root: "."
+
+    # Load the specified configuration file.
+    # Defaults to gcovr.cfg in the report_root directory. (gcovr --config)
+    :config_file: <config_file>
+
+    # Exit with a status of 2 if the total line coverage is less than MIN.
+    # Can be ORed with exit status of 'fail_under_branch' option. (gcovr --fail-under-line)
+    :fail_under_line: 30
+
+    # Exit with a status of 4 if the total branch coverage is less than MIN.
+    # Can be ORed with exit status of 'fail_under_line' option. (gcovr --fail-under-branch)
+    :fail_under_branch: 30
+
+    # Select the source file encoding.
+    # Defaults to the system default encoding (UTF-8). (gcovr --source-encoding)
+    :source_encoding: <source_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).
+    :report_include: "^src"
+
+    # Exclude source files that match this filter. (gcovr --exclude).
+    :report_exclude: "^vendor.*|^build.*|^test.*|^lib.*"
+
+    # Keep only gcov data files that match this filter. (gcovr --gcov-filter).
+    :gcov_filter: <gcov_filter>
+
+    # Exclude gcov data files that match this filter. (gcovr --gcov-exclude).
+    :gcov_exclude: <gcov_exclude>
+
+    # Exclude directories that match this regex while searching
+    # raw coverage files. (gcovr --exclude-directories).
+    :exclude_directories: <exclude_dirs>
+
+    # Use a particular gcov executable. (gcovr --gcov-executable).
+    :gcov_executable: <gcov_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]
+
+    # 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: <objdir>
+
+    # 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).
+    :num_parallel_threads: <num_threads>
+
+  # When scanning the code coverage, if any files are found that do not have
+  # associated coverage data, the command will abort with an error message.
+  :abort_on_uncovered: true
+
+  # When using the ``abort_on_uncovered`` option, the files in this list will not
+  # trigger a failure.
+  :uncovered_ignore_list: []
+```
+
+### ReportGenerator Configuration
+
+The ReportGenerator utility may be configured with the following configuration items.
+All generated reports may be found in `build/artifacts/gcov/ReportGenerator`.
+
+```yaml
+:gcov:
+  :report_generator:
+    # Optional directory for storing persistent coverage information.
+    # Can be used in future reports to show coverage evolution.
+    :history_directory: <history_directory>
+
+    # Optional plugin files for custom reports or custom history storage (separated by semicolon).
+    :plugins: CustomReports.dll
+
+    # 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.
+    :assembly_filters: "+Included;-Excluded"
+
+    # 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.
+    :class_filters: "+Included;-Excluded"
+
+    # Optional list of files 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.
+    :file_filters: "-./vendor/*;-./build/*;-./test/*;-./lib/*;+./src/*"
+
+    # The verbosity level of the log messages.
+    # Values: Verbose, Info, Warning, Error, Off
+    :verbosity: Warning
+
+    # Optional tag or build version.
+    :tag: <tag>
+```
+
+## Example Usage
+
+```sh
+ceedling gcov:all utils:gcov
+```
+
+## To-Do list
+
+- Generate overall report (combined statistics from all files with coverage)
+
+## Citations
+
+Most of the comment text which describes the options was taken from the
+[Gcovr User Guide](https://www.gcovr.com/en/stable/guide.html) and the
+[ReportGenerator Wiki](https://github.com/danielpalme/ReportGenerator/wiki).
+The text is repeated here to provide the most accurate option functionality.