The kwbuildproject command runs the integration build analysis and performs the following stages:
- issue detection
- report generation
kwbuildproject is installed with the Klocwork Server package.
- 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.
kwbuildproject --tables-directory <dir> --url http://<klocwork_server_host>:<klocwork_server_port>/<server_project> [<other_options>] <build_specification_1> [<build_specification_2>...]
- <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:
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.)
kwbuildproject --tables-directory C:\Klocwork\My_tables --url http://myserver:8080/myproject C:\Klocwork\kwinject.out
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
|--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.
If the path you want to specify contains spaces, use a pair of escaped double quotes, for example:
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 of the source files used in the project. Set this to --encoding UTF-8 if your source files contain multibyte characters (for example, Japanese). Use the --list option of kwconv to find the list of acceptable values.
|--errors-config||-e||Specify logic errors finder configuration in <xml file>. Same functionality as the --lef-config option.|
|--exclude-defects||-x||specify an external configuration file to filter specific defect types or all defect types for a specific constraint.
Caution: This is an unsupported option and we do not recommend using it.
|--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|
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:
Note: 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.|
set License Server host (default: localhost).
Tip: You can also set this value in the $HOME/.flexlmrc file on UNIX, or the KLOCWORK_LICENSE_FILE environment variable in the Windows registry. This registry entry is found at HKEY_LOCAL_MACHINE > SOFTWARE > FNPlm > License Manager > KLOCWORK_LICENSE_FILE. This will ensure that you do not need to enter these options every time you use kwbuildproject.
|--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:
|--short-log||Optimize and reduce the size of the build log by reporting fewer details.
Note that this option should only be used after the Klocwork build is stable as details necessary for troubleshooting will be suppressed in this mode.
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.
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:
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 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.
|License check fails||1||Tool fails to start.|
|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).|