To get a trial key
fill out the form below
Team License (a basic version)
Enterprise License (an extended version)
* By clicking this button you agree to our Privacy Policy statement

Request our prices
New License
License Renewal
--Select currency--
USD
EUR
RUB
* By clicking this button you agree to our Privacy Policy statement

Free PVS-Studio license for Microsoft MVP specialists
* By clicking this button you agree to our Privacy Policy statement

To get the licence for your open-source project, please fill out this form
* By clicking this button you agree to our Privacy Policy statement

I am interested to try it on the platforms:
* By clicking this button you agree to our Privacy Policy statement

Message submitted.

Your message has been sent. We will email you at


If you haven't received our response, please do the following:
check your Spam/Junk folder and click the "Not Spam" button for our message.
This way, you won't miss messages from our team in the future.

>
>
Analysis of Unreal Engine projects
Analyzer diagnostics
General Analysis (C++)
General Analysis (C#)
General Analysis (Java)
Diagnosis of micro-optimizations (C++)
Diagnosis of 64-bit errors (Viva64, C++)
Customer specific requests (C++)
MISRA errors
AUTOSAR errors
OWASP errors (C#)
Problems related to code analyzer
Additional information
Contents

Analysis of Unreal Engine projects

May 25 2022

This section describes the analysis of Unreal Engine projects on Windows operating system.

Unreal Engine projects check is available only under the PVS-Studio Enterprise license. You can request the trial Enterprise license here.

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

Issues with running the PVS-Studio analyzer on Unreal Engine version 5 or higher

The Unreal Engine version 5.0 has a bug because of which Unreal Engine Build Tool can't find the analyzer core on the default path: %ProgramFiles(x86)%\PVS-Studio\x64\PVS-Studio.exe:

UnrealBuildTool/image1.png

We have already made Pull Request which fixes the bug. As of now, there's a temporary solution — you need to copy the PVS-Studio.exe file from the "%ProgramFiles(x86)%\PVS-Studio\x64" folder to "...\UE_5.0\Engine\Restricted\NoRedist\Extras\ThirdPartyNotUE\PVS-Studio".

Note. If this bug isn't fixed by the moment of reading this document, you need to copy the PVS-Studio.exe file from the installation directory (by default, it's "%ProgramFiles(x86)%\PVS-Studio\x64") to "...\UE_5.0\Engine\Restricted\NoRedist\Extras\ThirdPartyNotUE\PVS-Studio" after every analyzer update.

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 Unreal Engine 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 1. Note that in this usage scenario, the project won't be built. Instead, all (on Rebuild command) or changed (on Build command) project files are preprocessed and then the project is analyzed.

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

How to use the analyzer with the project build (for Unreal Engine versions 4.22 and higher)

If you need to configure a simultaneous project build and its 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.

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 actions, but not to lose actions on the project build at the same time. It is necessary not to save the analysis actions to the cache because the unmodified files will not be checked if the analysis is performed by the updated version of the analyzer, in which new diagnostic rules were added. Deleting/restoring the cache allows you to avoid this situation. Because of this, even unmodified files will be checked by the new diagnostics, as a result, these diagnostics may detect potential errors or vulnerabilities that were not detected before.

Note 1. 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.

Note 2. Cache files in various Unreal 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.

How to calculate the path to the Unreal Build Tool actions cache file when modifying the build scripts

For versions 4.21 and 4.22

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

For versions 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 versions 4.26 and 4.27

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

For versions 5.0 and higher

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

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 Backup %ACTIONHISTORY_PATH%
    COPY %ACTIONHISTORY_PATH% %ACTIONHISTORY_BAC_PATH%
    ECHO Removing %ACTIONHISTORY_PATH%
    DEL  %ACTIONHISTORY_PATH%
  )
  ..\..\Engine\Binaries\DotNET\UnrealBuildTool.exe 
    %* -StaticAnalyzer=PVSStudio -DEPLOY 
  popd

  IF EXIST %ACTIONHISTORY_BAC_PATH% (
    ECHO Recovering %ACTIONHISTORY_PATH%
    COPY %ACTIONHISTORY_BAC_PATH% %ACTIONHISTORY_PATH%
    ECHO Removing %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. 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.

Selecting 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 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 it 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.

How to exclude files from the analysis with PathMasks

You can specify the directory masks in the settings of the PVS-Studio plugin for Visual Studio, the PVS-Studio plugin for Rider, and C and C++ Compiler Monitoring UI utility (Standalone.exe). If the full path to the file contains a fragment that matches with one of the PathMasks' masks, this file will be excluded from the analysis.

Important. For Unreal Engine projects, only directory masks (PathMasks) are relevant, but not file name masks (FileNameMasks).

In the plugin for Visual Studio, these settings are located in Extensions > PVS-Studio > Options... > Don't Check Files:

UnrealBuildTool/image2.png

In Rider, masks for excluding directories are located in Tools > PVS-Studio > Settings > Excludes:

UnrealBuildTool/image3.png

Similar settings are available for C and C++ Compiler Monitoring UI (Standalone.exe) in Tools > Options... > Don't Check Files:

UnrealBuildTool/image5.png

Among these masks, there is a special default mask to exclude the Unreal Engine source code: \Epic Games\UE_. This mask is added by default to prevent the analysis results from being cluttered with unnecessary warnings, information about which is unlikely to be useful for most developers.

Note. If Unreal Engine is installed in a non-default path, the analyzer's report will contain warnings issued for the Unreal Engine source code. If they bother you, then add the directory in which Unreal Engine is installed to PathMasks.

For more information on excluding files from analysis, see "Settings: Don't Check Files".

Baselining analysis results in Unreal Engine projects

Baselining of analyzer warnings is based on the message suppression feature.

Numerous analyzer warnings on legacy code often disrupt the regular use of static analysis. The legacy code is usually well tested and works stably, so it may be unnecessary to edit all the warnings there. Moreover, if the size of the code base is large enough, such edits can take a huge amount of time and effort. However, if you leave warnings for the existing code unhandled, they will disrupt the work with the warnings for the fresh code.

To solve this problem and start using static analysis on a regular basis, you can disable warnings for the legacy code. To do this, the PVS-Studio plugins for Visual Studio and JetBrains Rider have interface elements that allow you to suppress analyzer warnings in the corresponding IDEs.  

The warning suppression mechanism for Unreal Engine projects in these IDEs has only one difference for the user. For UE projects, the user needs to manually add one suppress file to the solution. For non-UE projects, suppress files can also be added automatically to each project.  

If you try to suppress warnings in Visual Studio or Rider for the UE project when the solution suppress file does not exist, you will get a warning. In Visual Studio: 

UnrealBuildTool/image7.png

And in Rider:  

UnrealBuildTool/image8.png

These messages describe the steps to add a solution-level suppress file. 

You can see a detailed description of the suppression mechanism in these IDEs in the corresponding sections of the documentation: 

For more information about the warning suppression mechanism, see the documentation section "Baselining analysis results (suppressing warnings for existing code)". 

You can also suppress analyzer warnings via the PVS-Studio_Cmd.exe console utility. To do this, PVS-Studio_Cmd.exe has the SuppressOnly and FilterFromSuppress modes. The SuppressOnly mode allows you to save the previously received analyzer warnings to a suppress file. A command example to create a suppress file:

PVS-Studio_Cmd.exe -t path/to/solution/file ^
                   -a SuppressOnly ^
                   -o path/to/report.pvslog ^
                   -u path/to/suppress_file.suppress

As a result of executing this command, all the issued warnings from the path/to/report.pvslog report will be added to path/to/suppress_file.suppress. If suppress file from the -u flag doesn't exist, it will be created.

The FilterFromSuppress allows you to use the suppress file to filter the messages. Here's the example of filtering the analyzer's report with a suppress file:

PVS-Studio_Cmd.exe -t path/to/solution/file ^
                   -a FilterFromSuppress ^
                   -o path/to/report.pvslog ^
                   -u path/to/suppress_file.suppress

As a result of executing this command, the path/to/report_filtered.plog file will be created next to the path/to/ report.pvslog report. It will contain all analyzer warnings missing from path/to/suppress_file.suppress.

To have analyzer warnings in the report only for new or changed code, you first need to get a suppress file that will serve as a "starting point" (baseline). To get a suppress file, you need to do the following:

  • run the analysis of the Unreal Engine project and get a .pvslog report (by default it is located in the ProjectDir/Saved/PVS-Studio folder);
  • get a suppress file for the analyzer report using the SuppressOnly mode;
  • filter the received analyzer reports with the FilterFromSuppress mode. Filter the reports using the previously obtained suppress file.

The analyzer report in the .plog format obtained after filtering in the FilterFromSuppress mode can be opened in Visual Studio with the plugin for PVS-Studio. You can also use the C and C ++ Compiler Monitoring UI utility. It is also possible to convert the .plog report to other formats using the PlogConverter.exe utility in Windows.

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 the PVS-Studio C++ analyzer core 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\'.

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