polyspace-report-generator

(DOS/UNIX) Generate reports for Polyspace analysis results stored locally or on Polyspace Access

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

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\R2024b (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.

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 (Polyspace Code Prover).

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).

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.

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 (Polyspace Code Prover).

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.

Examples

Generate PDF Reports for Analysis Results Stored Locally

You can generate multiple reports for analysis results that you store locally.

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.

SET template_path="C:\Program Files"\Polyspace\R2019a\toolbox\polyspace^
\psrptgen\templates\bug_finder
SET report_templates=%template_path%\BugFinder.rpt,^
%template_path%\CodingStandards.rpt

Generate the reports from the templates that you specified in report_templates for analysis results of Polyspace project myProject.

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

The command generates two PDF reports, myProject_BugFinder.PDF and myProject_CodingStandards.PDF. The reports are stored in C:\Polyspace_Workspace\myProject\Module_1\BF_Result\Polyspace-Doc. For more information on the content of the reports, see Bug Finder and Code Prover report (-report-template).

Configure Report Generator with Client Keystore

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.

Generate Report and Variables List from Polyspace Access

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 with option -list-project.

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

For more information on this command, see polyspace-access (Polyspace Access).

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 (Polyspace Code Prover).

Input Arguments

outputTemplate — path to report template file

string

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

resultsFolder — Analysis results folder path

string

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

hostName — Polyspace Access machine host name

string

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

runID — Polyspace Access run ID

integer

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 (Polyspace Access) with option -list-project.

reporting options — Options for generated report

string

Option	Description
-format HTML | PDF | WORD	File format of the report that you generate. By default, the command generates a 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-english	Generate the report in English. Use this option if your display language is set to another language.
-help	Display the help information.

polyspace access options — Options for Polyspace Access

string

Option	Description
-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 -list-project option of the polyspace-access command. For more information on the command, see polyspace-access (Polyspace Access). 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 command. For more information on the command, see polyspace-access (Polyspace Access).

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 use the option -wysiwyg to generate multiple filtered reports instead of a single report containing all results. 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 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