Главная
>
Документация
>
Как запустить PVS-Studio в Linux и macOS


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

Введение

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

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

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

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

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

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

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

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

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

JSON Compilation Database

На этой странице приведены инструкции для запуска анализа на основе файлов compile_commands.json. Он подходит для широко используемых инструментов сборки, таких как: CMake, Ninja, GNU Make, Qt Build System, Xcode.

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

Для работы этого метода необходима установленная утилита 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-файла (например, '@/путь/до/файла.txt'). Аргументы в 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 ...

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

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

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

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

Как выглядит интеграция с CLion, QtCreator и Eclipse CDT

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

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

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

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

Инструкция по проверке CMake проектов в среде Qt Creator находится на странице "Использование PVS-Studio в среде Qt Creator".

Для QtCreator существует расширение PVS-Studio for QtCreator, о нём больше информации тут.

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

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

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

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

В связи с этим, у нас есть ограничения на передаваемые параметры компиляции. К ним относятся параметры, мешающие запуску компилятора в режиме препроцессора, либо "портящие" вывод препроцессора. Ряд флажков оптимизации и отладки, например, -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 (обязателен) задаёт язык проверяемого файла, который анализатор ожидает найти при его разборе. Возможные значения: 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-ий уровень). При работе на больших проектах анализатор может выдать большое число предупреждений. Используйте эту настройку, если вы не можете исправить все сообщения анализатора сразу, и вам нужно сконцентрироваться на правке наиболее важных срабатываний в первую очередь.

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

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

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

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

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

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

Утилита Plog Converter

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Рисунок 7 - Пример простой Html страницы

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

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

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

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

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

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

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

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

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

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

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

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

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

Утилита blame-notifier предназначена для автоматизации процесса оповещения разработчиков, заложивших в репозиторий код, на который анализатор PVS-Studio выдал предупреждения. Отчет анализатора подается на вход blame-notifier с указанием дополнительных параметров; утилита находит файлы, в которых были обнаружены предупреждения и формирует HTML-отчет на каждого "виновного" разработчика. Также возможен вариант рассылки полного отчета: внутри него будут содержаться все предупреждения, относящиеся к каждому "виновному" разработчику.

Способы установки и использования утилиты описаны в соответствующем разделе документации: "Оповещение команд разработчиков (утилита 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. Анализ проекта без интеграции в сборочную систему - сложная задача, а с этой опцией анализатору удаётся получить важную информацию о компиляции проекта.

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

Заключение

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