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.
- 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:
A build specification (called kwinject.out by default) will be created when your build is complete.
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/Note: 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).
kwinject --output test.out devenv mysolution.sln /Rebuild
kwinject --output test2.out msbuild mysolution.sln /t:Rebuild /p:Configuration=Debug
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
- 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.
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:
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.
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.