Creating a Java build specification

Klocwork integrates with your build, capturing all of the information it needs to provide a centralized view of the entire code stream.

Klocwork stores this information in a text file called a build specification. The build specification is the basis of the Klocwork analysis.

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

Check out our cheat sheet as a quick reference Java integration build analysis - Cheat sheet.

A build specification is required at both the integration and local build levels.

For the integration build, creating a build specification is the first essential task following installation.
For some desktop environments, build integration happens automatically; for others, you need to create a build specification manually. If you're not sure whether you need to create a build specification manually, see Fixing issues before check-in with Klocwork Desktop Analysis and choose your coding environment.

You can analyze Klocwork Java projects from one or more build specification files based on the information in your build files. You can use the following automation tools to build your Java projects:

Gradle: You can use the kwgradle command or the kwgradlew command to generate the build specification for a project built with Gradle. These commands call the Gradle build natively to collect build events and generate a build specification.
Apache Maven: You can use the kwmaven command to generate a Klocwork build specification for a project built with Maven. The kwmaven command calls the maven build natively to collect build events and generate a build specification.
Apache Ant: There are two ways of generating the build specification for a project built with Ant. You can use the kwant command to launch Ant through an Ant script, intercepting the invocation of the javac task and generating the build specification. Or, you can edit the Ant build.xml file to include a kwant task.

The Klocwork build specification for Java projects is a semi-colon-separated text file containing the following information about the source code that will comprise your Klocwork project:

the classpath and Java version used for the javac invocation in the Gradle, Maven or Ant build
the source java files that were compiled
the Java class or .jar files, or directories containing class files or .jars

Prerequisites

Before you can create a build specification

install the Validate package. See Installing Klocwork.
verify your version of Gradle is supported. See Supported Java build tools to see what versions are supported.
you must use a javac from the Java Development Kit (JDK).

you must have the path to the Gradle, Maven, Ant, and JVM executables set in the PATH environment variable:

Unix:

PATH=<path_to_gradle_mvn_or_ant>/bin:<path_to_JDK>/bin:<klocwork_install>/bin:$PATH

Windows:

PATH=<path_to_gradle_mvn_or_ant>\bin;<path_to_JDK>\bin;<klocwork_install>\bin;%PATH%

Using kwgradle to create a Java build specification

To create a build specification with kwgradle:

Run gradle clean.
Navigate to the directory that contains the build.gradle file. (Skip this step if you specify the file name with the -f option of gradle).

Run kwgradle:

kwgradle --output /home/klocwork/freemind.out install

Continue to Checking your build specification file.

Using kwgradlew to create a Java build specification

To create a build specification with kwgradlew:

Run gradle clean.
Navigate to the directory that contains the gradelew file, or for Windows, the gradelew.bat file.

Run kwgradlew:

kwgradlew --output /home/klocwork/freemind.out install

Continue to Checking your build specification file.

Using kwmaven to create a build specification

To create a build specification with kwmaven:

Run mvn clean.
Navigate to the directory that contains the pom.xml file. (Skip this step if you specify the file name with the -f option).

Run kwmaven install:

kwmaven --output /home/klocwork/freemind.out install

Continue to Checking your build specification file.

Using kwant to create a Java build specification

To create a build specification with kwant:

Run ant clean.
Navigate to the directory that contains the build.xml file. (Skip this step if you specify the file name with the -f option of ant).

Run kwant:

kwant --output /home/klocwork/freemind.out

Continue to Checking your build specification file.

Manual integration -- editing the Ant build file

Editing the Ant build.xml file allows you to generate a build specification with greater control over all stages of the build. In this case, you add the exec-listener task to your Ant build file, which will use the Klocwork Ant build listener (KwAntListener) to produce a build file.

To edit the Ant build file and produce a build specification:

Edit the Ant build.xml file to add the kwant taskdef and properties after the project description (see example below).
Run your Ant build as usual.

Example

 <project name="MyProject" default="dist" basedir=".">
    <!-- Insert the following code -->
    <property name="kwout" location="kwant.out"/>
    <property name="rep.inst" location="full path to the installation directory"/>
    <!-- Included for integration builds -->
    <property name="buildspecUpdate" value="true"/>
    <taskdef name="exec-listener" classname="com.klocwork.kwant.KwAntListener">
        <classpath>
            <pathelement location="${rep.inst}\class\kwant.jar"/>
            <pathelement location="${rep.inst}\class\buildspec.jar"/>
            <pathelement location="${rep.inst}\class\kwutils.jar"/>
            <pathelement location="${rep.inst}\class\log4j.jar"/>
            <pathelement location="${rep.inst}\class\jdom.jar"/>
            <pathelement location="${rep.inst}\class\commons-io-1.4.jar"/>
            <pathelement location="${rep.inst}\class\datautils.jar"/>
            <pathelement location="${rep.inst}\class\buildutils.jar"/>
       </classpath>
    </taskdef>
    <exec-listener/>
</project>

The output file is saved to the specified location. You can now use the build specification to build the project.

When running in incremental mode (the buildspecUpdate property is set to true), manual integration will only pick up compiled files at build time. Any previously compiled files won't be added to the build specification for analysis. To get those files, you must recompile your project (for example: ant clean build).

Build specifications for projects that contain .jsp files

For a project that contains .jsp files, you create two build specifications:

one build specification for the .jsp files, using kwwebappscan. kwwebappscan scans the directory, finds Web application directories that contain .jsp files, and produces a build specification. For full details on this command, see kwwebappscan.
one build specification for the Java source files, as shown in previous sections

You then use both build specifications when you run a Klocwork analysis on the project.

Checking your build specification file

Open the build specification you just created and confirm the existence of jconfig and jcompile lines. For more details on the format of this file, see Build specification file format .

If the jconfig and jcompile lines are present, you are ready to move to the next step: Running the Java integration build analysis.

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

Make sure your project contains Java source files.
Look at alternate integration methods. See the alternate methods described in this article.

When to recreate your build specification

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

if you upgrade to a new version of Klocwork
if you modify build settings
if you have done a clean build (full rebuild of your source files)

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

What's next?

If you're analyzing your integration project, go to Running the Java integration build analysis.
If you're analyzing a desktop project, go to Fixing issues before check-in with Klocwork Desktop Analysis and pick your development environment.