Este artículo está dedicado a las características de verificar proyectos de Unreal Engine utilizando el analizador estático PVS-Studio en el sistema operativo Windows: cómo instalar el analizador, cómo verificar el proyecto, dónde y cómo ver el informe de errores.
Una parte integral del ciclo de nuestros artículos son temas relacionados de una forma u otra con la industria del juego. Verificar el motor físico utilizado en los juegos AAA
, comete los errores más importantes en la industria de los juegos,
para su salud , encontrar errores en uno de los motores de juegos más populares, Unreal Engine (UE), es
fácil . Al desarrollar juegos, así como al escribir cualquier otra aplicación, la calidad del código es importante. Los errores se detectan lo antes posible y es aconsejable hacerlo automáticamente: aquí es donde los analizadores de código estático ayudan a los programadores.
En este artículo intentaré hablar brevemente sobre cómo puede usar el analizador estático PVS-Studio para analizar proyectos creados en la UE. PVS-Studio ayudará a mejorar el código de sus proyectos al encontrar errores en él, lo que le permitirá reducir el tiempo dedicado a la revisión del código.
Tenga en cuenta que este artículo es adicional 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.
Instalar 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 el UE, al instalar PVS-Studio debe seleccionar los siguientes componentes: "Monitoreo del compilador C y C ++" e "Integración con Microsoft Visual Studio (Visual C ++ / C #)". El último elemento 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. Esto se puede hacer abriendo el Visual Studio IDE (VS) e ingresando la licencia en la ventana 'PVS-Studio | Opciones ... | Registro'. En VS 2019, el menú PVS-Studio se eliminó en el menú 'Extensiones', por lo que la ruta a la ventana de entrada de licencia se verá así: 'Extensiones' | 'PVS-Studio | Opciones ... | Registro'. La licencia se puede obtener en nuestro
sitio web .
Para construir proyectos de UE, no se usa el sistema de ensamblaje estándar utilizado en VS - MSBuild, sino el propio programa de Epic Games responsable del ensamblaje: UnrealBuildTool (UBT). En este sentido, el complemento PVS-Studio no puede implementar el script habitual para verificar proyectos C ++ / C # creados en VS: “PVS-Studio -> Verificar -> Proyecto actual”. Hay varias soluciones para solucionar esta limitación.
Realizar análisis usando un sistema de monitoreo de compilación
La primera y más fácil manera de verificar el proyecto UE se puede hacer utilizando el programa de Monitoreo del compilador C y C ++ (llamado Standalone.exe), que se encuentra en el directorio de instalación de PVS-Studio. El principio de su trabajo es que monitorea los lanzamientos de procesos correspondientes al compilador de destino (cl.exe en este caso) y recopila toda la información necesaria para el preprocesamiento y el análisis posterior de los archivos fuente. Después de abrir Monitoreo del compilador de C y C ++, use el menú "Herramientas" y seleccione la opción "Analizar sus archivos (C y C ++) ...". Presione el botón "Iniciar monitoreo" y verá que aparece una ventana en la esquina inferior izquierda de la pantalla que informa que las llamadas del compilador están siendo monitoreadas:
A continuación, cree su proyecto de UE y presione la tecla "Detener monitoreo".
Después de eso, comenzará el análisis de los archivos fuente que se han compilado. Se mostrará un informe de las advertencias encontradas en la ventana Salida del analizador del programa de Monitoreo del compilador C y C ++.
Se puede realizar un seguimiento similar de las llamadas del compilador y el posterior análisis de los archivos recibidos utilizando el programa de consola CLMonitor.exe ubicado en la misma carpeta donde se instaló PVS-Studio. CLMonitor.exe tiene dos modos operativos: modo servidor (cuando se inicia el seguimiento de los procesos correspondientes al compilador de destino) y modo cliente (cuando se analizan los archivos fuente recibidos en la etapa de seguimiento y se genera un informe sobre 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" inicia CLMonitor.exe en modo cliente y cierra la instancia en ejecución de este programa que funciona en modo servidor. Después de ejecutar este comando, CLMonitor.exe comenzará a analizar los archivos. El parámetro para la opción "- l" es la ruta al archivo en el que se escribirán los resultados del analizador.
Realización de análisis utilizando la clave -StaticAnalyzer = PVSStudio
Un enfoque alternativo y más conveniente para el análisis de proyectos de UE es la integración directa con el sistema de ensamblaje UBT. Para hacer esto, en VS, abra la ventana de propiedades de su proyecto UE y seleccione "NMake" en la lista "Propiedades de configuración". Agregue el distintivo -StaticAnalyzer = PVSStudio al cuadro de texto de la propiedad Generar línea de comandos. Como ejemplo, el valor del campo "Crear línea de comando" puede verse así:
C:\Program Files\Epic Games\UE_4.22\Engine\Build\BatchFiles\Build.bat" MyProject Win64 DebugGame -Project="$(SolutionDir)$(ProjectName).uproject" -WaitMutex -FromMsBuild -StaticAnalyzer=PVSStudio
Vale la pena considerar que ahora al realizar el ensamblaje del proyecto, solo se realizará un análisis, pero el ensamblaje en sí no se llevará a cabo. A continuación se describirá un escenario en el que se realizan tanto el ensamblaje como el análisis posterior. También es necesario comprender que solo se analizaron los archivos de origen que se han modificado desde la última compilación del proyecto (si se ha cambiado algún archivo .h de complemento, este no será el motivo del análisis durante la próxima compilación). Para realizar un análisis completo, debe agregar el mismo indicador al campo de texto de la propiedad "Reconstruir todas las líneas de comando". Ahora, cuando reconstruya el proyecto, obtendrá el resultado del análisis de todo el proyecto.
Script de análisis mediante la modificación de archivos por lotes
Ahora veamos otro escenario para integrar el analizador PVS-Studio en el sistema de ensamblaje UBT, en el que el análisis comienza inmediatamente después de que el proyecto se construye / se vuelve a ensamblar, es decir, en la salida se obtiene tanto el proyecto ensamblado como el archivo de resultados del análisis. Como habrá notado, el campo Generar línea de comandos contiene la ruta al archivo por lotes Build.bat, que a su vez contiene instrucciones para iniciar UBT con los argumentos necesarios. Build.bat comienza al comienzo de la construcción.
La idea es cambiar el archivo por lotes para que primero inicie UBT con argumentos de compilación estándar, y si la fase de compilación se completa con éxito, ejecute el mismo UBT nuevamente, pero con el indicador adicional -StaticAnalyzer = PVSStudio. Para implementar el escenario anterior, puede modificar el archivo por lotes Build.bat (y es mejor crear una copia con el nombre, por ejemplo, BuildAndAnalyze.bat) de la siguiente manera. Inmediatamente 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 el indicador -StaticAnalyzer = PVSStudio se configuró previamente en el campo Generar línea de comandos en la configuración del proyecto 'Propiedades | Propiedades de configuración | NMake', entonces debe eliminarse.
El problema con este enfoque es que solo se analizarán los archivos que se compilaron durante la fase de construcció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 de encabezado .h incluidos tampoco se tendrán en cuenta. Por lo tanto, no podemos llamar a dicho análisis incremental, ya que los cambios en los archivos de encabezado no conducirán a que el análisis se realice durante un nuevo ensamblaje. En este caso, puede reconstruir el proyecto, obteniendo un resultado de análisis para todo el proyecto. Sin embargo, puede llevar mucho tiempo completar el ensamblado, por lo que puede seguir el siguiente escenario: compilar, eliminar el archivo de caché - ActionHistory.bin, iniciar el ensamblaje con el indicador -StaticAnalyzer = PVSStudio y restaurar el archivo de caché. El archivo ActionHistory.bin contiene la información necesaria para realizar ensamblajes incrementales, así como el historial de inicio del analizador para los archivos escaneados.
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 modificar el archivo Build.bat original. Vale la pena señalar que tales cambios son relevantes solo para Unreal Engine versión 4.21 y superior. 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%"
Inmediatamente 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 determinar correctamente 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, entonces debe cambiar la inicialización de las tres variables descritas anteriormente.
Análisis incremental del proyecto a través de la modificación de UBT
PVS-Studio puede funcionar en modo de análisis incremental. El análisis incremental está destinado a verificar solo aquellos archivos fuente que han sido modificados desde la última compilación del proyecto. En el modo de análisis incremental, PVS-Studio se inicia automáticamente en segundo plano en la máquina del desarrollador inmediatamente después de compilar el código y analiza todos los archivos afectados por las modificaciones. Puede encontrar una guía más detallada sobre el uso de PVS-Studio en 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 con el escenario de trabajo estándar. En este caso, para poder realizar un análisis incremental (teniendo en cuenta los cambios en los archivos .h conectados), deberá realizar los cambios en el sistema de ensamblaje UBT usted mismo. Para hacer esto,
acceda al repositorio de UE en github.com y clónelo en su máquina. Para configurar aún más el repositorio clonado, debe seguir los pasos enumerados en la sección "Puesta en marcha" de la subsección "Windows". Puede encontrar la sección mencionada en la página principal del repositorio oficial de UE. Una vez que haya configurado su repositorio, puede comenzar a realizar cambios en UBT. Para hacer esto, vaya a la siguiente ruta en el repositorio clonado: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Abra la solución UnrealBuildTool.sln y en la ventana del Explorador de soluciones busque el archivo PVSToolChain.cs. En este archivo, agregue las siguientes líneas de código a la clase PVSApplicationSettings:
Esta línea de código permite deserializar la opción de Análisis incremental del archivo de configuración de PVS-Studio. No olvide habilitar el modo de análisis incremental PVS-Studio. Para hacer esto, abra el elemento del menú principal Extensiones en VS, el submenú PVS-Studio, Análisis después de la compilación (solo archivos modificados), habilitado. Ahora agregue las siguientes líneas de código inmediatamente después de declarar la variable BaseFileName:
Después de eso, elimine las declaraciones de variables anteriores OutputFileLocation y OutputFileItem a continuación en el código.
Durante el proceso de ensamblaje del proyecto UE, se genera un archivo de objeto .obj para cada archivo fuente .cpp. La idea de este análisis incremental es verificar solo aquellos archivos .cpp de origen para los cuales la fecha de creación / modificación de su archivo objeto es más nueva que la del archivo de informe .pvslog (para cada archivo fuente se genera su propio archivo .pvslog, luego todo Los archivos .pvslog se combinarán en un .pvslog final). Después de haber realizado los cambios anteriores, compile el UBT y copie el binario recién recopilado en la ubicación del UBT original.
Todo está listo, ahora cuando complete el ensamblaje del proyecto UE, recibirá un registro de informe que contiene los resultados del analizador solo para los archivos fuente que se han compilado. Recuerde que dicha modificación de UBT solo tiene sentido si modificó el archivo Build.bat para que elimine el archivo de caché ActionHistory.bin (una descripción detallada de este escenario se describió anteriormente). Para deshabilitar el modo de análisis incremental, simplemente configure la opción "Análisis después de la compilación (solo archivos modificados)" descrita anteriormente como "Deshabilitado".
Permítame recordarle una vez más: si establece el indicador -StaticAnalyzer = PVSStudio en el campo Generar línea de comandos en la configuración del proyecto 'Propiedades | Propiedades de configuración | NMake', entonces debe eliminarlo en este escenario.
Abrir el archivo de informe del analizador y su carga automática en Visual Studio
Por defecto, al analizar un proyecto UE, el archivo de informe no se carga en la ventana PVS-Studio en VS. Simplemente se guarda en relación con la carpeta del proyecto en la siguiente ruta: \ YouProject \ Saved \ PVS-Studio \. Para abrir este archivo en VS, debe usar el siguiente comando: 'PVS-Studio | Abrir / Guardar | Abrir informe de análisis' y configurar la opción 'Salida no analizada' en la opción de selección de tipo de archivo. También puede abrir el archivo de informe en el programa de Monitoreo del compilador C y C ++ usando este comando: 'Archivo | Abrir PVS-Studio Log' y también seleccionar el tipo de archivo 'Salida no analizada'.
Hay una opción más conveniente para abrir el registro de análisis: se carga automáticamente en VS. Para cargarlo automáticamente en la ventana de PVS-Studio en VS después de que se complete el análisis, debe habilitar la opción correspondiente: 'PVS-Studio | Opciones | Configuración específica del analizador | Guardar / Cargar (informe del analizador) | AutoloadUnrealEngineLog'.
Descargue y pruebe el analizador PVS-Studio
Yo, como autor de este artículo y como una de esas personas que están trabajando directamente en la implementación y el soporte de la funcionalidad PVS-Studio relacionada con el análisis de proyectos creados sobre la base del motor UE, estoy listo para ayudar a los lectores. Si tiene dificultades para usar PVS-Studio con su proyecto de UE o tiene alguna pregunta que no pudo encontrar una respuesta en este artículo, me complacerá hablar con usted. Escríbanos en
apoyo y me serán entregadas cartas sobre UE y temas relacionados. Gracias por su atencion
Enlaces de sitio
- Andrey Karpov. La tan esperada verificación de Unreal Engine 4 . (14 de abril de 2014)
- Pavel 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 de Unreal Engine . (27 de junio de 2017)
Si desea compartir este artículo con una audiencia de habla inglesa, utilice el enlace a la traducción: Ilya Gainulin.
Uso de PVS-Studio al verificar proyectos de Unreal Engine en el sistema operativo Windows .