In this section

Introduction

Checkstyle is a third-party open source tool that performs static analysis on Java code and reports potential problems. Checkstyle Analyzer is a Parasoft integration that allows Checkstyle to send violations to Parasoft (DTP) so that these results can be processed and viewed along with other data points. The integration also adds scope, authorship, and source control support that further enhance Checkstyle capabilities. Additionally, it allows the generation of a Parasoft Report that shows violations for each author and each severity.

This integration gives a development organization the ability to aggregate the results of all testing efforts across a variety of technologies, or even compare and contrast results from different analysis tools in one centralized location—increasing productivity and efficiency.

Requirements

• One of the following versions of Checkstyle and all its prerequisites should be installed on the testing machine: 5.5, 5.6. 5.7, 6.5 or 6.8
• The project to be tested must be compiled.
• Tested files must be have the .java file extension.
• Parasoft Analyzer package must be installed.
• Oracle Java Runtime 1.8.0 or higher (required to run Parasoft Analyzer package).

Installation

1. Unzip the analyzer into the directory where the Parasoft Analyzer package was installed. See the Parasoft Analyzer package documentation.
2. Create a plain text settings file with the required settings (see Configuration). We recommend using the provided checkstyle.settings.properties file as an example of a complete settings file. The file is located in the <ANALYZER_HOME>/examples directory. A full list of general settings properties can be found in the documentation provided with the Parasoft Analyzer package.

Usage

1. Open a command prompt and navigate to the Parasoft Analyzer package installation root directory.
2. Execute the parasofttestcli.bat or parasofttestcli.sh script using the required parameters, e.g., (all one line): 

parasofttestcli.bat -Dsettings="C:\sample\checkstyle.settings.properties" -Dconfig="file:///C:\sample\checkstyle.properties" -Ddata.dir="C:\sample\sampleProjectFolder"

Required Parameters

The following settings are required.

-Dconfig

Path to the test configuration that the analyzer should use for its run. Make sure to prepend the file path with file:///

-Dsettings

Path to the settings configuration file (see Configuration).

-Ddata.dir

Path to the file or folder you want to test.

Configuration

See the Parasoft Analyzer package documentation for a complete list of configurations.

Required Settings

The following settings are required to run the Checkstyle extension.

jtest.analyzer.checkstyle.enabled

Enables the analyzer. Values are true or false.

Example:

jtest.analyzer.checkstyle.enabled=true

jtest.analyzer.checkstyle.dir

The installation directory of Checkstyle.

Example:

jtest.analyzer.checkstyle.dir= C:\\ThirdParty\\checkstyle-5.7

Optional Settings

The following settings are not required to run the Checkstyle extension.

jtest.analyzer.checkstyle.files.limit

Custom limit for number of files to be tested in a single executed Checkstyle process. 

Example:

jtest.analyzer.checkstyle.files.limit=1000

jtest.analyzer.checkstyle.launch.timeout

Custom timeout (seconds) for the Checkstyle process to start. Default is 5.

Example:

jtest.analyzer.checkstyle.launch.timeout=20

jtest.analyzer.checkstyle.timeout

Custom timeout (seconds) for the Checkstyle process to complete. Default is 360.

Example.

jtest.analyzer.checkstyle.timeout=10

jtest.analyzer.checkstyle.launch.file

Custom launch file for Checkstyle process. Default is taken from the Checkstyle analyzer jar file. If one cannot be found, the extension attempts to use the checkstyle.ini file from the current working directory.

Example:

jtest.analyzer.checkstyle.launch.file=path\\to\\launch\\file

Customizing Rule Details and Metadata (Optional)

Parasoft DTP displays code analysis violations according to severity level, rule category, and other characteristics according to a rule map XML file. You can edit the rule map to change the default rule settings, as well determine how new rules that are not yet defined in the rule map are categorized and tagged in DTP.

The Checkstyle extension ships with an example rule map file in the <ANALYZER_HOME >/rules/builtin directory. Rules are specified using the following format:

<builtin>
	<category name=”Analyzer_name”>
		<category name=”Category_name”>
			<rule id=”rule_id” severity=”sev”/>

You can modify this file to change mappings and add new rules:

1. Either open the example rule map file or create a new one based on the example.
2. Modify the rule entries as desired.
3. If you created a new rule map file, adjust the rulemap value in .properties file.

About Rule Map Syntax

• A name property is required for category tags.
• id and severity properties are required for the rule element. Each id value must be unique within a given rule map file.
• Multiple rules with the same id in the same rule map file, even if the rules are under different categories or analyzers, are not allowed.
• If you are modifying rules that are shipped with the analyzer (rules in the builtin directory) only modify elements within the <builtin> element.

Adding Rule Documentation to DTP

You can add rule documentation to the DTP web application so that it can display the documentation for each individual rule. Once the rule documentation is installed, you will be able to view it as you browse Checkstyle violations in DTP.

• DTP requires a separate HTML file for each rule.
• Each filename must be the full name of the rule. For example, a rule named "CS.category.subcategory.ruleID” would need a file called “CS.category.subcategory.ruleID.html”.
• All HTM/HTML files must be stored in a specific folder structure using the analyzer ID and version as defined in the analyzer code. For example, the directory should be structured as "com.puppycrawl.tools.checkstyle/1.0/CS.category.subcategory.ruleID.html" if the Checkstyle analyzer has the following properties:
  
  analyzerID=com.puppycrawl.tools.checkstyle 
analyzerVersion=1.0
   
• Documentation directories should be saved under <DTP_INSTALLATION_DIR>/webapps/grs/ruledocs

Change Log

The following updates have been made to the Checkstyle extension.

Updates for 10.4.1

• Updated Parasoft Test library to 10.4.1
• The DTP Engine Package has been renamed to Parasoft Analyzer package. 

Updates for 10.3.4

• Updated Parasoft Test library to 10.3.4
• Can now run as a standalone analyzer without Jtest.
• The DTP Engine Package now uses a Parasoft Test license instead of a DTP license. Contact your Parasoft representative to obtain a Parasoft Test license if you don't have one.