# Интеграция PVS\-Studio Java в сборочную систему Gradle

Статический анализатор кода PVS\-Studio Java состоит из 2\-х основных частей: [ядра](https://pvs-studio.ru/ru/docs/manual/6703/), выполняющего анализ, и плагинов для интеграции в сборочные системы \([Maven](https://pvs-studio.ru/ru/docs/manual/6705/) и Gradle\) и IDE \([IntelliJ IDEA и Android Studio](https://pvs-studio.ru/ru/docs/manual/6704/)\)\.

Функции плагинов: 

* предоставление удобного интерфейса для запуска и настройки анализатора; 
* развёртывание в системе ядра анализатора;
* сбор и передача данных \(наборы исходных файлов и classpath\) о структуре проекта ядру анализатора\.

## Интеграция плагина PVS\-Studio в Gradle

Для интеграции плагина при использовании Groovy DSL необходимо добавить следующий код в скрипт сборки `build.gradle`:

```cpp
buildscript {
  repositories {
    mavenCentral()
    maven {
      url uri('https://cdn.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']
}
```

Для Kotlin DSL необходимо добавить следующий код в `build.gradle.kts`:

```cpp
import com.pvsstudio.WarningGroup

buildscript {
  repositories {
    mavenCentral()
    maven {
      url = uri("https://cdn.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)
}
```

## Запуск анализа

> Перед первым запуском анализа вам необходимо будет ввести лицензию\. Как это сделать — можно узнать в этой [документации](https://pvs-studio.ru/ru/docs/manual/0046/#PvsStudioJava)\.

Для запуска анализа выполните команду:

```cpp
./gradlew pvsAnalyze
```

**Обратите внимание:** при анализе проекта плагин запускает [ядро Java анализатора](https://pvs-studio.ru/ru/docs/manual/6703/), которое по умолчанию использует версию java из переменной окружения `PATH`\. Задать другую версию можно при помощи настройки плагина `javaPath`, подробное описание которой находится ниже в разделе **Конфигурация**\.

## Запуск анализа без доступа к сети

Для работы плагина нужно скачать его зависимости\. Если вам нужно работать с плагином в системе без доступа в сеть, вы должны создать офлайн репозиторий c зависимостями плагина\.   

Для загрузки зависимостей и подготовки к офлайн использованию примените такую команду:

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

Запускать эту команду нужно из директории с файлом `build.gradle` \(корневой директории проекта\)\. В этом случае все необходимые зависимости для сборки и анализа проекта будут сохранены в стандартной папке локального репозитория: 

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

Вы должны иметь подключение к сети во время запуска этой команды, чтобы зависимости могли загрузиться\. Для последующей работы интернет\-соединение уже не нужно\.

В системе должно быть установлено ядро Java той же версии, что и плагин\. Узнать, как установить ядро Java анализатора, можно в отдельной [документации](https://pvs-studio.ru/ru/docs/manual/6703/#java_core_install)\.

Использование анализатора в таком случае не отличается от обычного\. Для того чтобы Gradle не начинал скачивать зависимости, используйте флаг `--offline`\. Команда запуска анализа в офлайн режиме:

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

## Конфигурация

Ниже представлен список настроек анализатора, которые могут быть указаны в блоке `pvsstudio` файла `build.gradle` \(для Groovy DSL\) или `build.gradle.kts` \(для Kotlin DSL\):

* `additionalWarnings = ["VXXXX", ....]` \(Groovy\) / `setOf("VXXXX", ....)` \(Kotlin\) — список диагностических правил, которые будут добавлены к анализу\. Эта настройка имеет больший приоритет, чем `enabledWarnings`, `disabledWarnings` и `analysisMode`\. Значение по умолчанию отсутствует;
* `analysisMode = ["GA", ....]` \(Groovy\) / `setOf(WarningMode.GA, ....)` \(Kotlin\) — список активных групп диагностических правил\. Имеет меньший приоритет, чем настройки `--enabled-warnings`, `--disabled-warnings` и `--additional-warnings`\. Значение по умолчанию: `GA`\. Доступные группы: 
  * [`GA`](https://pvs-studio.ru/ru/docs/warnings/#GeneralAnalysisJAVA) \(правила общего назначения\);
  *  [`OWASP`](https://pvs-studio.ru/ru/pvs-studio/sast/owasp/#java) \(правила согласно [OWASP Top Ten](https://pvs-studio.ru/ru/pvs-studio/sast/owasptopten/) и [OWASP ASVS](https://pvs-studio.ru/ru/pvs-studio/sast/owasp/)\)\. 
* `analyzeOnly = ["PATH", ....]` \(Groovy\) / `setOf("PATH", ....)` \(Kotlin\) — список файлов и/или директорий, которые нужно проанализировать \(абсолютные или относительный пути, которые будут раскрыты относительно каталога запуска\)\. Файлы и/или директории, переданные в этом аргументе, объединяются в общий список с файлами и/или директориями из аргумента `--analyze-only-list`\. При отсутствии значения для данной настройки будут проанализированы все файлы\. Имеет меньший приоритет, чем `exclude`\. Значение по умолчанию отсутствует;
* `analyzeOnlyList = "PATH"` \(Groovy/Kotlin\) — путь к текстовому файлу, содержащему список путей к файлам и/или каталогам для анализа \(каждая запись должна быть на отдельной строке\)\. Поддерживаются относительные \(будут раскрыты относительно каталога запуска\) и абсолютные пути\. Файлы и/или директории, считанные из файла, указанного в этом аргументе, объединяются в общий список значений c аргументами из `analyzeOnly`\. Эта настройка имеет меньший приоритет, чем `exclude`\. Значение по умолчанию отсутствует;
* `disableCache = BOOLEAN` \(Groovy/Kotlin\) — позволяет отключить кэширование метамодели программы\. При отключённом кэше модель проекта не кэшируется и строится каждый раз заново\. При отключении кэширования метамодели проекта также отключается [инкрементальный](https://pvs-studio.ru/ru/docs/manual/0024/) режим анализа проекта \(настройка `incremental`\)\. Значение по умолчанию: `false`;
* `disabledWarnings = ["VXXXX", ....]` \(Groovy\) / `setOf("VXXX", ....)` \(Kotlin\) — список диагностических правил, которые не будут применены во время анализа\. При отсутствии данной настройки все диагностические правила считаются включёнными\. Имеет больший приоритет, чем `enabledWarnings` и `analysisMode`, но меньший, чем `--additionalWarnings`\. Значение по умолчанию отсутствует;
* `enabledWarnings = ["VXXXX", ....]` \(Groovy\) / `setOf("VXXXX", ....)` \(Kotlin\) — список активных диагностических правил\. Во время анализа будут использованы только перечисленные в этом списке диагностические правила\. Эта настройка имеет меньший приоритет, чем `disabledWarnings` и `additionalWarnings`, но больший, чем `analysisMode`\. Значение по умолчанию отсутствует;
* `exclude = ["PATH", ....]` \(Groovy\) / `setOf("PATH", ....)` \(Kotlin\) — список файлов и/или директорий, которые нужно исключить из анализа\. Поддерживаются относительные \(будут раскрыты относительно каталога запуска\) и абсолютные пути\. Эта настройка имеет больший приоритет, чем `analyzeOnly` и `analyzeOnlyList`\. Значение по умолчанию отсутствует\. При перечислении нескольких файлов или директорий в качестве разделителя используется пробел;
* `failOnWarnings = BOOLEAN` \(Groovy/Kotlin\) — устанавливает ненулевой код возврата программы, если анализатор выдал хотя бы одно предупреждение\. Такое поведение может быть удобным при [интеграции в CI/CD](https://pvs-studio.ru/ru/docs/#IDF1BF21914C)\. Значение по умолчанию: `false`;
* `forceRebuild = BOOLEAN` \(Groovy/Kotlin\) — позволяет принудительно перестроить целиком закэшированную метамодель программы\. При использовании данного флага отключается [инкрементальный](https://pvs-studio.ru/ru/docs/manual/0024/) режим анализа проекта \(настройка `incremental`\)\. Значение по умолчанию: `false`;
* `incremental = BOOLEAN` \(Groovy/Kotlin\) — позволяет запустить анализ [инкрементально](https://pvs-studio.ru/ru/docs/manual/0024/)\. В этом режиме анализируются только изменившиеся или новые файлы\. Значение по умолчанию: `false`;
* `javaPath = "PATH"` \(Groovy/Kotlin\) — задаёт путь до исполняемого файла java, с которым будет запускаться ядро анализатора\. Эту настройку можно задать для всей системы в файле [`global.json`](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\. Если не использовать `javaPath`, то PVS\-Studio попытается использовать путь из переменной окружения `PATH`;
* `jvmArguments = ["FLAG", ....]` \(Groovy\) / `setOf("FLAG", ....)` \(Kotlin\) — дополнительные флаги JVM, с которыми будет запускаться ядро анализатора\. Этот флаг позволяет настраивать JVM, которая будет запускать ядро Java анализатора\. Возможно задать эту настройку для всей системы в файле [`global.json`](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\. Значение по умолчанию: `["-Xss64m"]`;
* `licensePath = "PATH"` \(Groovy/Kotlin\) — путь до файла с лицензией\. Допустимые расширения файла: `.xml`, `.lic`\. Значение по умолчанию: 
  * **Windows**: `%APPDATA%/PVS-Studio/Settings.xml`, 
  * **macOS и Linux**: `~/.config/PVS-Studio/PVS-Studio.lic`;
* `logging = "LEVEL"` \(Groovy/Kotlin\) — уровень логирования при запуске анализа\. При включении логирования в подпапке `.PVS-Studio/logs` относительно директории текущего запуска Java анализатора будут созданы файлы логов для текущего запуска\. Значение по умолчанию: `OFF`\. Допустимые варианты значений: 
  * `OFF`;
  * `ERROR`; 
  * `WARN`;
  * `INFO`;
  * `DEBUG`; 
  * `TRACE`;
  * `ALL`\. 
* `outputFile = "PATH"` \(Groovy/Kotlin\) — путь до файла с отчётом, куда будут записаны результаты анализа\. Формат содержимого не зависит от расширения файла, указанного в данном параметре\. Значение по умолчанию: `$projectDir/PVS-Studio` \+ расширение формата из настройки `outputType`\. Для отчёта в формате `fullhtml` необходимо указать директорию, в которой будет создана папка с именем `fullhtml`, содержащая файл отчёта анализатора \(`index.html`\)\. Значение по умолчанию: `$projectDir/fullhtml`\. **Внимание\. **Вместо использования настройки `outputFile`_ _более предпочтительным сценарием является использование консольных утилит [PlogConverter \(Windows\)](https://pvs-studio.ru/ru/docs/manual/0038/#PlogConverter) и [plog\-converter \(Linux и macOS\)](https://pvs-studio.ru/ru/docs/manual/0038/#plog-converter)\. Эти утилиты позволяют конвертировать отчёт анализатора в большее количество форматов \(например, SARIF\), а также предоставляют дополнительные возможности: фильтрация предупреждений из отчёта, преобразование путей в отчёте с абсолютных на относительные и наоборот, получение разницы между отчётами и др\.; 
* `outputType = "TYPE"` \(Groovy/Kotlin\) — формат, в котором будет представлен отчёт анализатора\. Значение по умолчанию: `json`\. Допустимые варианты значений:
  * `text`;
  * `log`;
  * `json`; 
  * `xml`;
  * `tasklist`; 
  * `html`;
  * `fullhtml`; 
  * `errorfile`\. 
* `securityRelatedIssues = BOOLEAN` \(Groovy/Kotlin\) — позволяет выделить дополнительной маркировкой в поле `SAST` предупреждения, относящиеся к потенциальным проблемам безопасности и классифицируемые согласно ГОСТ Р 71207—2024\. Значение по умолчанию: `false`;
* `sourceTreeRoot = "PATH"` \(Groovy/Kotlin\) — корневая часть пути, которую анализатор [будет использовать](https://pvs-studio.ru/ru/docs/manual/0027/) при генерации относительных путей в отчёте для диагностических предупреждений\. Значение по умолчанию отсутствует;
* `suppressBase = "PATH"` \(Groovy/Kotlin\) — путь до [suppress\-файла](https://pvs-studio.ru/ru/docs/manual/0032/), содержащего подавленные предупреждения анализатора\. Они не попадут в отчёт при следующих проверках проекта\. Значение по умолчанию: `./.PVS-Studio/suppress_base.json`;
* `threadsNum = NUMBER` \(Groovy/Kotlin\) — позволяет задать число потоков, на которое будет распараллелен анализ\. Можно задать эту настройку для всей системы в файле [`global.json`](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\. Значение по умолчанию: _число доступных логических ядер_;
* `timeout = NUMBER` \(Groovy/Kotlin\) — таймаут анализа одного файла \(в минутах\)\. Эту настройку можно задать для всей системы в файле [`global.json`](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\. Значение по умолчанию: `10`;** **
* `compatibility = BOOLEAN` \(Groovy/Kotlin\) — активирует диагностическое правило [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), которое обнаруживает потенциальные проблемы совместимости API между выбранными версиями Java SE\. Значение по умолчанию: `false;`
* `excludePackages = ["PACK", ....]` \(Groovy\) / `setOf("PACK", ....)` \(Kotlin\) — пакеты, которые будут исключены из анализа совместимости\. Используется диагностическим правилом [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), если включена настройка `compatibility`;
* `sourceJava = NUMBER` \(Groovy/Kotlin\) — задаёт версию Java SE, на которой разработано приложение\. Эта настройка используется диагностическим правилом [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), если включена настройка `compatibility`\. Минимальное значение: `8`\. Максимальное значение: `14`;
* `targetJava = NUMBER` \(Groovy/Kotlin\) — задаёт версию Java SE, на совместимость с которой необходимо проверить API, используемое в приложении \(`sourceJava`\)\. Эта настройка используется диагностическим правилом [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), если включена настройка `compatibility`\. Минимальное значение: `8`\. Максимальное значение: `14`;

Настройки могут быть переданы через командную строку в момент запуска анализа\. Формат определения:

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

Пример:

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

**Обратите внимание**, что параметры, явно переданные в командной строке, имеют наивысший приоритет\.

### Как изменить версию Java для запуска анализатора

По умолчанию анализатор запускает ядро с `java` из переменной окружения `PATH`\. Если необходимо запустить анализ с другой версией, её можно указать вручную\. Для этого в настройке анализатора `javaPath` укажите путь до `java` из JDK\. Версия этой JDK \(версия языка Java\) будет использована при анализе исходного кода проекта:

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

## Обновление PVS\-Studio Java анализатора

Благодаря использованию `latest.release` в качестве версии [плагина](https://mvnrepository.com/artifact/com.pvsstudio/pvsstudio-gradle-plugin) в файле `build.gradle`_ _или `build.gradle.kts` у вас всегда будет использоваться последняя версия PVS\-Studio для анализа\.

### Использование прокси

При использовании прокси необходимо указать логин и пароль для корректной загрузки ядра анализатора\. 

Это можно сделать через аргументы: 

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

Команда для запуска анализа через плагин для Gradle с прокси:

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