Setting up static analysis of an Unreal Engine project
PVS-Studio has long been able to analyze Unreal Engine projects. But since the last note we have been working a lot on this mode. Therefore, I want to talk about how to quickly set up our analyzer to check your project on Unreal Engine.
It is best to consider testing an Unreal Engine project using a real example. As a test project, let's take Lyra, an example game that Epic Games presented with the release of Unreal Engine 5.0. Lyra is a multi-module project that serves as an introduction to the capabilities of UE5.
Work with the project will take place on Windows. We will build using Unreal Engine 5.3.2. For analysis, let's take PVS-Studio 7.29.
Installing PVS-Studio
The PVS-Studio installer itself can be found at this page. To analyze Unreal Engine projects using the method described in this article, you need an Enterprise license. You can get a trial Enterprise license at this link. The installation process is quite simple: just run the installer and follow its instructions. The only additional components required are the plugin for Visual Studio 2022. The installation process is described in documentation. You can also request and enter a license directly in the installer.
Running an analysis
The process of analyzing UE projects is different from analyzing other projects. If you try to run the analysis using standard methods, for example, through a plugin for Visual Studio, you will receive a warning about the impossibility of performing the analysis.
This behavior is due to the peculiarities of organizing the launch of analysis of UE projects. To assemble them it is used UnrealBuildTool, and the analysis is launched through it. In order to carry out a static analysis of the project, and not its assembly, the project itself needs to be configured.
For Unreal Engine projects, there are three ways to define the configuration:
Passing flags directly to UnrealBuildTool;
Setting parameters in .target.cs files;
Including settings in a file BuildConfiguration.xml (usually located in %appdata%\Unreal Engine\UnrealBuildTool).
Each option has its own characteristics and is suitable for different use scenarios.
The first option allows you to set settings for a specific configuration and a specific command (Build/Rebuild). The second method determines the configuration for a specific type of target (you can find out more about targets Here). And the third option can be used for global settings of UE projects.
To start the analysis, we use the first method, and then I will tell you how you can use the second.
To start the analysis, you need to transfer to UnrealBuildTool special flag:
-StaticAnalyzer=PVSStudio
In Visual Studio this can be done by adding this flag to NMake project team and running the build. To do this, open the project properties, select NMake and enter the flag in the field Build Command Line.
In this case, analysis will replace the project assembly. If you add an analyzer flag to the command Rebuild, then each time it is called the entire project will be analyzed. If you modify the command Buildthen when it starts, only changed files will be checked.
IN complete documentation You can learn more about the script for launching the build and analysis of the project.
Launch via NMake available if you open the Unreal Engine project via .sln file.
In JetBrains Rider, it is possible to launch UE projects directly through .uproject. In this case the modification NMake commands are not available and the option specifying the parameter is used StaticAnalyzer V .target.cs file.
By default, when analyzing a UE project, the report does not open in the PVS-Studio plugin window. In order for the analysis report to be loaded into the plugin table, you need to enable the setting before starting the analysis AutoloadUnrealEngineLog. The report itself is saved in the project subfolder Saved/PVS-Studio (in the case of Lyra – “\LyraStarterGame\Saved\PVS-Studio\LyraGame.pvslog”)
We run the analysis and see the following picture:
Modules are analyzed, not project source files.
Plus, the table contains triggers that relate not to the project, but to the Unreal Engine core.
Let's figure out how to get a report that is more relevant to the project being checked.
Setting up the analysis
When the analysis is not configured, automatically generated files are checked. Working with warnings in such files is pointless, and analysis takes additional time. Therefore, we can safely disable their checking.
To do this, in the settings of the PVS-Studio plugin there is an item Don't Check Files > PathMasks. Let's add the following mask there:
*.gen.cpp
Another problem with untuned analysis is the analysis of Unreal Engine kernel source files. If we were developing a plugin for UE or modifying the kernel itself, then such a check would be necessary. But now we are only interested in checking the project. Therefore, let's add to the setting PathMasks path to the Unreal Engine kernel (by default, the path mask is disabled in the settings, corresponding to the standard path to Unreal Engine. If you are using Unreal Engine compiled from GitHub, add the correct mask).
After restarting the analysis, we get the following report:
There are fewer warnings, and you can now work with them comfortably.
Configuration via .target.cs
Now let's look at the second method of launching the PVS-Studio analyzer.
Like other settings, enabling analysis can be configured in .target.cs files. This method is most convenient if you have to frequently regenerate project files. In this scenario the modification NMake commands are not suitable, since they will not be saved when generating a new solution.
To integrate PVS-Studio into UE you need to add .target.cs file parameter StaticAnalyzer with meaning StaticAnalyzer.PVSStudio.
In file LyraGame.Target.cs it will look like this:
public class LyraGameTarget : TargetRules
{
public LyraGameTarget(TargetInfo Target) : base(Target)
{
Type = TargetType.Game;
ExtraModuleNames.AddRange(new string[] { "LyraGame" });
StaticAnalyzer = StaticAnalyzer.PVSStudio;
LyraGameTarget.ApplySharedLyraTargetSettings(this);
}
....
}
IN .target.cs In the file, you can specify several more settings specific to PVS-Studio, for example, enabling diagnostic groups or analysis timeout. You can read more about the settings in documentation. The same settings can be specified in the PVS-Studio plugin interface.
Also in .target.cs file you can define general settings UnrealBuildTool, which will be executed only during analysis. To do this, add the following condition:
if (StaticAnalyzer == StaticAnalyzer.PVSStudio)
{
//Настройки
}
One of the settings for which this scenario is applicable is to disable the mechanism unity build.
Mechanism unity build is a method for speeding up the build of a C++ project by combining several translation units into one. By default this mode is enabled in UnrealBuildTool.
Since the PVS-Studio C++ analyzer checks exactly the translation units, in the analysis log we see that it is not the source files that are analyzed, but the merged files with the prefix Module.
This setting optimizes build time, but may interfere with analysis. Large files will be received for analysis, and a memory shortage may occur.
You can disable this analysis-only mode using the following code:
if (StaticAnalyzer == StaticAnalyzer.PVSStudio)
{
bUseUnityBuild = false;
}
At this point you can finish setting up the analysis.
New diagnostics
Unreal Engine-specific diagnostic projects are starting to appear in PVS-Studio.
For example, a diagnostic rule V1100. It means that in a class not inherited from UObjecta field was detected as a pointer to a type inherited from UObject. The Unreal Engine garbage collector may destroy the object addressed by this pointer.
Another example is diagnostics. V1102. In it, the analyzer marks entities that do not match naming convention for Unreal Engine projects. For example, the names of classes inheriting from UObjectshould start with the prefix Uand enumerations should begin with the prefix E. Compliance with conventions is required for the Unreal Header Tool to work correctly.
Conclusion
Setting up the PVS-Studio analyzer to work with an Unreal Engine project is quite simple. In future releases of Unreal Engine and PVS-Studio, new analysis configuration capabilities will appear. Follow for our updates.
For those interested in using these products together: at this link you can download the analyzer and Here learn more about the integration of PVS-Studio with Unreal Engine.
If you want to share this article with an English-speaking audience, please use the translation link: Mikhail Evtihevich. Setting up static analysis for Unreal Engine project.
