在Windows操作系统上检查虚幻引擎项目时使用PVS-Studio

本文专门介绍在Windows操作系统上使用PVS-Studio静态分析器检查Unreal Engine项目的功能：如何安装分析器，如何检查项目，在何处以及如何查看错误报告。

与游戏行业相关的主题是我们文章周期中不可或缺的一部分。 检查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 IDE（VS）并在“ PVS-Studio |选项... |注册”窗口中输入许可证来完成。 在VS 2019中，“扩展名”菜单中的PVS-Studio菜单已删除，因此许可证输入窗口的路径应如下所示：“扩展名” |“ PVS-Studio |选项... |注册”。 许可证可以在我们的网站上获得。

要构建UE项目，不使用VS中使用的标准组装系统-MSBuild，而是使用Epic Games自己的负责组装的程序-UnrealBuildTool（UBT）。 在这方面，PVS-Studio插件无法执行用于检查在VS中创建的C ++ / C＃项目的常用脚本：“ PVS-Studio->检查->当前项目”。 有几种解决方案可以解决此限制。

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

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

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

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

使用位于安装PVS-Studio的同一文件夹中的CLMonitor.exe控制台程序，可以对编译器调用进行类似的跟踪以及对接收到的文件进行后续分析。 CLMonitor.exe具有两种操作模式：服务器模式（在跟踪与目标编译器相对应的进程的开始时）和客户端模式（在分析在跟踪阶段接收到的源文件并生成分析结果报告时）。 要在服务器模式下运行CLMonitor.exe，请运行以下命令：

CLMonitor.exe monitor 

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

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

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

使用-StaticAnalyzer = PVSStudio键执行分析

分析UE项目的另一种更方便的方法是与UBT组装系统直接集成。 为此，在VS中，打开UE项目的属性窗口，然后在“配置属性”列表中选择“ NMake”。 将-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文件，这将不是下一次构建期间进行分析的原因）。 为了执行完整的分析，您需要在“重建所有命令行”属性的文本字段中添加相同的标志。 现在，当您重建项目时，您将获得整个项目的分析结果。

通过修改批处理文件来分析脚本

现在让我们看另一种将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分析仪

我，作为本文的作者，以及直接从事PVS-Studio功能的实现和支持的人员之一，这些功能与基于UE引擎构建的项目的分析有关，随时准备帮助读者。 如果您在UE项目中使用PVS-Studio遇到任何困难，或者在本文中找不到任何答案的问题，那么我将很高兴与您联系。 给我们写信以寻求支持 ，我们将把有关UE和相关问题的信函移交给我。 谢谢您的关注。

网站连结

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

如果您想与讲英语的读者分享这篇文章，请使用翻译链接：Ilya Gainulin。 在Windows OS上检查虚幻引擎项目时的PVS-Studio使用情况 。