Kwbazel

The kwbazel build integration command allows users to analyze projects built with the Bazel build system. kwbazel is an executable shell script that runs the Bazel build and generates trace and build specification files (kwinject.trace and kwinject.out).

Kwbazel supports two methods for generating trace and build specification files: the default aquery-based method and an experimental aspect-based method enabled with --aspect_build.

When using the experimental aspect-based build method, kwbazel performs incremental analysis by default to reduce build time. Use -w (or --overwrite) to overwrite any existing output files when you want to regenerate them.

Prerequisites

To use kwbazel, install Bazel and the Klocwork command line tools.
Ensure that source compilation with Bazel works fine by executing bazel build <target>.
Run kwbazel from a Bazel workspace directory (directory where ROOT workspace file is present).
To use the experimental --aspect_build option, use Bazel 6 or later and add a local Bazel repository declaration for p4sa_bazel_tools in your WORKSPACE file so Bazel can access the Klocwork aspect files.
```
local_repository(
    name = "p4sa_bazel_tools",
    path = "<Klocwork_install>/config/kwbazel",
)
```
For Bazel projects that delegate compilation to make, CMake, or gmake through rules_foreign_cc, use Bazel 7.1 or later.

Limitations

Kwbazel is only compatible with Linux and Windows operating systems.
Kwbazel supports building C/C++ and Java using the default mnemonics in both Linux and Windows, and C# code in Linux. Support for other programming languages is not available.
The experimental --aspect_build option currently supports C/C++ aspect-based build specification generation only. If you include other languages, kwbazel ignores them for aspect-based processing.
Build specification generation for Bazel projects that delegate compilation to make, CMake, or gmake through rules_foreign_cc requires the --aspect_build option and Bazel 7.1 or later. The default aquery-based method does not support these projects.
Custom mnemonics are supported via explicit options in Kwbazel.
Kwbazel does not monitor commands provided through shell rules. For such scenarios, consider using Kwinject for your build integration.
Kwbazel should not be used with Android Bazel builds (Kleaf). For Android Bazel builds, use Kwandroid with the --bazel option instead.
On Windows, use Bazel from a supported native environment. Do not use Git Bash, MSYS, Cygwin, or similar Bash variants for Bazel workflows.

Usage

kwbazel --bazel_version <version> --target <bazel_target> --klocwork_path <path_directory> [--arguments <bazel_arguments>] [--lang <language>] [--skip_build] [--aspect_build [<aspect_targets>] [--output_groups <groups>]]

where

<version> specifies the version of Bazel. The string bazel is also accepted
<bazel_target> specifies the build target
<path_directory> specifies the Klocwork output directory
Optional: <bazel_arguments> specifies the arguments used to run the build
Optional: <language> specifies the language option to separate the build for C/C++, C#, and Java
Optional: <aspect_targets> specifies one or more additional Bazel aspect targets to run with the default Klocwork aspect
Optional: <groups> specifies the output groups for any custom aspects that you run
Optional: --skip_build skips the implicit bazel build step

Options

Name (and short name)	Description
--bazel_version (-b) <version>	specifies the version of Bazel. If a single Bazel version is installed, use the string `bazel`. If multiple versions are installed, specify the version. Example: `--bazel_version bazel-6.4.0` You can check your Bazel version in /usr/bin or /usr/local/bin
--klocwork_path (-o) <path_directory>	specifies Klocwork output directory. kwinject.trace and kwinject.out will be created inside this directory
--target (-t) <bazel_target>	specifies the build target. Example: `-t //:hello_bazel` For multiple targets, run `-t "//:hello_bazel hello_klocwork"`

Name (and short name)

Description

--bazel_version (-b) <version>

specifies the version of Bazel. If a single Bazel version is installed, use the string bazel. If multiple versions are installed, specify the version. Example: --bazel_version bazel-6.4.0

You can check your Bazel version in /usr/bin or /usr/local/bin

--klocwork_path (-o) <path_directory>

specifies Klocwork output directory. kwinject.trace and kwinject.out will be created inside this directory

--target (-t) <bazel_target>

specifies the build target. Example: -t //:hello_bazel

For multiple targets, run -t "//:hello_bazel hello_klocwork"

Optional arguments

Name (and short name)	Description
--arguments (-a) <bazel_argument>	specifies Bazel arguments. Example: `--arguments "--spawn_strategy=linux-sandbox --sandbox_debug"`
--custom_mnemonics <string>	specifies use of custom mnemonics created by the user. Example: `--custom_mnemonics mnemonic1 mnemonic2 mnemonic3`
--overwrite (-w)	overwrite existing output files when rerunning kwbazel in aspect-based mode. This is useful when you want to regenerate the Klocwork trace and build specification without preserving the previous results.
--lang (-l) <language>	specifies the language option to separate the build for C/C++ (`cxx`), C# (`csharp`), and Java (`java`). Default is `cxx,csharp,java`
--aspect_build [<aspect_targets>]	enables experimental aspect-based build specification generation and disables the default aquery-based generation for that run. Requires Bazel 6 or later. If no additional aspect target is provided, kwbazel runs the default Klocwork aspect. If additional aspect targets are provided, kwbazel runs the default Klocwork aspect plus the custom aspects that you specify. Also use `--aspect_build` for Bazel projects that delegate compilation to make, CMake, or gmake through `rules_foreign_cc` (requires Bazel 7.1 or later).
--output_groups <groups>	specifies the output groups for any custom aspects run with `--aspect_build`. Provide a comma-separated list of output group names. Use only when passing additional aspect targets to `--aspect_build`.
--skip_build	skips the implicit `bazel build` step. Use when you have already completed the Bazel build before running kwbazel, such as in a CI/CD pipeline where kwbazel runs as a follow-up job to an existing build job.
--remote_executor <url>	specifies the remote executor address. Use to dispatch Bazel build actions to a remote executor. Example: `grpc://remote-executor.example.com:8980`
--remote_cache <url>	specifies the remote cache URL. Use to read from or write to a remote build cache. Example: `grpc://remote-cache.example.com:8990`
--debug	prints all executed commands directly to the terminal. Use for troubleshooting and understanding the build process.
--show_progress	displays progress information during build specification generation for improved visibility into long-running operations.

When you enable --aspect_build, kwbazel keeps the existing build specification generation workflow and replaces the aquery step with an aspect-based step for that run only.

Use --remote_executor to run Bazel build actions remotely, and use --remote_cache to reuse results from previous Bazel builds. Kwbazel extracts build specification data during the local analysis phase, even when Bazel build actions run remotely.

Examples:

kwbazel -b bazel -o klocwork -t //... --aspect_build

kwbazel -b bazel -o klocwork -t //... --aspect_build //:my_aspect.bzl%my_aspect --output_groups my_aspect_output

kwbazel -b bazel -o klocwork -t //... --aspect_build //:my_aspect.bzl%my_aspect,//:my_other_aspect.bzl%my_other_aspect --output_groups my_aspect_output,my_other_aspect_output

kwbazel -b bazel -o klocwork -t //... --skip_build

Optional kwinject arguments

Name (and short name)	Description
--config (-c) <file>	read filter configuration from <file>. The default is <Klocwork_install>/config/kwfilter.conf. Allows you to use a "private" copy of kwfilter.conf and the compiler configuration files, so that the originals do not need to be modified.
-f <variable_file>	read variables from a specified file
--ignore-files (-I)<pattern>[,<pattern>...]	ignore source files that match one of the specified patterns. <pattern> may contain the * and ? wildcards. For example: --ignore-files conftest.* specifies that temporary files created by the configure script will be ignored.
--no-config	do not read filter configuration from compiler mapping file, kwfilter.conf
--no-resolve	do not resolve symbolic links. When the --no-resolve option is specified, it does not resolve paths in compiler options.
--prog (-P) <prog>[=<filter>][,<prog>[=<filter>]...]	the program or programs kwinject should use to intercept programs, if you want to use something other than the compilers searched for by default. Specify the comma-separated list of programs to intercept, along with the appropriate filter to use. The default list of known programs and their filters is taken from the compiler mapping file, kwfilter.conf. The filter bindings defined through this option override any bindings read from a compiler filter file.
--variable (-V) <variable>=<string>	replace every occurrence of <string> in the output file with a reference to <variable> instead.