Main Content

Prepare Checkers Configuration for Polyspace Bug Finder Analysis

Before you incorporate Polyspace® as a tool in the software development process of your organization, first decide how you plan on using Polyspace to improve your code. Choose which source components to analyze, which issues to check for, and so on. You can then prepare analysis configuration files that reflect your choices.

Broadly speaking, a Bug Finder analysis configuration consists of two parts:

  • Build configuration including sources and target

  • Checkers configuration

This topic describes a workflow for creating your checkers configuration in a typical deployment scenario. You can adapt this workflow to the specific requirements of your project or organization.

Identify Checkers to Enable

Suppose that you want to establish certain coding standards across your organization. You might follow one of several approaches:

  • Adhere to an external coding standard.

    If Bug Finder supports the coding standard, you can select the standard and a predefined or custom set of rules from the standard.

    Polyspace Bug Finder™ supports these external standards directly. For these standards, simply enable the standard in your configuration and start analysis.

    • MISRA C™:2004

    • MISRA C:2012

    • MISRA C:2023

    • MISRA™ C++:2023

    • MISRA C++:2008

    • JSF AV C++

    • AUTOSAR C++14

    • CERT® C

    • CERT C++

    • ISO®/IEC TS 17961

    • Guidelines (Bug Finder only)

    See Check for and Review Coding Standard Violations.

  • Develop a set of in-house coding rules based on external standards and prior issues found.

    See if you can automate checking of those rules through Bug Finder defect checkers and/or external coding standard checkers.

    One way to locate a potential checker is to search by keywords in the documentation. Suppose you want to detect issues that can arise from use of variadic functions.

    1. Search for keywords such as variadic or va_arg and refine search results by product to Bug Finder and then by category to Review Analysis Results > Polyspace Bug Finder Results.

    2. Identify all checkers related to variadic functions. Note down the checkers that you want to enable. See if there is an overlap between checkers and eliminate duplicates.

    You can record each defect checker that you enabled or disabled for your process requirements. You can start from the spreadsheet of checkers in polyspaceroot\polyspace\resources\. In the Your Notes column, note down your rationale for enabling or disabling a checker.

  • Check only for defects (bugs) that are most likely to cause errors at run time.

    You might not be following standard coding practices in your organization and you might find external coding standards too sweeping for your preferences.

    Start from the Bug Finder defect checkers and identify a subset of checkers for which you want to have zero unjustified defects. One way to identify this subset can be the following:

    • First select defect checkers with high impact. These checkers can find issues that are likely to have serious consequences.

      See also Classification of Defects by Impact.

    • Run a first pass of Bug Finder analysis with high impact checkers and identify checkers that produce too much noise that you do not want to address immediately. You can disable these checkers for your initial deployment.

    See also Choose Specific Bug Finder Defect Checkers.

    You can follow a similar strategy with checkers for external coding standards. For instance, for MISRA C:2012, you can start from the mandatory or required guidelines and then choose to expand later.

At the end of this process, you have identified some checkers to enable in a Polyspace analysis. These checkers can be all defect (bug) checkers, or all checkers from external coding standards, or a mix of the two. The next section describes how to create checkers configuration files that you can deploy to your developers.

Create Checkers Configuration Files

A Polyspace Bug Finder analysis configuration is a list of analysis options specified using command-line flags. You can store the entire configuration in one options file, for instance, a text file named allOptions.txt, and specify the file using -options-file like this:

polyspace-bug-finder -options-file allOptions.txt

Or like this:

polyspace-bug-finder-server -options-file allOptions.txt

For your convenience, you can split the configuration into parts:

  • Build configuration (sources, targets, and so on) — Save all options related to your build in an options file buildOptions.txt. You can create this file manually or automatically from your build command (makefile). For more information on how to create this file, see Specify Target Environment and Compiler Behavior.

  • Defect checkers and external coding standard configuration — Specify checkers configuration in a checkers configuration file.

By splitting the build configuration and checkers configuration into separate options files, you can reuse the checkers configuration across projects while creating a build configuration individually for each project. Conversely, you can also use different checkers configurations while reusing the build configurations.

In the preceding section, you identified the checkers that you want to enable for your analyses. There are different ways you can collect the identified checkers into a single configuration file:

  • Create a custom coding standard (.pschk) — Suppose you want to collect and organise the identified rules into an in-house coding standard. To create this custom coding standard, specify the coding rules that comprises the standard in a SARIF file and then use the command polyspace-catalog-bundler. This command produces a pschk file that you can use with the Polyspace Platform user interface or at the command line. To specify a custom coding standard CustomCodingStandard.pschk, at the command line, enter

    polyspace-bug-finder -options-file buildOptions.txt -checkers-activation-file CustomCodingStandard.pschk
    For details about this workflow, see Create User-Defined Coding Standard by Using Polyspace Bug Finder Checkers. Custom coding standards are not supported by the older Polyspace user interface and Polyspace Access.

  • Create a checkers activation file (.xml) — Suppose you want to enable a set of external coding rules and Bug Finder defects using a single checkers activation file. You can create this XML using the Checkers Selection window. To open this window, at the command line, enter

    polyspace-checkers-selection
    In the Checkers selection window, select the defects and coding rules that you identified in the preceding section and save the selection as an XML file.

    If you prefer to use a text editor to create the XML file, start with example activation files located in the folder polyspaceroot\polyspace\examples\doc_cxx\checkers_activation_XML\.

    After creating the activation file, specify it as an input to Checkers activation file (-checkers-activation-file). For example, to use the checkers activation file checkers.xml, at the command line, enter:

    polyspace-bug-finder -options-file buildOptions.txt -checkers-activation-file checkers.xml
    For details about creating the XML file, see the examples in Checkers activation file (-checkers-activation-file).

  • Create an options file — Suppose you want to keep selection of Bug Finder defects and external coding standards separate from each other. In this case, the checkers configuration file is an options file Defects_Coding_Rules that consists of two parts:

    • The Bug Finder checkers selection — Enable the Bug Finder defects that you chose in the preceding section by using the option -checkers followed by a comma-separated list of the defect checkers. For instance:

      -checkers 
        INT_ZERO_DIV, 
        FLOAT_ZERO_DIV, 
      ...

    • External coding standard — Enable the coding standard you chose in the preceding step by using the command Set checkers by file (-checkers-selection-file). For instance, a text file that enables specific rules from the MISRA C:2012 and AUTOSAR C++14 standard contains these options:

      -misra3 from-file
      -autosar-cpp14 from-file 
      -checkers-selection-file externalRuleCheckers.xml
      
      The expander shows the structure of the XML file externalRuleCheckers.xml that enables or disables checkers for rules from specific standards.

       Checkers Selection File

      For more information on how to create the XML file, see Check for and Review Coding Standard Violations.

    Once you select your defects and coding standards, the options file Defects_Coding_Rules might looks like this:

    -checkers 
      INT_ZERO_DIV, 
      FLOAT_ZERO_DIV, 
    -misra3 from-file
    -autosar-cpp14 from-file 
    -checkers-selection-file externalRuleCheckers.xml
    
    You can use this option file to run a Bug Finder analysis using this command:
    polyspace-bug-finder -options-file buildOptions.txt -options-file Defects_Coding_Rules

Once you create the build option file and the checkers configuration file, use the Polyspace run command in scripts. For instance:

  • In a Jenkins build, you can specify the run command in a build script, along with other tools that you are running. After code submission, the Polyspace analysis can run on newly submitted code through the build scripts.

  • In Polyspace as you Code IDE extensions, you can use the checkers activation file (.XML) or the custom coding standard (.pschk) directly in your IDE.

  • In developer IDEs, you can specify the run command through a menu item that runs external tools. Developers can run the Polyspace analysis during coding by using the external tools.

Creating these options files by hand can be prone to errors. If you have a license of the desktop product, Polyspace Bug Finder, you can generate these files from the Polyspace user interface. See also Configure Polyspace Analysis Options in User Interface and Generate Scripts.

See Also

Related Topics