Главная
>
Документация
>
Анализ в режиме коммитов и слияния вето…


Анализ в режиме коммитов и слияния веток (pull/merge requests)

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

С помощью режима анализа коммитов и слияния веток можно проанализировать только те файлы, которые были изменены относительно текущего состояния ветки (в которую производится коммит или запрос на слияние). Это сократит время анализа и упростит просмотр его результатов: отчёт анализатора будет содержать предупреждения, выданные из-за ошибок в изменённых файлах.

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

Общие принципы анализа запросов на слияние

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

Рассмотрим дерево коммитов:

В данном случае была создана ветка 'quickFix'. После работы в ней открывается запрос на слияние. Для получения разницы между текущим состоянием ветки 'master' и последним коммитом в ветке 'quickFix' можно использовать следующую команду (на момент её выполнения нужно находиться в ветке 'quickFix'):

git diff --name-only HEAD master > .pvs-pr.list

Так мы получим список изменённых файлов относительно последних коммитов в ветках 'master' и 'quickFix'. Названия изменённых файлов будут сохранены в '.pvs-pr.list'.

Примечание. В примере получения файлов для анализа используется система контроля версий 'git'. Однако подойдёт любая система контроля версий, позволяющая получить список изменённых файлов.

Для проверки отправленного запроса на слияние нужно проанализировать полученный список файлов.

Получение списка изменённых файлов

В данном разделе приведены примеры команд для получения списка модифицированных файлов.

Для Git:

Для получения списка изменённых файлов перед коммитом, выполните команду:

git diff --cached --name-only > .pvs-pr.list

Для получения списка изменённых файлов между двумя коммитами, выполните команду:

git diff --name-only CommitA CommitB > .pvs-pr.list

Для SVN:

На Windows можно выполнить следующую команду в PowerShell:

Write-Host (svn status | Select-String -Pattern '^[AM]\W*(.*)' 
| %{$_.Matches.Groups[1].value})  -Separator "`b`n" > .pvs-pr.lits

На Linux:

svn status -q | grep -oP "^[M|A]\W*\K(.*)" > .pvs-pr.list

Для Mercurial:

hg log --template "{files % '{file}\n'}\n" > .pvs-pr.list

Для Perforce:

p4 diff -f -sa > .pvs-pr.list

Интеграция анализа в систему контроля версий

Большинство систем контроля версий поддерживают возможность отслеживания событий в репозитории с помощью специальных хуков. Как правило, хуки представляют из себя обычные файлы скриптов, которые запускает VCS. Они могут быть использованы как на стороне клиента (локальная машина разработчика), так и на стороне сервера системы контроля версии (если у вас развёрнут собственный сервер VCS (Version Control System)). Использование хуков на сервере VCS позволяет настроить глобальную политику для всех разработчиков компании.

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

Вы можете попробовать интегрировать PVS-Studio непосредственно на сервер VCS, следуя этому плану:

  • Определить событие, при котором следует запускать анализ. Хук должен выполняться до того, как система контроля версий применит новые изменения. Например, это может быть коммит или операция отправки изменений (push).
  • Далее нужно решить, где будет запускаться анализ. Вы можете это делать как на сервере VCS, так и на отдельной машине. Учтите, что для успешного анализа ваш проект должен собираться на той машине, на которой будет выполняться анализ.
  • Написать хук, который будет:
    • Получать список изменений при коммите или операции push. Вам может потребоваться не только список модифицированных файлов, но и сами изменения в виде patch-файла (например, требуется для Git).
    • Если вы планируете анализ на сервере VCS, вам может потребоваться иметь там же локальную копию вашего репозитория. К этой копии необходимо применить patch-файл и запустить анализ в режиме проверки списка файлов.
    • Если вы планируете запускать анализ на отдельной машине, вам нужно специальной командой (например, по ssh) отправить изменения на удалённую машину, применить там patch-файл и запустить анализ в режиме проверки списка файлов.
    • Далее нужно обработать результат анализа. Чтобы отклонить операцию при наличии сообщений анализатора, вам нужно будет завершить хук не нулевым кодом. Это можно сделать с помощью утилиты преобразования отчётов PlogConverter. Флаг -w указывает, что утилита должна завершать свою работу с кодом возврата 2, если в отфильтрованном отчёте есть срабатывания.

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

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

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

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

Пример содержимого файла с путями:

D:\MyProj\Tests.cs
D:\MyProj\Common.cpp
D:\MyProj\Form.h

Далее будут рассмотрены варианты запуска анализа для разных языков и ОС.

Анализ C# файлов

Для проверки C# файлов используется утилита 'PVS-Studio_Cmd' для Windows и 'pvs-studio-dotnet' для Linux и macOS.

Путь к файлу, который содержит список файлов для анализа, передаётся с помощью аргумента '-f' (подробную информацию об аргументах можно найти в документации). О формате этого файла написано выше в разделе "Режим проверки списка файлов".

Для получения информации о наличии предупреждений анализатора можно проверить код возврата. Коды возврата описаны в документации.

Windows

Пример команды запуска анализа:

PVS-Studio_Cmd.exe -t MyProject.sln ^
                   -f .pvs-pr.list ^
                   -o Analysis_Report.json

Будут проанализированы файлы из '.pvs-pr.list', которые содержатся в решении 'MyProject.sln'. Результаты анализа будут сохранены в файл 'Analysis_Report.json'.

Linux и macOS

Пример команды запуска анализа:

pvs-studio-dotnet -t MyProject.sln \
                  -f .pvs-pr.list \
                  -o Analysis_Report.json

Будут проанализированы файлы из '.pvs-pr.list', которые содержатся в решении 'MyProject.sln'. Результаты анализа будут сохранены в файл 'Analysis_Report.json'.

Анализ C и С++ файлов

Для проверки C и C++ файлов можно использовать утилиты:

Способ проверки для каждой утилиты описан далее.

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

Кэш зависимостей компиляции для С и C++ проектов

В данном разделе более подробно расписывается механизм работы файлов кэшей зависимостей компиляции в консольных утилитах PVS-Studio_Cmd.exe и pvs-studio-analyzer/CompilerCommandsAnalyzer.exe.

В этих утилитах имеются специальные флаги:

  • Флаг для анализа списка файлов. В этом флаге указан путь до файла, в котором построчно перечислены пути до файлов исходного кода, которые надо проанализировать:
    • PVS-Studio_Cmd.exe: ‑‑sourceFiles (-f);
    • pvs-studio-analyzer/CompilerCommandsAnalyzer.exe: ‑‑source-files (-S).
  • Флаг для перегенерации кэшей зависимостей С и С++ проектов с запуском анализа. Этот флаг запускает перегенерацию файлов кэшей зависимостей для всех файлов проекта(-ов) с запуском анализа всех файлов из проекта(-ов) или переданного через флаг списка файлов:
    • PVS-Studio_Cmd.exe: ‑‑regenerateDependencyCache (-G);
    • pvs-studio-analyzer/CompilerCommandsAnalyzer.exe: ‑‑regenerate-depend-info.
  • Флаг для перегенерации кэшей зависимостей С и С++ проектов без запуска анализа. Этот флаг запускает перегенерацию файлов кэшей зависимостей проекта(-ов) без запуска анализа:
    • PVS-Studio_Cmd.exe: ‑‑regenerateDependencyCacheWithoutAnalysis (-W);
    • pvs-studio-analyzer/CompilerCommandsAnalyzer.exe: ‑‑regenerate-depend-info-without-analysis.

При первом запуске анализа с использованием флага анализа списка файлов анализатор препроцессирует все C и C++ файлы из проектов, переданных на анализ. Эта информация о зависимостях сохраняется в отдельный файл кэша зависимостей для каждого проекта.

При последующих запусках анализатора с флагом анализа списка файлов информация в кэше зависимости добавляется/обновляется для:

  • файлов, указанных в списке из флага, в котором содержится список файлов для анализа;
  • файлов, для которых ещё нет записи в файле кэша зависимостей. Например, новые файлы, добавленные в проект;
  • файлов, которые ранее зависели от файлов, указанных в списке из флага анализа списка файлов. Информация о зависимостях берётся из файла кэша зависимости, который был сформирован/обновлён при прошлом запуске анализа с флагом анализа списка файлов.

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

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

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

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

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

pvs-studio-analyzer / CompilerCommandsAnalyzer.exe (Windows, Linux и macOS)

Примечание. Сценарий анализа файлов проекта, который использует сборочную систему MSBuild, описан в разделе "PVS-Studio_Cmd (Windows, Visual Studio\MSBuild)".

В зависимости от ОС, на которой выполняется анализ, утилита будет иметь разные названия:

  • Windows: 'CompilerCommandsAnalyzer.exe';
  • Linux и macOS: 'pvs-studio-analyzer'.

В примерах данной документации используется название 'pvs-studio-analyzer'. Способ анализа файлов для 'CompilerCommandsAnalyzer.exe' аналогичен описанным здесь.

Для использования 'pvs-studio-analyzer' нужно сгенерировать либо файл 'compile_commands.json', либо файл с результатами трассировки компиляции (актуально только для Linux). Они необходимы для того, чтобы анализатор имел информацию о компиляции конкретных файлов.

Получение 'compile_commands.json'

Со способами получения файла 'compile_commands.json' можно ознакомится в документации.

Получение файла трассировки (только для Linux)

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

Существует два варианта анализа с использованием файла трассировки. Можно либо производить полную трассировку сборки всего проекта при каждом запуске, либо кэшировать результат трассировки и использовать его.

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

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

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

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

Рассмотрим пример использования 'pvs-studio-analyzer'. Путь к файлу, который содержит список файлов для анализа, передаётся с помощью аргумента '-S' (подробную информацию об аргументах утилиты можно найти в документации). О формате этого файла написано выше в разделе "Режим проверки списка файлов".

Примечание. Если информация о компиляции была получена с использованием режима трассировки компиляции, с помощью флага '-f' передаётся файл трассировки (по умолчанию его название — 'strace_out').

Пример команды для анализа файлов:

pvs-studio-analyzer analyze -S .pvs-pr.list \
                            -f compile_commands.json \
                            -o Analysis_Report.json

При выполнении данной команды сгенерируется отчёт с результатом проверки файлов, содержащихся в '.pvs-pr.list'. Результаты анализа будут сохранены в файл 'Analysis_Report.json'.

Для генерации или обновления файла зависимостей без запуска анализа используется флаг ‑‑regenerate-depend-info-without-analysis. Вместе с этим флагом нельзя использовать флаг -S. Команда для обновления будет выглядеть следующим образом:

pvs-studio-analyzer analyze -f compile_commands.json \
                            –-regenerate-depend-info-without-analysis

Для принудительного обновления кэша зависимостей с последующим запуском анализа используется флаг ‑‑regenerate-depend-info. Его также можно использовать вместе с флагом -S. В этом случае для всех файлов из проекта обновится кэш зависимостей. Однако анализироваться при этом будут:

  • файлы, переданные на анализ (в флаге -S указан путь до файла, в котором построчно перечислены пути до файлов исходного кода, которые надо проанализировать);
  • файлы, зависящие от файлов, переданных на анализ (вначале происходит актуализация информации о зависимостях, а после эта информация используется при определении зависимостей файлов).

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

pvs-studio-analyzer analyze -S .pvs-pr.list \
                            -f compile_commands.json \
                            -o Analysis_Report.json \
                            –-regenerate-depend-info

По умолчанию файл с кэшем зависимостей генерируется в папку '.PVS-Studio', которая создаётся в рабочей директории. Сам кэш содержится в файле 'depend_info.json'.

Получение информации о наличии/отсутствии предупреждений в отчёте анализатора

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

С документацией по данным утилитам можно ознакомиться здесь.

Пример использования 'PlogConverter.exe':

PlogConverter.exe Analysis_Report.json ^
                  -t html ^
                  -n PVS-Studio ^
                  --indicateWarnings

Пример использования 'plog-converter':

plog-converter Analysis_Report.json \
               -t html \
               -n PVS-Studio \
               --indicate-warnings

В качестве первого аргумента командной строки передается путь до файла с результатами анализа. С помощью аргумента '-t' указывается формат, в котором необходимо сохранить отчёт. При помощи аргумента '-n' задаётся имя файла с преобразованным отчётом. Флаги '‑‑indicateWarnings' для 'PlogConverter.exe' и '‑‑indicate-warnings' для 'plog-converter' позволяют установить код возврата 2, если в отчёте есть предупреждения анализатора.

CLMonitor (Windows)

Путь к файлу, который содержит список файлов для анализа, передаётся с помощью аргумента '-f' (подробную информацию об аргументах можно найти в документации). О формате этого файла написано в разделе "Режим проверки списка файлов".

Пример команды запуска анализа:

CLMonitor.exe analyze -l "Analysis_Report.json" ^
                      -f ".pvs-pr.list"

При выполнении данной команды будет сгенерирован отчёт с результатом проверки файлов, содержащихся в '.pvs-pr.list'. Результаты анализа будут сохранены в файл 'Analysis_Report.json'.

По коду возврата консольной утилиты 'PlogConverter.exe' можно понять, есть срабатывания в отчёте анализатора или нет. Если предупреждения анализатора отсутствуют, код возврата — 0. При наличии предупреждений код возврата — 2. С документацией по данным утилитам можно ознакомиться здесь.

Пример использования 'PlogConverter.exe':

PlogConverter.exe Analysis_Report.json \
                  -t html \
                  -n PVS-Studio \
                  --indicate-warnings

В качестве первого аргумента командной строки передается путь до файла с результатами анализа. С помощью аргумента '-t' указывается формат, в котором необходимо сохранить отчёт. При помощи аргумента '-n' задаётся имя файла с преобразованным отчётом. Флаг '‑‑indicateWarnings' для 'PlogConverter.exe' позволяет задать код возврата 2, если в отчёте есть предупреждения анализатора.

PVS-Studio_Cmd (Windows, Visual Studio\MSBuild)

Если нужные файлы с кодом включены в проект Visual Studio, который использует сборочную систему MSBuild, то анализ производится с помощью утилиты PVS-Studio_Cmd.

Путь к файлу, который содержит список файлов для анализа, передаётся с помощью аргумента '-f' (подробную информацию об аргументах утилит можно найти в документации). О формате этого файла написано выше в разделе "Режим проверки списка файлов".

Для получения информации о наличии предупреждений анализатора можно проверить код возврата. Коды возврата описаны в документации.

Пример команды запуска анализа:

PVS-Studio_Cmd.exe -t MyProject.sln ^
                   -f .pvs-pr.list ^
                   -o Analysis_Report.json

Будут проанализированы файлы из '.pvs-pr.list', которые содержатся в решении 'MyProject.sln'. Результаты анализа будут сохранены в файл 'Analysis_Report.json'.

Для обновления зависимостей без запуска анализа используется флаг -W. Вместе с ним нельзя использовать флаг -f:

PVS-Studio_Cmd.exe -t MyProject.sln ^
                   -W

Для принудительного обновления кэша зависимостей с последующим запуском анализа используется флаг -G. Его также можно использовать вместе с флагом -f. В этом случае для всех файлов исходного кода из проектов, переданных для анализа, будут обновлены кэши зависимостей. Однако, анализироваться при этом будут:

  • файлы, переданные на анализ (во флаге -f указан путь до файла, в котором построчно перечислены пути до файлов исходного кода, которые надо проанализировать);
  • файлы, зависящие от файлов, переданных на анализ (вначале происходит актуализация информации о зависимостях, а после эта информация используется при определении зависимостей файлов).

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

PVS-Studio_Cmd.exe -t MyProject.sln ^
                   -f .pvs-pr.list ^
                   -G

По умолчанию файл с кэшем зависимостей генерируется на уровне проекта и сохраняется в папку '.pvs-studio'. Файл, содержащий кэш, имеет название вида 'projectName.vcxproj.deps.json' (часть имени файла, в данном случае 'projectName.vcxproj', соответствует имени проекта). Соответственно, если проанализировать файлы, относящиеся к одному решению, но к разным проектам, то в директории каждого из проектов будет создана папка '.pvs-studio' с файлом зависимостей.

Существует возможность изменить директорию сохранения кэша. Для этого используется параметр '-D'. В качестве его значения передаётся путь до директории, в которую необходимо сохранить кэш.

Для задания относительных путей в кэшах зависимостей используется флаг '-R'. В качестве аргумента ему необходимо передать путь, относительно которого будут раскрыты пути в файлах кэшей зависимостей.

Получение информации о наличии/отсутствии предупреждений в отчёте анализатора

По коду возврата консольной утилиты PVS-Studio_Cmd.exe можно понять, есть срабатывания в отчёте анализатора или нет. Код возврата 256 означает, что в отчёте есть предупреждения анализатора.

Также возможно использование консольных утилит PlogConverter.exe (Windows) или plog-converter (Linux/macOS) с флагом ‑‑indicateWarnings. При использовании этих флагов, если в отчёте анализатора имелись предупреждения, код возврата будет равен 2.

Пример использования PlogConverter.exe:

PlogConverter.exe Analysis_Report.json ^
                  -t html ^
                  -n PVS-Studio ^
                  --indicateWarnings

Пример использования plog-converter:

plog-converter Analysis_Report.json \
               -t html \
               -n PVS-Studio \
               --indicate-warnings

Анализ Java файлов

Для проверки Java файлов используется утилита 'pvs-studio.jar'. Подробную информацию о самой утилите и её аргументах можно найти в документации.

Windows, Linux и macOS

Путь к файлу, который содержит список файлов для анализа, передаётся с помощью флага '‑‑analyze-only-list'. О формате этого файла написано выше в разделе "Режим проверки списка файлов".

Для анализа списка файлов также необходимо передать путь до проекта, содержащего их. Делается это при помощи аргумента '-s'. С помощью аргумента '-e' определяется classpath. Если требуется использовать несколько сущностей classpath, то они разделяются пробелом.

Пример команды запуска анализа:

java -jar pvs-studio.jar -s projectDir ^
                         --analyze-only-list .pvs-pr.list ^
                         -e Lib1.jar Lib2.jar ^
                         -j4 ^
                         -o report.json ^
                         -O json ^
                         --user-name userName ^
                         --license-key key

В результате будут проанализированы файлы, записанные в '.pvs-pr.list'. Результаты анализа сохранятся в файл 'report.json'.

Для получения информации о наличии срабатываний можно воспользоваться флагом '‑‑fail-on-warnings'. При его использовании анализатор вернёт код 53, если в результате анализа будут выданы предупреждения.