Работа с ядром Java анализатора из командной строки

• Установка ядра Java анализатора
• Аргументы ядра Java анализатора
• Запуск анализа
  • Как изменить версию Java для запуска анализатора?
• Файл конфигурации Java анализатора
• Глобальный файл настроек Java анализатора
• Коды возврата ядра Java анализатора
• Обновление PVS-Studio Java

Статический анализатор кода PVS-Studio Java состоит из 2-х основных частей: ядра, выполняющего анализ, и плагинов для интеграции в сборочные системы (Maven, Gradle) и IDE (PVS-Studio для IntelliJ IDEA и Android Studio).

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

• Предоставление удобного интерфейса для запуска и настройки анализатора;
• Удобный просмотр и фильтрация результатов анализа (IDE);
• Сбор и передача данных (наборы исходных файлов и classpath) о структуре проекта ядру анализатора;
• Развёртывание в системе ядра анализатора версии, соответствующей версии плагина.

Установка ядра Java анализатора

На Windows ядро Java анализатора возможно установить через инсталлятор PVS-Studio для Windows. Скачать его можно на странице загрузки.

Кроме этого, на всех операционных системах возможно скачать ZIP архив для Java на странице загрузки. В этом архиве содержится ядро Java анализатора (папка с именем 7.33.85174 в директории pvs-studio-java). Ядро анализатора надо распаковать в необходимое вам место или по стандартному пусти установки ядра Java анализатора:

• Windows: %APPDATA%/PVS-Studio-Java;
• Linux и macOS: ~/.config/PVS-Studio-Java.

Аргументы ядра Java анализатора

Для получения информации про все доступные аргументы анализатора, необходимо выполнить команду ‑‑help:

java -jar pvs-studio.jar --help

Аргументы анализатора:

• ‑‑src (-s) — набор файлов или директорий для анализа. Значение по умолчанию отсутствует. При перечислении нескольких файлов или директорий в качестве разделителя используется пробел. Пример: ‑‑src "path/to/file1" "path/to/file2" "path/to/dir";
• ‑‑ext (-e) — определение classpath (*.jar/*.class файлы, директории). Значение по умолчанию отсутствует. При перечислении нескольких сущностей classpath в качестве разделителя используется пробел. Пример: ‑‑ext "path/to/file.jar" "path/to/dirJars";
• ‑‑ext-file — путь до файла с classpath. Значение по умолчанию отсутствует. В качестве разделителя classpath используется ':' в *nix системах и ';' — в Windows системах. Пример: ‑‑ext-file "path/to/project_classpath_file";
• ‑‑cfg (-c) — конфигурационный файл для запуска ядра анализатора. В этом файле должны быть сохранены значения аргументов командной строки ядра Java анализатора в JSON формате. Более подробная информация об этом файле находится в следующем разделе документации. Значение по умолчанию отсутствует;
• ‑‑help (-h) — вывод в консоль справочной информации об аргументах ядра Java анализатора;
• ‑‑user-name — имя пользователя;
• ‑‑license-key — лицензионный ключ;
• ‑‑license-path — путь до файла с лицензией. Примечание: если ‑‑user-name и ‑‑license-key пустые, то анализатор попробует взять информацию о лицензии из файла %APPDATA%/PVS-Studio/Settings.xml (Windows) или ~/.config/PVS-Studio/PVS-Studio.lic (macOS и Linux);
• --activate-license — флаг, позволяющий сохранить информацию о лицензии, указанную в аргументах ‑‑user-name и ‑‑license-key, в файл по стандартному пути: %APPDATA%/PVS-Studio/Settings.xml (в Windows) или ~/.config/PVS-Studio/PVS-Studio.lic (в macOS и Linux). Значение по умолчанию: false;
• ‑‑convert — запуск в режиме конвертации. Режимы:
  • toFullhtml — преобразует отчет с предупреждениями в формат fullhtml;
  • toSuppress — преобразует отчет с предупреждениями в формат файла подавления (suppress файл);
• ‑‑src-convert — путь до отчёта анализатора с предупреждениями (*.json);
• ‑‑dst-convert — путь до файла или каталога, куда будет записан результат преобразования (файл для toSuppress, директория для toFullhtml);
• ‑‑output-type (-O) — формат, в котором будет представлен отчет анализатора (text, log, json, xml, tasklist, html, fullhtml, errorfile). Значение по умолчанию: json. Пример: ‑‑output-type txt;
• ‑‑output-file (-o) — путь до файла с отчётом анализатора. Формат содержимого отчёта анализатора не зависит от расширения файла, указанного в этом аргументе. Значение по умолчанию: ./PVS-Studio + расширение формата из аргумента ‑‑output-type. Для отчёта в формате fullhtml необходимо указать директорию, в которой будет создана папка с именем fullhtml, содержащая файл отчёта анализатора (index.html). Значение по умолчанию: ./fullhtml. Внимание. Вместо использования аргумента ‑‑output-file более предпочтительным сценарием является использование консольных утилит PlogConverter (Windows) и plog-converter (Linux и macOS). Эти утилиты позволяют конвертировать отчёт анализатора в большее количество форматов (например, SARIF), а также предоставляют дополнительные возможности: фильтрация предупреждений из отчёта, преобразование путей в отчёте с абсолютных на относительные и наоборот, получение разницы между отчётами и др.;
• ‑‑threads (-j) — число потоков анализа. Количество потоков анализа позволяет ускорить процесс анализа, тратя на это больше ресурсов системы. Также возможно задать эту настройку для всей системы в файле global.json. Значение по умолчанию: число доступных процессоров;
• ‑‑sourcetree-root — корневая часть пути, которую анализатор будет использовать при генерации относительных путей в диагностических сообщениях. По умолчанию при генерации диагностических сообщений PVS-Studio выдаёт абсолютные пути до файлов, на которые анализатор выдал срабатывания. С помощью данной настройки можно задать корневую часть пути (путь до директории), которую анализатор будет автоматически подменять на специальный маркер. Замена произойдет, если путь до файла начинается с заданной корневой части. В дальнейшем отчёт с относительными путями возможно использовать для просмотра результатов анализа в окружении с отличающимся расположением исходных файлов. Например, в разных операционных системах. Значение по умолчанию отсутствует; Пример: ‑‑sourcetree-root /path/to/project/directory;
• ‑‑analysis-mode — список активных групп диагностических правил. Доступные группы: GA (правила общего назначения), OWASP (правила согласно OWASP ASVS). Настройки ‑‑enabled-warnings, ‑‑disabled-warnings и ‑‑additional-warnings имеют больший приоритет, чем эта настройка. То есть если диагностическая группа отключена (или включена), то при анализе возможно включить (или отключить) отдельные диагностики при помощи этих настроек. При перечислении нескольких групп в качестве разделителя используется пробел. Значение по умолчанию: GA. Пример: ‑‑analysis-mode GA OWASP;
• ‑‑enabled-warnings — список активных диагностик. Во время анализа будут использованы только те диагностики, которые перечислены в этом списке. При отсутствии значения данной настройки все диагностики считаются включенными, если дополнительно не задано значение для настройки ‑‑disabled-warnings. Эта настройка имеет меньший приоритет, чем настройка ‑‑disabled-warnings и ‑‑additional-warnings, но больший, чем настройка ‑‑analysis-mode. Значение по умолчанию отсутствует. При перечислении нескольких правил в качестве разделителя используется пробел. Пример: ‑‑enabled-warnings V6001 V6002 V6003;
• ‑‑disabled-warnings — список выключенных диагностик. Диагностики, перечисленные в этом списке, не будут применены во время анализа. При отсутствии данной настройки все диагностики считаются включёнными, если дополнительно не задана настройка ‑‑enabledWarnings. Эта настройка имеет больший приоритет чем настройки ‑‑enabledWarnings и ‑‑analysisMode, но меньший чем ‑‑additionalWarnings. Значение по умолчанию отсутствует;
• ‑‑additional-warnings — список включенных по умолчанию диагностик, которые будут добавлены к анализу. Если диагностика добавлена в этот список, то наличие её в списках ‑‑enabledWarnings и ‑‑disabledWarnings игнорируется. Кроме того, эта диагностика будет включена, даже если группа диагностик, в которую она входит, отключена (т.е. в ‑‑analysisMode не содержится этой группы). Эта настройка имеет больший приоритет, чем настройки --enabled-warnings, --disabled-warnings и ‑‑analysis-mode. Значение по умолчанию отсутствует. При перечислении нескольких правил в качестве разделителя используется пробел. Пример: ‑‑additional-warnings V6001 V6002 V6003;
• ‑‑exclude — список файлов и/или директорий, которые нужно исключить из анализа (абсолютные или относительные пути, которые будут раскрыты относительно каталога запуска). При отсутствии значения для данной настройки будут проанализированы все файлы, если дополнительно не задано значение для настройки ‑‑analyze-only или ‑‑analyze-only-list. Эта настройка имеет больший приоритет, чем настройки —analyze-only и —analyze-only-list. Значение по умолчанию отсутствует. При перечислении нескольких файлов или директорий в качестве разделителя используется пробел. Пример: --exclude "path/to/file1" "path/to/file2" "path/to/dir";
• ‑‑analyze-only — список файлов и/или директорий, которые нужно проанализировать (абсолютные или относительный пути, которые будут раскрыты относительно каталога запуска). Кроме этого, возможно записать эти пути построчно в файл и передать путь до этого файла в аргумент ‑‑analyze-only-list. При отсутствии значения для данной настройки будут проанализированы все файлы, если дополнительно не задано значение для настройки ‑‑exclude или ‑‑analyze-only-list. Эта настройка имеет меньший приоритет, чем настройка ‑‑exclude. Файлы и/или директории, переданные в этом аргументе, объединяются в общий список с файлами и/или директориями из файла из аргумента ‑‑analyze-only-list. Значение по умолчанию отсутствует. При перечислении нескольких файлов или директорий в качестве разделителя используется пробел. Пример: ‑‑analyze-only "path/to/file1" "path/to/file2" "path/to/dir";
• ‑‑analyze-only-list — путь к текстовому файлу, содержащему список путей к файлам и/или каталогам для анализа (каждая запись должна быть на отдельной строке). Поддерживаются относительные (будут раскрыты относительно каталога запуска) и абсолютные пути. При отсутствии значения для данной настройки будут проанализированы все файлы, если дополнительно не задано значение для настройки ‑‑exclude или ‑‑analyze-only. Этот настройка имеет меньший приоритет, чем настройка ‑‑exclude. Файлы и/или директории, считанные из файла, указанного в этом аргументе, объединяются в общий список с файлами и/или директориями из аргумента ‑‑analyze-only. Значение по умолчанию отсутствует;
• ‑‑suppress-base — путь до suppress файла, содержащего подавленные сообщения анализатора. Сообщения из suppress-файла не попадут в отчёт при последующих проверках проекта. Добавить сообщения в suppress файл можно через интерфейс плагина PVS-Studio для IntelliJ IDEA и Android Studio, при помощи задачи pvsSuppress из плагинов для Gradle и Maven, а также при помощи использования аргумента ‑‑convert со значением toSuppress. Значение по умолчанию: ./.PVS-Studio/suppress_base.json;
• ‑‑fail-on-warnings — флаг, позволяющий вернуть ненулевой код возврата, если анализатор выдал какое-либо предупреждение на проекте. Этот флаг позволяет отслеживать наличие предупреждений анализатора в отчёте, полученном при анализе. Данное поведение может быть удобным при интеграции в CI/CD. Значение по умолчанию: false;
• ‑‑incremental (-i) — флаг, позволяющий запускать анализ инкрементально. В этом режиме анализируются только изменившиеся файлы, что позволяет ускорить процесс анализа. Значение по умолчанию: false;
• ‑‑force-rebuild — флаг, позволяющий принудительно перестроить целиком закэшированную метамодель программы, содержащую информацию о её структуре и типах данных. Перестройка метамодели проекта бывает иногда необходима при обновлении версии анализатора или если метамодель проекта оказалась повреждена. При использовании данного флага отключается инкрементальный режим анализа проекта (флаг ‑‑incremental). Значение по умолчанию: false;
• ‑‑disable-cache — флаг, позволяющий отключить кэширование метамодели программы. При отключенном кэше модель проекта не кэшируется и строится каждый раз заново. Этот флаг бывает полезно использовать при выяснении причин ошибок в анализаторе. При отключении кэширования метамодели проекта также отключается инкрементальный режим анализа проекта (флаг ‑‑incremental). Значение по умолчанию: false;
• ‑‑timeout — таймаут анализа одного файла (в минутах). Позволяет увеличивать или уменьшать максимальное время, которое анализатор будет тратить на анализ одного файла. Также возможно задать эту настройку для всей системы в файле global.json. Значение по умолчанию: 10;
• ‑‑compatibility — флаг, активирующий диагностическое правило V6078, которое обнаруживает потенциальные проблемы совместимости API между выбранными версиями Java SE. Диагностика V6078 позволяет убедится, что API JDK, которое вы используете, не изменится или не исчезнет в более поздних версиях JDK. Значение по умолчанию: false;
• ‑‑source-java — версия Java SE, на которой разработано ваше приложение. Эта настройка используется диагностикой анализатора V6078, если включена настройка ‑‑compatibility. Минимальное значение: 8. Максимальное значение: 14;
• ‑‑target-java — версия Java SE, на совместимость с которой вы хотите проверить API, используемое в вашем приложении (‑‑source-java). Эта настройка используется диагностикой анализатора V6078, если включена настройка ‑‑compatibility. Минимальное значение: 8. Максимальное значение: 14;
• ‑‑exclude-packages — пакеты, которые вы хотите исключить из анализа совместимости (диагностика V6078). Эта настройка используется диагностикой анализатора V6078, если включена настройка ‑‑compatibility. Пример: ‑‑exclude-packages "package1" "package2" "package3".

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

Перед запуском анализа вам необходимо будет ввести лицензию. Как это сделать — можно узнать в этой документации.

Примеры быстрого запуска ядра Java анализатора:

java -jar pvs-studio.jar -s A.java B.java C.java -e Lib1.jar Lib2.jar -j4 
-o report.txt -O text --user-name someName –-license-key someSerial

java -jar pvs-studio.jar -s src/main/java --ext-file classpath.txt -j4 
-o report.txt -O text --license-path PVS-Studio.lic

Обратите внимание:

• анализатору для работы необходим набор исходных файлов (или директорий с исходными файлами) для анализа, а также classpath, чтобы корректно построить метамодель программы;
• при анализе проекта будет использована версия языка Java, соответствующая версии JDK, из которого используется файл java для запуска ядра Java анализатора. Если хотите изменить версию языка Java, которая будет использована при анализе, то используйте для запуска ядра Java анализатора (pvs-studio.jar) файл java из JDK соответствующей версии.

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

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

/path/to/jdk_folder/bin/java -jar pvs-studio.jar ^
-s A.java B.java C.java -e Lib1.jar Lib2.jar -j4 ^
-o report.txt -O text --user-name someName –-license-key someSerial

Файл конфигурации Java анализатора

Для упрощения команды запуска анализа можно вынести аргументы командной строки в специальный JSON-файл. В дальнейшем этот файл можно передать в ядро анализатора через флаг ‑‑cfg.

Синтаксис файла выглядит следующим образом:

{
  "single-value-parameter": "value",
  "multiple-values-parameter": ["value1", "value2", "value3"]
}

Каждый параметр в файле конфигурации представляет собой полное имя флага командной строки со значением, которое будет передано в этом флаге.

Пример файла конфигурации:

{
  "src": ["A.java", "B.java", "C.java"],
  "threads": 4,
  "output-file": "report.txt",
  "output-type": "text",
  "user-name": "someName",
  "license-key": "someSerial"
  ....
}

В таком случае запуск анализатора сведётся к следующей строке:

java -jar pvs-studio.jar –-cfg cfg.json

Обратите внимание, что параметры, переданные через командную строку, имеют более высокий приоритет, чем параметры, заданные в файле конфигурации.

Глобальный файл настроек Java анализатора

Часть настроек ядро Java анализатора берёт из файла global.json. Этот файл расположен в папке по стандартному пути установки ядра Java анализатора:

• Windows: %APPDATA%/PVS-Studio-Java/global.json;
• Linux и macOS: ~/.config/PVS-Studio-Java/global.json.

Вот список этих настроек:

• java — Значение по умолчанию: java;
• jvm-arguments — Значение по умолчанию: ["-Xss64m"];
• threads — Значение по умолчанию: число доступных процессоров. Это значение возможно переопределить через аргумент ‑‑threads командной строки ядра Java анализатора;
• timeout — Значение по умолчанию: 10. Это значение возможно переопределить через аргумент ‑‑timeout командной строки ядра Java анализатора;
• verbose — Значение по умолчанию: true.

Эти значения по умолчанию используются для всех ядер Java анализатора в системе, а также плагинами PVS-Studio для Java. При необходимости значения этих параметров можно изменить. Например, чтобы все плагины PVS-Studio для Java использовали одно и то же количество потоков для анализа.

Информацию о том, какие из этих настроек возможно переопределить в плагинах PVS-Studio для Java, вы найдёте в соответствующих разделах документации:

• Maven;
• Gradle;
• PVS-Studio для IntelliJ IDEA и Android Studio.

Коды возврата ядра Java анализатора

• '0' – анализ успешно завершён. Ошибки могут быть как найдены, так и не найдены;
• '50' – произошла ошибка при анализе;
• '51' – переданы невалидные аргументы при запуске анализа;
• '52' – при анализе используется невалидная или просроченная лицензия;
• '53' – анализ успешно завершен, и анализатор нашёл потенциальные ошибки в коде проекта. Этот код возврата будет возвращен только при использовании флага ядра Java анализатора ‑‑fail-on-warnings;
• '54' – при анализе попытались использовать Enterprise возможности ядра Java анализатора, но при этом использовали не Enterprise лицензию.

Обновление PVS-Studio Java

Каждый раз при запуске анализа проверяется наличие новой версии анализатора PVS-Studio. Если вышла новая версия анализатора, то в файле с результатами анализа будет содержаться сообщение: "A newer version of PVS-Studio is available (7.33.85174)". Это сообщение содержит последнюю версию ядра Java анализатора.

Кроме этого, получить последнюю версию PVS-Studio можно из файла по ссылке.

Для обновления ядра Java анализатора скачайте ZIP архив на странице загрузки. В этом архиве содержится ядро Java анализатора (папка с именем 7.33.85174 в директории pvs-studio-java). Ядро Java анализатора надо распаковать в необходимое место или в стандартную директорию:

• Windows: %APPDATA%/PVS-Studio-Java;
• Linux и macOS: ~/.config/PVS-Studio-Java.

Весь этот процесс можно автоматизировать при помощи различных скриптов, что позволит всегда использовать последнюю версию ядра Java анализатора.