Scaffolding¶
Rules and reporters classes are designed by contract, meaning they need to inherit their base classes, and implement pure virtual methods, and their source code follow certain structures. So we could scaffold new rules and reporters by copying their templates and replacing the placeholders. In addition, the scaffolding scripts can ease your work by adding the new rule and reporter to the OCLint build pipeline.
This document provides information on how to create rules and reporters with scaffold scripts.
Creating Rules with Scaffolding¶
Creating a custom rule can be done with scaffoldRule
script under oclint-scripts
folder.
We could get a list of its options by typing ./scaffoldRule -h
:
usage: scaffoldRule [-h] [-t {Generic,SourceCodeReader,ASTVisitor,ASTMatcher}]
[-c RULE_CATEGORY] [-n RULE_NAME] [-p {1,2,3}] [--test]
[--no-test]
class_name
positional arguments:
class_name class name of the rule
optional arguments:
-h, --help show this help message and exit
-t {Generic,SourceCodeReader,ASTVisitor,ASTMatcher}, --type {Generic,SourceCodeReader,ASTVisitor,ASTMatcher}
-c RULE_CATEGORY, --category RULE_CATEGORY
-n RULE_NAME, --name RULE_NAME
-p {1,2,3}, --priority {1,2,3}
--test Generate a test for the new rule (default)
--no-test Do not generate a test for the new rule
From where, we could specify the class name, along with the name, type, category and priority of the rule.
Class name is the only required argument. Without explicitly given a rule name, it could be generated according to the class name. The default values of type, category and priority are Generic
, custom
and 3
respectively.
See also
Learn how to choose the proper rule interface from Rule Module Internals document.
For example, if we want to create a controversial rule that extracts all switch statements with abstract syntax tree (AST) matcher, we can enter this command in the terminal:
./scaffoldRule AllSwitchStatements -c controversial -t ASTMatcher
Notice we would like scaffold script to populate the rule name and assign the default priority to this rule for us.
The scaffold script will create AllSwitchStatementsRule.cpp
file, and store it in controversial
folder under oclint-rules/rules
. The rule will be generated like the following:
#include "oclint/AbstractASTMatcherRule.h"
#include "oclint/RuleSet.h"
class AllSwitchStatementsRule : public AbstractASTMatcherRule
{
private:
static RuleSet rules;
public:
virtual const string name() const
{
return "all switch statements";
}
virtual int priority() const
{
return 3;
}
virtual const string category() const override
{
return "controversial";
}
virtual void callback(const MatchFinder::MatchResult &result)
{
}
virtual void setUpMatcher()
{
}
};
RuleSet AllSwitchStatementsRule::rules(new AllSwitchStatementsRule());
In addition, related CMakeLists.txt
files will be edited to ensure the new rule will be built along with other existing rules.
A unit test file for this rule is scaffolded along with this process for testing purposes.
Now, the scaffolding is finished, we can refer to Writing Custom Rules document to fill in the logic for the rule.
Creating Reporters with Scaffolding¶
Scaffolding a reporter is very similar to the rule, but much easier, since it only requires the reporter’s class name with an optional argument for specifying the reporter’s name. We could also get these options by typing ./scaffoldReporter -h
:
usage: scaffoldReporter [-h] [-n REPORTER_NAME] [--tests] [--no-tests]
class_name
positional arguments:
class_name class name of the reporter
optional arguments:
-h, --help show this help message and exit
-n REPORTER_NAME, --name REPORTER_NAME
--tests Generate a test for the new reporter (default)
--no-tests Do not generate a test for the new reporter
Let’s say we want to create a new ColorfulTextReporter, with this script, we could do
./scaffoldReporter ColorfulText -n color
The generated ColorfulTextReporter.cpp
will look like the following:
#include "oclint/Reporter.h"
class ColorfulTextReporter : public Reporter
{
public:
virtual const string name() const
{
return "color";
}
virtual void report(Results *results, ostream &out)
{
}
};
extern "C" Reporter* create()
{
return new ColorfulTextReporter();
}
Sequentially, the CMakeLists.txt
file under reporters
folder will be edited by appending the new reporter.
A unit test file for this reporter is scaffolded along with this process for testing purposes.
Now, we can refer to the Writing Custom Reporters document to print out the analysis results.