polyspace-query-language

R2026b

(System Command) Create and test user-defined coding standards and user-defined coding rules

Since R2026a

collapse all in page

Syntax

polyspace-query-language init
polyspace-query-language package
polyspace-query-language test TestOptions SourceFile AnalysisOptions
polyspace-query-language profile ProjectDirectory AnalysisOptions

Description

Note

This Polyspace® command is available in polyspaceroot\polyspace\bin. Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026b (see also Installation Folder (Polyspace Code Prover) for desktop products or Installation Folder (Polyspace Code Prover) for server products). To avoid typing the full path to this command, add this location to the PATH environment variable in your operating system.

polyspace-query-language init initializes a user-defined coding standard. In the current directory, it creates the necessary files to create the user defined coding standard, including main.pql and pql.json. The file main.pql is the entry point for subsequent polyspace-query-language commands. Create your coding standard and coding rules assuming the main.pql file as the entry point. The file pql.json is a configuration object and does not need to be modified. In addition, this command copies a folder .polyspace in the current folder. This folder contains the definition of supported classes and their predicates.

example

polyspace-query-language package creates a user-defined coding standard (.pschk) based on the specification in the file main.pql located in the current directory.

example

polyspace-query-language test TestOptions SourceFile AnalysisOptions runs a Polyspace Bug Finder™ analysis on SourceFile using the user-defined coding standard created by main.pql. The test passes if expected violations are present in the result. The options in AnalysisOptions are passed to the Polyspace Bug Finder analysis.

example

polyspace-query-language profile ProjectDirectory AnalysisOptions profiles the user defined coding standard and identifies the defects that bottlenecks the analysis. This commands analyzes the Polyspace Query Language (PQL) project in the folder ProjectDirectory. By default, Polyspace assumes the current directory is the ProjectDirectory.

Examples

Create New User Defined Coding Standard

  1. Open a terminal in the directory of your choice. Initialize the coding standard:

    polyspace-query-language init

  2. Open the file main.pql. Specify your coding standard and coding rules in this file. For example, this content creates a new user defined standard that has a single rule. This rule is a mapping to the Polyspace Bug Finder defect Useless if:

    package main

catalog QuickStart = {                               // Catalog
  section QuickStartSection = {                      // Section
    rule MappingToMisraRule = {                      // Rule
      std.defects.USELESS_IF                         // Mapping
    }
  }
}

  3. To create the user-defined coding rule following the specification in main.pql, at the command-line, enter:

    polyspace-query-language package

Test User Defined Coding Standards and Rules

Test your coding standard to verify that the violations appear as expected in the correct location. Consider this C code: 

void foo()
{
    int x;
    if (x = 0)
    { 
        x = 0;
    }
    if (x == 0)
    { 
    }
    for (x = 0; x < 5; ++x)
    {
    }
    while (x = 0) 
    { 
    }
}
This code uses an assignment operation as the condition for if and while statements. It also contains if statements that are always true. Prepare a coding standard that detects these issue. For later use, copy this code in src.cpp

  1. In a writable folder syntaxrule, initialize a new user-defined coding standard

    polyspace-query-language init

  2. In the file main.pql, enter this content:

    package main

// Main PQL file defines the catalog of your PQL project.
// The catalog is a collection of sections.
#[Description("MyStandard")]
catalog syntaxrule = {
	// Define and include sections in this list.
	#[Description("MySection")]
	section mysection = {
		#[Description("myRule"), Id(Rule1)]
		rule myRule = {	
			defect mydefect = 
			when 
			Cpp.ConditionClause.is(&cc)
			and cc.parent(&parentCC)
			and (Cpp.IfStatement.isa(parentCC, &ifStmt)	or Cpp.WhileStatement.isa(parentCC,&whilestmt))
			and cc.value(&value)
			and Cpp.AssignmentExpression.isa(value,&discard)
			and value.nodeText(&NT)
			raise "Assignment in If or while condition statement \"{NT}\""
			on cc

		},
		#[Description("myOtherRule"), Id(Rule2)]
		rule myOtherRule = {
			std.defects.USELESS_IF
		}

	}
}

  3. Create the user-defined coding standard syntaxrule.pschk containing the rules Rule1 and Rule2. At the command line, enter:

    polyspace-query-language package
    Run this command in the folder syntaxrule.

  4. Annotate the source file to indicate where you expect violations of the rules are:

    void foo()
{
    int x;
    if (x = 0)// expect-1-Rule1
    { 
        x = 0;
    }
    if (x == 0) // expect-1-Rule2
    { 
    }
    for (x = 0; x < 5; ++x)
    {
    }
    while (x = 0) // expect-1-Rule1
    { 
    }
}

  5. Test your coding standard:

    polyspace-query-language test src.cpp
    This command runs a Polyspace Bug Finder analysis on src.cpp using the user-defined coding standard syntaxrule.pschk and checks where the violation of the rules occur in the expected locations. Because the violations occur in the lines specified using the //expected... comments, the test passes.

Profile User Defined Coding Standard

Consider a user defined coding standard in the folder ProjectFolder which contains PQL defects addressing C11 code. To profile this user defined coding standard in , at the command line, enter

polyspace-query-language profile ProjectFolder -lang C -c-version C11
The analysis identifies the predicates that are most expensive and reports them in a list.

Input Arguments

collapse all

The source files that you want to analyze using the user-defined coding standard.

Example: polyspace-query-language test src.cpp,src2.cpp,src3,cpp...

Data Types: char

By default, the polyspace-query-language test command returns 0 if the Bug Finder analysis succeeds and then the annotated expectations are met. If the Bug Finder analysis fails or if the expectations are not met, the command returns nonzero. You can specify these options to change the default behavior:

  • -s / --silent-unexpected-positives — Unexpected violations are not considered errors and do not fail the test.

  • -n / --no-fail-if-test-fails — If the Bug Finder analysis succeeds, the command returns 0 even if the expectations annotated in the code are not met.

  • -f / --force-if-compile-error — Bug Finder analysis continues even if the code fails compilation.

  • -v / --verbose — Bug Finder analysis logs are printed in the command line.

Example: polyspace-query-language test -f src.cpp

Data Types: char

When you initialize a PQL project using polyspace-query-language init in a folder, a file pql.json is created. The folder containing this configuration file is the ProjectDirectory.

Example: polyspace-query-language profile "C:\PQL"

Data Types: string

When executing the polyspace-query-language test command, specify analysis options for the Bug Finder analysis as AnalysisOptions. For a list of Bug Finder analysis options, see Configuration.

Example: polyspace-query-language test src.cpp -lang cpp -cpp-version cpp20

Data Types: string

Version History

Introduced in R2026a

See Also

Topics