Main Content

Run Polyspace Bug Finder in the Polyspace Platform User Interface

Polyspace® Bug Finder™ identifies run-time errors, concurrency issues, security vulnerabilities, and other defects in C and C++ embedded software. Using static analysis, including semantic analysis, Bug Finder analyzes control flow, data flow, and interprocedural behavior. By highlighting defects as soon as they are detected, Bug Finder lets you triage and fix bugs early in the development process.

You can run Bug Finder on complete C/C++ projects from the Polyspace Platform user interface or by using scripts. For more information, see:

  • Run Polyspace in Polyspace Platform User Interface

    If this is your first time using Polyspace, start by using the Polyspace Platform user interface. You can get help from features such as a the new project menu, assisted configuration, and summarized analysis log.

  • Run Polyspace from Windows or Linux Command Line

    Once you set up a project in the Polyspace Platform user interface and complete a few trial runs, you can export the configuration to scripts that you run automatically or on demand. You can also run a Polyspace analysis directly from the command line in your operating system. You can then save the commands in batch files (Windows) or shell scripts (Linux) for later runs. If you are running Polyspace Server products using continuous integration tools such as Jenkins, you can reuse your scripts from the Polyspace desktop products.

  • Run Polyspace in MATLAB

    If you have a MATLAB installation, it is particularly easy to write scripts to run a Polyspace analysis. You get all the benefits of scripting in the MATLAB environment, such as, automatic help on function syntaxes. After running an analysis, you can create your own visualization of the results using MATLAB graphics and visualization tools.

Example Files

To follow the steps in this tutorial, copy the files from polyspaceroot\polyspace\examples\cxx\Bug_Finder_Example\sources to another folder. Here, polyspaceroot is the Polyspace installation folder, for example, C:\Program Files\Polyspace\R2024b.

Run Polyspace in Polyspace Platform User Interface

Open the Polyspace Platform User Interface

Double-click the polyspace-desktop-ui executable in polyspaceroot\polyspace\bin. Here, polyspaceroot is the Polyspace installation folder, for example, C:\Program Files\Polyspace\R2024b. See Installation Folder.

If you open the old desktop user interface and have not set the Polyspace Platform user interface as your default user interface, click the Try the new desktop UI button and optionally select the check box to make Polyspace Platform user interface the new default user interface.

If you set up a shortcut to Polyspace on your desktop or the Start menu in Windows®, double-click the shortcut.

Add Source Files

To run an analysis, you have to create a new Polyspace project. A Polyspace project points to source and include folders on your file system.

On the left of the Start Page pane, click New Project. Alternatively, select New > Project in the taskbar.

Select a location to save your project and enter your project name. Continue by adding your source and include folders. Select Add Source Folder from the taskbar and navigate to your source files folder. In this tutorial, add the folder in which you saved the source and include files.

Your new project is in the Projects pane. Your source folders are added to the Code node in the project. You can add more files or folders later by right-clicking the project or by using the buttons in the toolstrip.

Later, you can group your projects by saving them to a workspace. A workspace allows you to group related projects and open all the projects at once. For more information on how to use workspaces, see Manage Related Projects in Polyspace Platform User Interface Using Workspaces.

Configure and Run Polyspace

You can change the default options associated with a Polyspace analysis.

Double-click the Configuration node in the Projects pane. On the Configuration pane, change options as needed. For this tutorial, on the Static Analysis tab, select Coding Rules & Code Metrics. Select the option Use custom checkers file and click the folder icon. The Checkers Selection window opens. Select MISRA C:2023 in the sidebar and select All above the list of checks. Click Save changes to save your checkers selection file for your project and close the Checkers Selection window.

Checkers selection window with the All check box selected for MISRA C:2023 rules

For more information on configuration options, point to each option. In the tooltip that appears, click the More help link for context-sensitive help on the options.

Option tooltip for the Use custom checkers file option

Select the Project tab to return to your project toolstrip. To start an analysis, click Find Defects in the toolstrip.

A pane opens where you can follow the progress of analysis. After Polyspace completes the analysis, your results appear in the Results pane. Double-click the results file to open the results dashboard.

Additional Information

For additional information about running Polyspace in the Polyspace Platform user interface, see:

Run Polyspace from Windows or Linux Command Line

You can run Bug Finder from the Windows or Linux® command line with batch (.bat) files or shell (.sh) scripts.

To run a Bug Finder analysis, use the polyspace-bug-finder command.

To save typing the full path to the command, add the path polyspaceroot\polyspace\bin to the Path environment variable on your operating system. Here, polyspaceroot is the Polyspace installation folder, for example, C:\Program Files\Polyspace\R2024b.

Navigate to the folder where you saved the files. Enter this command:

polyspace-bug-finder -sources numerical.c,dataflow.c -I . -results-dir .
Here, . indicates the current folder. The options used are:

  • -sources — Specify comma-separated source files.

  • -I — Specify a path to an include folder. Use the -I option each time you want to add a different include folder.

  • -results-dir — Specify the path to the folder where Polyspace Bug Finder saves results.

    Note that the results folder is cleaned up and repopulated each time you run an analysis. To avoid accidental removal of files during the cleanup, instead of using an existing folder that contains other files, specify a dedicated folder for the Polyspace Bug Finder results.

When the analysis is complete, Bug Finder saves the results in the file ps_results.psbf. You can open this file from the Polyspace Platform user interface by using this command:

polyspace ps_results.psbf

Instead of specifying comma-separated sources directly on the command line, you can list the sources in a text file (one file per line). Use the option -sources-list-file to specify this text file.

Additional Information

For more information about running Polyspace from the Windows or Linux command line, see:

Run Polyspace in MATLAB

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

To run an analysis, use a polyspace.Project object. The object has two properties:

  • Configuration — Specify analysis options such as sources, includes, compiler and results folder using this property.

  • Results — After Polyspace completes an analysis, read the analysis results to a MATLAB table using this property.

To run the analysis, use the run method of this object.

To run Polyspace on the example file numerical.c in polyspaceroot\polyspace\examples\cxx\Bug_Finder_Examples\sources, enter the following at the MATLAB command prompt.

proj = polyspace.Project

% Configure analysis
proj.Configuration.Sources = {fullfile(polyspaceroot, 'polyspace', ... 
    'examples', 'cxx', 'Bug_Finder_Example', 'sources', 'numerical.c')};
proj.Configuration.TargetCompiler.Compiler = 'gnu4.9';
proj.Configuration.EnvironmentSettings.IncludeFolders = {fullfile(polyspaceroot, ...
'polyspace', 'examples', 'cxx', 'Bug_Finder_Example', 'sources')}
proj.Configuration.ResultsDir = fullfile(pwd,'results');

% Run analysis
bfStatus = proj.run('bugFinder');

% Read results
resObj = proj.Results;
bfSummary = getSummary(resObj, 'defects');
bfResults = getResults(resObj, 'readable');

When the analysis is complete, Bug Finder saves the results in the file ps_results.psbf. You can open this file from the Polyspace Platform user interface by using these commands:

resultsFile = fullfile(proj.Configuration.ResultsDir,'ps_results.psbf');
polyspaceBugFinder(resultsFile)

Additional Information

For more information about running Polyspace in MATLAB, see:

Related Topics