Dieser Artikel konzentriert sich auf die Besonderheiten der Überprüfung von Unreal Engine-Projekten mit dem statischen Analysator PVS-Studio unter dem Windows-Betriebssystem: Installieren des Analysators, Überprüfen eines Projekts, Wo und Anzeigen eines Fehlerberichts.
Ein wesentlicher Bestandteil der Reihe unserer Artikel sind Themen aus der Spielebranche. Überprüfen Sie eine aktuelle Engine, die in AAA-Spielen verwendet wird -
Sie sind willkommen , lassen
Sie sich die häufigsten Fehler in der Spielebranche einfallen - finden Sie Fehler in einer der beliebtesten Spiele-Engines Unreal Engine (UE) - ganz
einfach . Bei der Spieleentwicklung sowie bei jeder anderen Anwendung spielt die Qualität des Codes eine Rolle. Fehler werden am besten so früh wie möglich gefunden und am besten automatisch ausgeführt - 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 in UE erstellte Projekte zu überprüfen. PVS-Studio kann Ihnen dabei helfen, den Code Ihres Projekts zu verbessern, indem es Fehler darin findet, wodurch Sie den Zeitaufwand für die Codeüberprüfung reduzieren können.
Bitte beachten Sie, dass dieser Artikel eine Ergänzung zur vorhandenen
Dokumentation zur Analyse von UE-Projekten darstellt und nicht dazu dient, diese zu ersetzen, sondern den Inhalt der Dokumentation weitgehend zu entlehnen.
PVS-Studio Installation
Der PVS-Studio-Analysator lässt sich am einfachsten installieren, indem Sie seine
Installationsdatei herunterladen. Um in 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 #)". Der letzte Punkt ist für die Integration des PVS-Studio-Plugins 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. Sie können dies tun, indem Sie die Visual Studio (VS) -IDE öffnen und die Lizenz unter "PVS-Studio | Optionen ... | Registrierung" eingeben. In VS 2019 wurde das PVS-Studio-Menü in das Menü 'Erweiterungen' verschoben. Der Pfad zum Lizenzeintragsfenster sieht folgendermaßen aus: 'Erweiterungen' | 'PVS-Studio | Optionen ... | Registrierung'. Die Lizenz ist auf unserer
Website verfügbar.
Zum Erstellen von UE-Projekten wird ein benutzerdefiniertes UnrealBuildTool (UBT) -Programm von Epic Games verwendet, kein Standard-Build-System, das in VS (MSBuild) verwendet wird. In dieser Hinsicht kann das PVS-Studio-Plugin kein übliches Szenario zum Überprüfen von C ++ / C # -Projekten implementieren, das in VS erstellt wurde: "PVS-Studio -> Überprüfen -> Aktuelles Projekt". Es gibt verschiedene Lösungen, um diese Einschränkung zu vermeiden.
Durchführen einer Analyse mit dem Kompilierungsüberwachungssystem
Der erste und einfachste Weg, ein UE-Projekt zu überprüfen, ist die Verwendung des Programms C und C ++ Compiler Monitoring (Standalone.exe) im PVS-Studio-Installationsverzeichnis. Das Prinzip seiner Arbeit besteht darin, dass es Compilerprozesse überwacht, die dem Zielcompiler (in diesem Fall cl.exe) entsprechen, und alle erforderlichen Informationen für die Vorverarbeitung und weitere Analyse von Quelldateien sammelt. Nachdem Sie C und C ++ Compiler Monitoring geöffnet haben, verwenden Sie das Menü "Extras" und wählen Sie die Option "Analysieren Sie Ihre Dateien (C und C ++) ...". Klicken Sie auf "Überwachung starten". Das Fenster in der unteren linken Ecke zeigt an, dass die Überwachung von Compileraufrufen ausgeführt wird:
Erstellen Sie als Nächstes Ihr UE-Projekt und klicken Sie auf "Überwachung beenden".
Danach beginnt die Analyse der kompilierten Quelldateien. Der Bericht über die gefundenen Warnungen wird im Fenster "Analyzer-Ausgabe" des Programms C und C ++ Compiler Monitoring angezeigt.
Die Überwachung ähnlicher Compileraufrufe und die anschließende Analyse erkannter Dateien können 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: einen Servermodus, in dem Starts von Prozessen (entsprechend dem Zielcompiler) überwacht werden, und einen Clientmodus (wenn Quelldateien, die in der Überwachungsphase erkannt wurden, analysiert werden, gefolgt von einem Bericht ü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" führt CLMonitor.exe im Client-Modus aus und schließt die laufende Instanz dieses Programms, die im Server-Modus arbeitet. Nach Ausführung dieses Befehls beginnt CLMonitor.exe mit der Ausführung der Dateianalyse. Ein Parameter für die Option "- l" ist ein Pfad zu der Datei, in die die Ergebnisse des Analysators geschrieben werden.
Durchführen einer Analyse mit dem Schlüssel -StaticAnalyzer = PVSStudio
Ein anderer und bequemerer Ansatz zur Analyse von UE-Projekten ist die direkte Integration in das von UBT erstellte System. Öffnen Sie dazu das Eigenschaftsfenster Ihres UE-Projekts in VS und wählen Sie "NMake" in der Liste "Konfigurationseigenschaften". Fügen Sie das -StaticAnalyzer = PVSStudio in das Textfeld der Eigenschaft "Build Command Line" ein. Der Wert des Felds "Befehlszeile erstellen" könnte beispielsweise wie folgt aussehen:
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 sollte berücksichtigt werden, dass ein Projektaufbau nur analysiert und nicht erstellt wird. Das Szenario, in dem ein Projekt sowohl erstellt als auch analysiert wird, wird nachfolgend beschrieben. Es sollte auch beachtet werden, dass nur die Quelldateien analysiert werden, die seit dem letzten Projektaufbau geändert wurden. Das Ändern einer enthaltenen .h-Datei ist kein Grund, die Analyse beim nächsten Build durchzuführen. Um eine vollständige Analyse durchzuführen, müssen Sie dasselbe Flag in das Textfeld der Eigenschaft "Alle Befehlszeilen neu erstellen" einfügen. Wenn Sie das Projekt neu erstellen, erhalten Sie das Ergebnis der Analyse des gesamten Projekts.
Durchführen der Analyse durch Ändern von Paketdateien
Betrachten wir nun ein anderes Szenario, in dem der PVS-Studio-Analysator in das UBT-Build-System integriert wird. Währenddessen beginnt die Analyse direkt nach dem Durchführen eines Projekterbaus / -neubildens. Mit anderen Worten, Sie erhalten sowohl ein erstelltes Projekt als auch eine Datei mit Analyseergebnissen. Möglicherweise haben Sie bemerkt, dass das Feld Build Command Line den Pfad zur Batchdatei Build.bat enthält, die wiederum Anweisungen zum Ausführen von UBT mit den erforderlichen Argumenten enthält. Build.bat wird am Anfang des Builds ausgeführt.
Der Punkt besteht darin, die Batch-Datei so zu ändern, dass sie zuerst UBT mit Standard-Build-Argumenten ausführen und dann, wenn ein Build erfolgreich abgeschlossen wird, dasselbe UBT ausführt, jedoch bereits mit einem zusätzlichen Flag -StaticAnalyzer = PVSStudio. Um das obige Szenario zu implementieren, können Sie die Batchdatei Build.bat ändern. Es ist sogar noch besser, eine Kopie mit dem Namen BuildAndAnalyze.bat zu erstellen. Folgendes müssen Sie tun, um das beschriebene Szenario zu implementieren. Fügen Sie direkt 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 'Eigenschaften | Konfigurationseigenschaften | NMake' installiert wurde, muss es entfernt werden.
Das Problem bei diesem Ansatz ist, dass nur Dateien analysiert werden, die während der Erstellung kompiliert wurden. Das heißt, Sie erhalten keine Berichtsdatei mit einer vollständigen Überprüfung Ihres Projekts. Darüber hinaus werden Änderungen an enthaltenen .h-Dateien nicht berücksichtigt. Daher können wir diese Analyse nicht als inkrementell bezeichnen, da Änderungen in den Header-Dateien die Analyse beim nächsten Build nicht auslösen. In diesem Fall können Sie das Projekt neu erstellen und das Ergebnis der Analyse für das gesamte Projekt abrufen. Die vollständige Erstellung kann jedoch lange dauern, sodass Sie diesem Szenario folgen können: Erstellen Sie eine Erstellung, löschen Sie die Cache-Datei ActionHistory.bin, führen Sie die Erstellung mit dem Flag -StaticAnalyzer = PVSStudio aus und stellen Sie die Cache-Datei wieder her. Die Datei ActionHistory.bin enthält Informationen, die zum Ausführen eines inkrementellen Builds erforderlich sind, sowie den Verlauf der Ausführung des Analysators für überprüfte Dateien.
Auf den ersten Blick scheint dieses Szenario nicht das einfachste zu sein. Daher bieten wir eine vollständige Anleitung, wie Sie die ursprüngliche Build.bat-Datei ändern können. Es ist anzumerken, 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 direkt nach der Anweisung popd 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 für die korrekte Bestimmung des Pfads zur Cache-Datei benötigt werden, ihre Werte aus den Argumenten der Befehlszeile von Build.bat abrufen. Wenn Sie eine andere Reihenfolge dieser Argumente haben, müssen Sie die Initialisierung der drei oben beschriebenen Variablen entsprechend ändern.
Inkrementelle Projektanalyse über UBT-Modifikation
PVS-Studio kann im inkrementellen Analysemodus arbeiten. Inkrementelle Analyse soll nur die Dateien überprüfen, die seit dem letzten Build geändert wurden. Im inkrementellen Analysemodus wird PVS-Studio direkt nach der Codekompilierung automatisch auf dem Computer eines Entwicklers im Hintergrundmodus ausgeführt und analysiert alle geänderten 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 in einem Standardszenario. In diesem Fall müssen Sie Änderungen am Build-UBT-System selbst vornehmen, um die inkrementelle Analyse durchführen zu können (unter Berücksichtigung von Änderungen in den enthaltenen .h-Dateien). Erhalten Sie dazu
Zugriff auf das UE-Repository auf github.com und klonen Sie es auf Ihren Computer. Um das geklonte Repository weiter anzupassen, müssen Sie die Schritte ausführen, die im Abschnitt "Inbetriebnahme", Unterabschnitt "Windows" aufgeführt sind. Sie finden diesen Abschnitt auf der Startseite des offiziellen UE-Repositorys. Sobald Sie Ihr Repository eingerichtet haben, können Sie Änderungen in UBT vornehmen. Folgen Sie dazu diesem Pfad zum geklonten Repository: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Öffnen Sie die Lösung UnrealBuildTool.sln und suchen Sie die Datei PVSToolChain.cs im Projektmappen-Explorer. Fügen Sie in dieser Datei die folgenden Codezeilen in die Klasse PVSApplicationSettings ein:
Mit dieser Codezeile kann die Option IncrementalAnalysis aus den PVS-Studio-Einstellungsdateien deserialisiert werden. Vergessen Sie nicht, den inkrementellen Analysemodus PVS-Studio selbst zu aktivieren. Öffnen Sie dazu in VS "Erweiterungen" im Hauptmenü, Untermenü "PVS-Studio", "Analyse nach dem Erstellen (nur geänderte Dateien)", "Aktiviert". Fügen Sie nun direkt nach der Deklaration der Variablen BaseFileName die folgenden Codezeilen hinzu:
Entfernen Sie dann die vorherigen Deklarationen der Variablen OutputFileLocation und OutputFileItem.
Beim Erstellen des UE-Projekts wird für jede .cpp-Quelldatei eine Objekt-OBJ-Datei generiert. Bei dieser inkrementellen Analyse geht es darum, nur die CPP-Quelldateien zu überprüfen, für die das Erstellungs- / Änderungsdatum der Objektdatei nach dem der Pvslog-Berichtsdatei liegt. Für jede Quelldatei wird eine separate .pvslog-Datei generiert. In Zukunft werden alle .pvslog-Dateien in einem endgültigen .pvslog zusammengeführt. Wenn Sie die obigen Änderungen vorgenommen haben, erstellen Sie UBT und kopieren Sie die neu erstellte Binärdatei an den Speicherort des ursprünglichen UBT.
Jetzt ist alles fertig. Beim Erstellen Ihres UE-Projekts erhalten Sie ein Berichtsprotokoll, das die Ergebnisse des Analysators nur für kompilierte Quelldateien enthält. Beachten Sie, dass eine solche Änderung von UBT nur dann sinnvoll ist, wenn Sie die Datei Build.bat so geändert haben, dass die Cache-Datei ActionHistory.bin entfernt wurde (eine detaillierte Beschreibung dieses Szenarios wurde oben angegeben). Um den inkrementellen Analysemodus zu deaktivieren, installieren Sie einfach die oben im Modus "Deaktiviert" beschriebene Option "Analyse nach dem Erstellen (nur geänderte Dateien)".
Ich möchte Sie noch einmal daran erinnern: Wenn Sie das Flag -StaticAnalyzer = PVSStudio im Feld Build Command Line in den Einstellungen des Projekts 'Eigenschaften | Konfigurationseigenschaften | NMake' installiert haben, muss es in diesem Szenario entfernt werden.
Öffnen der Analyzer-Berichtsdatei und deren automatisches Laden in Visual Studio
Standardmäßig wird bei der Durchführung der UE-Projektanalyse keine Berichtsdatei im PVS-Studio-Fenster in VS angezeigt. Es wird nur 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 den Dateityp 'Nicht analysierte Ausgabe' auswählen. Sie können den Dateibericht auch im Programm C und C ++ Compiler Monitoring mit dem folgenden Befehl öffnen: 'Datei | PVS-Studio-Protokoll öffnen' und den Dateityp 'Nicht analysierte Ausgabe' auswählen.
Es gibt eine weitere bequemere Option zum Öffnen des Analyseberichtsprotokolls, nämlich das automatische Laden in VS. Damit es nach Abschluss der Analyse automatisch in das PVS-Studio-Fenster in VS geladen wird, müssen Sie die entsprechende Option aktivieren: 'PVS-Studio | Optionen | Spezifische Analyzer-Einstellungen | Speichern / Laden (Analyzer-Bericht) | AutoloadUnrealEngineLog' .
Laden Sie PVS-Studio herunter und testen Sie es
Als Autor dieses Artikels sowie als einer derjenigen, die direkt an der Implementierung und Unterstützung der Funktionen von PVS-Studio im Zusammenhang mit der Analyse von Projekten arbeiten, die auf der Basis der UE-Engine erstellt wurden, bin ich bereit, den Lesern zu helfen . Wenn Sie Probleme mit der Verwendung von PVS-Studio mit Ihrem UE-Projekt haben oder nach dem Lesen dieses Artikels Fragen haben, würde ich mich freuen, mit Ihnen zu chatten. Schreiben Sie an unseren Support, ich erhalte E-Mails zu UE und verwandten Themen. Vielen Dank für Ihre Aufmerksamkeit.
Zusätzliche Links
- Andrey Karpov. Eine lang erwartete Überprüfung der unwirklichen Engine 4 . (14. April 2014)
- Paul Eremeev, Svyatoslav Razmyslov. Wie das PVS-Studio-Team den Code der Unreal Engine verbesserte . (20. Juni 2015)
- Andrey Karpov. Statische Analyse als Teil des Entwicklungsprozesses in Unreal Engine . (27. Juni 2017)