Использование расширения PVS-Studio для Visual Studio Code
Смотреть отчёты PVS-Studio в Visual Studio Code можно с помощью специального расширения PVS-Studio. Ниже описано, как установить расширение, запустить анализ проекта или открыть уже существующий отчёт PVS-Studio и работать с ним.
Обратите внимание, что предварительно вам потребуется скачать и установить анализатор.
Установка расширения PVS-Studio
Чтобы установить расширение PVS-Studio, откройте Visual Studio Code и перейдите на вкладку 'Extensions', затем введите в поле поиска 'PVS-Studio' и кликните по кнопке 'Install':
При установке анализатора на Windows вы можете выбрать пункт 'Integration with Visual Studio Code' и тогда расширение добавится в Visual Studio Code автоматически.
Также на Windows можно выполнить установку расширения, используя файл pvs-studio-vscode-*.vsix, расположенный в каталоге PVS-Studio (по умолчанию "%PROGRAMFILES(x86)%\PVS-Studio").
Для установки плагина из .vsix-файла на вкладке 'Extensions' в правом верхнем углу необходимо нажать на три точки и в появившемся меню выбрать пункт 'Install from VSIX...':
В открывшемся окне выберите .vsix файл плагина PVS-Studio. После установки плагина перезапустите Visual Studio Code.
Также установить расширение или скачать .vsix файл можно cо страницы PVS-Studio в Visual Studio Marketplace.
После установки расширения окно PVS-Studio появится в качестве одной из вкладок на нижней панели Visual Studio Code. В случае, если окно PVS-Studio было скрыто, вы можете снова отобразить его с помощью команды 'PVS-Studio: Show window' в палитре команд (Ctrl + Shift + P).
Запуск анализа
Запустить анализ можно несколькими способами:
1. С помощью кнопки 'Analyze project' в окне PVS-Studio:
В этом случае будет запущен анализ всего решения.
2. Через контекстное меню редактора кода:
В этом случае будет запущен анализ только одного файла. Обратите внимание, что отсутствие данного пункта меню означает, что анализ текущего файла не поддерживается.
3. Через контекстное меню проводника.
В этом случае будут проанализированы все поддерживаемые файлы, которые были выделены. Кроме того, если среди выделенных элементов имеется папка, все поддерживаемые файлы, содержащиеся в ней и в ее поддиректориях, будут проанализированы.
4. Через меню группы вкладок редактора:
В этом случае будут проанализированы все поддерживаемые файлы, открытые в текущей группе вкладок.
5. С помощью команд 'Run regular analysis' и 'Run intermodular analysis' в палитре команд (Ctrl+Shift+P):
Обе команды запускают общий анализ решения. Разница между ними имеет значение только при анализе C и C++ кода. В этом режиме анализатор выполняет более глубокий анализ, но тратит на это больше времени.
В случае если в открытой в VS Code директории не найдено подходящей цели для анализа, вы получите соответствующее сообщение:
В обратном случае вам, возможно, будет предложено настроить параметры, специфичные для анализа проектов, использующих ту или иную сборочную систему. Больше информации об анализе проекта конкретного типа можно найти в разделах этой документации: 'Анализ C, C++ (CMake) проектов', 'Анализ C# (MSBuild) проектов' и 'Анализ Java проектов'.
В случае успешного запуска анализа окно PVS-Studio примет следующий вид:
В правом верхнем углу окна будет отображаться прогресс анализа в процентах. Рядом с ним появится кнопка, с помощью которой можно прервать анализ. Срабатывания будут появляться в таблице по мере поступления.
Анализ C, C++ (CMake) проектов
Перед запуском анализа необходимо установить расширение CMake Tools для VSCode.
Плагин совместим со следующими генераторами для сборки проектов:
- Ninja;
- Makefile Generators.
При обнаружении неподдерживаемого генератора или его отсутствии появится сообщение, предлагающее задать этот параметр в настройках CMake-Tools:
При клике по кнопке 'Edit setting' будет открыта страница с этой настройкой.
Перед запуском анализа вам будет предложено выбрать его тип: межмодульный анализ (Intermodular analysis) или обычный анализ (Regular analysis). Их отличие заключается в том, что межмодульный анализ выполняется дольше, чем обычный, но даёт лучший результат. Подробнее про этот режим вы можете прочитать в документации.
При запуске анализа также учитывается содержимое папки '.PVS-Studio' в директории исходного кода проекта. Если в ней будут найдены пользовательские файлы конфигурации (с расширением *.pvsconfig) или suppress-файлы (с суффиксом *.suppress.json), то они будут переданы анализатору для дальнейшей обработки.
Внимание: на данный момент при проверке CMake проектов поддерживается работа только с одним suppress-файлом. Если при запуске будет найдено несколько файлов, то в отчёте появится соответствующая запись. В ней также будет указано, какой файл используется при анализе.
Анализ C# (MSBuild) проектов
При первом анализе решения вы получите уведомление о создании файла в "[workspace folder]/.PVS-Studio/MSBuildAnalyzerConfig.json", в котором можно задать некоторые настройки анализа, аналогичные параметрам консольной версии анализатора.
Варианты действий:
- Edit – открыть только что созданный файл, анализ запущен не будет;
- Continue – запустить анализ с параметрами по умолчанию;
- Cancel – отменить запуск анализа.
В этом файле вы можете указать файлы и параметры, которые будут учитываться при анализе:
- suppress-файлы (с расширением *.suppress.json);
- файлы конфигурации (с расширением *.pvsconfig);
- платформу и конфигурацию сборки;
- конкретные проекты (.csproj и .vcxproj) и файлы (.cs, .cpp и др.) для анализа;
- а также другие настройки, описание которых вы можете найти как в самом файле, так и в документации.
Внимание: при запуске анализа конкретных файлов через контекстные меню или меню групп вкладок редактора будут проанализированы только файлы, включенные в выбранное решение.
Кроме того, если среди анализируемых файлов окажется файл проекта (файл с расширением .csproj), будет выполнен анализ всех поддерживаемых файлов с кодом, которые включены в этот проект.
Анализ Java проектов
Внимание: чтобы расширение смогло определить ваш проект в открытой директории, в VS Code также должно быть установлено и активировано расширение "Project manager for Java".
По умолчанию расширение ищет ядро анализатора в одной из следующих директорий:
- "C:\Users\[User]\AppData\Roaming\PVS-Studio-Java (на Windows)";
- "~/.config/PVS-Studio-Java (на Linux и macOS)".
Если ядро находится в другой папке, следует указать путь к ней в настройках расширения (File > Preferences > Settings > PVS-Studio: Java Projects Analyzer)
Для запуска ядра анализатора требуется JDK с 11-19 версией. По умолчанию используется JDK, путь к которому задан в переменных окружения. Если версия вашего JDK не входит в допустимый диапазон, установите поддерживаемый JDK и укажите путь к нему в настройках VS Code (File > Preferences > Settings > PVS-Studio: Java For Running Analyzer).
Перед анализом рекомендуется выполнить команду "Java: Reload Projects" в палитре команд (Ctrl + Shift + P). Если после этого появится выпадающий список с модулями вашего проекта, убедитесь, что галочкой отмечены все модули, которые нужно проанализировать.
Запускаем анализ
При первом анализе проекта вы получите уведомление о создании файла в "[workspace folder]/.PVS-Studio/JavaAnalyzerConfig.json", в котором можно задать некоторые настройки анализа, аналогичные параметрам консольной версии анализатора.
Варианты действий:
- Edit — открыть только что созданный файл, анализ запущен не будет;
- Continue — запустить анализ с параметрами по умолчанию;
- Cancel — отменить запуск анализа (файл создан не будет).
В этом файле вы можете указать параметры, которые будут учитываться при анализе, например:
- Путь к suppress-файлу (с расширением *.json);
- Включить/отключить инкрементальный анализ (по умолчанию отключен);
- Включить/отключить специальную диагностику V6078, обнаруживающую потенциальные проблемы совместимости API между выбранными версиями Java SE (версии указываются в качестве отдельных параметров).
Работа с результатами анализа
Преобразование отчёта PVS-Studio в формат JSON
Обратите внимание: расширение PVS-Studio для Visual Studio Code поддерживает только отчёты в формате JSON. В зависимости от типа проверяемого проекта и способа запуска анализа, PVS-Studio может генерировать отчёт в нескольких форматах. Чтобы отобразить отчёт в расширении, Вам потребуется выполнить его преобразование в JSON-формат.
Для преобразования можно воспользоваться утилитами командной строки PlogConverter.exe для Windows и plog-converter для Linux и macOS. Эти утилиты позволяют не только конвертировать отчёт PVS-Studio в разные форматы, но и дополнительно обрабатывать его. Например, проводить фильтрацию предупреждений. Подробнее о них можно прочитать здесь.
Пример команды конвертации отчёта PVS-Studio в JSON-формат при помощи PlogConverter.exe (Windows):
PlogConverter.exe path\to\report.plog -t json ^
-n PVS-Studio
Пример команды конвертации отчёта PVS-Studio в JSON-формат при помощи plog-converter (Linux и macOS):
plog-converter path/to/report/file.plog -t json \
-o PVS-Studio.json
Просмотр преобразованного отчёта PVS-Studio в VS Code
Для просмотра отчёта в Visual Studio Code нажмите 'Open report' в окне PVS-Studio и выберите нужный файл. Также открыть отчёт можно, выбрав в палитре команд (Ctrl+Shift+P) 'PVS-Studio: Load Report'.
После этого предупреждения из отчёта отобразятся в таблице:
Для удобной работы с таблицей закрепите её на панели. Для этого кликните правой кнопкой мыши на заголовке панели и выберите "Keep 'PVS-Studio'".
Для работы с отчётом, содержащим относительные пути, необходимо воспользоваться настройкой 'Source Tree Root'. Для этого откройте окно настроек, во вкладке 'Other' нажмите кнопку 'Browse' и выберите директорию, относительно которой будут разворачиваться все пути в файле отчёта.
Фильтрация предупреждений
Механизмы фильтрации окна вывода PVS-Studio позволяют быстро найти и отобразить как отдельные диагностические сообщения, так целые их группы. Среди инструментов окна есть ряд переключателей, позволяющих включить либо отключить отображение предупреждений из соответствующих им групп.
Все переключатели можно разбить на 3 группы: фильтры по уровню достоверности предупреждений, фильтры сообщений по диагностическим группам, фильтры по ключевым словам. Отфильтровать можно по коду сообщения, по тексту сообщения и по файлу, содержащему сообщение анализатора.
Детальное описание уровней достоверности предупреждений и групп диагностических правил приведено в разделе документации 'Знакомство со статическим анализатором кода PVS-Studio'.
Переключить видимость группы фильтраций можно с помощью кнопок 'Column', 'Level', 'Group'.
Все перечисленные механизмы фильтрации предупреждений можно совмещать между собой. Например, фильтровать сообщения по уровню и группам отображаемых предупреждений, исключать сообщения, помеченные как ложные срабатывания и т.п.
Подавление предупреждений
При первом запуске анализатора на большом проекте может быть действительно много срабатываний. Разумеется, стоит выписать себе самые интересные, а вот остальные можно скрыть при помощи механизма подавления предупреждений.
Для подавления всех предупреждений нужно нажать кнопку 'Suppress All Messages' в правой верхней части окна:
При её активации появится дополнительное окно с вопросом, какие именно предупреждения вы хотите подавить:
- Suppress All – подавит все предупреждения в таблице (даже скрытые через фильтры и настройки);
- Suppress Filtered– подавит только те предупреждения, что сейчас присутствуют в таблице.
При выборе нужного пункта предупреждения будут подавлены в существующий файл подавления предупреждений. Если файл подавления предупреждений не будет найден, то будет создан в следующей директории: "[корневой каталог исходного кода проекта]/.PVS-Studio".
Если предложенный выше вариант вам не подходит, то можно воспользоваться точечным подавлением предупреждений. Для этого необходимо выбрать нужные строки в таблице, открыть контекстное меню и выбрать "Add message to suppression file".
Навигация и сортировка
Окно вывода результатов PVS-Studio в первую очередь предназначено для упрощения навигации по коду проекта и переходу к участкам кода, содержащим потенциальные ошибки. Двойной щелчок мыши по любому из предупреждений в списке автоматически откроет файл, на который данное сообщение указывает.
Для выделения интересных предупреждений, например, тех, к которым имеет смысл вернуться повторно, можно использовать "звёздочку" в соответствующей колонке.
Правый клик по заголовку таблицы вызывает контекстное меню, с помощью которого можно настроить отображаемые столбцы.
Другие возможности
Таблица поддерживает множественное выделение с помощью стандартных комбинаций 'Ctrl' и 'Shift '. Контекстное меню таблицы предупреждений содержит несколько подпунктов:
- Mark as Favorite – отмечает выбранные сообщения как избранные;
- Mark as False Alarm – помечает выбранные сообщения как ложные срабатывания и добавляет специальный комментарий в исходный код;
- Copy message – копирует номер и сообщение диагностики, файл, на котором выдано предупреждение, в буфер обмена;
- Exclude diagnostic – исключает показ всех предупреждений с тем же кодом, что и у выделенного;
- Exclude paths – позволяет исключить путь к выделенному файлу либо часть этого пути. Все предупреждения на файлах, содержащих выбранный путь, не будут показаны.
Кнопки в правой части панели предназначены, соответственно, для запуска анализа, подавления предупреждений, сохранения отчёта, открытия нового отчёта, открытия настроек расширения. При наличии изменений в отчёте кнопка сохранения отчёта поменяет свой фон на красный, как показано на скриншоте ниже.
Конфигурация плагина
Для открытия окна настроек нажмите на крайнюю правую кнопку окна PVS-Studio или нажмите 'Ctrl+Shift+P' и введите 'PVS-Studio: Show Settings'.
Кнопка 'Save settings' сохраняет настройки в формате JSON. Для загрузки сохранённых настроек воспользуйтесь кнопкой 'Load settings'.
False alarms
Во вкладке False alarms можно настроить:
- показывать или нет ложные срабатывания;
- сохранять ли автоматически исходные файлы при отметке предупреждения как ложного;
- добавлять ли дополнительное сообщение к комментарию о ложном срабатывании.
Columns
Данная вкладка настроек позволяет отметить какие столбцы должны отображаться в таблице срабатываний.
Diagnostics
Вкладка Diagnostics позволяет отметить, какие предупреждения должны отображаться в таблице срабатываний. Все срабатывания разбиты на группы. Для поиска определённого диагностического правила можно воспользоваться полем 'Code and Messages'. Кнопки 'Check all/Uncheck all' предназначены для включения/выключения отображения всех диагностик из определённой группы. При отключении всех диагностик из соответствующей группы переключатель этой группы убирается из соответствующей группы фильтрации в окне PVS-Studio.
Exclude paths
Во вкладке Exclude paths в поле 'New excluded path' можно ввести пути или маски путей. Сообщения, выданные на файлы, удовлетворяющие условиям маски, не будут отображаться в таблице срабатываний.
Analysis
Во вкладке Analysis в поле 'Timeout' можно ввести время в секундах, по истечению которого анализ будет прерван. В поле 'Thread Count' можно ввести количество параллельно запускаемых процессов ядра анализатора, которые будут задействованы при анализе.
License
Во вкладке License можно ввести имя пользователя и лицензионный ключ из своей лицензии. Если вы ввели валидные данные, то у вас отобразится сообщение с данными лицензии.
Other
Documentation language. Настройка позволяет задать язык для встроенной справки по диагностическим сообщениям PVS-Studio, доступных на нашем сайте.
Данная настройка не меняет язык интерфейса расширения PVS-Studio или выдаваемых анализатором диагностических сообщений.
Source Tree Root. Для работы с отчётом PVS-Studio, содержащим пути до файлов в относительной форме нужно заменить их на абсолютные. Настройка позволяет задать директорию, относительно которой раскрываются все пути в файле отчёта.
Детальное описание использования относительных путей в файлах отчётов PVS-Studio смотрите здесь.
Security Related Issues. Сообщения в отчёте, классифицируемые по ГОСТ Р 71207-2024, будут выделены дополнительной маркировкой в столбце 'SAST'.