Kwbuildproject

The kwbuildproject command runs the integration build analysis and performs the following stages:

  • compilation
  • issue detection
  • linking
  • report generation

kwbuildproject is installed with the Klocwork Server package.

Related how-to articles: C/C++ | Java |C#

Notes

  • kwbuildproject automatically generates and uses precompiled header information.
  • For C/C++ projects, you can use kwbuildproject to run a distributed analysis.
  • kwbuildproject returns exit code 0 if the process was successful. Exit code 1 is returned when something went wrong but no tables were generated. Exit code 2 is returned when tables were generated but there was a critical error during the build (such as missing includes and compiler failures). For more information about C# exit codes, see below.
  • In addition to the tables directory, during analysis kwbuildproject will use additional space in your temp directory. The location of your temp directory is specified by your system's environment variables.

Usage

kwbuildproject --tables-directory <dir> 
--url http://<klocwork_server_host>:<klocwork_server_port>/<server_project>
[<other_options>] <build_specification_1> [<build_specification_2>...]

where:

  • <dir> is the output tables directory. The --tables-directory option is mandatory.
  • <klocwork_server_host>:<klocwork_server_port> and <server_project> identify the project for which you want to run the analysis, and the Klocwork Server where the project is located
  • <other_options> are any of the options from the table below
  • <build_specification_1> is a C/C++ | Java | C# build specification. You can specify any number of build specifications with this command.

You can also specify an arguments file for kwbuildproject:

kwbuildproject @<arguments_file>

You can create an arguments file to specify your command line arguments. Each argument must be specified on a separate line. (If the arguments file contains multibyte characters, the file must be UTF-8 encoded.)

Example 1

kwbuildproject --tables-directory C:\Klocwork\My_tables --url http://myserver:8080/myproject C:\Klocwork\kwinject.out

Example 2

You can also specify a stream, by using the '--project' or the –'url' option followed by the parent project name and specified stream name, as follows:

kwbuildproject C:\Klocwork\kwinject.out -o tables --url http://myserver:8080/myProj/stream1

However, streams configurations are shared between a stream and its 'base' project. For this reason, you should specify the base project if you are using the '--url' or '--project' flag in your analysis command: 

kwbuildproject kwinject.out -o tables --project myProject

Options

Name Short name Description
--add-compiler-options "<option_1> [<option_2>...]" -a

pass additional options to the C/C++ compiler. To pass multiple compiler options, separate them by spaces, and surround the entire string in quotation marks. Acceptable values are Compiler options for kwbuildproject.

Example:

--add-compiler-options "-I C:\Toolbus\lib_includes --print-errors"

If the path you want to specify contains spaces, use a pair of escaped double quotes, for example:

--add-compiler-options "-I \"\"C:\Toolbus\library includes\"\" --print-errors"

You must add a space after the end of the last set of escaped double quotes, for example, before the --print-errors option. The space before the first instance of escaped double quotes is included for consistency.
--add-linker-options "<option_1> [<option_2>...]" -L pass additional options to linker. To pass multiple linker options, separate them by spaces, and surround the entire string in quotation marks. Acceptable values are Linker options for kwbuildproject.
--buildspec-variable <variable_name>= <variable_value> -V allows the use of a build specification template. When this option is used, and a build specification template (*.tpl) is supplied as input to kwbuildproject instead of a standard build specification, kwbuildproject will substitute all occurrences of a given variable in a build specification template with the specified variable value. See Providing a build specification template for your developers.
--classic   forces Klocwork to use the previous generation (pre-Klocwork 2018) analysis engine.
--color -c enable colored console output
--dist-host <host_name>   specify the Distributed Analysis Server host (default: localhost)
--dist-port <int>   set Distributed Analysis Server port (default: 3440)
--encoding -C

encoding of the source files used in the project. Set this to --encoding UTF-8 if your source files contain multibyte characters (for example, Japanese), unless the files start with a byte order mark (BOM) character. Use the --list option of kwconv to find the list of acceptable values.

Notes:

  • If your source files start with a BOM character, you do not need to specify encoding. The BOM character signals that a text stream is already encoded in, or has been converted to, UTF-8.
  • If you set encoding only at build time and not at the project level, source files containing multibyte characters will not display properly in Klocwork's Source Viewer. Setting the encoding with kwbuildproject is useful when the servers are not running. If the servers are running, set source encoding at the project level with the --encoding option of kwadmin create-project or with kwadmin set-project-property, using the source_encoding property.
  • If encoding is not set at build time, the encoding set at the project level is used.
  • If encoding is not set at the project level, or if it is set but a project is not specified with the --url option of kwbuildproject, the default system encoding is used.
  • If encoding is set at both the project level and with kwbuildproject, the kwbuildproject option takes precedence.
--errors-config -e

Specify the checker configuration (.pconf) file to override any checker settings specified in the server project. Same functionality as the --lef-config option.
--exclude-issues -x

specify an external configuration file to filter specific issue types or all issue types for a specific constraint. You must specify the direct name of the macro you want to filter; you cannot use regular expressions to specify macro names.

For more information, see Filtering out issues.
--force -f run the analysis even if the tables directory specified with --tables-directory contains data files from the previous analysis run (same code base only). If the analysis is run for different code bases using the same tables, delete the tables before you run the analysis.
--force-32bit   forces the analysis engine to 32-bit. If you are using old path checkers from pre-2020.3, you have to use this option for the checkers to work
--force-clr   forces the analysis engine to analyze C++/CLI source files containing Managed C++ code. Note that using this option will result in parse errors for Managed C++ code constructs.
--help   display this help
--incremental -I

analyze only files changed since the last analysis, as well as any files with dependencies on the changed files. The prerequisite is a previous complete analysis of the full project. You must retain the output tables directory after the analysis run.

Note that you can also use --incremental to resume an interrupted build. This option handles situations in which source files have changed since the analysis stopped.
--java-kb <file> -K use Java knowledge base file
--jobs-num <int> | auto -j specify the maximum number of parallel compilation and issue detection processes to run. Specify one of:
  • an integer from 1 to 255
  • auto to set automatic mode. In this mode, the number of compilation jobs will equal the number of available processor cores plus 1. The automatic mode is not supported for distributed analysis. Note that -j auto is the default setting for kwbuildproject.
If you are running a parallel C/C++ or Java analysis on one machine, Klocwork recommends you set this value to the number of available processor cores on the build machine + 1. For example, if you have a dual-core machine, set this value to 3. Above this number, you will likely see a performance degradation. If you are distributing your C/C++ analysis load on multiple machines, Klocwork recommends that you set this value at the number of agents you are running plus 1 (for example, if you are running three agents, specify --jobs-num 4). For more information, see Running a distributed Klocwork C/C++ analysis.

Important: Make sure there is enough memory so that no swapping occurs. Reduce the number of jobs if required.
--lef-config   specify logic errors finder configuration in <xml file>. Same functionality as the --errors-config option.
--license-host <host_name> -H

set License Server host (default: localhost).
--license-port <port_number> -P set License Server port (default: 27000). See Tip for --license-host option.
--no-color   do not use colored output
--no-lef -n do not run the Klocwork issue detection stage
--project -S specifies the Klocwork Server project name. You can use this parameter to specify a project you want to download configuration files (such as pconf, metrics_default.mconf) from and apply them during the build.
--qac-project   Specify Helix QAC project location
--qac-install-dir   Specify Helix QAC installation directory
--quiet -q Suppress console messages. Command line parsing errors will not be suppressed.
--remote   run the engine remotely through Distributed Analysis Server
--replace-path <original_path>=<new_path>   replace a source path prefix. Possible to use multiple instances of this option in the same command line. Example: --replace-path /usr/include=include. See Replacing the path to your source files.
--short-log  

Optimize and reduce the size of the build log by reporting fewer details.

Important: This option should only be used after the Klocwork build is stable as details necessary for troubleshooting will be suppressed in this mode.
--strict  

For use when complying with Functional Safety Standards

When --strict is specified, extra warning information will be printed to the parse_errors.log and build_integration.log files. Also, when kwbuildproject skips one or more functions for analysis, additional information will be printed to the function_information.log file. For more information, see C/C++ Path Analysis errors. For further compliance instruction, see the Functional Safety Manual for Klocwork.
--tables-directory <dir> -o

specifies the location where you want to store the project's tables. Mandatory option. You cannot reuse a tables directory from a previous build unless you also specify one of:

  • --force
  • --incremental

You must have read and write permissions on this directory.

--url http://<klocwork_server_host>:<klocwork_server_port>/<server_project>   URL for the project. The arguments identify where the project and the Klocwork Server are located. Use https:// if a secure Klocwork Server connection has been configured. This option synchronizes the configuration, such as checkers, metric and knowledge base settings, located on the server with the specified project.
--use-fbkb <file> -k use the specified knowledge base file for C/C++ projects. You can use this option multiple times in one command line.
--use-prev-fbkb <file> -Q

use the specified knowledge base file as a lower-priority file during a knowledge base update. Records from this file will be added to the new file only if more recent comparable records do not exist. Use this option when you have an automatically generated knowledge base file for a previous version of your source code. This allows you to speed up the issue detection process. However, results will not be as accurate.

You can specify multiple instances of this option on one command line.
--verbose -v print verbose information about program execution, which can help to troubleshoot errors
--version   display version information

Exit codes for C# analysis

When you run the kwbuildproject command, the system generates an exit code. The following table lists the conditions that cause each exit code.

Condition Exit code Result
Success 0 Success.
License check fails 1 Tool fails to start.
Crash 1 Tool crashes.
Command line KAST fails 1 KAST pattern compilation fails.
Issues dumping fails 1 Tables directory is not completely created.
KB dumping fails 1 Tables directory is not completely created.
Metrics dumping fails 1 Tables directory is not completely created.
RDT dumping fails 1 Tables directory is not completely created.
DLL loading fails 2 External referenced assembly is not loaded, but analysis can be performed (accuracy degradation).
No configs found 2 Configurations (default configuration file or modification configuration file .pconf) are not loaded, but analysis can be performed.
No KB found 2 Some KB files are not loaded, but analysis can be performed (accuracy degradation).
Parse error 0 Some source files are not parsed (accuracy degradation).