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.
In order to use the analyzer, you need a license, which you can get on this 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.
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.
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:
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.
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.
Note. 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' as well as filtration of loaded analysis results through 'Detectable Errors'.
When integrating with UBT, the analyzer runs in the mode when only General Analysis diagnostics are enabled. If you're interested in running the analyzer for other groups of diagnostics, available in PVS-Studio, write to us at firstname.lastname@example.org.
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 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'.