https://github.com/sonaropencommunity/cxx-custom-checks-example-plugin
Sample for CXX custom rule: This plugin adds a custom rule to the cxx plugin of SonarQube.
https://github.com/sonaropencommunity/cxx-custom-checks-example-plugin
custom cxx plugin rule
Last synced: 8 months ago
JSON representation
Sample for CXX custom rule: This plugin adds a custom rule to the cxx plugin of SonarQube.
- Host: GitHub
- URL: https://github.com/sonaropencommunity/cxx-custom-checks-example-plugin
- Owner: SonarOpenCommunity
- Created: 2016-03-13T14:01:48.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-07-09T22:18:00.000Z (almost 2 years ago)
- Last Synced: 2025-04-14T17:29:36.855Z (about 1 year ago)
- Topics: custom, cxx, plugin, rule
- Language: Java
- Homepage:
- Size: 54.7 KB
- Stars: 6
- Watchers: 4
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CXX Custom Rules
The _cxx plugin_ makes it possible to add custom rules written in Java. In general, there are three ways to add coding rules to SonarQube:
* Writing a [SonarQube plugin](https://docs.sonarsource.com/sonarqube/latest/extension-guide/developing-a-plugin/plugin-basics/) in Java that uses [SonarQube APIs](https://javadocs.sonarsource.org/9.9.0.229/index.html) to add new rules
* Adding [XPath rules](https://docs.sonarsource.com/sonarqube/latest/extension-guide/adding-coding-rules/#adding-coding-rules-using-xpath) directly through the SonarQube web interface. The _cxx plugin_ provides an own [[CXX XPath|CXX-Custom-XPath-Rules]] extension.
* Importing [generic issue reports](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/importing-external-issues/generic-issue-import-format/) generated by an independently run tool
The _Java API_ will be more fully-featured than what's available for XPath, and is generally preferable. However, this comes with the overhead of maintaining a SonarQube plugin (including keeping it up-to-date as APIs change, upgrading the plugin after releasing a new version).
Importing generic issue reports is a good solution when there's a very specific need for a subset of projects on your SonarQube instance. They are the most flexible option but lack some features (such as being able to control their execution by inclusion in a quality profile).
# Writing a SonarQube plugin in Java that uses SonarQube APIs to add new rules
Writing custom rules for CXX is a six-step process:
* Create a new _SonarQube_ custom rules plugin (use https://github.com/SonarOpenCommunity/cxx-custom-checks-example-plugin as template).
* As a first step, the [pom.xml](https://github.com/SonarOpenCommunity/cxx-custom-checks-example-plugin/blob/master/pom.xml) file must be adapted. The version numbers must match the versions of the _cxx plugin_ ([cxx plugin pom.xml](https://github.com/SonarOpenCommunity/sonar-cxx/blob/master/pom.xml)) for which custom rules are written.
* Under [Advanced build properties](https://docs.sonarsource.com/sonarqube/latest/extension-guide/developing-a-plugin/plugin-basics/#advanced-build-properties) you will find further instructions for setting the metadata.
* [sonar-plugin-api](https://github.com/SonarSource/sonar-plugin-api?tab=readme-ov-file#sonar-plugin-api) describes changes to the API.
* Put a dependency on the API of the [cxx plugin](https://github.com/SonarOpenCommunity/sonar-cxx). The _cxx plugin_ must be built locally with _Maven_ so that it is available in the local _Maven Repository_ and can be used as a dependency in the custom plugin.
* Create as many custom rules as required. The rules must be derived from [CustomCxxRulesDefinition](https://github.com/SonarOpenCommunity/sonar-cxx/blob/master/sonar-cxx-plugin/src/main/java/org/sonar/plugins/cxx/CustomCxxRulesDefinition.java).
* the HTML description(s) must be created in `/org/sonar/l10n/cxx/rules/{repositoryKey}`
* Generate the _SonarQube_ custom rules plugin (jar file).
* Place this jar file in the `SONARQUBE_HOME/extensions/plugins` directory.
* Restart _SonarQube Server_.
The description [Plugin Basics](https://docs.sonarsource.com/sonarqube/latest/extension-guide/developing-a-plugin/plugin-basics/) is a good starting point for writing your own extensions. In addition, [Adding Coding Rules](https://docs.sonarsource.com/sonarqube/latest/extension-guide/adding-coding-rules/) gives further useful hints.
The existing _CXX rules_ can be used as a template for the new rules:
https://github.com/SonarOpenCommunity/sonar-cxx/tree/master/cxx-checks/src/main/java/org/sonar/cxx/checks
**C++ sample to verify:**
```C++
using namespace std;
void foo()
{
}
```
**Resulting AST:**
**Custom Rule Plugin sample:**
```Java
public final class MyCustomRulesPlugin implements Plugin {
@Override
public void define(Context context) {
context.addExtension(
MyCustomRulesDefinition.class
);
}
}
public class MyCustomRulesDefinition extends CustomCxxRulesDefinition {
@Override
public String repositoryName() {
return "Custom CXX";
}
@Override
public String repositoryKey() {
// The html descriptions for the rules of repository must be stored in the path '/org/sonar/l10n/cxx/rules/mycxx'.
// If the return value of 'repositoryKey' is changed, the storage location in 'resources' must also be adjusted.
return "mycxx";
}
@SuppressWarnings("rawtypes")
@Override
public Class[] checkClasses() {
return new Class[]{
UsingNamespaceCheck.class
};
}
}
// In case you are adding a .html description in resources, the .html file name should match the rule key.
// In this sample the name must be 'UsingNamespace.html'.
@Rule(
key = "UsingNamespace",
priority = Priority.BLOCKER,
name = "Using namespace directives are not allowed",
tags = {Tag.CONVENTION}
// second possibility to add a rule description:
//,description = "Using namespace directives are not allowed."
)
@SqaleConstantRemediation("5min")
@ActivatedByDefault
public class UsingNamespaceCheck extends SquidCheck {
@Override
public void init() {
subscribeTo(CxxGrammarImpl.usingDirective);
}
@Override
public void visitNode(AstNode node) {
getContext().createLineViolation(this, "Using namespace are not allowed.", node);
}
}
```