Cet article se concentre sur les spécificités de la vérification des projets Unreal Engine avec l'analyseur statique PVS-Studio sur le système d'exploitation Windows: comment installer l'analyseur, vérifier un projet, où et comment afficher un rapport d'erreur.
Une partie intégrante de la série de nos articles sont des sujets liés à l'industrie du jeu. Vérifiez un moteur réel utilisé dans les jeux AAA -
vous êtes les bienvenus , venez avec les meilleures erreurs dans l'industrie du jeu -
allez-y , trouvez des bugs dans l'un des moteurs de jeux les plus populaires Unreal Engine (UE) -
assez facile . Dans le développement de jeux, ainsi que dans toute autre application, la qualité du code est importante. Les erreurs sont mieux détectées le plus tôt possible et la meilleure option est de le faire automatiquement - c'est là que les analyseurs de code statique viennent en aide aux programmeurs.
Dans cet article, je vais essayer de parler brièvement de la façon dont vous pouvez utiliser l'analyseur statique PVS-Studio pour vérifier les projets créés dans UE. PVS-Studio peut vous aider à améliorer le code de votre projet en y trouvant des bogues, vous permettant ainsi de réduire le temps que vous passez sur la révision du code.
Veuillez noter que cet article est un ajout à la
documentation existante sur l'analyse des projets UE et ne sert pas à le remplacer, empruntant largement le contenu de la documentation.
Installation de PVS-Studio
La façon la plus simple d'installer l'analyseur PVS-Studio est de télécharger son
fichier d'installation . Pour pouvoir analyser les projets créés dans UE, vous devez sélectionner les composants suivants lors de l'installation de PVS-Studio: "Surveillance du compilateur C et C ++" et "Intégration avec Microsoft Visual Studio (Visual C ++ / C #)". Le dernier point est responsable de l'intégration du plugin PVS-Studio dans l'IDE de Visual Studio, à travers lequel il est pratique de travailler avec le journal des erreurs et avec les paramètres généraux de l'analyseur lui-même.
Pour fonctionner pleinement avec PVS-Studio, vous devez saisir une licence. Vous pouvez le faire en ouvrant Visual Studio (VS) IDE et en entrant la licence dans 'PVS-Studio | Options ... | Enregistrement'. Dans VS 2019, le menu PVS-Studio a été déplacé vers le menu 'Extensions', le chemin d'accès à la fenêtre d'entrée de licence ressemble à ceci: 'Extensions' | 'PVS-Studio | Options ... | Enregistrement'. La licence est disponible sur notre
site Web .
Pour construire des projets UE, un programme UnrealBuildTool (UBT) personnalisé d'Epic Games est utilisé, pas un système de construction standard, utilisé dans VS (MSBuild). À cet égard, le plugin PVS-Studio n'est pas en mesure d'implémenter un scénario habituel de vérification des projets C ++ / C #, créé dans VS: "PVS-Studio -> Vérifier -> Projet actuel". Il existe plusieurs solutions pour éviter cette limitation.
Exécution d'une analyse avec le système de surveillance de la compilation
La première et la plus simple pour vérifier un projet UE consiste à utiliser le programme C et C ++ Compiler Monitoring (nommé Standalone.exe), situé dans le répertoire d'installation de PVS-Studio. Le principe de son travail est qu'il surveille les processus du compilateur qui correspondent au compilateur cible (dans ce cas, cl.exe) et rassemble toutes les informations nécessaires pour le prétraitement et l'analyse approfondie des fichiers source. Après avoir ouvert la surveillance du compilateur C et C ++, utilisez le menu "Outils" et choisissez l'option "Analyser vos fichiers (C et C ++) ...". Appuyez sur "Démarrer la surveillance" et vous verrez la fenêtre dans le coin inférieur gauche vous indiquant que la surveillance des appels du compilateur est en cours:
Ensuite, construisez votre projet UE et appuyez sur "Arrêter la surveillance".
Après cela, l'analyse des fichiers source compilés commencera. Le rapport des avertissements trouvés sera affiché dans la fenêtre "Sortie analyseur" du programme C et C ++ Compiler Monitoring.
Une surveillance d'appels de compilateur similaire et une analyse ultérieure des fichiers détectés peuvent être effectuées à l'aide du programme de console CLMonitor.exe, situé dans le même dossier, où PVS-Studio a été installé. CLMonitor.exe a deux modes de fonctionnement: un mode serveur lorsque les lancements de processus (correspondant au compilateur cible) sont surveillés et un mode client (lorsque les fichiers source, détectés au stade de la surveillance, sont analysés, suivi d'un rapport des résultats d'analyse) . Afin d'exécuter CLMonitor.exe en mode serveur, exécutez la commande suivante:
CLMonitor.exe monitor
Après cela, générez votre projet UE et exécutez la commande ci-dessous:
CLMonitor.exe analyze -l "c:\ptest.plog"
La commande "analyse" exécute CLMonitor.exe en mode client et ferme l'instance en cours d'exécution de ce programme, travaillant en mode serveur. Après avoir exécuté cette commande, CLMonitor.exe commencera à exécuter l'analyse des fichiers. Un paramètre pour l'option "- l" est un chemin d'accès au fichier, dans lequel les résultats de l'analyseur seront écrits.
Exécution d'une analyse avec la clé -StaticAnalyzer = PVSStudio
Une approche différente et plus pratique pour analyser les projets UE est une intégration directe avec le système construit UBT. Pour ce faire, ouvrez la fenêtre de propriétés de votre projet UE dans VS et choisissez "NMake" dans la liste "Propriétés de configuration". Ajoutez -StaticAnalyzer = PVSStudio dans le champ de texte de la propriété "Build Command Line". Par exemple, la valeur du champ "Build Command Line" peut ressembler à ceci:
C:\Program Files\Epic Games\UE_4.22\Engine\Build\BatchFiles\Build.bat" MyProject Win64 DebugGame -Project="$(SolutionDir)$(ProjectName).uproject" -WaitMutex -FromMsBuild -StaticAnalyzer=PVSStudio
Il convient de prendre en compte que lors de l'exécution d'une construction de projet, il sera uniquement analysé, pas construit. Le scénario dans lequel un projet est à la fois construit et analysé sera décrit ci-dessous. Il convient également de noter que seuls les fichiers source qui ont été modifiés depuis la dernière version du projet seront analysés. La modification d'un fichier .h inclus n'est pas une raison pour effectuer l'analyse lors de la prochaine génération. Pour effectuer une analyse complète, vous devez ajouter le même indicateur dans le champ de texte de la propriété "Rebuild All Command Line". Maintenant, lors de la reconstruction du projet, vous obtiendrez le résultat de l'analyse de l'ensemble du projet.
Exécution de l'analyse via la modification des fichiers de package
Considérons maintenant un autre scénario de l'intégration de l'analyseur PVS-Studio dans le système de construction UBT. Ce faisant, l'analyse démarre juste après avoir effectué une construction / reconstruction de projet. En d'autres termes, vous obtenez à la fois un projet construit et un fichier avec les résultats d'analyse. Vous avez peut-être remarqué que le champ Build Command Line contient le chemin d'accès au fichier de commandes Build.bat, qui, à son tour, contient des instructions pour exécuter UBT avec les arguments nécessaires. Build.bat s'exécute au tout début de la génération.
Le point est de changer le fichier batch afin qu'il puisse d'abord exécuter UBT avec des arguments de construction standard, puis, si une génération se termine avec succès, exécutez le même UBT, mais déjà avec un indicateur supplémentaire -StaticAnalyzer = PVSStudio. Pour implémenter le scénario ci-dessus, vous pouvez modifier le fichier de commandes Build.bat. Il est encore préférable de créer sa copie nommée, par exemple, BuildAndAnalyze.bat. Voici ce que vous devez faire pour implémenter le scénario décrit. Juste après la commande popd, insérez les instructions suivantes:
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!" )
Si l'indicateur -StaticAnalyzer = PVSStudio a été précédemment installé dans le champ Build Command Line dans les paramètres 'Properties | Configuration Properties | NMake' du projet, il doit être supprimé.
Le problème avec cette approche est que seuls les fichiers qui ont été compilés lors de la génération seront analysés. Autrement dit, vous ne recevrez pas de fichier de rapport avec une vérification complète de votre projet. De plus, toute modification apportée aux fichiers .h inclus ne sera pas non plus prise en compte. Par conséquent, nous ne pouvons pas appeler cette analyse incrémentielle, car les modifications dans les fichiers d'en-tête ne déclencheront pas l'analyse lors de la prochaine génération. Dans ce cas, vous pouvez reconstruire le projet, en obtenant le résultat de l'analyse pour l'ensemble du projet. Cependant, la génération complète peut prendre du temps, vous pouvez donc suivre ce scénario: créer une génération, supprimer le fichier de cache ActionHistory.bin, exécuter la génération avec l'indicateur -StaticAnalyzer = PVSStudio, restaurer le fichier de cache. Le fichier ActionHistory.bin contient les informations nécessaires pour effectuer une génération incrémentielle ainsi que l'historique d'exécution de l'analyseur pour les fichiers vérifiés.
À première vue, ce scénario peut ne pas sembler le plus simple, nous vous fournirons donc un ensemble complet d'instructions sur la façon de modifier le fichier Build.bat d'origine. Il convient de noter que ces modifications ne concernent que Unreal Engine version 4.21 et versions ultérieures. Après la commande setlocal enabledelayedexpansion, déclarez les variables suivantes:
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%"
Juste après l'instruction popd, insérez ces commandes:
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% ) )
Notez que les variables PROJECT_NAME, PLATFORM et UPROJECT_FILE, nécessaires pour déterminer correctement le chemin d'accès au fichier cache, obtiennent leurs valeurs à partir des arguments de la ligne de commande de Build.bat. Si vous avez un ordre différent de ces arguments, vous devez modifier de manière appropriée l'initialisation des trois variables, décrites ci-dessus.
Analyse de projet incrémentielle via modification UBT
PVS-Studio est capable de travailler en mode d'analyse incrémentale. L'analyse incrémentielle est destinée à vérifier uniquement les fichiers qui ont été modifiés depuis la dernière génération. En mode d'analyse incrémentielle, PVS-Studio s'exécute automatiquement sur l'ordinateur d'un développeur en mode arrière-plan juste après la compilation du code et analyse tous les fichiers modifiés. Vous pouvez trouver un guide plus détaillé sur l'utilisation de PVS-Studio en mode d'analyse incrémentielle dans notre
documentation .
Avec l'implémentation du mode d'analyse incrémentale pour les projets UE, tout est encore un peu plus compliqué que dans un scénario standard. Dans ce cas, pour pouvoir effectuer l'analyse incrémentielle (en tenant compte des changements dans les fichiers .h inclus), vous devrez introduire vous-même les modifications dans le système UBT de génération. Pour ce faire,
accédez au référentiel UE sur github.com et clonez-le sur votre machine. Pour personnaliser davantage le référentiel cloné, vous devrez effectuer les étapes répertoriées dans la section "Mise en service et exécution", sous-section "Windows". Vous pouvez trouver cette section sur la première page du référentiel officiel de l'UE. Une fois que vous avez configuré votre référentiel, vous pouvez commencer à apporter des modifications dans UBT. Pour ce faire, suivez ce chemin d'accès au référentiel cloné: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Ouvrez la solution UnrealBuildTool.sln et recherchez le fichier PVSToolChain.cs dans l'Explorateur de solutions. Dans ce fichier, ajoutez les lignes de code suivantes dans la classe PVSApplicationSettings:
Cette ligne de code permet de désérialiser l'option IncrementalAnalysis des fichiers de paramètres PVS-Studio. N'oubliez pas d'activer le mode d'analyse incrémentielle PVS-Studio lui-même. Pour ce faire, dans VS, ouvrez "Extensions" dans le menu principal, sous-menu "PVS-Studio", "Analyse après construction (fichiers modifiés uniquement)", "Activé". Ajoutez maintenant les lignes de code suivantes juste après la déclaration de la variable BaseFileName:
Supprimez ensuite les déclarations précédentes des variables OutputFileLocation et OutputFileItem ci-dessous.
Lors de la construction du projet UE, un fichier objet .obj est généré pour chaque fichier source .cpp. Cette analyse incrémentielle consiste à vérifier uniquement les fichiers source .cpp pour lesquels la date de création / modification de leur fichier objet est postérieure à celle du fichier de rapport .pvslog. Un fichier .pvslog distinct est généré pour chaque fichier source, à l'avenir, tous les fichiers .pvslog seront fusionnés dans un fichier .pvslog final). Une fois que vous avez apporté les modifications ci-dessus, créez UBT et copiez le fichier binaire nouvellement construit à l'emplacement de l'UBT d'origine.
Maintenant que tout est prêt, vous recevrez un journal de rapport lors de la construction de votre projet UE, contenant les résultats de l'analyseur uniquement pour les fichiers source compilés. Gardez à l'esprit qu'une telle modification de l'UBT n'a de sens que si vous avez modifié le fichier Build.bat de telle manière qu'il a effectué la suppression du fichier cache ActionHistory.bin (une description détaillée de ce scénario a été donnée ci-dessus). Pour désactiver le mode d'analyse incrémentielle, il suffit d'installer l'option "Analyse après construction (fichiers modifiés uniquement)" décrite ci-dessus dans le mode "Désactivé".
Permettez-moi de vous rappeler une fois de plus: si vous avez installé l'indicateur -StaticAnalyzer = PVSStudio dans le champ Build Command Line dans les paramètres du projet 'Properties | Configuration Properties | NMake', il doit être supprimé dans ce scénario.
Ouverture du fichier de rapport Analyzer et son chargement automatique dans Visual Studio
Par défaut lors de l'analyse du projet UE, un fichier de rapport ne sera pas affiché dans la fenêtre PVS-Studio dans VS. Il est juste stocké relativement au dossier du projet par le chemin suivant: \ YouProject \ Saved \ PVS-Studio \. Pour ouvrir ce fichier dans VS, vous devez utiliser la commande suivante: 'PVS-Studio | Ouvrir / Enregistrer | Ouvrir le rapport d'analyse' et sélectionner le type de fichier 'Sortie non analysée'. Vous pouvez également ouvrir le rapport de fichier dans le programme Surveillance du compilateur C et C ++, en utilisant la commande suivante: 'Fichier | Ouvrir le journal PVS-Studio' et également choisir le type de fichier 'Sortie non analysée'.
Il existe une autre option plus pratique pour ouvrir le journal du rapport d'analyse, qui est son chargement automatique dans VS. Pour qu'il se charge automatiquement dans la fenêtre PVS-Studio dans VS une fois l'analyse terminée, vous devez activer l'option appropriée: 'PVS-Studio | Options | Paramètres spécifiques de l'analyseur | Enregistrer / charger (rapport de l'analyseur) | AutoloadUnrealEngineLog' .
Téléchargez et essayez PVS-Studio
En tant qu'auteur de cet article, ainsi que l'une de ces personnes qui travaille directement sur la mise en œuvre et le support des fonctionnalités de PVS-Studio liées à l'analyse de projets, construites sur la base du moteur UE, je suis prêt à aider les lecteurs . Si vous rencontrez des problèmes pour utiliser PVS-Studio avec votre projet UE ou si vous avez des questions après avoir lu cet article, je serais heureux de discuter avec vous. Écrivez à notre support, je recevrai des mails sur UE et les problèmes associés. Merci de votre attention.
Liens supplémentaires
- Andrey Karpov. Un contrôle tant attendu du moteur Unreal 4 . (14 avril 2014)
- Paul Eremeev, Svyatoslav Razmyslov. Comment l'équipe PVS-Studio a amélioré le code d'Unreal Engine . (20 juin 2015)
- Andrey Karpov. Analyse statique dans le cadre du processus de développement dans Unreal Engine . (27 juin 2017)