Встраивание PVS-Studio в процесс непрерывной интеграции


В данной статье рассматривается встраивание PVS-Studio в процесс непрерывной интеграции в среде Windows. Встраивание в процесс CI в среде Linux описано в статье "Как запустить PVS-Studio в Linux".

Наиболее эффективный сценарий использования статического анализа

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

Этот принцип происходит из того факта, что чем раньше обнаружена ошибка, тем меньше стоимость и сложность её исправления. Поэтому необходимо стремиться к как можно более раннему обнаружению и исправлению ошибок, для чего и необходимо использование PVS-Studio на машинах разработчиков. Рекомендуется использование режима инкрементального анализа, позволяющего автоматически запускать проверку только изменённого кода после сборки проекта.

Тем не менее использование PVS-Studio на машинах разработчиков не исключает возможности попадания ошибок в систему контроля версий. Для отслеживания таких ситуаций и нужно иметь второй уровень защиты - регулярный запуск статического анализатора на сборочном сервере. Даже в случае попадания ошибки в систему контроля версий, её удастся своевременно выявить и исправить. Встраивание анализа в процесс ночных сборок позволит на следующий день получать информацию обо всех ошибках, допущенных в течение прошлого дня, и оперативно поправить проблемный код.

Примечание. Не рекомендуется конфигурировать статический анализ кода на сервере таким образом, чтобы он запускался на каждый коммит, так как анализ может занимать продолжительное время. Если необходим именно такой сценарий использования и при этом сборочной системой проекта является MSBuild, можно воспользоваться режимом инкрементального анализа command line модуля 'PVS-Studio_Cmd.exe'. За дополнительной информацией обратитесь к разделу "Инкрементальный анализ в command line модуле 'PVS-Studio_Cmd.exe'" текущего документа. Также для анализа файлов при инкрементальной сборке (вне зависимости от сборочной системы) можно использовать утилиту 'CLMonitor.exe' (только для анализа C, C++ кода). Более подробно использование утилиты 'CLMonitor.exe' описано в разделе "Система мониторинга компиляции" текущего документа.

Подготовка к непрерывной интеграции

Подготовка к встраиванию PVS-Studio в процесс непрерывной интеграции - важный этап, позволяющий сэкономить время в дальнейшем и использовать статический анализатор более эффективно. В этом разделе будут рассмотрены те особенности настройки PVS-Studio, которые упростят последующую работу.

Автоматическое развёртывание PVS-Studio

Для установки PVS-Studio требуются права администратора. Автоматическая установка осуществляется следующей командой, выполненной в командной строке (одной строкой):

PVS-Studio_setup.exe /verysilent /suppressmsgboxes 
/norestart /nocloseapplications

Выполнение этой команды приведёт к установке всех доступных компонентов PVS-Studio. Обратите внимание, что PVS-Studio может потребоваться перезагрузка компьютера в случае, например, если обновляемые файлы были заблокированы. Если установщик запустить без флага 'NORESTART', перезагрузка может произойти без предварительных уведомлений или диалогов.

В состав дистрибутива входит утилита 'PVS-Studio-Updater.exe', позволяющая проверять наличие обновлений анализатора, а в случае их наличия, загрузить и установить их на локальной машине. Для запуска утилиты в 'silent' режиме следует использовать те же параметры, что и для установки дистрибутива:

PVS-Studio-Updater.exe /verysilent /suppressmsgboxes

Файлы настроек и лицензии генерируются автоматически и в дальнейшем могут быть отредактированы или скопированы на другие машины. Расположение файлов по умолчанию:

%AppData%\PVS-Studio\PVS-Studio.lic
%AppData%\PVS-Studio\Settings.xml

Для более детальной информации по автоматическому развёртыванию PVS-Studio обратитесь к статье "Автоматическое развёртывание PVS-Studio".

Предварительная настройка анализатора

Перед использованием анализатора необходимо выполнить его предварительную настройку, что поможет оптимизировать работу со списком предупреждений, а также (возможно) повысить скорость проведения анализа.

Примечание. Описанные ниже опции можно изменить, напрямую отредактировав файл настроек, или воспользовавшись интерфейсом страницы настроек в плагине к Visual Studio или в Standalone приложении.

Часто бывает полезно исключить из анализа определённые файлы или даже целые директории. Это позволит не анализировать код сторонних библиотек, сократив общее время анализа, и оставив в выводе только те предупреждения, которые актуальны именно для вашего проекта. По умолчанию в настройках анализатора уже присутствуют исключения для некоторых файлов или путей, например, для библиотеки boost. Более подробно исключение файлов из анализа описано в статье "Настройки: Don't Check Files".

На этапе внедрения также следует отключить те диагностические правила PVS-Studio, которые неактуальны для проверяемого проекта. Существует возможность отключения как отдельных диагностических правил, так и целых групп. Если вы изначально знаете диагностики, неактуальные для вашего проекта (например, 64-битные ошибки), есть смысл отключить их сразу. Это также может ускорить работу анализатора. Если список таких диагностических правил неизвестен, то при необходимости их можно будет отключить позже. Более подробно отключение диагностических правил описано в статье "Настройки: Detectable Errors".

Отключение предупреждений на старый код

В случае внедрения статического анализа в существующий проект, когда объём кодовой базы уже существенен, проверка исходного кода может выявить большое количество ошибок в существующем коде. Команда разработчиков, занимающихся данным проектом, может не иметь ресурсов, необходимых для исправления всех этих предупреждений. В таком случае возникает необходимость убрать все предупреждения, обнаруженные в старом коде, чтобы с текущего момента видеть только те предупреждения анализатора, которые были выданы на вновь написанный/модифицированный код.

Достичь желаемого результата можно с использованием механизма массового подавления сообщений анализатора. Более подробно про это написано в статье: "Массовое подавление сообщений анализатора".

Примечание 1. Если необходимо скрыть только отдельные предупреждения анализатора, следует воспользоваться механизмом подавления ложных срабатываний, описанном в статье "Подавление ложных предупреждений".

Примечание 2. Используя SonarQube, можно изменять отображение предупреждений, найденных за определённый период времени. Таким образом, можно настроить отображение только тех предупреждений, которые были найдены после внедрения анализатора (т.е. отключить отображение предупреждений на старый код).

Встраивание PVS-Studio в процесс непрерывной интеграции

PVS-Studio достаточно просто встраивается в процесс непрерывной интеграции, а также предоставляет средства для удобной обработки результатов работы анализатора.

Интеграция PVS-Studio с платформой SonarQube доступна только при наличии Enterprise лицензии. Для заказа лицензии, пожалуйста, напишите нам.

Ниже будут описаны принципы анализа проектов, основанных на различных сборочных системах, а также утилиты для работы с результатами анализа.

Анализ исходного кода MSBuild / Visual Studio проектов

В данном разделе будет описан наиболее эффективный вариант анализа MSBuild / Visual Studio проектов, то есть файлов решений Visual Studio (.sln), проектов Visual C++ (.vcxproj) и Visual C# (.csproj).

Основные сведения

Анализ из командной строки проектов, перечисленных выше, производится за счёт использования модуля 'PVS-Studio_Cmd.exe', находящегося в установочной директории PVS-Studio. Расположение установочной директории по умолчанию - 'C:\Program Files (x86)\PVS-Studio\'.

Передавая модулю 'PVS-Studio_Cmd.exe' различные аргументы, можно регулировать параметры анализа. Увидеть список всех доступных аргументов можно, выполнив команду:

PVS-Studio_Cmd.exe --help

Анализатор имеет один обязательный аргумент - '--target', с помощью которого задаётся объект для проверки (.sln, .vcxproj или .csproj файл). Остальные аргументы являются опциональными и подробно описываются в статье "Проверка Visual C++ (.vcxproj) и Visual C# (.csproj) проектов из командной строки с помощью PVS-Studio".

Рассмотрим пример запуска анализа на .sln файле (одной строкой):

PVS-Studio_Cmd.exe --target "targetsolution.sln" --platform "Any CPU" 
--output "results.plog" --configuration "Release"

Исполнение этой команды запустит анализ .sln файла 'targetsolution.sln' для платформы 'Any CPU' и конфигурации 'Release'. Выходной файл ('results.plog') будет создан в директории проверяемого проекта. При анализе будут использоваться стандартные настройки анализатора, так как явно не указано обратное.

Модуль 'PVS-Studio_Cmd.exe' имеет ряд ненулевых кодов возврата, посредством которых информирует о результирующем состоянии анализа. Код возврата представляет собой битовую маску, маскирующую все возможные состояния, возникшие во время работы утилиты. То есть ненулевой код не является свидетельством того, что утилита закончила свою работу некорректно. Подробное описание кодов возврата приведено в упомянутой выше статье "Проверка Visual C++ (.vcxproj) и Visual C# (.csproj) проектов из командной строки с помощью PVS-Studio".

Получение результатов анализа только нового / модифицированного кода

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

В случае необходимости получения такого результата при запуске модуля 'PVS-Studio_Cmd.exe' необходимо указывать аргумент командной строки '--suppressAll'. При наличии этого флага все сообщения будут добавлены в базу подавленных сообщений (.suppress файлы соответствующих проектов) после сохранения результатов проверки. Следовательно, при следующей проверке эти сообщения выданы не будут. Если всё же потребуется посмотреть старые сообщения, рядом с .plog файлом, содержащим новые сообщения, будет сохранён полный лог проверки.

Механизм массового подавления предупреждений анализатора более подробно описан в статье "Массовое подавление сообщений анализатора".

Примечание. При использовании платформы SonarQube можно наблюдать только за новыми предупреждениями, не используя механизмы подавления. Для этого необходимо настроить отображение результатов анализа таким образом, чтобы видеть изменения только за последний день.

Инкрементальный анализ в command line модуле 'PVS-Studio_Cmd.exe'

Режим инкрементального анализа в PVS-Studio позволяет проверять только файлы, изменённые/затронутые с момента последней сборки проекта. Этот режим доступен как при работе с использованием плагина для Visual Studio, так и при проверке проектов с использованием command line модуля PVS-Studio. Использование режима инкрементального анализа позволит получить предупреждения только на модифицированный код, а также сократить время анализа, так как те части проекта, которые не изменялись, проанализированы не будут.

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

Использование инкрементального анализа в модуле 'PVS-Studio_Cmd.exe' регулируется с помощью флага '--incremental'. Доступны следующие режимы работы:

  • Scan - проанализировать все зависимости для определения того, на каких файлах должен быть выполнен инкрементальный анализ. Непосредственно анализ выполнен не будет.
  • Analyze - выполнить инкрементальный анализ. Этот шаг должен выполняться после выполнения шага Scan, и может выполняться как до, так и после сборки решения или проекта. Статический анализ будет выполнен только для измененных файлов с момента последней сборки.
  • ScanAndAnalyze - проанализировать все зависимости для определения того, на каких файлах должен быть выполнен инкрементальный анализ, и сразу же выполнить инкрементальный анализ измененных файлов с исходным кодом.

Для получения подробной информации об инкрементальном анализе в PVS-Studio обратитесь к статье "Режим инкрементального анализа PVS-Studio".

Примечание. При использовании режима инкрементального анализа следует учитывать некоторые особенности. Если PVS-Studio использует препроцессор Visual C++ ('cl.exe'), возможно возникновение ситуации с блокировкой файлов. Это связано с тем, что при попытке записи файла, он может быть заблокирован компилятором 'cl.exe', выполняющим препроцессирование. При использовании препроцессора Clang данная ситуация возникает значительно реже. Это следует учитывать при решении конфигурирования сервера в пользу инкрементального анализа вместо полноценного анализа по ночам.

Анализ CMake проектов

Если стоит задача анализа CMake проектов, рекомендуется генерировать из них решения для среды Visual Studio и в дальнейшем работать с ними. Это позволит полноценно использовать модуль 'PVS-Studio_Cmd.exe' и все связанные с этим фактом преимущества.

Анализ исходного кода проектов со специфичными сборочными системами

В случае, если проект не использует сборочную систему MSBuild, его не получится проанализировать с использованием command line модуля 'PVS-Studio_Cmd.exe'. Тем не менее, в состав дистрибутива входят утилиты, с помощью которых можно проверить даже проекты со специфичными сборочными системами.

Система мониторинга компиляции

Система мониторинга компиляции (PVS-Studio Compiler Monitoring, CLMonitoring) предназначена для 'бесшовной' интеграции статического анализа PVS-Studio в любую сборочную систему на ОС семейства Windows, использующую для компиляции файлов один из препроцессоров, поддерживаемых command line анализатором 'PVS-Studio.exe'.

Принцип работы сервера мониторинга (CLMonitor.exe) основан на отслеживании запуска процессов, соответствующих целевому компилятору, и сборе информации об окружении этих процессов. Сервер мониторинга отслеживает запуски процессов только для того пользователя, из-под которого он сам запущен.

Поддерживаемые компиляторы:

  • компиляторы семейства Microsoft Visual C++ (cl.exe);
  • C/C++ компиляторы из GNU Compiler Collection (gcc.exe, g++.exe);
  • компилятор Clang (clang.exe), а также компиляторы на основе Clang.

При интеграции сервера мониторинга в сборочный процесс первоначально необходимо запустить модуль 'CLMonitor.exe' с аргументом 'monitor':

CLMonitor.exe monitor

Это позволит серверу мониторинга запустить самого себя в режиме отслеживания и завершить работу, а сборочной системе - продолжить выполнять оставшиеся задачи. При этом второй (запущенный из первого) процесс CLMonitor будет оставаться запущенным и производить отслеживание сборки.

После завершения сборки необходимо запустить модуль 'CLMonitor.exe' в режиме клиента для генерации препроцессированных файлов и непосредственного запуска статического анализа:

CLMonitor.exe analyze -l "c:\ptest.plog" -u "c:\ptest.suppress" -s

Рассмотрим эту команду более подробно:

  • analyze - запуск модуля 'CLMonitor.exe' для анализа;
  • -l - полный путь до файла, в который будут записаны результаты статического анализа;
  • -u - путь до базы подавления (suppress файл);
  • -s - дописать в базу подавления все новые сообщения текущей проверки.

Более подробно использование системы мониторинга компиляции описано в статье "Система мониторинга компиляции в PVS-Studio".

Примечание. Системе мониторинга компиляции присущ ряд недостатков, связанный с естественными ограничениями такого подхода, а именно - невозможность гарантировать на 100% перехват всех запусков компилятора при сборке (например, при сильной загрузке системы). Также следует помнить о том, что если параллельно выполняются несколько сборок, система может отследить запуски компиляторов сторонней сборки.

Прямая интеграция анализатора в системы автоматизированной сборки

Примечание. Прямая интеграция анализатора возможна только для проверки С/С++ кода.

Прямая интеграция анализатора может быть необходима в случаях отсутствия возможности использования command line модуля 'PVS-Studio_Cmd.exe' (проект собирается не с помощью сборочной системы MSBuild) и системы мониторинга компиляции (см. примечание соответствующего раздела).

В таком случае может потребоваться встроить в сборочный процесс прямой вызов анализатора ('PVS-Studio.exe') и передать ему все необходимые для препроцессирования аргументы. То есть анализатор необходимо вызвать для тех же файлов, для которых вызывается компилятор.

Подробное описание прямой интеграции анализатора в системы автоматизированной сборки приведено в статье "Прямая интеграция анализатора в системы автоматизации сборки (C/C++)".

Работа с результатами анализа

Результатом работы анализатора является .plog файл, имеющий формат XML. Этот файл не предназначен для ручной обработки, например, для чтения программистом. Тем не менее, в состав дистрибутива входят специальные утилиты, цель которых - сделать работу с .plog файлом максимально удобной.

PlogConverter

Для преобразования результатов работы анализатора в один из форматов для непосредственной работы предназначена утилита 'PlogConverter.exe', входящая в состав дистрибутива. 'PlogConverter.exe' позволяет выполнять преобразование .plog файлов в следующие форматы:

  • текстовый файл с результатами анализа. Может быть удобен для вывода результатов анализа (например, новых сообщений анализатора) в лог сборочной системы \ сервера непрерывной интеграции;
  • HTML файл с гиперссылками на исходные файлы. Такой файл удобно рассылать заинтересованным разработчикам по e-mail;
  • CSV таблица с результатами анализа;
  • Tasks файл для просмотра в QtCreator;
  • текстовый файл, содержащий сводную таблицу количества сообщений на разных уровнях\группах диагностик.

Пример запуска утилиты 'PlogConverter.exe' (одной строкой):

PlogConverter.exe test1.plog -o "C:\Results" -r "C:\Test" 
-a GA:1 -t Html

Данная команда преобразует файл 'test1.plog' в формат .html с отображением диагностических правил первого уровня категории GA (диагностики общего назначения). Результат будет записан в директорию 'C:\Results'. Оригинальный .plog файл изменён не будет.

Получить подробную справка по всем параметрам утилиты 'PlogConverter' можно с помощью команды:

PlogConverter.exe --help

Примечание. Утилита 'PlogConverter' поставляется вместе с исходными файлами (C#), которые доступны в архиве 'PlogConverter_src.zip'. Для создания собственного формата вывода результатов анализа можно переиспользовать алгоритм разбора структуры .plog файла.

Более подробно утилита 'PlogConverter' описана в статье "Работа с результатами анализа (.plog файл)".

SonarQube

Результаты статического анализа могут быть импортированы платформой непрерывного анализа и измерения качества кода SonarQube. Для импорта результатов анализа предназначен плагин 'sonar-pvs-studio-plugin', входящий в состав дистрибутива. Использование плагина позволяет добавлять сообщения, найденные анализатором PVS-Studio, в базу сообщений сервера SonarQube. Это, в свою очередь, даёт возможность видеть статистику появления / исправления ошибок, осуществлять навигацию по предупреждениям анализатора, просматривать документацию к диагностическим правилам и многое другое.

Все сообщения PVS-Studio, добавленные в SonarQube, имеют тип Bug. В интерфейсе SonarQube сохранено разделение сообщений по группам диагностик аналогично тому, как это сделано в анализаторе.

Более подробная информация об интеграции результатов анализа в SonarQube приведена в статье "Интеграция результатов анализа PVS-Studio в SonarQube".

Плагин PVS-Studio для Jenkins

В настоящий момент плагин PVS-Studio для Jenkins поддерживается только на операционных системах семейства Windows.

В состав дистрибутива входит плагин 'pvs-studio.hpi', предназначенный для публикации результатов работы анализатора PVS-Studio в системе непрерывной интеграции Jenkins.

Примечание. Плагин для Jenkins позволяет публиковать результаты статического анализа, для чего он использует отчёты анализатора (.plog-файлы). Это позволяет настраивать публикацию различных результатов анализа: полного анализа проекта, инкрементального анализа (анализ только модифицированных файлов) и т.п. Соответственно, для публикации результатов различного типа анализа, необходимо только правильно настроить сам анализатор и передать плагину путь до одного или нескольких соответствующих .plog файлов (об этом будет написано ниже). Информация о проведении полного анализа описана в разделах "Анализ исходного кода MSBuild / Visual Studio проектов" и "Анализ исходного кода проектов со специфичными сборочными системами", режим инкрементального анализа описан в статье "Режим инкрементального анализа PVS-Studio".

Для установки плагина необходимо в меню настроек плагинов (Manage Jenkins - Manage Plugins), на вкладке 'Advanced' загрузить плагин (выбрать плагин в секции 'Upload Plugin' и произвести его установку, нажав кнопку 'Upload'). Jenkins выполнит установку плагина и, в случае необходимости перезагрузки сервера, сообщит об этом.

В настройках сервера ('Configure System') в разделе 'PVS-Studio Plugin Settings' необходимо задать директорию установки PVS-Studio. Директория по умолчанию - 'C:\Program Files (x86)\PVS-Studio\'.

Для публикации результатов анализа в настройках проекта необходимо добавить послесборочный шаг (секция 'Post-build Actions') 'Publish PVS-Studio analysis result'. Обязательное поле - 'Path(s) to PVS-Studio analysis report(s)', в котором задаётся путь до .plog-файла (результат работы PVS-Studio), содержимое которого и будет отображаться на странице сборки. Поддерживаются абсолютные и относительные (относительно workspace'a проекта) пути. Также поддерживаются переменные окружения Jenkins.

Если необходимо отобразить объединённые результаты из нескольких .plog-файлов, следует разделить их символом '|'.

Пример задания путей до нескольких отчётов для публикации объединённого результата:

$REPORT_PATH | D:\analysis reports\testLog.plog | .\additionalLog.plog

Дополнительные параметры ('Analyzers and levels settings', 'Excluded codes', 'Settings path') позволяют выполнить дополнительную фильтрацию предупреждений анализатора. Краткое описание этих параметров доступно прямо на форме их задания. Смысловое значение этих параметров, а также возможные значения, аналогичны параметрам 'analyzer', 'excludedCodes' и 'settings' утилиты PlogConverter и описаны в статье "Работа с результатами анализа (.plog файл)".

После успешного выполнения шага публикации результатов анализа PVS-Studio на страницах сборки будут отображаться результаты анализа. Результаты анализа сохраняются для каждой сборки, что позволит просматривать отчёт анализатора, соответствующий конкретной сборке.

В случае, если результирующий отчёт анализатора имеет большой объём, на странице сборки будет отображаться его превью, а полный отчёт будет доступен для просмотра при нажатии ссылок 'View full report' над / под превью отчёта, или 'Full PVS-Studio analysis report' в меню слева.

Рисунок 1 - Внешний вид страницы сборки с отображением результатов анализа PVS-Studio

Рисунок 1 - Внешний вид страницы сборки с отображением результатов анализа PVS-Studio

Рассылка результатов анализа

Эффективным способом оповещения разработчиков о результатах анализа является их рассылка с использованием специализированных утилит, например, SendEmail. При использовании платформы контроля качества кода SonarQube, выполнять рассылку писем можно её средствами.

Ещё одним вариантом оповещения разработчиков является использование утилиты 'BlameNotifier', поставляемой в составе дистрибутива PVS-Studio. Она позволяет формировать вариативные отчёты. Например, разработчики, заложившие код с ошибками в систему контроля версий, получат индивидуальный отчёт. Лидеры команд, руководитель разработки и т.д. могут получить полный лог отчёта, включающий в себя информацию обо всех найденных ошибках и разработчиках, которые эти ошибки допустили.

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

BlameNotifier.exe --help

Более подробно утилита 'BlameNotifier' рассматривается в статье "Работа с результатами анализа (.plog файл)" в разделе "Оповещение разработчиков".

Заключение

Если у вас остались вопросы, пожалуйста, напишите нам на почту: support@viva64.com


А ты совершаешь ошибки в коде?

Проверь с помощью
PVS-Studio

Статический анализ
кода для C, C++ и C#

goto PVS-Studio;