Contents
How to run PVS-Studio Java
- System requirements
- Plugin for Maven
- Plugin for Gradle
- Plugin for IntelliJ IDEA
- Using analyzer core directly
- Integration of PVS-Studio with continuous integration systems and SonarQube
- Suppression of analyzer messages
- View the analyzer's most interesting warnings
- Updating PVS-Studio Java
- Common problems and their solutions
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>https://files.pvs-studio.com/java/pvsstudio-maven-repository/</url>
</pluginRepository>
</pluginRepositories>
<build>
<plugins>
<plugin>
<groupId>com.pvsstudio</groupId>
<artifactId>pvsstudio-maven-plugin</artifactId>
<version>7.23.69221</version>
<configuration>
<analyzer>
<outputType>text</outputType>
<outputFile>path/to/output.txt</outputFile>
</analyzer>
</configuration>
</plugin>
</plugins>
</build>Then you need to enter the license in the way described in the documentation. After that, you can run the analysis:
mvn pvsstudio:pvsAnalyzeIn 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.23.69221</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>pvsAnalyze</goal>
</goals>
</execution>
</executions>
</plugin>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;
- <analysisMode>GA, ....</analysisMode> - list of active groups of analyzer rules. The available groups are GA (general analysis rule set), OWASP (rule set according to OWASP ASVS). Default value: GA;
- <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);
- <additionalWarnings>V6XXX, ....</additionalWarnings> - list of analyzer rules which are disabled by default but should be included in analysis. The value is absent by default;
- <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);
- <analyzeOnlyList>PATH</analyzeOnlyList> - path to the text file containing a list of paths to files and/or directories for analysis (each entry must be on a separate line). Relative and absolute paths are supported. This parameter complements the list obtained from 'analyzeOnly'. There is no default value;
- <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:
-Dpvsstudio.<nameSingleParam>=value
-Dpvsstudio.<nameMultipleParam>=value1;value2;value3Example:
mvn pvsstudio:pvsAnalyze -Dpvsstudio.outputType=text
-Dpvsstudio.outputFile=path/to/output.txt
-Dpvsstudio.disabledWarnings=V6001;V6002;V6003Important! 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('https://files.pvs-studio.com/java/pvsstudio-maven-repository/')
}
}
dependencies {
classpath group: 'com.pvsstudio',
name: 'pvsstudio-gradle-plugin',
version: '7.23.69221'
}
}
apply plugin: com.pvsstudio.PvsStudioGradlePlugin
pvsstudio {
outputType = 'text'
outputFile = 'path/to/output.txt'
}Then you need to enter the license in the way described in the documentation. After that, you can run the analysis:
./gradlew pvsAnalyzeConfiguration
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;
- analysisMode = ["GA", ....] - list of active groups of analyzer rules. The available groups are GA (general analysis rule set), OWASP (rule set according to OWASP ASVS). Default value: GA;
- 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);
- additionalWarnings = ["V6XXX", ....] – list of analyzer rules which are disabled by default but should be included in analysis. The value is absent by default;
- 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);
- analyzeOnlyList = "PATH" - path to the text file containing a list of paths to files and/or directories for analysis (each entry must be on a separate line). Relative and absolute paths are supported. This parameter complements the list obtained from 'analyzeOnly'. There is no default value;
- 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:
-Ppvsstudio.<nameSingleParam>=value
-Ppvsstudio.<nameMultipleParam>=value1;value2;value3Example:
./gradlew pvsAnalyze -Ppvsstudio.outputType=text
-Ppvsstudio.outputFile=path/to/output.txt
-Ppvsstudio.disabledWarnings=V6001;V6002;V6003Important! 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 plugin for IDEA can be installed either from the official JetBrains plugin 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
2) Manage Plugin Repositories
3) Add repository (https://files.pvs-studio.com/java/pvsstudio-idea-plugins/updatePlugins.xml)
4) Install
Then you should enter license information. You can read more about entering the license in the documentation.
And finally, you can run the analysis of a current project:
Keyboard shortcuts in the PVS-Studio plugin for IntelliJ IDEA
The PVS-Studio plugin for IntelliJ IDEA has the analysis result window. It has a dropdown menu that appears when you right-click on the analysis result window:
Some of these actions have keyboard shortcuts. Thus, you can perform them without using a mouse.
The arrow keys for navigating the analyzer's warnings also have shortcuts:
- move to the next message: Alt + ];
- move to the previous message: Alt + [.
Using shortcuts is helpful, since they speed up the analysis result processing. You can set and customize the shortcuts in settings: File -> Settings -> Keymap. To find shortcuts faster, enter 'PVS-Studio' in the search field of the Keymap window.
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 (https://files.pvs-studio.com/java/pvsstudio-cores/7.23.69221.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.23.69221.
To get information about all available arguments of the analyzer, you must run the command '--help':
java -jar pvs-studio.jar --helpLet'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";
- --analyze-only - 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";
- --analyze-only-list - path to the text file containing a list of paths to files and/or directories for analysis (each entry must be on a separate line). Relative and absolute paths are supported. This parameter complements the list obtained from 'analyzeOnly'. There is no default value;
- --analysis-mode - list of active groups of analyzer rules. The available groups are GA (general analysis rule set), OWASP (rule set according to OWASP ASVS). If you need to list several groups, use ' ' as the separator. Example: --analysis-mode GA OWASP;
- --disabled-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: --disabled-warnings V6001 V6002 V6003;
- --enabled-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: --enabled-warnings V6001 V6002 V6003;
- --additional-warnings - list of analyzer rules which are disabled by default but should be included in analysis. If you need to list several rules, use ' ' as the separator. Example: --additional-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.licTo 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.jsonImportant! 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.
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
The analyzer can recognize several annotations. It would skip warnings for the code that was already marked by such annotations. For example:
@SuppressWarnings("OctalInteger")
void f() {
int x = 01000;
}View the analyzer's most interesting warnings
If you are new to the static analysis tool and would like to know what it can do, you can use the Best Warnings mechanism. This mechanism will show you the most important and reliable warnings.
To check out the analyzer's most interesting warnings, click on the 'Best' button, as shown in the screenshot below:
After that, the table with the results of the analysis will show maximum of ten of the most critical warnings of the analyzer.
Updating PVS-Studio Java
Plugin for Maven
To update pvsstudio-maven-plugin, you need to change the plugin version in the file pom.xml. The current version of the plugin: 7.23.69221.
<build>
<plugins>
<plugin>
<groupId>com.pvsstudio</groupId>
<artifactId>pvsstudio-maven-plugin</artifactId>
<version>7.23.69221</version>
<configuration>
<analyzer>
<outputType>text</outputType>
<outputFile>path/to/output.txt</outputFile>
</analyzer>
</configuration>
</plugin>
</plugins>
</build>Plugin for Gradle
To update pvsstudio-gradle-plugin, you need to change the plugin version in the file pom.xml. The current version of the plugin: 7.23.69221.
buildscript {
repositories {
mavenCentral()
maven {
url uri('https://files.pvs-studio.com/java/pvsstudio-maven-repository/')
}
}
dependencies {
classpath 'com.pvsstudio:pvsstudio-gradle-plugin:7.23.69221'
}
}Plugin for IntelliJ IDEA
If a PVS-Studio update is available, a message about it will be displayed in the report when the analysis is started.
To update the plugin, open the plugin settings window File -> Settings -> Plugins, find the PVS-Studio for IDEA and Android Studio plugin in the Installed list, click Update button and restart the IDE.
Proxy usage
If you use a proxy, you must specify a username and password to download or update the core. This can be done via arguments:
- -Dhttp.proxyUser, -Dhttp.proxyPassword
- -Dhttps.proxyUser, -Dhttps.proxyPassword
- -Djava.net.socks.username, -Djava.net.socks.password
- -Dftp.proxyUser, -Dftp.proxyPassword
The command to run the analysis through the plugin for Maven with a proxy:
mvn pvsstudio:pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"The command to run the analysis through the plugin for Gradle with a proxy:
./gradlew pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"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) Tools -> PVS-Studio -> Settings
2) Environment tab -> JVM arguments
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) Tools -> PVS-Studio -> Settings
2) Environment tab -> Java executable
Unable to start the analysis (V00X errors occur)
If you are unable to run the analysis, please contact our support and attach text files from the .PVS-Studio directory (located in the project directory).