In the simplest scenario for a kwwrap-based build integration, you are doing a make build, and your makefile defines several widely used variations on the name of your C compiler, C++ compiler, and linker/librarian.

Inserting kwwrap into your makefile causes kwwrap to execute for every compile and link command in your build, and generate a build trace while your build runs. A build trace is a file that contains the sequence of process calls that took place during your build (for example, the make command).

Note that you must always specify the full path to the trace file, so that kwwrap is always writing to the same file. In addition, if you run the kwwrap-enabled build more than once with the same settings, delete the previously generated build trace before running the build again. Otherwise, the trace file will contain commands from multiple builds.

To integrate kwwrap with your build:

1. Edit your makefile, inserting the kwwrap command line before your compiler and linker names. For example, the following lines in our makefile:

   CC = gcc
   CXX = g++
   AR = ar
   

   are replaced by:

   CC = kwwrap -o <path_to_kwwrap_trace_file> gcc
   CXX = kwwrap -o <path_to_kwwrap_trace_file> g++
   AR = kwwrap -o <path_to_kwwrap_trace_file> ar

   where <path_to_kwwrap_trace_file> is the full path to the build trace file that will be generated by kwwrap.

2. Run your build command (for example, make).

   kwwrap generates a build trace while your build runs. It is stored in the location specified in the make file.

3. Convert the build trace into a build specification with kwinject.

   kwinject --trace-in <path_to_kwwrap_trace_file> --output <path_to_kwinject_output_file>
   

   For example:

   kwinject --trace-in C:/temp/kwwrap.trace --output C:Klocwork/temp/kwinject.out
   

Example

$ cd /path/to/zlib-1.2.2
... configure and generate Makefile
$ ./configure
... now edit the Makefile
-- file: zlib-1.2.2/Makefile
...
CC=kwwrap -o /path/to/kwwrap.trace gcc
LDSHARED=kwwrap -o /path/to/kwwrap.trace gcc
AR=kwwrap -o /path/to/kwwrap.trace ar rc
...
-- cut
... run the build using wrapped compiler/linker; kwwrap.trace will be generated
$ make
... convert the raw build trace to a build specification
$ kwinject -t /path/to/kwwrap.trace -o kwinject.out

For situations where the compiler must be substituted with a single command (that is, without options such as -o), on Windows, you can create a configuration file for kwwrap. The file must be named kwwrap.conf, and it must be located in the same directory as kwwrap.

Each line of the kwwrap configuration file has the following format:<executable_name>=<options_list>

where

• <executable_name> is the name of the compiler or linker executable
• <options_list> is the list of kwwrap options

Notes

• There should be no spaces before and after the equal sign (=).
• Use double quotes (") to specify a variable value that includes spaces.

Example kwwrap.conf file

cl.exe=-o "C:\My traces\mozilla.trace" "C:\Program Files\Microsoft Visual Studio .NET\Vc7\bin\cl.exe"
link.exe=-o "C:\My traces\mozilla.trace" "C:\Program Files\Microsoft Visual Studio .NET\Vc7\bin\link.exe"

Using environment variables

If changing the original makefile is not an option, you can use environment variables to override the values set by the makefile. You can then use the --environment-overrides (-e) option of GNU make or MS nmake.

UNIX example, using make and gcc

... building on UNIX
$ cd zlib-1.2.2
... build
$ ./configure
...
$ CC="kwwrap -o /path/to/kwwrap.trace gcc"
$ AR="kwwrap -o /path/to/kwwrap.trace ar rc"
$ LDSHARED="kwwrap -o /path/to/kwwrap.trace gcc"
$ export CC AR LDSHARED
... build using wrapped compiler/linker; kwwrap.trace will be generated
$ make -e
... convert build trace to build specification
$ kwinject -t /path/to/kwwrap.trace -o kwinject.out

Windows example

On the Windows platform, zlib is built with Microsoft's nmake and cl-compiler. The Microsoft-specific makefile uses a slightly different set of variables: CC, AR and LD.

... building on Windows
> cd d:\path\to\zlib-1.2.2
... set up environment variables
> set CC=kwwrap -o d:\path\to\kwwrap.trace cl
> set AR=kwwrap -o d:\path\to\kwwrap.trace lib
> set LD=kwwrap -o d:\path\to\kwwrap.trace link
... build uses wrapped compiler/linker; kwwrap.trace will be generated
> nmake -e -f win32\Makefile.msc
... convert build trace to a build specification
> kwinject -t d:\path\to\kwwrap.trace -o kwinject.out

Creating wrapper scripts

xerces is a medium-sized open-source project that uses GNU make to build on UNIX. The simple approach of editing the makefile does not apply here, because xerces uses a custom configuration script that does not accept a compiler name that includes spaces, such as "kwwrap gcc". Instead, we can create wrapper scripts.

Example

$ cd /path/to/xerces-c-src_2_6_0
... create a directory for shell-wrappers
$ mkdir kw-wrappers
... create several simple wrapper scripts and save them into the kw-wrappers directory:
-- file: kw-wrappers/kwwrap-gcc
#!/bin/sh
exec kwwrap -o /path/to/kwwrap.trace gcc "$@"
-- file: kw-wrappers/kwwrap-g++
#!/bin/sh
exec kwwrap -o /path/to/kwwrap.trace g++ "$@"
-- file: kw-wrappers/kwwrap-ar
#!/bin/sh
exec kwwrap -o /path/to/kwwrap.trace ar "$@"
-- cut
... don’t forget to set the execute permissions on the created scripts
$ chmod +x kw-wrappers/*
... set up PATH and other environment variables
$ PATH=$PWD/kw-wrappers:$PATH
$ CC=kwwrap-gcc
$ CXX=kwwrap-g++
$ AR=kwwrap-ar
$ export CC CXX AR
... configure xerces
$ XERCESCROOT=$PWD
$ cd $XERCESCROOT/src/xercesc
$ ./runConfigure -p linux -c $CC -x $CXX
... build using the wrapper scripts; build trace will be generated
$ make
... generate a build specification from the build trace
$ kwinject -t /path/to/kwwrap/trace -o kwinject.out

If you use CMake to manage your build process, you can modify your CMakeLists.txt file to generate a build trace file that can be used as input to kwinject to generate your build specification file. You can use this method if you have System Integrity Protection (SIP) enabled on Mac OS X 10.10 or later.

set(KWWRAP_PATH "<path to Klocwork install directory>/bin/kwwrap")   # Specify kwwrap full path
set(KWWRAP_TRACE_PATH "${PROJECT_BINARY_DIR}/kw.trace")              # Specify path to Klocwork trace file
set(KWWRAP_TARGET "${KWWRAP_PATH} -o ${KWWRAP_TRACE_PATH}")
 
set(CMAKE_C_COMPILE_OBJECT "${KWWRAP_TARGET} ${CMAKE_C_COMPILE_OBJECT}")
set(CMAKE_C_LINK_EXECUTABLE "${KWWRAP_TARGET} ${CMAKE_C_LINK_EXECUTABLE}")
set(CMAKE_C_CREATE_SHARED_LIBRARY "${KWWRAP_TARGET} ${CMAKE_C_CREATE_SHARED_LIBRARY}")
set(CMAKE_C_CREATE_SHARED_MODULE "${KWWRAP_TARGET} ${CMAKE_C_CREATE_SHARED_MODULE}")
set(CMAKE_C_CREATE_STATIC_LIBRARY "${KWWRAP_TARGET} ${CMAKE_C_CREATE_STATIC_LIBRARY}")
 
set(CMAKE_CXX_COMPILE_OBJECT "${KWWRAP_TARGET} ${CMAKE_CXX_COMPILE_OBJECT}")
set(CMAKE_CXX_LINK_EXECUTABLE "${KWWRAP_TARGET} ${CMAKE_CXX_LINK_EXECUTABLE}")
set(CMAKE_CXX_CREATE_SHARED_LIBRARY "${KWWRAP_TARGET} ${CMAKE_CXX_CREATE_SHARED_LIBRARY}")
set(CMAKE_CXX_CREATE_SHARED_MODULE "${KWWRAP_TARGET} ${CMAKE_CXX_CREATE_SHARED_MODULE}")
set(CMAKE_CXX_CREATE_STATIC_LIBRARY "${KWWRAP_TARGET} ${CMAKE_CXX_CREATE_STATIC_LIBRARY}")

The --pretend option of kwwrap can be used to run a "pretend build"--a build in which your compiler and linker are never executed. With this option, kwwrap writes the supplied command line to a build trace, but does not run the command.

A "pretend" build generally takes less time than a real build, and the generated build trace is not accurate. This approach therefore only makes sense for simple projects, and projects where an accurate build specification is not critical.

Here is an example using zlib. This example uses environment variables to override makefile settings as described in Using environment variables.

$ cd zlib-1.2.2
... build
$ ./configure
... set up environment variables
$ CC="kwwrap -p -o /path/to/kwwrap.trace gcc"
$ AR="kwwrap -p -o /path/to/kwwrap.trace ar rc"
$ LDSHARED="kwwrap -p -o /path/to/kwwrap.trace gcc"
$ export CC AR LDSHARED
... "pretend" build using wrappers; compiler/linker are not executed
$ make -e -i
... convert the build trace to a build specification
$ kwinject -t /path/to/kwwrap.trace -o kwinject.out

• Read the how-to article, Creating C/C++ KAST checkers.
• Watch a demo of Checker Studio here.
• Try writing a checker with Tutorial 1 - Creating a C/C++ KAST checker.

Prerequisites

The Klocwork Extensibility Interface is installed as part of the Klocwork command line feature from the Klocwork Product Portal.

Mac users: You must have a working version of the GCC compiler to create custom checkers.