Este artigo aborda as especificidades da verificação de projetos do Unreal Engine com o analisador estático PVS-Studio no sistema operacional Windows: como instalar o analisador, verificar um projeto, onde e como visualizar um relatório de erro.
Parte integrante da série de nossos artigos são tópicos relacionados à indústria de jogos. Verifique um mecanismo real usado em jogos AAA - de
nada , encontre os principais erros da indústria de jogos -
vá em frente , encontre bugs em um dos motores de jogos mais populares, o Unreal Engine (UE) - com
bastante facilidade . No desenvolvimento de jogos, assim como em qualquer outro aplicativo, a qualidade do código é importante. Os erros são melhor encontrados o mais cedo possível e a melhor opção é fazê-lo automaticamente - é aqui que os analisadores de código estático ajudam os programadores.
Neste artigo, tentarei falar brevemente sobre como você pode usar o analisador estático PVS-Studio para verificar projetos criados no UE. O PVS-Studio pode ajudá-lo a melhorar o código do seu projeto, encontrando erros nele, permitindo reduzir o tempo gasto na revisão do código.
Observe que este artigo é uma adição à
documentação existente na análise de projetos da UE e não serve para substituí-lo, emprestando amplamente o conteúdo da documentação.
Instalação do PVS-Studio
A maneira mais fácil de instalar o analisador PVS-Studio é baixar o
arquivo de instalação . Para poder analisar os projetos criados no UE, é necessário selecionar os seguintes componentes ao instalar o PVS-Studio: "Monitoramento do compilador C e C ++" e "Integração com o Microsoft Visual Studio (Visual C ++ / C #)". O último ponto é responsável por integrar o plug-in PVS-Studio no Visual Studio IDE, por meio 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ê precisa inserir uma licença. Você pode fazer isso abrindo o Visual Studio (VS) IDE e inserindo a licença no 'PVS-Studio | Opções ... | Registro'. No VS 2019, o menu PVS-Studio foi movido para o menu 'Extensões', o caminho para a janela de entrada da licença é semelhante a: 'Extensões' | 'PVS-Studio | Opções ... | Registro'. A licença está disponível em nosso
site .
Para criar projetos UE, é usado um programa UnrealBuildTool (UBT) personalizado da Epic Games, não um sistema de compilação padrão, usado no VS (MSBuild). Nesse sentido, o plug-in PVS-Studio não pode implementar um cenário usual de verificação de projetos C ++ / C #, criados no VS: "PVS-Studio -> Verificar -> Projeto Atual". Existem várias soluções para evitar essa limitação.
Executando análises com o sistema de monitoramento de compilação
A primeira e a maneira mais fácil de verificar um projeto UE é usar o programa C e C ++ Compiler Monitoring (denominado Standalone.exe), localizado no diretório de instalação do PVS-Studio. O princípio de seu trabalho é que ele monitora os processos do compilador que correspondem ao compilador de destino (neste caso, cl.exe) e reúne 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 escolha a opção "Analisar seus arquivos (C e C ++) ...". Pressione "Iniciar monitoramento" e você verá a janela no canto inferior esquerdo informando que o monitoramento de chamadas do compilador está em andamento:
Em seguida, construa seu projeto UE e pressione "Stop Monitoring".
Depois disso, a análise dos arquivos de origem compilados será iniciada. O relatório dos avisos encontrados será mostrado na janela "Saída do analisador" do programa Monitoramento do compilador C e C ++.
O monitoramento de chamadas do compilador semelhante e a análise subsequente dos arquivos detectados podem ser feitos usando o programa do console CLMonitor.exe, localizado na mesma pasta em que o PVS-Studio foi instalado. O CLMonitor.exe possui dois modos de operação: um modo de servidor quando os lançamentos de processos (correspondentes ao compilador de destino) são monitorados e um modo cliente (quando os arquivos de origem, detectados no estágio de monitoramento, são analisados, seguidos por um relatório dos resultados da análise) . Para executar o CLMonitor.exe no modo de servidor, execute o seguinte comando:
CLMonitor.exe monitor
Depois disso, construa seu projeto UE e execute o comando abaixo:
CLMonitor.exe analyze -l "c:\ptest.plog"
O comando "analisar" executa o CLMonitor.exe no modo cliente e fecha a instância em execução deste programa, trabalhando no modo servidor. Após executar este comando, o CLMonitor.exe começará a executar a análise de arquivos. Um parâmetro para a opção "- l" é um caminho para o arquivo, no qual os resultados do analisador serão gravados.
Executando análises com a chave -StaticAnalyzer = PVSStudio
Uma abordagem diferente e mais conveniente para analisar projetos da UE é uma integração direta com o sistema construído pela UBT. Para fazer isso, abra a janela de propriedades do seu projeto UE no VS e escolha "NMake" na lista "Propriedades de configuração". Adicione -StaticAnalyzer = PVSStudio no campo de texto da propriedade "Build Command Line". Como exemplo, o valor do campo "Criar linha de comando" pode ter a seguinte aparência:
C:\Program Files\Epic Games\UE_4.22\Engine\Build\BatchFiles\Build.bat" MyProject Win64 DebugGame -Project="$(SolutionDir)$(ProjectName).uproject" -WaitMutex -FromMsBuild -StaticAnalyzer=PVSStudio
Deve-se levar em consideração que, ao executar uma construção do projeto, ela será analisada apenas, não construída. O cenário em que um projeto é construído e analisado será descrito abaixo. Também deve ser observado que apenas os arquivos de origem que foram alterados desde a última compilação do projeto serão analisados. A alteração de qualquer arquivo .h incluído não é um motivo para executar a análise durante a próxima compilação. Para realizar uma análise completa, você precisa adicionar o mesmo sinalizador no campo de texto da propriedade "Reconstruir toda a linha de comando". Agora, ao reconstruir o projeto, você obterá o resultado da análise de todo o projeto.
Executando a análise por meio da modificação de arquivos do pacote
Agora, vamos considerar outro cenário do analisador PVS-Studio integrado ao sistema de construção UBT. Enquanto isso, a análise começa logo após a execução / construção do projeto. Em outras palavras, você obtém um projeto construído e um arquivo com resultados de análise. Você pode ter notado que 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 executar o UBT com os argumentos necessários. O Build.bat é executado no início do build.
O ponto é alterar o arquivo em lote para que ele possa executar primeiro o UBT com argumentos de construção padrão e, se uma construção for concluída com êxito, execute o mesmo UBT, mas já com um sinalizador adicional -StaticAnalyzer = PVSStudio. Para implementar o cenário acima, você pode alterar o arquivo em lotes Build.bat. É ainda melhor criar sua cópia chamada, por exemplo, BuildAndAnalyze.bat. Aqui está o que você precisa fazer para implementar o cenário descrito. Logo 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 instalado anteriormente no campo Build Command Line nas configurações do projeto 'Properties | Configuration Properties | NMake', ele deverá ser removido.
O problema dessa abordagem é que apenas os arquivos que foram compilados durante a compilaçã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 .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 acionarão a análise durante a próxima compilação. Nesse caso, você pode reconstruir o projeto, obtendo o resultado da análise para todo o projeto. No entanto, a compilação completa pode demorar, portanto, você pode seguir este cenário: faça uma compilação, exclua o arquivo de cache ActionHistory.bin, execute a compilação com o sinalizador -StaticAnalyzer = PVSStudio, restaure o arquivo de cache. O arquivo ActionHistory.bin contém informações necessárias para executar a construção incremental, bem como o histórico de execução do analisador para 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 alterar o arquivo Build.bat original. Vale ressaltar que essas alterações são relevantes apenas para o Unreal Engine versão 4.21 e posterior. 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%"
Logo 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 para o arquivo em cache, obtêm seus valores a partir dos argumentos da linha de comando do Build.bat. Se você tiver uma ordem diferente desses argumentos, precisará alterar adequadamente a inicialização das três variáveis descritas acima.
Análise de projeto incremental via modificação UBT
O PVS-Studio pode trabalhar no modo de análise incremental. A análise incremental destina-se a verificar apenas os arquivos que foram alterados desde a última compilação. No modo de análise incremental, o PVS-Studio é executado automaticamente no computador de um desenvolvedor no modo de segundo plano logo após a compilação do código e analisa todos os arquivos modificados. 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 UE, tudo fica um pouco mais complicado do que em um cenário padrão. Nesse caso, para poder executar a análise incremental (levando em consideração as alterações nos arquivos .h incluídos), você deverá introduzir edições no sistema UBT de construção. Para fazer isso,
obtenha acesso ao repositório da UE no github.com e clone-o na sua máquina. Para personalizar ainda mais o repositório clonado, você precisará concluir as etapas listadas na seção "Instalando e executando", subseção "Windows". Você pode encontrar esta seção na primeira página 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, siga este caminho para o repositório clonado: \ UnrealEngine \ Engine \ Source \ Programs \ UnrealBuildTool. Abra a solução UnrealBuildTool.sln e localize o arquivo PVSToolChain.cs no Solution Explorer. Nesse arquivo, adicione as seguintes linhas de código na classe PVSApplicationSettings:
Essa linha de código permite que a opção IncrementalAnalysis seja desserializada dos arquivos 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, no VS abra "Extensões" no menu principal, submenu "PVS-Studio", "Análise após compilação (somente arquivos modificados)", "Ativado". Agora adicione as seguintes linhas de código logo após a declaração da variável BaseFileName:
Em seguida, remova as declarações anteriores das variáveis OutputFileLocation e OutputFileItem abaixo.
Durante a construção do projeto UE, um arquivo .obj de objeto é gerado para cada arquivo .cpp de origem. Essa análise incremental visa verificar apenas os arquivos .cpp de origem cuja data de criação / modificação do arquivo de objeto seja posterior à do arquivo de relatório .pvslog. Um arquivo .pvslog separado é gerado para cada arquivo de origem. No futuro, todos os arquivos .pvslog serão mesclados em um .pvslog final). Depois de fazer as alterações acima, crie o UBT e copie o arquivo binário recém-criado para o local do UBT original.
Agora está tudo pronto, você receberá um log de relatório ao executar a construção do seu projeto UE, contendo os resultados do analisador apenas para arquivos de origem compilados. Lembre-se de que essa modificação do UBT só faz sentido se você tiver modificado o arquivo Build.bat de forma a executar a remoção do arquivo de cache ActionHistory.bin (a descrição detalhada desse cenário foi fornecida acima). Para desativar o modo de análise incremental, basta instalar a opção "Análise após compilação (somente arquivos modificados)" descrita acima no modo "Desativado".
Deixe-me lembrá-lo mais uma vez: se você instalou o sinalizador -StaticAnalyzer = PVSStudio no campo Build Command Line nas configurações do projeto 'Properties | Configuration Properties | NMake' ', ele deverá ser removido neste cenário.
Abrindo o arquivo de relatório do analisador e seu carregamento automático no Visual Studio
Por padrão, ao executar a análise do projeto UE, um arquivo de relatório não será mostrado na janela PVS-Studio no VS. Ele é armazenado relativamente na pasta do projeto pelo seguinte caminho: \ YouProject \ Saved \ PVS-Studio \. Para abrir esse arquivo no VS, você precisa usar o seguinte comando: 'PVS-Studio | Abrir / Salvar | Abrir relatório de análise' e selecione o tipo de arquivo 'Saída não analisada'. Você também pode abrir o relatório de arquivo no programa C and C ++ Compiler Monitoring, usando o seguinte comando: 'File | Open PVS-Studio Log' e também escolher o tipo de arquivo 'Unparsed output'.
Há outra opção mais conveniente para abrir o log do relatório de análise, que é o carregamento automático no VS. Para carregar automaticamente na janela do PVS-Studio no VS após a conclusão da análise, é necessário ativar a opção apropriada: 'PVS-Studio | Opções | Configurações específicas do analisador | Salvar / carregar (relatório do analisador) | AutoloadUnrealEngineLog' .
Faça o download e experimente o PVS-Studio
Como autor deste artigo, além de uma das pessoas que estão trabalhando diretamente na implementação e suporte da funcionalidade do PVS-Studio relacionada à análise de projetos, construída com base no mecanismo da UE, estou pronto para ajudar os leitores . Se você estiver com problemas para usar o PVS-Studio com seu projeto UE ou tiver alguma dúvida depois de ler este artigo, ficarei feliz em conversar com você. Escreva para o nosso suporte, receberei e-mails no UE e questões relacionadas. Obrigado pela atenção.
Links adicionais
- Andrey Karpov. Uma verificação há muito esperada do mecanismo irreal 4 . (14 de abril de 2014)
- Paul Eremeev, Svyatoslav Razmyslov. Como a equipe do PVS-Studio aprimorou o código da Unreal Engine . (20 de junho de 2015)
- Andrey Karpov. Análise estática como parte do processo de desenvolvimento no Unreal Engine . (27 de junho de 2017)