Main Content

polyspace-access

(DOS/UNIX) Manage Polyspace Access results and users at the command line

collapse all in page

Syntax

polyspace-access -create-project folderPath -host hostname [login options]
polyspace-access -move-project projectPath -to-project-path destinationPath -host hostname [login options]
polyspace-access -delete-project projectPath -host hostname [login options]
polyspace-access -set-deletion-policy projectPath -max-days MAX_DAYS -max-runs MAX_RUNS -host hostname [login options]
polyspace-access -unset-deletion-policy projectPath -host hostname [login options]
polyspace-access -get-deletion-policy projectPath -host hostname [login options]
polyspace-access -list-project [projectPath] -host hostname [login options]
polyspace-access -list-runs projectPath -host hostname [login options]
polyspace-access -set-project-information projectPath -banner bannerText -host hostname [login options]
polyspace-access -unset-project-information projectPath -host hostname [login options]
polyspace-access -upload pathToFileOrFolderOrZipFile [upload options] -host hostname [login options]
polyspace-access -export findingsToExport -output filePath [export options] -host hostname [login options]
polyspace-access -download findingsToDownload -output-folder-path outputFolderPath -host hostname [login options]
polyspace-access -review fileOrFindingID -project-path projectToReview review options -host hostname [login options]
polyspace-access -import-reviews sourceProjectPath -to-project-path targetProjectPath [-import-strategy never-overwrite-target | always-overwrite-target] -host hostname [login options]
polyspace-access -set-sqo projectPathWithSQO -level sqoLevel [-name sqoName] -host hostname [login options]
polyspace-access -get-sqo projectPathWithSQO -host hostname [login options]
polyspace-access -list-sqo -host hostname [login options]
polyspace-access -add-label label -run-id runID -host hostname [login options]
polyspace-access -remove-label label -run-id runID -host hostname [login options]
polyspace-access -set-unassigned-findings findingsToAssign -owner userToAssign -source-contains pattern [set unassigned findings options] -host hostname [login options]
polyspace-access -set-role role -user username -group groupname -project-path folderPathOrProjectPath -host hostname [login options]
polyspace-access -unset-role -user username -group groupname -project-path folderPathOrProjectPath -host hostname [login options]
polyspace-access -generate-migration-commands metrics_dir -output-folder-path dir [generate migration commands options]
polyspace-access -migrate -option-file-path dir [-dryrun] -host hostname [login options]
polyspace-access -ver -host hostname [login options]
polyspace-access -encrypt-password

Description

Manage and View Projects

Note

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

polyspace-access -create-project folderPath -host hostname [login options] creates a project folder in the Polyspace Access™ web interface. The folder can be at the top of the project hierarchy or a subfolder under an existing project folder.

example

polyspace-access -move-project projectPath -to-project-path destinationPath -host hostname [login options] moves or renames a project or folder. The sourcePath and destinationPath must be absolute paths of the source and destination projects or folders. You cannot move or rename a project or folder if the path you specify for the destination already exists.

polyspace-access -delete-project projectPath -host hostname [login options] deletes specified project or folder from the Polyspace Access Project Explorer. The project or folder is moved to the ProjectsWaitingForDeletion folder, which is visible only to users with a role of Administrator. If the project is already in the ProjectsWaitingForDeletion folder, the command deletes the project entirely from the database. See also Delete Project Runs or Entire Projects (Polyspace Access).

polyspace-access -set-deletion-policy projectPath -max-days MAX_DAYS -max-runs MAX_RUNS -host hostname [login options] sets or edits project run deletion policy for specified project. After you set the policy Polyspace applies that policy on each subsequent upload to the project and deletes project runs from the database based on these thresholds:

  • Age of project run in days (MAX_DAYS) — If the number of days since a run was uploaded to the project exceeds MAX_DAYS, Polyspace deletes the run.

  • Number of runs in a project (MAX_RUNS) — If a project already contains MAX_RUNS and you upload a new run, Polyspace deletes the oldest run in the project.

When you set the policy you can specify either threshold or both of them. When you specify both thresholds, Polyspace deletes a project run if that run meets either threshold. See also Delete Project Runs or Entire Projects (Polyspace Access).

polyspace-access -unset-deletion-policy projectPath -host hostname [login options] unsets the project run deletion policy for the specified project. When a project has no deletion policy, all the runs that you upload to that project remain in the database until you manually delete them. See also Delete Project Runs or Entire Projects (Polyspace Access).

polyspace-access -get-deletion-policy projectPath -host hostname [login options] shows deletion policy for specified project. See also Delete Project Runs or Entire Projects (Polyspace Access).

polyspace-access -list-project [projectPath] -host hostname [login options] without the optional argument projectPath lists the paths to all projects in the Polyspace Access database and their last run IDs. If you specify the full path to a project with the argument projectPath, the command lists the last run ID for only that project.

example

polyspace-access -list-runs projectPath -host hostname [login options] shows all the runs that were uploaded to the specified project. For each run, you see the run ID and any labels associated with that run.

polyspace-access -set-project-information projectPath -banner bannerText -host hostname [login options] displays the text you specify in bannerText within a banner in the Polyspace Access user interface. The banner is shown when you select the folder or project that you specified with projectPath. See Add Project Banners to Results in Polyspace Access (Polyspace Access).

polyspace-access -unset-project-information projectPath -host hostname [login options] removes an existing project banner from the specified project.

Upload, Download, or Export Results

polyspace-access -upload pathToFileOrFolderOrZipFile [upload options] -host hostname [login options] uploads Polyspace Bug Finder™, Code Prover, or Polyspace Test™ results to the Polyspace Access database from the file (recommended), folder, or zipped file that you specify. You can upload Bug Finder or Code Prover results using this command only if those results were generated with Polyspace Bug Finder Server™ or Polyspace Code Prover™ Server. You can upload results to an existing Polyspace Access project only if those results were generated by the same type of analysis. For instance, you cannot upload results of a Bug Finder analysis to a project that contains Code Prover results. To upload results generated with the Polyspace desktop interface, see Upload Results from Polyspace Desktop Client. Use the upload options to specify a project parent folder or to rename a project.

Note

example

polyspace-access -export findingsToExport -output filePath [export options] -host hostname [login options] exports project results from the Polyspace Access database to a text file whose location you specify with filePath. You can specify filters when you export the results or export a comparison between two projects. You specify the project using either the full path in Polyspace Access or the run ID. Use this command to export findings to other tools that you use for custom reports. To get the paths to projects and their last run IDs, use polyspace-access with the -list-project command.

example

polyspace-access -download findingsToDownload -output-folder-path outputFolderPath -host hostname [login options] downloads results from Polyspace Access project findingsToDownload to a folder whose location you specify with outputFolderPath. You specify the project using either the full path in Polyspace Access or the run ID.

You cannot open the downloaded results in the Polyspace desktop interface or the Polyspace as You Code IDE extensions. Use this command as part of the workflow to merge review information between projects, or to create a baseline for subsequent Polyspace analyses.

To get the paths to projects and their last run IDs, use polyspace-access with the -list-project command.

Manage Review Information for Findings

polyspace-access -review fileOrFindingID -project-path projectToReview review options -host hostname [login options] edits the information in the review fields of the findings in the project projectToReview. To review a single finding, pass a finding ID to the -review command. To perform a batch review, pass the path of a file where you store the finding IDs of multiple findings to the -review command. In this file, list one finding ID per line. You must specify at least one review field with review options, such as status, severity, comment, owner, or a bug tracking tool (BTT) ticket number.

You cannot assign a review field to a finding if that review field is set with a code annotation.

example

polyspace-access -import-reviews sourceProjectPath -to-project-path targetProjectPath [-import-strategy never-overwrite-target | always-overwrite-target] -host hostname [login options] imports review information from source project sourceProjectPath to target project targetProjectPath. Use this option if you have already reviewed findings in the source project and you reuse the code that contains those findings in the target project.

You can optionally specify one of these import strategies:

  • never-overwrite-target (default) — If a review field in the target project already has content, do not overwrite that review field with the content from the source project

  • always-overwrite-target — Always overwrite the content of the review fields in the target project with the content from the source project, even if the target review fields already have content.

See also Import Review Information from Existing Polyspace Access Projects (Polyspace Access).

Manage Software Quality Objectives (SQO)

polyspace-access -set-sqo projectPathWithSQO -level sqoLevel [-name sqoName] -host hostname [login options] assigns an SQO level to the specified project for the SQO definition that is currently applied to the project. You can optionally apply a different SQO definition to the project by specifying the name of that SQO definition with option -name. See also Manage Software Quality Objectives in Polyspace Access (Polyspace Access). You can run this command only on single projects but not on project folders.

polyspace-access -get-sqo projectPathWithSQO -host hostname [login options] shows the currently assigned SQO definition and SQO level for the specified project. See also Manage Software Quality Objectives in Polyspace Access (Polyspace Access). You can run this command only on single projects but not on project folders.

polyspace-access -list-sqo -host hostname [login options] lists the name of all the available SQO. See also Manage Software Quality Objectives in Polyspace Access (Polyspace Access).

Manage Project Run Labels and Unassigned Findings

polyspace-access -add-label label -run-id runID -host hostname [login options] adds a label to the project run specified with runID. Use labels to identify project runs of interest more easily, or to associate a run with a specific branch or continuous integration build job. See also Manage Labels at the Command Line (Polyspace Access).

polyspace-access -remove-label label -run-id runID -host hostname [login options] removes the specified label from the project run with run ID runID. If the specified label does not match any of the project run labels, the command is ignored. See also Manage Labels at the Command Line (Polyspace Access).

polyspace-access -set-unassigned-findings findingsToAssign -owner userToAssign -source-contains pattern [set unassigned findings options] -host hostname [login options] assigns owners to unassigned results in a project in the Polyspace Access database. You specify the project using either the full path in Polyspace Access or the run ID. Use the set unassigned findings options to assign findings from different source files or different groups of source files to different owners. To get the paths to projects and their last run IDs, use polyspace-access with the -list-project command.

example

Manage User Permissions

polyspace-access -set-role role -user username -group groupname -project-path folderPathOrProjectPath -host hostname [login options] assigns a role role to username or groupname for the specified project or project folder. A user or group role set for a project folder applies to all project findings under that folder. All users in a group inherit the role assigned to their parent group. You specify the project using either the full path in Polyspace Access or the last run ID. To get the paths to projects and their last run IDs, use polyspace-access command with the -list-project command.

example

polyspace-access -unset-role -user username -group groupname -project-path folderPathOrProjectPath -host hostname [login options] removes any role previously assigned to username or groupname for the specified project or project folder. Unassigning a role for a group unassigns that role for all the users in that group. You specify the project using either the full path in Polyspace Access or the last run ID. To get the paths to projects and their last run IDs, use polyspace-access with the -list-project command.

Migrate Results from Polyspace Web Metrics

polyspace-access -generate-migration-commands metrics_dir -output-folder-path dir [generate migration commands options] generates scripts to migrate projects from the path metrics_dir in Polyspace Metrics to Polyspace Access. The command stores the scripts in dir. To specify which project findings to migrate, use generate migration commands options.

example

polyspace-access -migrate -option-file-path dir [-dryrun] -host hostname [login options] migrates projects from Polyspace Metrics to Polyspace Access using the scripts generated with the -generate-migration-commands command. To view which projects are migrated without actually migrating the projects, use the -dryrun option.

example

Other Commands

polyspace-access -ver -host hostname [login options] displays the version and license number of the Polyspace Access instance that you specify with hostname, and the version of the polyspace-access binary. You can run this command only with Polyspace Access instances for which you have login credentials.

polyspace-access -encrypt-password encrypts the password you use to log into Polyspace Access. Use the output of this command as the argument of the -encrypted-password option when you write automation scripts to interact with Polyspace Access.

If your username or password contain non-ASCII characters, check that you run the -encrypt-password command from a UTF-8 encoded terminal.

example

Examples

collapse all

Polyspace Access requires login credentials. You can enter the credentials at the command-line when you execute a command, or you can generate an encrypted password to use with other login options in automation scripts.

To encrypt your password, use the -encrypt-password command and enter your Polyspace Access credentials. The command uses the user name and password you enter to generate an encrypted password.

polyspace-access -encrypt-password
login: jsmith
password:
CRYPTED_PASSWORD KEAGKAMJMCOPLFKPKOHOJNDJCBACFJBL
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 KEAGKAMJMCOPLFKPKOHOJNDJCBACFJBL
To restrict the file permissions, right-click the file and select the Permissions tab on Linux® or the Security tab on Windows®.

If you manage your analysis findings through automated scripts, create a variable to store the connection configuration and login credentials. Use this variable in your script, or at the command line to avoid typing your credentials when you execute a command.

set LOGIN=-host myAccessServer -port 1234 -credentials-file myCredentials.txt
 
polyspace-access %LOGIN% -create-project myProject

Suppose that you want to upload a set of findings to Polyspace Access generated with Polyspace Bug Finder Server or Polyspace Code Prover Server, and authorize only some team members to view these findings.

Create a project folder restrictedProject at the top of the project hierarchy.

polyspace-access -host myAccessServer -port 1234 ^
-create-project restrictedProject

Set roles for users jsmith and rroll, and group Authorized Users, authorizing them to access the project folder as contributors. If a user name or group name contains spaces, enclose it in double quotes.

polyspace-access -host myAccessServer ^
-port 1234 -set-role contributor ^
-user jsmith -user rroll -group "Authorized Users" -project-path restrictedProject
Aside from the creator of the project folder and the users and group with a role of contributor, no other user can view or access any findings uploaded to restrictedProject.

Upload Bug Finder project findings from project "My Example Project" to parent folder Restricted.

polyspace-access -host myAccessServer -port 1234 ^
-upload "C:\Polyspace_Workspace\My Example Project\Module1\ps_results.psbf" ^
-parent-project Restricted
The uploaded findings are stored under restrictedProject/My_Example_Project (Bug Finder). The -upload command outputs information about the upload including an ACCESS URL. You can use that URL to view the uploaded results in the Polyspace Access interface.

See also Manage Project Permissions (Polyspace Access).

If you follow a component-based development approach, you can assign analysis findings by component to their respective owners.

Get a list of projects currently stored on the Polyspace Access database. The command outputs a list of project findings paths and their last run ID.

polyspace-access -host myAccessServer -list-project

Connecting to https://example-access-server:9443
Connecting as jsmith

Get project list with the last Run Id
Restricted/Code_Prover_Example (Code Prover) RUN_ID 14
multimodule/vxWorks_demo (Code Prover) RUN_ID 16
public/Bug_Finder_Example (Bug Finder) RUN_ID 24
public/CP/Code_Prover_Example (Polyspace Code Prover) RUN_ID 8
public/Polyspace (Code Prover) RUN_ID 28
Command Completed

Assign all red and orange run-time error findings to the owner of all the files in Component_A of project vxWorks_demo. Perform the same assignment for the owner of Component_B. To specify the vxWorks_demo project, use the run ID.

polyspace-access -host myAccessServer ^
-set-unassigned-findings 16 ^
-owner A_owner -source-contains Component_A ^
-owner B_owner -source-contains Component_B ^
-rte Red -rte Orange
-source-contains Component_A matches all files with a file path that contains Component_A.

-source-contains Component_B matches all files with a file path that contains Component_B, but excludes files with a file path that contains Component_A.

After you assign findings, export the findings and generate .csv files for each owner containing the findings assigned to them.

polyspace-access -host myAccessServer ^
-export 16 ^
-output C:\Polyspace_Workspace\myResults.csv ^
-output-per-owner
The command generates file myResults.csv containing all findings from the project with run ID 16. The command also generates files myResults.csv.A_owner.csv and myResults.csv.B_owner.csv on the same file path.

If you want to make batch edits to the review information of analysis results after you upload those results to Polyspace Access:

  1. Export a list of findings that you want to review.

  2. Edit the review information for each finding using the finding IDs stored in the file from step 1.

Export a list of findings that you want to review, using the polyspace-access -export command. For example, if you want to export only new defects with severity High or Medium from a project with project path public/example/Bug_Finder_Example (Bug Finder) and project ID 129, run this command:

polyspace-access $login -export 129 -output newMedHighDefects.txt\
 -resolution new -defects High -defects Medium

The command outputs the tab separated values (TSV) file newMedHighDefects.txt. The file contains a list of findings that match the filters that you specified, where the first column of the file shows the finding IDs.

Here, $login is a variable that stores the login credentials and other connection information. To configure this variable, see Encrypt Password and Store Login Options in a Variable (Polyspace Access).

Extract the finding IDs column from the file that you generated in the previous step to another text file. For instance, you use the awk command (BASH command) or a for loop (DOS command) to skip the column header and then save the finding IDs to file findingIDs.txt.

#BASH COMMAND
awk ' NR>1 {print$1} ' newMedHighDefects.txt >> findingIDs.txt

##########################################

REM DOS COMMAND
for /f "skip=1" %i in (newMedHighDefects.txt); do @echo %i >> findingIDs.txt

Pass the file findingIDs.txt to the polyspace-access -review command. Specify the path of the project that contains those findings and the review fields that you want to edit. For instance, you might want to assign a status, owner, and comment to the findings.

# BASH COMMAND

 polyspace-access $login -review findingIDs.txt \
 -project-path "public/example/Bug_Finder_Example (Bug Finder)" \
 -set-status "To investigate" -set-owner jsmith \
 -set-comment "Finding assigned automatically"

######################################################

REM DOS COMMAND

polyspace-access %login% -review findingIDs.txt ^
 -project-path "public/example/Bug_Finder_Example (Bug Finder)" ^
 -set-status To investigate" -set-owner jsmith ^
 -set-comment "Finding assigned automatically"

The command runs once and performs a batch edit of the specified review fields for all the findings listed in the file findingsIDs.txt. Depending on the number of findings and on your network speed, the command might take a few moments to complete.

If you have projects stored on a Polyspace Metrics server, you can migrate them to the Polyspace Access database. Log in to your Metrics server to complete this operation.

Generate migration scripts for the projects you want to migrate. Specify the folder path of the location where the projects are stored, for example C:\Users\jsmith\AppData\Roaming\Polyspace_RLDatas\results-repository 

polyspace-access -generate-migration-commands ^
C:\Users\jsmith\AppData\Roaming\Polyspace_RLDatas\results-repository ^
-output-folder-path C:\Polyspace_Workspace\toMigrate -project-date-after 2017-06

The command generates migration scripts for all projects in the specified metrics folder that were uploaded on or after June 2017. The scripts are stored in folder C:\Polyspace_Workspace\toMigrate.

Use the -dryrun option to check which projects will be migrated.

polyspace-access -host myAccessServer ^
-migrate -option-file-path ^
C:\Polyspace_Workspace\toMigrate -dryrun
The command output contains a list of projects. Inspect it to ensure that you are migrating the correct projects.

To perform the migration, rerun the last command without the -dryrun option.

Input Arguments

collapse all

Connection Configuration and Login

hostname corresponds to the host name that you specify in the URL of the Polyspace Access interface, for example https://hostname: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. You must specify a host name with all polyspace-access commands, except the -generate-migration-commands and -encrypt-password commands.

Example: -host myAccessServer

Options to specify connection configuration and login credentials.

Connection Options

OptionDescription

-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 access Polyspace Access. The default protocol is https.
-credentials-file filePath

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 the file where you store your credentials is UTF-8 encoded and that you restrict the read and write permissions on the file. 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

Login credentials you use to interact with Polyspace Access. The argument of -encrypted-password is the output of the -encrypt-password command.

If you do not use these two options, you are prompted to enter your credentials at the command line, unless you use -api-key.

-max-retry retryNumber

Number of times the polyspace-access command retries to upload results when you upload from a client machine to the server machine that hosts Polyspace Access. Specify this option to retry the upload command in the event of sporadic network outages. The command waits 10 seconds between retries.

By default, the command retries up to 60 times.

Miscellaneous Options

OptionDescription

-output filePath

Full path to the file where you store command outputs.

-tmp-dir folderPath

Folder path where you store temporary files generated by the polyspace-access commands. The default folder path is tmp/ps_results_server on Linux and C:/Users/%username%/AppData/Local/Temp/ps_results_server on Windows.

-log filePath

File path where you store the command output log. By default the command does not generate a log file.

-h

Display the help information for polyspace-access or one of its commands.

Manage and View Projects

Absolute Project folder path specified as a string. If the name includes spaces, use double quotes. Specify the full path to folders nested under a parent folder.

If your folder path involves a folder that does not already exist, the folder is created.

Example: -create-project topFolder

Example: -create-project "topFolder/subFolder/Folder has spaces"

Absolute path of the project specified as a string. If the path name includes spaces, use double quotes. When you use this argument with:

  • -list-project, the argument is optional. The command returns the run ID of the last run uploaded to the specified project.

  • -list-run, the command returns the run ID and labels of all the runs that you uploaded to the specified project.

Example: -move-project "public/Examples/Bug_Finder_Example (Bug Finder)"

Example: -move-runs public/Examples/Code_Prover_Example

Example: -delete-project public/Folder/projectName

Example: -set-deletion-policy public/Folder/projectName

Example: -unset-deletion-policy public/Folder/projectName

Example: -get-deletion-policy public/Folder/projectName

Example: -list-project public/Folder/projectName

Example: -list-runs public/Folder/projectName

Example: -set-project-information public/Folder/projectName -banner "My banner text."

Absolute path of project or folder specified as a string. If the name includes spaces, use double quotes. Specify the absolute path of the new folder or project location.

If you move or rename a folder, all subfolders and subprojects are moved to the new parent folder. If you move a project to a different folder, you must specify the absolute path including the project name for the destination path.

Example: -to-project-path new/Folder/Path

Example: -to-project-path "new/Folder/name has spaces"

Maximum age of a project run specified as number of days. If the number of days since you uploaded a project run exceeds MAX_DAYS, Polyspace deletes the run from the database.

The deletion policy is applied on each upload after you set the policy. If you do not upload a new run to a project and a the number of days since a run was uploaded exceeds MAX_DAYS, the run is not deleted.

Example: -set-deletion-policy public/Folder/projectName -max-days 30

Maximum number of runs that you keep in a project. If a project already contains MAX_RUNS runs, and you upload a new run, Polyspace deletes the oldest run in that project from the database. Polyspace does not count runs that you exclude from deletion when applying the maximum number of runs deletion policy.

Example: -set-deletion-policy public/Folder/projectName -max-runs 10

Text string to display in the project banner. If a banner already exists, bannerText replaces the existing banner. Use the \n newline character to create banners with multiple lines. If the banner text includes spaces, use double quotes.

The Polyspace Access user interface displays the project banner on the aggregate project folder or individual project runs. Click the expander on the banner to display longer banner messages in full within the user interface.

Example: -set-project-information public/Folder/projectName -banner "My banner text."

Example: -set-project-information public/Folder/projectName -banner "Multi-line banner example.\n\nMy banner text."

Upload, Download, or Export Results

Path of a Bug Finder (PSBF), Code Prover (PSCP) , or Polyspace Test (PSTESTR or PSPROF) results file specified as a string. The command uploads copies of the results file and other files located in the same results folder. Alternatively, you can specify the path of a parent folder that contains a single PSBF, PSCP, PSTESTR, or PSPROF results file, or the path of a zipped results file or folder.

For instance, for the Bug Finder results stored in C:\Polyspace_Workspace\myProject\Module_1\BF_results\ps_results.psbf, specify this with the -upload command. If the path name includes spaces, enclose the path in double quotes.

For faster uploads, store your analysis results in a dedicated results folder by using option -results-dir when you run the analysis. If you store results in a folder that contains a large number of files unrelated to Polyspace analysis results, for example the root folder of your repository, Polyspace Access takes longer to upload the results.

Example: -upload C:\Polyspace_Workspace\myProject\Module_1\BF_results\ps_results.psbf

Example: -upload C:\Polyspace_Workspace\myProject\Module_1\ -project projectFolder

Example: -upload C:\Polyspace_Workspace\myTestProj\results\results.pstestr -project testsFolder

Options to specify path to project folder and name of project where you upload results. These options are not optional.

OptionDescription

-parent-project folderPath

Path of the parent folder in the Polyspace Access explorer under which you store uploaded results.

If you do not specify a parent folder, uploaded results are stored under the public folder.

-project resultsName

Name of the uploaded results in the Polyspace Access explorer. Use this option to rename the results that you upload.

If you do not specify a results name, the results are stored as projectName (resultsType), where spaces in the projectName are replaced with underscores. For instance, if you upload Bug Finder results from project Bug Finder Example, these results are stored as Bug_Finder_Example (Bug Finder).

-exclude-from-deletion

Exclude the run that you are uploading from the project run deletion policy. Use this option to protect project runs of interest from deletion. For instance, you might want to keep the first run that you upload to a project as a baseline, but still apply a deletion policy to all other runs that you upload to that project. Polyspace does not count runs that you exclude from deletion when applying the maximum number of runs deletion policy.

When you exclude a run from the deletion policy, the run remains in the database until you explicitly delete it. The run appears as Persistent in the Runs Deletion window on the Polyspace Access interface. You cannot delete individual runs manually at the command line.

Example:

polyspace-access -upload /usr/local/polyspace/results/ps_results.psbf \
 -parent-project public/examples \
 -exclude-from-deletion
See also Delete Project Runs or Entire Projects (Polyspace Access).

Path or run ID of the project findings that you export. Polyspace assigns a unique run ID to each analysis run you upload. If the path name includes spaces, use double quotes. To get the project findings path or last run ID, use -list-project.

Example: -export "public/Examples/Bug_Finder_Example (Bug Finder)"

Example: -export 4

Path to the file that stores the output of the command when you specify the -output option. This option is mandatory with the -export command.

Example: -output C:\Polyspace_Workspace\myResults.txt

Options to specify where to export findings, and which subset of findings you export. Use these options to export findings to other tools you use to create custom reports or other custom review templates.

OptionDescription

-output filePath

File path where you export the findings. This option is mandatory with the -export command.

-output-per-owner

Use this option to generate files that only contain findings assigned to a particular user. The files are stored on the path you specify with -output.

For an example of how to assign findings to owners at the command-line, see Assign Results to Component Owners and Export Assigned Results (Polyspace Access).

-rte All | Red | Gray | Orange | Green

Type of RTE finding to export. Specify All, Red, Gray, Orange, or Green.

To specify more than one argument, call the option for each argument. For example, -rte Red -rte Orange.

-defects All | High | Medium | Low

Impact of DEFECTS findings to export. Specify All, High, Medium, or Low.

To specify more than one argument, call the option for each argument. For example, -defects Medium -defects Low.

-custom-coding-rules

Export all custom coding rules findings.

-coding-rules

Export all coding rules findings.

-code-metrics

Export all code metrics findings.

-global-variables

Export all global variables findings.

-status Unreviewed | "To investigate" | "To fix" | Justified | "No action planned" | "Not a defect" | Other

Review status of the findings to export. Specify Unreviewed (default), "To investigate", "To fix", Justified, "No action planned", "Not a defect", or Other.

To specify more than one argument, call the option for each argument. For example, -status Tofix -status Toinvestigate.

-severity All | High | Medium | Low

Severity of the findings to export. Specify All, High, Medium, or Low.

To specify more than one argument, call the option for each argument. For example, -severity High -severity Low.

-unassigned-findings

Export all unassigned findings.

-open-findings-for-sqo 1 | 2 | 3 | 4 |5 | 6

Software quality objective or SQO level that must be satisfied. Specify a number from 1 to 6 for sqo_level. If you specify an SQO level, the polyspace-access command exports only open findings that must be fixed or justified to satisfy the requirements of this level.

The SQO levels 1 to 6 specify an increasingly stricter set of predefined or user-defined requirements in terms of Polyspace results. To customize the requirements in the Polyspace Access web interface, see Customize Software Quality Objectives (Polyspace Access)

For more information on the SQO levels, see Evaluate Polyspace Bug Finder Results Against Bug Finder Quality Objectives.

For instance, SQO level 2 in Code Prover requires that you must not have unjustified red checks. This specification means that if you use -open-findings-for-sqo with a level higher than 2, all red checks are exported and must be subsequently fixed or justified. If you want to impose this requirement in the earlier SQO level 1, you can customize level 1 in the Polyspace Access web interface.

-resolution New | Fixed | Unresolved | Resolved

Use this option to compare two runs from the same project. The resolution corresponds to the type of comparison that the software performs between the current run and a baseline run that you specify with option -baseline. The baseline run must be older than the current run.

The resolution types are:

  • New — Findings that are in the current run but not in the baseline run.

    If the project contains only one run, all findings are new and you can omit this option.

  • Fixed — Findings that are fixed in the current run, either because the finding was fixed in the source code, or because the source code containing the finding is deleted or no longer part of the analysis.

    If the project contains only one run, you get an error.

  • Unresolved — Findings from the baseline run that are still present in the current run.

    If the project contains only one run, you get an error.

  • Resolved — Findings that are Fixed in the current run or findings with a status of Justified, No Action Planned, or Not A Defect in the current run.

    If the project contains only one run, you get an error.

If you do not specify a baseline, the current run is compared to the run that immediately precedes it.

You can specify only one resolution type at a time. To export a comparison for multiple resolution types, run the polyspace-access -export command for each resolution type.

See also Comparison Mode at the Command Line (Polyspace Access).

-baseline runID

Specify the run ID of a run that you use as a baseline for comparison with a current run. This option requires option -resolution.

This option is not mandatory. If you do not specify a baseline, the current run is compared to the run that immediately precedes it. If the project contains only one run, you get an error.

See also Comparison Mode at the Command Line (Polyspace Access).

-imported-reviews Not applied | Written | Overwritten | Unconfirmed

Use this option to export a list of findings from a project (target) whose review information was imported from another project (source). Specify one of these types of imports:

  • Not applied — Review information was imported from the source project but the review fields in the target project kept the original values.

  • Written — The Review information from the source project was written to the target project only if the review fields in the target project were previously empty.

  • Overwritten — The Review information from the source project was written to the target project even if the review fields in the target project were not previously empty.

  • Unconfirmed — Use this filter to select findings that where the result of the import operation has not been confirmed by a reviewer. You confirm the result of the import operation in the Polyspace Access interface. See Confirm Imported Review Information (Polyspace Access).

See also Import Review Information from Existing Polyspace Access Projects (Polyspace Access)

You can also use a combination of options. For instance, -coding-rules -severity High exports coding rule violations that have been assigned a status of High in the Polyspace Access web interface.

Path or run ID of the project findings that you download. Polyspace assigns a unique run ID to each analysis run that you upload to Polyspace Access. If the path name includes spaces, use double quotes. To get the project findings path or latest run ID, use -list-project.

When you specify the project path, the command downloads the latest run of that project. To download an older run, specify the run ID. To obtain the run ID of older runs, in the Polyspace Access interface, select a project in the Project Explorer, and then click the Current drop-down selection in the toolstrip to view the available run IDs.

Example: -download "public/Examples/Bug_Finder_Example (Bug Finder)"

Example: -download 5113

Path of the folder where you store the downloaded results. If the folder you specify already exists, it must be empty. This option is mandatory with the -download command.

Example: -output-folder-path C:\Polyspace_Workspace\baseline

Manage Review Information for Findings

Specify the ID of the finding to which you want to add review information by using the command -review. To perform a batch review, store the finding IDs of multiple findings in a text file (one finding ID per line) and pass that file to -review instead.

Polyspace Access assigns unique IDs to each finding that you upload.

Example: -review 1234

Example: -review listOfFindings.txt

Specify the absolute path of the project that contains the findings to which you want to add review information. Use option -project-path to specify the path. When you use -review, this option is mandatory.

Example: -project-path path/To/Project

Example: -project-path "project/path/with spaces"

Options to assign one or more review fields to the finding with the specified finding ID. When you use polyspace-access -review, you must specify at least one review option. After you assign review information to the finding, that information is available in the Result Details pane in Polyspace Access.

OptionDescription

-set-status Unreviewed | "To investigate" | "To fix" | Justified | "No action planned" | "Not a defect" | Other

Assign a status of the finding. Specify Unreviewed (default), "To investigate", "To fix", Justified, "No action planned", "Not a defect", or Other.

To reset a finding status, set the status to Unreviewed.

-set-severity Unset | High | Medium | Low

Assign severity of the finding. Specify Unset (default), High, Medium, or Low.

To reset a finding severity, set the severity to Unset.

-set-comment comment

Assign a comment to the finding.

-unset-comment

Delete the comment currently assigned to the finding.

-set-owner username

Assign an owner to the finding. Specify the username that the user uses to log into Polyspace Access, not the display name. For instance, specify jsmith instead of John Smith.

-unset-owner

Remove the owner currently assigned to the finding.

-set-ticket ticketID

Assign an existing BTT ticket to the finding. Specify the ticket ID.

You can assign a BTT ticket to a finding only if you integrate a BTT such as Jira Software or Redmine with Polyspace Access. Contact your Polyspace administrator to determine if Polyspace is configured for issue tracking.

-unset-ticket

Remove the BTT ticket currently applied to the finding.

Specify the absolute path of the project where you have already reviewed the findings. You import the review information from this source project.

Example: -import-reviews path/To/sourceProject

Example: -import-reviews "source project/path/with spaces"

Specify the absolute path of the target project to which you import the review information. By default, if a review field already has content, the imported review information from the source project does not overwrite it. Use option -import-strategy always-overwrite-target to force the overwrite of the target project review information with the review information imported from the source project.

Example: -to-project-path path/To/targetProject

Example: -to-project-path "target project/path/with spaces"

Manage Software Quality Objectives (SQO)

Specify the absolute path of a project with the command -set-sqo to assign an SQO level and optionally an SQO definition. To view the currently applied SQO level and SQO definition for the specified project, use the command -get-sqo. You cannot specify a folder path with the commands -set-sqo and -get-sqo.

If your project path involves a folder that does not already exist, the folder is created.

Example: -set-sqo path/To/Project

Example: -get-sqo "project/path/with spaces"

Level of the SQO to assign to the specified project for the currently applied SQO definition. Use option -name to also assign a different SQO definition.

Example: -level 3

Example: -level Exhaustive

Specify an SQO definition name (optional) to apply a different SQO definition to the specified project.

To see a lit of available SQO definitions, use the command -list-sqo. To view the currently applied SQO definition for the specified project, use the command -get-sqo.

If the SQO definition name contains spaces, use double quotes.

Example: -name Polyspace

Example: -name "My Custom SQO"

Manage Project Run Labels and Unassigned Findings

Specify a label to add or to remove from the project run that you specify with option -run-id. If the label includes spaces, use double quotes.

Example: -add-label testing_branch

Example: -remove-label "testing branch"

Specify the run ID of the project run to which you add a label or from which you remove a label. To view the latest run IDs for a project, use the command -list-project. To view the run IDs of all the project runs for a specific project, use the command -list-runs.

Example: -run-id 1234

Path or run ID of the project findings that you assign to a user. Polyspace assigns a unique run ID to each analysis run you upload. If the path name includes spaces, use double quotes. To get the project findings path or last run ID, use -list-project.

Example: -set-unassigned-findings "public/Examples/Bug_Finder_Example (Bug Finder)"

Example: -set-unassigned-findings 4

User name of user you assign as owner of unassigned findings. To assign multiple owners, call the option for each user.

Each call to -owner must be paired with a call to -source-contains.

Example: -owner jsmith

Pattern to match against file path of project source files. To match file paths for all source files, use "-source-contains /".

Enter a substring from the file path. You cannot use regular expressions.

When you call this option more than once, each instance excludes patterns from previous instances. For example, -source-contains foo -source-contains bar matches all file paths that contain foo, then all file paths that contain bar excluding paths that contain foo.

When you assign findings to multiple owners, call this option for each call to -owner.

Example: -source-contains main

Options to assign all findings or only a subset based on component or individual source files. To make an assignment, specify a pattern to match against the folder or file paths to assign.

OptionDescription

-rte All | Red | Gray | Orange | Green

Type of unassigned RTE finding to assign. Specify All, Red, Gray, Orange, or Green.

To specify more than one argument, call the option for each argument. For example, -rte Red -rte Orange.

-defects All | High | Medium | Low

Impact of unassigned DEFECTS findings to assign. Specify All, High, Medium, or Low.

To specify more than one argument, call the option for each argument. For example, -defects Medium -defects Low.

-custom-coding-rules

Assign owner to all unassigned custom coding rules findings.

-coding-rules

Assign owner to all unassigned coding rules findings.

-code-metrics

Assign owner to all unassigned code metrics findings.

-global-variables

Assign owner to all unassigned global variables findings.

-resolution New

Assign owner to unassigned findings that are new compared to previous analysis run. If the project contains only one run, all findings are new and you can omit this option.

-status Unreviewed | "To investigate" | "To fix" | Justified | "No action planned" | "Not a defect" | Other

Review status of the unassigned findings to assign. Specify Unreviewed, "To investigate", "To fix", Justified, "No actionp lanned", "Not a defect", or Other.

To specify more than one argument, call the option for each argument. For example, -status "To fix" -status "To investigate".

-severity All | High | Medium | Low

Severity of the unassigned findings to assign. Specify All, High, Medium, or Low.

To specify more than one argument, call the option for each argument. For example, -severity High -severity Low.

-dryrun

Display command output without making any assignment. Use this option to check that your assignments are correct.

Manage User Permissions

Level of access to project folder and findings for a user.

  • owner: User can move, rename, or delete specified project folders or findings and review their content.

  • contributor: User can review content of specified project folder or findings.

  • forbidden: User cannot access specified project folder or findings. Set this role to restrict the access of a user to a set of project findings inside a project folder that is accessible to the user.

Example: -set-role contributor

Polyspace Access user name.

Example: -user jsmith

Polyspace Access group name.

Example: -group "Group UI team"

Path of a project folder or project findings. When folderPathOrProjectPath is the path to a project folder, the user role you set applies to all subfolders and project findings under that folder. If the path name includes spaces, use double quotes. To get the project folder or findings path, use -list-project.

Example: -project-path "public/Examples/Bug_Finder_Example (Bug Finder)"

Example: -project-path public

Migrate Results from Metrics to Polyspace Access

Path of folder containing the Polyspace Metrics projects you want to migrate to Polyspace Access.

Example: -generate-migration-commands C:\Users\%username%\AppData\Roaming\Polyspace_RLDatas\results-repository

Path to folder that stores the output of -generate-migration-commands. Do not specify an existing folder.

Example: local/Polyspace_Workspace/migration_scripts

OptionDescription

-output-folder-path folderPath

Folder path where you want to store the generated command files. Do not specify an existing folder.

-max-project-runs int

Number of most recent analysis runs you want to migrate for each project. For instance, to migrate only the last two analysis runs of a project, specify 2.

-project-date-after YYYY[-MM[-DD]]

Only migrate results that were uploaded to Polyspace Metrics on or after the specified date.

-product productName

Product used to analyze and produce project findings, specified as bug-finder, code-prover, or polyspace-ada.

-analysis-mode integration | unit-by-unit

Analysis mode use to generate project findings, specified as integration or unit-by-unit.

Version History

Introduced in R2019a

expand all

See Also

Topics