Оглавление
Проверка проектов Visual Studio / MSBuild / .NET из командной строки с помощью PVS-Studio
- Запуск анализа sln и csproj/vcxproj файлов
- Задание отдельных файлов для проверки
- Фильтрация списка анализируемых файлов по маске
- Режим межмодульного анализа
- Коды возврата command-line утилит
- Запуск анализа из командной строки для C/C++ проектов, не использующих сборочную систему Visual Studio
- Влияние настроек PVS-Studio на запуск из командной строки; фильтрация и преобразование результатов анализа (plog\json файла)
В данном документе описывается использование command line утилит для анализа MSBuild проектов (.vcxproj / .csproj) и решений Visual Studio (solutions).
В данном документе описывается использование command-line утилит. Использование плагинов для IDE Visual Studio и Rider описано в соответствующих разделах документации: "Знакомство со статическим анализатором кода PVS-Studio на Windows", "Работа PVS-Studio в JetBrains Rider".
Command line анализатор MSBuild / .NET Core проектов имеет разные имена на разных поддерживаемых анализатором платформах:
- PVS-Studio_Cmd (анализ решений, C#, C++ проектов на Windows);
- pvs-studio-dotnet (анализ решений, C# проектов на Linux / macOS).
Описываемые ниже особенности актуальны для обеих утилит. Примеры с PVS-Studio_Cmd / pvs-studio-dotnet являются взаимозаменяемыми, если явно не указано обратное.
Примечание. Для анализа C++ проектов, не использующих сборочную систему MSBuild, на Windows следует воспользоваться системой мониторинга компиляции или прямой интеграцией анализатора в сборочную систему. Анализ C++ проектов на Linux / macOS подробно описан в этом разделе документации.
Запуск анализа sln и csproj/vcxproj файлов
Command line утилиты по умолчанию распаковываются в следующие директории:
- PVS-Studio_Cmd.exe
- Windows: "C:\Program Files (x86)\PVS-Studio\";
- pvs-studio-dotnet
- Linux: "/usr/share/pvs-studio-dotnet/";
- macOS: "/usr/local/share/pvs-studio-dotnet".
Команда '--help' выведет все доступные аргументы анализатора:
PVS-Studio_Cmd.exe --helpРассмотрим основные аргументы анализатора:
- --target (-t): обязательный параметр. Позволяет указать объект для проверки (sln или csproj/vcxproj файл);
- --output (-o): путь до файла, в который будут записаны результаты анализа. Если данный параметр пропущен, файл отчёта анализатора будет создан рядом с файлом, указанным через флаг '--target'. Поддерживается сохранение отчёта анализатора в 2 форматах: .json и .plog. Тип формата определяется по указанному расширению. По умолчанию, без указания данного флага, на Windows будет создан отчёт в формате .plog, а на Linux и macOS — в формате .json;
- --platform (-p) и --configuration (-c): платформа и конфигурация, для которых будет запущена проверка. Если данные параметры не указаны, будет выбрана первая из доступных пар "платформа|конфигурация" (при проверке sln файла) либо "Debug|AnyCPU" (при проверке отдельного csproj проекта) или "Debug|Win32" (при проверке отдельного vcxproj проекта);
- --sourceFiles (-f): путь до текстового файла, содержащего список путей до исходных файлов для анализа (каждый должен быть на отдельной строке). Поддерживаются относительные и абсолютные пути. В данном режиме при анализе C и C++ файлов генерируется кэш зависимостей компиляции, расположением которого можно управлять с помощью флага '-D';
- --regenerateDependencyCache (-G): обновляет кэш зависимостей компиляции. Флаг поддерживает следующие режимы:
- RunAnalysis - обновить кэш зависимостей и запустить анализ;
- SkipAnalysis - обновить кэш зависимостей без запуска анализа.
- --dependencyRoot (-D): опциональный путь к директории для размещения кэшей зависимости исходных файлов. Работает в дополнение к флагам '--sourceFiles' (-f) и '--regenerateDependencyCache' (-G);
- --dependencyCacheSourcesRoot (-R): опциональный путь, который используется для создания относительных путей в кэшах зависимостей исходных файлов, генерируемом при использовании флагов '--sourceFiles' (-f) и '--regenerateDependencyCache' (-G);
- --settings (-s): путь до файла настроек PVS-Studio. Если параметр опущен, будет использован файл настроек Settings.xml, находящийся в директории "%AppData%\PVS-Studio\" на Windows или "~/.config/PVS-Studio/" на Linux / macOS. Эти же файлы настроек используются плагинами (Visual Studio, Rider), что даёт возможность их редактирования с помощью интерфейса PVS-Studio плагина в данных IDE. Обратите внимание, что для работы анализатора под Windows файл настроек должен содержать регистрационную информацию. Различные способы ввода лицензии описаны здесь. В зависимости от используемого файла настроек, применяются следующие правила:
- при использовании файла настроек по умолчанию он должен содержать регистрационную информацию;
- при явном указании пути до файла настроек регистрационная информация должна быть записана или в указанном файле настроек, или в файле настроек, используемом по умолчанию;
- --licFile (-l): путь до файла лицензии PVS-Studio. Данный флаг доступен только в pvs-studio-dotnet. Если параметр опущен, будет использован файл лицензии PVS-Studio.lic, находящийся в директории "~/.config/PVS-Studio/ ".
- --progress (-r): включение режима подробного логгирования в stdout прогресса проверки (по умолчанию выключено);
- --suppressAll (-a): добавить неподавленные сообщения в suppress файлы соответствующих проектов (по умолчанию выключено). При наличии данного флага все сообщения будут добавлены в базу подавленных сообщений после сохранения результата проверки. Флаг поддерживает 5 режима работы.
- SuppressOnly добавляет сообщения из переданного отчёта о работе анализатора в suppress файлы без запуска анализа;
- AnalyzeAndSuppress запускает анализ, сохраняет отчёт о работе анализатора, и только затем подавляет найденные в нём сообщения. Этот режим позволит вам при регулярных запусках получать отчёт анализатора, в котором содержатся только новые сообщения на изменённый \ написанный код, т.е. новые сообщения попадают в новый лог и сразу же подавляются - при последующей проверке их уже не будет выдано. Тем не менее, если вам всё же потребуется посмотреть старые сообщения (без перепроверки), рядом с отчётом о работе анализатора, содержащим новые сообщения, будет сохранён файл с полным отчётом о проверке (только для .plog отчётов анализатора). Подробнее про режим подавления сообщений можно прочитать в этом разделе документации;
- FilterFromSuppress фильтрует сообщения в существующем файле отчета (.plog, .json или 'сырой' вывод C++ ядра ) без запуска анализа при помощи suppress файлов, расположенных рядом с файлами проектов/решения. Ещё один вариант: передать путь до suppress файлов в параметре –useSuppressFile (-u). Файл с результатами фильтрации сохраняется рядом с переданным файлом отчета. Имя этого файла имеет постфикс '_filtered'.
- CountSuppressedMessages подсчитывает количество подавленных сообщений во всех suppress файлах. Данный режим также может подсчитать количество актуальных сообщений в suppress файлах. Если передать полный файл отчета (через флаг -o), то можно узнать сколько сообщений в базе подавления еще актуальны. Вы можете узнать статистку по каждому suppress файлу, если запустите данный режим с флагом '-r'.
- UpdateSuppressFiles выполняет обновление suppress файлов, удаляя из них сообщения, которые не содержатся в переданном файле отчёта. Обратите внимание, что для работы этого режима требуется полный отчёт, содержащий подавленные сообщения. Полный отчёт создается каждый раз, при запуске анализа, если есть подавленные сообщения. Файл полного отчёта имеет имя "*_WithSuppressedMessages.*" и располагаться рядом с основным отчётом. Если вы запустите данный режим c файлом отчета, не содержащим подавленные сообщения, все suppress файлы будут очищены.
- --sourceTreeRoot (-e): корневая часть пути, которую PVS-Studio будет использовать при генерации относительных путей в диагностических сообщениях. Задание этого параметра переопределяет значение 'SourceTreeRoot' в настройках PVS-Studio;
- -- incremental (-i): режим инкрементального анализа. Для получения подробной информации об инкрементальном анализе в PVS-Studio обратитесь к разделу "Режим инкрементального анализа PVS-Studio". Обратите внимание что этот режим доступен только для Enterprise лицензии PVS-Studio. Доступны следующие режимы работы инкрементального анализа:
- Scan – проанализировать все зависимости для определения того, на каких файлах должен быть выполнен инкрементальный анализ. Непосредственно анализ выполнен не будет. Будут учтены изменения, произведенные с момента последней сборки, предыдущая история изменений будет удалена.
- AppendScan – проанализировать все зависимости для определения того, на каких файлах должен быть выполнен инкрементальный анализ. Непосредственно анализ выполнен не будет. Будут учтены изменения, произведенные с момента последней сборки, а также все предыдущие изменения.
- Analyze – выполнить инкрементальный анализ. Этот шаг должен выполняться после выполнения шагов Scan или AppendScan, и может выполняться как до, так и после сборки решения или проекта. Статический анализ будет выполнен только для файлов из списка, полученного в результате выполнения команд Scan или AppendScan.
- ScanAndAnalyze - проанализировать все зависимости для определения того, на каких файлах должен быть выполнен инкрементальный анализ, и сразу же выполнить инкрементальный анализ измененных файлов с исходным кодом. Будут учтены изменения, произведенные с момента последней сборки.
- --msBuildProperties (-m): позволяет задать или переопределить свойства уровня проекта. Для задания или переопределения нескольких свойств уровня проекта, используйте символ "|", например: --msBuildProperties "WarningLevel=2|OutDir=bin\OUT32\"
- --excludeDefines (-x): список символов, которые будут исключены из текущего набора при анализе проекта. При необходимости перечисления нескольких символов в качестве разделителя используется ';'. Пример: --excludeDefines "DEF1;DEF2". Данная опция учитывается только при анализе C# проектов.
- --appendDefines (-d): список символов, которые будут добавлены к текущему набору при анализе проекта. При необходимости перечисления нескольких символов в качестве разделителя используется ';'. Пример: --appendDefines "DEF1;DEF2". Данная опция учитывается только при анализе C# проектов.
- --selectProjects (-S): список проектов анализируемого решения (sln), которые будут проанализированы. Остальные проекты будут исключены из анализа. Поддерживается перечисление проектов через имя проектного файла (c расширением или с без него), по абсолютному или относительному пути. При необходимости перечисления нескольких проектов в качестве разделителя используется ';'. Пример: --selectProjects Project1;"Project 2.vcxproj";".\Project3\Project3.csproj".
- --excludeProjects (-E): список проектов анализируемого решения (sln), которые будут исключены из анализа. Поддерживается перечисление проектов через имя проектного файла (c расширением или с без него), по абсолютному или относительному пути. При необходимости перечисления нескольких проектов в качестве разделителя используется ';'. Пример: --excludeProjects Project1;"Project 2.vcxproj";".\Project3\Project3.csproj".
- --rulesConfig (-C): путь к файлу конфигурации диагностик .pvsconfig. Может быть использован совместно с файлами конфигурации из проектов / решения и файлами конфигурации из каталогов:
- Windows: "%AppData%\PVS-Studio\";
- Linux / macOS: "~/.config/PVS-Studio/".
- --useSuppressFile (-u): путь до suppress файлов. Через этот параметр можно указать несколько suppress файлов. В качестве разделителя используется символ ';'. Например: -u "path\to\test.suppress;path\to\test.suppress.json". Подробнее про режим подавления сообщений можно прочитать в этом разделе документации.
- --disableLicenseExpirationCheck (-h): cбрасывает код возврата и отключает предупреждение об истечении срока действия лицензии, когда срок действия лицензии подходит к концу.
Приведём пример запуска проверки списка файлов, записанных в "pvs.txt", из состава решения "My Solution":
PVS-Studio_Cmd.exe --target "mysolution.sln" --platform "Any CPU"
--configuration "Release" --output "mylog.plog"
--sourceFiles "pvs.txt" --progressCommand line версия анализатора PVS-Studio поддерживает все настройки по фильтрации\отключению сообщений, доступные в плагинах для Visual Studio и Rider. Вы можете как задать их вручную в xml файле, переданном с помощью аргумента '--settings', так и использовать настройки, заданные через UI плагина, не передавая данного аргумента. Обратите внимание, что IDE плагин PVS-Studio использует отдельный набор настроек для каждого пользователя в системе.
Актуально только для PVS-Studio_Cmd. Если вы установили несколько экземпляров PVS-Studio различных версий для текущего пользователя системы, то все экземпляры программы будут использовать установочную директорию, указанную при последней установке. Во избежание конфликтов в работе анализатора в настройках, передаваемых с аргументом --settings (-s), необходимо указать путь до установочной директории (значение элемента <InstallDir>).
Задание отдельных файлов для проверки
PVS-Studio_Cmd позволяет провести выборочную проверку отдельных файлов, заданных в списке, передаваемом с помощью флага '--sourceFiles' (-f). Список файлов представляет собой простой текстовый файл, в котором построчно указаны пути к проверяемым файлам. Относительные пути к файлам будут раскрыты относительно текущей рабочей директории. Можно указывать как исходные компилируемые файлы (c/cpp для C++ и cs для C#), так и заголовочные файлы (h/hpp для C++).
В данном режиме работы при анализе C и C++ файлов генерируется кэш зависимостей компиляции, который будет использован при последующих запусках анализа. По умолчанию кэши зависимостей сохраняются в специальной поддиректории '.pvs-studio', рядом с проектными файлами (.vcxproj). При необходимости можно изменить место их хранения при помощи флага '--dependencyRoot' (-D).
Фильтрация списка анализируемых файлов по маске
Для того, чтобы определить набор анализируемых файлов, пути и названия которых соответствуют определенному шаблону, флагу '--sourceFiles' (-f) должен быть передан специально сформированный XML файл. В нем могут содержаться списки абсолютных и относительных путей и\или масок до проверяемых файлов.
<SourceFilesFilters>
<SourceFiles>
<Path>C:\Projects\Project1\source1.cpp</Path>
<Path>\Project2\*</Path>
<Path>source_*.cpp</Path>
</SourceFiles>
<SourcesRoot>C:\Projects\</SourcesRoot>
</SourceFilesFilters>Режим межмодульного анализа
Включение данного режима позволяет анализатору учитывать информацию не только из анализируемого файла, но и из связанных с ним файлов. Это позволяет производить более глубокий и качественный анализ. Однако, на сбор необходимой информации требуется дополнительное время, что отразится на времени анализа вашего проекта.
Данный режим актуален для C и C++ проектов. C# проекты обеспечивают межмодульный анализ по умолчанию.
Чтобы включить данный режим, необходимо в файле настроек (Settings.xml) выставить значение 'true' в теге 'IntermodularAnalysisCpp'.
Коды возврата command-line утилит
Утилиты PVS-Studio_Cmd / pvs-studio-dotnet имеют несколько ненулевых кодов возврата, которые не означают проблемы в работе самой утилиты, т.е. даже если утилита вернула не '0', это ещё не означает, что она "упала". Код возврата представляет собой битовую маску, маскирующую все возможные состояния, возникшие во время работы утилиты. Например, утилита вернёт ненулевой код возврата в случае, если анализатор нашёл в проверяемом коде потенциальные ошибки. Это позволяет обрабатывать такую ситуацию отдельно, например, на сборочном сервере, когда политика использования анализатора не подразумевает наличия срабатываний в коде, заложенном в систему контроля версий.
Коды возврата PVS-Studio_Cmd (Windows)
Рассмотрим далее все возможные коды состояния утилиты, из которых формируется битовая маска кода возврата.
- '0' - анализ успешно завершён, ошибок в проверяемом коде не найдено;
- '1' - ошибка (падение) анализатора при проверке одного из файлов;
- '2' - общая (неспецифичная) ошибка при работе анализатора, перехваченное исключение при работе. Обычно это сигнализирует о наличии ошибки в коде самого анализатора и сопровождается выведением stack trace'а этой ошибки в stderr. Если вам встретилась подобная ошибка, пожалуйста, помогите нам улучшить анализатор и пришлите этот stack trace нам;
- '4' - какие-то из переданных аргументов командной строки некорректны;
- '8' - не найден заданный проект, solution или файл настроек анализатора;
- '16' - заданная конфигурация и (или) платформа не найдены в файле решения;
- '32' - файл решения или проекта не поддерживается или содержит ошибки;
- '64' - некорректное расширение проверяемого решения или проекта;
- '128' - некорректная или просроченная лицензия на анализатор;
- '256' - в проверяемом коде найдены потенциальные ошибки;
- '512' - произошла ошибка при выполнении подавления сообщений
- '1024' - показывает, что лицензия на анализатор истечёт в течение месяца;
Приведём пример скрипта Windows batch для расшифровки кода возврата утилиты PVS-Studio_Cmd:
@echo off
"C:\Program Files (x86)\PVS-Studio\PVS-Studio_Cmd.exe"
-t "YourSolution.sln" -o "YourSolution.plog"
set /A FilesFail = "(%errorlevel% & 1) / 1"
set /A GeneralExeption = "(%errorlevel% & 2) / 2"
set /A IncorrectArguments = "(%errorlevel% & 4) / 4"
set /A FileNotFound = "(%errorlevel% & 8) / 8"
set /A IncorrectCfg = "(%errorlevel% & 16) / 16"
set /A InvalidSolution = "(%errorlevel% & 32) / 32"
set /A IncorrectExtension = "(%errorlevel% & 64) / 64"
set /A IncorrectLicense = "(%errorlevel% & 128) / 128"
set /A AnalysisDiff = "(%errorlevel% & 256) / 256"
set /A SuppressFail = "(%errorlevel% & 512) / 512"
set /A LicenseRenewal = "(%errorlevel% & 1024) / 1024"
if %FilesFail% == 1 echo FilesFail
if %GeneralExeption% == 1 echo GeneralExeption
if %IncorrectArguments% == 1 echo IncorrectArguments
if %FileNotFound% == 1 echo FileNotFound
if %IncorrectCfg% == 1 echo IncorrectConfiguration
if %InvalidSolution% == 1 echo IncorrectCfg
if %IncorrectExtension% == 1 echo IncorrectExtension
if %IncorrectLicense% == 1 echo IncorrectLicense
if %AnalysisDiff% == 1 echo AnalysisDiff
if %SuppressFail% == 1 echo SuppressFail
if %LicenseRenewal% == 1 echo LicenseRenewalКоды возврата pvs-studio-dotnet (Linux / macOS)
Примечание. Так как максимальное значение кода возврата под Unix ограничено 255, коды возврата утилит PVS-Studio_Cmd (где может возвращаться значение больше 255) и pvs-studio-dotnet отличаются.
Рассмотрим далее все возможные коды состояния утилиты, из которых формируется битовая маска кода возврата.
- '0' - анализ успешно завершён, ошибок в проверяемом коде не найдено;
- '1' - некорректная или просроченная лицензия на анализатор;
- '2' - общая ошибка при работе анализатора. Эта ошибка включает пропущенные аргументы командной строки, некорректный solution или проект, заданный для анализа, ошибки внутри анализатора и т.п. Если ошибка сопровождается stack trace, пожалуйста, помогите нам улучшить анализатор и пришлите этот stack trace нам;
- '4' - показывает, что лицензия на анализатор истечёт в течение месяца;
- '8' - в проверяемом коде найдены потенциальные ошибки;
Запуск анализа из командной строки для C/C++ проектов, не использующих сборочную систему Visual Studio
Примечание. Данный раздел актуален для Windows. Анализ C++ проектов на Linux / macOS описан в соответствующем разделе документации.
Если ваш C/C++ проект не использует стандартные сборочные системы Visual Studio (VCBuild/MSBuild) или даже использует собственную сборочную систему / make-файлы через NMake проекты Visual Studio, то вы не сможете проверить такой проект с помощью PVS-Studio_Cmd.
В таком случае вы можете воспользоваться системой отслеживания компиляторов, которая позволяет анализировать проекты, независимо от их сборочной системы, "перехватывая" запуск процессов компиляции. Система отслеживания компиляции может использоваться как из командной строки, так и через пользовательский интерфейс приложения C and C++ Compiler Monitoring UI.
Также вы можете напрямую встроить запуск command line ядра анализатора непосредственно в вашу сборочную систему. Заметьте, что это потребует прописывать вызов ядра анализатора PVS-Studio.exe для каждого компилируемого файла, по аналогии с тем, как вызывается C++ компилятор.
Влияние настроек PVS-Studio на запуск из командной строки; фильтрация и преобразование результатов анализа (plog\json файла)
При запуске анализа кода из командной строки по умолчанию используются те же настройки, что и при запуске анализа из IDE (Visual Studio / Rider). Также можно указать, какой файл настроек использовать, с помощью аргумента --settings, как было описано выше.
Что касается, к примеру, системы фильтров (Keyword Message Filtering и Detectable Errors), то она НЕ применяется при анализе из командной строки. В том смысле, что в файле отчета независимо от заданных параметров будут все сообщения об ошибках. Но при загрузке файла с результатами в IDE фильтры уже будут применены. Это происходит из-за того, что фильтры применяются динамически к результатам (и при запуске из IDE также). Это очень удобно, поскольку, получив список сообщений, вы можете захотеть отключить некоторые из них (например, V201). Достаточно отключить их в настройках и соответствующие сообщения пропадут из списка БЕЗ перезапуска анализа.
Формат отчёта анализатора не предназначен для прямого отображения или чтения человеком. Однако, если необходимо каким-либо образом отфильтровать результаты анализа и преобразовать их в "читаемый" вид, можно воспользоваться утилитой PlogConverter, распространяемой вместе с PVS-Studio.
Для работы с отчётами разных форматов требуется использование разных утилит:
- .plog – PlogConverter.exe (доступна только на Windows);
- .json – plog-converter (Linux, macOS).
Исходный код обеих утилит открыт и доступен для загрузки: PlogConverter; plog-converter, что позволяет достаточно просто добавлять поддержку новых форматов на основе существующих алгоритмов.
Более подробно данные утилиты описываются в соответствующих разделах документации:
- PlogConverter – "Работа с XML отчётом (.plog файл)" (подраздел "Конвертация результатов анализа");
- plog-converter – "Как запустить PVS-Studio в Linux и macOS" (подраздел "Утилита Plog Converter").