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.
Search for keywords such as
variadic
orva_arg
and refine search results by product to Bug Finder and then by category to Review Analysis Results > Polyspace Bug Finder Results.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
. In the Your Notes column, note down your rationale for enabling or disabling a checker.polyspaceroot
\polyspace\resources\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 commandpolyspace-catalog-bundler
. This command produces apschk
file that you can use with the Polyspace Platform user interface or at the command line. To specify a custom coding standard
, at the command line, enterCustomCodingStandard.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.polyspace-bug-finder -options-file buildOptions.txt -checkers-activation-file
CustomCodingStandard.pschk
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, enterIn 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.polyspace-checkers-selection
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
, at the command line, enter:checkers.xml
For details about creating the XML file, see the examples inpolyspace-bug-finder -options-file buildOptions.txt -checkers-activation-file
checkers.xml
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
that consists of two parts:Defects_Coding_Rules
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:The expander shows the structure of the XML file-misra3 from-file -autosar-cpp14 from-file -checkers-selection-file externalRuleCheckers.xml
externalRuleCheckers.xml
that enables or disables checkers for rules from specific standards.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
might looks like this:Defects_Coding_Rules
You can use this option file to run a Bug Finder analysis using this command:-checkers INT_ZERO_DIV, FLOAT_ZERO_DIV, -misra3 from-file -autosar-cpp14 from-file -checkers-selection-file externalRuleCheckers.xml
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.