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)
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:
|
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:
- in Analyze and Fix statuses
- of all severities
- in all source files for the project or subdirectory
- of "Local" origin
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:
|
| --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 CThis 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:
|
|
| --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-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. Not for kwshell or build specification template users.
|
| --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:
|
|
| --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:
|
| --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:
|
| --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 CThis 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:
|
| 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 |