Статический анализатор С/C++ кода PVS-Studio представляет собой консольное приложение с именем pvs-studio и несколько вспомогательных утилит. Для работы программы необходимо иметь настроенное окружение для сборки вашего проекта.
Для проверки каждого файла с кодом выполняется новый запуск анализатора. Результаты проверки множества исходных файлов могут дописываться в один отчёт анализатора, либо выводиться в stdout.
Существуют три основных режима работы анализатора:
Примеры команд для установки анализатора из пакетов и репозиториев приведены на этих страницах:
Вы можете запросить лицензию для знакомства с PVS-Studio через форму обратной связи.
Для сохранения информации о лицензии в файл следует воспользоваться следующей командой:
Написать нам
pvs-studio-analyzer credentials NAME KEY [-o LIC-FILE]По умолчанию будет создан файл PVS-Studio.lic в директории ~/.config/PVS-Studio/. В этом случае файл лицензии можно не указывать в параметрах запуска анализатора, он будет подхвачен автоматически.
Лицензионный ключ к анализатору представляет собой текстовый файл в кодировке UTF8.
Проверить срок действия лицензии можно с помощью следующей команды:
pvs-studio --license-info /path/to/PVS-Studio.licЛучшим способом использования анализатора является интеграция в сборочную систему. Следует прописать вызов анализатора рядом с вызовом компилятора. Но если необходимо быстро попробовать анализатор на небольшом проекте, то можно воспользоваться утилитой pvs-studio-analyzer.
Важно. Проект должен успешно компилироваться и быть собран перед анализом.
Для проверки CMake-проекта используется формат JSON Compilation Database. Для получения необходимого анализатору файла compile_commands.json необходимо добавить один флаг к вызову CMake:
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=On <src-tree-root>CMake поддерживает генерацию JSON Compilation Database для Unix Makefiles.
Запускается анализ следующими командами:
pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
-o /path/to/project.log -e /path/to/exclude-path -j<N>
plog-converter -a GA:1,2 -t tasklist
-o /path/to/project.tasks /path/to/project.logДля проверки Ninja-проекта также используется формат JSON Compilation Database. Для получения необходимого анализатору файла compile_commands.json необходимо выполнить следующие команды:
cmake -GNinja <src-tree-root>
ninja -t compdbЗапускается анализ следующими командами:
pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
-o /path/to/project.log -e /path/to/exclude-path -j<N>
plog-converter -a GA:1,2 -t tasklist
-o /path/to/project.tasks /path/to/project.logДля проверки проекта, использующего Qt Build System, необходимо выполнить следующие команды:
qbs generate --generator clangdbЗапускается анализ следующими командами:
pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
-o /path/to/project.log -e /path/to/exclude-path -j<N>
plog-converter -a GA:1,2 -t tasklist
-o /path/to/project.tasks /path/to/project.logС помощью утилиты xcpretty необходимо сгенерировать JSON Compilation Database:
xcodebuild [flags] | xcpretty -r json-compilation-databaseЗапускается анализ следующими командами:
pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
-f build/reports/compilation_db.json
-o /path/to/project.log -e /path/to/exclude-path -j<N>
plog-converter -a GA:1,2 -t tasklist
-o /path/to/project.tasks /path/to/project.logДля работы этой утилиты необходим установленная утилита strace.
Собрать проект можно с помощью команды:
pvs-studio-analyzer trace -- makeВместо команды make может быть любая команда запуска сборки проекта со всеми необходимыми параметрами, например:
pvs-studio-analyzer trace -- make debugПосле сборки проекта необходимо выполнить команды:
pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
-o /path/to/project.log -e /path/to/exclude-path -j<N>
plog-converter -a GA:1,2 -t tasklist
-o /path/to/project.tasks /path/to/project.logПредупреждения анализатора будут сохранены в указанный project.tasks файл. Разные способы просмотра и фильтрации полученного отчёта приведены в разделе этого документа "Просмотр и фильтрация отчёта анализатора".
Если у вас не CMake проект или возникли проблемы с системной утилитой strace, то можно попробовать сгенерировать файл compile_commands.json с помощью утилиты Bear. Этот файл поможет анализатору успешно проверить проект только в том случае, если переменные окружения не влияют на компиляцию файлов.
В таком случае компиляторы могут иметь специальные имена и анализатор не сможет их найти. Для проверки такого проекта необходимо явно перечислить имена компиляторов без путей:
pvs-studio-analyzer analyze ... --compiler COMPILER_NAME
--compiler gcc --compiler g++ --compiler COMPILER_NAME
plog-converter ...Также при использовании кросс-компиляторов изменится каталог с заголовочными файлами компилятора. Чтобы анализатор не выдавал предупреждения на эти файлы, необходимо исключить такие директории из анализа с помощью флага -e:
pvs-studio-analyzer ... -e /path/to/exclude-path ...При интеграции анализатора в сборочную систему проблем с кросс-компиляторами не возникает.
Вы можете передавать response-файлы в pvs-studio-analyzer. Response-файл – это файл, содержащий аргументы командной строки.
Response-файл можно передать через параметр командной строки, который начинается на символ '@'. После этого символа следует путь до response-файла (например, '@/путь/до/файла.txt'). Аргументы в response-файле разделены пробелами/табуляцией/переносами строк. Если вы хотите передать аргумент, который содержит пробельный символ, то вы можете экранировать этот символ с помощью обратного слэша (\) или обернуть весь аргумент в одинарные ('') или двойные ("") кавычки. Кавычки внутри кавычек экранировать нельзя. Разницы между одинарными и двойными кавычками нет. Обратите внимание, что аргументы передаются без изменений, подстановок значений переменных среды и раскрытия glob'ов не происходит. Рекурсивные response-файлы поддерживаются.
Для утилиты pvs-studio-analyzer доступен режим инкрементального анализа (анализ только изменённых файлов). Для этого необходимо запустить утилиту с параметром --incremental:
pvs-studio-analyzer analyze ... -incremental ...Этот режим работает независимо от инкрементальной сборки проекта. Т.е. если Ваш проект полностью скомпилирован, то первый запуск инкрементального анализа всё равно будет анализировать все файлы. А при следующем запуске будут анализироваться только изменённые.
Для отслеживания изменённых файлов, анализатор сохраняет служебную информацию в каталоге с именем .PVS-Studio в директории запуска. Поэтому для использования этого режима необходимо всегда запускать анализатор в одной и той же директории.
Тестовые проекты доступны в официальном репозитории PVS-Studio на GitHub:
На рисунке 1 представлен пример просмотра предупреждений анализатора в CLion:
Рисунок 1 - Просмотр предупреждений PVS-Studio в CLion
На рисунке 2 представлен пример просмотра предупреждений анализатора в QtCreator:
Рисунок 2 - Просмотр предупреждений PVS-Studio в QtCreator
На рисунке 3 представлен пример просмотра предупреждений анализатора в Eclipse CDT:
Рисунок 3 - Просмотр предупреждений PVS-Studio в Eclipse CDT
Анализатор проверяет не исходные файлы, а препроцессированные файлы. Такой способ позволяет проводить более глубокий и качественный анализ исходного кода.
В связи с этим, у нас есть ограничения на передаваемые параметры компиляции. К ним относятся параметры, мешающие запуску компилятора в режиме препроцессора, либо "портящие" вывод препроцессора. Ряд флажков оптимизации и отладки, например, -O2, -O3, -g3, -ggdb3 и другие, вносят изменения, "портящие" вывод препроцессора. Информация о недопустимых параметрах будет выведена анализатором при их обнаружении.
Этот факт ни в коем случае не обязывает вносить изменения в настройки проверяемого проекта, но для правильного запуска анализатора часть параметров необходимо исключить.
При интеграции анализатора в сборочную систему ему необходимо передать файл с настройками (*.cfg). Имя конфигурационного файла может быть произвольным, и его необходимо передать с флагом "--cfg".
Файл настроек с именем PVS-Studio.cfg, находящийся в одной директории с исполняемым файлом анализатора, может быть загружен автоматически без передачи через параметры командной строки.
Возможные значения настроек в конфигурационном файле:
Важное примечание:
Не обязательно создавать новый конфигурационный файл для проверки каждого файла. В него достаточно сохранить постоянные настройки, например, lic-file и т.п.
Любой из перечисленных способов интеграции анализатора в сборочную систему можно автоматизировать в системе Continuous Integration. Это можно сделать в Jenkins, TeamCity и других, настроив автоматический запуск анализа и уведомление о найденных ошибках.
Также возможна интеграция с платформой непрерывного анализа SonarQube с помощью плагина PVS-Studio. Плагин предоставляется с анализатором в .tgz архиве, доступном для загрузки. Инструкция по настройке доступна на странице: "Интеграция результатов анализа PVS-Studio в SonarQube".
Для конвертации отчёта анализатора о найденных ошибках в различные форматы (*.xml, *.tasks и т.п.) можно воспользоваться утилитой Plog Converter, которая распространяется с открытым исходным кодом.
В командной строке терминала выполнить:
plog-converter [опции] <путь к файлу с логом PVS-Studio>Все опции могут быть указаны в произвольном порядке.
Доступные опции:
Детальное описание уровней достоверности предупреждений и наборов диагностических правил приведено в разделе документации "Знакомство со статическим анализатором кода PVS-Studio".
На данный момент доступны следующие форматы:
Результатом работы утилиты является файл с сообщениями в нужном формате, отфильтрованными по правилам, указанным в файле конфигурации.
Пример команды, которая подойдёт большинству пользователей для открытия отчёта в QtCreator:
plog-converter -a GA:1,2 -t tasklist
-o /path/to/project.tasks /path/to/project.logНа рисунке 3 представлен пример просмотра .tasks файла в QtCreator:
Рисунок 4 - Просмотр .tasks файла в QtCreator
Конвертер отчётов анализатора позволяет генерировать Html отчёт двух видов:
1. FullHtml - полноценный отчёт для просмотра результатов анализа. Есть возможность поиска и сортировки сообщений по типу, файлу, уровню, коду и тексту предупреждения. Особенностью этого отчёта является возможность навигации к месту ошибки в файле с исходным кодом. Сами файлы с исходным кодом, на которых были предупреждения анализатора, копируются в html и являются частью отчёта. Примеры отчёта приведены на рисунках 4-5.
Рисунок 4 - Пример главной страницы Html отчёта
Рисунок 5 - Просмотр предупреждения в коде
Пример команды для получения такого отчёта:
plog-converter -a GA:1,2 -t fullhtml
/path/to/project.log -o /path/to/report_dirТакой отчёт удобно рассылать в архиве или предоставлять к нему доступ по локальной сети с помощью любого веб-сервера, например, Lighttpd и т.п.
2. Html - легковесный отчёт, состоящий из одного файла в формате .html. Содержит краткую информацию о найденных предупреждениях и подходит для уведомления о результатах по электронной почте. Пример отчёта приведен на рисунке 6.
Рисунок 6 - Пример простой Html страницы
Пример команды для получения такого отчёта:
plog-converter -a GA:1,2 -t html
/path/to/project.log -o /path/to/project.htmlПример команд для открытия отчёта в редакторе gVim:
$ plog-converter -a GA:1,2 -t errorfile
-o /path/to/project.err /path/to/project.log
$ gvim /path/to/project.err
:set makeprg=cat\ %
:silent make
:cwНа рисунке 7 представлен пример просмотра .err файла в gVim:
Рисунок 7 - Просмотр .err файла в gVim
Пример команд для открытия отчёта в редакторе Emacs:
plog-converter -a GA:1,2 -t errorfile
-o /path/to/project.err /path/to/project.log
emacs
M-x compile
cat /path/to/project.err 2>&1На рисунке 8 представлен пример просмотра .err файла в Emacs:
Рисунок 8 - Просмотр .err файла в Emacs
Пример команд для конвертации отчёта в CSV формат
plog-converter -a GA:1,2 -t csv
-o /path/to/project.csv /path/to/project.logПосле открытия файла project.csv в LibreOffice Calc необходимо добавить автофильтр: Menu Bar --> Data --> AutoFilter. На рисунке 9 представлен пример просмотра .csv файла в LibreOffice Calc:
Рисунок 9 - Просмотр .csv файла в LibreOffice Calc
Более объёмные настройки можно сохранить в файл конфигурации со следующими опциями:
Имя опции отделяется от значений символом '='. Каждая опция указывается на отдельной строке. Комментарии пишутся на отдельных строках, перед комментарием ставится символ #.
Для добавления своего формата вывода следует выполнить следующие действия:
Создать свой класс вывода, сделав его наследником от класса IOutput, и переопределить виртуальный метод void write(const AnalyzerMessage& msg). В этом методе описать вывод сообщения в нужном формате. Поля структуры AnalyzerMessage указаны в файле analyzermessage.h. Сделать по аналогии с уже существующими классами вывода (например, XMLOutput).
В OutputFactory::OutputFactory в m_outputs добавить свой формат по аналогии с уже указанными там. Как вариант, добавить его через метод OutputFactory::registerOutput.
После этих действий формат будет доступен как значение опции -t утилиты.
Утилита blame-notifier предназначена для автоматизации процесса оповещения разработчиков, заложивших в репозиторий код, на который анализатор PVS-Studio выдал предупреждения. Отчет анализатора подается на вход blame-notifier с указанием дополнительных параметров; утилита находит файлы, в которых были обнаружены предупреждения и формирует HTML-отчет на каждого "виновного" разработчика. Также возможен вариант рассылки полного отчета: внутри него будут содержаться все предупреждения, относящиеся к каждому "виновному" разработчику.
Способы установки и использования утилиты описаны в соответствующем разделе документации: "Оповещение команд разработчиков (утилита blame-notifier)".
Массовое подавление предупреждений позволяет легко внедрить анализатор в любой проект и сразу начать получать выгоду от этого, т.е. находить новые ошибки. Этот механизм позволяет запланировать исправление пропущенных предупреждений в будущем, не отвлекая разработчиков от выполнения текущих задач.
Есть несколько способов использования этого механизма, в зависимости от варианта интеграции анализатора.
Для подавления всех предупреждений анализатора (первый раз и в последующих случаях) необходимо выполнять команду:
pvs-studio-analyzer suppress /path/to/report.logЕсли вы хотите подавить предупреждение для какого-либо конкретного файла, воспользуйтесь флагом --file(-f):
pvs-studio-analyzer suppress -f test.c /path/to/report.logПомимо самого файла, вы можете явно указать номер строки для подавления:
pvs-studio-analyzer suppress -f test.c:22 /path/to/report.logПри такой записи будут подавлены все предупреждения, которые находятся на строке 22 файла 'test.c'.
Этот флаг можно указывать несколько раз, тем самым подавив предупреждения сразу в нескольких файлах.
Помимо явного указания файла, есть механизм подавления конкретных диагностик:
pvs-studio-analyzer suppress -v512 /path/to/report.logФлаг --warning(-v) так же можно указывать несколько раз:
pvs-studio-analyzer suppress -v1040 -v512 /path/to/report.logУказанные выше флаги --file и --warning можно комбинировать для более точечного подавления предупреждений:
pvs-studio-analyzer suppress -f test.c:22 -v512 /path/to/report.logТак, указанная выше команда подавит все предупреждения диагностики V512 на 22 строке файла 'test.c'.
Анализ проекта можно запускать как прежде. При этом подавленные предупреждения будут фильтроваться:
pvs-studio-analyzer analyze ... -s /path/to/suppress.json \
-o /path/to/report.log
plog-converter ...Прямая интеграция анализатора может выглядеть следующим образом:
.cpp.o:
$(CXX) $(CFLAGS) $(DFLAGS) $(INCLUDES) $< -o $@
$(CXX) $(CFLAGS) $< $(DFLAGS) $(INCLUDES) -E -o $@.PVS-Studio.i
pvs-studio --cfg $(PVS_CFG) --source-file $< --i-file $@.PVS-Studio.i
--output-file $@.PVS-Studio.logВ этом режиме анализатор не может одновременно проверять исходные файлы и фильтровать их. Поэтому для фильтрации и подавления предупреждений потребуются дополнительные команды.
Для подавления всех предупреждений анализатора также необходимо выполнять команду:
pvs-studio-analyzer suppress /path/to/report.logДля фильтрации нового лога необходимо воспользоваться следующими командами:
pvs-studio-analyzer filter-suppressed /path/to/report.log
plog-converter ...Файл с подавленными предупреждениями также имеет имя по умолчанию suppress_base.json, для которого при необходимости можно задать произвольное имя.
1. Утилита strace выдаёт сообщение вида:
strace: invalid option -- 'y'Вам необходимо обновить версию программы strace. Анализ проекта без интеграции в сборочную систему - сложная задача, а с этой опцией анализатору удаётся получить важную информацию о компиляции проекта.
2. Утилита strace выдаёт сообщение вида:
strace: umovestr: short read (512 < 2049) @0x7ffe...: Bad addressТакие ошибки возникают в системных процессах и на сборку/анализ проекта не влияют.
3. Утилита pvs-studio-analyzer выдаёт сообщение вида:
No compilation units foundАнализатору не удалось обнаружить файлы для анализа. Возможно, вы используете кросс-компиляторы для сборки проекта. Смотрите раздел "Если вы используете кросс-компиляторы" в этой документации.
4. Отчёт анализатора состоит из подобных строк:
r-vUVbw<6y|D3 h22y|D3xJGy|D3pzp(=a'(ah9f(ah9fJ}*wJ}*}x(->'2h_u(ahАнализатор сохраняет отчёт в промежуточном формате. Для просмотра отчёта его необходимо преобразовать в читабельный формат с помощью утилиты plog-converter, которая устанавливается вместе с анализатором.
5. Анализатор выдаёт ошибку:
Incorrect parameter syntax:
The ... parameter does not support multiple instances.При вызове анализатора какой-то из параметров задали несколько раз.
Такое может возникнуть, если часть параметров анализатора определили в конфигурационном файле, а часть передали через параметры командной строки. При этом случайно определив какой-нибудь параметр несколько раз.
При использовании утилиты pvs-studio-analyzer почти все параметры определяются автоматически, поэтому она может работать без конфигурационного файла. Дублирование таких параметров тоже может приводить к такой ошибке.
6. Анализатор выдаёт предупреждение:
V001 A code fragment from 'path/to/file' cannot be analyzed.Если анализатору не удаётся понять какой-нибудь фрагмент кода, то он его пропускает и выдаёт предупреждение V001. На анализ других фрагментов кода такая ситуация обычно не влияет, но если такой код находится в заголовочном файле, то таких предупреждений может быть очень много. Для поддержки проблемной конструкции пришлите нам препроцессированный файл (.i) для проблемного файла с исходным кодом.
Если у вас возникли вопросы или проблемы с запуском анализатора, то напишите нам.
