Checkers activation file (-checkers-activation-file)

Activate a custom combination of defects and coding rules for a Polyspace Bug Finder analysis

Since R2021a

Description

Specify the full path of an activation (.XML) file or a coding standard (.pschk) file where you define custom combination of Polyspace^® Bug Finder™ defects and coding standards checkers.

Set Option

User interface (desktop products only): This option is not directly available in the user interface. Enter the command line option -checkers-activation-file in the Other field. See Other.

User interface (Polyspace Platform): In your project configuration, the option is on the Defect and Coding Standards tab.

Command line and options file: Use the option -checkers-activation-file. See Command-Line Information.

Why Use This Option

This option allows you to:

Create a custom selection of Polyspace Bug Finder defects and coding rules in a reusable .XML file.
Check for violations of a user defined coding standards defined in a reusable .pschk file.

You can reuse the files across multiple projects or share with multiple users to maintain a common set of rules across your group or organization.

Settings

A default Polyspace Bug Finder analysis reports a specific set of defects and does not report any coding rule violations. To activate a custom set of checkers including defects and coding rules, use a checkers activation file or a user defined coding standard.

You can create the input file for the option in one of the following ways:

Create the checkers activation (.XML) file by saving your checkers selection in the Checkers Selection window. See Create Checkers Activation File Using Checkers Selection Interface.
Create the custom coding standard (.pschk) by using the command polyspace-catalog-bundler.
Open an existing checkers activation XML file in a text editor and turn on the desired checkers. See Update Checkers Activation File in Text Editor.

If you have a preexisting file, then use the file as input to this option:

If you use the Checkers selection interface, browse to the file and then click Finish.
If you use the command line workflow, specify the complete path to the file as the input to -checkers-activation-file.

Dependencies

To use this option in the Polyspace Platform user interface, you must set the option Set checkers using file to On ().

Examples

Create Checkers Activation File Using Checkers Selection Interface

Create a checkers activation file by using the Checkers selection interface. This file is a reusable selection of Bug Finder defects and coding rules that you can use as the input to the option -checkers-activation-file in a Bug Finder analysis.

Open the Checkers selection interface. You can open this interface in one of several ways:
- If you use the Polyspace Platform user interface, select Use custom checkers file at the Defects and Coding Standards tab. Then, click . The checkers selection window opens.
- If you use the Polyspace as You Code plugins for IDEs, you can open the Checkers selection interface from your IDE. See Setting Checkers in Polyspace as You Code.
- If you use a command line workflow, then at the command line, enter:
```
polyspace-checkers-selection
```
  Alternatively, navigate to polyspaceroot\polyspace\bin and launch the binary polyspace-checkers-selection. Here, polyspaceroot is the root installation folder for the Polyspace products, for instance, C:\Program Files\Polyspace Server\R2024b.
In the Checkers selection interface, select New. Select defect checkers and coding rules that you want enabled. Click Save Changes to save your selection as an XML file, for instance, checkers.xml.
When running a Bug Finder analysis, specify this XML file as the argument for the option -checkers-activation-file.
```
polyspace-bug-finder-access -sources src.c -checkers-activation-file checkers.xml
```

Update Checkers Activation File in Text Editor

In some cases, you might not have access to the Checkers Selection UI. For instance, you might be using Polyspace in a headless terminal. In this case, create the checkers activation XML file by using the template files in polyspaceroot\polyspace\examples\doc_cxx\checkers_activation_XML.

To activate Bug Finder defects or checkers from one of the coding standards, make a writable copy of the corresponding templates. Locate the checker by finding the node that has the correct check id attribute. Activate the checker by setting the state attribute to "on".

Alternatively, to make a custom XML that activates various coding standards and Bug Finder defects, copy the relevant entries from the corresponding coding standard and defect templates into the blank.xml template in polyspaceserverroot\polyspace\examples\doc_cxx\checkers_activation_XML. A checkers activation XML file that activates the Bug Finder defect DATA_RACE and CERT C coding rule CON01-C resembles this example:

<?xml version="1.0" encoding="UTF-8"?>
<polyspace_checkers_selection xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="selection_schema.xsd" revision="2.0">
  <standard name="Bug Finder Findings">
      <section name="Concurrency">
		<check id="DATA_RACE" state="on"/>
      </section>
  </standard>
  
  <standard name="SEI CERT C">
      <section name="Concurrency (CON)">
		<check id="CON01-C" state="on"/>
      </section>
    </standard>
</polyspace_checkers_selection>

For a full list of coding rule check IDs, defect checker short names, and section names, see:

Note

The XML format of the checker configuration file might change in future releases.

Tips

The option -checkers-activation-file is an improved version of a similar option Set checkers by file (-checkers-selection-file). The improvements are the following:
- The option -checkers-activation-file is sufficient to both specify checkers and enable them. The option -checkers-selection-file only specifies a set of checkers for the analysis using a checkers selection file. You have to enable them separately using the value from-file for one of the coding standards options (such as -misra3 or -autosar-cpp14).
- The option -checkers-activation-file enables both defect and coding standard checkers. The option -checkers-selection-file covers coding standard checkers only. To specify and enable defect checkers, you have to then use the option -checkers with a comma-separated list of defect checker names.
Both options -checkers-activation-file and -checkers-selection-file require an XML file with the checker specifications as argument. The XML files have the same format with the only difference coming from the fact that -checkers-activation-file enables defect checkers in addition to coding standard checkers. The XML file for -checkers-activation-file has this additional element:
```
<standard name="Bug Finder Findings">
   <section name="Numerical">
      <check name="INT_ZERO_DIV" state="on">
      <check name="INT_CONV_OVFL" state="on">
       ...
   </section>
</standard>
```
If you use the XML generated for the option -checkers-selection-file with the option -checkers-activation-file, Polyspace converts the provided XML into the correct format and emits a warning.
If you use an activation file generated by using a previous version of Polyspace, previously unimplemented checkers might become implemented. Polyspace warns if the file XML file lists an implemented checker as 'notimplemented'.
If you use Polyspace as You Code extensions in IDEs, this option is implemented through the IDE extension setting. You do not have to use this option explicitly. If you want to explicitly use this option, enter the option in an analysis options file. See options file.
You can classify the activated checkers into custom subsets by entering specific texts in the Comment column of the Checkers selection interface. During results review, Polyspace displays the text you entered in the Results Details pane and in the Detail column of the Results List (if available). You can then sort the result into the desired subset using the entered text. For instance, say you want to specify certain checkers as Mandatory. Enter the text Mandatory in the Comment column of the Checkers selection interface. During code review, you can isolate the Mandatory checkers by sorting the result by Comment in the Results List.
Note
The custom text that you enter in the Checkers selection interface is omitted in:
- Generated reports.
- The Polyspace desktop interface when you open results from Polyspace Access in the desktop interface. This limitation applies only to Bug Finder checkers.

Command-Line Information

Parameter: -checkers-activation-file

Value: Path to checkers activation (.XML) file or the user defined coding standard (.pschk) file. You can specify an absolute path or a path relative to the location from which you run the polyspace-bug-finder command.

No Default

Example (Bug Finder):

polyspace-bug-finder -sources src.c
               -checkers-activation-file checkers.xml