How to Run PVS-Studio Java


PVS-Studio Java static code analyzer consists of 2 main parts: the analyzer core, which performs the analysis, and plugins for integration into build systems and IDEs.

Plugins extract project structure (a collection of source files and classpath), then pass this information to the analyzer core. In addition, plugins are responsible for deploying the core for analysis - it will be automatically downloaded during the first analysis run.

The analyzer has several different ways to integrate into a project.

System Requirements

  • Operating system: Windows, Linux, macOS;
  • Minimum required Java version to run the analyzer with: Java 8 (64-bit). Note: A project being analyzed could use any Java version;
  • Minimum required IntelliJ IDEA version: 2017.2 (optional)

Plugin for Maven

For projects with Maven build system, you can use the pvsstudio-maven-plugin. To do this, you need to add the following to the pom.xml file:

<pluginRepositories>
  <pluginRepository>
    <id>pvsstudio-maven-repo</id>
    <url>http://files.viva64.com/java/pvsstudio-maven-repository/</url>
  </pluginRepository>
</pluginRepositories>
<build>
  <plugins>
    <plugin>
      <groupId>com.pvsstudio</groupId>
      <artifactId>pvsstudio-maven-plugin</artifactId>
      <version>7.02.32034</version>
      <configuration>
        <analyzer>
          <outputType>text</outputType>
          <outputFile>path/to/output.txt</outputFile>
        </analyzer>
      </configuration>
    </plugin>
  </plugins>
</build>

After that, you can run the analysis:

$ mvn pvsstudio:pvsAnalyze

In addition, the analysis can be included in a project build cycle by adding the execution element:

<plugin>
  <groupId>com.pvsstudio</groupId>
  <artifactId>pvsstudio-maven-plugin</artifactId>
  <version>7.02.32034</version>
  <executions>
    <execution>
      <phase>compile</phase>
      <goals>
        <goal>pvsAnalyze</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Entering license information

To enter the license information you can use the following command:

mvn pvsstudio:pvsCredentials "-Dpvsstudio.username=USR" "-Dpvsstudio.serial=KEY"

After that, the license information will be saved in %APPDATA%/PVS-Studio-Java/PVS-Studio.lic in Windows OS or in ~/.config/PVS-Studio-Java/PVS-Studio.lic in macOS and Linux.

Configuration

Analyzer configuration is performed in the <analyzer> section. A list of analyzer options is given below.

  • <outputFile>PATH</outputFile> - a path to the file with the analyzer report. Default value: ${basedir}/PVS-Studio. Note: for a report in the 'fullhtml' format in outputFile it is necessary to specify a directory in which a folder will be created with the name 'fullhtml' containing the analyzer report. Default value: ${basedir}/fullhtml;
  • <outputType>TYPE</outputType> - analyzer report format (text, log, json, xml, tasklist, fullhtml, errorfile). Default value: json;
  • <threadsNum>NUMBER</threadsNum> - number of analysis threads. Default value: number of available processors;
  • <sourceTreeRoot>PATH</sourceTreeRoot> - a common directory root to source files, that will be used to generate an analyzer report with relative paths to the analyzed source files. The value is absent by default;
  • <enabledWarnings>V6XXX, ....</enabledWarnings> - list of enabled analyzer rules. When enabled rules are specified here, all other rules are considered to be enabled. The value is absent by default. When this option is absent, all of the analyzer rules are considered to be enabled (unless the additional disabledWarnings option is specified);
  • <disabledWarnings>V6XXX, ....</disabledWarnings> - list of disabled diagnostics. When disabled rules are specified here, all other rules are considered to be enabled. The value is absent by default. When this option is absent all of the analyzer rules are considered to be enabled (unless the additional enabledWarnings option is specified);
  • <exclude>PATH, ....</exclude> - list of files and/or directories which have to be excluded from the analysis (absolute or relative paths). The value is absent by default - all files will be analyzed unless the analyzeOnly option is provided;
  • <analyzeOnly>PATH, ....</analyzeOnly> - list of files and/or directories which have to be analyzed (absolute or relative paths). Default value: absent - all files will be analyzed unless the exclude option is provided;
  • <suppressBase>PATH</suppressBase> - path to a suppress file, containing suppressed analyzer messages, that will not be included in analyzer's report. You can add analyzer messages to a suppress file from the interface of PVS-Studio IDE plug-in for IntelliJ IDEA Default value: ${basedir}/.PVS-Studio/suppress_base.json;
  • <failOnWarnings>BOOLEAN</failOnWarnings> - abort a build, if the analyzer generates a warning. Default value: false;
  • <incremental>BOOLEAN</incremental> - enable incremental analysis (analysis will be performed for the modified files only). Default value: false;
  • <forceRebuild>BOOLEAN</forceRebuild> - flag that allows to forcibly rebuild the entire cached program metamodel containing information about its structure and type information. Default value: false;
  • <disableCache>BOOLEAN</disableCache> - flag that allows to disable cashing of the program metamodel. Default value: false;
  • <timeout>NUMBER</timeout> - timeout for analyzing a single file (in minutes). Default value: 10;
  • <verbose>BOOLEAN</verbose> - saving of temporary analyzer files (for example, containing a structure of analyzed project). Default value: false;
  • <javaPath>PATH</javaPath> - path to the java interpreter, which will run the analyzer core. Default value: java from the PATH environment variable;
  • <jvmArguments>FLAG, ....</jvmArguments> - additional JVM flags with which the analyzer core will be executed. Default value: -Xss64m;

Plugin for Gradle

For projects with the Gradle build system, you can use the pvsstudio-gradle-plugin plugin. To do this, you need to add the following to the build.gradle file:

buildscript {
  repositories {
    mavenCentral()
    maven {
      url uri('http://files.viva64.com/java/pvsstudio-maven-repository/')
    }
  }
  dependencies {
    classpath group: 'com.pvsstudio',
              name: 'pvsstudio-gradle-plugin',
              version: '7.02.32034'
  }
}
apply plugin: com.pvsstudio.PvsStudioGradlePlugin
pvsstudio {
  outputType = 'text'
  outputFile = 'path/to/output.txt'
}

After that, you can run the analysis:

$ ./gradlew pvsAnalyze

Entering license information

To enter the license information you can use the following command:

./gradlew pvsCredentials "-Ppvsstudio.username=USR" "-Ppvsstudio.serial=KEY"

After that, the license information will be saved in % APPDATA%/PVS-Studio-Java/PVS-Studio.lic in Windows OS or in ~/.config/PVS-Studio-Java/PVS-Studio.lic in macOS and Linux.

Configuration

The analyzer configuration is performed in the section "pvsstudio". A list of analyzer configurations is given below.

  • outputFile = "PATH" - path to the file with the analyzer report. Default value: $projectDir/PVS-Studio. Note: for a report in the 'fullhtml' format in outputFile it is necessary to specify a directory in which a folder will be created with the name 'fullhtml' containing the analyzer report. Default value: ${projectDir}/fullhtml;
  • outputType = "TYPE" - format of the analyzer report (text, log, json, xml, tasklist, fullhtml, errorfile). Default value: json;
  • threadsNum = NUMBER - number of analysis threads. The default value: number of available processors;
  • sourceTreeRoot = "PATH" - a common directory root to source files, that will be used to generate an analyzer report with relative paths to the analyzed source files. The value is absent by default;
  • enabledWarnings = ["V6XXX", ....] - list of enabled analyzer rules. When enabled rules are specified here, all other rules are considered to be enabled. The value is absent by default. When this option is absent, all of the analyzer rules are considered to be enabled (unless the additional disabledWarnings option is specified);
  • disabledWarnings = ["V6XXX", ....] - list of disabled diagnostics. When disabled rules are specified here, all other rules are considered to be enabled. The value is absent by default. When this option is absent all of the analyzer rules are considered to be enabled (unless the additional enabledWarnings option is specified);
  • exclude = ["PATH", ....] - list of files and/or directories which have to be excluded from the analysis (absolute or relative paths). The value is absent by default - all files will be analyzed unless the analyzeOnly option is provided;
  • analyzeOnly = ["PATH", ....] - list of files and/or directories which have to be analyzed (absolute or relative paths). Default value: absent - all files will be analyzed unless the exclude option is provided;
  • suppressBase = "PATH" - path to a suppress file, containing suppressed analyzer messages, that will not be included in analyzer's report. You can add analyzer messages to a suppress file from the interface of PVS-Studio IDE plug-in for IntelliJ IDEA Default value: $projectDir/.PVS-Studio/suppress_base.json;
  • failOnWarnings = BOOLEAN - abort a build, if the analyzer issued a certain warning. Default value: false;
  • incremental = BOOLEAN - enable incremental analysis (analysis will be performed for the modified files only). Default value: false;
  • forceRebuild = BOOLEAN - flag that allows to forcibly rebuild the entire cached program metamodel containing information about its structure and type information. Default value: false;
  • disableCache = BOOLEAN - flag that allows to disable cashing of the program metamodel. Default value: false;
  • timeout = NUMBER - timeout of one file analysis (in minutes). Default value: 10;
  • verbose = BOOLEAN - saving of temporary analyzer files (for example with a structure of the analyzed project). Default value: false;
  • javaPath = "PATH" - path to the java interpreter, which will run the analyzer core. Default value: java from the PATH environment variable;
  • jvmArguments = ["FLAG", ....] - - additional JVM flags with which the analyzer core will be executed. Default value: ["-Xss64m"];

Plugin for IntelliJ IDEA

The PVS-Studio Java analyzer can be also used as a plugin for IntelliJ IDEA. In this case, parsing of a project structure is performed by means of this IDE and the plugin provides a convenient graphic interface to work with the analyzer.

PVS-Studio plug-in for IDEA can be installed either from the official JetBrains plug-in repository, or from a repository on our site. Another way of the plugin and the analyzer core installation is the PVS-Studio installer for Windows. It is available on the download page.

The following instructions describe how to install the plugin from our repository.

1) File -> Settings -> Plugins

Picture 6

2) Manage Plugin Repositories

Picture 18

3) Add repository (http://files.viva64.com/java/pvsstudio-idea-plugins/updatePlugins.xml)

Picture 22

4) Install

Picture 23

Then you should enter license information.

1) Analyze -> PVS-Studio -> Settings

Picture 25

2) Registration tab

Picture 27

And finally, you can run the analysis of a current project:

Picture 29

Integration of PVS-Studio with Continuous Integration systems and SonarQube

Any of the following methods of integration of the analysis into a build system can be used for automated analysis in Continuous Integration systems. This can be performed in Jenkins, TeamCity and other CI systems by setting up automatic analysis launch and notification on the generated errors.

It is also possible to integrate PVS-Studio analyzer with the SonarQube continuous quality inspection system using the corresponding PVS-Studio plug-in. Installation instructions are available on this page: "Integration of PVS-Studio analysis results into SonarQube".

Using analyzer core directly

If none of the above methods of integration into a project is appropriate, you can use the analyzer core directly. You can download the analyzer core by the link (http://files.viva64.com/java/pvsstudio-cores/7.02.32034.zip) or using the PVS-Studio installer for Windows which is available on the download page.

The analyzer requires a collection of source files (or directories with source files) for analysis, and classpath information.

The set of source files for the analysis is specified using the -s flag and classpath is specified using the -e flag. In addition, using the --ext-file flag you can specify a file that lists all classpath inclusions, separated by pathSeparator (':' in Unix systems, and ';' in Windows).

All available analyzer core flags can be viewed by using the following command:

java -jar pvs-studio.jar --help

Examples of quick launch:

java -jar pvs-studio.jar -s A.java B.java C.java -e Lib1.jar Lib2.jar -j4 -o report.txt -O text

java -jar pvs-studio.jar -s src/main/java --ext-file classpath.txt -j4 -o report.txt -O text

Suppression of analyzer messages

There are several ways to suppress analyzer messages.

1. Using special comments:

void f() {
    int x = 01000; //-V6061
}

2. Using a special suppression file

The special suppression 'suppress' file can be generated PVS-Studio IDE plug-in for InlelliJ IDEA. Path to suppress file can be specified as a parameter to maven or gradle analyzer plug-ins, or it can be passed to as a parameter to the direct call of analyzer core.

Picture 35

When suppressing messages through IDEA, suppress file will be generated in the '.PVS-Studio' directory, which itself is located in the directory of a project that is currently opened in the IDE. The name of the suppress file will be suppress_base.json;

3. Using @SuppressWarnings(....) annotations

Analyzer can recognize several annotations and is able to skip warnings for the code that was already marked by such annotations. For example:

@SuppressWarnings("OctalInteger")
void f() {
    int x = 01000;
}

Common problems and their solutions

"GC overhead limit exceeded" occurs or analysis aborts by timeout

The insufficient memory problem can be solved by increasing the available amount of memory and stack.

Plugin for Maven:

<jvmArguments>-Xmx4096m, -Xss256m</jvmArguments>

Plugin for Gradle:

jvmArguments = ["-Xmx4096m", "-Xss256m"]

Plugin for IntelliJ IDEA:

1) Analyze -> PVS-Studio -> Settings

2) Environment tab -> JVM arguments

Picture 31

Typically, the default amount of memory may be insufficient when analyzing some generated code with a large number of nested constructs.

It's probably better to exclude that code from analysis (using exclude), to speed it up.

How to change Java executable to run the analyzer with?

The analyzer runs core with java from the PATH environment variable by default. If you need to run the analysis with some other java, you can specify it manually.

Plugin for Maven:

<javaPath>C:/Program Files/Java/jdk1.8.0_162/bin/java.exe</javaPath>

Plugin for Gradle:

javaPath = "C:/Program Files/Java/jdk1.8.0_162/bin/java.exe"

Plugin for IntelliJ IDEA:

1) Analyze -> PVS-Studio -> Settings

2) Environment tab -> Java executable

Picture 33

Unable to start the analysis (V00X errors occur)

If you are unable to run the analysis, please email us (support@viva64.com) and attach text files from the .PVS-Studio directory (located in the project directory).


Bugs Found

Checked Projects
344
Collected Errors
12 970