Configure backward compatibility with earlier analysis tools

Starting in Klocwork 2025.4, you can lock projects to earlier analysis tool versions, which allows you to upgrade to the latest Validate server while maintaining backward compatibility with older projects.

Key concepts of project-level locking

• You can lock projects to a specific version of Klocwork analysis tools (2022.4 and later). This applies to the entire stream family and must be set on the base project.

• If not explicitly locked, projects will use the current version of Validate.

• A unified tool (kwanalysis) can be used as an alternative to kwbuildproject, kwcheck, and kwciagent for backward-compatible analysis.

• You can use the optional analysis tool store (kwtoolstore and kwtoolstoreservice), available on embedded or standalone mode, for hosting versioned tools.

• You can also generate a wrapper script for bootstrap environments (kwanalysis wrapper).

Benefits of locking projects

By locking projects, you can:

• Run builds to specific analysis tool versions

• Take advantage of centralized management of multiple analysis versions

• Upgrade to the latest Klocwork release without breaking legacy workflows

• Take advantage of automatic tool acquisition and version inference to simplify CI and developer setup

• Use a wrapper script to enable onboarding with no pre-installed tools (only Java and the wrapper are required), making it ideal for every environment from developer workstations to build servers, CI pipelines, and fully ephemeral machines. This approach eliminates the need for admin-level installations and allows analysis to be up and running conveniently.

Lock projects to a supported Klocwork version

Projects can be locked to any supported Klocwork version (release 2022.4 or later) using the command kwadmin analysis-tool-version or kwadmin lock-project. Locking applies at the project level, not individual streams.

Option 1: Use kwadmin analysis-tool-version

kwadmin analysis-tool-version --tool-version <version> --tool-location <tool_location> <project_name>

Example:

kwadmin analysis-tool-version --tool-version 23.4 --tool-location /space/klocwork/23.4/buildtools MyProject

Option 2: Use kwadmin lock-project-version

kwadmin lock-project-version <project_name>

Example:

kwadmin lock-project-version MyProject

After locking:

• The version tag (for instance, 25.2) appears next to the project name on Validate

• Unlocked projects show a gray version tag and will default to the latest analysis tools

For more details on analysis-tool-version and lock-project-version subcommands, see the Kwadmin documentation.

Verify if a project is locked to an earlier version of Klocwork

Here are some ways to verify if a project is locked to an earlier analysis tool version:

• Validate Portal: Check the version tag next to the project name

• Command line:

  • kwadmin list-projects -f

  • kwcheck list-projects -f or kwciagent list-projects -f

• Klocwork Web API: Query the project metadata for the version information

Run builds on earlier analysis tools

The executable kwanalysisconsolidates legacy executables (kwbuildproject, kwcheck, kwciagent) under one interface. The following is a mapping for running builds using kwanalysis:

Legacy tool	New equivalent
kwbuildproject <options>	kwanalysis buildproject <options>
kwcheck <options>	kwanalysis check <options>
kwciagent <options>	kwanalysis ciagent <options>

Examples

kwanalysis <subcommand> --tool-version <version> --tool-location <tool_location> <options>
kwanalysis check --tool-version 23.4 --tool-location /space/klocwork/23.4/buildtools MyProject
kwanalysis buildproject --tool-version 23.4 --tool-location /space/klocwork/23.4/buildtools MyProject --tables-directory C:\Klocwork\My_tables
--url http://myserver:8080/myproject C:\Klocwork\kwinject.out

For more information on kwanalysis subcommands and options, see Kwanalysis.

(Optional) Set up and use the analysis tool store

The analysis tool store is an optional distribution point for:

(Optional) Use a wrapper script

You can create a wrapper script that generates portable environment bootstrap files, allowing Java analysis to run without any local pre-installed tools.

When executed, the wrapper script:

• Validates your authentication credentials and checks for required tools

• Downloads missing build tools from the tool store if they're not already present

• Sets key environment variables such as:

  • PATH: Updated to include the latest kwanalysis build tools.

  • KW_PROJECT_NAME: The name of the project being analyzed.

  • KW_BUILDTOOLS_LOCATION: The directory where the latest kwanalysis build tools are located.

  • Default validation URL: Used for connecting to the Validate server during analysis.

For more information, see Create and use an analysis wrapper script.

Migrate your locked projects

When migrating your locked projects to the latest Validate installation, consider these recommendations:

Scenario	Recommendation
Existing scripts using legacy commands	Update the binary name in your scripts: kwbuildproject to kwanalysis buildproject.
Needs multi-version builds across projects	Use a dedicated wrapper script for each project and commit the corresponding properties files to version control.
Air-gapped environments	Pre-seed the $KW_TOOLS_DIR directory with required tools and disable access to any external tool store. For more information, see Use the analysis tool store.
Multi-Validate federation	Configure a standalone tool store and set the validate.urls list to include all Validate instances. For more information, see Use the analysis tool store.
Custom checkers	Enforce kwanalysis sync or kwanalysis --sync-checkers in your pipeline templates to ensure consistency across environments.

End-to-end example

This example demonstrates how to run a complete analysis using the wrapper script, inject build data, perform analysis, and load results into the server.

Set up project locking and wrapper script

These steps are done once per project and are all optional.

1. Lock the project:

   kwadmin analysis-tool-version --tool-version 25.2 --tool-location /opt/klocwork/25.2/buildtools MyProject

2. Generate a wrapper script:

   kwanalysis wrapper --project MyProject

3. Check in the generated wrapper files. These files are described in Create and use an analysis wrapper script.

   • Linux: source kwanalysisw.sh --application-token myAppToken123

   • PowerShell: . .\kwanalysisw.ps1 --application-token myAppToken123

Analyze project

Use this flow for standard analysis runs:

1. Checkout project from source control.

2. Source the wrapper script.

3. Create your build specification:

   kwinject -w -o kwinject.out bash build.sh

4. Run analysis:

   kwanalysis buildproject --project MyProject -f -o kw_tables kwinject.out

   Add --sync-checkers if you need to sync custom checkers during analysis.

5. Load results into Validate:

   kwadmin load MyProject kw_tables
   

Analyze CI project

Use this flow for CI/CD integration:

1. Checkout project from source control.

2. Source the wrapper script.

3. Create your build specification:

   kwinject -w -o kwinject.out bash build.sh

4. Sync custom checkers for CI agent (optional):

   kwanalysis deploy sync --tool-location /opt/klocwork/25.2/buildtools

5. Run CI agent analysis:

   kwanalysis ciagent --project MyProject --ci-build build_456

Troubleshooting

Refer to the following table to resolve issues with project locking and backward compatibility with earlier analysis tools:

Symptom	Possible cause	Resolution
Build/ci-build load rejected	Tool version mismatch (project locked)	Run with correct version, or unlock the project then lock it to the new desired version
Tools not auto-downloading	Misconfigured tool store or tool.store.url missing	Verify admin.conf or toolstore.properties and Validate logs
Wrapper scripts not setting environment variables	Script not executed via sourcing	Use source or dot invocation, not subshell run. See Create and use an analysis wrapper script.
Custom checkers missing	Sync not triggered	Add --sync-checkers or run kwanalysis sync
Permission denied when trying to upload artifact to tool store	User not project root admin	Adjust role or escalate
Wrong cache directory used	$KW_TOOLS_DIR set unintentionally	Echo variable; unset if undesired