Cet article est consacré aux fonctionnalités de vérification des projets Unreal Engine à l'aide de l'analyseur statique PVS-Studio sur le système d'exploitation Windows: comment installer l'analyseur, comment vérifier le projet, où et comment afficher le rapport d'erreur.
Une partie intégrante du cycle de nos articles sont des sujets d'une manière ou d'une autre liés à l'industrie du jeu. Vérifier le moteur physique utilisé dans les jeux AAA - faites les meilleures erreurs dans l'industrie du jeu -
pour votre santé , trouver des bugs dans l'un des moteurs de jeux les plus populaires - Unreal Engine (UE) - est
facile . Lors du développement de jeux, ainsi que lors de l'écriture d'autres applications, la qualité du code est importante. Les erreurs sont mieux détectées le plus tôt possible et il est conseillé 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 analyser les projets créés dans l'UE. PVS-Studio vous aidera à améliorer le code de vos projets en y trouvant des erreurs, vous permettant ainsi de réduire le temps consacré à la révision du code.
Veuillez noter que cet article s'ajoute à la
documentation existante sur l'analyse des projets UE et ne sert pas à le remplacer, empruntant largement le contenu de la documentation.
Installer 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 l'UE, lors de l'installation de PVS-Studio, vous devez sélectionner les composants suivants: «Surveillance du compilateur C et C ++» et «Intégration avec Microsoft Visual Studio (Visual C ++ / C #)». Le dernier élément est responsable de l'intégration du plug-in PVS-Studio dans l'IDE 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 travailler pleinement avec PVS-Studio, vous devez entrer une licence. Cela peut être fait en ouvrant Visual Studio IDE (VS) et en entrant la licence dans la fenêtre 'PVS-Studio | Options ... | Enregistrement'. Dans VS 2019, le menu PVS-Studio a été supprimé dans le menu 'Extensions', donc le chemin d'accès à la fenêtre d'entrée de licence ressemblera à ceci: 'Extensions' | 'PVS-Studio | Options ... | Enregistrement'. La licence peut être obtenue sur notre
site Web .
Pour construire des projets UE, ce n'est pas le système d'assemblage standard utilisé dans VS-MSBuild qui est utilisé, mais le propre programme d'Epic Games responsable de l'assemblage - UnrealBuildTool (UBT). À cet égard, le plugin PVS-Studio n'est pas en mesure d'implémenter le script habituel pour vérifier les projets C ++ / C # créés dans VS: «PVS-Studio -> Vérifier -> Projet actuel». Il existe plusieurs solutions pour contourner cette limitation.
Effectuer une analyse à l'aide d'un système de surveillance de compilation
La première et la plus simple façon de vérifier l'UE du projet peut être effectuée à l'aide du programme de surveillance du compilateur C et C ++ (appelé Standalone.exe), qui se trouve dans le répertoire d'installation de PVS-Studio. Le principe de son travail est de surveiller les lancements de processus correspondant au compilateur cible (cl.exe dans ce cas) et de collecter toutes les informations nécessaires au prétraitement et à l'analyse approfondie des fichiers sources. Après avoir ouvert la surveillance du compilateur C et C ++, utilisez le menu "Outils" et sélectionnez l'option "Analyser vos fichiers (C et C ++) ...". Appuyez sur le bouton "Démarrer la surveillance" et vous verrez une fenêtre apparaître dans le coin inférieur gauche de l'écran informant que les appels du compilateur sont surveillés:
Ensuite, construisez votre projet UE et appuyez sur la touche «Stop Monitoring».
Après cela, l'analyse des fichiers source qui ont été compilés commencera. Un rapport des avertissements trouvés sera affiché dans la fenêtre Sortie de l'analyseur du programme de surveillance du compilateur C et C ++.
Un suivi similaire des appels du compilateur et une analyse ultérieure des fichiers reçus peuvent être effectués à 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: le mode serveur (lorsque le suivi démarre des processus correspondant au compilateur cible) et le mode client (lors de l'analyse des fichiers source reçus à l'étape de suivi et de la génération d'un rapport sur les résultats de l'analyse). Pour 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» lance CLMonitor.exe en mode client et ferme l'instance en cours d'exécution de ce programme fonctionnant en mode serveur. Après avoir exécuté cette commande, CLMonitor.exe commencera à analyser les fichiers. Le paramètre de l'option "-l" est le chemin d'accès au fichier dans lequel les résultats de l'analyseur seront écrits.
Exécution d'une analyse à l'aide de la clé -StaticAnalyzer = PVSStudio
Une approche alternative et plus pratique pour l'analyse des projets UE est l'intégration directe avec le système d'assemblage UBT. Pour ce faire, dans VS, ouvrez la fenêtre des propriétés de votre projet UE et sélectionnez «NMake» dans la liste «Propriétés de configuration». Ajoutez l'indicateur -StaticAnalyzer = PVSStudio à la zone 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 noter qu'à présent, lors de l'assemblage du projet, seule l'analyse sera effectuée, mais l'assemblage lui-même ne sera pas effectué. Un scénario dans lequel l'assemblage et l'analyse ultérieure sont effectués sera décrit ci-dessous. Il est également nécessaire de comprendre que seuls les fichiers source seront analysés qui ont été modifiés depuis la dernière génération du projet (si un fichier .h du plug-in a été modifié, ce ne sera pas la raison de l'analyse lors de la prochaine génération). Pour effectuer une analyse complète, vous devez ajouter le même indicateur au champ de texte de la propriété «Reconstruire toutes les lignes de commande». Maintenant, lorsque vous reconstruisez le projet, vous obtiendrez le résultat de l'analyse de l'ensemble du projet.
Script d'analyse en modifiant les fichiers batch
Examinons maintenant un autre scénario d'intégration de l'analyseur PVS-Studio dans le système d'assemblage UBT, dans lequel l'analyse démarre immédiatement après la construction / le réassemblage du projet, c'est-à-dire qu'à la sortie, vous obtenez à la fois le projet assemblé et le fichier de résultats d'analyse. Comme vous l'avez peut-être remarqué, le champ Build Command Line contient le chemin d'accès au fichier de commandes Build.bat, qui à son tour contient des instructions pour démarrer UBT avec les arguments nécessaires. Build.bat démarre au tout début de la génération.
L'idée est de modifier le fichier batch afin qu'il démarre d'abord UBT avec les arguments de génération standard, et si la phase de génération est terminée avec succès, réexécutez le même UBT, mais avec l'indicateur supplémentaire -StaticAnalyzer = PVSStudio. Pour implémenter le scénario ci-dessus, vous pouvez modifier le fichier de commandes Build.bat (et il est préférable de créer une copie avec le nom, par exemple, BuildAndAnalyze.bat) comme suit. Immédiatement 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 défini dans le champ Générer la ligne de commande dans les paramètres du projet «Propriétés | Propriétés de configuration | NMake», il doit être supprimé.
Le problème avec cette approche est que seuls les fichiers qui ont été compilés pendant la phase de construction seront analysés. Autrement dit, vous ne recevrez pas de fichier de rapport avec une vérification complète de votre projet. De plus, aucune modification apportée aux fichiers d'en-tête .h inclus ne sera également prise en compte. Par conséquent, nous ne pouvons pas appeler une telle analyse incrémentielle, car les modifications dans les fichiers d'en-tête n'entraîneront pas l'analyse lors d'un nouvel assemblage. Dans ce cas, vous pouvez reconstruire le projet en obtenant un résultat d'analyse pour l'ensemble du projet. Cependant, cela peut prendre un certain temps pour terminer l'assembly, vous pouvez donc suivre le scénario suivant: créer, supprimer le fichier cache - ActionHistory.bin, démarrer l'assembly avec l'indicateur -StaticAnalyzer = PVSStudio et restaurer le fichier cache. Le fichier ActionHistory.bin contient les informations nécessaires pour effectuer des assemblages incrémentiels, ainsi que l'historique de démarrage de l'analyseur pour les fichiers analysés.
À première vue, ce scénario peut ne pas sembler être 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 s'appliquent qu'à Unreal Engine version 4.21 et supérieure. 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%"
Immédiatement 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 ligne de commande Build.bat. Si vous avez un ordre différent de ces arguments, vous devez modifier en conséquence l'initialisation des trois variables décrites ci-dessus.
Analyse incrémentale du projet par modification de l'UBT
PVS-Studio peut fonctionner en mode d'analyse incrémentielle. L'analyse incrémentielle est destinée à vérifier uniquement les fichiers source qui ont été modifiés depuis la dernière génération du projet. En mode d'analyse incrémentielle, PVS-Studio démarre automatiquement en arrière-plan sur la machine du développeur immédiatement après la compilation du code et analyse tous les fichiers affectés par les modifications. 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émentielle pour les projets UE, tout est encore un peu plus compliqué qu'avec le scénario de travail standard. Dans ce cas, afin de pouvoir effectuer une analyse incrémentielle (en tenant compte des changements dans les fichiers .h connectés), vous devrez apporter vous-même des modifications au système d'assemblage UBT. Pour ce faire,
accédez au référentiel UE sur github.com et clonez-le sur votre machine. Pour configurer davantage le référentiel cloné, vous devez suivre les étapes répertoriées dans la section «Mise en route et exécution» de la sous-section «Windows». Vous pouvez trouver la section mentionnée sur la page principale du référentiel UE officiel. Une fois que vous avez configuré votre référentiel, vous pouvez commencer à apporter des modifications à UBT. Pour ce faire, accédez au chemin suivant dans le référentiel cloné: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Ouvrez la solution UnrealBuildTool.sln et dans la fenêtre Explorateur de solutions, recherchez le fichier PVSToolChain.cs. Dans ce fichier, ajoutez les lignes de code suivantes à la classe PVSApplicationSettings:
Cette ligne de code permet de désérialiser l'option IncrementalAnalysis du fichier de paramètres PVS-Studio. N'oubliez pas d'activer le mode d'analyse incrémentielle PVS-Studio lui-même. Pour ce faire, ouvrez l'élément de menu principal Extensions dans VS, le sous-menu PVS-Studio, Analyse après construction (fichiers modifiés uniquement), Activé. Ajoutez maintenant les lignes de code suivantes immédiatement après avoir déclaré la variable BaseFileName:
Après cela, supprimez les déclarations de variable précédentes OutputFileLocation et OutputFileItem ci-dessous dans le code.
Pendant le processus d'assemblage du projet UE, un fichier objet .obj est généré pour chaque fichier source .cpp. L'idée de cette analyse incrémentielle est de vérifier uniquement les fichiers source .cpp pour lesquels la date de création / modification de leur fichier objet est plus récente que celle du fichier de rapport .pvslog (pour chaque fichier source son propre fichier .pvslog est généré, puis tout Les fichiers .pvslog seront combinés en un seul .pvslog final). Après avoir apporté les modifications ci-dessus, compilez l'UBT et copiez le binaire nouvellement collecté à l'emplacement de l'UBT d'origine.
Tout est prêt, maintenant lorsque vous générez le projet UE, vous recevrez un journal de rapport contenant les résultats de l'analyseur uniquement pour les fichiers source qui ont été compilés. N'oubliez pas qu'une telle modification UBT n'a de sens que si vous avez modifié le fichier Build.bat afin qu'il supprime le fichier cache ActionHistory.bin (une description détaillée de ce scénario a été décrite ci-dessus). Pour désactiver le mode d'analyse incrémentielle, définissez simplement l'option «Analyse après génération (fichiers modifiés uniquement)» décrite ci-dessus sur «Désactivée».
Permettez-moi de vous rappeler une fois de plus: si vous définissez l'indicateur -StaticAnalyzer = PVSStudio dans le champ Build Command Line dans les paramètres du projet 'Properties | Configuration Properties | NMake', vous devez le supprimer dans ce scénario.
Ouverture du fichier de rapport de l'analyseur et son chargement automatique dans Visual Studio
Par défaut, lors de l'analyse d'un UE de projet, le fichier de rapport n'est pas chargé dans la fenêtre PVS-Studio dans VS. Il est simplement enregistré par rapport au dossier du projet dans 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 définir l'option 'Sortie non analysée' dans l'option de sélection du type de fichier. Vous pouvez également ouvrir le fichier de rapport dans le programme de surveillance du compilateur C et C ++ à l'aide de cette commande: 'Fichier | Ouvrir le journal PVS-Studio' et également sélectionner le type de fichier 'Sortie non analysée'.
Il existe une option plus pratique pour ouvrir le journal d'analyse - il est automatiquement chargé dans VS. Pour le charger automatiquement dans la fenêtre PVS-Studio dans VS une fois l'analyse terminée, vous devez activer l'option correspondante: 'PVS-Studio | Options | Paramètres spécifiques de l'analyseur | Enregistrer / charger (rapport de l'analyseur) | AutoloadUnrealEngineLog'.
Téléchargez et essayez l'analyseur PVS-Studio
En tant qu'auteur de cet article et en tant que personne travaillant directement sur la mise en œuvre et le support de la fonctionnalité PVS-Studio liée à l'analyse de projets construits sur la base du moteur UE, je suis prêt à aider les lecteurs. Si vous avez des difficultés à utiliser PVS-Studio avec votre projet UE ou si vous avez des questions auxquelles vous n'avez pas trouvé de réponse dans cet article, je serai heureux de vous parler. Écrivez-nous en
soutien et des lettres me seront remises concernant l'UE et les questions connexes. Merci de votre attention.
Liens annexes
- Andrey Karpov. Le contrôle tant attendu d'Unreal Engine 4 . (14 avril 2014)
- Pavel Eremeev, Sviatoslav Razmyslov. Comment l'équipe PVS-Studio a amélioré le code Unreal Engine . (20 juin 2015)
- Andrey Karpov. Analyse statique dans le cadre du processus de développement d'Unreal Engine . (27 juin 2017)
Si vous souhaitez partager cet article avec un public anglophone, veuillez utiliser le lien vers la traduction: Ilya Gainulin.
Utilisation de PVS-Studio lors de la vérification de projets Unreal Engine sur le système d'exploitation Windows .