audk/.pytool/Plugin/UncrustifyCheck/Readme.md

UncrustifyCheck Plugin

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 AuditOnly mode.

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
"*.c",
"*.h"
]

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.

Configuration

The plugin can be configured with a few optional configuration options.

  "UncrustifyCheck": {
      "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.
  }

AdditionalIncludePaths

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.

AuditOnly

Boolean - Default is False.

If 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.

ConfigFilePath

String - Default is "uncrustify.cfg"

When specified in the config file, this is a package relative path to the Uncrustify configuration file.

IgnoreFiles

This option supports .gitignore file and folder matching strings including wildcards.

The files specified by this configuration option will not be processed by Uncrustify.

IgnoreStandardPaths

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
"*.c",
"*.h"
]

OutputFileDiffs

Boolean - Default is True.

If 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.

SkipGitExclusions

Boolean - Default is False.

By default, files in paths matched in a .gitignore file or a recognized git submodule are excluded. If this option is True, the plugin will not attempt to recognize these files and exclude them.

High-Level Plugin Operation

This plugin generates two main sets of temporary files:

1. A working directory in the directory Build/.pytool/Plugin/Uncrustify
2. For each source file with formatting errors, a sibling file with the .uncrustify_plugin extension

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 with the .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.