Customize Existing Code Prover Report Template

This example uses:

In this example, you learn how to customize an existing report template to suit your requirements. A report template defines the content and formatting of reports generated from analysis results. 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 verification 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 Developer template that is available in Polyspace^® Code Prover™.

View Components of 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 Developer 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 Developer template in the Report Explorer interface.
The Developer template is in polyspaceroot/toolbox/polyspace/psrptgen/templates 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.

Report Explorer window showing components in the left pane and the component properties displayed in the right pane.

Some components of the Developer 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 Code Prover checks 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 all 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 Developer 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 Developer template that filters Unreachable code checks from a report generated using the template.

Open the Developer template in the Report Explorer interface and save it elsewhere with a different name, for instance, Developer_without_UNR.
Add a new global component that filters Unreachable code checks from the Developer_without_UNR 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 exclude Unreachable code checks, under the Advanced Filters group, enter ^(?!Unreachable code).* in the Check types to include field.
  You can enter MATLAB regular expressions in this field. 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 ^(?!Unreachable code).* indicates that Polyspace result names beginning with Unreachable code must be excluded from the report. See Regular Expressions and Complete List of Polyspace Code Prover Results.
  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 Code Prover.
  The right pane shows the properties of this component.
2. Clear the Override Global Report filter box.
Save the Developer_without_UNR template after making your changes.
In the Polyspace user interface, create a report using both the Developer and Developer_without_UNR template from results containing Unreachable code checks. Compare the two reports.
For instance:
1. Open Help > Examples > Code_Prover_Example.psprj.
  The demo result contains Unreachable code checks.
2. Create a pdf report using the Developer template.
  In the report, open Chapter 5. Polyspace Run-Time Checks Results (in your version of the product, the chapter number might be different). You can see gray Unreachable code checks. Close the report.
3. Create a pdf report using the Developer_without_UNR template. In the Run Report window, use the Browse button to add the Developer_without_UNR template to the existing template list.
  In the report, open Chapter 6. Polyspace Run-Time Checks Results (in your version of the product, the chapter number might be different). You do not see gray Unreachable code checks.
  Note
  After you add the template to the existing list of templates, before generating the report, make sure to select the newly added template.

Further Exploration

Modify the Developer template such that the file initialisations.c is excluded from a report generated using the template. Generate a report from Code_Prover_Example results using your modified template and verify that the file initialisations.c is excluded from the report.

Hint: The regular expression you must use is ^(?!.*initialisations.c).*

For more examples, see Sample Report Template Customizations.