Deploying custom checkers

From current

Custom checkers > Deploying custom checkers

Contents

Introduction

The kwdeploy command is used to deploy checkers to a server project, making them available to any connected desktops through synchronization.

Note: KAST checkers with custom functions and C/C++ Path checkers require manual installation on the desktop because synchronization doesn’t push .dll or .so files to the desktop from the server or vice-versa.

Conversely, desktop-only deployments are accomplished by putting the checker deployment package in the appropriate folder (without the use of kwdeploy).

Whether deploying checkers to the server-project or only the desktop, the process starts with the checker deployment package.

Note: This how-to assumes that you have added the Klocwork bin directory to your Path. On Windows, the Klocwork bin directory is automatically added to your System Path environment variable.

About the checker deployment packages

What is a checker deployment package?

A checker deployment package is an archive (JAR or ZIP file) that contains the files necessary to:

  • display the checker in the Configuration Editor for integration projects and in the Configuration Editor for any connected desktops, so that users can enable or disable the new checker
  • detect the specific C/C++ or Java issue type
  • display issue help for the checker in Klocwork Review
  • display issue help for the checker in C and C++ checker reference and Java checker reference at http://<klocwork_server_host>:<klocwork_server_port>/documentation. Klocwork Documentation is available only if your organization has a server installation of Klocwork.
  • displays the appropriate message and title for the checker in the analysis results in Klocwork Review and the Klocwork plug-ins

Java checkers are contained in a JAR file; C/C++ checkers are contained in a ZIP file.

Contents

The contents of the checker deployment package vary depending on whether the checker is:

  • C/C++ or Java
  • a KAST or Path checker

See Checker deployment package contents.

Package deployment considerations

From a deployment perspective, the most important aspects of the checker deployment package are:

  • whether it’s Java or C/C++ (and if C/C++, whether it’s platform-specific or not)
  • whether you want the checker to be disabled before deployment

Platform specific or not?

If the checker deployment package is in a ZIP file, it’s a C/C++ checker. Typically, C/C++ checkers are platform specific. However, C/C++ KAST checkers that do not use custom functions are platform independent.

Check the contents of the checker deployment package (ZIP file) to see if it contains platform subdirectories at the top level.

For server deployments: Copy the ZIP to <projects_root>/plugins. If it is platform-specific, copy the ZIP to <projects_root>/plugins/<platform-name>. See Deploying custom checkers for a server installation.

Note: You may need to create a plugins subdirectory in your projects_root directory. If the checker is platform-specific, you will also need to create the proper platform subdirectory in <projects_root>/plugins.

For desktop deployments: Unzip the file and ensure the platform directory is copied over to your <username>/.klocwork/plugins directory. See Desktop-only deployment.

The possible subdirectories are:

  • ix86-pc-win32
  • ix86-pc-linux
  • sparc-sun-solaris2
  • powerpc-ibm-aix

Checker deployment package contents

JAR file contents

The JAR for a Java Path or KAST checker contains:

Filename or folder Description
<CHECKER.CODE>.jkb contains the knowledge base file that defines the checker behavior for Java Path checkers only.
checkers.xml is the checker configuration, which by default has the checker enabled for analysis. This is the file you need to access if you want to disable the checker before deployment, see Manually disabling a checker before deployment.
toc.xml, <CHECKER.CODE>.htm, etc. contains the checker’s help files converted into a format understandable by Klocwork Review, as well as Klocwork Documentation at http://<klocwork_server_host>:<klocwork_server_port>/documentation

ZIP file contents

The ZIP for a C/C++ KAST or Path checker contains:

Filename or folder Description
<CHECKER.NAME>.xml is the checker configuration, which by default has the checker enabled for analysis. This is the file you need to access if you want to disable the checker before deployment; see Manually disabling a checker before deployment
<CHECKER.NAME>.jar contains the checker’s help files converted into a format understandable by Klocwork Review, as well as Klocwork Documentation at http://<klocwork_server_host>:<klocwork_server_port>/documentation
<platform directory> platform directory if the checker is a:
  • KAST checker that uses custom functions
  • Path checker

The platform directory should contain the plug-in library ( .so or .dll).

Manually disabling a checker before deployment

By default, a custom checker is enabled for analysis; consequently, any results from connected desktops and distributed analysis will detect the new issue before a new server-project analysis is available. If you will be using kwdeploy install, you may want to manually disable the checker before you deploy it and then enable it before your next server-project analysis. This will avoid discrepancies in analysis results.

Alternatively, you can use kwdeploy sync when deploying new checkers to avoid differing analysis results.

To disable the checker, you’ll need to change enabled="true" to enabled="false" in either the checkers.xml file for a Java checker or <CHECKER.NAME>.xml for a C/C++ checker.

Disabling the checker

  1. Access the JAR or ZIP file.
  2. Open checkers.xml (Java) or <CHECKER.NAME>.xml (C/C++) in the editor of your choice.
  3. Change the "enabled" attribute of the error tag from "true" to "false".
  4. Save the file.
  5. Repack the JAR or ZIP file.
    • C/C++: Run make install (Unix) or nmake install (Windows).
    • Java: Run ant.

Server-project and connected desktop deployment

About checker deployments for server installations

The instructions for installing checkers also include steps for organizations that use distributed analysis.

If your organization has connected desktops or distributed analysis and you will be using kwdeploy install, you might want to disable the checkers before deploying them. If you don’t disable the checkers before installation:

  • the connected desktops might have different results from the server-project (until the next server-project analysis is available)
  • your distributed analysis results might differ from your server project analysis

If you use kwdeploy sync or have a server project with neither connected desktops nor distributed analysis, you don’t have to worry about differing results.

Note: KAST checkers with custom functions and C/C++ Path checkers require manual installation on the desktop because synchronization doesn’t push .dll or .so files to the desktop from the server or vice-versa.

Deploying custom checkers for a server installation

The steps involved in deploying custom checkers to a server-project (that may have connected desktops and/or distributed analysis) are:

  1. Optional: Disable the checker before deployment. This is recommended if you are using kwdeploy install for server installations with connected desktops and/or distributed analysis. See Manually disabling a checker before deployment.
    Distributed analysis: If you distribute the Klocwork analysis, you also need to stop the Distributed Analysis Server and agents.
  2. If your projects_root directory does not contain a plugins folder, you will need to create one manually. See Platform specific or not?.
  3. For C/C++ checkers (ZIP):
    • Copy the ZIP to <projects_root>/plugins.
      Note: If it is a platform-specific checker, copy the ZIP into <projects_root>/plugins/<platform-name>.
  4. For Java checkers (JAR):
    • Copy the JAR to <projects_root>/plugins.
    Distributed analysis:
    • Start the Distributed Analysis Server with kwdist, using the --sync-custom-checkers and --web-url options to reflect the custom checkers deployed on (or removed from) the Klocwork Server.
    • Register the distributed analysis agents with kwagent.
  5. Run kwdeploy install or Run kwdeploy sync.
  6. Optional: Enable the checkers in the Configuration Editor:
    • From Klocwork Review, open the Configuration Editor for the project.
    • In the Issues configuration tab, expand the appropriate language, either C and C++ or Java.
    • Locate the new checker(s) under the Custom checkers tree and add a check.
  7. Run an integration build analysis with kwbuildproject: 
    kwbuildproject --tables-directory <dir> [<options>] <build_specification>
    Distributed analysis:
  8. Have connected desktop users synchronize with the Klocwork Server and run a desktop analysis with kwcheck or in their IDE.

For more information, see:

Run kwdeploy install

kwdeploy install gives you more control over your build environment by allowing you to specify which checkers you want to deploy to your build environment from the <projects_root>/plugins directory. See also Manually disabling a checker before deployment.

On the other hand, kwdeploy sync automatically deploys or uninstalls any checkers to/from your build environment that are different (added or removed) from the contents of the <projects_root>/plugins directory.

Prerequisite

You must have copied the checker deployment package(s) into the <projects_root>/plugins directory before using kwdeploy. See Step 3 in Deploying custom checkers for a server installation.

Run: 

kwdeploy install <CHECKER1> <CHECKER2> <...> [--url http(s)://<host>:<port>]

where

  • <CHECKER1> <...> are the names of the checker deployment packages being deployed. Multiple checkers should be delimited with spaces. Important: The checker names are case sensitive and should NOT include the file extensions .jar or .zip.
  • <host> is the Klocwork Server host name (default: localhost)
  • <port> is the Klocwork Server port number (default: 8080)

Run kwdeploy sync

kwdeploy sync automatically matches the checkers in your build environment with those currently available in the <projects_root>/plugins folder. There is no need to specify checker names or use an uninstall subcommand when removing checkers from your build environment.

Prerequisite

Or

  • If removing checkers, you must first delete the checkers from <projects_root>/plugins before running kwdeploy sync to remove them from your build environment: 
    kwdeploy sync [--url http(s)://<host>:<port>]
    where
    • <host> is the Klocwork Server host name (default: localhost)
    • <port> is the Klocwork Server port number (default: 8080)

Desktop-only deployment

About desktop-only deployments

Desktop-only deployment does not require the use of kwdeploy. It’s simply a matter of copying or unzipping the checker deployment package to <username>/.klocwork/plugins.

Typically, deploying a custom checker to a single desktop is done as part of the testing process during checker development. If this checker is to be deployed to the Klocwork server-project and connected desktops, it is recommended that you remove the checker from your desktop and re-install it by synchronizing with the server project.

Deploying custom checkers to the desktop only

Copy the JAR file (Java checker) or unzip the ZIP file (C/C++ checker) into the plugins folder.

If you do not see a plugins directory in the following location, you must create a plugins folder manually in <username>/.klocwork/plugins. The location varies depending on your operating system:

  • Unix: ~<username>/.klocwork/plugins
  • Windows 7 and Vista: C:\users\<username>\.klocwork\plugins
  • Windows XP: C:\Documents and Settings\<username>\.klocwork\plugins

If the checker deployment package is a ZIP file, you must unzip it into the plugins directory. Make sure the "Use folder names" option is checked in the zip utility dialog so that platform directories will be copied over.

Possible platform directories are:

  • ix86-pc-win32
  • ix86-pc-linux
  • sparc-sun-solaris2
  • powerpc-ibm-aix

Uninstalling checkers

Introduction

For Klocwork Server deployments, to uninstall custom checkers you can use either kwdeploy uninstall to remove specified checkers or kwdeploy sync to mirror the checkers in <projects_root>/plugins.

When you uninstall checkers, analysis results in the connected desktops and distributed analysis will differ from the server-project until the next analysis is complete. After uninstalling checkers, it's recommended that another server-project analysis is run as soon as possible to minimize these discrepancies.

To uninstall checkers from the desktops only, simply delete the checker deployment package from <username>/.klocwork/plugins.

Uninstalling checkers from a server installation

Uninstall checkers using kwdeploy uninstall

  1. Run kwdeploy uninstall: 
    kwdeploy uninstall <CHECKER1> <CHECKER2> <...> [--url http(s)://<host>:<port>]
    where
    • <CHECKER1> <...> are the names of the checker deployment packages being deployed. Multiple checkers should be delimited with spaces.
    Important: The checker names are case sensitive and should NOT include the file extensions .jar or .zip.
    • <host> is the Klocwork Server host name (default: localhost)
    • <port> is the Klocwork Server port number (default: 8080)
  2. Stop the Klocwork Servers with kwservice stop or Windows Services Administration. Stopping and then starting the servers updates context-sensitive issue help and Klocwork Documentation to reflect the checkers that are installed or removed.
    Distributed analysis: You also need to stop the Analysis Server and agents with kwdistadmin stop-server.
  3. Delete the checkers from <projects_root>/plugins.
    Note: If the checker is platform dependent, you will need to delete it from the <projects_root>/plugins/<platform name> directory.
  4. Start the Klocwork Servers with kwservice start or Windows Services Administration.
  5. Distributed analysis:
    • Start the Distributed Analysis Server with kwdist, using the --sync-custom-checkers and --web-url options to reflect the custom checkers deployed on (or removed from) the Klocwork Server.
  6. Run an integration build analysis with kwbuildproject: 
    kwbuildproject [options] <build_specification> --tables-directory <dir>
    Distributed analysis: Run kwbuildproject with the --remote option.
  7. Have connected desktop users synchronize with the Klocwork Server and run a desktop analysis with kwcheck or in their IDE.

Uninstall checkers using kwdeploy sync

  1. Stop the Klocwork Servers with kwservice stop or Windows Services Administration. Stopping and then starting the servers updates context-sensitive issue help and Klocwork Documentation to reflect the checkers that are installed or removed.
    Distributed analysis: You also need to stop the Distributed Analysis Server and agents.
  2. Delete the checkers from <projects_root>/plugins.
    Note: If the checker is platform dependent, you will need to delete it from <projects_root>/plugins/<platform-name>.
  3. Start the Klocwork Servers with kwservice start or Windows Services Administration.
    Distributed analysis:
    • Start the Distributed Analysis Server with kwdist, using the --sync-custom-checkers and --web-url options to reflect the custom checkers deployed on (or removed from) the Klocwork Server.
    • Register the distributed analysis agents with kwagent.
  4. Run kwdeploy sync.
  5. Run an integration build analysis with kwbuildproject: 
    kwbuildproject [options] <build_specification> --tables-directory <dir>
    Distributed analysis: Run kwbuildproject with the --remote option.
  6. Have connected desktop users synchronize with the Klocwork Server and run a desktop analysis with kwcheck or in their IDE.

Uninstalling checkers from the desktop

If you were testing a checker as part of your checker development process and it is ready for deployment, provide the checker deployment package to your build integration team and then delete the checker from your desktop.

You will need to delete the checker files from the desktop plugins folder. The location varies depending on your operating system:

  • Unix: ~<username>/.klocwork/plugins
  • Windows 7 and Vista: C:\users\<username>\.klocwork\plugins
  • Windows XP: C:\Documents and Settings\<username>\.klocwork\plugins

Notes

  • The Java checker is a JAR file.
  • You will need to remove all of the files associated with the C/C++ checker.

Documentation for custom C/C++ checkers

Overview

How-to

Tutorials

Examples

Deployment

  • Deploying custom checkers

Reference

Retrieved from "http://www.klocwork.com/products/documentation/current/Deploying_custom_checkers"