Quick-start - Setting up an integration project for developers to connect to

From Insight-9.0

Jump to: navigation, search

Contents

Before you can run a Klocwork analysis of your integration build and review the results, you need to:

  • download and install the Klocwork Server package
  • configure and start the Klocwork servers

If you haven't already done this, see Quick-start - Installing Klocwork.

You also need some source code to analyze. You'll likely want to use your own source code, but you can also try Klocwork on an open-source project.

Let Klocwork monitor your integration build

Klocwork needs to monitor your build so that it can create a structured build log. We call this log a build specification.

The build specification is the basis of the entire Klocwork analysis, so it's important that it's an accurate and up-to-date representation of your build. If the build specification is inaccurate, the Klocwork analysis will be inaccurate too.

Skip to Java instructions.

Capture build settings for a C/C++ project

Tip: Not sure if your compiler is supported out-of-the-box? Go to Making sure kwinject recognizes your compiler.

This example uses zlib. If you're using your own source code, just substitute your information for the zlib-specific information:

  1. Change the working directory to the top-level source directory that contains the make information, for example: 
     cd /usr/local/zlib-1.2.3/
    Note: A typical open-source project may require some initial setup. Usually this is done with scripts called make clean and configure.
  2. Run kwinject against your project's build command to generate the build specification, with any arguments your build command requires. 
     kwinject <build-command> [arg...]
    We'll use the -o option to specify the name and location of the output text file. In our example, this becomes: 
     kwinject –o /home/klocwork/zlib.out make
    This example specifies that the output file should be named zlib.out.
    Once your build is complete, the build specification is saved to the specified location.

Troubleshooting

If you see an error message about kwcc_config.xml, go to Handling missing includes, defines and macros.

See also:

Making sure kwinject recognizes your compiler

In order for kwinject to recognize your compiler name, you must first identify what compiler type is associated with your compiler in the table below (for example, gcc is a variant of GNU).

1. Look up your compiler type

Go to C/C++ compilers supported for build integration and look up your compiler type to see if it's supported.

If your compiler's exact name doesn't appear in the table, you need to run an extended kwinject command that binds your compiler name to the appropriate Klocwork compiler code, as shown below.

If your compiler doesn't appear in this table at all, you can still use kwinject. See Adding an unsupported compiler.

2. Run the extended kwinject command

Run kwinject with the -P option: 

 kwinject -o <output-text-file> -P <your-compiler>[=<Klocwork-compiler-code>] <native-build-command>

where

  • <your_compiler> is one or more executables applicable to the specified compiler type
  • <Klocwork_compiler_code> is one of the compiler names recognized by kwinject

For example, if your compiler is gcc4 and you know this is a variant of GNU, run the following command: 

 kwinject -o myproject.out -P gcc4=gnu make

In some cases, a single build environment may have multiple compilers or linkers (for example, gcc-x86, gcc-mips, and ar-mips). In this situation, just use multiple instances of the -P option. For example: 

 kwinject -o myproject.out -P gcc-x86=gnu -P gcc-mips=gnu -P ar-mips=ar make

Review your build specification for accuracy

Once you've got a build specification:

  • Confirm the existence of compile, link and config lines.
  • Carefully review the build specification to ensure that your compiler options have been processed properly.

If so, you're ready to move to the next step: Set up an integration project.

Troubleshooting

If your build specification contains only a version line, see Build specification contains only the version line.

For more information on making sure kwinject has accurately captured your build settings, see:

Capture build settings for a Java project

The following example uses the kwant command to capture build settings. You can follow this example if your project is also build with ant 1.6.x or later. Otherwise, choose one of the following:

Note: Klocwork recommends that you run ant clean to have a clean build before you run kwant.

To create a build specification with kwant:

  1. Navigate to the directory that contains your project's build.xml file.
  2. Run kwant with any options required by your build: 
     kwant [ant options]
    For example, freemind does not require any ant options, so all we need to enter is: 
     kwant
    The output file, called kwinject.out, is saved to the specified location.

See kwant for full details on this command.

Checking your build specification file

Open the build specification you just created and confirm the existence of jconfig and jcompile lines.

If the jconfig and jcompile lines are present, you are ready to move to the next step: Set up an integration project.

Troubleshooting

If your build specification file doesn't contain jconfig or jcompile lines, here are a few things you can try:

Providing a build specification template for your development team

Normally, developers working at their desktops each create their own build specifications, either manually, or automatically as part of the Klocwork analysis.

As an alternative, you can create a build specification template that can be used with kwcheck as well as with kwbuildproject.

A build specification template is a version of build specification that uses variables for any paths that may differ on developer desktops. The build engineer can create one file that can be shared with all developers. When the build specification template is used to run a Klocwork analysis, the variable references are replaced with variable values.

This means that a build specification created in one build environment can be used in another build environment.

To learn how to set this up, see Providing a build specification template for your developers.

Set up an integration project

Now you've got a valid build specification. The next step is to set up a Klocwork project for your integration build. The project is a convenient mechanism to centrally manage the information the Klocwork analysis engines create. You only need to do this once.

All we need to do at this point is give our project a name and specify the language of our source code, using kwadmin create-project.

If the Klocwork Server isn't running on your local machine, you'll need to specify the name of the machine where it's running. If the Klocwork Server isn't running on the default port, 8080, you'll need to specify the port number.

Here's an example that specifies the host and port: 

kwadmin --host server2.klocwork.com --port 1109 create-project zlib_1_2_3 --language c,cxx

Note: If you see an error message saying that you need to run kwauth first, see kwauth.

That's all there is to it. We're ready to run an analysis.

Tip: You can also use the Klocwork Management Console GUI for many of the tasks in this section, if you prefer. See Getting started with the KMC.

Analyze your integration build

To analyze your integration build, you use the kwbuildproject command. All you need to do is point to the project and build specification you created earlier, and tell Klocwork where to store the output files.

Using zlib as an example: 

kwbuildproject --project zlib_1_2_3 /home/klocwork/zlib.out --tables-directory /home/klocwork/zlib_tables

Using the --project option is optional, but ensures that kwbuildproject will pick up the current project-specific settings.

Tip: If you're building C/C++ code, you can speed up the analysis by distributing the load. See Running a Klocwork distributed analysis.

Check your build log for errors

Analysis progress is displayed while the build is running. If you see errors such as include or parse errors, see Troubleshooting.

After the analysis, you can find the full build log (build.log) in the output tables directory. In the KMC, you can view the full log for a completed analysis by selecting the build in the tree view, selecting the Status tab in the right pane, and clicking View Full Log. The build log is displayed in your default text editor.

Load the analysis results into the Klocwork database

To complete the analysis, you need to load the results into the Klocwork database and create the reports using the kwadmin load command.

Just specify the name of your Klocwork project and the path to the tables directory from the previous step.

If the Klocwork Server isn't running on your local machine, you'll need to specify the name of the machine where it's running. If the Klocwork Server isn't running on the default port, 8080, you'll need to specify the port number.

Using zlib as an example: 

kwadmin --host server2.klocwork.com --port 8088 load zlib_1_2_3 /home/klocwork/zlib_tables

What do I need to do for the next analysis?

After you've run the initial full analysis, here's what you need to do the next time:

  1. Update your build specification, if necessary, using the --update option of kwinject. See kwinject for details.
    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.
  2. Analyze your integration build.
  3. Load the analysis results into the Klocwork database.

What's next?

At this point, two things can happen:

You might also want to check out the following:

Retrieved from "http://www.klocwork.com/products/documentation/Insight-9.0/Quick-start_-_Setting_up_an_integration_project_for_developers_to_connect_to"
Personal tools