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 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 2018.1 analysis run, make sure you read Before your first Klocwork 2018.1 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.

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, Build and Desktop Analysis plug-ins are compatible within each major release, so you can use 2018 plug-ins with a version 2018.1 Klocwork Server. You can also use older build server tools with newer versions of the Klocwork Server, up to three minor releases back. 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 2018.1 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.
7. 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.
8. Stop the servers.
9. (Optional) To create a second restore point, back up the projects_root directories you have prepared for migration.
10. Store the existing Klocwork license in a safe place.
11. To prevent confusion, delete the old Klocwork logs from <projects_root>/logs.

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

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.

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

where

• <2018.1_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 2018 kw_central database (version: 95) validation started
<detected errors appear here>
Wed Jun 01 07:54:28 CDT 2018 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.

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

To migrate a projects_root, run the following command from <Klocwork_2018.1_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, for example, MISRA, 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're using MISRA checkers, you'll also need to copy the misra.checkers.zip file from the taxonomies folder into the <projects_root>/plugins folder.

• 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 2018.1 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 MySQL configuration file located at <old_Klocwork_install>/config/kwmysql.ini

  Make the same changes to kwmysql.ini in the new installation.

  Note: The following fields are no longer supported with the version of MySQL used with version 9.2 and later. If your previous kwmysql.ini file contains these fields, do not copy these lines to the new file:

  skip-bdb

  myisam_max_extra_sort_file_size

  Important: Do not copy your customized configuration files into the new Klocwork installation. Instead, make the same customizations to the newly installed configuration files.

• 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.

  Important: Do not copy your customized configuration files into the new Klocwork installation. Instead, make the same customizations to the newly installed configuration files.

• 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 are running Windows in a 32-bit environment and 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.

Ensure that all Klocwork plug-ins are upgraded to Klocwork 2018.1.

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, perform your first Klocwork 2018.1 integration build analysis on unmodified source code.

We recommend running your final pre-upgrade integration build analysis and your first Klocwork 2018.1 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.