In a continuous integration process, developers submit code to a shared repository. An automated build system using a tool such as Jenkins builds and tests each submission at regular intervals or based on predefined triggers and integrates the code. You can run a Polyspace® analysis as part of this process.
This topic provides sample Shell scripts that run a Polyspace analysis using Polyspace Bug Finder™ Server™ and upload the results for review in the Polyspace Access web interface. The script also sends e-mail notifications to potential reviewers. Notified reviewers can login to the Polyspace Access web interface (if they have a Polyspace Bug Finder Access™ license) and review the results.
The scripts are written for a specific development toolchain but can be easily extended to the processes used in your project, team or organization. The scripts are also meant to be run in a Jenkins freestyle project. If you are using Jenkins Pipelines, see Sample Jenkins Pipeline Scripts for Polyspace Analysis.
In particular, the scripts:
Run on Linux® only.
The scripts use some Linux-specific commands such as export
.
However, these commands are not an integral part of the Polyspace workflow. If you write Windows® scripts (.bat
files), use the
equivalent Windows commands instead.
Work only with Jenkins after you install the Polyspace plugin.
The scripts are designed for the Jenkins plugin in these two ways:
The scripts uses helper functions
$ps_helper
and
$ps_helper_access
for simpler
scripting. The helper functions export Polyspace results for e-mail attachments and use
command-line utilities to filter the results.
These helper functions are available only with the Jenkins
plugin. However, the underlying commands come with a
Polyspace
Bug Finder
Server installation. On build automation tools other
than Jenkins, you can create these helper functions using
the polyspace-report-generator
command or
polyspace-access
command (with the
-export
option). See Send Email Notifications with Polyspace Bug Finder Results.
If you perform a distributed build in Jenkins, the plugin must be installed in the same folder in the same operating system on both the master node and the agent node executing the Polyspace analysis. Otherwise, you cannot use the helper functions.
The scripts create text files for e-mail attachments and mail subjects and bodies for personalized e-mails. If you install the Polyspace plugin in Jenkins, an extension of an e-mail plugin is available for use in your Jenkins projects. The e-mail plugin allows you to easily send the personalized e-mails with the previously created subjects, bodies and attachments. Without the Polyspace plugin, you have to find an alternative way to send the e-mails.
Run a Bug Finder analysis.
The scripts run Bug Finder on the demo example
Bug_Finder_Example
. If you install the product
Polyspace
Bug Finder
Server, the folder containing the demo example is
.
Here, polyspaceserverroot
/polyspace/examples/cxx/Bug_Finder_Example
is the installation folder for Polyspace Server products, for instance,
polyspaceserverroot
/usr/local/Polyspace Server/R2019a/
.
You can easily adapt the script to run Code Prover. Replace
polyspace-bug-finder-server
with
polyspace-code-prover-server
. You can use the
demo example Code_Prover_Example
specifically meant
for Code Prover.
To run a Polyspace analysis on a server and review the results in the Polyspace Access web interface, you must perform a one-time setup.
To run the analysis, you must install one instance of the Polyspace Server product.
To upload results, you must set up the components required to host the web interface of Polyspace Access.
To view the uploaded results, you (and each developer reviewing the results) must have one Polyspace license.
Similar requirements apply to a Polyspace Code Prover™ analysis on a server.
See Install Polyspace Server and Access Products.
To install the Polyspace plugin, in the Jenkins interface, select Manage Jenkins on the left. Select Manage Plugin. Search for the Polyspace plugin and then download and install the plugin.
The following steps outline how to set up a Polyspace analysis in Jenkins after installing the Polyspace plugin. Note that the steps refer to Jenkins version 2.150.1. The steps in your Jenkins version and your Polyspace plugin installation might be slightly different.
If you use a different build automation tool, you can perform similar setup steps.
Specify the full paths of the folder containing the Polyspace commands and host name and port number of the server hosting the Polyspace Access web interface. After you specify the paths, in your scripts, you do not have to use the full paths to the commands or the server details for uploading results.
In the Jenkins interface, select Manage Jenkins on the left. Select Configure System.
In the Polyspace section, specify the following:
Paths to Polyspace commands.
The path refers to
,
where
polyspaceserverroot
/polyspace/bin
is the installation folder for Polyspace Server products, for instance,
polyspaceserverroot
/usr/local/Polyspace
Server/R2019a/
.
The host name, port number and protocol
(http
or
https
) used by the server hosting the
Polyspace Access web interface.
The Name field allows you to define a convenient shorthand that you use later in Jenkins projects.
In the E-mail Notification section, specify your company's SMTP server (and other details needed for sending e-mails).
When you create a Jenkins project (for instance, a Freestyle project), you can refer to the Polyspace paths by the global shorthands that you defined earlier.
To create a Jenkins project for running Polyspace:
In the Jenkins interface, select New Item on the left. Select Freestyle Project.
In the Build Environment section of the project, enter the two shorthand names you defined earlier:
The name for the path to the folder containing the Polyspace commands
The name for the details of the server hosting the Polyspace Access web interface.
Also, enter a login and password that can be used to upload to the Polyspace Access web interface. The login and password must be associated with a Polyspace Bug Finder Access license.
In the Build section of the project, you can enter scripts that use the Polyspace commands and details of the server hosting the Polyspace Access web interface.
The scripts run a Polyspace analysis and upload results to the Polyspace Access web interface.
In the Post-build Actions section of the project, configure e-mail addresses and attachments to be sent after the analysis.
This script runs a Bug Finder analysis, uploads the results and exports defects with high impact for a common notification email to all recipients.
The script assumes that the current folder contains a folder
sources
with .c
files. Otherwise modify
the line gcc -c sources/*.c
with the full path to the
sources.
set -e export RESULT=ResultBF export PROG=Bug_Finder_Example export PARENT_PROJECT=/public/BugFinderExample_PRS_01 # ================================================================ # Trace build command and create an options file build_cmd="gcc -c sources/*.c" polyspace-configure \ -allow-overwrite \ -allow-build-error \ -prog $PROG \ -author jenkins \ -output-options-file $PROG.psopts \ $build_cmd # ================================================================ # Run Bug Finder on the options file polyspace-bug-finder-server -options-file $PROG.psopts -results-dir $RESULT # ================================================================ # Upload results to Polyspace Access web interface $ps_helper_access -create-project $PARENT_PROJECT $ps_helper_access \ -upload $RESULT \ -parent-project $PARENT_PROJECT \ -project $PROG # ================================================================ # Export results filtered for defects with "High" impact $ps_helper_access \ -export $PARENT_PROJECT/$PROG \ -output Results_All.tsv \ -defects High # ================================================================ # Finalize Jenkins status exit 0 |
After the script is run, you can create a post-build action to send an e-mail to
all recipients with the exported file Results_All.tsv
.
In this script, $ps_helper_access
is a shorthand for the
polyspace-access
command
with the options specifying host name, port, login and encrypted password included.
The other polyspace-access
options are explicitly written in the
script.
This script runs the previous Bug Finder analysis and uploads the results. However, the script differs from the previous script in these ways:
The script uses a run_command
function that prints
a message when running a command. The function helps determine from the
console output which part of the script is running.
When exporting the results, the script creates a separate results file for different owners.
A master file Results_All.tsv
contains
all results. This file is sent in e-mail attachment to a
manager. The manager email is configured in the post-build
step.
If the file contains more than 10 defects, the build
status is considered as a failure. The script sends a status
UNSTABLE
in the e-mail
notification.
The results file
Results_Users_userA.tsv
exported for
userA
contains defects from the group
Programming and with impact High.
This result file is sent in e-mail attachment to
userA
.
The results file
Results_Users_userB.tsv
exported for
userB
contains defects from the
function bug_memstdlib()
.
This result file is sent in e-mail attachment to
userB
.
A separate mail subject is created for the manager in the file
mailsubject_manager.txt
and for users
userA
and userB
in the files
mailsubject_user_userA.txt
and
mailsubject_user_userB.txt
respectively.
A mail body is created for the email to the manager in the file
mailbody_manager.txt
.
The script:
Assumes that the current folder contains a folder
sources
with .c
files.
Otherwise, modify the line gcc -c sources/*.c
with
the full path to the sources.
Assumes users named userA
and
userB
. In particular, the email addresses
userA@companyname.com
and
userB@companyname.com
(determined from the user
name and SMTP server configured earlier) must be real e-mail
addresses.
Replace the names with real user names.
set -e export RESULT=ResultBF export PROG=Bug_Finder_Example export REPORT=Results_List.tsv # ================================================================ # Define function to print message while running command run_command() { # $1 is a message # $2 $3 ... is the command to dump and to run message=$1 shift cat >> mailbody_manager.txt << EOF $(date): $message EOF "$@" } # ================================================================ # Initialize mail body cat > mailbody_manager.txt << EOF Dear Manager(s) Here is the report of the Jenkins Job ${JOB_NAME} #${BUILD_NUMBER} It contains all Red Defect found in Bug Finder Example project EOF # ================================================================ # Trace build command and create options file build_cmd="gcc -c sources/*.c" run_command "Tracing build command", \ polyspace-configure \ -allow-overwrite \ -allow-build-error \ -prog $PROG \ -author jenkins \ -output-options-file $PROG.psopts \ $build_cmd # ================================================================ # Run Bug Finder on the options file run_command "Running Bug finder" \ polyspace-bug-finder-server -options-file $PROG.psopts -results-dir $RESULT # ================================================================ # Upload results to Polyspace Access web interface run_command "Creating Project $PARENT_PROJECT" \ $ps_helper_access -create-project $PARENT_PROJECT run_command "Uploading on $PARENT_PROJECT/$PROG" \ $ps_helper_access \ -upload $RESULT \ -parent-project $PARENT_PROJECT \ -project $PROG \ -output upload.output PROJECT_RUNID=$($ps_helper prs_print_runid upload.output) PROJECT_URL=$($ps_helper prs_print_projecturl upload.output $POLYSPACE_ACCESS_URL) # ================================================================ # Export report run_command "Exporting report from $PARENT_PROJECT/$PROG" \ $ps_helper_access \ -export $PROJECT_RUNID \ -output $REPORT \ -defects High # ================================================================ # Filter Reports run_command "Filtering reports for defects" \ $ps_helper report_filter \ $REPORT \ Results_All.tsv \ Family Defect \ # ================================================================ # Filter Reports for userA and userB run_command "Filtering Reports for userA: Group=='Programming' and Information=='Impact: High'" \ $ps_helper report_filter \ $REPORT \ Results_Users.tsv \ userA \ Group Programming \ Information "Impact: High" run_command "Filtering Reports for userB: Function=='bug_memstdlib()'" \ $ps_helper report_filter \ $REPORT \ Results_Users.tsv \ userB \ Function "bug_memstdlib()" # ================================================================ # Update Jenkins status # Jenkins build status is unstable when there are more than 10 Defects BUILD_STATUS=$($ps_helper report_status Results_All.tsv 10) # ================================================================ # Update mail body and mail subject NB_FINDINGS_ALL=$($ps_helper report_count_findings Results_All.tsv) NB_FINDINGS_USERA=$($ps_helper report_count_findings Results_Users_userA.tsv) NB_FINDINGS_USERB=$($ps_helper report_count_findings Results_Users_userB.tsv) cat >> mailbody_manager.txt << EOF Number of defects: $NB_FINDINGS_ALL Number of findings owned by userA: $NB_FINDINGS_USERA Number of findings owned by userB: $NB_FINDINGS_USERB All results are uploaded in: $PROJECT_URL Build Status: $BUILD_STATUS EOF cat >> mailsubject_manager.txt << EOF Jenkins for Manager - Polyspace run completed with status $BUILD_STATUS and $NB_FINDINGS_ALL findings EOF for user in userA userB do echo "Jenkins for $user - $($ps_helper report_count_findings Results_Users_$user.tsv)) findings" > mailsubject_user_$user.txt done # ================================================================ # Exit with correct build status [ "$BUILD_STATUS" != "SUCCESS" ] && exit 129 exit 0 |
After the script is run, you can create a post-build action to send an e-mail to a
manager with the exported file Results_All.tsv
. Specify the
e-mail address in the Recipients field, the email subject in
the Mail Subject field and the email body in the Mail
Body field.
In addition, a separate e-mail is sent to userA
and
userB
with the files
Results_Users_userA.tsv
and
Results_Users_userB.tsv
in attachment (and the content of
mailsubject_user_userA.txt
and
mailsubject_user_userB.txt
as mail subjects). The e-mail
addresses are userA@companyname.com
and
userB@companyname.com
(determined from the user name and SMTP
server configured earlier).
The script uses the helper function $ps_helper
to filter the
results based on group, impact and function. The helper function uses command-line
utilities to filter the master file for results and perform actions such as create a
separate results file for each owner. The function takes these actions as arguments:
report_filter
: Filters results from exported text
file based on contents of the text file.
For instance:
$ps_helper report_filter \ Results_List.tsv \ Results_Users.tsv \ userA \ Group Programming \ Information "Impact: High"
Results_List.tsv
and writes to the file
Results_Users_userA.tsv
. The text file
Results_List.tsv
contains columns for
Group
and Information
. Only
those rows where the Group
column contains
Programming
and the
Information
column contains Impact:
High
are written to the file
Results_Users_userA.tsv
.report_status
: Returns UNSTABLE
or SUCCESS
based on the number of results in a
file.
For instance:
BUILD_STATUS=$($ps_helper report_status Results_All.tsv 10))
UNSTABLE
if the file
Results_All.tsv
contains more than 10 results (10
rows).report_count_findings
: Reports number of results in
a file.
For instance:
NB_FINDINGS_ALL=$($ps_helper report_count_findings Results_All.tsv)
Results_All.tsv
.prs_print_projecturl
: Uses the host name and port
number to create the URL of the Polyspace Access web interface.
For instance:
PROJECT_URL=$($ps_helper prs_print_projecturl Results_All.tsv $POLYSPACE_ACCESS_URL)
Results_All.tsv
(exported by the
polyspace-access
command) and extracts the URL of
the Polyspace Access web interface in
$POLYSPACE_ACCESS_URL
and the URL of the current
project in $PROJECT_URL
.
polyspace-access
| polyspace-bug-finder-server
| polyspace-configure
| polyspace-report-generator
| polyspace-code-prover-server
(Polyspace Code Prover Server)