This CiBuildPlugin scans all the files in a given package and checks for coding standard compliance issues.
This plugin is enabled by default. If a package would like to prevent the plugin from reporting errors, it can do
so by enabling
This plugin requires the directory containing the Uncrustify executable that should be used for this plugin to
be specified in an environment variable named
UNCRUSTIFY_CI_PATH. This unique variable name is used to avoid confusion
with other paths to Uncrustify which might not be the expected build for use by this plugin.
By default, an Uncrustify configuration file named "uncrustify.cfg" located in the same directory as the plugin is
used. The value can be overridden to a package-specific path with the
ConfigFilePath configuration file option.
- Uncrustify source code and documentation: https://github.com/uncrustify/uncrustify
- Project Mu Uncrustify fork source code and documentation: https://dev.azure.com/projectmu/Uncrustify
Files Checked in a Package¶
By default, this plugin will discover all files in the package with the following default paths:
# C source
From this list of files, any files ignored by Git or residing in a Git submodule will be removed. If Git is not found, submodules are not found, or ignored files are not found no changes are made to the list of discovered files.
To control the paths checked in a given package, review the configuration options described in this file.
The plugin can be configured with a few optional configuration options.
"AdditionalIncludePaths": , # Additional paths to check formatting (wildcards supported).
"AuditOnly": False, # Don't fail the build if there are errors. Just log them.
"ConfigFilePath": "", # Custom path to an Uncrustify config file.
"IgnoreFiles": , # A list of file patterns to ignore.
"IgnoreStandardPaths": , # Standard Plugin defined paths that should be ignored.
"OutputFileDiffs": True, # Output chunks of formatting diffs in the test case log.
# This can significantly slow down the plugin on very large packages.
"SkipGitExclusions": False # Don't exclude git ignored files and files in git submodules.
A package configuration file can specify any additional paths to be included with this option.
At this time, it is recommended all files run against the plugin be written in the C or C++ language.
Boolean - Default is
True, run the test in an "audit only mode" which will log all errors but instead of failing the build, it will set
the test as skipped. This allows visibility into the failures without breaking the build.
String - Default is
When specified in the config file, this is a package relative path to the Uncrustify configuration file.
This option supports .gitignore file and folder matching strings including wildcards.
The files specified by this configuration option will not be processed by Uncrustify.
This plugin by default will check the below standard paths. A package configuration file can specify any of these paths to be ignored.
# C source
Boolean - Default is
True, output diffs of formatting changes into the test case log. This is helpful to exactly understand what changes
need to be made to the source code in order to fix a coding standard compliance issue.
Note that calculating the file diffs on a very large set of of results (e.g. >100 files) can significantly slow down plugin execution.
Boolean - Default is
By default, files in paths matched in a .gitignore file or a recognized git submodule are excluded. If this option
True, the plugin will not attempt to recognize these files and exclude them.
MU_CHANGE - Feature added.
Mu adds support for passing this parameter on the command line when running
stuart_ci_build. If passed, it will
cause any changes to be made in-place to the files in the workspace, enabling the caller to easily format any failing
code before submitting a PR.
While this can also be set as an environment variable, it is recommended to only use it as a CLI paramter.
NOTE: This is not an option in the config
yaml. It is an option passed directly into the tool.
High-Level Plugin Operation¶
This plugin generates two main sets of temporary files:
- A working directory in the directory
- For each source file with formatting errors, a sibling file with the
The working directory contains temporary files unique to operation of the plugin. All of these files are removed on
exit of the plugin including successful or unsuccessful execution (such as a Python exception occurring). If for any
reason, any files in the package exist prior to running the plugin with the
.uncrustify_plugin extension, the plugin
will inform the user to remove these files and exit before running Uncrustify. This is to ensure the accuracy of the
results reported from each execution instance of the plugin.
The plugin determines the list of relevant files to check with Uncrustify and then invokes Uncrustify with that file
list. For any files not compliant to the configuration file provided, Uncrustify will generate a corresponding file
.uncrustify_plugin extension. The plugin discovers all of these files. If any such files are present, this
indicates a formatting issue was found and the test is marked failed (unless
AuditOnly mode is enabled).
The test case log will contain a report of which files failed to format properly, allowing the user to run Uncrustify
against the file locally to fix the issue. If the
OutputFileDiffs configuration option is set to
True, the plugin
will output diff chunks for all code formatting issues in the test case log.