Creating a C/C++ build specification

From current

Switch to C# | Java

Contents

Insight integrates with your build, capturing all of the information it needs to provide a centralized view of the entire code stream.

Insight stores this information in a structured build log -- a text file we call a build specification. The build specification is the basis of the Insight analysis.

It's important 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.

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.

This article shows you how to use kwinject to capture your build settings. kwinject is recommended for capturing build settings for all C/C++ projects, except if you are running distributed builds (where the compiler is executed across several machines):

Prerequisites

Before you can create a build specification, you need to install the Server or User package. See Installing Klocwork Insight.

Capture your build settings

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

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:

  1. Change the working directory to the top-level source directory that contains the make information, for example: 
     cd /usr/local/zlib-1.2.3/
    Note: A typical open-source project may require some initial setup. Usually this is done with scripts called make clean and configure.
  2. 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).

Examples: 

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

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

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. 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

For certain compilers, you need to comment and/or uncomment lines in the compiler mapping file, located at <klocwork_install>/config/kwfilter.conf.

Green Hills GHS: Uncomment the following lines: 

filter	ghs	gcc, gcx, ccarm, cxarm, ccmips, cxmips
#filter	ghscom	ecomarm
You also need to comment out the GNU line: 
#filter	gnu	gcc, g++, cc, c++

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

filter	xlc	cc
You also need to comment out the GNU line: 
#filter	gnu	gcc, g++, cc, c++

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

filter	gnu_ld	ld

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

filter	ldarc	ldarc, ldac

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

filter link_hc12 linker
filter lib_hc12 libmaker

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

filter coverage coverage

GCC cross-compilers: There are many GCC cross-compilers (such as CodeSourcery, GNU ARM, and Atollic ARM). The executable names vary, depending on factors such as vendor, compiler version and target ABI, so it's impossible for Klocwork to include them all in kwfilter.conf. However, kwinject can typically determine the configuration for these compilers successfully if you add the exact compiler name to the filter gnu line in kwfilter.conf. For example: 

#filter	gnu	gcc, g++, cc, c++, arm-atollic-eabi-gcc

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:

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 update your build specification

You need to update or create a new build specification in the following situations:

  • if source files are added or removed
  • if build settings are changed

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

Note: If you have done a clean build (full rebuild of your source files), we recommend that you create a new build specification and perform a full build analysis. See Running a full build analysis.

Incremental updates to your build specification

After you have created a build specification with kwinject, you can update it, rather than creating an entirely new build specification, whenever you perform an incremental analysis of your desktop or integration project.

Use the --update option of kwinject to update an existing build specification. For more information, see Running incremental analysis.

What's next?

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

See also

Retrieved from "http://www.klocwork.com/products/documentation/current/Creating_a_C/C%2B%2B_build_specification"