Dieser Artikel befasst sich mit den Funktionen zum Überprüfen von Unreal Engine-Projekten mithilfe des statischen PVS-Studio-Analysators unter dem Windows-Betriebssystem: Installieren des Analysators, Überprüfen des Projekts, Wo und Anzeigen des Fehlerberichts.
Ein wesentlicher Bestandteil des Zyklus unserer Artikel sind Themen, die auf die eine oder andere Weise mit der Spielebranche zusammenhängen. Es ist
einfach, die in AAA-Spielen verwendete physische Engine zu überprüfen -
bitte machen
Sie die häufigsten Fehler in der Spielebranche -, um Fehler in einer der beliebtesten Game-Engines - Unreal Engine (UE) - zu finden. Bei der Entwicklung von Spielen sowie beim Schreiben anderer Anwendungen ist die Qualität des Codes wichtig. Fehler werden am besten so früh wie möglich gefunden, und es ist ratsam, dies automatisch zu tun - hier helfen statische Codeanalysatoren Programmierern.
In diesem Artikel werde ich versuchen, kurz darüber zu sprechen, wie Sie den statischen Analysator PVS-Studio verwenden können, um im UE erstellte Projekte zu analysieren. PVS-Studio hilft dabei, den Code Ihrer Projekte zu verbessern, indem Fehler darin gefunden werden, wodurch Sie den Zeitaufwand für die Codeüberprüfung reduzieren können.
Bitte beachten Sie, dass dieser Artikel zusätzlich zu der
vorhandenen Dokumentation zur Analyse von UE-Projekten dient und nicht dazu dient, diese zu ersetzen, da der Inhalt der Dokumentation weitgehend entlehnt wird.
Installieren Sie PVS-Studio
Der PVS-Studio-Analysator lässt sich am einfachsten installieren, indem Sie seine
Installationsdatei herunterladen. Um in der UE erstellte Projekte analysieren zu können, müssen Sie bei der Installation von PVS-Studio die folgenden Komponenten auswählen: "C- und C ++ - Compiler-Überwachung" und "Integration mit Microsoft Visual Studio (Visual C ++ / C #)". Das letzte Element ist für die Integration des PVS-Studio-Plug-Ins in die Visual Studio-IDE verantwortlich, über die bequem mit dem Fehlerprotokoll und den allgemeinen Einstellungen des Analysators selbst gearbeitet werden kann.
Um vollständig mit PVS-Studio arbeiten zu können, müssen Sie eine Lizenz eingeben. Öffnen Sie dazu die Visual Studio IDE (VS) und geben Sie die Lizenz im Fenster 'PVS-Studio | Optionen ... | Registrierung' ein. In VS 2019 wurde das PVS-Studio-Menü im Menü "Erweiterungen" entfernt, sodass der Pfad zum Lizenzeintragsfenster folgendermaßen aussieht: "Erweiterungen" | "PVS-Studio | Optionen ... | Registrierung". Die Lizenz erhalten Sie auf unserer
Website .
Zum Erstellen von UE-Projekten wird nicht das in VS-MSBuild verwendete Standard-Assembly-System verwendet, sondern das eigene Programm von Epic Games, das für die Assembly verantwortlich ist - UnrealBuildTool (UBT). In dieser Hinsicht kann das PVS-Studio-Plugin das übliche Skript zum Überprüfen von in VS erstellten C ++ / C # -Projekten nicht implementieren: „PVS-Studio -> Überprüfen -> Aktuelles Projekt“. Es gibt verschiedene Lösungen, um diese Einschränkung zu umgehen.
Durchführen einer Analyse mit einem Kompilierungsüberwachungssystem
Die erste und einfachste Möglichkeit, das Projekt-UE zu überprüfen, ist das C- und C ++ - Compiler-Überwachungsprogramm (Standalone.exe), das sich im PVS-Studio-Installationsverzeichnis befindet. Das Prinzip seiner Arbeit besteht darin, dass es die Starts von Prozessen überwacht, die dem Ziel-Compiler entsprechen (in diesem Fall cl.exe), und alle notwendigen Informationen für die Vorverarbeitung und weitere Analyse der Quelldateien sammelt. Verwenden Sie nach dem Öffnen der C- und C ++ - Compilerüberwachung das Menü "Extras" und wählen Sie die Option "Analysieren Sie Ihre Dateien (C und C ++) ...". Klicken Sie auf die Schaltfläche „Überwachung starten“. In der unteren linken Ecke des Bildschirms wird ein Fenster angezeigt, in dem Sie darüber informiert werden, dass die Compileraufrufe überwacht werden:
Erstellen Sie als Nächstes Ihr UE-Projekt und drücken Sie die Taste „Überwachung beenden“.
Danach beginnt die Analyse der kompilierten Quelldateien. Ein Bericht über die gefundenen Warnungen wird im Fenster Analyzer-Ausgabe des C- und C ++ - Compiler-Überwachungsprogramms angezeigt.
Eine ähnliche Verfolgung von Compileraufrufen und eine anschließende Analyse der empfangenen Dateien kann mit dem Konsolenprogramm CLMonitor.exe durchgeführt werden, das sich in demselben Ordner befindet, in dem PVS-Studio installiert wurde. CLMonitor.exe verfügt über zwei Betriebsmodi: den Servermodus (beim Starten von Prozessen, die dem Zielcompiler entsprechen) und den Clientmodus (beim Analysieren der in der Verfolgungsphase empfangenen Quelldateien und beim Erstellen eines Berichts über die Analyseergebnisse). Führen Sie den folgenden Befehl aus, um CLMonitor.exe im Servermodus auszuführen:
CLMonitor.exe monitor
Erstellen Sie danach Ihr UE-Projekt und führen Sie den folgenden Befehl aus:
CLMonitor.exe analyze -l "c:\ptest.plog"
Der Befehl "analyse" startet CLMonitor.exe im Client-Modus und schließt die laufende Instanz dieses Programms, das im Server-Modus arbeitet. Nach Ausführung dieses Befehls beginnt CLMonitor.exe mit der Analyse der Dateien. Der Parameter für die Option "- l" ist der Pfad zu der Datei, in die die Ergebnisse des Analysators geschrieben werden.
Durchführen der Analyse mit dem Schlüssel -StaticAnalyzer = PVSStudio
Ein alternativer und bequemer Ansatz für die Analyse von UE-Projekten ist die direkte Integration in das UBT-Montagesystem. Öffnen Sie dazu in VS das Eigenschaftenfenster Ihres UE-Projekts und wählen Sie in der Liste "Konfigurationseigenschaften" die Option "NMake". Fügen Sie das Flag -StaticAnalyzer = PVSStudio zum Eigenschaftstextfeld Build Command Line hinzu. Der Wert des Felds "Befehlszeile erstellen" sieht beispielsweise folgendermaßen aus:
C:\Program Files\Epic Games\UE_4.22\Engine\Build\BatchFiles\Build.bat" MyProject Win64 DebugGame -Project="$(SolutionDir)$(ProjectName).uproject" -WaitMutex -FromMsBuild -StaticAnalyzer=PVSStudio
Es ist zu berücksichtigen, dass jetzt bei der Durchführung der Montage des Projekts nur eine Analyse durchgeführt wird, die Montage selbst jedoch nicht. Ein Szenario, in dem sowohl die Montage als auch die nachfolgende Analyse durchgeführt werden, wird nachstehend beschrieben. Es ist auch wichtig zu verstehen, dass nur die Quelldateien analysiert werden, die seit dem letzten Build des Projekts geändert wurden (wenn eine Plug-in-H-Datei geändert wurde, ist dies nicht der Grund für die Analyse beim nächsten Build). Um eine vollständige Analyse durchzuführen, müssen Sie dem Textfeld der Eigenschaft "Alle Befehlszeilen neu erstellen" dasselbe Flag hinzufügen. Wenn Sie nun das Projekt neu erstellen, erhalten Sie das Ergebnis der Analyse des gesamten Projekts.
Analyseskript durch Ändern von Batchdateien
Schauen wir uns nun ein anderes Szenario für die Integration des PVS-Studio-Analysators in das UBT-Assemblierungssystem an, bei dem die Analyse unmittelbar nach dem Erstellen / Zusammensetzen des Projekts beginnt, dh am Ausgang erhalten Sie sowohl das zusammengesetzte Projekt als auch die Analyseergebnisdatei. Wie Sie vielleicht bemerkt haben, enthält das Feld Build Command Line den Pfad zur Batch-Datei Build.bat, die wiederum Anweisungen zum Starten von UBT mit den erforderlichen Argumenten enthält. Build.bat beginnt ganz am Anfang des Builds.
Die Idee ist, die Batch-Datei so zu ändern, dass UBT zuerst mit den Standard-Build-Argumenten gestartet wird. Wenn die Build-Phase erfolgreich abgeschlossen wurde, führen Sie dasselbe UBT erneut aus, jedoch mit dem zusätzlichen Flag -StaticAnalyzer = PVSStudio. Um das obige Szenario zu implementieren, können Sie die Batchdatei Build.bat wie folgt ändern (und am besten eine Kopie mit dem Namen BuildAndAnalyze.bat erstellen). Fügen Sie unmittelbar nach dem Befehl popd die folgenden Anweisungen ein:
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!" )
Wenn das Flag -StaticAnalyzer = PVSStudio zuvor im Feld Build Command Line in den Projekteinstellungen 'Properties | Configuration Properties | NMake' gesetzt wurde, muss es entfernt werden.
Das Problem bei diesem Ansatz ist, dass nur die Dateien analysiert werden, die während der Erstellungsphase kompiliert wurden. Das heißt, Sie erhalten keine Berichtsdatei mit einer vollständigen Überprüfung Ihres Projekts. Darüber hinaus werden Änderungen an den enthaltenen .h-Header-Dateien nicht berücksichtigt. Daher können wir eine solche Analyse nicht als inkrementell bezeichnen, da Änderungen in den Header-Dateien nicht dazu führen, dass die Analyse während einer neuen Assembly durchgeführt wird. In diesem Fall können Sie das Projekt neu erstellen und ein Analyseergebnis für das gesamte Projekt erhalten. Das Abschließen der Assembly kann jedoch lange dauern, sodass Sie das folgende Szenario ausführen können: Erstellen, Löschen der Cache-Datei - ActionHistory.bin, Starten der Assembly mit dem Flag -StaticAnalyzer = PVSStudio und Wiederherstellen der Cache-Datei. Die Datei ActionHistory.bin enthält die erforderlichen Informationen zum Ausführen inkrementeller Assemblys sowie den Startverlauf des Analysators für die gescannten Dateien.
Auf den ersten Blick scheint dieses Szenario nicht das einfachste zu sein. Daher werden wir eine vollständige Anleitung bereitstellen, wie Sie die ursprüngliche Build.bat-Datei ändern können. Es ist erwähnenswert, dass solche Änderungen nur für Unreal Engine Version 4.21 und höher relevant sind. Deklarieren Sie nach dem Befehl setlocal enabledelayedexpansion die folgenden Variablen:
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%"
Fügen Sie unmittelbar nach der popd-Anweisung die folgenden Befehle ein:
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% ) )
Beachten Sie, dass die Variablen PROJECT_NAME, PLATFORM und UPROJECT_FILE, die zum korrekten Ermitteln des Cache-Pfads erforderlich sind, ihre Werte aus den Build.bat-Befehlszeilenargumenten abrufen. Wenn Sie eine andere Reihenfolge dieser Argumente haben, müssen Sie die Initialisierung der drei oben beschriebenen Variablen entsprechend ändern.
Inkrementelle Projektanalyse durch Modifikation von UBT
PVS-Studio kann im inkrementellen Analysemodus arbeiten. Inkrementelle Analysen sollen nur die Quelldateien überprüfen, die seit dem letzten Build des Projekts geändert wurden. Im inkrementellen Analysemodus startet PVS-Studio unmittelbar nach dem Kompilieren des Codes automatisch im Hintergrund auf dem Computer des Entwicklers und analysiert alle von den Änderungen betroffenen Dateien. Eine ausführlichere Anleitung zur Verwendung von PVS-Studio im inkrementellen Analysemodus finden Sie in unserer
Dokumentation .
Mit der Implementierung des inkrementellen Analysemodus für UE-Projekte ist alles wieder etwas komplizierter als mit dem Standardarbeitsszenario. In diesem Fall müssen Sie selbst Änderungen am UBT-Assembly-System vornehmen, um eine inkrementelle Analyse durchführen zu können (unter Berücksichtigung von Änderungen in den verbundenen .h-Dateien). Greifen Sie dazu
auf das UE-Repository auf github.com zu und klonen Sie es auf Ihren Computer. Um das geklonte Repository weiter zu konfigurieren, müssen Sie die Schritte ausführen, die im Abschnitt "Inbetriebnahme" des Unterabschnitts "Windows" aufgeführt sind. Sie finden den genannten Abschnitt auf der Hauptseite des offiziellen UE-Repositorys. Sobald Sie Ihr Repository eingerichtet haben, können Sie Änderungen an UBT vornehmen. Gehen Sie dazu im geklonten Repository zum folgenden Pfad: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Öffnen Sie die Lösung UnrealBuildTool.sln und suchen Sie im Projektmappen-Explorer die Datei PVSToolChain.cs. Fügen Sie in dieser Datei der PVSApplicationSettings-Klasse die folgenden Codezeilen hinzu:
Mit dieser Codezeile kann die Option IncrementalAnalysis aus der PVS-Studio-Einstellungsdatei deserialisiert werden. Vergessen Sie nicht, den inkrementellen PVS-Studio-Analysemodus selbst zu aktivieren. Öffnen Sie dazu den Hauptmenüpunkt Erweiterungen in VS, dem Untermenü PVS-Studio, Analyse nach dem Erstellen (nur geänderte Dateien), Aktiviert. Fügen Sie nun unmittelbar nach dem Deklarieren der BaseFileName-Variablen die folgenden Codezeilen hinzu:
Löschen Sie danach die vorherigen Variablendeklarationen OutputFileLocation und OutputFileItem unten im Code.
Während des Assemblierungsprozesses des Projekt-UE wird für jede Quell-CPP-Datei eine OBJ-Objektdatei generiert. Die Idee dieser inkrementellen Analyse besteht darin, nur die Quell-CPP-Dateien zu überprüfen, für die das Erstellungs- / Änderungsdatum ihrer Objektdatei neuer ist als das der .pvslog-Berichtsdatei (für jede Quelldatei wird eine eigene .pvslog-Datei generiert, und dann alles .pvslog-Dateien werden zu einem endgültigen .pvslog zusammengefasst. Nachdem Sie die obigen Änderungen vorgenommen haben, kompilieren Sie das UBT und kopieren Sie die neu gesammelte Binärdatei an den Speicherort des ursprünglichen UBT.
Alles ist fertig. Wenn Sie die Montage des UE-Projekts abgeschlossen haben, erhalten Sie ein Berichtsprotokoll mit den Ergebnissen des Analysators nur für die kompilierten Quelldateien. Denken Sie daran, dass eine solche Änderung an UBT nur dann sinnvoll ist, wenn Sie die Datei Build.bat so ändern, dass die Cache-Datei ActionHistory.bin gelöscht wird (eine detaillierte Beschreibung dieses Szenarios wurde oben beschrieben). Um den inkrementellen Analysemodus zu deaktivieren, setzen Sie einfach die oben beschriebene Option "Analyse nach dem Erstellen (nur geänderte Dateien)" auf "Deaktiviert".
Ich möchte Sie noch einmal daran erinnern: Wenn Sie das Flag -StaticAnalyzer = PVSStudio im Feld Build Command Line in den Projekteinstellungen 'Eigenschaften | Konfigurationseigenschaften | NMake' setzen, müssen Sie es in diesem Szenario entfernen.
Öffnen der Analyzer-Berichtsdatei und deren automatisches Laden in Visual Studio
Standardmäßig wird bei der Analyse eines Projekt-UE die Berichtsdatei nicht in das PVS-Studio-Fenster in VS geladen. Es wird einfach relativ zum Projektordner unter folgendem Pfad gespeichert: \ YouProject \ Saved \ PVS-Studio \. Um diese Datei in VS zu öffnen, müssen Sie den folgenden Befehl verwenden: 'PVS-Studio | Öffnen / Speichern | Analysebericht öffnen' und die Option 'Nicht analysierte Ausgabe' in der Option zur Auswahl des Dateityps festlegen. Sie können die Berichtsdatei auch im C- und C ++ - Compiler-Überwachungsprogramm mit dem folgenden Befehl öffnen: 'Datei | PVS-Studio-Protokoll öffnen' und den Dateityp 'Nicht analysierte Ausgabe' auswählen.
Es gibt eine bequemere Option zum Öffnen des Analyseprotokolls - es wird automatisch in VS geladen. Um es nach Abschluss der Analyse automatisch in das PVS-Studio-Fenster in VS zu laden, müssen Sie die entsprechende Option aktivieren: 'PVS-Studio | Optionen | Spezifische Analyzer-Einstellungen | Speichern / Laden (Analyzer-Bericht) | AutoloadUnrealEngineLog'.
Laden Sie den PVS-Studio Analyzer herunter und testen Sie ihn
Ich als Autor dieses Artikels und als einer derjenigen, die direkt an der Implementierung und Unterstützung der PVS-Studio-Funktionalität im Zusammenhang mit der Analyse von Projekten arbeiten, die auf der Basis der UE-Engine erstellt wurden, bin bereit, den Lesern zu helfen. Wenn Sie Probleme bei der Verwendung von PVS-Studio mit Ihrem UE-Projekt haben oder Fragen haben, auf die Sie in diesem Artikel keine Antwort finden konnten, werde ich mich freuen, mit Ihnen zu sprechen. Schreiben Sie uns zur
Unterstützung und Briefe werden mir bezüglich UE und verwandten Themen übergeben. Vielen Dank für Ihre Aufmerksamkeit.
Sitelinks
- Andrey Karpov. Der lang erwartete Check von Unreal Engine 4 . (14. April 2014)
- Pavel Eremeev, Svyatoslav Razmyslov. Wie das PVS-Studio-Team den Unreal Engine-Code verbessert hat . (20. Juni 2015)
- Andrey Karpov. Statische Analyse als Teil des Unreal Engine-Entwicklungsprozesses . (27. Juni 2017)
Wenn Sie diesen Artikel einem englischsprachigen Publikum zugänglich machen möchten, verwenden Sie bitte den Link zur Übersetzung: Ilya Gainulin.
PVS-Studio-Verwendung beim Überprüfen von Unreal Engine-Projekten unter Windows .