Contents
Integrating PVS-Studio Java into the Gradle build system
- Integrating the PVS-Studio plugin into Gradle
- 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 Gradle
To integrate the plugin, add the following code to the build.gradle script:
buildscript {
repositories {
mavenCentral()
maven {
url uri('https://files.pvs-studio.com/java/pvsstudio-maven-repository/')
}
}
dependencies {
classpath 'com.pvsstudio:pvsstudio-gradle-plugin:latest.release'
}
}
apply plugin: com.pvsstudio.PvsStudioGradlePlugin
pvsstudio {
outputType = 'text'
outputFile = 'path/to/output.txt'
analysisMode = ['GA', 'OWASP']
}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:
./gradlew pvsAnalyzePlease 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 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.
Use this command to download the dependencies and prepare them for offline use:
./gradlew build --refresh-dependenciesRun this command from the directory that contains the build.gradle 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%/.gradle/caches/modules-2/files-2.1 on Windows or ~/.gradle/caches/modules-2/files-2.1 on Linux/macOS.
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 gradle from downloading dependencies use the ‑‑offline flag. This command runs the analysis in offline mode:
./gradlew pvsAnalyze –-offlineConfiguration
The following is a list of analysis settings you can specify in the pvsstudio section of the build.gradle file:
- outputType = "TYPE" — the format of the analyzer report (text, log, json, xml, tasklist, html, fullhtml, errorfile). The default value is json;
- outputFile = "PATH" — 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 $projectDir/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 $projectDir/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 — 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" — 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", ....] — 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 this 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", ....] — 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", ....] — 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 analyzeOnly or analyzeOnlyList 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", ....] — 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", ....] — 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", ....] — 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" — 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 analyzeOnlyList setting. The default value is absent.
- suppressBase = "PATH" — 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 pvsSuppress task from the pvsstudio-gradle-plugin plugin. The default value is $projectDir/.PVS-Studio/suppress_base.json;
- failOnWarnings = BOOLEAN — the flag used to terminate the 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 — the flag used to enable incremental analysis. In this mode, the analyzer checks only modified files. The default value is false;
- forceRebuild = BOOLEAN — 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 — 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 — 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" — 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", ....] — 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 — 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 — 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 — 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", ....] — 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:
-Ppvsstudio.<nameSingleParam>=value
-Ppvsstudio.<nameMultipleParam>=value1;value2;value3Example:
./gradlew pvsAnalyze -Ppvsstudio.outputType=text
-Ppvsstudio.outputFile=path/to/output.txt
-Ppvsstudio.disabledWarnings=V6001;V6002;V6003Please 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"
....Updating PVS-Studio Java
By using latest.release as the plugin version in the build.gradle file, you will always have the latest version of PVS-Studio for analysis.
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 Gradle that uses a proxy:
./gradlew pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"Was this page helpful?
