Create User-Defined Coding Standard by Using Polyspace Bug Finder Checkers

A user-defined coding standard is a collection of coding rules that you curate to check for bugs and defects that are relevant to your project. To create a user-defined coding standard, map your coding rules to existing Polyspace^® Bug Finder™ checkers in a Static Analysis Results Interchange Format (SARIF) file. The SARIF file defines the coding rules of your user-defined coding standard and sorts them into subgroups and categories. After creating the SARIF file, you can convert it into a Polyspace coding standard (.pschk) file, which you can use in a Bug Finder analysis to enforce the user-defined standard.

This topic shows how to create a user-defined coding standard once you have the mapping between the coding rules in the user-defined coding standard and existing Bug Finder checkers. To learn how to create the mapping, see Find Polyspace Bug Finder Checkers That Map to Coding Rules in User-Defined Coding Standard.

You can use user-defined coding standards and review the resulting violations in the Polyspace Platform user interface and Polyspace as You Code IDE extensions. The Polyspace desktop user interface and Polyspace Access™ do not support user-defined coding standards. If you upload analysis results that contain violations of a user-defined coding standard to Polyspace Access, the violations of user-defined coding standard are not uploaded and are ignored when you review the results in a web browser.

Overview of SARIF File Properties

This section describes the properties of the SARIF file that are relevant to creating a user-defined coding standard. For details about the SARIF file format and its properties, see SARIF documentation.

A valid SARIF file that encodes the mapping between coding rules and Bug Finder checkers must have "https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json" as the value of the property $schema. The $version property must be 2.1.0.

The body of the SARIF file contains a runs node, which includes a description of the user-defined coding standard. The runs node has a child node named supportedTaxonomies, which in turn has a child node named taxonomies. The taxonomies node has these child nodes:

properties — This node introduces categories and subsets for the coding rules in your user-defined coding standard.
taxa — This node consists of one or more comma-separated elements. Each element corresponds to a coding rule in the user-defined coding standard. To add a new rule, add a new element.

Each elements of the taxa node define the properties of one coding rule in the user-defined standard:

id — This property of the taxa node specifies the identifier of the coding rule. This identifier is used when reviewing violations of the user-defined coding standard.
text — This property specifies the rule description.
sectionName — A user-defined coding standard can consist of several sections. This property specifies which sections the coding rule belongs to. Group related coding rules into sections to make the standard easier to use. You can put new coding rules into existing sections or new sections.
category and subsets — These properties specify the category and subsets that the coding rule belong to. The category property accepts a single value, while the subset property accepts an array of values. Categories and subsets divide the coding rules in the standard following two separate axes. For example, you can categorize the coding rules in your user-defined standards into categories based on the importance of fixing their violations, such as Required and Optional. Then you can categorize the coding rules into subsets based on the cost of running the analysis, such as Quick Analysis and Overnight Analysis. When you define each coding rule, you can choose to categorize the rule into one of the categories and one or more of the subsets. When running an analysis, you can quickly select a set of rules using these categories and subsets based on the nature of the analysis.
language — This property indicates whether a rule is applicable to C, or C++, or both. When analyzing C code, the rules that apply to C++ are deactivated, and vice versa. Use the values C and C++ for rules that apply to C and C++, respectively. If a rule applies to both C and C++, use the value C|C++.
semantic — This value specifies how a coding rule of a user-defined standard is implemented in Bug Finder. Currently, Bug Finder supports implementing coding rule for user-defined coding standard by mapping coding rules to existing checkers. Use the value mapping for this field.
mapping — Each element of the taxa node contains one or more mapping nodes in a comma-separated list. Use this property to indicate which Bug Finder checkers map to your coding rule.

Each entry in the mapping list has these child nodes:

standard — Use this node to indicate the Bug Finder coding standard or defect that you choose for the mapping. The acceptable values for standard are:

Polyspace Bug Finder Standard	Value of `standard`
MISRA C:2023 Directives and Rules	`MISRA-C-2023`
MISRA C:2012 Directives and Rules	`MISRA-C3`
CERT C Rules and Recommendations	`CERT-C`
Common Weakness Enumeration (CWE)	`CWE`
MISRA C++:2023 Rules and Directives	`MISRA-CPP-2023`
CERT C++ Rules	`CERT-CPP`
AUTOSAR C++14 Rules	`AUTOSAR-CPP14`
Defects	`DEFECT`

These standards are designed for modern C/C++. Avoid mapping to older standards that do not cover the more recent aspects of the languages. Polyspace does not support mapping to Guidelines checkers and Custom coding rules.

id — Use this node to indicate which rule from the standard maps to your coding rule. The id is the identifier of the rule within the standard. For example, to mad to AUTOSAR C++14 Rule A12-8-1, use the value A12-8-1.

Create Mapping in SARIF

By using the properties described in the preceding section, you can summarize the required information for the user-defined coding standard into a SARIF file. Consider these coding rules in a user-defined coding standard:

Section	ID	Description	Bug Finder Checker	Category	Subset
Class	C.4	Make a function a member only if it needs direct access to the representation of a class	`AUTOSAR C++14 Rule M9-3-3`	Cat-1	Subset A
Class	C.22	Make default operations consistent	`Move operation uses copy`, `AUTOSAR C++14 Rule A12-8-1`, `AUTOSAR C++14 Rule A12-1-1`	Cat-1	Subset A
Move Semantics	Move_1	A move operation may throw	`A move operation may throw`	Cat-2	Subset A
Move Semantics	Move_2	Move operation uses copy	`Move operation uses copy`	Cat-2	Subset A, Subset B
Move Semantics	Move_3	Const `std::move` input may cause a more expensive object copy	`Const std::move input may cause a more expensive object copy`	Cat-2	Subset A, Subset B
Container	Container_1	Expensive use of map instead of set	`Expensive use of map instead of set`	Cat-3	Subset A, Subset B
Container	Container_2	Expensive use of map's bracket operator to insert or assign a value	`Expensive use of map's bracket operator to insert or assign a value`	Cat-3	Subset A, Subset B

To create the mapping for this user-defined coding standard:

Create a SARIF file that follows the schema 2.1.0. Set "https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json" as the value of the property $schema and 2.1.0 as the value of $version.
Specify the name of your coding standard in the property runs/taxonomies/name.
Specify the categories and subsets of your standard in the properties runs/taxonomies/properties/categories and runs/taxonomies/properties/subsets. For example:
```
"categories": ["Cat-1", "Cat-2", "Cat-3"],
"subsets": ["Subset A", "Subset B"],
```
Specify an ID for the standard by using the property runs/taxonomies/properties/id. This ID is used when annotating results of the user-defined coding standard.
For each rule in your coding standard, add an element in the comma-separated list runs/taxonomies/taxa.

Specify coding rule properties for each element in the properties node. For example, use this entry for the rule C.22:

{
   "id": "C.22",
   "shortDescription": {
     "text": "Make default operations consistent."
   },
   "properties": {
     "sectionName": "Class",
     "category": "Cat-1",
     "language": ["C++"],
     "subsets": ["Subset A"],
     "semantic": {
       "type": "mapping",
       "mapping": [
         {
           "standard": "DEFECT",
           "id": "MOVE_OPERATION_USES_COPY"
         },
         {
           "standard": "AUTOSAR-CPP14",
           "id": "A12-8-1"
         },
         {
           "standard": "AUTOSAR-CPP14",
           "id": "A12-1-1"
         }

       ]
     }
   }
 }

Example SARIF

{
  "$schema": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "informationUri": " ",
          "name": "Bug Finder",
          "fullName": "Polyspace",
          "semanticVersion": "R2024a Prerelease",
          "organization": "MathWorks",
          "supportedTaxonomies": [
            {
              "name": "Name"

            }
          ]
        }
      },
      "taxonomies": [
        {
          "name": "User-Defined Coding Standard",
          "properties": {
            "categories": ["Cat-1", "Cat2", "Cat-3"],
            "subsets": ["Subset A", "Subset B"],
            "id": "UDCS"
          },
          "taxa": [
            {
              "id": "C.4",
              "shortDescription": {
                "text": "Make a function a member only if it needs direct access to the representation of a class."
              },
              "properties": {
                "sectionName": "Class",
                "category": "Cat-1",
                "language": ["C++"],
                "subsets": ["Subset A"],
                "semantic": {
                  "type": "mapping",
                  "mapping": [
                    {
                      "standard": "AUTOSAR-CPP14",
                      "id": "M9-3-3"
                    }

                  ]
                }
              }
            },{
              "id": "C.22",
              "shortDescription": {
                "text": "Make default operations consistent."
              },
              "properties": {
                "sectionName": "Class",
                "category": "Cat-1",
                "language": ["C++"],
                "subsets": ["Subset A"],
                "semantic": {
                  "type": "mapping",
                  "mapping": [
                    {
                      "standard": "DEFECT",
                      "id": "MOVE_OPERATION_USES_COPY"
                    },
                    {
                      "standard": "AUTOSAR-CPP14",
                      "id": "A12-8-1"
                    },
                    {
                      "standard": "AUTOSAR-CPP14",
                      "id": "A12-1-1"
                    }

                  ]
                }
              }
            },{
              "id": "Move_1",
              "shortDescription": {
                "text": "A move operation may throw."
              },
              "properties": {
                "sectionName": "Move Semantics",
                "category": "Cat-2",
                "language": ["C++"],
                "subsets": ["Subset A"],
                "semantic": {
                  "type": "mapping",
                  "mapping": [
                    {
                      "standard": "DEFECT",
                      "id": "MOVE_OPERATION_MAY_THROW"
                    }

                  ]
                }
              }
            },{
              "id": "Move_2",
              "shortDescription": {
                "text": "Move operation uses copy."
              },
              "properties": {
                "sectionName": "Move Semantics",
                "category": "Cat-2",
                "language": ["C++"],
                "subsets": ["Subset A", "Subset B"],
                "semantic": {
                  "type": "mapping",
                  "mapping": [
                    {
                      "standard": "DEFECT",
                      "id": "MOVE_OPERATION_USES_COPY"
                    }

                  ]
                }
              }
            },{
              "id": "Move_3",
              "shortDescription": {
                "text": "Const std::move input may cause a more expensive object copy."
              },
              "properties": {
                "sectionName": "Move Semantics",
                "category": "Cat-2",
                "language": ["C++"],
                "subsets": ["Subset A", "Subset B"],
                "semantic": {
                  "type": "mapping",
                  "mapping": [
                    {
                      "standard": "DEFECT",
                      "id": "EXPENSIVE_STD_MOVE_CONST_OBJECT"
                    }

                  ]
                }
              }
            },{
              "id": "Container_1",
              "shortDescription": {
                "text": "Expensive use of map instead of set."
              },
              "properties": {
                "sectionName": "Container",
                "category": "Cat-3",
                "language": ["C++"],
                "subsets": ["Subset A", "Subset B"],
                "semantic": {
                  "type": "mapping",
                  "mapping": [
                    {
                      "standard": "DEFECT",
                      "id": "EXPENSIVE_USE_OF_MAP_INSTEAD_OF_SET"
                    }

                  ]
                }
              }
            },{
              "id": "Container_2",
              "shortDescription": {
                "text": "Expensive use of map's bracket operator to insert or assign a value."
              },
              "properties": {
                "sectionName": "Container",
                "category": "Cat-3",
                "language": ["C++"],
                "subsets": ["Subset A", "Subset B"],
                "semantic": {
                  "type": "mapping",
                  "mapping": [
                    {
                      "standard": "DEFECT",
                      "id": "EXPENSIVE_MAP_INSERT_OR_ASSIGN"
                    }

                  ]
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Create User-Defined Coding Standard

Once you have a SARIF file that implements the mapping between the coding rules in your user-defined coding standard and existing Bug Finder checkers, you can then create the user-defined coding standard. To create the user-defined coding standard, use the command polyspace-catalog-bundler.

Save the SARIF file as myMapping.SARIF. Then create a Polyspace coding standard (.pschk) file myCodingStandard by using this command:

polyspace-catalog-bundler import -catalog myMapping.SARIF -bundle myCodingStandard.pschk -identifier VersionA

Here, myMapping.SARIF is the SARIF file that contains the mapping between the guidelines in your user-defined coding standard. The file myCodingStandard.pschk is the resulting user-defined coding standard file. The identifier VersionA is associated with the user-defined coding standard file. When you run a Bug Finder analysis using user-defined standard, Polyspace prints the identifier in the analysis log. The analysis log also shows the checksum of myMapping.SARIF.

Use the identifier and the checksum to verify that you use the correct user-defined coding standard in your analysis. This information allow you to keep track of different versions of a user-defined standard that you use in your project.

You can open file myCodingStandard.pschk file in the Checkers Selection window:

The Checkers Selection window showing the user-defined coding standard.

The coding rule defined in the taxa node are selectable in the Checkers Selection window.
The categories and subsets you listed in the taxonomies/properties node are selectable check boxes that allow you to select a group of coding rules quickly.
Each new entry in the sectionName nodes corresponds to an expandable section in the Checkers Selection window.

After creating the .pschk file, you can share the file with other Polyspace users in your organization.

To check for violations of the user-defined coding standard, use one of these methods:

Command line — Use the .pschk file as an input to the option Checkers activation file (-checkers-activation-file).
Polyspace Platform user interface — In the Configuration pane, select Static Analysis > Defects and Coding Standards > . Enter the .pschk file in the Checkers activation file box.
Polyspace as You Code — Specify the .pschk file in the Checkers Selection window. You can open the Checkers Selection window from your Polyspace as You Code plugin. See Setting Checkers in Polyspace as You Code (Polyspace Access).

For more details about finding violations of the user-defined coding standard, see Check for Violations of User-Defined Coding Standard Using Polyspace Bug Finder.

Create User-Defined Coding Standard by Using Polyspace Bug Finder Checkers

Overview of SARIF File Properties

Create Mapping in SARIF

Create User-Defined Coding Standard

See Also

Related Topics