Get Started with Polyspace Analysis by Using MATLAB

This tutorial shows how to analyze handwritten C/C++ code by running a Polyspace^® analysis from the MATLAB^® Command Window or the MATLAB Editor. To analyze code generated from a Simulink^® model, see Run Polyspace Analysis on Code Generated from Simulink Model.

Prerequisites

Integrate Polyspace with MATLAB before you run a Polyspace analysis from the MATLAB Command Window. See Integrate Polyspace with MATLAB and Simulink.

Run Polyspace Analysis by Using MATLAB

You analyze handwritten C code by configuring and then starting a Polyspace analysis from the MATLAB Command Window or the MATLAB Editor.

To perform a Polyspace analysis, create a polyspace.Project object, specify the source files and the analysis options, and then start the analysis by using this object. To create a polyspace.Project object, use the function polyspace.Project.

psPrj = polyspace.Project;

In this tutorial, the handwritten code in the file numerical.c is analyzed. The file numerical.c is part of your Polyspace software. This source file and the header files required to analyze it can be found in the folder polyspaceroot\polyspace\examples\cxx\Bug_Finder_Example\sources. Here, polyspaceroot is the location of the Polyspace installation folder in your development environment. Create the paths to these source and header files by using the function fullfile.

% Create the Path to source and header files
sourceFile = fullfile(polyspaceroot, 'polyspace', ... 
    'examples', 'cxx', 'Bug_Finder_Example', 'sources', 'numerical.c');
includeFolder = fullfile(polyspaceroot, 'polyspace', ... 
    'examples', 'cxx', 'Bug_Finder_Example', 'sources');

Associate the source and header files with the psPrj object.

% Associate the source and header files
psPrj.Configuration.Sources = {sourceFile};
psPrj.Configuration.EnvironmentSettings.IncludeFolders = {includeFolder};

Configure the Polyspace analysis options. For instance, you can specify the compiler for the Polyspace analysis and check for violation of specific coding rules. You can also specify a folder where you store the generated results. For instance, store the results in the folder 'results' in the current working directory.

% Specify target compiler
psPrj.Configuration.TargetCompiler.Compiler = 'gnu4.9';
% Enable Mchecking for MISRA C violation
psPrj.Configuration.CodingRulesCodeMetrics.EnableMisraC3 = true;
psPrj.Configuration.CodingRulesCodeMetrics.MisraC3Subset = 'mandatory';
% Specify results folder
psPrj.Configuration.ResultsDir = fullfile(pwd,'results');

The variable pwd contains the path of the current working directory. For details on configurable Polyspace analysis options, see polyspace.Project.Configuration Properties.

Start the Polyspace analysis by using the function run.

% start BugFinder analysis
bfStatus = run(psPrj, 'bugFinder');

The progress of the Polyspace analysis appears in the MATLAB Command Window. When the analysis is successful, bfStatus is set to 0.

The Polyspace analysis result consists of a list of Bug Finder defects. To view a summary of the Bug Finder defects in a MATLAB table, use the function getSummary. For more details about obtaining summary of different kinds of results, see getSummary.

% Obtain list of Bug Finder defects
resObj = psPrj.Results;
bfSummary = getSummary(resObj, 'defects');

The Bug Finder defects are listed in the 9x4 table bfSummary.

List of Bug Finder results shown in a MATLAB table.

Frequently Used MATLAB Functions

This table lists some MATLAB functions that you can use for automating a Polyspace analysis from the MATLAB Editor or Command Window.

Function	Application
`fopen`	Opens a file for binary read access. For instance, use this function to read an error log file.
`fclose`	Closes a file that was opened by using `fopen`. For instance, use this function to close an error log file after reading it.
`open`	Opens a file outside MATLAB in an appropriate application. For instance, use this function to open `psprj` files in the Polyspace UI.
`exist`	Checks for the existence of an entity. For instance, use this function to check if a particular folder or file already exists.
`delete`	Deletes a file or an object. For instance, use this function to delete older results or unnecessary options objects.
`questdlg`	Creates a configurable dialog box. Use this function to change different settings of a Polyspace analysis in a script. For instance, you can choose to enable different coding rules based on the output of this function.
`clear`	Clears the workspace by deleting all objects. You can this function at the beginning of the Polyspace analysis.
`clc`	Clears all text from the MATLAB Command Window.
`fullfile`	Builds full file names from its parts. For instance, use this function to construct the full paths to source files.
`char`	Converts an array to a character array. For instance, use this function to construct the input arguments to functions that take character arrays.
`string`	Converts a variable into string arrays. For instance, use this function to construct input arguments for functions that take strings.
`dir`	Lists the content of the current working folder. For instance, use this function to find specific files or folders in the current folder.
`system`	Executes operating system commands and returns their outputs. For instance, use this function to execute a command-line script without exiting MATLAB.
`disp`	Displays the value of the input variable. For instance, use this function for debugging code, similar to how `printf()` is used in C code.
`visdiff`	Compares two files or folder. For instance, use this function to compare results from different Polyspace analysis to see the difference.
`ismember`	Determines if the elements in one array are also present in another array. For instance, use this function to check if a checker or coding rule is enabled in a Polyspace analysis, or to filter results to find a specific check.
`any`	Determines if any array elements are nonzero. For instance, use this function to check for new results.
`nnz`	Returns the number of nonzero matrix elements. For instance, use this function to check for new results.
`fieldnames`	Reads a structure, a Java^® object, or a Microsoft^® COM object and returns the field names. For instance, use this function to read and manipulate tables.