Analysis of Unreal Engine projects

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

A general description of how to integrate PVS-Studio C/C++ analyzer into any build system directly is available here.

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. Open Visual Studio and in the 'PVS-Studio|Options...Registration' window enter your license information (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 the analysis when running from Visual Studio, open properties of the project 'Properties|Configuration Properties|NMake' 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.

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

SET ACTIONHISTORY_FOLDER=....
SET ACTION_HISTORY=....
SET ACTION_HISTORY_BAC=%ACTION_HISTORY%.bac
SET ACTIONHISTORY_PATH="%ACTIONHISTORY_FOLDER%\%ACTION_HISTORY%"
SET ACTIONHISTORY_BAC_PATH=
      "%ACTIONHISTORY_FOLDER%\%ACTION_HISTORY_BAC%"

Different variable values for variables ACTIONHISTORY_FOLDER and ACTION_HISTORY are required for various engine versions in the script fragment above.

For version 4.21 and 4.22:

SET ACTIONHISTORY_FOLDER=
      %UPROJECT_FILE%\..\Intermediate\Build\%PLATFORM%\%PROJECT_NAME%
SET ACTION_HISTORY=ActionHistory.bin

For version 4.23 and later:

SET ACTIONHISTORY_FOLDER=
     %UPROJECT_FILE%\..\Intermediate\Build\%PLATFORM%\%PLATFORM%\
     %PROJECT_NAME%
SET ACTION_HISTORY=ActionHistory.dat

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 necessary, you can use a modified script when working from Visual Studio. To do this, you need to specify it as a used one in project properties: Properties|Configuration Properties|NMake|Build Command Line.

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'. Then choose the file type 'unparsed output'. 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 Visual Studio

Automatic loading of the analysis log in the PVS-Studio output window when working in Visual Studio 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'.


Bugs Found

Checked Projects
409
Collected Errors
14 072
This website uses cookies and other technology to provide you a more personalized experience. By continuing the view of our web-pages you accept the terms of using these files. If you don't want your personal data to be processed, please, leave this site. Learn More →
Accept