Como configurar a otimização guiada por perfil no Visual Studio

O suporte à otimização guiada por perfil foi introduzido na versão 22.2.71 da AGDE.

Como localizar as configurações de PGO

Abra as configurações do projeto no Solution Explorer.

Menu de propriedades do Solution Explorer do Visual Studio para o projeto
atual.

Figura 1. Janela do Solution Explorer do Visual Studio.

Confira se a plataforma está definida para uma configuração do Android (por exemplo, Android-arm64-v8a).

No painel à esquerda, selecione Configuration Properties > General. Procure o grupo de propriedades chamado PGO.

Caixa de diálogo mostrando as propriedades gerais do projeto e as configurações de PGO
destacadas.

Figura 2. Caixa de diálogo "Project Properties".

Ativar builds instrumentados por PGO no projeto

Adicione ao projeto uma nova configuração chamada Instrumented. Ela é baseada na configuração que você usa durante o desenvolvimento para testes, ou seja, seu build otimizado tradicional. Ainda é possível ativar outros recursos de depuração caso as configurações de otimização do compilador sejam preservadas.

Clique em Configuration Manager… na caixa de diálogo da página "Property".

Parte de cima da caixa de diálogo "Property Pages", mostrando os menus suspensos "Active Solution
Configuration" e "Platform", além do botão
"Configuration Manager".

Figura 3. Caixa de diálogo do "Configuration Manager".

Na caixa de diálogo do "Configuration Manager", selecione o menu suspenso Active solution configuration e escolha <New…>.

Caixa de diálogo &quot;Configuration Manager&quot;, com o menu suspenso &quot;Active Solution Configuration&quot;
aberto e a opção &quot;New&quot; destacada.

Figura 4. Criação de uma nova configuração de build.

Crie uma configuração instrumentada por PGO.

Caixa de diálogo &quot;New Solution Configuration&quot; criando uma nova configuração de build instrumentada por PGO
com base na configuração do build de lançamento
atual.

Figura 5. Caixa de diálogo "New Solution Configuration".

Para ativar a criação no modo de instrumentação pela PGO e gerar um perfil para seu jogo, selecione Instrumented na lista de opções da configuração Profile-Guided Optimization Mode.

Caixa de diálogo &quot;Project Properties&quot; aberta nas configurações gerais, com as configurações de PGO
aparecendo, e o modo de otimização guiada pelo perfil definido como
&quot;Instrumented&quot;.

Figura 6. Caixa de diálogo "Project Properties" destacando as configurações da PGO.

Para a configuração Profile Guided Optimization Profiles, insira o caminho para a pasta no seu dispositivo Android em que você quer salvar o arquivo de saída bruto dos dados do perfil. Normalmente, esse valor é algo como /data/data/<package name>/cache/, em que <package name> é o nome de pacote completo do APK (por exemplo, com.google.sample.tunnel).

Para entender melhor como isso funciona, consulte a documentação do Clang (link em inglês).

Como gravar dados de perfil instrumentados por PGO no dispositivo

Os dados da PGO costumam ser gravados no dispositivo pelo sistema de instrumentação dela ao sair do processo. No Android, os apps não saem do processo, eles são sempre encerrados. Isso significa que a funcionalidade padrão de gravação em disco nunca é acionada, exigindo que o app grave dados de PGO manualmente.

Seu app precisa chamar __llvm_profile_write_file de forma explícita para gravar os dados do perfil. Esse símbolo só fica disponível ao criar um build instrumentado por PGO. Para facilitar, recomendamos o uso do seguinte padrão ao declarar __llvm_profile_write_file.

#ifdef PGO_INSTRUMENT
extern "C" int __llvm_profile_write_file(void);
#else
extern "C" int __llvm_profile_write_file(void) { return 0; }
#endif

Chamar essa função grava os dados de perfil na pasta especificada anteriormente.

Como executar um perfil

Para gerar o perfil, execute o APK criado com a instrumentação por PGO no dispositivo de destino. Depois de ter executado o código corretamente e acionado a chamada para a função __llvm_profile_write_file, seu app vai gravar os dados do perfil no armazenamento.

Neste ponto, copie os perfis do dispositivo para uso pelo compilador.

Como preparar dados de perfil para uso pelo compilador

Quando usada de forma isolada, a ferramenta de linha de comando llvm-profdata, que é fornecida como parte do Clang/LLVM no Android NDK, é usada para preparar arquivos de dados de perfil para uso pelo compilador durante a otimização de um build guiada por perfil.

A AGDE realiza essa etapa automaticamente mesclando todos os arquivos de dados do perfil adicionados ao projeto e consumindo-os quando a configuração Profile-Guided Optimization Mode nas páginas de propriedade do projeto está definida como Optimized.

Como criar um projeto com a otimização guiada por perfil ativada

Agora que você capturou seus perfis e os adicionou ao projeto, o compilador pode usar os dados para ajustar a otimização do build.

Gere uma configuração de projeto para seu build otimizado pela PGO para que você possa criar nesse modo apenas quando necessário.

Caixa de diálogo &quot;New Solution Configuration&quot; criando uma configuração com base no
build de lançamento, mas com &quot;PGO-Optimized&quot; como o nome da configuração
do build.

Figura 7. Criação de uma configuração de build otimizada pela PGO.

Defina a configuração Profile-Guided Optimization Mode nas páginas de propriedade do projeto como Optimized.

Caixa de diálogo &quot;Project Properties&quot; aberta nas configurações gerais, com as configurações de PGO
aparecendo, e o modo de otimização guiada pelo perfil definido como
&quot;Optimized&quot;.

Figura 8. Configuração do modo de otimização PGO como "Optimized".

Copie e adicione os arquivos do dispositivo ao projeto no Solution Explorer. Esses arquivos de dados do perfil serão coletados pelo compilador na próxima vez que você criar a configuração otimizada pela PGO. Eles serão usados para ajustar o modo como o compilador otimiza seu código.

Você pode copiar os arquivos de dados do perfil para o projeto do dispositivo usando o adb ou o Android Device Explorer.

Como usar a otimização guiada por perfil fora da AGDE

Se você está usando um sistema de build sem suporte da AGDE, pode ser necessário editar o build diretamente. Clang documentação cobre as chaves necessárias (-fprofile-generate) e -fprofile-use.

Se você estiver usando um mecanismo de middleware para o jogo, consulte a documentação dele para aprender a ativar a PGO, caso haja suporte.