Introduction

klocwork

The Klocwork Plugin for Jenkins, developed by Emenda and the open source community, provides an easy way for Klocwork users to automate industry leading static code analysis as part of their Continuous Integration or Continuous Deployment environments.

Jenkins Logo

The plugin provides a simple interface within Jenkins to configure Klocwork settings and to automate the different Klocwork build steps required for analysis.

For example, the plugin allows you to globally define multiple Klocwork servers from which you can easily select one via drop down menu when setting up a Jenkins job.

Furthermore, the plugin includes build steps that will automatically analyse your entire project and upload the results to the Klocwork server. This means you no longer have to manually execute Klocwork commands via terminal  every time you would like to run analysis. All you have to do is select the desired build steps and tell Jenkins how often you would like Klocwork to perform an analysis.

By automating the different stages of analysis, the plugin does all the heavy lifting so that you can focus on delivering higher quality code faster!


Contents

It is assumed that a basic level of Jenkins and Klocwork exists before setting up the plugin. Please also note that there is considerable help within the plugin, accessible by clicking the help icons when configuring each part of the plugin.

  1. Features
  2. Prerequisites
  3. Plugin Installation
  4. Setting up the plugin
    1. Global Jenkins Settings
    2. Avoid Global Jenkins Settings
    3. Basic Jobs
    4. Example Job with zlib
      1. Build Environment
      2. Integration Analysis
      3. Incremental Diff Analysis
      4. Cross-Project Issue Sync
      5. Quality Gateway
      6. Publish Integration Results
    5. Job-DSL
    6. Pipelines
  5. Support

1. Features

Klocwork supports a server-client architecture. The server tools are used for integration analyses, typically run on build servers/slaves. The client tools are used for incremental analyses of deltas, that support real-time analysis of developers changes as code is being developed. It has become increasingly popular to perform Quality Gateway or Gating checks of developers changes, and the client tools are a perfect fit for this operation. Thus, the Jenkins Klocwork community plugin supports both Server Integration Analyses and Incremental Client Quality Gateway checks.

To support the DevOps and Continuous Delivery (CD) movement requiring speed from a static analysis tool, the plugin provides a “Diff” mechanism (based on your version control system), such that we only analyse those files which were changed in the last change set. Git is supported out-of-the-box, and all other versioning systems are supported with minimal setup. This enables Klocwork to utilise the client tools to perform an Incremental Diff Analysis – acting as a Quality Gateway to approve or reject developers’ changes.


2. Prerequisites

  • Minimum Jenkins core version: 1.614
  • The Jenkins server must be running on the Java 1.8 JRE. For instructions on how to change this please see this guide
  • Klocwork version 9.6 or newer
  • The Klocwork Community plugin does not contain the Klocwork build tools, it is required to install or deploy the Klocwork build tools to the build machine (master/slave) manually

3. Plugin Installation

To install the Klocwork plugin, click on Manage Jenkins on the left side bar, and then click on Manage Plugins.

 

Click on the Available tab and type ‘Klocwork’ in the filter box.  The search result ‘Klocwork Community Plug-in’ should appear.

Tick the checkbox to select the plugin.

Click the Download now and Install after restart button.

After Jenkins restarts itself, you should see that the plugin has been installed.

4. Setting up the plugin

4.1. Global Jenkins Settings

This section will allow us to configure one or more Klocwork servers, which we can then later use in a Jenkins job.

(You can skip this step if you prefer to automatically configure the environment per-job/pipeline and just ensure that certain environment variables are set.)

Click on Manage Jenkins on the side bar, and then click on Configure System.

Scroll down to the Klocwork section as shown below.

To get started, for each Klocwork server you would like to define, enter the server URL and give it a label. You may also enter specific license settings for a particular Klocwork server you define inside Jenkins. Alternatively, you could just specify a global license host for all Klocwork servers to use by default if a specific license host is not configured.

The Advanced button at the bottom allows you to specify PATHs to a <server_install>/bin/ directory. This will allow you to have access to the Klocwork command line tools which will be needed when creating a Jenkins job later. If already have a provisioning system that sets up the environment/paths for your tools then we suggest you also do this for Klocwork. We only provide this functionality for basic setups.

Save your settings.

4.2. Avoid Global Jenkins Settings

If you want to avoid global settings within Jenkins then the following variables are those which need to be set for a job (depending on which tools you use for that job)

You can set the value of these variables on a per job basis via other Jenkins plugins, such as EnvInject.

  • KLOCWORK_URL – e.g. http://xubuntu-emenda:8080, this is the address of the Klocwork server to connect to
  • KLOCWORK_PROJECT – the project you want to connect to. Requires the KLOCWORK_URL
  • KLOCWORK_LICENSE_HOST – the license host used for the job
  • KLOCWORK_LICENSE_PORT – the license port used for the job
  • KLOCWORK_LTOKEN – (optional) specify a custom location for the Klocwork Ltoken (authentication token)

Additionally, the path to the Klocwork tools should be added to the PATH environment variable.

4.3. Basic Jobs

This section goes over how to configure the Jenkins Klocwork community plugin for freestyle / matrix / multi-configuration jobs in Jenkins.

4.3.1. Build Environment

The plugin reads from the environment to retrieve values (e.g. Klocwork server URL, project name, license settings), so the first thing we need to do is configure the environment. If you setup the Global Jenkins settings you can do this through the GUI under Build Environment:

Check the box for Klocwork – Build Environment Settings.

Click on the advanced buttons in order to have the same fields available as shown in the screenshot above.

From the Klocwork Server Configuration drop down menu, select the name of the Klocwork server you configured when setting up the Klocwork Plugin in the previous section.

Enter the name of the Klocwork project you wish to analyse. This must match with a project name on the specified Klocwork server.

Optionally, click on the drop down menu for Klocwork Install Configuration and select the name representing the path to the Klocwork server installation directory you typed in when setting up the plugin’s global settings.

Optionally, you may also input the path to the ltoken. The ltoken file can be found in your .klocwork directory. If the .klocwork directory does not exist, run kwauth. The ltoken file should then be generated and you can add its path to Jenkins.

If you chose to avoid global settings, use a plugin such as EnvInject or Parameterized Builds to configure the environment variables listed here.

4.3.2. Integration Analysis

This section will configure the different build steps for an integration analysis  on a project build.  Usually, this will consist of using the Klocwork server tools, running the integration analysis, and loading the results on to the Klocwork server. Due to popular demand, these steps have been separated out in order for users to perform custom operations to the Klocwork tables directory. By toggling the Advanced sections of the build steps you can set other options such additional flags to pass to the commands, the name of the tables directory, and any custom configurations that should be imported before the analysis.

The build steps provided by the plugin are listed below:

  • Klocwork – Full Integration Analysis (step 1 – analysis)
    • Runs kwbuildproject on the build to perform a full integration analysis
  • Klocwork – Full Integration Analysis (step 2 – DB load)
    • Uploads the results of the full integration analysis to the database on the Klocwork serve
  • Klocwork – Cross-Project Issue sync
    • Synchronises issues across different projects based on the Project Filter (which determines which projects should be processed during synchronisation) and the Last Synchronisation Date (how far back Klocwork should go when synchronising issue citations)
  • Klocwork – Incremental Diff Analysis
    • Selectively runs an analysis only on files that have changed between the current and previous build

In the simplest case, all we would need to do here is click on the Add build step button and add the following build steps

  • If on Linux: Execute shell. If on Windows: Execute Windows batch command
  • Klocwork-Full Integration Analysis (step 1 – analysis)
  • Klocwork-Full Integration Analysis (step 2 – DB load)

Inside the Execute Shell/Execute Windows batch command textbox, enter the appropriate Klocwork integration tool command e.g. kwinject followed by the appropriate project build tool command e.g. make

4.3.3. Incremental Diff Analysis

To perform an Incremental Diff Analysis using the Klocwork client (A.K.A desktop) tools, select the Incremental Diff Analysis build step. By default the analysis is incremental, but often we do not want to keep a Jenkins workspace or previous build results and therefore we only want to analyse changed files. How do we know which files have changed? Well, your versioning system should know, and hence you can specify a previous commit to analyse using Git, or a custom file (default “diff_file_list.txt”) which contains a list of files to analyse, separated by new lines. If you selected git, the plugin automatically executes a git diff with the “–name-only” flag.

The beauty of this is that we can quickly analyse only the changed files and get immediate results. The post-build publisher step then provides a Quality Gateway capability to fail or pass the Jenkins job based on the analysis results. The Advanced section allows you to specify more options, such as location of the generated XML report, location of the Klocwork tables directories and any additional flags to pass to the Klocwork command (kwcheck).

4.3.4. Cross-Project Issue Sync

The cross-project issue sync uses the command kwxsync to synchronise Klocwork issues across multiple projects. For example, if many projects share a common code base and as such, many of the issues discovered within these projects are the same, we can synchronise comments, statuses and ownership of these issues across projects on the Klocwork server.

For the command to do anything useful, please untick the “Perform Dry Run” option. As this command cannot be easily undone, we make dry running the default option for you to first configure the command correctly.

4.3.5. Quality Gateway

The quality gateway post-build step provides the ability to mark builds as failed, unstable, or passed in case a certain threshold is exceeded. The gateway can be applied to both the integration (server) and incremental (client) analyses.

Integration Analysis

In the below example we have configured two conditions.

  1. Marks the build as unstable if New MISRA-C:2012 issues discovered in the last build exceeds the set threshold of 1
  2. Marks the build as failed if New issues with Severity 1 or 2 have been discovered

Incremental Diff Analysis

Currently, the Quality Gateway for the client tools only sets a threshold and if ANY new issues found exceed this threshold the build is failed. We are working on expanding the functionality here, but currently if you want to filter the results you can add additional options to the Incremental Diff Analysis Build-step to filter based on severity, status, taxonomy, etc.

4.3.6. Publish Integration Results

The post-build publish step ‘Klocwork – Publish Klocwork test result report’ (previously known as just ‘Klocwork test result report’) provides the ability to query an integration build for results, and present these within the Jenkins dashboard.

As a pre-requisite, at least one integration build step (‘Klocwork (deprecated) – Invoke Klocwork command’ or ‘Klocwork – Full Integration Analysis *’) to must have been run and ideally this should be used 1-1 with analysis steps to build up the trend reports in Jenkins.

The key features for this step are:

  • Generates an xml file containing the results of the query
  • Generates a trend graph on the projects main page
  • Generates a state graph on the projects build page
  • Provides the ability to mark builds as failed, unstable, or passed in case a certain threshold is exceeded for the query (superseded by 2.3.5 Quality Gateway)
  • Creates a Klocwork server web page link to the project

Below is an example configuration that will report all open issues found in the latest integration build for the project, and fail the Jenkins job if it contains any new critical issues.

Note: that we are moving away from specific features to anything older than Klocwork 9.6 and thus we will only be concerning ourselves with the options and features used by Klocwork 9.6 and later.

  • Klocwork v9.6 and later: This tick box is used to tell the step whether it should be using the Web API (https://support.roguewave.com/documentation/klocwork/en/current/klocworkwebapicookbook/) introduced in version 9.6 of Klocwork and onwards.
  • Query: This is the Klocwork search query that will be used to retrieve issues from the server, the syntax should be the same as that from the Klocwork project web portal issues screen. The default query gets all the open issues in the project, but we tend to find that it might be more beneficial to just report on the new issues
  • Klocwork report XMLs: (deprecated) Not used with Klocwork v9.6 and later. Leave blank
  • Publish Graphs: Here we have two drop down boxes “No of Builds” and “Interval”. This allows us to adjust the trend graph to only display the last X builds and you can adjust to show every build or every Y build. We also have tick boxes that you can un-tick to not publish the trend or build graphs
  • Build status: (deprecated – Use the 2.3.5 Quality Gateway) This provides the ability to mark builds as failed, unstable, or passed. We can set a threshold and if the number of issues retrieved is greater than the threshold then the corresponding status is set. As in the example above a common threshold is to fail on any new issues by placing 0 in the New fail box.
  • Severity evaluation: (deprecated) Use the 2.3.5 Quality Gateway. We can apply the threshold to all issue severities, to just the critical or just the lower severities. Leave enabled the severities you wish to be considered against the threshold.
  • Trend Graph Configuration: Here you can set the size of the trend graph on the project page and which lines to display on the graph
  • Host Name: The Klocwork server hostname without the full http://
  • Port: The Klocwork server port, typically 8080
  • Project Name: The name of the Klocwork project as shown in the web portal
  • User: (deprecated) This field can be left blank as it uses the username from the generated ltoken
  • Fail Jenkins job if new Klocwork issues exist of severity: (deprecated) Use the 2.3.5 Quality Gateway

4.4. Example Job with zlib

We will test our Jenkins configuration by running an analysis on zlib, a small open source compression library. To do this, we will need to download the Git plugin for Jenkins.

Search for ‘Git plugin’ on the Manage Plugins page. Install it and restart Jenkins.

Finally, let’s create our first Jenkins job!

On the homepage, click on New Item on the left side bar, and then check Freestyle project. Give your job a name and then click OK.

 

Scroll down to Source Code Management and enter details as shown below.

 

Now scroll to Build Environment and input the appropriate settings for your system.

 

Scroll down to Build.

 

Click on the Add build step button and add the following build steps

  • If on Linux: Execute shell. If on Windows: Execute Windows batch command
  • Klocwork-Full Integration Analysis (step 1 – analysis)
  • Klocwork-Full Integration Analysis (step 2 – DB load)

Add the two commands to the Execute shell:

./configure

kwinject make

(./configure simply configures the make file for zlib)

Finally, Save the job. However, before we run it, we must create a ‘zlib’ project on the Klocwork server.

You can do this by running

kwadmin create-project –-url http://<kw server host>:<port number>/zlib

Once the project has been created, go ahead and run the job by clicking Build Now on the sidebar.

Wait for the job to finish running. You can monitor the job’s progress by hovering your mouse over the build number and clicking on the small arrow that appears, and then clicking on Console Output.

The console output is also very useful for identifying and debugging any errors encountered during the job.

 

Once the Jenkins job has finished, you can login to the Klocwork web portal to view the analysis results.

4.5. Job-DSL

More information on the Jenkins Job DSL plug-in.

The Klocwork plug-in supports DSL for job-generation. The following is an example of DSL structure for a Klocwork job:

job("DSL-Test") {
 wrappers{
  klocworkWrapper {...} //Contains settings for the job such as which Klocwork installation to use
 }
 steps{
  klocworkDesktopBuilder {
   desktopConfig {...} //Runs the kwcheck/desktop analysis, with support for "diff" analysis
   }
  }
 
  klocworkServerAnalysisBuilder {
   serverConfig {...} //Runs the kwbuildproject/server build analysis for uploading to the Klocwork server (step 1)
  }
 
  klocworkServerLoadBuilder {
   serverConfig {...} //Uploads the results of the analysis in the previous step to the Klocwork server (step 2)
  }

  klocworkXSyncBuilder {
   syncConfig {...} //Runs the kwxsync tool which synchronises statuses and comments in shared code across Klocwork projects
  }
 }
 
 publishers{
  klocworkGatewayPublisher {
   gatewayConfig {
    enableServerGateway(true)
    gatewayServerConfigs {...} //Server analysis gateway - pass/fail the Jenkins job based on server analysis results
    enableDesktopGateway(true)
    gatewayDesktopConfig {...} //Desktop analysis gateway - pass/fail the Jenkins job based on desktop analysis results
   }
  }
 }
}

4.5.1. Build Environment

Use klocworkWrapper to configure the plug-in if you are not configuring Klocwork via environment variables.

Syntax:

klocworkWrapper {
 serverConfig("<server config name>")
 installConfig("<install config name>")
 serverProject("<server project name>")
 ltoken("<ltoken location>")
}

4.5.2. Incremental Diff Analysis

Use klocworkDesktopBuilder to run the incremental “diff” analysis.

Syntax:

klocworkDesktopBuilder {
 desktopConfig {
  buildSpec("<build specification path/name>")
  projectDir("<custom project directory path/name>")
  cleanupProject(<true/false>)
  reportFile("<report output file path/name>")
  additionalOpts("<additional kwcheck options>")
  incrementalAnalysis(<true/false>)
  diffAnalysisConfig {
   diffType("<manual>/<git>")
   gitPreviousCommit("<previous commit value>") //if using git
   diffFileList("<diff file list path>") //if using "manual"
  }
 }
}

4.5.3. Integration Analysis

Use klocworkServerAnalysisBuilder to run the server/integration analysis and klocworkServerLoadBuilder to upload the results to the Klocwork server.

Syntax:

klocworkServerAnalysisBuilder {
 serverConfig {
  buildSpec("<build specification path/name>")
  tablesDir("<tables directory (analysis output) path/name>")
  incrementalAnalysis(<true/false>)
  ignoreCompileErrors(<true/false>)
  importConfig("<list of configuration files to import>")
  additionalOpts("<additional options to kwbuildproject>")
 }
}
klocworkServerLoadBuilder {
 serverConfig {
  tablesDir("<tables directory (analysis output) path/name>") //should match tablesDir value of klocworkServerAnalysisBuilder
  buildName("<build name>")
  additionalOpts("<additional options to kwadmin load>")
 }
}

4.5.4. Cross-Project Issue Sync

Use klocworkXSyncBuilder to run kwxsync: synchronise statuses and comments across Klocwork server projects.

Syntax:

klocworkXSyncBuilder {
 syncConfig {
  dryRun(<true/false>)
  lastSync("<DD-MM-YYYY hh:mm:ss>") //Time since last sync
  projectRegexp("<project regular expression>") //Regular expression - only matching projects will be included in the sync
  statusAnalyze(<true/false>) //Include status "Analyze"
  statusIgnore(<true/false>) //Include status "Ignore"
  statusNotAProblem(<true/false>) //Include status "Not a Problem"
  statusFix(<true/false>) //Include status "Fix"
  statusFixInNextRelease(<true/false>) //Include status "Fix in Next Release"
  statusFixInLaterRelease(<true/false>) //Include status "Fix in Later Release"
  statusDefer(<true/false>) //Include status "Defer"
  statusFilter(<true/false>) //Include status "Filter
  additionalOpts("<additional options to kwxsync>") 
 }
}

4.5.5. Quality Gateway

Use klocworkGatewayPublisher to add analysis gateways to your job.

Syntax:

klocworkGatewayPublisher {
 gatewayConfig {
  enableServerGateway(<true/false>)
  gatewayServerConfigs {
   klocworkGatewayServerConfig {
    jobResult("<failure/unstable/passed>")
    query("<Klocwork search query, e.g. Status:New>")
    threshold("<no. of issues to activate condition>")
    conditionName("<condition name>")
   }
  }
  enableDesktopGateway(<true/false>)
  gatewayDesktopConfig {
   threshold("<no. of issues to fail build>")
   reportFile("<kwcheck analysis output file path/name>")
  }
 }
}

4.6. Pipelines

More information on Jenkins pipelines.

The Jenkins Klocwork Community plugin supports the Declarative DSL pipelines. To auto-generate the DSL code (recommended for first timers), go to the Snippet Generator

4.6.1. Build Environment

As with normal jobs, you have the option to use the plugin’s builtin functionality to configure the build environment, or you can set this up manually be setting these environment variables.

Use the “klocworkWrapper” function if you want to use the plugin’s builtin functionality, e.g.
// use global Jenkins settings to configure the environment.
klocworkWrapper(installConfig: '-- none --', ltoken: 'kwltoken', serverConfig: 'xubuntu', serverProject: 'MY_PROJECT') {
// inside this block the environment variables are accessible
}

4.6.2. Integration Analysis

// example how to configure an integration analysis step 1 and 2
klocworkIntegrationStep1([additionalOpts: '', buildSpec: 'kwinject.out', ignoreCompileErrors: true, importConfig: '', incrementalAnalysis: true, tablesDir: 'kwtables'])
klocworkIntegrationStep2([additionalOpts: '', buildName: '${GIT_COMMIT}-BUILD-${BUILD_ID}', tablesDir: 'kwtables'])

4.6.3. Incremental Diff Analysis

// example how to configure a client incremental diff analysis, using the GIT_PREVIOUS_COMMIT environment variable to generate a change set
klocworkIncremental([additionalOpts: '', buildSpec: 'kwinject.out', cleanupProject: false, diffAnalysisConfig: [diffFileList: 'diff_file_list.txt', diffType: 'git', gitPreviousCommit: '${GIT_PREVIOUS_COMMIT}'], incrementalAnalysis: true, projectDir: '', reportFile: '']) 

4.6.4. Cross-Project Issue Sync

klocworkIssueSync([additionalOpts: '', dryRun: true, lastSync: '03-00-0000 00:00:00', projectRegexp: '', statusAnalyze: true, statusDefer: true, statusFilter: true, statusFix: true, statusFixInLaterRelease: false, statusFixInNextRelease: true, statusIgnore: true, statusNotAProblem: true])

4.6.5. Quality Gateway

Integration Analysis

klocworkQualityGateway([enableDesktopGateway: false, enableServerGateway: true, gatewayDesktopConfig: [reportFile: '', threshold: '1'], gatewayServerConfigs: [[conditionName: 'MISRA-C:2012 Compliance', jobResult: 'unstable', query: 'state:+New status:Analyze taxonomy:"MISRA C 2012 (C99)"', threshold: '1'], [conditionName: 'Critical Issues', jobResult: 'failure', query: 'state:+New status:Analyze severity:1,2', threshold: '1']]])

Incremental Diff Analysis

klocworkQualityGateway([enableDesktopGateway: true, enableServerGateway: false, gatewayDesktopConfig: [reportFile: '', threshold: '1']])

5. Support

Please see our handy listing of commonly faced issues and solutions on the troubleshooting page available: here

Please contact our global support team if you have a feature request, bug report or need any assistance with the plugin: support@emenda.eu