Проверка Unreal Engine проектов


В данном разделе рассматривается проверка Unreal Engine проектов на операционной системе Windows. Инструкции по проверке проектов на Linux\macOS доступны по данной ссылке.

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

Для сборки проектов для Unreal Engine используется специализированная сборочная система Unreal Build System. Данная система интегрируется поверх сборочной системы, используемой средой Visual Studio (MSBuild), с помощью автогенерируемых makefile проектов MSBuild. Это специальный тип Visual C++ (vcxproj) проектов, в которых для непосредственного выполнения сборки выполняется команда, вызывающая стороннюю утилиту, например, (но далеко не обязательно) Make. Использование makefile проектов позволяет работать с кодом Unreal Engine из среды Visual Studio, используя такие преимущества, как автодополнение, подсветка синтаксиса, навигация по символам и т.п.

В связи с тем, что makefile проекты MSBuild сами по себе не содержат полной информации, необходимой для компиляции, а, следовательно, и препроцессирования исходных C/C++ файлов, PVS-Studio не поддерживает проверку таких проектов с помощью Visual Studio плагина или консольной утилиты PVS-Studio_Cmd.exe. Поэтому, для проверки таких проектов с помощью PVS-Studio можно пойти двумя путями - отслеживание вызовов компилятора (Compiler Monitoring) и прямая интеграция C/C++ анализатора PVS-Studio.exe в сборочную утилиту Unreal Build Tool. Рассмотрим эти варианты подробнее.

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

Для сборки на Windows Unreal Build System использует компилятор Visual C++ - cl.exe. Этот компилятор поддерживается системой отслеживания компиляторов PVS-Studio на Windows. Эту систему можно использовать как из приложения C and C++ Compiler Monitoring UI (Standalone.exe), так и с помощью консольной утилиты CLMonitor.exe.

Запуск мониторинга компиляций можно осуществлять вручную из приложения Compiler Monitoring UI, или назначить на событие начала\окончания сборки в Visual Studio. Результатом работы системы мониторинга является XML файл отчёта plog, который можно открыть в Visual Studio плагине PVS-Studio, или преобразовать к одному из стандартных форматов (txt, html, csv) с помощью специальной утилиты PlogConverter.

Подробное описание системы отслеживания вызовов компилятора доступно в данном разделе документации. Мы рекомендуем использовать данный способ запуска анализа для знакомства с анализатором, как наиболее простой в настройке.

Проверка с помощью интеграции в Unreal Build Tool

Общее описание прямого встраивания C/C++ анализатора в любую сборочную систему доступно здесь.

В случае с Unreal Build System, разработчики из Epic Games предоставляют возможность использовать PVS-Studio с помощью интеграции со сборочной утилитой Unreal Build Tool, начиная с версии 4.17.

Перед началом анализа вам будет необходимо ввести лицензию на анализатор - откройте Visual Studio, и в окне 'PVS-Studio|Options...Registration' введите ваши данные (обратите внимание, что в до версии Unreal Engine 4.20, UBT не умел подхватывать лицензию из общего файла настроек PVS-Studio; в случае, если UBT не видит лицензию, введённую через интерфейс, вам необходимо создать отдельный файл лицензии с именем PVS-Studio.lic вручную и подложить его в директорию '%USERPROFILE%\AppData\Roaming\PVS-Studio').

Unreal Build Tool позволяет запускать анализ PVS-Studio, добавив данный флаг в строку запуска:

-StaticAnalyzer=PVSStudio

Например, полная строка запуска Unreal Build Tool может выглядеть так:

UnrealBuildTool.exe UE4Client Win32 Debug -WaitMutex -FromMsBuild 
    -StaticAnalyzer=PVSStudio -DEPLOY

Для включения анализа при запуске из Visual Studio, откройте свойства проекта 'Properties|Configuration Properties|NMake' и добавьте флаг -StaticAnalyzer=PVSStudio в опции сборки и пересборки (Build Command Line / Rebuild All Command Line).

Примечание. Обратите внимание, что при таком сценарии использования будет выполнен только анализ - сборка проведена не будет.

Модификация сборочных скриптов для сборки и анализа

Если вам требуется настроить одновременную сборку и анализ в рамках одной конфигурации Visual Studio, то для этого можно создать вспомогательные скрипты (в нашем примере назовём их, соответственно, BuildAndAnalyze и RebuildAndAnalyze) на основе стандартных скриптов Build и Rebuild.

Основное изменение в скрипте RebuildAndAnalyze - вызов для сборки нового скрипта BuildAndAnalyze.bat, а не Build.bat.

В скрипт BuildAndAnalyze необходимо добавить удаление кэша действий и запуск UnrealBuildTool с флагом анализа после проведения успешной сборки.

В кэш сохраняются действия, выполняемые UBT в ходе работы (сборки, анализ и т.п.).

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

Восстановление кэша из бэкапа после анализа необходимо для того, чтобы вновь получить сохранённые действия сборки. Если UBT не обнаружит сохранённых действий сборки - она будет выполнена заново.

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

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

Первоначально необходимо определить ряд переменных, которые будут необходимы для удаления/восстановления файла кэша действий. Операции, связанные с кэшем действий, актуальны для версий Unreal Engine 4.21 и выше.

SET PROJECT_NAME=%1%
SET PLATFORM=%2%
SET UPROJECT_FILE=%~5

SET ACTIONHISTORY_FOLDER=
      %UPROJECT_FILE%\..\Intermediate\Build\%PLATFORM%\%PROJECT_NAME%
SET ACTION_HISTORY=ActionHistory.bin
SET ACTION_HISTORY_BAC=%ACTION_HISTORY%.bac
SET ACTIONHISTORY_PATH="%ACTIONHISTORY_FOLDER%\%ACTION_HISTORY%"
SET ACTIONHISTORY_BAC_PATH=
      "%ACTIONHISTORY_FOLDER%\%ACTION_HISTORY_BAC%"

После вызова UnrealBuildTool для сборки (и команды 'popd') необходимо добавить следующий код:

SET "UBT_ERR_LEVEL=!ERRORLEVEL!"
SET "NEED_TO_PERFORM_ANALYSIS="

IF "!UBT_ERR_LEVEL!"=="0" (
  SET "NEED_TO_PERFORM_ANALYSIS=TRUE"
)

IF "!UBT_ERR_LEVEL!"=="2" (
  SET "NEED_TO_PERFORM_ANALYSIS=TRUE"
)

IF DEFINED NEED_TO_PERFORM_ANALYSIS (
  pushd "%~dp0\..\..\Source"

  ECHO Running static analysis

  IF EXIST %ACTIONHISTORY_PATH% (
    ECHO Copying %ACTION_HISTORY% to %ACTION_HISTORY_BAC%
    COPY %ACTIONHISTORY_PATH% %ACTIONHISTORY_BAC_PATH%
    ECHO Removing %ACTION_HISTORY%: %ACTIONHISTORY_PATH%
    DEL  %ACTIONHISTORY_PATH%
)

  ..\..\Engine\Binaries\DotNET\UnrealBuildTool.exe 
    %* -StaticAnalyzer=PVSStudio -DEPLOY 
  popd

  SET "UBT_ERR_LEVEL=!ERRORLEVEL!"

  IF EXIST %ACTIONHISTORY_BAC_PATH% (
    ECHO Recovering %ACTION_HISTORY%
    COPY %ACTIONHISTORY_BAC_PATH% %ACTIONHISTORY_PATH%
    ECHO Removing %ACTION_HISTORY_BAC%: %ACTIONHISTORY_BAC_PATH%
    DEL  %ACTIONHISTORY_BAC_PATH%
  )
)

Наиболее важными операциями из приведённого выше кода являются удаление и восстановление кэша, а также запуск UnrealBuildTool с флагом -StaticAnalyzer=PVSStudio для проведения анализа.

При необходимости можно использовать модифицированный скрипт при работе из среды Visual Studio. Для этого необходимо указать его в качестве используемого в свойствах проекта: Properties|Configuration Properties|NMake|Build Command Line.

Обратите внимание, что при использовании модифицированных скриптов флаг -StaticAnalyzer=PVSStudio в аргументах запуска скрипта указывать не нужно, так как он уже выставляется в скрипте при запуске UnrealBuildTool для анализа.

Примечание. Интеграция PVS-Studio с Unreal Build Tool поддерживает не все настройки анализатора, доступные из Visual Studio (PVS-Studio|Options...). В данный момент поддерживается добавление директорий-исключений через 'PVS-Studio|Options...|Don't Check Files' и фильтрация загруженных результатов анализа через 'Detectable Errors'.

В режиме интеграции с UBT анализатор запускается в режиме работы только группы диагностик General Analysis. Если вас интересует запуск анализатора для других групп диагностик, доступных в PVS-Studio, напишите нам на support@viva64.com.

Работа с результатами анализа

Путь до файла с результатами анализа будет выведен в Output (Build) окно Visual Studio (или stdout, если вы запускали Unreal Build Tool вручную из командной строки). Данный файл с результатами анализа имеет "нераспарсенный" вид - его можно открыть в IDE командой 'PVS-Studio|Open/Save|Open Analysis Report' и выбрав тип файла 'unparsed output', либо результаты анализа можно преобразовать с помощью утилиты PlogConverter, как это было описано в разделе выше для XML лога.

Особенности работы со списком диагностических предупреждений более подробно описаны в статье "Работа со списком диагностических сообщений", а работа с отчётом анализатора - в статье "Работа с XML отчётом (.plog файл)".

Автоматическая загрузка логов в IDE Visual Studio

Более удобным вариантом использования является автоматическая загрузка лога анализа в окно вывода PVS-Studio при работе в среде Visual Studio. Для такого сценария необходимо включить соответствующую опцию: 'PVS-Studio|Options|Specific Analyzer Settings|Save/Load (analyzer report)|AutoloadUnrealEngineLog'.


Найденные ошибки

Проверено проектов
366
Собрано ошибок
13 539

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

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

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

goto PVS-Studio;