Check custom rules (`-custom-rules`)

(Removed) Follow naming conventions for identifiers

Using Code Prover to follow naming conventions is no longer supported. Use Check custom rules (-custom-rules) in Bug Finder instead. For more information, see Version History.

Description

Define naming conventions for identifiers and check your code against them.

Set Option

User interface (desktop products only): In your project configuration, the option is on the Coding Standards & Code Metrics node.

Command line and options file: Use the option -custom-rules. See Command-Line Information.

Why Use This Option

Use this option to impose naming conventions on identifiers. Using a naming convention allows you to easily determine the nature of an identifier from its name. For instance, if you define a naming convention for structures, you can easily tell whether an identifier represents a structured variable or not.

After analysis, the Results List pane lists violations of the naming conventions. On the Source pane, for every violation, Polyspace^® assigns a symbol to the keyword or identifier relevant to the violation.

For the full list of types on which you can apply naming conventions, see Custom Coding Rules.

Settings

On

Polyspace matches identifiers in your code against text patterns you define. Define the text patterns in a custom coding rules file. To create a coding rules file,

Use the custom rules wizard:

Click . A Checkers selection window opens.
The Custom node in the left pane is highlighted. Expand the nodes in the right pane to select custom rule you want to check.

For every custom rule you want to check:

Select On .
In the Convention column, enter the error message you want to display if the rule is violated.
For example, for rule 4.3, All struct fields must follow the specified pattern, you can enter All struct fields must begin with s_. This message appears on the Result Details pane if:
- You specify the Pattern as s_[A-Za-z0-9_]+.
- A structure field in your code does not begin with s_.

In the Pattern column, enter the text pattern.

For example, for rule 4.3, All struct fields must follow the specified pattern, you can enter s_[A-Za-z0-9_]+. Polyspace reports violation of rule 4.3 if a structure field does not begin with s_.

You can use Perl regular expressions to define patterns. For instance, you can use the following expressions.

Expression	Meaning
.	Matches any single character except newline
`[a-z0-9]`	Matches any single letter in the set `a-z`, or digit in the set `0-9`
`[^a-e]`	Matches any single letter not in the set `a-e`
`\d`	Matches any single digit
`\w`	Matches any single alphanumeric character or `_`
`x?`	Matches 0 or 1 occurrence of `x`
`x*`	Matches 0 or more occurrences of `x`
`x+`	Matches 1 or more occurrences of `x`

For frequent patterns, you can use the following regular expressions:

(?!__)[a-z0-9_]+(?!__), matches a text pattern that does not start and end with two underscores.
```
int __text; //Does not match
int _text_; //Matches
```
[a-z0-9_]+_(u8|u16|u32|s8|s16|s32) , matches a text pattern that ends with a specific suffix.
```
int _text_; //Does not match
int _text_s16; //Matches
int _text_s33; // Does not match
```
[a-z0-9_]+_(u8|u16|u32|s8|s16|s32)(_b3|_b8)? , matches a text pattern that ends with a specific suffix and an optional second suffix.
```
int _text_s16; //Matches
int _text_s16_b8; //Matches
```

For a complete list of regular expressions, see Perl documentation.

To use or update an existing coding rules file, click to open the Checkers selection window then do one of the following:

Enter the full path to the file in the field provided
Click Browse and navigate to the file location.

Off (default)

Polyspace does not check your code against custom naming conventions.

Command-Line Information

Parameter: -custom-rules

Value: from-file, specify the file using

Set
                    checkers by file (-checkers-selection-file)

Default: Off

Example (Bug Finder):

polyspace-bug-finder -sources file_name
                    -custom-rules from-file -checkers-selection-file
                    "C:\Standards\custom_config.xml"

Example (Code Prover):

polyspace-code-prover -sources file_name
                    -custom-rules from-file -checkers-selection-file
                    "C:\Standards\custom_config.xml"

Example (Bug Finder Server):

polyspace-bug-finder-server -sources file_name
                    -custom-rules from-file -checkers-selection-file
                    "C:\Standards\custom_config.xml"

Example (Code Prover Server):

polyspace-code-prover-server -sources file_name
                    -custom-rules from-file -checkers-selection-file
                    "C:\Standards\custom_config.xml"

Version History

expand all

R2024a: Removed from Code Prover

If you use the option -custom-rules in a Code Prover analysis, Polyspace issues a warning and the analysis ignores the option. The workflow for checking compliance with naming conventions has been removed from Code Prover. To check for compliance with naming conventions, use Bug Finder. For instance, at the command line, replace this command:

polyspace-code-prover -sources file_name -custom-rules from-file -checkers-selection-file "C:\Standards\custom_config.xml"

with this command:

polyspace-bug-finder -sources file_name -custom-rules from-file -checkers-selection-file "C:\Standards\custom_config.xml"

See Migrate Code Prover Workflows for Checking Coding Standards and Code Metrics to Bug Finder.

R2022a: Option to be removed from Code Prover

If you use the option -custom-rules in a Code Prover analysis, Polyspace issues a warning. The workflow for checking compliance with naming conventions will be removed from Code Prover in a future release. To check for compliance with naming conventions, use Bug Finder. For instance, at the command line, replace this command:

polyspace-code-prover -sources file_name -custom-rules from-file -checkers-selection-file "C:\Standards\custom_config.xml"

with this command:

polyspace-bug-finder -sources file_name -custom-rules from-file -checkers-selection-file "C:\Standards\custom_config.xml"

See Migrate Code Prover Workflows for Checking Coding Standards and Code Metrics to Bug Finder.

R2021b: Use of text format for coding rules file not supported

Since R2019a, the file where you define custom coding rules uses the XML format. Using a text file for this purpose results in an error. You can save selections for custom coding rules and all the coding standards that Polyspace supports in the same file.

Desktop user interface:

If you have a project that contains custom coding rules and coding standard selection files in text format, Polyspace automatically updates and consolidates those files into a single XML file. If your project has conflicting configurations that refer to the same custom selection file, the software saves the consolidated coding standard selection for each configuration to separate XML files.

To update your text files to the XML format manually, in the Coding Standards & Code Metrics node of the Configuration pane, click . In the Checkers selection window, select the files then click Save Changes. Polyspace consolidates the files into a single XML files, and saves this file as filename.xml, where filename is the name of the first selected file alphabetically. For instance, if you select foo.conf and bar.conf, they are saved as bar.conf.xml.

Command-line:

In the command-line or in the IDE extensions, using text files as input to -custom-rules results in an error. To select a custom selection of custom rules, use an XML file.

Use the file custom_rules.xml as a template to create the XML file where you define a custom selection of coding standard checkers. This template file is in polyspaceroot\polyspace\examples\doc_cxx\coding_standards_XML. Here, polyspaceroot is the root installation folder for the Polyspace products, for instance, C:\Program Files\Polyspace\R2024b. To update your script, replace reference to the old file format with the new XML file format.

Example of Configuration File in XML Format

R2021b: Option to be removed from Code Prover

Using -custom-rules in a Code Prover analysis is not recommended. For this purpose, use Bug Finder instead.

R2019b: Use of text format for coding rules file will not be supported

Since R2019a, the file where you define a custom selection of coding standard checkers uses the XML format. You can save custom selections for all the coding standards that Polyspace supports in the same file. If you use a text file, Polyspace issues a warning and converts the text file to XML.