May 04 2021

Analysis of Unreal Engine projects

May 04 2021

Analysis using compiler monitoring
Analysis using Unreal Build Tool integration
- Modification of build scripts for building and analyzing
- Enabling various diagnostic groups
Handling the analysis results
- Automatic loading/uploading of logs in IDE
Troubleshooting

This section describes the analysis of Unreal Engine projects on Windows operating system. The instructions for checking projects under Linux\macOS are available by this link.

Integration with Unreal Build System is available only under Enterprise PVS-Studio license. You can request a trial Enterprise license at the download page.

A specialized build system called Unreal Build System is used for building Unreal Engine projects. This system is integrated over the build system used by the Visual Studio \ JetBrains Rider environment (MSBuild) by utilizing autogenerated makefile MSBuild projects. This is a special type of Visual C++ (vcxproj) projects in which the execution of the build is relegated to the execution of a command calling a third-party utility, for example (but not necessarily), Make. The use of makefile projects allows working with source code of Unreal Engine from Visual Studio \ JetBrains Rider environment, taking advantage of such features as code autocompletion, syntax highlighting, symbol navigation, etc.

Because makefile MSBuild projects themselves do not contain full information, necessary to perform the compilation, and therefore, preprocessing of C/C++ source files, PVS-Studio does not support the analysis of such projects from within Visual Studio, or by PVS-Studio_Cmd.exe command line tool. Therefore, to check such projects with PVS-Studio, you can go two ways - monitoring of compiler invocations (Compiler Monitoring) and direct integration of the PVS-Studio.exe C/C++ analyzer in the Unreal Build Tool utility. Let's consider these options in more detail.

Analysis using compiler monitoring

Unreal Build System uses the Visual C++ compiler-cl.exe for building under Windows. This compiler is supported by the system of PVS-Studio compiler monitoring on Windows. It can be both used from the C and C++ Compiler Monitoring UI (Standalone.exe) or from CLMonitor.exe command line tool.

Compiler monitoring can be launched manually from within the Compiler Monitoring UI or it can be assigned to the event of starting\ending builds in Visual Studio. The result of the analysis by the monitoring system is a plog XML report file, which you can open from the Visual Studio PVS-Studio extension, or convert to one of the standard formats (txt, html, csv) using the PlogConverter special tool.

A more detailed description for the system of compiler monitoring is available in this section of the documentation. We recommend using this way to run the analysis when you want to check it for the first time and get acquainted with the analyzer, as this way is the easiest one to set up.

Analysis using Unreal Build Tool integration

In case of Unreal Build System, the developers from Epic Games provide the opportunity to use PVS-Studio through the direct integration with the build utility called Unreal Build Tool, starting from version 4.17.

Before starting the analysis, you should enter your license for the analyzer. For this you need to enter your data in IDE:

'PVS-Studio|Options...|Registration' in Visual Studio;
'Toos|PVS-Studio|Settings...|Registaration' in JetBrains Rider.

Please note, that before Unreal Engine version 4.20, UBT was unable to get the license information from the PVS-Studio common settings file. In case UBT does not recognize a license entered via UI, you should create a separate license file with the name of PVS-Studio.lic and place it to the '%USERPROFILE%\AppData\Roaming\PVS-Studio' directory.

Unreal Build Tool allows to run the PVS-Studio analysis by adding the following flag in the command line:

-StaticAnalyzer=PVSStudio

For instance, a full command line of Unreal Build Tool might look as follows:

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

To enable analysis when running from IDE, open the project properties for the chosen configuration:

'Properties|Configuration Properties|NMake' in Visual Studio;
'Properties|NMake' in JetBrains Rider;

and add the flag -StaticAnalyzer=PVSStudio in the build and rebuild options (Build Command Line / Rebuild All Command Line).

Note. Note that in this usage scenario, only the analysis will be performed. A build won't be performed.

Note 2. PVS-Studio integration with Unreal Build Tool supports not all analyzer settings, available from Visual Studio (PVS-Studio|Options...). At the moment, PVS-Studio supports adding exceptions for specific directories through 'PVS-Studio|Options...|Don't Check Files', enabling various diagnostic groups, filtration of loaded analysis results through 'Detectable Errors'.

Modification of build scripts for building and analyzing

If you need to configure a simultaneous build and analysis in terms of one Visual Studio configuration, you can create auxiliary scripts (for our example let's name them BuildAndAnalyze and RebuildAndAnalyze, respectively) based on standard Build and Rebuild scripts.

The main change in the RebuildAndAnalyze script is a call for building a new script BuildAndAnalyze.bat, but not Build.bat.

In the BuildAndAnalyze script you need to add removal of actions cache and run of UnrealBuildTool with the analysis flag after performing a successful build.

Actions performed by UBT (builds, analysis and so on) are saved in cache.

Cache removal is needed before the analysis, in order not to save the analysis actions, which will allow for a repeated full analysis. In case if analysis actions are cached, a kind of incremental analysis will be performed on the re-run (only modified files will be analyzed). But the resulting analyzer report will include warnings from all logs (both newly received and old). At the same time if, for example, the analysis is performed by the updated analyzer version (that will include new diagnostic rules), the analyzer won't check unmodified files.

Restoring the cache from the backup is needed to restore saved build actions. If UBT hasn't found saved build actions - build will be re-run.

Removing/restoring the cache is needed in order not to save the analysis results (to be able to perform full analysis again), but not to lose actions on the project build.

Note. Changes described above are based on the standard Build script and the standard script command line. In case if the modified script or non-standard order of arguments is used, additional changes may be required.

Initially, you need to define the number of variables that are needed to remove/restore the action cache file. Operations related to actions cache are relevant for Unreal Engine version 4.21 and later.

Note. Cache files in various engine versions may differ in both extension and location. Take this into account when creating scripts.

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

for %%i in ("%UPROJECT_FILE%") do SET "PROJECT_PATH=%%~dpi"
SET PREFIX=%PROJECT_PATH%Intermediate\Build\%PLATFORM%
SET ACTIONHISTORY_PATH=....
SET ACTIONHISTORY_BAC_PATH= "%ACTIONHISTORY_PATH:"=%.bac"

For various engine versions, the corresponding ACTIONHISTORY_PATH value must be set in the script fragment above.

For version 4.21 and 4.22:

SET ACTIONHISTORY_PATH="%PREFIX%\%PROJECT_NAME%\ActionHistory.bin"

For version 4.23 and 4.24:

SET ACTIONHISTORY_PATH="%PREFIX%\%PLATFORM%\%PROJECT_NAME%\ActionHistory.dat"

For version 4.25:

SET ACTIONHISTORY_PATH="%PREFIX%\%PROJECT_NAME%\ActionHistory.dat"

For version 4.26:

echo %PROJECT_NAME% | findstr /c:"Editor">nul &&
  (SET UE_FOLDER=UE4Editor) || (SET UE_FOLDER=UE4)
SET ACTIONHISTORY_PATH="%PREFIX%\%UE_FOLDER%\%CONFIGURATION%\ActionHistory.bin"
REM If you have build configurations for Client/Server target, then you need
REM to take them into account when defining the UE_FOLDER variable.

After calling UnrealBuildTool for building (and the command 'popd') you need to add the following code:

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%
  )
)

The most important operations from the code above are the cache removal and recovery as well as the run of UnrealBuildTool with the flag -StaticAnalyzer=PVSStudio to perform the analysis.

If needed, use the modified script when working from the IDE environment. For this, you need to specify it as the one you use in the project properties:

'Properties|Configuration Properties|NMake|Build Command Line' in Visual Studio;
'Properties |NMake|Build Command Line' in JetBrains Rider.

Note that when using modified scripts, you don't need to specify the flag -StaticAnalyzer=PVSStudio in the script launching arguments, as it's already set in the script when running UnrealBuildTool for the analysis.

Enabling various diagnostic groups

Starting from version 4.25 of Unreal Engine you can enable various diagnostic groups.

To select the needed diagnostic groups, you need to modify the target files of the project.

To use the appropriate options from the PVS-Studio settings file (Settings.xml), set the value 'true' for the 'WindowsPlatform PVS.UseApplicationSettings' property (for example, in the constructor) in the target file:

public MyUEProjectTarget( TargetInfo Target) : base(Target)
{
  ....
  WindowsPlatform.PVS.UseApplicationSettings = true;
}

You can also include the necessary diagnostic groups in the target file directly. For example, you can enable diagnostics of micro-optimizations as follows:

WindowsPlatform.PVS.ModeFlags =
  UnrealBuildTool.PVSAnalysisModeFlags.Optimizations;

Valid values for enabling the appropriate diagnostic groups are:

Check64BitPortability;
GeneralAnalysis;
Optimizations;
CustomerSpecific;
MISRA.

To enable several groups of diagnostics, use the '|' operator:

WindowsPlatform.PVS.ModeFlags =
    UnrealBuildTool.PVSAnalysisModeFlags.GeneralAnalysis
  | UnrealBuildTool.PVSAnalysisModeFlags.Optimizations;

Handling the analysis results

The path to the file with the analysis results will be displayed in the Output (Build) Visual Studio window (or stdout, if you launched Unreal Build manually from the command line). This file with results is unparsed - it can be opened in IDE:

by the command 'PVS-Studio|Open/Save|Open Analysis Report' by choosing the 'unparsed output' file type in Visual Studio;
by the command 'Tools|PVS-Studio|Open Report' in JetBrains Rider.

Or you can convert the analysis results using the utility PlogConverter in the way is was described in the section for the XML log above.

You can read more about handling the list of diagnostic warnings in the article "Handling the diagnostic messages list". As for working with the analyzer report - check out the article "Managing XML Analyzer Report (.plog file)".

Automatic loading/uploading of logs in IDE

Automatic loading of the analysis log in the PVS-Studio output window when working in IDE is more convenient. For such a scenario, you need to enable the appropriate option:

'PVS-Studio|Options|Specific Analyzer Settings|Save/Load (analyzer report)|AutoloadUnrealEngineLog' in Visual Studio;
'Tools | PVS-Studio|Settings...|Settings|Save/Load (analyzer report)|Autoload Unreal Engine Log' in JetBrains Rider.

Troubleshooting

Unreal Build Tool + PVS-Studio work as follows:

Unreal Build Tool collects the necessary information for PVS-Studio (start commands, compiler options, and so on);
Unreal Build Tool runs PVS-Studio for each compilation unit ('. cpp'):
- PVS-Studio creates a preprocessed file ('.i');
- PVS-Studio runs the analysis;
- PVS-Studio saves the report in '.pvslog';
After analyzing all the files, Unreal Build Tool merges all the '.pvslog' files in a single file, which is usually stored in "$PROJECT\Saved\PVS-Studio\*.pvslog";

However, a problem may appear at any of the above steps. For example, the analyzer could not check one of the source files. Therefore, if the analysis fails, please contact us immediately. We'll try to find out what caused the failure and fix the issue as soon as possible.

Additional files will help us understand the cause of an issue and reproduce it. Please, attach the following additional files to the email:

the build log that was received with the '-verbose' option;
the '.pvslog' files. The paths to '.pvslog' may differ. They depend on the Unreal Engine version. But usually the paths to '.pvslog' are based on {PLATFORM} and {CONFIGURATION}. For example, in UE 4.26 you can find the paths to '.pvslog' in '{PROJECT}\Intermediate\Build\{PLATFORM}\UE4|UE4Editor\{CONFIGURATION}\{PROJECT}\PVS\'.