Installing and integrating Klocwork CI for the command-line

Klocwork easily integrates with your company’s command-line-based build environment. Simply integrate Klocwork CI by adding a small number of build steps to the build configuration.

Integrating Klocwork CI into your build environment

At the low level, the kwconan command line utility provides support for CI. The kwconan command line utility integrates with any build environment that supports scripting, to provide analysis results for your CI software builds. The steps below are for users who use a custom command-line-based environment. For TeamCity, see Installing and configuring Klocwork for the TeamCity plugin and for Jenkins, see Installing Klocwork for the Jenkins plugin.

Add the following steps to your build configuration:

1. Capture or update your native build specification with the kwinject command.

   In your build environment, issue your regular build command, but prefix it with the kwinject command.

   kwinject <my_build_command>

   For example, if your build command is "make", run the following command:

   kwinject make

   An updated build specification will be created when your build is complete.

   Note: For accurate results, the build specification (kwinject.out) should be persisted between builds
2. Generate static analysis results by using the kwbuildproject command.
   To generate the list of defects introduced and fixed since your last build, run kwbuildproject in incremental conan mode, specifying the name and server location of your project.

   kwbuildproject --url http(s)://<host>:<port>/<project_name> --incremental --conan --tables-directory <dir> [<options>] <build_specification1> [<build_specification2>...]

   where
   • <host> is the host name of the Klocwork Server
   • <port> is the port number of the Klocwork Server
   • <project_name> is the name of the Klocwork project you want to run kwconan against
   • <dir> is the output tables directory (mandatory argument)
   • <options> are any of the options for kwbuildproject
   • <build_specification> is the build specification you generated earlier. You can specify any number of build specifications with this command.

   Example

   kwbuildproject --url http://jsmith02:8080/my_project --incremental --conan --tables-directory mytables /home/klocwork/myproject.out

3. Analyze the results by adding the kwconan run command.

   Analyze the results against the baseline and create a list of new and fixed defects by adding the kwconan run command. This will output the results in JSON format. You can capture this output and store it in a file. This file can be turned into an artifact, depending on your CI system.

   kwconan run --tables-directory <dir> --url http://<host>:<port>/<project_name>

   where

   • <dir> is the path to the tables directory created by kwbuildproject. If you attempt to use a tables directory for a full build analysis, you will receive an error and no results will be shown.
   • <host> is the host name of the Klocwork Server
   • <port> is the port number of the Klocwork Server
   • <project_name> is the name of the project you want to run kwconan against

   Example

   kwconan run --tables-directory mytables --url http://jsmith02:8080/my_project --json

4. Interpret the results of the analysis and take action. If you are having trouble getting the results to display, see the Continuous integration issues for additional help.

   You can check the results and take actions according to your process. For example, you can fail the build and notify developers if any critical issues are found or reject a staged changeset. You can combine step 3 with this step by creating a script that runs the kwconan run command and processes the results in a single step.

   Note: If you attempt to use a tables directory created for a full build analysis, you will receive an error and no results will be shown.
5. Update the baseline by running the kwconan promote command.

   Add the kwconan promote command to the build steps to be able to update the baseline with the current analysis results.

   In some cases you may want to skip this step and discard the current analysis results, for example, if new issues were detected in a pre-commit or staged changeset. If you do not promote the analysis results, they will be reported in the next build.

   kwconan promote --tables-directory <dir> --url http://<host>:<port>/<project_name>

   where

   • <dir> is the path to the tables directory created by kwbuildproject. If you attempt to use a tables directory for a full build analysis, you will receive an error and no results will be shown.
   • <host> is the host name of the Klocwork Server
   • <port> is the port number of the Klocwork Server
   • <project_name> is the name of the project you want to run kwconan against