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 installed 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.10.43221</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.10.43221</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> - 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, html, fullhtml, errorfile). Default value: json;
  • <threadsNum>NUMBER</threadsNum> - number of analysis threads. Default value: number of available processors;
  • <sourceTreeRoot>PATH</sourceTreeRoot> - root part of the path which the analyzer will use to generate relative paths in diagnostic messages. 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 disabled. 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 analyzer rules. 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. When this option is absent, all files will be analyzed (unless the additional analyzeOnly option is specified);
  • <analyzeOnly>PATH, ....</analyzeOnly> - list of files and/or directories which have to be analyzed (absolute or relative paths). The value is absent by default. When this option is absent, all files will be analyzed (unless the additional exclude option is specified);
  • <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> - flag that allows you to end a task with a failure, 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> - flag that allows saving temporary analyzer files for its diagnostic. 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;
  • <compatibility>BOOLEAN</compatibility> - flag that allows you to activate the V6078 diagnostic rule that detects potential API compatibility issues between selected Java SE versions;
  • <sourceJava>NUMBER</sourceJava> - Java SE version that your application is developed on;
  • <targetJava>NUMBER</targetJava> - Java SE version that has to be checked for compatibility with the API used in your application (sourceJava);
  • <excludePackages>"PACK", ....</excludePackages> - packages that you want to exclude from compatibility analysis.

Configuration via the command line

In addition to configuring the <analyzer > block, in pom.xml you can define the analyzer settings via the command line. Definition format:

-Ppvsstudio.<nameSingleParam>=value 
-Ppvsstudio.<nameMultipleParam>=value1;value2;value3

Example:

mvn pvsstudio:pvsAnalyze -Ppvsstudio.outputType=text
-Ppvsstudio.outputFile=path/to/output.txt
-Ppvsstudio.disabledWarnings=V6001;V6002;V6003

Important! When defining parameters via the command line, keep in mind that the parameters explicitly specified in the command line when running the analysis take precedence over the parameters specified when configuring the <analyzer > block in pom.xml.

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.10.43221'
  }
}

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, html, fullhtml, errorfile). Default value: json;
  • threadsNum = NUMBER - number of analysis threads. The default value: number of available processors;
  • sourceTreeRoot = "PATH" – root part of the path that the analyzer will use to generate relative paths in diagnostic messages. 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 disabled. 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 analyzer rules. 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. When this option is absent, all files will be analyzed (unless the additional analyzeOnly option is specified);
  • analyzeOnly = ["PATH", ....] – list of files and/or directories which have to be analyzed (absolute or relative paths). The value is absent by default. When this option is absent, all files will be analyzed (unless the additional exclude option is specified);
  • 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 - flag that allows you to end a pvsAnalyze task with a failure, 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 – flag that allows saving temporary analyzer files for its diagnostic. 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"];
  • compatibility = BOOLEAN - flag that allows you to activate the V6078 diagnostic rule that detects potential API compatibility issues between selected Java SE versions;
  • sourceJava = NUMBER - Java SE version that your application is developed on;
  • targetJava = NUMBER - Java SE version that has to be checked for compatibility with the API used in your application (sourceJava);
  • excludePackages = ["PACK", ....] - packages that you want to exclude from compatibility analysis.

Configuration via the command line

In addition to configuring the 'pvsstudio' block, in build.gradle, you can define the analyzer settings via the command line. Definition format:

-Dpvsstudio.<nameSingleParam>=value 
-Dpvsstudio.<nameMultipleParam>=value1;value2;value3

Example:

./gradlew pvsAnalyze -Dpvsstudio.outputType=text
-Dpvsstudio.outputFile=path/to/output.txt
-Dpvsstudio.disabledWarnings=V6001;V6002;V6003

Important! When defining parameters via the command line, keep in mind that the parameters explicitly specified in the command line when running the analysis take precedence over the parameters specified when configuring the 'pvsstudio' block in build.gradle.

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

https://import.viva64.com/docx/manual/PVS-Studio_Java/image1.png

2) Manage Plugin Repositories

https://import.viva64.com/docx/manual/PVS-Studio_Java/image3.png

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

https://import.viva64.com/docx/manual/PVS-Studio_Java/image4.png

4) Install

https://import.viva64.com/docx/manual/PVS-Studio_Java/image5.png

Then you should enter license information.

1) Analyze -> PVS-Studio -> Settings

https://import.viva64.com/docx/manual/PVS-Studio_Java/image7.png

2) Registration tab

https://import.viva64.com/docx/manual/PVS-Studio_Java/image9.png

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

https://import.viva64.com/docx/manual/PVS-Studio_Java/image11.png

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.10.43221.zip) or using the PVS-Studio installer for Windows which is available on the download page.

If you install the analyzer via the PVS-Studio installer for Windows, the core will be downloaded to %APPDATA%/PVS-Studio-Java/7.10.43221.

To get information about all available arguments of the analyzer, you must run the command '--help':

java -jar pvs-studio.jar --help

Let's look at the main arguments of the analyzer:

  • --src (-s) - set of *.java files or directories for analysis. If you need to list multiple files/directories, use ' ' as the separator. Example: --src "path/to/file1" "path/to/file2" "path/to/dir";
  • --ext (-e) - definition of classpath (.jar/.class files, directories). If you need to list multiple classpath entities, use ' ' as the separator. Example: --ext "path/to/file.jar" "path/to/dirJars";
  • --ext-file - path to the file with classpath. pathSeparator is used as a classpath separator (separator ':' - in Unix systems and ';' -in Windows);
  • --output-file (-o) - path to the file where the analysis results will be written. Default value: {currentDir}/PVS-Studio.json. Note: to get a report in the 'fullhtml' format in outputFile, specify the directory where the directory named 'fullhtml' with the analyzer report will be created. Default value: {currentDir}/fullhtml;
  • --output-type (-O) - output format (text, log, json, xml, tasklist, html, fullhtml, errorfile);
  • --incremental (-i) - analysis of only modified files;
  • --threads (-j) - number of analysis threads. Default value: number of available processors;
  • --cfg (-c) - configuration file for running the core.
  • --help (-h) – printing help information to the screen.
  • --sourcetree-root - root part of the path that the analyzer will use to generate relative paths in diagnostic messages. There's no default value;
  • --force-rebuild - flag that allows you to forcibly rebuild the entire cached metamodel of the program containing information about its structure and data types;
  • --disable-cache - flag that allows you to disable caching of the program's metamodel;
  • --exclude - the list of files and/or directories which have to be excluded from the analysis (absolute or relative paths). If you need to list multiple files/directories, use ' ' as the separator. Example: --exclude "path/to/file1" "path/to/file2" "path/to/dir";
  • --include - list of files and/or directories which have to be analyzed (absolute or relative paths). If you need to list multiple files/directories, use ' ' as the separator. Example: --include "path/to/file1" "path/to/file2" "path/to/dir";
  • --disable-warnings - list of disabled diagnostics. When setting disabled diagnostics, those not specified here will be considered enabled. If you need to list several rules, use ' ' as the separator. Example: --disable-warnings V6001 V6002 V6003;
  • --enable-warnings - list of active diagnostics. When setting enabled diagnostics, those not specified here will be disabled. If you need to list several rules, use ' ' as the separator. Example: --enable-warnings V6001 V6002 V6003;
  • --suppress-base - path to the suppress file containing suppressed analyzer messages that will not be issued in the analysis report;
  • --timeout - timeout of one file analysis (in minutes). Default value:10;
  • --username - user's name;
  • serial-number - license serial number;
  • license-path - path to the license file. Note: if 'username 'and' serial-number ' are empty, the analyzer will check the license information in %APPDATA%/PVS-Studio-Java/PVS-Studio.lic in OS Windows or in ~/.config/PVS-Studio-Java/PVS-Studio.lic in macOS and Linux.
  • --compatibility - flag that enables the V6078 diagnostic rule that detects potential API compatibility issues between selected Java SE versions;
  • --source-java - Java SE version that your application is developed on;
  • --target-java - Java SE version that has to be checked for compatibility with the API used in your application (--source-java);
  • --exclude-packages - packages that you want to exclude from compatibility analysis. If you need to list multiple packages, use ' ' as the separator. Example: --exclude-packages "package1" "package2" "package3";
  • --fail-on-warnings - flag that allows you to return non-null code if the analyzer has issued a warning;
  • --convert - running in conversion mode. Modes: 'toFullhtml' converts a report with warnings to the 'fullhtml' format, 'toSuppress' converts a report with warnings to the suppression file format;
  • --src-convert - path to the analyzer report with warnings (*. json);
  • --dst-convert - conversion destination (file for 'toSuppress', directory for 'toFullhtml');

The analyzer requires a collection of source files (or directories with source files) for analysis, and classpath information in order to build the program metamodel correctly.

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 -username name someName –serial-number someSerial

java -jar pvs-studio.jar -s src/main/java --ext-file classpath.txt -j4 
-o report.txt -O text --license-path PVS-Studio.lic

To avoid writing all the necessary parameters in the command line every time, you can use the '--cfg' parameter. To do this, create a file with the following contents:

{
  "src": ["A.java", "B.java", "C.java"],
  "threads": 4,
  "output-file": "report.txt",
  "output-type": "text",
  "username": "someName",
  "serial-number": "someSerial"
  ....
}

Or

{
  "src": ["src/main/java"],
  "threads": 4,
  "ext-file": "classpath.txt", 
  "output-file": "report.txt",
  "output-type": "text",
  "license-path": "PVS-Studio.lic"
  ....
}

In this case, running the analyzer will narrow down to the following line:

java -jar pvs-studio.jar –-cfg cfg.json

Important! When you use the configuration file, keep in mind that arguments explicitly written in the command line, take precedence when running the analyzer.

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".

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.

https://import.viva64.com/docx/manual/PVS-Studio_Java/image13.png

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

https://import.viva64.com/docx/manual/PVS-Studio_Java/image14.png

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

https://import.viva64.com/docx/manual/PVS-Studio_Java/image14.png

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
412
Collected Errors
14 132
This website uses cookies and other technology to provide you a more personalized experience. By continuing the view of our web-pages you accept the terms of using these files. If you don't want your personal data to be processed, please, leave this site. Learn More →
Accept