Как запустить PVS-Studio в Linux


Введение

Статический анализатор С/C++ кода PVS-Studio для Linux представляет собой консольное приложение с именем pvs-studio. Для работы программы необходимо иметь установленный компилятор GCC или Clang, файл лицензии PVS-Studio.lic и конфигурационный файл PVS-Studio.cfg.

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

Существуют два основных режима работы анализатора в среде Linux:

Установка и обновление PVS-Studio

Примеры команд для установки анализатора из пакетов и репозиториев приведены на этой странице.

Как посмотреть срок действия лицензии

Лицензионный ключ к анализатору представляет собой текстовой файл в кодировке UTF8.

Проверить срок действия лицензии можно с помощью следующей команды:

pvs-studio --license-info /path/to/PVS-Studio.lic

Вы можете запросить лицензию для знакомства с PVS-Studio по электронной почте support@viva64.com или через форму обратной связи.

Поддерживаемые версии GCC и Clang

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

По умолчанию препроцессор берётся из переменных окружения CC/CXX. Если таковых не задано, то используются gcc и g++ или clang и clang++, доступные через переменную окружения PATH.

Быстрый старт

Лучшим способом использования анализатора является интеграция в сборочную систему. Следует прописать вызов анализатора рядом с вызовом компилятора. Но если необходимо быстро попробовать анализатор на небольшом проекте, то можно воспользоваться утилитой pvs-studio-analyzer.

Важно. Проект должен успешно компилироваться и быть собран перед анализом.

CMake-проект

Для проверки 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

CMake/Ninja-проект

Для проверки 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

Любой проект

Для работы этой утилиты необходим установленная утилита strace.

Собрать проект можно с помощью команды:

$ pvs-studio-analyzer trace -- make

Вместо команды make может быть любая команда запуска сборки проекта со всеми необходимыми параметрами, например:

$ pvs-studio-analyzer trace -- make debug -j2

После сборки проекта необходимо выполнить команды:

$ 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 trace -- ...
$ 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 ...

При интеграции анализатора в сборочную систему проблем с кросс-компиляторами не возникает.

Конфигурационный файл *.cfg

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

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

Возможные значения настроек в конфигурационном файле:

  • exclude-path (опционально) задаёт директорию, файлы из которой проверять не надо. Обычно это каталоги системных файлов или подключаемых библиотек. Параметров exclude-path может быть несколько.
  • platform (обязателен) задаёт используемую платформу. Возможные варианты: linux32 или linux64.
  • preprocessor (обязателен) задаёт используемый препроцессор. Возможные варианты: gcc или clang.
  • language (обязателен) задаёт язык проверяемого файла, который анализатор ожидает найти при его разборе. Возможные значения: C, C++. Поскольку каждый из поддерживаемых языковых диалектов содержит специфичные ключевые слова, неправильное указание данного параметра может привести к ошибкам разбора кода V001.
  • lic-file (обязателен) содержит абсолютный путь до файла с лицензией.
  • analysis-mode (опционально) задаёт тип выдаваемых предупреждений. Рекомендуется использовать значение "4" (General Analysis, подходит подавляющему большинству пользователей).
  • output-file (опционально) задаёт полный путь к файлу, в который будет записываться отчёт работы анализатора. При отсутствии этого параметра в конфигурационном файле все сообщения о найденных ошибках будут выводиться в консоль.
  • sourcetree-root (опционально) по умолчанию, при генерации диагностических сообщений, PVS-Studio выдаёт абсолютные, полные пути до файлов, в которых анализатор нашёл ошибки. С помощью данной настройки можно задать корневую часть пути, которую анализатор будет автоматически подменять на специальный маркер. Например, абсолютный путь до файла /home/project/main.cpp будет заменён на относительный путь |?|/main.cpp, если /home/project был указан в качестве корня.
  • cl-params (опционально) должен содержать оригинальные параметры компиляции исходного файла. Недопустимые параметры для работы анализатора приведены в разделе документации "Параметры препроцессора".
  • source-file (обязателен) содержит абсолютный путь до проверяемого исходного файла.
  • skip-cl-exe (опционально) указывает анализатору, что этап препроцессирования можно пропустить и сразу приступить к проверке.
  • i-file (опционально) содержит абсолютный путь до препроцессированного файла.

Важное примечание:

Не обязательно создавать новый конфигурационный файл для проверки каждого файла. В него достаточно сохранить постоянные настройки, например, lic-file и т.п. Изменяемые параметры можно передавать напрямую анализатору, например, так:

$ pvs-studio --cfg PVS-Studio.cfg --source-file
/home/user/Documents/src/source.cpp --cl-params -c -Wall
-std=c++11 /home/user/Documents/src/source.cpp

Параметры препроцессора

Анализатор проверяет не исходные файлы, а препроцессированные файлы. Такой способ позволяет проводить более глубокий и качественный анализ исходного кода.

В связи с этим, у нас есть ограничения на передаваемые параметры компиляции. К ним относятся параметры, мешающие запуску компилятора в режиме препроцессора, либо "портящие" вывод препроцессора. Например, параметр, "-o" не должен быть передан в --cl-params, т.к. анализатор перенаправляет вывод препроцессора в текстовой файл (препроцессированный), вместо бинарного объектного файла. Ряд флажков оптимизации и отладки, например, -O2, -O3, -g3, -ggdb3 и другие, вносят изменения, "портящие" вывод препроцессора. Информация о недопустимых параметрах будет выведена анализатором при их обнаружении.

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

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

Настройки PVS-Studio для проверки исходного файла

Для проверки одного исходного файла при отсутствии препроцессированного файла необходимо подготовить конфигурационный файл следующего вида:

exclude-path = /usr/include/
platform = linux64
preprocessor = gcc
analysis-mode=4
language = C++
lic-file = /home/user/Documents/PVS-Studio/PVS-Studio.lic
output-file = /home/user/Documents/src/project.log
cl-params = -c -Wall -std=c++11 /home/user/Documents/src/source.cpp
source-file = /home/user/Documents/src/source.cpp

Настройки PVS-Studio для проверки препроцессированного файла

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

exclude-path = /usr/include/
skip-cl-exe = yes
platform = linux64
preprocessor = gcc
analysis-mode=4
language = C++
lic-file = /home/user/Documents/PVS-Studio/PVS-Studio.lic
output-file = /home/user/Documents/src/project.log
source-file = /home/user/Documents/src/source.cpp
i-file = /home/user/Documents/src/source.i

Интеграция в Makefile/Makefile.am

Вызов исполняемого файла анализатора должен быть выполнен в том же месте, где и вызов компилятора. Строка запуска компилятора должна быть полностью продублирована при вызове анализатора с флагом --cl-params, за исключением выходных параметров, например -o:

.cpp.o:
  $(CXX) $(CFLAGS) $(DFLAGS) $(INCLUDES) $< -o $@
  pvs-studio --cfg $(CFG_PATH) --source-file $< --language C++
     --cl-params $(CFLAGS) $(DFLAGS) $(INCLUDES) $<

Важные примечания:

  • Путь до исходного файла, который присутствует в оригинальной строке компиляции, должен быть продублирован с флагом --source-file;
  • Настройки анализатора не должны дублироваться в параметрах командной строки и конфигурационном файле;
  • Проверка нескольких исходных файлов одним вызовом анализатора - не поддерживается.

Интеграция в CMake/CLion/QtCreator

Для проектов, использующих cmake, можно использовать модуль PVS-Studio.cmake. Примерное содержание CMakeLists.txt, использующего этот модуль:

include(PVS-Studio.cmake)
pvs_studio_add_target(TARGET analyze ALL
                      FORMAT tasklist
                      PREPROCESSOR gcc
                      LOG "/path/to/report.tasks"
                      ANALYZE main_target subtarget:path/to/subtarget
                      LICENSE "/path/to/PVS-Studio.lic"
                      CXX_FLAGS ${PREPROCESSOR_ADDITIONAL_FLAGS}
                      C_FLAGS ${PREPROCESSOR_ADDITIONAL_FLAGS}
                      CONFIG "/path/to/PVS-Studio.cfg")

Все настройки являются опциональными. Параметр ALL означает, что анализ запустится при сборке проекта (Build All).

Такой способ поддерживает инкрементальную сборку: результирующий лог будет содержать ошибки из последних версий файлов.

Можно добавить дополнительную команду, которая будет конвертировать полученный лог в необходимый формат с помощью утилиты plog-converter:

include(PVS-Studio.cmake)
pvs_studio_add_target(TARGET analyze
                      OUTPUT FORMAT errorfile
                      ANALYZE target
                      LOG target.plog
                      LICENSE "/path/to/PVS-Studio.lic")

На рисунке 1 представлен пример просмотра предупреждений анализатора в CLion:

Рисунок 1 - Просмотр предупреждений PVS-Studio в CLion

Рисунок 1 - Просмотр предупреждений PVS-Studio в CLion

На рисунке 2 представлен пример просмотра предупреждений анализатора в QtCreator:

Рисунок 2 - Просмотр предупреждений PVS-Studio в QtCreator

Рисунок 2 - Просмотр предупреждений PVS-Studio в QtCreator

Интеграция в QMake

Для qmake-проектов можно использовать файл PVS-Studio.pri. Принцип его работы похож на описанный выше CMake-модуль.

pvs_studio.target = pvs
pvs_studio.output = true
pvs_studio.license = /path/to/PVS-Studio.lic
pvs_studio.cxxflags = -std=c++14
pvs_studio.sources = $${SOURCES}
include(PVS-Studio.pri)

Интеграция PVS-Studio с системами Continuous Integration

Любой из перечисленных способов интеграции анализатора в сборочную систему можно автоматизировать в системе Continuous Integration. Это можно сделать в Jenkins, TeamCity и других, настроив автоматический запуск анализа и уведомление о найденных ошибках.

Также возможна интеграция с платформой непрерывного анализа SonarQube с помощью плагина PVS-Studio. Плагин предоставляется с анализатором в .tgz архиве, доступном для загрузки. Инструкция по настройке доступна на странице: "Интеграция результатов анализа PVS-Studio в SonarQube".

Просмотр и фильтрация отчёта анализатора

Утилита Plog Converter

Для конвертации отчёта анализатора о найденных ошибках в различные форматы (*.xml, *.tasks и т.п.) можно воспользоваться утилитой Plog Converter, которая распространяется с открытым исходным кодом.

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

В командной строке терминала выполнить:

$ plog-converter [опции] <путь к файлу с логом PVS-Studio>

Все опции могут быть указаны в произвольном порядке.

Доступные опции:

  • -t - формат вывода утилиты.
  • -o - путь к файлу, в который будет осуществляться вывод. Если пропущено, вывод будет осуществляться на стандартное устройство вывода.
  • -s - путь к файлу конфигурации. Файл аналогичен файлу конфигурации анализатора PVS-Studio.cfg. Из этого файла используется информация о корне проекта и исключённых директориях (exclude-path).
  • -r - путь до директории проекта.
  • -a - набор фильтруемых диагностических правил. Полный список: GA, 64, OP, CS. Могут использоваться в сочетании с уровнями, например: "-a GA:1,2;64:1;CS".
  • -d - список исключённых диагностик, разделённых запятыми: "-d V595,V730".
  • -e - использовать stderr вместо stdout.

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

На данный момент доступны следующие форматы:

  • xml – удобный формат для дополнительной обработки результатов анализа, поддерживается плагином для SonarQube;
  • csv - текстовый формат, предназначенный для представления табличных данных;
  • errorfile - формат вывода gcc и clang;
  • tasklist - формат ошибок, который можно открыть в QtCreator.

Результатом работы утилиты является файл с сообщениями в нужном формате, отфильтрованными по правилам, указанным в файле конфигурации.

Просмотр отчёта анализатора в QtCreator

Пример команды, которая подойдёт большинству пользователей для открытия отчёта в QtCreator:

$ plog-converter -a GA:1,2 -t tasklist
  -o /path/to/project.tasks /path/to/project.log

На рисунке 3 представлен пример просмотра .tasks файла в QtCreator:

Рисунок 3 - Просмотр .tasks файла в QtCreator

Рисунок 3 - Просмотр .tasks файла в QtCreator

Просмотр отчёта анализатора в Vim/gVim

Пример команд для открытия отчёта в редакторе 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

На рисунке 4 представлен пример просмотра .err файла в gVim:

Рисунок 4 - Просмотр .err файла в gVim

Рисунок 4 - Просмотр .err файла в gVim

Просмотр отчёта анализатора в GNU Emacs

Пример команд для открытия отчёта в редакторе 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

На рисунке 5 представлен пример просмотра .err файла в Emacs:

Рисунок 5 - Просмотр .err файла в Emacs

Рисунок 5 - Просмотр .err файла в Emacs

Просмотр отчёта анализатора в LibreOffice Calc

Пример команд для конвертации отчёта в 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. На рисунке 6 представлен пример просмотра .csv файла в LibreOffice Calc:

Рисунок 6 - Просмотр .csv файла в LibreOffice Calc

Рисунок 6 - Просмотр .csv файла в LibreOffice Calc

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

Более объёмные настройки можно сохранить в файл конфигурации со следующими опциями:

  • enabled-analyzers - опция, аналогичная опции -a в параметрах консольной строки.
  • sourcetree-root - строка, задающая путь к корню исходных файлов проверяемого проекта. Если указана неправильно, дальнейшая работа с результатом работы утилиты будет затруднена.
  • errors-off - глобально выключенные номера предупреждений, перечисленные через пробел.
  • exclude-path - файлы, путь к которым содержит одно из значений этой опции, не будут проанализированы.
  • disabled-keywords - ключевые слова. Сообщения, указывающие на строки, содержащие эти ключевые слова, будут исключены из обработки.

Имя опции отделяется от значений символом '='. Каждая опция указывается на отдельной строке. Комментарии пишутся на отдельных строках, перед комментарием ставится символ #.

Добавление своих форматов вывода

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

Создать свой класс вывода, сделав его наследником от класса IOutput, и переопределить виртуальный метод void write(const AnalyzerMessage& msg). В этом методе описать вывод сообщения в нужном формате. Поля структуры AnalyzerMessage указаны в файле analyzermessage.h. Сделать по аналогии с уже существующими классами вывода (например, XMLOutput).

В OutputFactory::OutputFactory в m_outputs добавить свой формат по аналогии с уже указанными там. Как вариант, добавить его через метод OutputFactory::registerOutput.

После этих действий формат будет доступен как значение опции -t утилиты.

Сборка из исходного кода и установка

Для компиляции утилиты требуется g++ версии 4.9 или новее и CMake. Никаких дополнительных библиотек не требуется.

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ...
make -j8
sudo make install

Описание распространённых проблем и их решение

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) для проблемного файла с исходным кодом.

Заключение

Если у вас возникли вопросы или проблемы с запуском анализатора, то напишите нам.


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

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

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

goto PVS-Studio;