Kwciagent

kwciagent is a continuous integration (CI) analysis tool for C/C++, C#, and Java developers, similar to kwcheck. Whereas kwcheck is used on developer's desktops, kwciagent can be used on CI systems to analyze changed code.

While connected to a base project or any of its streams, performing a local analysis syncs all the defects in the project's base project and all its streams. Also, citing defects locally applies to the base project and all its streams.

General usage

Always place the subcommand directly after the kwciagent command in your command line:

kwciagent <subcommand> [<options>]

You can use an arguments file with kwciagent subcommands. 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. The usage is:

kwciagent <subcommand> @<arguments-file> 

kwciagent add-replace-path

Adds system path replacement configurations. Use to replace or shorten the directory structure for your source files.

Usage

kwciagent add-replace-path <path_1>=<path_2>

Example

kwciagent add-replace-path c:\projects=/space/project

kwciagent clean

Clears the local defect matching cache. Use for a more accurate one-to-one matching between server and client tools.

Usage

kwciagent clean

kwciagent create

Creates local project and project-settings directories for a CI project; the newly created project does not contain data until it is analyzed or synchronized with the server project.

Usage

kwciagent create --url http://<klocwork_server_host>:<klocwork_server_port>/<project> [-pd <local_project_dir>] [-sd <local_settings_dir>]

Example

kwciagent create --url http://acme:8074/bigproject

Details

By default, the local-project and Klocwork project-settings directories are created in your working directory and are named .kwlp and .kwps. You can specify your own names and locations for these directories with the -pd and -sd options. However, using the default names and locations allows you to limit the scope of your analysis or filter with kwciagentlist to your current subdirectory instead of the whole project.

  • .kwlp stores temporary working files and the build specification file.
  • .kwps stores the build specification template (if applicable) and configuration files

To delete your analysis results and settings, delete the .kwlp directory and run kwciagent create again.

Options

Name Short name Description
--build-spec <file>.out -b imports the build specification into the local project
--license-host <host_name>   specify the License Server host name; ignored if --url is used
--license-port <port_number>   specify the License Server port number; ignored if --url is used
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree
--settings-dir <dir> -sd specify name and location of the project settings directory. Default: .kwps in your working directory
--url http://<klocwork_server_host>:<klocwork_server_port>/<server_project>   URL for the project. The arguments identify the project and the Klocwork Server where it's located. Use https:// if a secure Klocwork Server connection has been configured.

kwciagent disable

Disables the specified checkers. Requires permission to change local configuration. When you enable or disable checkers, a file called a user profile (.pconf.xml) is created to store the non-default settings. You can export this file with kwciagent export to share with other users. You can also use the Configuration Editor to disable checkers.

Usage

kwciagent disable <issue_code_1> [<issue_code_2>] [...]

Example

kwciagent disable cl.mlk cwarn.signedbit

Details

Separate issue codes with spaces. Issue codes are not case sensitive. Note that disabling the Header Analysis checkers has no effect for kwciagent.

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent discard

Removes the specified configuration file from your project. Requires permission to change local configuration.

Usage

kwciagent discard [options] <config_file>

Example

kwciagent discard user_metrics.mconf

Details

The types of configuration files you can remove are:

  • build specification (buildspec.txt)
  • build specification template (.tpl)
  • user profile (.pconf.xml)
  • knowledge bases (.kb for C/C++ or .jkb for Java)
  • metric thresholds (.mconf)
  • macro override file (kw_override.h)
When you remove a user profile, Klocwork reverts to the default checker configuration.

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent enable

Enables specified checkers. Requires permission to change local configuration. When you enable or disable checkers, a file called a user profile (.pconf.xml) is created to store the non-default settings. You can export this file with kwciagent export to share with other users. You can also use the Configuration Editor to enable checkers.

Usage

kwciagent enable [options] <issue_code_1> [issue_code_2][...]

Example

kwciagent enable cl.assign.void cwarn.signedbit

Details

Separate issue codes with spaces. Issue codes are not case sensitive. Note that disabling the Header Analysis checkers has no effect for kwciagent.

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent export

Exports the specified configuration file from your project to share with other users. Requires permission to change local configuration. With connected desktop, all configuration settings are pushed to the desktop from the server. If you have permission to change local configuration, you can export local settings so that other users can import them. Local settings take precedence.

Usage

kwciagent export [options] <config_file>

Example

kwciagent export user_metrics.mconf -o /shared/jlee_metrics.mconf

Details

You can export the following configuration files:

  • user profile (.pconf)
  • knowledge bases (.kb for C/C++, .jkb for Java)
  • metric thresholds (.mconf)
  • macro override file (kw_override.h)

Options

Name Short name Description
-o <file>   specify the output file location and name (default: current directory and current file name)
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent import

Imports the specified configuration file into your local project. Requires permission to change local configuration. With connected desktop, all configuration settings are pushed to the desktop from the server. If you have permission to change local configuration, you can export local settings so that other users can import them. Local settings take precedence.

Usage

kwciagent import [options] <file>

Example

kwciagent import /shared/jlee_metrics.mconf

Details

With the exception of knowledge bases, a local project can only contain one of each of the following file types:

File type Default extension
build specification .out
exact match file

.emp

Ensure that the .emp file contains a list of absolute paths.
knowledge base .kb for C/C++, .jkb for Java
macro override file .h
metric thresholds .mconf
user profile .pconf

To import a file with a non-default extension, specify the --type option.

Filtering out issues

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

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree
--type <config_file_type> -t specify file type for files with non-default extensions; allowed arguments are:
  • buildspec or b
  • kb
  • jkb
  • override-file
  • mconf
  • pconf

kwciagent info

Displays local project settings.

Usage

kwciagent info [options] 

Example

kwciagent info -pd new_project

Details

Settings displayed:

  • status.permission: The statuses you are allowed to use when changing issue status. *\:* means that you can change a reported issue to or from any status.
  • klocwork.host: Connected projects only
  • klocwork.project: Connected projects only
  • license.host: For all projects, connected or not
  • license.port: For all projects, connected or not
  • useconf.permission: Whether you have permission to change local configuration, such as enabling or disabling checkers

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent list

Filters the issue list by issue number, issue code, status, severity and file.

Usage

kwciagent list [options] [<file_1>] [<file_2>] [...] 

Example

kwciagent list --id 4-9,16-22,77 --issue abr,abv.stack foo.c foo2.cpp

Details

Files must be space delimited, whereas filtering options, such as status, must be comma delimited. Express ranges for severity or issue ID with a hyphen.

By default, kwciagent displays issues:

Running kwciagent list from the directory that contains the .kwlp will list detected issues for the whole project. If your local project directory has the default name (.kwlp) and is located in the source tree, you can filter issues in the current subdirectory instead of the whole project. Simply run kwciagent list from the desired subdirectory. Issues in header files outside the given directory are not listed.

If you run kwciagent list on a project that includes streams, you will see some additional flags in your output, as follows:

JSON:

"inConnected": true/false,

"inOtherStreams": true/false,

XML:

<inOtherStreams>true/false</inOtherStreams>

<inConnected>true/false</inConnected>

inConnected is true if the issue exists directly on the connected stream or project and is not in the "Fixed" state. inOtherStreams is true if the issue exists in any stream in the family tree except for the connected stream. Both flags can be true (for example, the issue exists in both a connected stream and in an additional stream).

Filter options

Name Short name Description
--apply-replace-path -p list defects using their replace-path paths
--id <local_issue_ID>   lists issues by issue ID
--id-system <system_ID>   list issues by system ID
--issue <issue_code_1>[,<issue_code_2>...]   list specified issue codes. Issue codes are case insensitive. For a complete list of the issue codes, see C and C++ checker reference or Java checker reference. You can also run kwdtconfeditor to view a list of checkers and their default settings.
--local -l show local issues. The default setting is to show:
  • only issues detected in your local project
  • no issues detected in the integration build analysis
--no-local -L don't show local issues. Use this option, along with the --system option, to list only system issues.
--no-system -Y don't show system issues. This is the default setting (along with --local).
--severity <severity_number>   list issues of the specified severities. Severity is a value between 1 and 4, with one representing the most serious issues and 4 representing the least serious. Separate severities with spaces or use a hyphen for a range:--severity 1,3-4
--status <status_name>|all -s list detected issues of the specified statuses. Use double quotation marks to enclose statuses containing spaces: "fix in next release". Use kwciagent list-statuses for a list of statuses.
--system -y show system issues. kwciagent list --system shows you system issues in addition to the local issues you see by default. kwciagent list --system --no-local shows only system issues.
--taxonomy <taxonomy_name>  

list detected issues by taxonomy name. For example:

kwciagent list --taxonomy MISRA C

This shows you only those issues detected by checkers in the MISRA C taxonomy

Other options

Name Short name Description
-F <format>   controls the format of the issue list; possible formats are:
  • detailed - display traceback on all detected issues in formatted text output
  • json - display traceback on all detected issues in JSON format
  • scriptable - output semi-colon delimited format
  • short - output without issue numbers and absolute path names
  • xml - output in XML format
For more information, see Kwcheck output reference.
--license-host <host_name>   specify the License Server host name
--license-port <port_number>   specify the License Server port number
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree
--report <output_file>[,<output_file_2>...]   export the list of reported issues (that match specified filter options, if any) to the specified file(s). Only .txt files are supported. Use -F to specify the level of detail you want in your output. Example:kwciagent list -F detailed --report /space/jlee/myreport.txt

kwciagent list-conf

Lists configuration files used by your local project.

Usage

kwciagent list-conf

Example

kwciagent list-conf -pd my_project

Description

Supported configuration files:

  • build specification (buildspec.txt)
  • build specification template (.tpl)
  • user profile (.pconf.xml)
  • knowledge bases (.kb for C/C++ or .jkb for Java)
  • metric thresholds (.mconf)
  • macro override file (kw_override.h)

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent list-projects

Lists projects on the Klocwork Server.

Usage

kwciagent list-projects

Example

kwciagent list-projects --url http://server1.acme.com:8080

Options

Name Description
--url http(s)://<klocwork_server_host>:<klocwork_server_port>/ URL for the Klocwork Server. Use https:// if a secure Klocwork Server connection has been configured.

kwciagent list-replace-path

List replace paths set with add-replace-path.

Usage

kwciagent list-replace-path

kwciagent list-statuses

Lists possible statuses for detected issues.

Usage

kwciagent list-statuses 

kwciagent list-vars

Lists variables in the build specification template that have been set using kwciagent set-var.

Usage

kwciagent list-vars [options]

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent remove-replace-path

Removes replace path settings.

Usage

kwciagent remove-replace-path <path>

Example

kwciagent remove-replace-path c:\projects

kwciagent remove-var

Removes variables that have been set for a build specification template.

Usage

kwciagent remove-var [options] <var1> [var2] [...]

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent run

Runs the analysis on a project, subdirectory or file(s).

Usage

kwciagent run [options]

Example

kwciagent run --issue ABR,MLK.MUST --severity 1-3 -F detailed --report project.txt foo.c foo2.cpp

Details

Files must be space delimited, whereas filtering options, such as status, must be comma delimited. Express ranges for severity or issue ID with a hyphen. Running kwciagent run from the directory that contains .kwlp will analyze all source files for the project. For C/C++ projects, if your local project directory has the default name (.kwlp) and is located in the source tree, you can limit the context of the analysis to the current subdirectory. Files from that subdirectory (and from any child directory) will be analyzed. For Java projects, only incremental analysis is supported. Klocwork analyzing individual files is not recommended because the limited scope of the analysis can cause inaccurate results.

Options

Name Short name Description
--build-spec <file>.out -b

imports the build specification into the local project.

--ci-build <build name> -c uploads new local CI-defects to the server with specified CI build name
--classic   forces Klocwork to use the previous generation (pre-Klocwork 2018) analysis engine. The previous analysis engine only provides partial support for C++11 and C++14. For more information, see Specifying the C/C++ analysis engine mode.
-F <format>   controls the format of the issue list; possible formats are:
  • detailed - display traceback on all detected issues
  • json - display traceback on all detected issues in JSON format
  • scriptable - output semi-colon delimited format
  • short - output without issue numbers and absolute path names
  • xml - output in XML format
For more information, see kwciagent output reference.
--issue <issue_code_1>[,<issue_code_2>...]   list specified issue codes. Issue codes are case insensitive. For a complete list of the issue codes, see C and C++ checker reference or Java checker reference. You can also run kwdtconfeditor to view a list of checkers and their default settings.
--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.

    For a parallel analysis on one machine, Klocwork recommends you specify the number of processor cores plus 1. Above this number, performance will be degraded.

--license-host <host_name>  

specify the License Server host name

The specified host name is used and stored. If the host name changes, use kwciagent set.
--license-port <port_number>   specify the License Server port number.
The specified port number is used and stored. If the port number changes, use kwciagent set.
--local -l show local issues. The default setting is to show:
  • only issues detected in your local project
  • no issues detected in the integration build analysis
--no-local -L don't show local issues. Use this option, along with the --system option, to list only system issues.
--no-server-bjkbs   disable retrieving bjkbs from the server. Do not use if you cannot analyze the whole code base locally.
--no-system -Y don't show system issues. This is the default setting (along with --local).
--modern  

forces Klocwork to use the modern analysis engine, with advanced capabilities for analyzing modern C++ code. This engine provides full support of the language specification up to C++17, and partial support for C++20 and C++23. Note that this engine can significantly increase the number of new defects found. For more information, see Specifying the C/C++ analysis engine mode.

--overrides-file   specify the overrides file to use for propagation
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree
--rebuild -r overrides incremental analysis to run a complete re-analysis on the project
--report <output-file>   specify the issue output file
--severity <severity_number>   list issues of the specified severities. Severity is a value between 1 and 4, with one representing the most serious issues and 4 representing the least serious. Separate severities with spaces or use a hyphen for a range:--severity 1,3-4
--short-log  

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

This option should only be used after the Klocwork build is stable as details necessary for troubleshooting will be suppressed in this mode.
--status <status> -s list detected issues of the specified statuses. Use double quotation marks to enclose statuses containing spaces: "fix in next release". Use kwciagent list-statuses for a list of statuses.
--sync-after-load -n Optional. Synchronize server defects to project directory after CI build load. Use if you are preserving project directories between analysis runs.
--system -y show system issues. kwciagent run --system shows you system issues in addition to the local issues you see by default. kwciagent run --system --no-local shows only system issues.
--tags   specify a comma separated list of build tags
--taxonomy <taxonomy_name>  

list detected issues by taxonomy name. For example:

kwciagent list --taxonomy MISRA C

This shows you only those issues detected by checkers in the MISRA C taxonomy

kwciagent set

Changes settings for your local project.

Usage

kwciagent set [options] <property_name>=<property_value> [...]

Example

kwciagent set klocwork.host=acmedev klocwork.port=1108

Description

Possible property/value pairs:

Property name Property value Description
engine.type= <engine_type>

use 'classic' to force Klocwork to use the previous generation (pre-Klocwork 2018) analysis engine.

use 'modern' to force Klocwork to use the modern analysis engine, with advanced capabilities for analyzing modern C++ code.

klocwork.host= <klocwork_server_host> Default: localhost
klocwork.port= <klocwork_server_port> Default: 8080
klocwork.project= <server_project_name> Allows you to:
  • change a standalone desktop to a connected desktop
  • connect to a different server project
  • change a connected desktop to a standalone desktop
klocwork.ssl= 0 or false; 1 or true If a secure Klocwork Server connection has been configured, set this property to 1 or true.
license.host= <license_server_host> Default: localhost
license.port= <license_server_port> Default: 27000
ignore_defect_threshold= true of false

To ignore the configured defect threshold limit for a project and force a build to load even if it surpasses it, set this property to true.

show_streams_as_system= true or false To show stream defects as system defects, set this property to true.
source.encoding= <encoding> encoding of the source files used in the project. The default is your system encoding. Use the --list option of kwconv to find the list of acceptable values. For more information, see the --encoding option of kwbuildproject.

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent set enable_exact_file_match

Enables exact file matching.

Usage

kwciagent set enable_exact_file_match <true/false>

Example

kwciagent set enable_exact_file_match true

kwciagent set-status

Changes the issue status and adds comments.

Usage

					kwciagent set-status [options] <issue_ID> [<issue_ID> <issue_ID>-<issue_ID> [...]
				

Example

					kwciagent set-status 22 7 30-32 --status fix -c "top priority"
				

Description

Separate multiple issue IDs by spaces or use a hyphen for a range.

Options

Name Short name Description
--comment <text> -c add comment
--license-host <host>   specify the License Server host name
--license-port <port>   specify the License Server port number
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree
--status <status> -s specify the status to assign. Use double quotation marks to enclose statuses containing spaces: "fix in next release". Use kwciagent list-statuses to list all statuses.

kwciagent set-var

Maps variables in a build specification template to local paths in your local project. You only need to map variables using kwciagent set-var when you see an error message indicating that one or more variables need to be defined.

Usage

kwciagent set-var [options] <var1>=<pathname> [<var2>=<pathname>] [...]

Example

kwciagent set-var SCROOT=/builds/nightly/foosystem

Options

Name Short name Description
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree

kwciagent sync

Sends your results and status changes to the server project and pulls server project analysis results, status changes, and configuration settings into your local project.

Usage

kwciagent sync

Example

kwciagent sync foo.c

Description

Synchronization occurs automatically between connected desktops and the project on the Klocwork Server. However, kwciagent sync allows you to synchronize manually.

Options

Name Short name Description
--build-spec -b imports the build specification into the local project (not for kwshell or build specification template users)
--ci-build -c uploads new local CI-defects to the server with specified CI build name
--overrides-file   specify the overrides file to use for propagation
--project-dir <dir> -pd specify the name if different from the default name (.kwlp), and/or location if it's outside the source tree
--tags   specify a comma separated list of build tags