Integrating Klocwork with Electric Cloud

From Insight-9.0

Jump to: navigation, search

Contents

Overview

If you run your native C/C++ builds in the Electric Cloud environment, you can integrate the Klocwork system build analysis with Electric Cloud.

The main steps in the integration process are:

  1. Generate a build specification for Electric Cloud. Note that a build specification template can also be used for Electric Cloud integrations.
  2. Run a distributed Klocwork analysis in Electric Cloud, using the build specification as input.
  3. Create a Klocwork project. See Set up a system-build project.
  4. Load the analysis results into the database. See Load the analysis results into the Klocwork database.

Note: The Klocwork servers must be running for the last two steps. See Starting the Klocwork servers.

Deployment considerations

The tools required for this integration are included in the Command Line Build Tools component of the Klocwork Server package.

You must install the Command Line Build Tools component in one of the following configurations:

  • Install Klocwork to the same path on all Electric Cloud agent hosts.
  • Specify the path to the Klocwork installation on the command line.

When using the second of these two configurations, you must specify both the Klocwork installation directory and your current working directory to emake. You can do this in one of two ways:

  • edit the EMAKE_ROOT environment variable, and export the variable, or
  • use the kwecbuild option --ec-option to specify the emake option --emake-root. For example: 
    --ec-option "--emake-root=/space/testing/kw/9.0/:/space/test.lab/ecloudtests/cvs-1.11.23"

When you use the --emake-root option or the EMAKE_ROOT environment variable, Electric Cloud no longer distributes the current working directory to the agents by default. This is why you need to specify both the Klocwork installation directory path and your current working directory.

IMPORTANT: Spaces are not supported in the paths to source files or the tables directory.

Note that when using Cygwin, you need to specify the --cmd-line option of kwlogparser.

Generate a build specification for Electric Cloud

The steps involved in creating a build specification in the Electric Cloud environment are:

  1. Create an emake annotation file. This XML annotation file is a structured log of the distributed build, with some extra information (such as automatically tracked dependencies and time metrics).
  2. Convert the annotation file into a Klocwork build trace. A build trace is a file that contains the sequence of process calls that took place during your native build (for example, the make command).
  3. Use the build trace to create a build specification or build specification template.

Note: For more information on creating build specifications, including customizing the master compiler filter file (kwfilter.conf) and compiler filter files, see How kwinject works.

To create a build specification in the Electric Cloud environment

  1. Run emake with the following options to generate an annotation file: 
    emake --emake-cm=<clusterManagerHost> --emake-annodetail=basic --emake-annofile=<annotation_file>
    where
    <clusterManagerHost> is the host where the cluster manager is installed
    <annotation_file> is the output build log
    Note: You must use the same working directory for emake and kwecbuild.
    For example: 
    emake --emake-cm=serverXYZ --emake-annodetail=basic --emake-annofile=emake.xml
  2. Run kwlogparser to convert the annotation file into a build trace: 
    kwlogparser [options] <parser> <annotation_file>
    For example: 
    kwlogparser -o emake.trace emake-annotation emake.xml
    This command converts the emake annotation log file named emake.xml into a build trace named emake.trace.
  3. Run kwinject to convert the build trace into a build specification or build specification template: 
    kwinject --trace-in <file> [options]
    For example: 
    kwinject --trace-in emake.trace -o emake.out
    This command converts the trace file we generated in step 2 into a build specification named emake.out.

When do I need to update my build specification?

You need to update or create a new build specification in the following situations:

  • if source files are added or removed
  • if build settings are changed

If you reuse an existing build specification or try to modify it manually in these situations, the analysis results will not be accurate.

Run a distributed Klocwork analysis in Electric Cloud

To run a distributed Klocwork analysis in Electric Cloud, run kwecbuild from the native build directory: 

kwecbuild --ec-make <path_to_emake> [<other_options>] <build_specification_file>

where:

  • <path_to_emake> is the path to the Electric Cloud emake utility
  • <other_options> are any of the kwecbuild options
  • <build_specification_file> is a build specification file created by kwinject

Important:

  • kwecbuild must be executed from same directory as the Electric Cloud integration system build.
  • The output (tables) directory for kwecbuild must be under the current working directory.

Example 

kwecbuild --ec-make /opt/ecloud/i686_Linux/bin/emake --ec-host server01 --output-dir tables kwinject.out

This example command outputs Klocwork tables to the tables subdirectory of the current working directory.

Where does kwecbuild run the various Klocwork analysis stages?

  • The compilation stage is integrated into the Electric Cloud environment. The generated make file is located at <output_tables_directory>/makefile.
  • The issue detection stage is integrated into the Electric Cloud environment. The generated make file is located at <output_tables_directory>/clef/ecMakefile.
  • The linking and reports stages are executed locally.

Limitations

  • Only a full, complete analysis is supported. Incremental analysis is not supported, and it is not possible to resume an analysis with kwecbuild.
  • Multibyte characters (such as Japanese) are not supported by kwecbuild.

Example

The following example uses the open-source project readline.

The <Server_install>/bin directory has been added to $PATH.

Our current working directory is /space/source/x86-32/c/readline/5.2.

Creating a build specification for Electric Cloud

First we need to create a build specification, which will then be used as the basis for our system build analysis.

  1. We run emake to generate an annotation file. 
    /opt/ecloud/i686_Linux/bin/emake --emake-cm=localhost --emake-annodetail=basic --emake-annofile=emake.xml
    This command specifies that the emake cluster manager is on localhost, and creates an annotation file named emake.xml.
  2. We convert the annotation into a build trace with kwlogparser. 
    kwlogparser --output emake.trace emake-annotation emake.xml
    This command converts emake.xml into a build trace named emake.trace.
  3. We convert the build trace into a build specification with kwinject. 
    kwinject –-trace-in emake.trace
    This command generates a build specification from emake.trace. The default output build specification file name, kwinject.out, will be used.

Running a distributed analysis with kwecbuild

Now we can use the build specification to run a distributed analysis.

  1. We ensure that our current working directory is the same directory as our Electric Cloud integrated system build.
    /space/source/x86-32/c/readline/5.2
  2. We run a distributed Klocwork analysis in Electric Cloud, using the build specification as input.
    kwecbuild --force --license-host flex1 --ec-make /opt/ecloud/i686_Linux/bin/emake --ec-host localhost --output-dir tables kwinject.out
    This command runs a distributed analysis on the build specification kwinject.out. Note that as required, the output directory for kwecbuild is inside the current working directory. The --force option allows us to overwrite data from a previous analysis.
  3. We make sure the Klocwork servers are running before performing the next two steps. See Starting the Klocwork servers.
  4. We create a Klocwork project.
    kwadmin create-project readline52
    This command creates a project named readline52.
  5. We load the analysis results into the database.
    kwadmin load readline52 tables
    This command loads the data in the tables directory into the Klocwork database.
Retrieved from "http://www.klocwork.com/products/documentation/Insight-9.0/Integrating_Klocwork_with_Electric_Cloud"
Personal tools