Changing the thresholds for reported metricsChanging the thresholds for reported metricsKlocwork can detect and report on metrics threshold violations that you set based on your organization's standards and priorities. The default metrics thresholds configuration file produces a report that covers a few basic metrics. By modifying this configuration file, however, you can have Klocwork report on those errors most relevant to your code quality objectives. About the default metrics thresholds configuration fileThe metrics thresholds configuration file is a text file in which you set the thresholds you want Klocwork to report. If a metrics threshold is violated, Klocwork reports the violation. Each line in the configuration file sets one threshold. Here are a few examples of the types of metrics thresholds you could set:
Note: All metrics rules are commented out in this default file. They must be uncommented in order to report on metric threshold violations.
The metrics_default.mconf file shows some examples of the types of threshold violation rules that can be created. Editing the metrics thresholds configuration file
Syntax of metric threshold rulesEach line of the metric thresholds configuration file represents one metric threshold for which you want Klocwork to detect violations. Each metric threshold rule in the file has the following fields:
The following sections detail each field. Comments and blank lines are allowed in the configuration file syntax. Use the pound symbol (#) at the beginning of comment lines so they are not read as rules. Tip: The #!alias syntax allows you to substitute text in the rules:
#!alias MetricCode = <expression> Following this comment, all occurrences of "MetricCode" are textually substituted with <expression>.
NameName is a simple description of the violation that appears in the report if such a violation is detected, for example, Number of class declarations. For a full list, see the Name column of the tables in Metrics reference. The name must be unique among metric rule names used in all .mconf files.
Entity-typeEntity-type is the software entity for which the metric threshold is applicable. If you want the same threshold to apply to more than one software entity, you can specify several in a comma-separated list. For example:
The following tables show which entity types you can use with each of the metric categories. Applicable entity types for each metric category: C/C++
TYPE in class level threshold rules stands for structs and unions. TEMPLATE-MEMBER in function-level metric threshold rules stands for class-template methods. Applicable entity types for each metric category: Java
Metric-expressionMetric-expression can be either of the following:
Error-thresholdError-threshold is a number that represents the threshold for the metric. See Number values (below) for more information. It may be prefixed by a logical operation such as <, <=, or >=. See Logical operations below for more information. If only a number is entered in this field, the default operation applied is "greater than" (>). Violation of this metric would be reported as an error. For example, if you set the error threshold for the lines of code per file metric at <100, an error would be reported if the number of lines of code in a file (LOC_FILE) were less than 100. Tip: There may be some metrics thresholds for which you only want to report warnings and never errors. To achieve this, set your error threshold to a condition that can never be true. For example, if you want files with less than 100 lines of code to report a warning, set the error threshold to <0 (a condition that can never be true) and the warning threshold to <100.
Warning-thresholdWarning-threshold is a number that represents the threshold for the metric defined in the expression. The number may be prefixed by a logical operation such as <, <=, or >=. If only a number is entered in this field, the default operation applied is "greater than" (>). Violations of this metric would be reported as a warning. For example, if you set the warning threshold for the lines of code per file metric at <100, a warning would be reported if the number of lines of code in a file (LOC_FILE) were less than 100. If a metric exceeds both the warning and the error thresholds, only the error message is reported.
Example of full metric threshold rule
Function call valuesFunctionCall can have the following functions:
Number valuesNumber can be any of the following:
Logical operationsLogical operations can be any of the following:
Creating categories of metric threshold rulesIf you choose, you can organize your metric threshold rules into categories with names you find meaningful. You can name the categories as you wish. Note, however, that all metrics grouped into one category are assigned the same error or warning severity level, so they should be of equal importance in terms of how important it is to address the detected violations.
Specifying categories in the configuration fileCategories are specified in the configuration file with a line like the following:
where
The default configuration file contains three placeholder "user-defined warning categories". Examples of setting a metrics thresholdThe following table describes and shows the syntax of some typical metrics thresholds to include in a Klocwork report. Remember that you can change the text of the Name field (which describes the metrics threshold).
Example 1Rule intent: At the file level, show the percentage of comment lines. If less than five percent of lines are comments, issue an error. If less than 10% but more than five percent of lines are comments, issue a warning. Rule syntax: Name;Kind;Expression;Error threshold;Warning threshold Percent of comments;FILE;LINESCOMM/LOC_FILE*100;<5;<10
Example 2Rule intent: Show the number of calls to unique functions. If there are 20 or more, issue an error. If there are 15 to 19, issue a warning. Rule syntax: Name;Kind;Expression;Error threshold;Warning threshold Number of unique calls (UCT);FUNCTION,CLASS-METHOD;NOCALLS;20;15
Example 3The following example shows three stages. The source code file shows what you begin with: 1 /* function main */
2 main(){
3 printf("Hello world\n");
4 }
5
6 hello(){
7 // tbd
8 }
9 test(int a){
10 return 1;
11 }
12
Change the threshold in the Metrics thresholds configuration file: Number of lines of code of function;FUNCTION;LOC_FILE;>100;>30 Cyclomatic complexity (VG);FUNCTION;CYCLOMATIC;20;8 Empty function;FUNCTION;NOOPUSED|NORET;==3.14;==0 After your .mconf file is imported and analyzed, the default kwcheck output will be: 1 <path>/example2.c:6 METRICS.W.Empty_function Analyze Violated metric "Empty_function": hello 0==0 Specifying sizes for built-in typesNote: All the BYTES*** metrics described in this section are calculated for C/C++ projects only.
When you run a Klocwork analysis, it calculates all supported metrics and stores them in the metric.dat file in your tables directory. The reports, however, only show violations of metrics thresholds for which there are rules in the metrics thresholds configuration file. If you want Klocwork to report on more metrics, you need to write additional metric threshold rules and add them to your metrics thresholds configuration file. Before you can write new rules involving the following metrics, however, you may need to provide additional information to ensure that the metrics are calculated correctly. The required information is beyond the scope of what Klocwork can discover directly from your source code. The following metrics that calculate the number of bytes of certain entities in your code may only be calculated correctly if you use additional Klocwork options.
Calculation of these metrics depends on stored information about the size, in bytes, of built-in types in your software system. If the size of your built-in types matches the default sizes, Klocwork correctly calculates these metrics every time you run it. Klocwork uses the following default sizes for built-in types: Windows char;1 Unix: char;1 If the size of your built-in types do not match these default sizes, you need to create a "size of types" file and use this configuration file during Klocwork analysis:
Applying the metrics threshold configuration file to the analysisTo apply your new configuration file to the integration build analysis, import it into a project or the projects_root. |