Customize Existing Bug Finder Report Template

This example uses:

In this example, you learn how to customize an existing report template to suit your requirements. A report template allows you to generate a report from your analysis results in a specific format. If an existing report template does not suit your requirements, you can change certain aspects of the template.

For more information on the existing templates, see Bug Finder and Code Prover report (-report-template).

Prerequisites

Before you customize a report template:

See whether an existing report template meets your requirements. Identify the template that produces reports in a format close to what you need. You can adapt this template.
To test a template, generate a report from sample results using the template. See Generate Reports from Polyspace Results.
Make sure you have MATLAB^® Report Generator™ installed on your system.

In this example, you modify the BugFinder template that is available in Polyspace^® Bug Finder™.

View Components in Polyspace Report Template

A report template can be broken into components in MATLAB Report Generator. Each component represents some of the information that is included in a report generated using the template. For example, the component Title Page represents the information in the title page of the report.

In this example, you view the components of the BugFinder template.

Add paths to Polyspace-specific report components by pointing to subfolders of your Polyspace installation folder. At the MATLAB command prompt, enter:
```
addpath(fullfile(polyspaceroot, 'toolbox', 'polyspace', 'psrptgen', 'psrptgen'));
addpath(fullfile(polyspaceroot, 'toolbox', 'polyspace', 'psrptgen', 'templates'));
addpath(fullfile(polyspaceroot, 'toolbox', 'polyspace', 'psrptgen', 'psrptgen', 'udd'));
```
Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2024b. If you integrate MATLAB and Polyspace, you can use the polyspaceroot function in MATLAB to find the installation folder location. See Integrate Polyspace with MATLAB and Simulink.
Open the Report Explorer interface. At the MATLAB command prompt, enter:
```
report
```
Open the BugFinder template in the Report Explorer interface.
The BugFinder template is in polyspaceroot/toolbox/polyspace/psrptgen/templates/bug_finder where polyspaceroot is the Polyspace installation folder.

Your template opens in the Report Explorer. On the left pane, you can see the components of the template. You can click each component and view the component properties on the right pane.

Some components of the BugFinder template and their purpose are described below.

Component	Purpose
`Title Page` (MATLAB Report Generator)	Inserts title page in the beginning of report
`Chapter/Subsection` (MATLAB Report Generator)	Groups portions of report into sections with titles
`Code Verification Summary`	Inserts summary table of Polyspace analysis results
`Logical If` (MATLAB Report Generator)	Executes child components only if a condition is satisfied
`Run-time Checks Summary Ordered by File`	Inserts a table with Polyspace Bug Finder defects grouped by file

To understand how the template works, compare the components in the template with a report generated using the template.

For more information on the components, see Work with Components (MATLAB Report Generator). For information on Polyspace-specific components, see Generate Reports.

Note

Some of the component properties are set using internal expressions. Although you can view the expressions, do not change them. For instance, the conditions specified in the Logical If components in the BugFinder template are specified using internal expressions.

Change Components of Template

In the Report Explorer interface, you can:

Change properties of existing components of your template.
Add new components to your template or remove existing components.

In this example, you add a component to the BugFinder template so that the template includes only Integer division by zero and Float division by zero defects in a report.

Open the BugFinder template in the Report Explorer interface and save it elsewhere with a different name, for instance, BugFinder_Division_by_Zero.
Add a new global component that filters every defect except division by zero from the BugFinder_Division_by_Zero template. The component is global because it applies to the full report and not one chapter of the report.
To perform this action:
1. Drag the component Report Customization (Filtering) located under Polyspace in the middle pane and place it above the Title Page component. The positioning of the component ensures that the filters apply to the full report and not one chapter of the report.
2. Select the Report Customization (Filtering) component. On the right pane, you can set the properties of this component. By default, the properties are set such that all results are included in the report.
  To include only Integer division by zero and Float division by zero defects, under the Advanced Filters group, enter Integer division by zero and Float division by zero in the Check types to include field.
  
  You can also use MATLAB regular expressions in this field to exclude results. For instance, to exclude the result Dead code, enter ^(?!Dead code).*. The report generator applies the regular expressions against the Polyspace result names. For instance:
  - The caret ^ indicates that the subsequent pattern must be at the beginning of the string.
  - The characters (?!pattern).* indicates that the subsequent pattern must not appear in the string.
  Together, the regular expression ^(?!Dead code).* indicates that Polyspace result names beginning with Dead code must be excluded from the report.See Regular Expressions.
  You can toggle between activating and deactivating this component. Right-click the component and select Activate/Deactivate Component.
Change an existing chapter-specific component so that it does not override the global filter you applied in the previous step. If you prevent the overriding, the chapter-specific component follows the filtering specifications in the global component.
To perform this action:
1. On the left pane, select the Run-time Checks Details Ordered by Color/File component. This component produces tables in the report with details of run-time checks found in Polyspace Bug Finder.
  The right pane shows the properties of this component.
2. Clear the Override Global Report filter box.
Save the BugFinder_Division_by_Zero template after making your changes.
In the Polyspace user interface, create a report using both the BugFinder and BugFinder_Division_by_Zero template from results containing division by zero defects. Compare the two reports.
For instance:
1. Open Help > Examples > Bug_Finder_Example.psprj.
  The demo result contains Integer division by zero and Float division by zero defects.
2. Create a PDF report using the BugFinder template. See Generate Reports from Polyspace Results.
  In the report, open Chapter 5. Defects (in your version of the product, the chapter number might be different). You can see all defects from the example result. Close the report.
3. Create a PDF report using the BugFinder_Division_by_Zero template. In the Run Report window, use the Browse button to add the BugFinder_Division_by_Zero template to the existing template list.
  In the report, open Chapter 6. Defects (in your version of the product, the chapter number might be different). You see only Integer division by zero and Float division by zero defects.
  Note
  After you add the template to the existing list of templates, before generating the report, make sure to select the newly added template.