Integrating PVS-Studio Java into the Maven build system
- Integrating the PVS-Studio plugin into Maven
- Running the analysis
- Running the analysis without network access
- Configuration
- Updating PVS-Studio Java
PVS-Studio Java static analyzer consists of two main components: the core that performs analysis, the plugins for integrating the analyzer into build systems (Maven and Gradle), and IDEs (PVS-Studio for IntelliJ IDEA and Android Studio).
With the plugins, you can:
- run and configure the analyzer in a user-friendly interface;
- deploy the analyzer core in the system;
- collect and transfer the project structure data (the set of source files and the classpath) to the analyzer core.
Integrating the PVS-Studio plugin into Maven
To integrate the plugin, add the following code 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.34.87460</version>
<configuration>
<analyzer>
<outputType>text</outputType>
<outputFile>path/to/output.txt</outputFile>
<analysisMode>GA,OWASP</analysisMode>
</analyzer>
</configuration>
</plugin>
</plugins>
</build>
Running the analysis
Before running the analysis, enter the PVS-Studio license. To learn how to do this, please consult the documentation.
To run the analysis, execute the following command:
mvn pvsstudio:pvsAnalyze
In addition, you can incorporate the analysis into the project build cycle by adding the <execution> element:
<plugin>
<groupId>com.pvsstudio</groupId>
<artifactId>pvsstudio-maven-plugin</artifactId>
<version>7.34.87460</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>pvsAnalyze</goal>
</goals>
</execution>
</executions>
</plugin>
Please note: when analyzing a project, the plugin starts the Java analyzer core. When the analyzer core is started, it uses the same Java language version as the JDK. The java file from the JDK is used to start the Java analyzer core (the <javaPath> plugin setting). If you want to change the Java language version to be used in the analysis, use the java file from the JDK for that version to run the Java analyzer core.
Running the analysis without network access
For the plugin to work, you need to download its dependencies. If you work with the plugin on a system that does not have network access, create a local repository of the plugin dependencies. To do that, you may use maven-dependency-plugin.
Use this command to download the dependencies and prepare them for offline use:
mvn dependency:go-offline
Run this command from the directory that contains the pom.xml file (the project root directory). In this case, all the dependencies needed to build and analyze the project will be saved in the default local repository folder: %userprofile%/.m2/repository on Windows or ~/.m2/repository on Linux/macOS.
To save the offline repository to a different folder, use the maven.repo.local parameter. In this case, the command would look like as follows:
mvn dependency:go-offline -Dmaven.repo.local=/custom/path
To download the dependencies, you need to have a network connection while running this command. Internet access is no longer required to continue working.
The system must be installed the same Java core version as the plugin. You can learn how to install the Java analyzer core in this documentation.
Using the analyzer in this case is no different from its normal use. To prevent maven from downloading dependencies use the ‑‑offline(-o) flag. An example of a command to run an offline analysis using a user local repository:
mvn -o pvsstudio:pvsAnalyze -Dmaven.repo.local=/custom/path
Configuration
The <analyzer> block is used to configure the analyzer. The following is a list of analysis settings.
- <outputType>TYPE</outputType> — the format of the analyzer report (text, log, json, xml, tasklist, html, fullhtml, errorfile). The default value is json;
- <outputFile>PATH</outputFile> — the path to the report file where the analysis results are written. The file extension specified in this parameter does not affect the format of the content. The default value is ${basedir}/PVS-Studio + the format extension from the <outputType> setting. To get a report in the fullhtml format, specify the directory where a folder named fullhtml containing the analyzer report file (index.html) will be created. The default value is ${basedir}/fullhtml. Please note. Instead of the <outputFile> setting, it's better to use the PlogConverter (Windows) and plog-converter (Linux and macOS) console utilities. They enable you to convert the analyzer report to more formats (for example, SARIF). The utilities provide additional features: filtering warnings from the report, converting paths in the report from absolute to relative (and vice versa), getting data on the differences between reports, etc.;
- <threadsNum>NUMBER</threadsNum> — is used to set the number of threads to which the analysis will be parallelized. You can set value for this setting for the whole system in the global.json file. The default value is the number of available processors;
- <sourceTreeRoot>PATH</sourceTreeRoot> — the root part of the path that the analyzer uses to generate relative paths in diagnostic messages. By default, PVS-Studio shows absolute paths to the files where the analyzer found errors. With this setting, you can specify the root part of the path (path to the directory). The analyzer will automatically replace it with a special marker. The file path is replaced if it begins with the specified root path. You will be able to use the report with relative paths to view the analysis results in an environment with a different location of source files. For example, in different operating systems. The default value is absent;
- <analysisMode>GA, ....</analysisMode> — the list of enabled groups of warnings. Available groups: GA (general analysis diagnostics), OWASP (OWASP ASVS compliant diagnostics). <enabledWarnings>, <disabledWarnings>, and <additionalWarnings> have a higher priority than the <analysisMode> setting. That is, if a diagnostic group is disabled (or enabled), you can use these settings to enable (or disable) individual diagnostics during analysis. The default value is GA;
- <enabledWarnings>VXXXX, ....</enabledWarnings> — the list of enabled diagnostic rules. During the analysis, the analyzer uses only the diagnostics that are specified in this list. If the value is absent, all diagnostics are enabled unless a value is specified for <disabledWarnings>. The priority of the <enabledWarnings> setting is lower than <disabledWarnings> and <additionalWarnings> but higher than <analysisMode>. The default value is absent.
- <disabledWarnings>VXXXX, ....</disabledWarnings> — the list of disabled diagnostics. The diagnostics listed in this list are disabled during the analysis. If this setting is disabled, all diagnostics are enabled unless the <enabledWarnings> setting is set. The priority of the <disabledWarnings> setting is higher than <enabledWarnings> and <analysisMode> but lower than <additionalWarnings>. The default value is absent;
- <additionalWarnings>VXXXX, ....</additionalWarnings> — the list of diagnostic rules to be included in analysis, which are enabled by default. If a diagnostic is added to this list, its co-presence in the <enabledWarnings> and <disabledWarnings> lists is ignored. In addition, you can enable the diagnostic rule even if the diagnostic group to which it belongs is disabled (i.e. <analysisMode> does not contain this group). The <additionalWarnings> setting has a higher priority than the <enabledWarnings>, <disabledWarnings>, and <analysisMode> settings. The default value is absent;
- <exclude>PATH, ....</exclude> — the list of files and/or directories to be excluded from the analysis (absolute or relative paths are expanded relative to the project root directory). If this setting is disabled, all files are analyzed unless the <analyzeOnly> or <analyzeOnlyList> setting is enabled. The <exclude> setting has a higher priority than the <analyzeOnly> and <analyzeOnlyList> settings. The default value is absent;
- <analyzeOnly>PATH, ...</analyzeOnly> — the list of files and/or directories to be analyzed (absolute or relative paths that are expanded relative to the project root directory). You can also write these paths to a file line-by-line and pass the path to that file to the <analyzeOnlyList> setting. If this setting is disabled, all files will be analyzed unless the <exclude> or <analyzeOnlyList> setting is enabled. The <analyzeOnly> setting has a lower priority than the <exclude> setting. Files and/or directories passed in this setting are merged into a common list with files and/or directories from the <analyzeOnlyList> setting. The default value is absent;
- <analyzeOnlyList>PATH</analyzeOnlyList> — the analog of the <analyzeOnly> setting. The path to the text file which contains the list of paths to files/directories to be analyzed (each entry must be on a separate line). Relative (will be expanded relative to the project root directory) and absolute paths are supported. If this setting is disabled, all files will be analyzed unless the <exclude> or <analyzeOnly> setting is enabled. The <analyzeOnlyList> setting has a lower priority than the <exclude> setting. Files and/or directories read from the file specified in this setting are merged into a common list with files and/or directories from the <analyzeOnly> setting. The default value is absent;
- <suppressBase>PATH</suppressBase> — the path to the suppress file which contains suppressed warnings of the analyzer. Warnings from the suppress file will not be included in the report in any subsequent project checks. You can add analyzer messages to a suppress file from the interface of PVS-Studio plugin for IntelliJ IDEA and Android Studio. You can also use the pvsstudio:pvsSuppress task from the pvsstudio-maven-plugin. The default value is ${basedir}/.PVS-Studio/suppress_base.json;
- <failOnWarnings>BOOLEAN</failOnWarnings> — the flag used to terminate the pvsstudio:pvsAnalyze task with a failure if the analyzer has issued a warning. The flag allows you to monitor analyzer warnings in the analyzer report. Such behavior can be useful when you integrate the analyzer into CI/CD. The default value is false;
- <incremental>BOOLEAN</incremental> — the flag used to enable incremental analysis. In this mode, the analyzer checks only modified files. The default value is false;
- <forceRebuild>BOOLEAN</forceRebuild> — the flag used to force rebuild the entire cached metamodel of a program. The metamodel contains information about the program structure and data types. Rebuilding the project metamodel can be necessary when the analyzer version is updated or if the project metamodel is corrupted. When this setting is used, the incremental analysis mode is disabled (the <incremental> setting). The default value is false;
- <disableCache>BOOLEAN</disableCache> — the flag used to disable caching of the program metamodel. When the cache is disabled, the project model is not cached and is rebuilt each time. This flag can be useful when identifying the causes of analyzer errors. Disabling project metamodel caching also disables the incremental analysis (the <incremental> setting). The default value is false;
- <timeout>NUMBER</timeout> — the timeout for analyzing a file (in minutes). It enables you to increase or decrease the maximum amount of time taken to analyze one file. You can set value for this setting for the whole system in the global.json file. The default value is 10;
- <javaPath>PATH</javaPath> — specifies the path to the Java interpreter used to start the analyzer core. You can set value for this setting for the whole system in the global.json file. The source code files are analyzed using the Java language version corresponding to the JDK build which path is set in this parameter. By default, PVS-Studio uses the path from the PATH environment variable;
- <jvmArguments>FLAG, ....</jvmArguments> — additional JVM flags used to execute the analyzer core. This flag enables you to configure the JVM that runs the Java analyzer core. You can set value for this setting for the whole system in the global.json file. The default value is["-Xss64m"];
- <compatibility>BOOLEAN</compatibility> — the flag that enables the V6078 diagnostic rule that detects potential API compatibility issues between the selected Java SE versions. The V6078 diagnostic ensures that the JDK API you are using will not be modified or will not disappear in future versions of the JDK. The default value is false;
- <sourceJava>NUMBER</sourceJava> — the Java SE version that your application is developed on. This setting is used by the V6078 diagnostic rule if the <compatibility> setting is enabled. The minimum value is 8. The maximum value is 14;
- <targetJava>NUMBER</targetJava> — the Java SE version to be checked for compatibility with the API used in your application (<sourceJava>). This setting is used by the V6078 diagnostic rule if the <compatibility> setting is enabled. The minimum value is 8. The maximum value is 14;
- <excludePackages>"PACK", ....</excludePackages> — packages to be excluded from the compatibility analysis (the V6078 diagnostic). The V6078 diagnostic rule uses this setting if <compatibility> is enabled. The default value is absent.
You can define the analyzer settings via the command line when running the analysis. The definition format:
-Dpvsstudio.<nameSingleParam>=value
-Dpvsstudio.<nameMultipleParam>=value1;value2;value3
Example:
mvn pvsstudio:pvsAnalyze -Dpvsstudio.outputType=text
-Dpvsstudio.outputFile=path/to/output.txt
-Dpvsstudio.disabledWarnings=V6001;V6002;V6003
Please note that parameters explicitly passed via the command line have the highest priority.
How to change the Java version to run the analyzer
By default, the analyzer starts the core with java from the PATH environment variable. If you need to run the analysis with some other version, you can set it manually. To do this, specify the path to java from the JDK in the <javaPath> analyzer setting. The version of this JDK (version of Java language) will be used when analyzing the source code of the project:
....
<javaPath>C:/Program Files/Java/jdk19.0.5/bin/java</javaPath>
....
Updating PVS-Studio Java
To update pvsstudio-maven-plugin, change the version of the plugin in the pom.xml file.
Using a proxy
When using a proxy, it is necessary to enter your login and password to correctly load the analyzer core.
To do this, you can use the following arguments:
- -Dhttp.proxyUser, -Dhttp.proxyPassword
- -Dhttps.proxyUser, -Dhttps.proxyPassword
- -Djava.net.socks.username, -Djava.net.socks.password
- -Dftp.proxyUser, -Dftp.proxyPassword
You can use this command to run the analysis via the plugin for Maven that uses a proxy:
mvn pvsstudio:pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"