polyspace-report-generator

(System Command) Generate reports from Polyspace analysis results stored locally or on Polyspace Access

collapse all in page

The following options will be removed in a future release:

  • -generate-results-list-file

  • -generate-variable-access-file

  • -key-mode

Use polyspace-results-export instead for exporting results to an external format such as CSV or JSON.

Use the VariableAccess report template for generating a global variables accesses report. See Bug Finder and Code Prover report (-report-template).

Syntax

polyspace-report-generator -template outputTemplate [reporting options]
polyspace-report-generator -generate-results-list-file [-results-dir resultsFolder] [-set-language-english]
polyspace-report-generator -generate-variable-access-file [-results-dir resultsFolder] [-set-language-english]
polyspace-report-generator -configure-keystore
polyspace-report-generator -template outputTemplate -host hostName -run-id runID [polyspace access options] [reporting options]
polyspace-report-generator -generate-results-list-file -host hostName -run-id runID [polyspace access options] [-set-language-english]
polyspace-report-generator -generate-variable-access-file -host hostName -run-id runID [polyspace access options] [-set-language-english]

Description

The polyspace-report-generator system command generates PDF, Word, or HTML reports from Polyspace® static analysis results by using predefined or custom templates.

Generate Reports from Local Results

Note

This Polyspace command is available in polyspaceroot\polyspace\bin. Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026a (see also Installation Folder for desktop products or Installation Folder for server products). To avoid typing the full path to this command, add this location to the PATH environment variable in your operating system.

polyspace-report-generator -template outputTemplate [reporting options] generates a report by using the template outputTemplate for the local analysis results that you specify with reporting options.

By default, reports for results from project-name are stored as project-name_report-name in the PathToFolder\Polyspace-Doc folder. PathToFolder is the results folder of project-name.

example

polyspace-report-generator -generate-results-list-file [-results-dir resultsFolder] [-set-language-english] exports the analysis results stored locally in resultsFolder to a tab-delimited text file. The file contains the result information available on the Results List pane in the user interface. For more information on the exported results list, see View Exported Results.

By default, the results file for results from project-name is stored in the PathToFolder\Polyspace-Doc folder. PathToFolder is the results folder of project-name.

For exporting results to a tab-delimited text file, the polyspace-results-export command is preferred.

polyspace-report-generator -generate-variable-access-file [-results-dir resultsFolder] [-set-language-english] exports the list of global variables in your code from the Code Prover analysis stored locally in FOLDER to a tab-delimited text file. The file contains the information available on the Variable Access pane in the user interface. For more information on the exported variables list, see View Exported Variable List.

By default, the variables file for results from project-name is stored in the PathToFolder\Polyspace-Doc folder. PathToFolder is the results folder of project-name.

polyspace-report-generator -configure-keystore configures the report generator to communicate with Polyspace Access™ over HTTPS.

Run this one-time configuration step if Polyspace Access is configured to use the HTTPS protocol and you do not have a Polyspace Bug Finder™ desktop license, or you have a desktop license but you have not configured the desktop UI to communicate with Polyspace Access over HTTPS. Before running this command, generate a client keystore to store the SSL certificate that Polyspace Access uses for HTTPS. See Generate a Client Keystore (Polyspace Access).

example

Generate Reports from Polyspace Access Results

polyspace-report-generator -template outputTemplate -host hostName -run-id runID [polyspace access options] [reporting options] generates a report by using the template outputTemplate for the analysis results corresponding to run runID on Polyspace Access. hostName is the fully qualified host name of the machine that hosts Polyspace Access.

By default, reports for results from project-name are stored as project-name_report-name in the PathToFolder\Polyspace-Doc folder. PathToFolder is the path from which you call the command.

example

polyspace-report-generator -generate-results-list-file -host hostName -run-id runID [polyspace access options] [-set-language-english] exports the analysis results corresponding to run runID on Polyspace Access to a tab-delimited text file. The file contains the result information available on the Results List pane in the Polyspace Access web interface. hostName is the fully qualified host name of the machine that hosts Polyspace Access. For more information on the exported results list, see Results List in Polyspace Access Web Interface (Polyspace Access).

By default, the results file for results from project-name is stored in the PathToFolder\Polyspace-Doc folder. PathToFolder is the path from which you call the command.

For exporting results to a tab-delimited text file, the polyspace-results-export command is preferred.

polyspace-report-generator -generate-variable-access-file -host hostName -run-id runID [polyspace access options] [-set-language-english] exports the list of global variables in your code from the Code Prover analysis corresponding to run runID on Polyspace Access to a tab-delimited text file. The file contains the information available on the Variable Access pane in the Polyspace Access web interface. hostName is the fully qualified host name of the machine that hosts Polyspace Access. For more information on the exported variables list, see View Exported Variable List.

By default, the variables file for results from project-name is stored in the PathToFolder\Polyspace-Doc folder. PathToFolder is the path from which you call the command.

example

Examples

collapse all

This example shows how to generate PDF reports on the command line from a Bug Finder results file (.psbf file) stored locally on your machine.

Create a variable template_path to store the path to the report templates and create a variable report_templates to store a comma-separated list of templates to use. The commands below use the SET command available on the Windows® command prompt. Replace the SET command appropriately for other terminals.

SET template_path="C:\Program Files"\Polyspace\R2026a\toolbox\polyspace\psrptgen\templates\bug_finder
SET report_templates=%template_path%\BugFinder.rpt,%template_path%\CodingStandards.rpt
This example uses the following report templates:

  • BugFinder: A report generated using this template shows all Bug Finder results (both defects and coding standard violations).

  • CodingStandards: A report generated using this template contains a file-by-file breakdown of coding standard violations.

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

Using the templates that you specified in the variable report_templates, generate a PDF report from analysis results stored in the folder C:\Polyspace_Workspace\myProject\Module_1\BF_Result.

polyspace-report-generator -template %report_templates% -results-dir C:\Polyspace_Workspace\myProject\Module_1\BF_Result -format PDF

This example shows how to generate PDF reports on the command line from a Code Prover results file (.pscp file) stored locally on your machine.

Create a variable template_path to store the path to the report templates and create a variable report_templates to store a template to use. The commands below use the SET command available on the Windows command prompt. Replace the SET command appropriately for other terminals.

SET template_path="C:\Program Files"\Polyspace\R2026a\toolbox\polyspace\psrptgen\templates\
SET report_templates=%template_path%\Developer.rpt
This example uses the Developer template, which has dedicated chapters on reporting of run-time errors. For more information on the templates, see Bug Finder and Code Prover report (-report-template).

Using the templates that you specified in the variable report_templates, generate a PDF report from analysis results stored in the folder C:\Polyspace_Workspace\myProject\Module_1\CP_Result.

polyspace-report-generator -template %report_templates% -results-dir C:\Polyspace_Workspace\myProject\Module_1\CP_Result -format PDF

If you configure Polyspace Access to use the HTTPS protocol, you must generate a client keystore where you store the SSL certificate that Polyspace Access uses, and configure polyspace-report-generator to use that keystore. See Generate a Client Keystore (Polyspace Access). This one-time configuration enables the report generator to communicate with Polyspace Access over HTTPS.

To configure the report generator with a client keystore, use the polyspace-report-generator -configure-keystore command. Follow the prompts to provide the URL you use to log into Polyspace Access, the full path to the keystore file you generated, and the keystore password.

polyspace-report-generator -configure-keystore
Location: US, user name: jsmit, id: 62600@us-jsmith, print mode: false
Enter the Polyspace Access URL using form  http[s]://<host>:<port> :
https://myAccessServer:9443
Enter full path to client keystore file :
C:\R2019b\ssl\client-cert.jks
Enter client keystore password :

The keystore has been configured

You must run the keystore configuration command again if:

  • The Polyspace Access URL changes, for instance if you use a different port number.

  • The path to the keystore file changes.

  • The keystore password changes.

Note

To generate reports of results on Polyspace Access at the command line, you must have a Polyspace Bug Finder Server™ or Polyspace Code Prover™ Server installation.

Suppose that you want to generate a report and export the variables list for the results of a Code Prover analysis stored on the Polyspace Access database.

To connect to Polyspace Access, provide a host name and your login credentials including your encrypted password. To encrypt your password, use the polyspace-access command and enter your user name and password at the prompt. 

polyspace-access -encrypt-password 
login: jsmith
password:
CRYPTED_PASSWORD LAMMMEACDMKEFELKMNDCONEAPECEEKPL
Command Completed

Store the login and encrypted password in a credentials file and restrict read and write permission on this file. Open a text editor, copy these two lines in the editor, then save the file as myCredentials.txt for example.

 -login jsmith
 -encrypted-password LAMMMEACDMKEFELKMNDCONEAPECEEKPL
To restrict the file permissions, right-click the file and select the Permissions tab on Linux® or the Security tab on Windows.

To specify project results on Polyspace Access, specify the run ID of the project. To obtain a list of projects with their latest run IDs, use the polyspace-access -list-project (Polyspace Access) command. 

polyspace-access -host myAccessServer -credentials-file myCredentials.txt -list-project
Connecting to https://myAccessServer:9443
Connecting as jsmith
Get project list with the last Run Id
Restricted/Code_Prover_Example (Code Prover) RUN_ID 14
public/Bug_Finder_Example (Bug Finder) RUN_ID 24
public/CP/Code_Prover_Example (Polyspace Code Prover) RUN_ID 16
public/Polyspace (Code Prover) RUN_ID 28
Command Completed

Generate a Developer report for results with run ID 16 from the Polyspace Access instance with host name myAccessServer. The URL of this instance of Polyspace Access is https://myAccessServer:9443.

SET template_path=^
"C:\Program Files\Polyspace\R2019a\toolbox\polyspace\psrptgen\templates"

polyspace-report-generator -credentials-file myCredentials.txt ^
-template %template_path%\Developer.rpt ^
-host myAccessServer ^
-run-id 16 ^
-output-name myReport
The command creates report myReport.docx by using the template that you specify. The report is stored in folder Polyspace-Doc on the path from which you called the command.

Generate a tab-delimited text file that contains a list of global variables in your code for the specified analysis results.

polyspace-report-generator -credentials-file myCredentials.txt^
-generate-variable-access-file ^
-host myAccessServer ^
-run-id 16
The list of global variables Variable_View.txt is stored in the same folder as the generated report. For more information on the exported variables list, see View Exported Variable List.

Input Arguments

collapse all

Path to the report template that you use to generate an analysis report. To generate multiple reports, specify a comma-separated list of report template paths (do not put a space after the commas). The templates are available in polyspaceroot\toolbox\polyspace\psrptgen\templates\ as .rpt files. Here, polyspaceroot is the Polyspace installation folder. The polyspace-report-generator command accepts the same templates as the analysis option -report-template. For information on the available templates, see Bug Finder and Code Prover report (-report-template).

This option is not compatible with -generate-variable-access-file and -generate-results-list-file.

Example: C:\Program Files\Polyspace\R2019a\toolbox\polyspace\psrptgen\templates\Developer.rpt

Example: TEMPLATE_PATH\BugFinder.rpt,TEMPLATE_PATH\CodingStandards.rpt

Path to a folder containing Polyspace analysis results (.psbf or .pscp file). To generate a report for multiple verifications, specify a comma-separated list of folder paths (do not put a space after the commas). If you do not specify a folder path, the command generates a report for analysis results in the current folder.

Example: C:\Polyspace_Workspace\My_project\Module_1\results

Example: C:\Polyspace_Workspace\My_project\Module_2\results,C:\Polyspace_Workspace\My_project\Module_3\other_results

Fully qualified host name of the machine that hosts the Polyspace Access Gateway API service. You must specify a host name to generate a report for results on the Polyspace Access database.

Example: my-company-server

Run ID of the project findings for which you generate a report. Polyspace assigns a unique run ID to each analysis run that you upload to the Polyspace Access.

You can see the run ID of a project in the Polyspace Access web interface. To get the run ID, use the command polyspace-access -list-project (Polyspace Access).

OptionDescription
-format HTML | PDF | WORD

File format of the report that you generate. By default, the command generates a Microsoft® Word document.

To generate reports in multiple formats, specify a comma-separated list of formats. (Do not put a space after the commas). For instance, -format PDF,HTML.

This option is not compatible with -generate-variable-access-file and -generate-results-list-file.

-output-name outputName

Name of the generated report or folder name if you generate multiple reports.

The report or exported file is saved on the path from which you call the command. To save in a different folder, specify the full path to the folder, for instance -output-name C:\PathTo\OtherFolder.

-results-dir FOLDER_1,...,FOLDER_N

Path to the locally stored results folder. To generate reports for multiple analyses, specify a comma-separated list of folder path. (Do not put a space after the commas). For example:

-results-dir folderPath1,folderPath2
This option is not compatible with Polyspace Access results.

-key-mode file-scope | function-scope

Specify how the entries in the Key column of the exported results are calculated:

  • file-scope (default) — The key is calculated from the result name, result type, and file location.

  • function-scope — The key is calculated from the result name, result type, and function location if the results is located inside a function, or file location otherwise. Keys generated in this mode are prefixed with FN if the result is inside a function.

See also Enable Function Scope for Exported Keys.

This option applies only in combination with option -generate-results-list-file.

-set-language-englishGenerate the report in English. Use this option if your display language is set to another language.
-helpDisplay the help information.
OptionDescription

-host HOST_NAME

HOST_NAME corresponds to the host name that you specify in the URL of the Polyspace Access interface, for example https://HOST_NAME:port/metrics/index.html. If you are unsure about which host name to use, contact your Polyspace Access administrator. The default host name is localhost.

This option is mandatory when you generate reports for results stored on the Polyspace Access database.

-run-id RUN_ID

Run ID of the project. Polyspace assigns a unique run ID to each analysis run that you upload. To get the last run ID of a project, use the polyspace-access -list-project (Polyspace Access) command.

This option is mandatory when you generate reports for results stored on the Polyspace Access database.

-all-units

Specify this option to generate a report for all units from a unit by unit analysis.

When you use this option, specify the run ID of only one unit with -run-id. The command includes the other units from the analysis in the report.

-port portNumber

portNumber corresponds to the port number that you specify in the URL of the Polyspace Access interface, for example https://hostname:portNumber/metrics/index.html. If you are unsure about which port number to use, contact your Polyspace Access administrator. The default port number is 9443.

-protocol http | https

HTTP protocol used to connect to Polyspace Access. Default value is https.
-credentials-file file_path

Full path to the text file where you store your login credentials. Use this option if, for instance, you use a command that requires your Polyspace Access credentials in a script but you do not want to store your credentials in that script. While the script runs, someone inspecting currently running processes cannot see your credentials.

You can store only one set of credentials in the file, either as -login and -encrypted-password entries on separate lines, for instance: 

-login jsmith
-encrypted-password LAMMMEACDMKEFELKMNDCONEAPECEEKPL
or as an -api-key entry:
-api-key keyValue123
Make sure that you restrict the read and write permissions on the file where you store your credentials. For example, to restrict read and write permissions on file login.txt in Linux, use this command:
chmod go-rwx login.txt

-api-key keyValue

API key you use as a login credential instead of providing your login and encrypted password. To assign an API key to a user, see Configure User Manager (Polyspace Access) or contact your Polyspace Access administrator.

Use the API key if, for instance, you use a command that requires your Polyspace Access login credentials as part of an automation script with a CI tool like Jenkins®. If a user updates his or her password, you do not need to update the API key associated with that user in your scripts.

It is recommended that you store the API key in a text file and pass that file to the command by using -credentials-file. See the description for option -credentials-file.

-login username

-encrypted-password ENCRYPTED_PASSWD

Credentials that you use to log into Polyspace Access. The argument of -encrypted-password is the output of the polyspace-access -encrypt-password (Polyspace Access) command.

Tips

  • You cannot use the polyspace-report-generator command with results generated with Polyspace as You Code™. Use the polyspace-results-export command instead. See polyspace-results-export.

  • Report generation can take a long time for result sets containing a very large number of defects or coding rules violations. In some cases, you might run into issues from insufficient memory. If that happens, you can either increase the Java® heap size or export the results to a tab-delimited text (TSV) file. The results export is faster than report generation and can complete in reasonable time even for large result sets. For more information, see Fix Insufficient Memory Errors During Polyspace Report Generation.

Alternative Functionality

Instead of generating reports from existing analysis results, you might want a report to be generated along with the analysis. In this case, use the analysis options -report-template and -report-output-format. See Configure Reporting.

Reports generated along with analysis will only contain review information imported from previous analyses (if any such information is imported). If you add new review information to the results, you will have to regenerate the reports using the polyspace-report-generator command.

Version History

Introduced in R2013b

expand all

See Also

|

Topics