Kwinject

kwinject monitors your C/C++ and C# builds to create a build specification. You can then use the build specification to analyze a Klocwork project from a C/C++ or C# software system.

Project build errors can interfere with Klocwork's ability to create a complete and accurate build specification.

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.

Kwinject uses the --update option as its default behavior. This means if a build specification of the same name is found, running kwinject again appends to the build specification file instead of overwriting the file.

See also Environment variables used by kwinject.

Usage

To generate a build specification, in your build environment, run:

kwinject [option...] <build-command> [arg...]

To overwrite an existing build specification, run:

kwinject --overwrite [option...] <build-command> [arg...]

To generate a build trace, in your build environment, run:

kwinject [option...] --trace-out <file> <build-command> [arg...]

To convert a build trace to a build specification:

kwinject [option...] --trace-in <file>

To specify variables from a file to pass to kwinject:

kwinject -f <variable_file> <build-command> [arg...]

where:

  • [options] can be any of the options from the table below
  • <variable_file> is an options file for additional variables that is in the format of: OPTION=VALUE
  • <build-command> is your build command, for example, make
  • [arg...] is any arguments your build command requires
If you use Visual Studio, we recommend that you run kwinject from a Visual Studio command prompt in order to more accurately capture the Visual Studio build environment settings.

If you run your build with a script

When your build is run by a shell script (as with Cygwin or MKS Korn), you need to run kwinject as follows:

kwinject [options] sh <shell_script>

For example:

kwinject sh /usr/src/xerces-c-2.5.0-1.sh
When running kwinject under Cygwin, it is not possible to specify a symbolic link as the command argument for kwinject.

When your build is run by a batch script, you need to run kwinject as follows:

kwinject [options] cmd /c <batch_script>

For example:

kwinject cmd /c "my build.bat"

Options

Name Short name Description
--help -h display this help
--version -v display version
--cache-dir <directory>   use specified cache directory to save source files temporarily during the build process. The default location is the current working directory. The directory specified by the --cache-dir option does not contain the source files after the kwinject command completes.
--cache-files <pattern>[,<pattern>...] -C save source files matching one of the specified patterns; if any of these files are deleted during a build, they will be restored to their original location. Useful for preserving generated source files so that they can be included in the Klocwork analysis. See Caching temporary source files.
--config <file> -c read filter configuration from <file>. The default is <Klocwork_install>/config/kwfilter.conf. Allows you to use a "private" copy of kwfilter.conf and the compiler configuration files, so that the originals do not need to be modified. See Creating a C/C++ build specification, Creating a C-sharp build specification.
--debug   print debug information
--exclude-description <pattern>[,<pattern>...]   do not handle a program if the description matches on of the specified patterns.
--exclude-prog <pattern>[,<pattern>...]   do not handle programs matching one of the specified patterns.
-f <variable_file>   read variables from a specified file
--ignore-files <pattern>[,<pattern>...] -I ignore source files that match one of the specified patterns. <pattern> may contain the * and ? wildcards. For example: --ignore-files conftest.* specifies that temporary files created by the configure script will be ignored.
--no-config   do not read filter configuration from compiler mapping file,kwfilter.conf
--no-resolve  

do not resolve symbolic links. When the --no-resolve option is specified, it does not resolve paths in compiler options.

This command option is supported on Unix only.
--output <file> -o

write the build specification to <file>. By default, the build specification is written to kwinject.out in the current working directory. This option cannot be used with the --trace-out option.

If you are creating a build specification template, you need to give the file a name with the extension .tpl.
--overwrite -w Overwrites the existing build specification.

Whenever you run a clean build (full rebuild), you should use kwinject with the --overwrite option, to ensure that the build specification is accurate.

If you forget to use kwinject with your build command, or if you run kwinject with the --overwrite option with a partial build, you will end up with an inaccurate build specification. In this case, you should recreate the build specification by running kwinject with the --overwrite option.
--prog <prog>[=<filter>][,<prog>[=<filter>]...] -P the program or programs kwinject should use to intercept programs, if you want to use something other than the compilers searched for by default.

Specify the comma-separated list of programs to intercept, along with the appropriate filter to use. The default list of known programs and their filters is taken from the compiler mapping file, kwfilter.conf. The filter bindings defined through this option override any bindings read from a compiler filter file. See Troubleshooting an incomplete kwinject build specification for related information.

--trace-in <file> -t read build trace from <file>. When this option is used, the command and arguments are ignored in favor of the specified build trace. No external process is started; the intercepted commands and arguments are read from the previously saved build trace file instead. This option cannot be used with the --trace-out option or the <build-command> argument. See Using a build trace to troubleshoot build specification problems.
--trace-out <file> -T save build trace to <file>. This option cannot be used with any of the following options:
  • --trace-in
  • --output
  • --update
  • --variable
  • --no-resolve
  • --no-config
  • --config
  • --prog
  • --ignore-files
--variable <variable>=<string> -V replace every occurrence of <string> in the output file with a reference to <variable> instead. Using this option will create a build specification template, rather than a build specification. <variable> must be a unique sequence of alpha-numeric characters and underscores, starting with a letter. <string> is a directory path.
Important: When using this option, ensure that you also use the --output option to specify a file with the .tpl extension. See Providing a build specification template for your developers for how-to information.
--white-dir <directory>   specify a directory containing additional input files. This can be a temporary directory.