# Integrating PVS\-Studio Java into the Gradle build system

PVS\-Studio Java static analyzer consists of two main components: [the analysis core](https://pvs-studio.com/en/docs/manual/6703/) and the plugins for integration the analyzer into build systems \([Maven](https://pvs-studio.com/en/docs/manual/6705/) and Gradle\) and IDEs \([IntelliJ IDEA and Android Studio](https://pvs-studio.com/en/docs/manual/6704/)\)\.

Plugins have the following features:

* run and configure the analyzer in a user\-friendly interface;
* deploy the analyzer core in the system;
* collect and pass the project structure data \(the set of source files and the classpath\) to the analyzer core\.

## How to integrate PVS\-Studio plugin into Gradle

To integrate the plugin using the Groovy DSL, add the following code to the `build.gradle` script:

```cpp
buildscript {
  repositories {
    mavenCentral()
    maven {
      url uri('https://wcdn.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 = '.PVS-Studio/report.txt'
  analysisMode = ['GA', 'OWASP']
}
```

To integrate the plugin with the Kotlin DSL, add the following code to the `build.gradle.kts` script:

```cpp
import com.pvsstudio.WarningGroup

buildscript {
  repositories {
    mavenCentral()
    maven {
      url = uri("https://wcdn.pvs-studio.com/java/pvsstudio-maven-repository/")
    }
  }
  dependencies {
    classpath("com.pvsstudio:pvsstudio-gradle-plugin:latest.release")
  }
}

apply<com.pvsstudio.PvsStudioGradlePlugin>()

extensions.configure<com.pvsstudio.AnalyzerConfig>("pvsstudio") {
  outputType = "text"
  outputFile = ".PVS-Studio/output.txt"
  analysisMode = setOf(WarningGroup.GA, WarningGroup.OWASP)
}
```

## How to run the analysis

> Before running the analysis, enter the PVS\-Studio license\. To learn how to do this, please consult the [documentation](https://pvs-studio.com/en/docs/manual/0046/#PvsStudioJava)\.

To run the analysis, execute the following command:

```cpp
./gradlew pvsAnalyze
```

**Note\.** When analyzing a project, the plugin runs the [Java analyzer core](https://pvs-studio.com/en/docs/manual/6703/), which uses the Java version from the `PATH` environment variable by default\. You can set a different version by configuring the `javaPath` plugin\. The **Configuration** section below describes this in detail\.

## How to run the analysis without network access

To run the plugin, you need to download its dependencies\. If you work with the plugin on a system that without network access, create a local repository containing the plugin dependencies\. 

Use this command to download the dependencies and prepare them for offline use:

```cpp
./gradlew build --refresh-dependencies
```

Run 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 are saved in the default local repository folder: 

* **on Windows**: `%userprofile%/.gradle/caches/modules-2/files-2.1`
* **on Linux or macOS**: `~/.gradle/caches/modules-2/files-2.1`\. 

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](https://pvs-studio.com/en/docs/manual/6703/#java_core_install)\.

The analyzer is used the same way as in standard scenarios\. To prevent Gradle from downloading dependencies, use the `--offline` flag\. This command runs the analysis in offline mode:

```cpp
./gradlew pvsAnalyze –-offline
```

## Configuration

Here is a list of analysis settings you can specify in the `pvsstudio` section of the `build.gradle` \(for Groovy DSL\) or ` build.gradle.kts` file \(for Kotlin DSL\):

* `additionalWarnings = ["VXXXX", ....]` \(Groovy\) / `setOf("VXXXX", ....)` \(Kotlin\) specifies a list of diagnostic rules that should be additionally included in the analysis\. It has a higher priority than `enabledWarnings`, `disabledWarnings`, and `analysisMode`\. Default value: not set\.
* `analysisMode = ["GA", ....]` \(Groovy\) / `setOf(WarningMode.GA, ....)` \(Kotlin\) specifies a list of enabled warning groups\. This setting has lower priority than `--enabled-warnings`, `--disabled-warnings`, and `--additional-warnings`\. Default value: `GA`\. Available groups:
  * `[GA](https://pvs-studio.com/en/docs/warnings/#GeneralAnalysisJAVA)` \(general analysis diagnostic rules\);
  *  `[OWASP](https://pvs-studio.com/en/pvs-studio/sast/owasp/#java)` \(rules based on [OWASP Top Ten](https://pvs-studio.com/en/pvs-studio/sast/owasptopten/) and [OWASP ASVS](https://pvs-studio.com/en/pvs-studio/sast/owasp/)\)\. 
* `analyzeOnly = ["PATH", ....]` \(Groovy\) / `setOf("PATH", ....)` \(Kotlin\) specifies a list of files and/or directories to be analyzed\. Relative \(will be expanded relative to the working directory\) and absolute paths are supported\. These passed files and/or directories are merged with those specified in `--analyze-only-list`\. If not set, all files are analyzed\. This setting has lower priority than `exclude`\. Default value: not set\.
* `analyzeOnlyList = "PATH"` \(Groovy/Kotlin\) specifies a path to a text file with a list of files and/or directories to be analyzed—each entry must be on a separate line\. Relative \(will be expanded relative to the working directory\) and absolute paths are supported\. The files and/or directories from this file are merged with those specified in `analyzeOnly`\. This setting has a lower priority than `exclude`\. Default value: not set\.
* `disableCache = BOOLEAN` \(Groovy/Kotlin\) disables caching of the program metamodel\. When the cache is disabled, the project model is not cached and is rebuilt each run\. Disabling caching also disables [incremental](https://pvs-studio.com/en/docs/manual/0024/) analysis even if the `incremental` setting is specified\. Default value: `false`\.
* `disabledWarnings = ["VXXXX", ....]` \(Groovy\) / `setOf("VXXX", ....)` \(Kotlin\) specifies a list of diagnostic rules to be excluded from analysis\. If not set, all rules are enabled\. This setting has higher priority than `enabledWarnings` and `analysisMode`, but lower priority than `--additionalWarnings`\. Default value: not set\.
* `enabledWarnings = ["VXXXX", ....]` \(Groovy\) / `setOf("VXXXX", ....)` \(Kotlin\) specifies a list of diagnostic rules to be applied during analysis\. Only the listed rules are used\. This setting has lower priority than `disabledWarnings` and `additionalWarnings`, but higher priority than `analysisMode`\. Default value: not set\.
* `exclude = ["PATH", ....]` \(Groovy\) / `setOf("PATH", ....)` \(Kotlin\) specifies a list of files and/or directories to be excluded from analysis\. Relative \(will be expanded relative to the working directory\) and absolute paths are supported\. The setting has a higher priority than `analyzeOnly` and `analyzeOnlyList`\. Default value: not set\. Multiple entries are separated by spaces\.
* `failOnWarnings = BOOLEAN` \(Groovy/Kotlin\) returns a non\-zero exit code if at least one warning is issued\. This behavior can be useful when [integrating into CI/CD](https://pvs-studio.com/en/docs/#IDF1BF21914C)\. Default value: `false`;
* `forceRebuild = BOOLEAN` \(Groovy/Kotlin\) forces rebuild the entire cached program metamodel\. Enabling this option disables the [incremental analysis](https://pvs-studio.com/en/docs/manual/0024/) mode even if the `incremental` settings is specified\. Default value: `false`\.
* `incremental = BOOLEAN` \(Groovy/Kotlin\) enables [incremental](https://pvs-studio.com/en/docs/manual/0024/) analysis\. In this mode, the analyzer checks only modified files\. Default value: `false`\.
* `javaPath = "PATH"` \(Groovy/Kotlin\) specifies a path to the Java executable file that is used to run the analyzer core\. This setting can be configured system\-wide in the [`global.json`](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file) file\. If the `javaPath` is not used, PVS\-Studio attempts to use the `PATH` environment variable\.
* `jvmArguments = ["FLAG", ....]` \(Groovy\) / `setOf("FLAG", ....)` \(Kotlin\) specifies additional JVM arguments used to run the analyzer core\. This flag enables configuring the JVM that runs the Java analyzer core\. You can set value for this setting for the whole system in the `[global.json](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file)` file\. Default value: `["-Xss64m"]`\.
* `licensePath = "PATH"` \(Groovy/Kotlin\) specifies a path to the license file\. Available file extensions are `.xml` and `.lic`\. Default values are: 
  * **Windows**: `%APPDATA%/PVS-Studio/Settings.xml`
  * **macOS/Linux**: `~/.config/PVS-Studio/PVS-Studio.lic`\.
* `logging = "LEVEL"` \(Groovy/Kotlin\) specifies the logging level when starting the analysis\. When enabled, log files are created for the current run in the `.PVS-Studio/logs` subdirectory relative where Java analyzer is currently running\. Default value: `OFF`\. Available values are: 
  * `OFF`
  * `ERROR`
  * `WARN`
  * `INFO`
  * `DEBUG`
  * `TRACE`
  * `ALL`\.
* `outputFile = "PATH"` \(Groovy/Kotlin\) specifies a path to the analyzer report file\. The report format does not depend on the file extension specified in the parameter\. Default value: `$projectDir/PVS-Studio` \+ the format extension defined by `outputType`\. To generate a report in the `.fullhtml` format, specify the directory where the `fullhtml` subdirectory is created and contained the analyzer report file \(`index.html`\)\. Default value: `$projectDir/fullhtml`\. **Note\. **It is recommended to use [PlogConverter \(Windows\)](https://pvs-studio.com/en/docs/manual/0038/#PlogConverter) and [plog\-converter \(Linux and macOS\)](https://pvs-studio.com/en/docs/manual/0038/#plog-converter) instead of `outputFile`_\. _They enable converting 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\), comparing reports, etc\.
* `outputType = "TYPE"` \(Groovy/Kotlin\) specifies the analyzer report format\. Default value: `json`\. Available values are:
  * `text`
  * `log`
  * `json`
  * `xml`
  * `tasklist`
  * `html`
  * `fullhtml`
  * `errorfile`\. 
* `securityRelatedIssues = BOOLEAN` \(Groovy/Kotlin\) tags warnings related to potential security issues with additional mark up in the `SAST` field in the analyzer output\. Default value: `false`\.
* `sourceTreeRoot = "PATH"` \(Groovy/Kotlin\) specifies the root path [used](https://pvs-studio.com/en/docs/manual/0027/) by the analyzer to generate relative paths in the report\. Default value: not set\.
* `suppressBase = "PATH"` \(Groovy/Kotlin\) specifies a path to the [suppress file](https://pvs-studio.com/en/docs/manual/0032/) with suppressed warnings\. These warnings are excluded from future analysis reports\. Default value: `./.PVS-Studio/suppress_base.json`\.
* `threadsNum = NUMBER` \(Groovy/Kotlin\) specifies the number of analysis threads\. This setting can be configured system\-wide in the [`global.json`](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file) file\. Default value: _the_ _number of available logical processors\._
* `timeout = NUMBER` \(Groovy/Kotlin\) specifies the timeout for analyzing a file \(in minutes\)\. This setting can be configured globally in the [`global.json`](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file) file\. Default value: `10`\.
* `compatibility = BOOLEAN` \(Groovy/Kotlin\) enables the [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule, which detects potential API compatibility issues between selected Java SE versions\. Default value: `false`\.
* `excludePackages = ["PACK", ....]` \(Groovy\) / `setOf("PACK", ....)` \(Kotlin\) specifies packages to be excluded from compatibility analysis\. The [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule uses this setting if the `compatibility` setting is enabled\.
* `sourceJava = NUMBER` \(Groovy/Kotlin\) specifies the Java SE version used to develop the application\. The [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule uses this setting if the `compatibility` setting is enabled\. Minimum value: `8`\. Maximum value: `14`\.
* `targetJava = NUMBER` \(Groovy/Kotlin\) specifies the Java SE version against which the API used in the application \(`sourceJava`\) is checked for compatibility\. The [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule uses this setting if the `compatibility` setting is enabled\. Minimum value: `8`\. Maximum value: `14`\.

You can define the analyzer settings via the command line when running the analysis in the following format:

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

The example:

```cpp
./gradlew pvsAnalyze -Ppvsstudio.outputType=text
                     -Ppvsstudio.outputFile=.PVS-Studio/report.txt
                     -Ppvsstudio.disabledWarnings=V6001;V6002;V6003
```

**Note\.** 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, by specifying the path to `java` from the JDK in the `javaPath` analyzer setting\. The version of this JDK \(the Java language version\) is used when analyzing the project's source code:

```cpp
....
javaPath = "C:/Program Files/Java/jdk19.0.5/bin/java"
....
```

## How to update PVS\-Studio Java 

By using `latest.release` as the [plugin](https://mvnrepository.com/artifact/com.pvsstudio/pvsstudio-gradle-plugin) version in the files `build.gradle` or `build.gradle.kts`,you always have the latest PVS\-Studio version\.

### Using a proxy

When using a proxy, enter your login and password to correctly load the analyzer core, using the following arguments: 

* `-Dhttp.proxyUser` and `-Dhttp.proxyPassword`
* `-Dhttps.proxyUser` and `-Dhttps.proxyPassword`
* `-Djava.net.socks.username` and `-Djava.net.socks.password`
* `-Dftp.proxyUser` and `-Dftp.proxyPassword`\.

You can use this command to run the analysis via the plugin for Gradle that uses a proxy:

```cpp
./gradlew pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"
```