move ceedling tests to test/unit-test
This commit is contained in:
hathach
433
test/unit-test/vendor/ceedling/plugins/gcov/README.md
vendored
Normal file
433
test/unit-test/vendor/ceedling/plugins/gcov/README.md
vendored
Normal file
@@ -0,0 +1,433 @@
|
||||
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.
|
||||
# Ceedling globs described in the Ceedling packet ``Path`` section can be used
|
||||
# when directories are placed on the list. Globs are limited to matching directories
|
||||
# and not files.
|
||||
: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>
|
||||
|
||||
# Optional list of one or more regular expressions to exclude gcov notes files that match these filters.
|
||||
:gcov_exclude:
|
||||
- <exclude_regex1>
|
||||
- <exclude_regex2>
|
||||
|
||||
# Optionally use a particular gcov executable. Defaults to gcov.
|
||||
:gcov_executable: <gcov_cmd>
|
||||
|
||||
# Optionally set the number of threads to use in parallel. Defaults to 1.
|
||||
:num_parallel_threads: <num_threads>
|
||||
|
||||
# Optional list of one or more command line arguments to pass to Report Generator.
|
||||
# Useful for configuring Risk Hotspots and Other Settings.
|
||||
# https://github.com/danielpalme/ReportGenerator/wiki/Settings
|
||||
:custom_args:
|
||||
- <custom_arg1>
|
||||
- <custom_arg2>
|
||||
```
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user