Kwcheck
kwcheck is a desktop analysis tool for C/C++, C#, and Java developers using IDEs and text editors that aren't supported by Klocwork in the form of an IDE plug-in. For how-to information, see Getting started with kwcheck for C/C++ and Getting started with kwcheck for Java.
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 kwcheck command in your command line:
kwcheck <subcommand> [<options>]
You can use an arguments file with kwcheck 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:
kwcheck <subcommand> @<arguments-file>
kwcheck add-replace-path
Adds system path replacement configurations. Use to replace or shorten the directory structure for your source files.
Usage
kwcheck add-replace-path <path_1>=<path_2>
Example
kwcheck add-replace-path c:\projects=/space/project
kwcheck clean
Clears the local defect matching cache. Use for a more accurate one-to-one matching between server and client tools.
Usage
kwcheck clean
kwcheck create
Creates local project and project-settings directories for a desktop project; the newly created project does not contain data until it is analyzed or synchronized with the server project.
Usage: Connected desktop
kwcheck create --url http://<klocwork_server_host>:<klocwork_server_port>/<project> [-pd <local_project_dir>] [-sd <local_settings_dir>]
Example
kwcheck create --url http://acme:8074/bigproject
Usage: Standalone desktop
kwcheck create [--license-host <host_name>] [--license-port <port_number>] [-pd <local_project_dir>] [-sd <local_settings_dir>]
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 kwcheck list 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 kwcheck create again.
Options
| Name | Short name | Description |
|---|---|---|
| --build-spec <file>.out | -b | imports the build specification into the local project. This option is incompatible with build specification template files and build specification files generated by kwshell. |
| --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 | |
| --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. |
kwcheck 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 kwcheck export to share with other users. You can also use the Configuration Editor to disable checkers.
Usage
kwcheck disable <ISSUE.CODE1> <ISSUE.CODE2> [...]
Example
kwcheck disable CL.MLK CWARN.SIGNEDBIT
Details
Separate issue codes with spaces. Issue codes must use upper case. Note that disabling the Header Analysis checkers has no effect for kwcheck or Klocwork Desktop.
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 |
kwcheck discard
Removes the specified configuration file from your project. Requires permission to change local configuration.
Usage
kwcheck discard [options] <config_file>
Example
kwcheck 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 |
kwcheck 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 kwcheck export to share with other users. You can also use the Configuration Editor to enable checkers.
Usage
kwcheck enable [options] <ISSUE.CODE1> <ISSUE.CODE2> [...]
Example
kwcheck enable CL.MLK CWARN.SIGNEDBIT
Details
Separate issue codes with spaces. Issue codes must use upper case.
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 |
kwcheck 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
kwcheck export [options] <config_file>
Example
kwcheck 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 |
kwcheck 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
kwcheck import [options] <file>
Example
kwcheck import /shared/jlee_metrics.mconf
Details
With the exception of knowledge bases, a desktop 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:
|
kwcheck info
Displays local project settings.
Usage
kwcheck info [options]
Example
kwcheck 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 |
kwcheck list
Filters the issue list by issue number, issue code, status, severity and file.
Usage
kwcheck list [options] [<file_1>] [<file_2>] [...]
Example
kwcheck 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, kwcheck displays issues:
- in Analyze and Fix statuses
- of all severities
- in all source files for the project or subdirectory
- of "Local" origin
Running kwcheck 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 kwcheck list from the desired subdirectory. Issues in header files outside the given directory are not listed.
If you run kwcheck 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 kwcheck list-statuses for a list of statuses. |
| --system | -y | show system issues. kwcheck list --system shows you system issues in addition to the local issues you see by default. kwcheck list --system --no-local shows only system issues. |
| --taxonomy <taxonomy_name> |
list detected issues by taxonomy name. For example: kwcheck list --taxonomy "MISRA C 2012 (C99)"This shows you only those issues detected by checkers in the MISRA C 2012 C99 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:kwcheck list -F detailed --report /space/jlee/myreport.txt |
kwcheck list-conf
Lists configuration files used by your local project.
Usage
kwcheck list-conf
Example
kwcheck 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 |
kwcheck list-projects
Lists projects on the Klocwork Server.
Usage
kwcheck list-projects
Example
kwcheck 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. |
kwcheck list-replace-path
List replace paths set with add-replace-path.
Usage
kwcheck list-replace-path
kwcheck list-vars
Lists variables in the build specification template that have been set using kwcheck set-var.
Usage
kwcheck 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 |
kwcheck remove-replace-path
Removes replace path settings.
Usage
kwcheck remove-replace-path <path>
Example
kwcheck remove-replace-path c:\projects
kwcheck remove-var
Removes variables that have been set for a build specification template.
Usage
kwcheck 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 |
kwcheck run
Runs the analysis on a project, subdirectory or file(s).
Usage
kwcheck run [options]
Example
kwcheck 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 kwcheck 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, both incremental analysis and differential analysis are supported.
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.
|
| --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. | |
| --engine-threads-num <num> | -th | specify the maximum number of threads used by each instance of the C/C++/C# path analysis engine process. Default value: 1. A negative value results in automatic thread count assignment. |
| -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 kwcheck 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 kwcheck set |
|
| --local | -l | show local issues. The default setting is to show:
|
| --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. |
|
| --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). |
| --files-overrides | 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 kwcheck list-statuses for a list of statuses. |
| --system | -y | show system issues. kwcheck run --system shows you system issues in addition to the local issues you see by default. kwcheck run --system --no-local shows only system issues. |
| --taxonomy <taxonomy_name> |
list detected issues by taxonomy name. For example: kwcheck list --taxonomy "MISRA C 2012 (C99)"This shows you only those issues detected by checkers in the MISRA C 2012 C99 taxonomy. |
kwcheck set
Changes settings for your local project.
Usage
kwcheck set [options] <property_name>=<property_value> [...]
Example
kwcheck 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 |
| 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 |
kwcheck set enable_exact_file_match
Enables exact file matching.
Usage
kwcheck set enable_exact_file_match <true/false>
Example
kwcheck set enable_exact_file_match true
kwcheck set-status
Changes the issue status and adds comments.
Usage
kwcheck set-status [options] <issue_ID> [<issue_ID> <issue_ID>-<issue_ID> [...]
Example
kwcheck 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 kwcheck list-statuses to list all statuses. |
kwcheck set-var
Maps variables in a build specification template to local paths in your local project. You only need to map variables using kwcheck set-var when you see an error message indicating that one or more variables need to be defined.
Usage
kwcheck set-var [options] <var1>=<pathname> [<var2>=<pathname>] [...]
Example
kwcheck 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 |
kwcheck sync
Sends your results and status changes to the server project and pulls server project analysis results, status changes, and configuration settings into your desktop project.
Usage
kwcheck sync
Example
kwcheck sync foo.c
Description
Synchronization occurs automatically between connected desktops and the project on the Klocwork Server. However, kwcheck 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) |
| --files-overrides | 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 |