Este artículo se centra en los detalles específicos de la verificación de proyectos de Unreal Engine con el analizador estático PVS-Studio en el sistema operativo Windows: cómo instalar el analizador, verificar un proyecto, dónde y cómo ver un informe de error.
Una parte integral de la serie de nuestros artículos son temas relacionados con la industria del juego. Compruebe un motor real utilizado en los juegos AAA: de nada, descubra los principales errores en la industria de los juegos;
continúe , encuentre errores en uno de los motores de juegos más populares Unreal Engine (UE), lo
suficientemente fácil . En el desarrollo de juegos, así como con cualquier otra aplicación, la calidad del código es importante. Los errores se detectan lo antes posible y la mejor opción es hacerlo automáticamente; aquí es donde los analizadores de código estático ayudan a los programadores.
En este artículo, trataré de hablar brevemente sobre cómo puede usar el analizador estático PVS-Studio para verificar proyectos creados en UE. PVS-Studio puede ayudarlo a mejorar el código de su proyecto al encontrar errores en él, lo que le permite reducir el tiempo que dedica a la revisión del código.
Tenga en cuenta que este artículo es una adición a la
documentación existente sobre el análisis de proyectos de UE y no sirve para reemplazarlo, tomando prestados en gran medida el contenido de la documentación.
Instalación PVS-Studio
La forma más fácil de instalar el analizador PVS-Studio es descargar su
archivo de instalación . Para poder analizar proyectos creados en UE, debe seleccionar los siguientes componentes al instalar PVS-Studio: "Monitoreo del compilador C y C ++" e "Integración con Microsoft Visual Studio (Visual C ++ / C #)". El último punto es responsable de integrar el complemento PVS-Studio en el IDE de Visual Studio, a través del cual es conveniente trabajar con el registro de errores y con la configuración general del analizador.
Para trabajar completamente con PVS-Studio, debe ingresar una licencia. Puede hacerlo abriendo el IDE de Visual Studio (VS) e ingresando la licencia en 'PVS-Studio | Opciones ... | Registro'. En VS 2019, el menú PVS-Studio se ha movido al menú 'Extensiones', la ruta a la ventana de entrada de licencia se ve así: 'Extensiones' | 'PVS-Studio | Opciones ... | Registro'. La licencia está disponible en nuestro
sitio web .
Para construir proyectos UE, se usa un programa personalizado UnrealBuildTool (UBT) de Epic Games, no un sistema de construcción estándar, usado en VS (MSBuild). En este sentido, el complemento PVS-Studio no puede implementar un escenario habitual de verificación de proyectos C ++ / C #, creado en VS: "PVS-Studio -> Verificar -> Proyecto actual". Hay varias soluciones para evitar esta limitación.
Realizar análisis con sistema de monitoreo de compilación
La primera y la forma más fácil de verificar un proyecto de UE es usar el programa C y C ++ Compiler Monitoring (llamado Standalone.exe), ubicado en el directorio de instalación de PVS-Studio. El principio de su trabajo es que supervisa los procesos del compilador que corresponden al compilador de destino (en este caso, cl.exe) y recopila toda la información necesaria para el preprocesamiento y el análisis posterior de los archivos fuente. Una vez que haya abierto la supervisión del compilador C y C ++, use el menú "Herramientas" y elija la opción "Analizar sus archivos (C y C ++) ...". Presione "Iniciar monitoreo" y verá la ventana en la esquina inferior izquierda que le indica que el monitoreo de llamadas del compilador está en proceso:
A continuación, cree su proyecto de UE y presione "Detener supervisión".
Después de eso, comenzará el análisis de los archivos fuente compilados. El informe de las advertencias encontradas se mostrará en la ventana "Salida del analizador" del programa C y C ++ Compiler Monitoring.
Se puede realizar un monitoreo similar de las llamadas del compilador y el posterior análisis de los archivos detectados utilizando el programa de consola CLMonitor.exe, ubicado en la misma carpeta, donde se instaló PVS-Studio. CLMonitor.exe tiene dos modos operativos: un modo de servidor cuando se monitorean los lanzamientos de procesos (correspondientes al compilador de destino) y un modo de cliente (cuando se analizan los archivos fuente, detectados en la etapa de monitoreo, seguido de un informe de los resultados del análisis) . Para ejecutar CLMonitor.exe en modo servidor, ejecute el siguiente comando:
CLMonitor.exe monitor
Después de eso, construya su proyecto UE y ejecute el siguiente comando:
CLMonitor.exe analyze -l "c:\ptest.plog"
El comando "analizar" ejecuta CLMonitor.exe en modo cliente y cierra la instancia en ejecución de este programa, trabajando en modo servidor. Después de ejecutar este comando, CLMonitor.exe comenzará a ejecutar el análisis de archivos. Un parámetro para la opción "- l" es una ruta al archivo, en el que se escribirán los resultados del analizador.
Realizar análisis con la clave -StaticAnalyzer = PVSStudio
Un enfoque diferente y más conveniente para analizar proyectos de UE es una integración directa con el sistema UBT. Para hacer esto, abra la ventana de propiedades de su proyecto UE en VS y elija "NMake" en la lista "Propiedades de configuración". Agregue -StaticAnalyzer = PVSStudio en el campo de texto de la propiedad "Build Command Line". Como ejemplo, el valor del campo "Generar línea de comando" podría tener el siguiente aspecto:
C:\Program Files\Epic Games\UE_4.22\Engine\Build\BatchFiles\Build.bat" MyProject Win64 DebugGame -Project="$(SolutionDir)$(ProjectName).uproject" -WaitMutex -FromMsBuild -StaticAnalyzer=PVSStudio
Debe tenerse en cuenta que al realizar una compilación del proyecto, solo se analizará, no se compilará. El escenario en el que se construye y analiza un proyecto se describirá a continuación. También debe tenerse en cuenta que solo se analizarán los archivos de origen que se han modificado desde la última compilación del proyecto. El cambio de cualquier archivo .h incluido no es una razón para realizar el análisis durante la próxima compilación. Para realizar un análisis completo, debe agregar el mismo indicador en el campo de texto de la propiedad "Reconstruir toda la línea de comandos". Ahora, al reconstruir el proyecto, obtendrá el resultado de analizar todo el proyecto.
Realizar el análisis mediante la modificación de archivos de paquete
Ahora consideremos otro escenario del analizador PVS-Studio que se integra en el sistema de compilación UBT. Mientras lo hace, el análisis comienza justo después de realizar una compilación / reconstrucción del proyecto. En otras palabras, obtienes un proyecto construido y un archivo con resultados de análisis. Es posible que haya notado que el campo Build Command Line contiene la ruta al archivo por lotes Build.bat, que, a su vez, contiene instrucciones para ejecutar UBT con los argumentos necesarios. Build.bat se ejecuta al comienzo de la compilación.
El punto es cambiar el archivo por lotes para que primero pueda ejecutar UBT con argumentos de compilación estándar y luego, si una compilación se completa con éxito, ejecute el mismo UBT, pero ya con un indicador adicional -StaticAnalyzer = PVSStudio. Para implementar el escenario anterior, puede cambiar el archivo por lotes Build.bat. Es incluso mejor crear su copia llamada, por ejemplo, BuildAndAnalyze.bat. Esto es lo que debe hacer para implementar el escenario descrito. Justo después del comando popd, inserte las siguientes instrucciones:
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 la bandera -StaticAnalyzer = PVSStudio se instaló previamente en el campo Generar línea de comandos en la configuración del proyecto 'Propiedades | Propiedades de configuración | NMake', debe eliminarse.
El problema con este enfoque es que solo se analizarán los archivos que se compilaron durante la compilación. Es decir, no recibirá un archivo de informe con una verificación completa de su proyecto. Además, los cambios realizados en los archivos .h incluidos tampoco se tendrán en cuenta. Por lo tanto, no podemos llamar a este análisis incremental, ya que los cambios en los archivos de encabezado no activarán el análisis durante la próxima compilación. En este caso, puede reconstruir el proyecto, obteniendo el resultado del análisis de todo el proyecto. Sin embargo, la compilación completa puede llevar mucho tiempo, por lo que puede seguir este escenario: haga una compilación, elimine el archivo de caché ActionHistory.bin, ejecute la compilación con el indicador -StaticAnalyzer = PVSStudio, restaure el archivo de caché. El archivo ActionHistory.bin contiene información necesaria para realizar una compilación incremental, así como el historial de ejecución del analizador para archivos verificados.
A primera vista, este escenario puede no parecer el más fácil, por lo que le proporcionaremos un conjunto completo de instrucciones sobre cómo puede cambiar el archivo Build.bat original. Vale la pena señalar que dichos cambios solo son relevantes para Unreal Engine versión 4.21 y posteriores. Después del comando setlocal enabledelayedexpansion, declare las siguientes variables:
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%"
Justo después de la instrucción popd, inserte estos comandos:
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% ) )
Tenga en cuenta que las variables PROJECT_NAME, PLATFORM y UPROJECT_FILE, necesarias para la determinación correcta de la ruta al archivo de caché, obtienen sus valores de los argumentos de la línea de comandos de Build.bat. Si tiene un orden diferente de estos argumentos, debe cambiar adecuadamente la inicialización de las tres variables, descritas anteriormente.
Análisis incremental del proyecto a través de la modificación UBT
PVS-Studio puede trabajar en el modo de análisis incremental. El análisis incremental está destinado a verificar solo aquellos archivos que se han cambiado desde la última compilación. En el modo de análisis incremental, PVS-Studio se ejecuta automáticamente en la computadora de un desarrollador en el modo de fondo justo después de la compilación del código y analiza todos los archivos modificados. Puede encontrar una guía más detallada sobre el uso de PVS-Studio en el modo de análisis incremental en nuestra
documentación .
Con la implementación del modo de análisis incremental para proyectos de UE, todo vuelve a ser un poco más complicado que en un escenario estándar. En este caso, para poder realizar el análisis incremental (teniendo en cuenta los cambios en los archivos .h incluidos), deberá introducir las modificaciones en el sistema UBT de compilación usted mismo. Para hacer esto,
obtenga acceso al repositorio de UE en github.com y clónelo en su máquina. Para personalizar aún más el repositorio clonado, deberá completar los pasos que se enumeran en la sección "Puesta en marcha", subsección "Windows". Puede encontrar esta sección en la página principal del repositorio oficial de UE. Una vez que haya configurado su repositorio, puede comenzar a hacer cambios en UBT. Para hacer esto, siga esta ruta al repositorio clonado: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Abra la solución UnrealBuildTool.sln y busque el archivo PVSToolChain.cs en el Explorador de soluciones. En este archivo, agregue las siguientes líneas de código en la clase PVSApplicationSettings:
Esta línea de código permite deserializar la opción de Análisis incremental de los archivos de configuración de PVS-Studio. No olvide habilitar el modo de análisis incremental PVS-Studio. Para hacer esto, en VS abra "Extensiones" en el menú principal, submenú "PVS-Studio", "Análisis después de la compilación (solo archivos modificados)", "Habilitado". Ahora agregue las siguientes líneas de código justo después de la declaración de la variable BaseFileName:
Luego, elimine las declaraciones anteriores de las variables OutputFileLocation y OutputFileItem a continuación.
Al crear el proyecto UE, se genera un archivo .obj de objeto para cada archivo .cpp de origen. Este análisis incremental se trata de verificar solo aquellos archivos .cpp de origen para los cuales la fecha de creación / modificación de su archivo objeto es posterior a la del archivo de informe .pvslog. Se genera un archivo .pvslog separado para cada archivo fuente, en el futuro todos los archivos .pvslog se fusionarán en un .pvslog final). Una vez que haya realizado los cambios anteriores, cree UBT y copie el archivo binario recién creado en la ubicación del UBT original.
Ahora está todo listo, recibirá un registro de informe cuando realice la compilación de su proyecto UE, que contenga los resultados del analizador solo para los archivos fuente compilados. Tenga en cuenta que dicha modificación de UBT tiene sentido solo si ha modificado el archivo Build.bat de tal manera que realizó la eliminación del archivo de caché ActionHistory.bin (la descripción detallada de este escenario se proporcionó anteriormente). Para deshabilitar el modo de análisis incremental, simplemente instale la opción "Análisis después de la compilación (solo archivos modificados)" descrita anteriormente en el modo "Deshabilitado".
Permítame recordarle una vez más: si instaló el indicador -StaticAnalyzer = PVSStudio en el campo Generar línea de comando en la configuración del proyecto 'Propiedades | Propiedades de configuración | NMake', debe eliminarse en este escenario.
Abrir el archivo de informe del analizador y su carga automática en Visual Studio
Por defecto, al realizar el análisis del proyecto UE, no se mostrará un archivo de informe en la ventana PVS-Studio en VS. Simplemente se almacena en la carpeta del proyecto mediante la siguiente ruta: \ YouProject \ Saved \ PVS-Studio \. Para abrir este archivo en VS, debe utilizar el siguiente comando: 'PVS-Studio | Abrir / Guardar | Abrir informe de análisis' y seleccionar el tipo de archivo 'Salida no analizada'. También puede abrir el informe de archivo en el programa C y C ++ Compiler Monitoring, utilizando el siguiente comando: 'Archivo | Abrir PVS-Studio Log' y también elegir el tipo de archivo 'Salida no analizada'.
Hay otra opción más conveniente para abrir el registro del informe de análisis, que es su carga automática en VS. Para que se cargue automáticamente en la ventana PVS-Studio en VS después de que se complete el análisis, debe habilitar la opción adecuada: 'PVS-Studio | Opciones | Configuración específica del analizador | Guardar / Cargar (informe del analizador) | AutoloadUnrealEngineLog' .
Descargar y probar PVS-Studio
Como autor de este artículo, y como una de esas personas que está trabajando directamente en la implementación y el soporte de la funcionalidad de PVS-Studio relacionada con el análisis de proyectos, construida sobre la base del motor UE, estoy listo para ayudar a los lectores . Si tiene problemas para usar PVS-Studio con su proyecto UE o tiene alguna pregunta después de leer este artículo, me complacerá conversar con usted. Escriba a nuestro soporte, recibiré correos electrónicos sobre UE y problemas relacionados. Gracias por su atencion
Enlaces Adicionales
- Andrey Karpov. Una comprobación muy esperada de Unreal Engine 4 . (14 de abril de 2014)
- Paul Eremeev, Svyatoslav Razmyslov. Cómo el equipo de PVS-Studio mejoró el código de Unreal Engine . (20 de junio de 2015)
- Andrey Karpov. Análisis estático como parte del proceso de desarrollo en Unreal Engine . (27 de junio de 2017)