Migrate your projects_root directory

We recommend that you make a copy of your projects_root directory and migrate the copy. This way, users can continue to use Klocwork Static Code Analysis, though they should be instructed not to make any changes, such as changing an issue's status.

To reduce the amount of time required for migration, we also strongly recommend that you delete unneeded projects and failed builds before migration, as detailed in the procedure that follows.

If you are moving to a new major release of the software, ensure that you have a compatible license, as each major release requires a new Klocwork license. See Licensing for more information.

If you do not use the default server settings, you will need to specify your custom settings prior to beginning the upgrade. Otherwise, during the installation these settings will revert back to the default settings. If you forget, you can always go in and change the settings for each of your environments after you have completed upgrading.

To avoid losing issues, status changes or comments from the last release in your first Klocwork 2023.3 analysis run, make sure you read Before your first Klocwork integration build analysis.

Tomcat server configuration:Klocwork Static Code Analysis's Tomcat server configuration (<projects_root>/tomcat/conf/server.template) will be backed up and replaced during migration. The backup file will be named server.template.bak or server.template.bak_X (where X is a number). If your server.template had modifications from the Klocwork Static Code Analysis defaults, you can copy them from the backup, ensuring that maxPostSize is set to -1, and re-start the Klocwork Static Code Analysis server.

Supported upgrade paths

Find your current version in the chart below and follow the appropriate upgrade path. If you need to upgrade from earlier versions of the product that aren't listed in the table below, use the import method. See Import your existing projects into a new projects_root for more information.

Perforce is also here to help! If you need to move from an older release, you can contact Static Code Analysis Professional Services to discuss assistance via a services engagement.

Interoperability between releases

To take advantage of the latest improvements in Klocwork, we always recommend you upgrade your Server, Build, and Desktop Analysis plug-ins to the latest version of the product. Klocwork Server and Build Tools are compatible with the Desktop Analysis plug-ins within each major release.

Klocwork also provides the ability to load builds from the previous major version of Klocwork into the current version of Klocwork. For example, this means you can load Klocwork builds from any version of Klocwork 2022 into Klocwork 2023.3 without having to import or migrate data. For more information, see Cross-version support for builds.

Running two versions of the Klocwork Servers

If you will be running two sets of the Klocwork Servers, for example to test the Klocwork 2023.3 Servers while users continue to access your existing servers, you must run them on different projects_root directories (and set the ports appropriately).

For details on starting and stopping the servers, see Starting the Klocwork Servers and Stopping the Klocwork Servers.

To prepare to upgrade:

1. For the projects_root you want to migrate, run the following command:

   kwservice --projects-root <projects_root> check 
   

2. Make note of what servers are running and what ports they are running on. After migration to the new version of Klocwork, the servers will be running on these ports.
3. Stop the servers.
4. To create a restore point, perform a complete backup of any projects_root directories you want to migrate. After you upgrade Klocwork, you cannot undo the upgrade. For information, see Backing up Klocwork data.
5. If you customized any configuration files (such as kwmysql.ini or kwfilter.conf), back up the <server_install>/config directory.
6. Start the servers.

Important: To reduce the time required to migrate your Klocwork data, we strongly recommend that you:

• Delete any projects from the previous version that you do not need to migrate. See kwadmin delete-project.
• Delete any failed project builds from the previous version. You cannot resume a build that failed in a previous release after migrating the project as described in this article. However, you may be able to load the build from tables. See kwadmin delete-build.
7. Stop the servers.
8. (Optional) To create a second restore point, back up the projects_root directories you have prepared for migration.
9. Store the existing Klocwork license in a safe place.
10. To prevent confusion, delete the old Klocwork logs from <projects_root>/logs.

Install the Klocwork 2023.3 Server package. For instructions, see Installing Klocwork.

Important: Using the 2023.1-2023.3 versions of dbvalidate and dbvalidate cleanup with projects-root that have CI builds can result in data loss. To run dbvalidate and dbvalidate cleanup before upgrading from Validate versions 2023.1-2023.3, use the versions included in the 2023.4 Validate installation package.

dbvalidate is a tool that checks the consistency of data in your database. Running this tool is mandatory, so that any errors in your database can be corrected before you migrate or import. Use the version of the dbvalidate tool that matches your installed version of software (that is, the version that matches your projects_root directory).

The Database Server from your old installation must be running to validate the database. The Database Server is listed as a separate service from the Klocwork Server, so ensure that it is running.

Run the following command, for example:

java -jar <server_install>/class/dbvalidate.jar --projects-root <projects_root>

where

• <server_install> is your installation directory
• <projects_root> specifies the location of the old projects root you want to validate

Example

java -jar /local/tools/klocwork/server/class/dbvalidate.jar --projects-root /local/tools/klocwork/server/projects_root 

The dbvalidate tool will report any errors between the "validation started" and "validation finished" lines:

Wed Jun 01 07:53:58 CDT 2022 kw_central database (version: 95) validation started
<detected errors appear here>
Wed Jun 01 07:54:28 CDT 2020 Database validation finished.

• If Errors are displayed, please open a support ticket so that we can correct the error prior to import or migration.
• If no errors are displayed, your database was successfully validated.

You can also run dbvalidate with the --rebuildIndex=true option; This enables you to re-create the lucene index for the specified project, which often allows you to decrease the size of the index.

Important: Make sure you back up your lucene index folder before running dbvalidate with the --rebuildIndex=true option.

For example, you can run the following:

java -cp dbvalidate.jar com.klocwork.dbvalidate.Cleanup231 --projects-root <projects_root_folder> --project <project_name> --rebuildIndex=true

If you received a new license file from Customer Support, copy it to <projects_root>/licenses.

See Customizing licensing for information on licensing options.

To migrate a projects_root, run the following command from <Klocwork_2023.3_Server_install>/bin:

kwservice --projects-root <old_projects_root> start --migrate

If the projects_root migrates successfully, the Klocwork Servers start on the port numbers picked up from the migrated projects_root.

Notes

• If you imported a custom taxonomy in a previous release, you need to re-import the new taxonomy file to pick up changes. See What's new for a list of changes to the taxonomies.
• If you will be running the Klocwork Servers as Windows services, after starting the servers with the --migrate option, stop the servers with kwservice --projects-root <migrated_projects_root> stop. Then start the Klocwork 2023.3 services in Windows Services Administration.
• You can manage the Klocwork servers remotely on Unix with SSH, or on Windows with Windows Services administration. Otherwise, you must issue the start, restart, and stop commands locally.
• The above command converts all external configuration files in the projects_root to UTF-8. All external configuration files must be UTF-8 encoded if they contain multibyte characters (for example, Japanese). External configuration files are those listed in Configuration files you can edit.

• If you modified the MariaDB configuration file located at <old_Klocwork_install>/config/kwmysql.ini, make the same changes to kwmysql.ini in the new installation.

• If you modified the compiler mapping file located at <old_Klocwork_install>/config/kwfilter.conf make the same changes to kwfilter.conf in the new installation.

• If you added custom metrics reports to Klocwork Static Code Analysis, you need to edit the custom metrics report configuration file (metrics.xml). The metrics.xml file is located at: <projects_root>/config.
• If you modified the memory allocation file located at <old_Klocwork_install>/config/java_wrappers_memory.conf, verify that you still need these modifications, and make the same changes to java_wrappers_memory.conf in the new installation.

Notes

• The metrics.xml file applies to a projects_root directory, not to an entire Klocwork installation. Therefore, if you have multiple projects_root directories, you will need to copy your customized metrics.xml file to each of your projects_roots.
• You need to restart the Klocwork Server after customizing the metrics.xml file.

Ensure that you can see your projects and builds in Klocwork Static Code Analysis.

If you installed a new license file, ensure that it was installed correctly by checking that the number of licenses is correct.

To take advantage of the latest improvements in Klocwork, we always recommend you upgrade your Desktop Analysis plug-ins to the latest version of the product.

When upgrading to the Klocwork extension for Visual Studio, any analysis results data generated from the previous version of the plug-in will be removed. Therefore, any local defect citation information not already synchronized with the server will be lost. You can re-analyze your solution(s) to get the analysis results with the new plug-in.

To migrate another projects_root, carry out the steps in this chapter again (except for installing Klocwork).

Summary of upgrade steps for second or later projects_root directory:

1. Prepare to upgrade.
2. Run:

   kwservice --projects-root <projects_root> start --migrate
   

3. Re-create any compiler configuration files you had customized.
4. If you added custom metrics reports to Klocwork Static Code Analysis, edit the custom metrics report configuration file (metrics.xml).
5. Test your upgrade.

New releases of Klocwork normally have changes to the checker configuration to keep up with current events and respond to customer requests. These changes may mean that your checker configuration from the previous release isn't the same in the new release.

Make sure that you have the right checkers enabled to match your old configuration. See What's New for a list of updated checkers, then make any changes to your checker configuration. After you're satisfied with your configuration, re-generate your build specification to capture the latest changes and perform your integration build analysis on unmodified source code.

If you've already run your first Klocwork2023.3 analysis and you're missing some issues or status changes, delete that build, reconfigure your checkers, and run a new analysis.

We recommend running your final pre-upgrade integration build analysis and your first Klocwork 2023.3 analysis on identical source code, and then comparing the two builds. This allows you to assess changes in the analysis engine. For details on improved, added, and removed checkers in this version, see What's New.