polyspaceBugFinder

R2026b

Run Polyspace Bug Finder analysis from MATLAB

For easier scripting, run Polyspace^® analysis using a polyspace.Project object.

Syntax

polyspaceBugFinder

status = polyspaceBugFinder(projectFile)

status = polyspaceBugFinder(optsObject)

status = polyspaceBugFinder(projectFile, '-nodesktop')

status = polyspaceBugFinder(resultsFile)

status = polyspaceBugFinder('-results-dir', resultsFolder)

status = polyspaceBugFinder('-sources', sourceFiles)

status = polyspaceBugFinder('-sources', sourceFiles, Name,Value)

[status, jobID] = polyspaceBugFinder(___, '-batch', '-scheduler', scheduler)

Description

polyspaceBugFinder opens Polyspace Bug Finder™.

status = polyspaceBugFinder(projectFile) opens a Polyspace project file in Polyspace Bug Finder.

status = polyspaceBugFinder(optsObject) runs an analysis on the Polyspace options object in MATLAB^®.

Note

When you use a Polyspace options object to run an analysis, use only the Polyspace options object to specify options of the analysis. Using name-value arguments is not supported when the first argument is a Polyspace options object.

status = polyspaceBugFinder(projectFile, '-nodesktop') runs an analysis on the Polyspace project file in MATLAB. If the project has multiple build or static analysis configurations, the analysis runs using the active variants. To see which configuration variants are active, open the project in the Polyspace Platform user interface. Then, open the Configuration pane and check the Build and Static Analysis tabs.

status = polyspaceBugFinder(resultsFile) opens a Polyspace results file in Polyspace Bug Finder.

status = polyspaceBugFinder('-results-dir', resultsFolder) opens a Polyspace results file from resultsFolder in Polyspace Bug Finder.

status = polyspaceBugFinder('-sources', sourceFiles) runs a Polyspace Bug Finder analysis on the source files specified in sourceFiles.

status = polyspaceBugFinder('-sources', sourceFiles, Name,Value) runs a Polyspace Bug Finder analysis on the source files with additional options specified by one or more Name,Value pair arguments.

Note

Before you run Polyspace from MATLAB, you must link your Polyspace and MATLAB installations. See Integrate Polyspace with MATLAB and Simulink.

[status, jobID] = polyspaceBugFinder(___, '-batch', '-scheduler', scheduler) offloads the analysis to a remote cluster. Here, scheduler specifies the head node of the cluster that manages the analysis submissions from multiple clients. See also Manipulate Two Jobs in the Cluster.

Examples

Open Polyspace Projects from MATLAB

This example shows how to open a Polyspace project file with extension .psprjx from MATLAB. In this example, you open the project file Bug_Finder_Example.psprjx from the folder polyspaceroot\polyspace\examples\cxx\Bug_Finder_Example.

Open the project Bug_Finder_Example.psprjx in the Polyspace Platform user interface.

prjFile = fullfile(polyspaceroot, 'polyspace', 'examples', 'cxx', ...
         'Bug_Finder_Example', 'Bug_Finder_Example.psprjx');
polyspaceBugFinder(prjFile);

Open Polyspace Results from MATLAB

This example shows how to open a Polyspace results file from MATLAB. In this example, you open the results file from the folder polyspaceroot\polyspace\examples\cxx\Bug_Finder_Example\Module_1\BF_Result.

Open the results of resFolder.

resFolder = fullfile(polyspaceroot, 'polyspace', 'examples',  ...
         'cxx', 'Bug_Finder_Example', 'Module_1', 'BF_Result');
polyspaceBugFinder('-results-dir',resFolder)

Run Polyspace Analysis with Options Object

This example shows how to run a Polyspace analysis from the MATLAB command line using objects.

Create an options object and add the source file and include folder to the properties.

opts = polyspace.Options;
opts.Sources = {fullfile(polyspaceroot, 'polyspace', 'examples',...
    'cxx', 'Bug_Finder_Example', 'sources', 'numerical.c')};
opts.EnvironmentSettings.IncludeFolders = {fullfile(polyspaceroot, 'polyspace', 'examples',...
    'cxx', 'Bug_Finder_Example', 'sources')};
opts.ResultsDir = fullfile(pwd,'results');

Run the analysis and view the results.

polyspaceBugFinder(opts);
polyspaceBugFinder('-results-dir',opts.ResultsDir)

Run Polyspace Analysis from MATLAB with DOS/UNIX Options

This example shows how to run a Polyspace analysis in MATLAB using DOS/UNIX-style options.

Run the analysis and open the results.

sourceFiles = fullfile(polyspaceroot, 'polyspace', 'examples',...
    'cxx', 'Bug_Finder_Example', 'sources', 'numerical.c');
includeFolders = fullfile(polyspaceroot, 'polyspace', 'examples',...
    'cxx', 'Bug_Finder_Example', 'sources');
resultsDir = fullfile(pwd,'results');
polyspaceBugFinder('-sources',sourceFiles, ...
             '-I',includeFolders, ...
             '-results-dir',resultsDir);

To view the results, enter:

polyspaceBugFinder('-results-dir',resultsDir);

Run Polyspace Analysis with Coding Rules Checking

This example shows two different ways to customize an analysis in MATLAB. You can customize as many additional options as you want by changing properties in an options object or by using name-value arguments. Here you specify checking of MISRA C™ 2012 coding rules.

Create variables to save the source file path and results folder path. You can use these variables for either analysis method.

sourceFileName = fullfile(polyspaceroot, 'polyspace','examples', 'cxx', 'Bug_Finder_Example','sources','dataflow.c');
resFolder1 = fullfile('Polyspace_Results_1');
resFolder2 = fullfile('Polyspace_Results_2');

Analyze coding rules with an options object.

opts = polyspace.Options();
opts.Sources = {sourceFileName};
opts.ResultsDir = resFolder1;
opts.CodingRulesCodeMetrics.MisraC3Subset = 'all';
opts.CodingRulesCodeMetrics.EnableMisraC3 = true;
polyspaceBugFinder(opts);
polyspaceBugFinder('-results-dir',resFolder1);

Analyze coding rules with DOS/UNIX options.

polyspaceBugFinder('-sources',sourceFileName,'-results-dir',resFolder2,'-misra3','all');
polyspaceBugFinder('-results-dir',resFolder2);

Input Arguments

optsObject — Polyspace options object name

object handle

Polyspace options object name, specified as the object handle.

To create an options object, use one of the Polyspace options classes.

Example: opts

projectFile — Name of .psprjx file

character vector

Name of project file with extension .psprjx, specified as a character vector.

If the file is not in the current folder, projectFile must include a full or relative path.

Example: 'C:\Polyspace_Projects\myProject.psprjx'

Data Types: char

resultsFile — Name of .psbf file

character vector

Name of results file with extension .psbf, specified as a character vector.

If the file is not in the current folder, resultsFile must include a full or relative path.

Example: 'myResults.psbf'

Data Types: char

resultsFolder — Name of results folder

character vector

Name of results folder, specified as a character vector. The folder must contain the results file with extension .psbf. If the results file resides in a subfolder of the specified folder, this command does not open the results file.

If the folder is not in the current folder, resultsFolder must include a full or relative path.

Example: 'C:\Polyspace\Results\'

Data Types: char

sourceFiles — Comma-separated names of C or C++ files

character vector

Comma-separated C or C++ source file names, specified as a single character vector.

If the files are not in the current folder, sourceFiles must include a full or relative path.

Example: 'myFile.c', 'C:\mySources\myFile1.c,C:\mySources\myFile2.c'

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: '-target','i386','-compiler','gnu4.6' specifies that the source code is intended for an i386 target and contains non-ANSI C syntax for GCC 4.6.

For option names and values, see the Command-Line Information section in Configuration.

Output Arguments

status — Status indicating whether the Polyspace Bug Finder analysis completed successfully or not

true | false

If the Polyspace Bug Finder analysis completes without error, status is false. Otherwise, it is true.

The analysis might fail for multiple reasons, including:

• You provided a source file, project file, or results file that does not exist.

• You specified an invalid path.

• One of your files did not compile.

jobID — ID of job associated with submitted analysis on the remote cluster

integer

If you offload the Polyspace analysis to a remote cluster, the command returns the ID of the job associated with the submitted analysis on the remote cluster. You can use this ID to manage the job or download the analysis results once the job completes. See also polyspaceJobsManager.

Version History

Introduced in R2013b

R2026a: Support for Polyspace Platform project files (.psprjx)

Starting in R2026a, the Polyspace Platform user interface is the default user interface for static analysis. To support this change, the polyspaceBugFinder command accepts Polyspace Platform project files (.psprjx) as input.

If you specify a classic .psprj file, the command first converts it to a .psprjx file with the same name and saves it in the same location. If the .psprj file contains multiple modules, polyspaceBugFinder converts and analyzes only the first module. To analyze every module in the .psprj file, use polyspace-project -convert-psprj-to-workspace to create a workspace with one Polyspace Platform project for each module. Then, run polyspaceBugFinder on each project in the workspace.