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

• Введение
• Установка и обновление PVS-Studio
• Информация о файле лицензии
• Запуск анализа
  • JSON Compilation Database
  • Трассировка компиляции (только для Linux)
  • Запуск анализа проекта
  • Если вы используете кросс-компиляторы
  • Response-файлы
• Режим инкрементального анализа
• Режим анализа списков файлов
• Интеграция PVS-Studio в сборочные системы и IDE
  • Примеры интеграции в CMake, QMake, Makefile и WAF
  • Интеграция с CLion и Qt Creator
  • Параметры препроцессора
  • Конфигурационный файл *.cfg
• Интеграция PVS-Studio с системами Continuous Integration
• Просмотр и фильтрация отчёта анализатора
  • Утилита Plog Converter
  • Просмотр отчёта анализатора в Qt Creator
  • Просмотр HTML-отчёта в браузере или почтовом клиенте
  • Просмотр отчёта анализатора в Vim и gVim
  • Просмотр отчёта анализатора в GNU Emacs
  • Просмотр отчёта анализатора в LibreOffice Calc
• Рассылка результатов анализа (утилита blame-notifier)
• Массовое подавление сообщений анализатора
  • Прямая интеграция анализатора в сборочную систему
• Описание распространённых проблем и их решение

Введение

Статический анализатор PVS-Studio для С и C++ представляет собой консольное приложение pvs-studio и набор вспомогательных утилит. Также доступны интеграции с VS Code, Qt Creator и CLion в виде плагинов, предоставляющие удобный интерфейс для анализа проектов. Чтобы программа работала, необходимо настроить окружение для сборки вашего проекта.

A new run of the analyzer is performed for every code file. The analysis results of several source code files can be added to one analyzer report or displayed in stdout.

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

• Анализ проекта с помощью утилиты pvs-studio-analyzer;
• Интеграция анализатора с помощью модуля для CMake;
• Прямая интеграция ядра PVS-Studio в сборочную систему.

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

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

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

Информация о файле лицензии

Для ознакомления с PVS-Studio можно запросить лицензию через форму обратной связи. Подробнее о том, как ввести полученную лицензию на Linux и macOS, можно прочитать здесь.

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

Перед запуском анализа выполните один из следующих шагов для получения модели сборки проекта.

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

JSON Compilation Database

Для анализа проектов можно заранее сгенерировать файл compile_commands.json.

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

• CMake,
• Ninja,
• GNU Make,
• Qt Build System,
• Xcode.

На этой странице вы можете найти руководство по тому, как запускать анализ при помощи compile_commands.json файлов.

Примечание. Подход упрощает анализ, т.к. запуски компилятора не нуждаются в полной трассировке.

Трассировка компиляции (только для Linux)

Если сгенерировать файл compile_commands.json невозможно, воспользуйтесь режимом трассировки компиляции. Для его работы необходима установить утилиту strace. С её помощью анализатор собирает необходимую информацию о компиляции проекта во время его сборки.

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

Собрать проект и отследить процесс его компиляции можно с помощью команды:

pvs-studio-analyzer trace -- make

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

Например:

pvs-studio-analyzer trace -- make debug

В результате трассировки по умолчанию будет сформирован файл strace_out. Подробнее о режиме трассировки можно узнать в документации.

Запуск анализа проекта

После получения файла трассировки компиляции strace_out или JSON Compilation Database compile_commands.json можно запустить анализ следующими командами:

pvs-studio-analyzer analyze -o /path/to/PVS-Studio.log \
                            -e /path/to/exclude-path \
                            -j<N>
plog-converter -a GA:1,2 \
               -t json \
               -o /path/to/Analysis_Report.json \
               /path/to/PVS-Studio.log

Режим analyze предполагает наличие файлов strace_out или compile_commands.json в текущем рабочем каталоге. Можно явно указать расположение одного из этих файлов при помощи флага ‑‑file (-f).

Предупреждения анализатора будут сохранены в указанный Analysis_Report.json файл. Разные способы просмотра и фильтрации полученного отчёта приведены в разделе "Просмотр и фильтрация отчёта анализатора".

Если вы используете кросс-компиляторы

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

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

Если pvs-studio-analyzer неправильно определяет тип кросс-компилятора и, как следствие, неправильно запускает препроцессор, попробуйте явно указать его через этот флаг:

pvs-studio-analyzer analyze ... --compiler CustomCompiler=gcc

Теперь pvs-studio-analyzer запустит CustomCompiler с флагами препроцессирования gcc. Подробнее об этом можно прочитать в документации.

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

Response-файлы

Вы можете передавать response-файлы в pvs-studio-analyzer. Response-файл — это файл, содержащий аргументы командной строки.

Response-файл можно передать через параметр командной строки, который начинается с символа @. После следует путь до response-файла, например, @/path/to/file.rsp. Аргументы в response-файле разделены пробелами, табуляцией или переносами строк. Если вы хотите передать аргумент, который содержит пробельный символ, то экранируйте этот символ с помощью обратного слэша \ или оберните весь аргумент в одинарные '' или двойные "" кавычки. Однако кавычки внутри кавычек экранировать нельзя. Разницы между одинарными и двойными кавычками нет. Обратите внимание, что аргументы передаются без изменений: подстановок значений переменных среды и раскрытия glob не происходит. Рекурсивные response-файлы также поддерживаются.

Режим инкрементального анализа

Для утилиты pvs-studio-analyzer доступен режим инкрементального анализа, т.е. анализ только изменённых файлов. Для этого запустите утилиту с параметром ‑‑incremental:

pvs-studio-analyzer analyze ... --incremental ...

Этот режим работает независимо от инкрементальной сборки проекта, т.е. если ваш проект полностью скомпилирован, то первый запуск инкрементального анализа всё равно будет анализировать все файлы. При следующем запуске будут анализироваться только изменённые.

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

Режим анализа списков файлов

Утилита pvs-studio-analyzer поддерживает режим анализа списка файлов, при помощи которого можно настроить анализатор для проверки коммитов и pull requests. Для анализа запустите утилиту с параметром ‑‑source-files или -S и укажите путь к файлу со списком исходных файлов для анализа:

pvs-studio-analyzer analyze ... -S source_file_list ...

Более подробно изучить анализ списков файлов можно в документации.

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

Примеры интеграции в CMake, QMake, Makefile и WAF

Тестовые проекты доступны в официальном репозитории PVS-Studio на GitHub:

• pvs-studio-cmake-examples, сам CMake модуль в GitHub репозитории;
• pvs-studio-qmake-examples;
• pvs-studio-makefile-examples;
• pvs-studio-waf-examples.

Интеграция с CLion и Qt Creator

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

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

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

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

Вы можете ознакомиться с инструкция по проверке CMake проектов в среде Qt Creator в документации. "Интеграция с Qt Creator без использования плагина PVS-Studio".

Для Qt Creator существует расширение PVS-Studio, подробнее о нём можно прочитать в документации.

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

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

В связи с этим действуют ограничения на передаваемые параметры компиляции. К ним относятся параметры, мешающие запуску компилятора в режиме препроцессора или искажающие его вывод. Например, ряд флагов оптимизации и отладки — такие как -O2, -O3, -g3, -ggdb3 и другие — могут нарушить вывод препроцессора. При обнаружении недопустимых параметров анализатор выдаст соответствующее предупреждение.

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

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

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

В конфигурационном файле можно установить следующие настройки:

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

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

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

Также возможна интеграция с платформой непрерывного анализа SonarQube с помощью плагина PVS-Studio. Более подробная информация о нём доступна на этой странице.

Результаты анализа PVS-Studio можно загружать в DevSecOps-платформы DefectDojo, SonarQube, CodeChecker, AppSec.Hub, Hexway и Securitm, преобразовав в специальный формат. Подробнее об интеграции отчётов можно прочесть в документации.

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

Утилита Plog Converter

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

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

Для просмотра отчёта анализатора можно воспользоваться плагином Qt Creator. Подробнее о плагине для Qt Creator можно прочитать в документации.

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

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

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

Рисунок 3 — Просмотр .tasks файла в Qt Creator

Просмотр HTML-отчёта в браузере или почтовом клиенте

Конвертер отчётов анализатора позволяет генерировать HTML-отчёт двух видов:

1. FullHtml — полноценный отчёт для просмотра результатов анализа. Он поддерживает поиск и сортировку предупреждений по типу, файлу, уровню, коду и сообщению предупреждения. Особенностью этого отчёта является возможность навигации к месту ошибки в файле с исходным кодом. Сами файлы с исходным кодом, содержащие предупреждения анализатора, копируются в HTML и становятся частью отчёта. Примеры отчёта приведены на рисунках 4–5.

Рисунок 4 — Пример главной страницы HTML-отчёта

Рисунок 5 — Просмотр предупреждения в коде

Пример команды для получения отчёта:

plog-converter -a GA:1,2 -t fullhtml \
               -o /path/to/report_dir \
               /path/to/project.log

Такой отчёт удобно рассылать в архиве или предоставлять к нему доступ по локальной сети с помощью любого веб-сервера, например, Lighttpd.

2. Html — упрощённый вариант предыдущего отчёта, состоящий из одного файла в формате .html. Содержит краткую информацию о найденных предупреждениях и подходит для уведомления о результатах по электронной почте. Пример отчёта приведен на рисунке 6.

Рисунок 6 — Пример простой HTML-страницы

Пример команды для получения отчёта:

plog-converter -a GA:1,2 -t html \
               -o /path/to/project.html \
               /path/to/project.log

Просмотр отчёта анализатора в 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

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

Рисунок 7 — Просмотр .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

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

Рисунок 8 — Просмотр .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. На рисунке 9 представлен пример файла .csv в LibreOffice Calc:

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

Рассылка результатов анализа (утилита blame-notifier)

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

• отчёт анализатора передаётся утилите blame-notifier с указанием дополнительных параметров;
• утилита находит файлы с предупреждениями и формирует HTML-отчёты, сгруппированными по авторам изменений;
• HTML-отчёты отправляются через указанный SMTP-сервер всем авторам, указанным в специальном файле.

Также возможна рассылка полного отчёта, содержащего все предупреждения, сгруппированные по авторам.

Способы установки и использования утилиты описаны в соответствующем разделе документации: "Оповещение команд разработчиков (утилита blame-notifier)".

Массовое подавление сообщений анализатора

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

Есть несколько способов использования этого механизма в зависимости от варианта интеграции анализатора. Подробнее о том, как использовать механизм подавления в pvs-studio-analyzer можно узнать в документации.

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

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

.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_file.suppress.json, однако при необходимости можно задать произвольное имя.

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

1. Утилита strace выдаёт сообщение вида:

strace: invalid option -- 'y'

Обновите программу strace до минимально поддерживаемой версии 4.7. Поскольку анализ проекта без интеграции в сборочную систему представляет собой сложную задачу, данная опция помогает анализатору извлечь важную информацию о компиляции.

2. Утилита strace выдаёт сообщение вида:

strace: umovestr: short read (512 < 2049) @0x7ffe...: Bad address

Такие ошибки возникают в системных процессах и на сборку/анализ проекта не влияют.

3. Утилита pvs-studio-analyzer выдаёт сообщение вида:

No compilation units found

Анализатору не удалось обнаружить файлы для анализа. Возможно, вы используете кросс-компиляторы для сборки проекта. Подробнее об этом можете прочитать в этом разделе.

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

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. Обычно это не влияет на анализ других частей кода, но если проблемный фрагмент находится в заголовочном файле, количество таких предупреждений может значительно возрасти. Для исправления проблемы пришлите нам препроцессированный (*.PVS-Studio.i) и конфигурационный (*.PVS-Studio.cfg) файлы для проблемного файла с исходным кодом через форму обратной связи.