Creating a C/C++ build specification

Klocwork integrates with your build, capturing all of the information it needs to provide a centralized view of the entire code stream. It stores this information in a structured build log -- a text file we call a build specification. The build specification is the basis of the Klocwork analysis.

A build specification is required at both the integration and local build levels.

For the integration build, creating a build specification is the first essential task following installation.
For some desktop environments, build integration happens automatically; for others, you need to create a build specification manually. If you're not sure whether you need to create a build specification manually, go to Fixing issues before check-in with Klocwork Desktop Analysis and choose your coding environment.

It's essential that the build specification is an accurate and up-to-date representation of your build. If the build specification is inaccurate, the Klocwork analysis will be inaccurate too.

Use the kwinject command to capture build settings for all C/C++ projects, except in certain circumstances such as the following:

If you're using Electric Cloud, see Integrating Klocwork with Electric Cloud.
For other distributed build environments, including Klocwork's distributed analysis, see Using kwwrap plus kwinject to generate a build specification.

Prerequisites

Install the Server package. See Installing Klocwork.
Perform a clean build of your project. Project build errors can interfere with Klocwork's ability to create a complete and accurate build specification.

Capture your build settings

The first time you run the kwinject command on a project, verify that you have a clean build of that project. You can do this by running the clean command, for example make clean.

You can also check out our cheat sheet as a quick reference C/C++ integration build analysis - Cheat sheet.

Troubleshooting: Not sure if your compiler is supported out-of-the-box? Go to Making sure kwinject recognizes your compiler.

In your build environment, issue your regular build command, but prefix it with the kwinject command, plus whatever kwinject options you need. For a full list of kwinject options, see kwinject.

kwinject [kwinject_options] <build_command> [args]

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

kwinject make

A build specification (called kwinject.out by default) will be created when your build is complete.

Example

This example uses zlib. Just substitute your information for the zlib-specific information:

Change the working directory to the top-level source directory that contains the make information, for example:
```
 cd /usr/local/zlib-1.2.3/ 
```
A typical open-source project may require some initial setup. Usually this is done with scripts called make clean and configure.
We'll use the --output option to specify the name and location of the output text file. In our example, this becomes:
```
 kwinject --output /home/klocwork/zlib.out make 
```
This example specifies that the output file should be named zlib.out . If you don't use the --output option, kwinject automatically names the build specification file kwinject.out and saves it to the current working directory.
Once the build is complete, the build specification is saved to the specified location.

Troubleshooting: If you see the error message "Compiler can't be configured", see kwinject error - Compiler can't be configured.

Visual Studio projects

You can use kwinject to create a build specification if you build your Visual Studio projects from the command line (with devenv, msdev, vcbuild or msbuild).

We recommend that you run kwinject from a Visual Studio command prompt in order to more accurately capture the Visual Studio build environment settings.

Examples:

kwinject --output test.out devenv mysolution.sln /Rebuild

kwinject --output test2.out msbuild mysolution.sln /t:Rebuild /p:Configuration=Debug

You don't need to specify the configuration with devenv, because it uses the default.

If you are using VS2012:

In order to produce the correct build specification, you must do the following:

Kill orphan MSBuild.exe processes before running devenv
Set MSBUILDDISABLENODEREUSE environment variable to 1
When building via MSbuild, use the /nodereuse:false option

Making sure kwinject recognizes your compiler

For kwinject to recognize your compiler name, you may need to identify what compiler type is associated with your compiler (for example, gcc is a variant of GNU).

Go to C/C++ compilers supported for build integration and look up your compiler type to see if it's supported.

If you don't know your compiler name, see Using a build trace to troubleshoot build specification problems to learn how to generate a build trace and review it for your compiler name.
If your compiler doesn't appear in this table at all, contact Customer Support so that we can support your compiler. See Adding an unsupported C/C++ compiler for the information you'll need to send to Support.
If your compiler's exact name doesn't appear in the table, but you know it's one of the supported compiler types, you need to bind your compiler's name to the compiler type recognized by kwinject. Create a custom kwfilter.conf file as noted below or run kwinject with the --prog option. For example, if your compiler is gcc4 and you know this is a variant of GNU, run the following command:
```
kwinject --prog gcc4=gnu make 
```
For more information, see Troubleshooting an incomplete kwinject build specification.

Notes for specific compilers

To automatically deploy a custom binding to build machines and developer desktops, you need to deploy a custom kwfilter.conf file, as follows:

Create an empty kwfilter.conf somewhere outside of your <install>/config directory and add your desired compiler(s). For example, add a line from the samples below or copy a commented line from the default <install>/config/kwfilter.conf file and place it in the new file, removing the comment tags.
Copy the new file to your <projects_root>/compiler_config directory. If this folder does not already exist, then create it.
Run kwdeploy sync on your build machines to sync your changes. Connected developer desktops are updated after the next local analysis.

For more information about this procedure, see Deploying kwfilter.conf.

Here are some sample compilers:

Green Hills GHS: Add the following lines:

filter     ghs     gcc, gcx, ccarm, cxarm, ccmips, cxmips
#filter ghscom  ecomarm

You also need to add the GNU line:

#filter    gnu     gcc, g++, cc, c++

Intel XL C/C++: Add the following line:

filter     xlc     cc

You also need to add the GNU line:

#filter    gnu     gcc, g++, cc, c++

GNU: Add the following line if ld is invoked directly (not through gcc):

filter     gnu_ld  ld

Metaware High C/C++: Add the following line if ldarc is invoked directly (not through hcarc):

filter     ldarc   ldarc, ldac

CodeWarrior Freescale S12: Add the following lines if you use the CodeWarrior S12 linker and libmaker:

filter link_hc12 linker
filter lib_hc12 libmaker

Wind River Diab: Add the following line if you are using the "coverage" tool:

filter coverage coverage

VSI-Cafe: For VSI-Cafe, add these lines:

filter cafe_compile cl
filter cafe_link link

Review your build specification for accuracy

Once you've got a build specification, confirm the existence of compile , link and config lines.

Carefully review the build specification to ensure that your compiler options have been processed properly. For more information on making sure kwinject has accurately captured your build settings, see:

Format of the build specification file for C/C++ projects

If your build specification contains only a version line or is missing the config line, go to Troubleshooting an incomplete kwinject build specification.

When to recreate your build specification

After a build specification file exists, by default, Klocwork updates the file instead of overwriting it.

In certain situations, Klocwork highly recommends you create a new build specification (by using the --overwrite option):

if you upgrade to a new version of Klocwork
if you modify build settings
if you have done a clean build (full rebuild of your source files)

If you reuse an existing build specification or try to modify it manually in these situations, the analysis results will not be accurate.

What's next?

Now it's time to use your build specification to run an analysis.

If you're analyzing an integration project, go to Running the C and C++ integration build analysis.
If you're analyzing a desktop project, go to Fixing issues before check-in with Klocwork Desktop Analysis and pick your development environment.