在Windows OS上检查虚幻引擎项目时的PVS-Studio使用情况

本文重点介绍在Windows操作系统上使用PVS-Studio静态分析器检查虚幻引擎项目的细节：如何安装分析器，检查项目，在何处以及如何查看错误报告。

我们系列文章中不可或缺的部分是与游戏行业相关的主题。 检查AAA游戏中使用的实际引擎- 不客气 ，提出游戏行业中的主要错误- 继续进行 ，查找最流行的游戏引擎之一，虚幻引擎（UE）中的错误- 足够容易 。 在游戏开发以及任何其他应用程序中，代码的质量至关重要。 最好尽早发现错误，最好的选择是自动执行错误-这是静态代码分析器帮助程序员的地方。

在本文中，我将尝试简要地讨论如何使用PVS-Studio静态分析器检查在UE中创建的项目。 PVS-Studio可以通过发现项目中的错误来帮助您改善项目的代码，从而减少您花费在代码审查上的时间。

请注意，本文是关于UE项目分析的现有文档的补充，并不能替代它，而是在很大程度上借鉴了文档的内容。

PVS-Studio安装

安装PVS-Studio分析仪最简单的方法是下载其安装文件 。 为了能够分析在UE中创建的项目，在安装PVS-Studio时需要选择以下组件：“ C和C ++编译器监视”和“与Microsoft Visual Studio集成（Visual C ++ / C＃）”。 最后一点是将PVS-Studio插件集成到Visual Studio IDE中，通过它可以方便地处理错误日志和分析仪本身的常规设置。

要与PVS-Studio完全配合使用，您需要输入许可证。 您可以通过打开Visual Studio（VS）IDE并在“ PVS-Studio |选项... |注册”中输入许可证来执行此操作。 在VS 2019中，PVS-Studio菜单已移至“扩展”菜单，许可证输入窗口的路径如下所示：“扩展” |“ PVS-Studio |选项... |注册”。 该许可证可在我们的网站上找到 。

为了构建UE项目，使用了Epic Games的自定义UnrealBuildTool（UBT）程序，而不是VS（MSBuild）中使用的标准构建系统。 在这方面，PVS-Studio插件无法实现在VS中创建的检查C ++ / C＃项目的常规方案：“ PVS-Studio->检查->当前项目”。 有几种解决方案可以避免这种限制。

使用编译监视系统执行分析

检查UE项目的第一种也是最简单的方法是使用位于PVS-Studio安装目录中的程序C和C ++编译器监视（名为Standalone.exe）。 它的工作原理是，它监视与目标编译器相对应的编译器进程（在本例中为cl.exe），并收集所有必要的信息以进行预处理和源文件的进一步分析。 打开C和C ++编译器监视后，使用菜单“工具”，然后选择“分析文件（C和C ++）...”选项。 按“开始监视”，您将在左下角看到窗口，告诉您编译器正在监视监视：

接下来，构建您的UE项目，然后按“停止监视”。

之后，将开始分析已编译的源文件。 找到的警告报告将显示在程序C和C ++编译器监视的“分析器输出”窗口中。

可以使用CLMonitor.exe控制台程序进行类似的编译器调用监视和检测到的文件的后续分析，该程序位于安装PVS-Studio的同一文件夹中。 CLMonitor.exe有两种操作模式：监视进程启动（对应于目标编译器）的服务器模式和客户端模式（分析在监视阶段检测到的源文件，然后报告分析结果）的客户端模式。 。 为了在服务器模式下运行CLMonitor.exe，请执行以下命令：

CLMonitor.exe monitor 

之后，构建您的UE项目并执行以下命令：

 CLMonitor.exe analyze -l "c:\ptest.plog" 

“ analyze”命令在客户端模式下运行CLMonitor.exe，并关闭在服务器模式下运行的该程序的运行实例。 执行此命令后，CLMonitor.exe将开始执行文件分析。 “-l”选项的参数是文件的路径，将在其中写入分析器的结果。

使用键-StaticAnalyzer = PVSStudio执行分析

分析UE项目的一种不同且更方便的方法是与UBT构建的系统直接集成。 为此，请在VS中打开UE项目的属性窗口，然后在“配置属性”列表中选择“ NMake”。 在属性“ Build Command Line”的文本字段中添加-StaticAnalyzer = PVSStudio。 例如，字段“ Build Command Line”的值可能如下所示：

 C:\Program Files\Epic Games\UE_4.22\Engine\Build\BatchFiles\Build.bat" MyProject Win64 DebugGame -Project="$(SolutionDir)$(ProjectName).uproject" -WaitMutex -FromMsBuild -StaticAnalyzer=PVSStudio 

应该考虑到，在执行项目构建时，只会进行分析，而不会进行构建。 下面将描述构建和分析项目的场景。 还应注意，仅分析自上次项目构建以来已更改的那些源文件。 更改任何包含的.h文件不是在下次构建期间执行分析的原因。 为了执行完整的分析，您需要在属性“ Rebuild All Command Line”的文本字段中添加相同的标志。 现在，在重建项目时，您将获得分析整个项目的结果。

通过修改软件包文件执行分析

现在让我们考虑将PVS-Studio分析仪集成到UBT构建系统中的另一种情况。 这样做时，分析将在执行项目构建/重建后立即开始。 换句话说，您将同时获得一个已建项目和一个包含分析结果的文件。 您可能已经注意到，“构建命令行”字段包含批处理文件Build.bat的路径，而该文件又包含使用所需参数运行UBT的指令。 Build.bat在构建的最开始运行。

关键是更改批处理文件，以便它可以首先使用标准的构建参数运行UBT，然后，如果构建成功完成，则运行相同的UBT，但已经带有附加标志-StaticAnalyzer = PVSStudio。 要实现上述方案，您可以更改批处理文件Build.bat。 最好创建其副本，例如BuildAndAnalyze.bat。 这是实现上述方案所需的操作。 在popd命令之后，立即插入以下说明：

 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 ..\..\Engine\Binaries\DotNET\UnrealBuildTool.exe %* -StaticAnalyzer=PVSStudio -DEPLOY popd SET "UBT_ERR_LEVEL=!ERRORLEVEL!" ) 

如果先前在项目“属性|配置属性| NMake”设置的“构建命令行”字段中安装了-StaticAnalyzer = PVSStudio标志，则必须将其删除。

这种方法的问题在于，将仅分析在构建过程中编译的文件。 也就是说，您不会收到包含项目完整检查的报告文件。 此外，也不会考虑对包括的.h文件所做的任何更改。 因此，我们不能将此分析称为增量分析，因为头文件中的更改不会在下一个构建期间触发分析。 在这种情况下，您可以重建项目，以获取整个项目的分析结果。 但是，完全构建可能需要很长时间，因此您可以按照以下方案进行操作：进行构建，删除缓存文件ActionHistory.bin，使用标志-StaticAnalyzer = PVSStudio运行该构建，还原缓存文件。 ActionHistory.bin文件包含执行增量构建所需的信息以及运行分析器以检查文件的历史记录。

乍一看，这种情况似乎并不是最简单的，所以我们将提供有关如何更改原始Build.bat文件的完整说明。 值得注意的是，此类更改仅与Unreal Engine 4.21及更高版本有关。 在setlocal enabledelayedexpansion命令之后，声明以下变量：

 SET PROJECT_NAME=%1% SET PLATFORM=%2% SET UPROJECT_FILE=%~5 SET ACTIONHISTORY_FOLDER= %UPROJECT_FILE%\..\Intermediate\Build\%PLATFORM%\%PROJECT_NAME% SET ACTION_HISTORY=ActionHistory.bin SET ACTION_HISTORY_BAC=%ACTION_HISTORY%.bac SET ACTIONHISTORY_PATH="%ACTIONHISTORY_FOLDER%\%ACTION_HISTORY%" SET ACTIONHISTORY_BAC_PATH= "%ACTIONHISTORY_FOLDER%\%ACTION_HISTORY_BAC%" 

在popd指令之后，插入以下命令：

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

请注意，正确确定缓存文件路径所需的变量PROJECT_NAME，PLATFORM和UPROJECT_FILE是从Build.bat命令行的参数中获取其值的。 如果这些参数的顺序不同，则必须适当地更改上述三个变量的初始化。

通过UBT修改进行增量项目分析

PVS-Studio可以在增量分析模式下工作。 增量分析旨在仅检查自上次构建以来已更改的那些文件。 在增量分析模式下，PVS-Studio在代码编译后立即在后台模式下自动在开发人员的计算机上运行，​​并分析所有修改的文件。 您可以在我们的文档中找到有关在增量分析模式下使用PVS-Studio的更详细的指南。

通过针对UE项目的增量分析模式的实施，一切都比标准方案中的要复杂得多。 在这种情况下，为了能够执行增量分析（考虑到包含的.h文件中的更改），您必须自己在构建UBT系统中引入编辑。 为此，请访问 github.com上的UE存储库并将其克隆到您的机器上。 要进一步自定义克隆的存储库，您需要完成“启动和运行”部分“ Windows”小节中列出的步骤。 您可以在官方UE信息库的首页上找到此部分。 设置存储库后，即可开始在UBT中进行更改。 为此，请遵循以下路径进入克隆的存储库：\ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool。 打开解决方案UnrealBuildTool.sln，然后在解决方案资源管理器中找到文件PVSToolChain.cs。 在此文件中，将以下代码行添加到类PVSApplicationSettings中：

 /// <summary> /// Whether need incremental analysis or not /// </summary> public bool IncrementalAnalysis; 

此行代码允许从PVS-Studio设置文件中反序列化IncrementalAnalysis选项。 不要忘记启用PVS-Studio增量分析模式本身。 为此，在VS中，打开主菜单中的“扩展”子菜单“ PVS-Studio”，“构建后分析（仅适用于修改的文件）”，“启用”。 现在，在声明变量BaseFileName之后立即添加以下代码行：

 // Get pvslog file FileReference OutputFileLocation = FileReference. Combine(OutputDir, BaseFileName + ".pvslog"); FileItem OutputFileItem = FileItem.GetItemByFileReference(OutputFileLocation); if (ApplicationSettings.IncrementalAnalysis && OutputFileItem.Exists) { // Get object file FileReference ObjectFileLocation = FileReference. Combine(OutputDir, BaseFileName + ".obj"); FileItem ObjectFileItem = FileItem.GetItemByFileReference(ObjectFileLocation); if (ObjectFileItem.Exists && (ObjectFileItem.LastWriteTimeUtc < OutputFileItem.LastWriteTimeUtc)) { continue; } } 

然后在下面删除变量OutputFileLocation和OutputFileItem的先前声明。

在构建UE项目时，将为每个源.cpp文件生成一个对象.obj文件。 增量分析仅涉及检查源.cpp文件，这些源.cpp文件的创建/修改日期晚于.pvslog报告文件之一。 每个源文件都会生成一个单独的.pvslog文件，以后所有的.pvslog文件都将合并为一个最终的.pvslog文件。 完成上述更改后，构建UBT，然后将新建的二进制文件复制到原始UBT的位置。

现在已经准备就绪，在执行UE项目的构建时，您将收到报告日志，其中仅包含分析器针对已编译源文件的结果。 请记住，仅当您以某种方式修改Build.bat文件以执行删除高速缓存文件ActionHistory.bin的方式对UBT进行这种修改时，才有意义（上面已详细介绍了此方案）。 要禁用增量分析模式，只需在模式“禁用”中安装上述选项“构建后分析（仅修改文件）”。

让我再次提醒您：如果在项目“属性|配置属性| NMake”的设置中的“构建命令行”字段中安装了-StaticAnalyzer = PVSStudio标志，则在这种情况下必须将其删除。

打开分析器报告文件并将其自动加载到Visual Studio中

默认情况下，执行UE项目分析时，VS中的PVS-Studio窗口中不会显示报告文件。 它只是通过以下路径相对于项目文件夹存储：\ YouProject \ Saved \ PVS-Studio \。 要在VS中打开此文件，您需要使用以下命令：“ PVS-Studio |打开/保存|打开分析报告”，然后选择“未分析的输出”文件类型。 您也可以使用以下命令在程序C和C ++编译器监视中打开文件报告：“文件|打开PVS-Studio日志”，还选择文件类型“未分析的输出”。

还有另一个更方便的选项来打开分析报告日志，这是它在VS中的自动加载。 为了使它在分析完成后自动加载到VS中的PVS-Studio窗口中，您需要启用适当的选项：“ PVS-Studio |选项|特定分析仪设置|保存/加载（分析仪报告）| AutoloadUnrealEngineLog” 。

下载并尝试PVS-Studio

作为本文的作者，以及直接基于UE引擎构建与项目分析相关的PVS-Studio功能的实现和支持的人员之一，我随时准备帮助读者。 如果您在UE项目中使用PVS-Studio时遇到问题，或者在阅读本文后有任何疑问，我们将很高兴与您聊天。 写信给我们的支持，我将收到有关UE和相关问题的邮件。 谢谢您的关注。

附加链接

1. 安德烈·卡波夫（Andrey Karpov）。 期待已久的虚幻引擎检查4 。 （2014年4月14日）
2. 保罗·埃雷梅耶夫（Paul Eremeev），斯维亚托斯拉夫·拉兹米洛夫（Svyatoslav Razmyslov）。 PVS-Studio团队如何改进虚幻引擎的代码 。 （2015年6月20日）
3. 安德烈·卡波夫（Andrey Karpov）。 静态分析是虚幻引擎开发过程的一部分 。 （2017年6月27日）