Este artigo é dedicado aos recursos de verificação de projetos do Unreal Engine usando o analisador estático PVS-Studio no sistema operacional Windows: como instalar o analisador, como verificar o projeto, onde e como visualizar o relatório de erros.
Parte integrante do ciclo de nossos artigos são tópicos de uma maneira ou de outra relacionados à indústria de jogos. Verificar o mecanismo físico usado nos jogos AAA - cometa os principais erros da indústria de jogos -
para sua saúde , encontrar bugs em um dos mecanismos de jogos mais populares - o Unreal Engine (UE) - é
fácil . Ao desenvolver jogos, bem como ao escrever outros aplicativos, a qualidade do código é importante. Os erros são melhor encontrados o mais cedo possível e é aconselhável fazer isso automaticamente - é aqui que os analisadores de código estático auxiliam os programadores.
Neste artigo, tentarei falar brevemente sobre como você pode usar o analisador estático PVS-Studio para analisar projetos criados no UE. O PVS-Studio ajudará a melhorar o código de seus projetos, encontrando erros, permitindo reduzir o tempo gasto na revisão de códigos.
Observe que este artigo é um complemento à
documentação existente sobre a análise de projetos da UE e não serve para substituí-lo, emprestando amplamente o conteúdo da documentação.
Instale o PVS-Studio
A maneira mais fácil de instalar o analisador PVS-Studio é baixar o
arquivo de instalação . Para poder analisar projetos criados no UE, ao instalar o PVS-Studio, você precisa selecionar os seguintes componentes: “Monitoramento de compilador C e C ++” e “Integração com o Microsoft Visual Studio (Visual C ++ / C #)”. O último item é responsável pela integração do plug-in PVS-Studio no IDE do Visual Studio, através do qual é conveniente trabalhar com o log de erros e com as configurações gerais do próprio analisador.
Para trabalhar totalmente com o PVS-Studio, você deve inserir uma licença. Isso pode ser feito abrindo o IDE do Visual Studio (VS) e inserindo a licença na janela 'PVS-Studio | Opções ... | Registro'. No VS 2019, o menu PVS-Studio foi removido no menu 'Extensões', para que o caminho para a janela de entrada da licença tenha a seguinte aparência: 'Extensões' | 'PVS-Studio | Opções ... | Registro'. A licença pode ser obtida em nosso
site .
Para criar projetos UE, não é usado o sistema de montagem padrão usado no VS - MSBuild, mas o próprio programa da Epic Games responsável pela montagem - UnrealBuildTool (UBT). Nesse sentido, o plug-in PVS-Studio não pode implementar o script usual para verificar projetos C ++ / C # criados no VS: “PVS-Studio -> Verificar -> Projeto Atual”. Existem várias soluções para contornar essa limitação.
Executando análise usando um sistema de monitoramento de compilação
A primeira e mais fácil maneira de verificar o projeto UE pode ser feita usando o programa C e C ++ Compiler Monitoring (chamado Standalone.exe), localizado no diretório de instalação do PVS-Studio. O princípio de seu trabalho é que ele monitora os lançamentos de processos correspondentes ao compilador de destino (neste caso, cl.exe) e coleta todas as informações necessárias para pré-processamento e análise posterior dos arquivos de origem. Depois de abrir o Monitoramento do compilador C e C ++, use o menu “Ferramentas” e selecione a opção “Analisar seus arquivos (C e C ++) ...”. Pressione o botão “Iniciar monitoramento” e você verá uma janela no canto inferior esquerdo da tela informando que as chamadas do compilador estão sendo monitoradas:
Em seguida, construa seu projeto UE e pressione a tecla "Stop Monitoring".
Depois disso, a análise dos arquivos de origem que foram compilados será iniciada. Um relatório dos avisos encontrados será exibido na janela Saída do analisador do programa C and C ++ Compiler Monitoring.
O rastreamento semelhante de chamadas do compilador e a análise subsequente dos arquivos recebidos podem ser feitos usando o programa de console CLMonitor.exe, localizado na mesma pasta em que o PVS-Studio foi instalado. O CLMonitor.exe possui dois modos operacionais: modo de servidor (quando o rastreamento de processos corresponde ao compilador de destino) e modo cliente (ao analisar os arquivos de origem recebidos no estágio de rastreamento e gerar um relatório sobre os resultados da análise). Para executar o CLMonitor.exe no modo de servidor, execute o seguinte comando:
CLMonitor.exe monitor
Depois disso, crie seu projeto UE e execute o comando abaixo:
CLMonitor.exe analyze -l "c:\ptest.plog"
O comando "analisar" inicia o CLMonitor.exe no modo cliente e fecha a instância em execução deste programa que trabalha no modo servidor. Após executar este comando, o CLMonitor.exe começará a analisar os arquivos. O parâmetro para a opção "- l" é o caminho para o arquivo no qual os resultados do analisador serão gravados.
Executando análises usando a chave -StaticAnalyzer = PVSStudio
Uma abordagem alternativa e mais conveniente para a análise de projetos da UE é a integração direta com o sistema de montagem UBT. Para fazer isso, no VS, abra a janela de propriedades do seu projeto UE e selecione "NMake" na lista "Configuration Properties". Adicione o sinalizador -StaticAnalyzer = PVSStudio à caixa de texto da propriedade Build Command Line. Como exemplo, o valor do campo "Build Command Line" pode ser assim:
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 considerar que agora, ao realizar a montagem do projeto, apenas análises serão realizadas, mas a montagem em si não será realizada. Um cenário em que a montagem e a análise subsequente são realizadas será descrito abaixo. Também é necessário entender que apenas os arquivos de origem serão analisados que foram alterados desde a última compilação do projeto (se algum arquivo .h de plug-in tiver sido alterado, esse não será o motivo da análise durante a próxima compilação). Para realizar uma análise completa, você precisa adicionar o mesmo sinalizador ao campo de texto da propriedade "Reconstruir todas as linhas de comando". Agora, quando você reconstrói o projeto, obtém o resultado da análise de todo o projeto.
Script de análise através da modificação de arquivos em lote
Agora, vejamos outro cenário para integrar o analisador PVS-Studio ao sistema de montagem UBT, no qual a análise é iniciada imediatamente após a construção / remontagem do projeto, ou seja, na saída, você obtém o projeto montado e o arquivo de resultados da análise. Como você deve ter notado, o campo Build Command Line contém o caminho para o arquivo em lotes Build.bat, que por sua vez contém instruções para iniciar o UBT com os argumentos necessários. O Build.bat inicia no início da compilação.
A idéia é alterar o arquivo em lote para que ele inicie o UBT primeiro com os argumentos de construção padrão e, se a fase de construção for concluída com êxito, execute o mesmo UBT novamente, mas com o sinalizador adicional -StaticAnalyzer = PVSStudio. Para implementar o cenário acima, você pode modificar o arquivo em lotes Build.bat (e é melhor criar uma cópia com o nome, por exemplo, BuildAndAnalyze.bat) da seguinte maneira. Imediatamente após o comando popd, insira as seguintes instruções:
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!" )
Se o sinalizador -StaticAnalyzer = PVSStudio tiver sido definido anteriormente no campo Build Command Line nas configurações do projeto 'Properties | Configuration Properties | NMake', será necessário removê-lo.
O problema dessa abordagem é que apenas os arquivos que foram compilados durante a fase de construção serão analisados. Ou seja, você não receberá um arquivo de relatório com uma verificação completa do seu projeto. Além disso, quaisquer alterações feitas nos arquivos de cabeçalho .h incluídos também não serão levadas em consideração. Portanto, não podemos chamar essa análise de incremental, pois as alterações nos arquivos de cabeçalho não levarão a análise a ser realizada durante uma nova montagem. Nesse caso, você pode reconstruir o projeto, obtendo um resultado de análise para todo o projeto. No entanto, pode levar muito tempo para concluir a montagem, para que você possa seguir o seguinte cenário: criar, excluir o arquivo de cache - ActionHistory.bin, iniciar a montagem com o sinalizador -StaticAnalyzer = PVSStudio e restaurar o arquivo de cache. O arquivo ActionHistory.bin contém as informações necessárias para a execução de montagens incrementais, bem como o histórico de inicialização do analisador para os arquivos verificados.
À primeira vista, esse cenário pode não parecer o mais fácil, portanto forneceremos um conjunto completo de instruções sobre como você pode modificar o arquivo Build.bat original. Vale ressaltar que essas alterações são relevantes apenas para o Unreal Engine versão 4.21 e superior. Após o comando setlocal enabledelayedexpansion, declare as seguintes variáveis:
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%"
Imediatamente após a instrução popd, insira estes 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% ) )
Observe que as variáveis PROJECT_NAME, PLATFORM e UPROJECT_FILE necessárias para determinar corretamente o caminho do cache obtêm seus valores nos argumentos da linha de comando Build.bat. Se você tiver uma ordem diferente desses argumentos, deverá alterar a inicialização das três variáveis descritas acima.
Análise incremental de projeto através da modificação do UBT
O PVS-Studio pode trabalhar no modo de análise incremental. A análise incremental visa verificar apenas os arquivos de origem que foram modificados desde a última compilação do projeto. No modo de análise incremental, o PVS-Studio inicia automaticamente em segundo plano na máquina do desenvolvedor imediatamente após a compilação do código e analisa todos os arquivos afetados pelas modificações. Você pode encontrar um guia mais detalhado sobre o uso do PVS-Studio no modo de análise incremental em nossa
documentação .
Com a implementação do modo de análise incremental para projetos da UE, tudo fica um pouco mais complicado do que com o cenário de trabalho padrão. Nesse caso, para poder executar uma análise incremental (levando em consideração as alterações nos arquivos .h conectados), você precisará fazer alterações no sistema de montagem UBT. Para fazer isso,
acesse o repositório UE no github.com e clone-o na sua máquina. Para configurar ainda mais o repositório clonado, você precisa seguir as etapas listadas na seção “Instalando e executando” da subseção “Windows”. Você pode encontrar a seção mencionada na página principal do repositório oficial da UE. Depois de configurar seu repositório, você poderá começar a fazer alterações no UBT. Para fazer isso, vá para o seguinte caminho no repositório clonado: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Abra a solução UnrealBuildTool.sln e, na janela Solution Explorer, localize o arquivo PVSToolChain.cs. Neste arquivo, adicione as seguintes linhas de código à classe PVSApplicationSettings:
Essa linha de código permite que a opção IncrementalAnalysis seja desserializada do arquivo de configurações do PVS-Studio. Não se esqueça de ativar o próprio modo de análise incremental do PVS-Studio.Para fazer isso, abra o item de menu principal Extensões no VS, o submenu PVS-Studio, Análise após compilação (somente arquivos modificados), Ativado. Agora adicione as seguintes linhas de código imediatamente após declarar a variável BaseFileName:
Depois disso, exclua as declarações de variáveis anteriores OutputFileLocation e OutputFileItem abaixo no código.
Durante o processo de montagem do projeto UE, um arquivo de objeto .obj é gerado para cada arquivo .cpp de origem. A ideia dessa análise incremental é verificar apenas os arquivos .cpp de origem para os quais a data de criação / modificação do arquivo de objeto é mais recente que a do arquivo de relatório .pvslog (para cada arquivo de origem é gerado seu próprio arquivo .pvslog, então tudo Os arquivos .pvslog serão combinados em um final .pvslog). Depois de fazer as alterações acima, compile o UBT e copie o binário recém-coletado no local do UBT original.
Está tudo pronto, agora, quando você concluir a montagem do projeto UE, receberá um log de relatório contendo os resultados do analisador apenas para os arquivos de origem que foram submetidos à compilação. Lembre-se de que essa modificação no UBT só faz sentido se você modificar o arquivo Build.bat para excluir o arquivo de cache ActionHistory.bin (uma descrição detalhada desse cenário foi descrita acima). Para desativar o modo de análise incremental, basta definir a opção "Análise após compilação (somente arquivos modificados)" descrita acima como "Desativado".
Deixe-me lembrá-lo mais uma vez: se você definir o sinalizador -StaticAnalyzer = PVSStudio no campo Build Command Line nas configurações do projeto 'Properties | Configuration Properties | NMake', será necessário removê-lo neste cenário.
Abrindo o arquivo de relatório do analisador e seu carregamento automático no Visual Studio
Por padrão, ao analisar um projeto UE, o arquivo de relatório não é carregado na janela PVS-Studio no VS. É simplesmente salvo em relação à pasta do projeto no seguinte caminho: \ YouProject \ Saved \ PVS-Studio \. Para abrir esse arquivo no VS, é necessário usar o seguinte comando: 'PVS-Studio | Abrir / Salvar | Abrir relatório de análise' e defina a opção 'Saída não analisada' na opção de seleção de tipo de arquivo. Você também pode abrir o arquivo de relatório no programa de Monitoramento de Compilador C e C ++ usando este comando: 'Arquivo | Abrir registro do PVS-Studio' e também selecionar o tipo de arquivo 'Saída não analisada'.
Existe uma opção mais conveniente para abrir o log de análise - ele é carregado automaticamente no VS. Para carregá-lo automaticamente na janela PVS-Studio no VS após a conclusão da análise, é necessário ativar a opção correspondente: 'PVS-Studio | Opções | Configurações específicas do analisador | Salvar / carregar (relatório do analisador) | AutoloadUnrealEngineLog'.
Faça o download e experimente o analisador PVS-Studio
Eu, como autor deste artigo e como uma daquelas pessoas que estão trabalhando diretamente na implementação e suporte da funcionalidade PVS-Studio relacionada à análise de projetos baseados no mecanismo UE, estou pronto para ajudar os leitores. Se você tiver alguma dificuldade em usar o PVS-Studio com seu projeto UE ou tiver alguma dúvida que não encontrou resposta neste artigo, terei prazer em conversar com você. Escreva-nos em
suporte e cartas serão entregues a mim sobre a UE e questões relacionadas. Obrigado pela atenção.
Sitelinks
- Andrey Karpov. A tão esperada verificação do Unreal Engine 4 . (14 de abril de 2014)
- Pavel Eremeev, Svyatoslav Razmyslov. Como a equipe do PVS-Studio aprimorou o código do Unreal Engine . (20 de junho de 2015)
- Andrey Karpov. Análise estática como parte do processo de desenvolvimento do Unreal Engine . (27 de junho de 2017)
Se você deseja compartilhar este artigo com um público que fala inglês, use o link para a tradução: Ilya Gainulin.
Uso do PVS-Studio ao verificar projetos de mecanismo irreal no sistema operacional Windows .