Criar perfis de referência

Os perfis de referência são essenciais para maximizar a performance do Jetpack Compose. A pré-compilação das jornadas ideais do usuário ajuda a garantir que a interface do Compose seja renderizada sem problemas.

Gere perfis automaticamente para cada lançamento usando a biblioteca Macrobenchmark do Jetpack e BaselineProfileRule. Recomendamos usar o com.android.tools.build:gradle:8.0.0 ou versões mais recentes para aproveitar as melhorias de build ao usar perfis de referência.

Estas são as etapas gerais para criar um novo perfil de referência:

1. Configure o módulo do perfil de referência.
2. Defina o teste JUnit que ajuda a gerar perfis de referência.
3. Adicione as jornadas ideais do usuário (CUJs) que você quer otimizar.
4. Gere o perfil de referência.

Depois de gerar o perfil de referência, compare-o usando um dispositivo físico para medir as melhorias na velocidade.

Criar um novo perfil de referência com o AGP 8.2 ou mais recente

A maneira mais fácil de criar um novo perfil de referência é usar o modelo de módulo disponível no Android Studio Iguana com o Plug-in do Android para Gradle (AGP) 8.2 e mais recentes.

O modelo de módulo do gerador de perfis de referência do Android Studio automatiza a criação de um novo módulo para gerar e comparar perfis de referência. A execução do modelo gera a maior parte da configuração do build típica, a geração do perfil de referência e o código de verificação. O modelo cria um código para gerar e comparar perfis de referência e avaliar a inicialização do app.

Configurar o módulo do perfil de referência

Para executar o modelo de módulo do perfil de referência, siga estas etapas:

1. Selecione File > New > New Module.
2. Selecione o modelo Gerador de perfil de referência no painel Modelos e configure-o:

   

   Os campos no modelo são os seguintes:
   • Aplicativo de destino: o app para o qual o perfil de referência é gerado. Quando você só tem um módulo de app no projeto, há apenas um item nessa lista.
   • Nome do módulo: o nome que você quer definir para o módulo do perfil de referência que está sendo criado.
   • Nome do pacote: o nome do pacote que você quer para o módulo do perfil de referência.
   • Idioma: se você quer que o código gerado seja em Kotlin ou Java.
   • Build configuration language: para decidir se você vai usar o script Kotlin (KTS) ou o Groovy nos scripts de configuração do build.
   • Usar dispositivo gerenciado pelo Gradle: se você está usando dispositivos gerenciados pelo Gradle para testar o app.
3. Clique em Finish para que o novo módulo seja criado. Se você estiver usando o controle de origem, talvez receba uma solicitação para adicionar os arquivos do módulo recém-criado ao controle de origem.

Definir o gerador do perfil de referência

O módulo recém-criado contém testes para gerar e comparar o perfil de referência e testar apenas a inicialização básica do app. Recomendamos que você os aumente para incluir as CUJs e os fluxos de trabalho avançados de inicialização. Verifique se todos os testes relacionados à inicialização do app estão em um bloco rule com includeInStartupProfile definido como true. Por outro lado, para uma performance ideal, verifique se os testes não relacionados à inicialização do app não estão incluídos em um perfil de inicialização. As otimizações de inicialização do app são usadas para definir uma parte especial de um perfil de referência chamado perfil de inicialização.

Isso vai ajudar na manutenção se você abstrair essas CUJs fora do perfil de referência gerado e do código de referência para que elas possam ser usadas para ambos. Assim, as mudanças nas CUJs são usadas de maneira consistente.

Gerar e instalar o perfil de referência

O modelo de módulo do perfil de referência adiciona uma nova configuração de execução para gerar o perfil de referência. Se você estiver usando variações de produto, o Android Studio vai criar várias configurações de execução para que seja possível gerar perfis de referência separados para cada uma delas.

Quando a configuração de execução Generate Baseline Profile for concluída, ela vai copiar o perfil de referência gerado para o arquivo src/variant/generated/baselineProfiles/baseline-prof.txt no módulo que está sendo criado. As opções de variantes são o tipo de build de lançamento ou uma variante que o envolva.

O perfil de referência gerado é criado originalmente em build/outputs. O caminho completo é determinado pela variante ou variação do app para o qual um perfil está sendo criado e pelo uso de um dispositivo gerenciado pelo Gradle ou um dispositivo conectado para criar um perfil. Se você usar os nomes utilizados pelo código e as configurações de build geradas pelo modelo, o perfil de referência será criado no arquivo build/outputs/managed_device_android_test_additional_output/nonminifiedrelease/pixel6Api31/BaselineProfileGenerator_generate-baseline-prof.txt. Provavelmente, você não precisará interagir diretamente com essa versão do perfil de referência gerado, a menos que esteja copiando manualmente para os módulos de destino (não recomendado).

Criar um novo perfil de referência com o AGP 8.1

Caso não seja possível usar o modelo de módulo do perfil de referência, use o modelo de módulo da biblioteca Macrobenchmark e o plug-in do perfil de referência para Gradle para criar um novo perfil. Recomendamos usar essas ferramentas no Android Studio Giraffe e com o AGP 8.1 e versões mais recentes.

Confira as etapas para criar um novo perfil de referência usando o modelo de módulo da biblioteca Macrobenchmark e o plug-in do perfil de referência para Gradle:

1. Configure um módulo da Macrobenchmark no seu projeto do Gradle.

2. Defina uma nova classe com o nome BaselineProfileGenerator:

   class BaselineProfileGenerator {
       @get:Rule
       val baselineProfileRule = BaselineProfileRule()
   
       @Test
       fun startup() = baselineProfileRule.collect(
           packageName = "com.example.app",
           profileBlock = {
               startActivityAndWait()
           }
       )
   }
   

   O gerador pode incluir interações com o app além da inicialização. Isso permite otimizar o desempenho de execução do app, como listas de rolagem, execução de animações e navegação em uma Activity. Confira outros exemplos de testes que usam @BaselineProfileRule para melhorar jornadas ideais do usuário.

3. Adicione o plug-in do perfil de referência para Gradle (libs.plugins.androidx.baselineprofile). Ele facilita a geração e manutenção de perfis de referência.

4. Para gerar o perfil de referência, execute as tarefas do Gradle :app:generateBaselineProfile ou :app:generateVariantBaselineProfile no terminal.

   Execute o gerador como um teste instrumentado em um dispositivo físico com acesso root, emulador ou dispositivo gerenciado pelo Gradle. Se você usa um dispositivo gerenciado pelo Gradle, defina aosp como systemImageSource, já que o gerador de perfis de referência precisa de acesso root.

   No final da tarefa de geração, o perfil de referência será copiado para app/src//generated/baselineProfiles.

Criar um novo perfil de referência sem modelos

Recomendamos criar um perfil de referência usando o modelo de módulo de perfil de referência do Android Studio Baseline Profile (preferencial) ou o modelo da biblioteca Macrobenchmark, mas você também pode usar o plug-in do perfil de referência para Gradle sozinho. Para saber mais sobre o plug-in do perfil de referência para Gradle, consulte Configurar a geração do perfil de referência.

Confira como criar um perfil de referência usando o plug-in para Gradle:

1. Crie um novo módulo com.android.test (por exemplo, :baseline-profile).

2. Configure o arquivo build.gradle.kts para :baseline-profile:

   1. Aplique o plug-in androidx.baselineprofile.
   2. Verifique se o targetProjectPath aponta para o módulo :app.
   3. Se quiser, adicione um dispositivo gerenciado pelo Gradle (GMD, na sigla em inglês). No exemplo a seguir, é pixel6Api31. Se não for especificado, o plug-in vai usar um dispositivo conectado, seja ele emulado ou físico.
   4. Aplique a configuração desejada, conforme mostrado no exemplo a seguir.

   Kotlin

   plugins {
       id("com.android.test")
       id("androidx.baselineprofile")
   }
   
   android {
       defaultConfig {
           ...
       }
   
       // Point to the app module, the module that you're generating the Baseline Profile for.
       targetProjectPath = ":app"
       // Configure a GMD (optional).
       testOptions.managedDevices.devices {
           pixel6Api31(com.android.build.api.dsl.ManagedVirtualDevice) {
               device = "Pixel 6"
               apiLevel = 31
               systemImageSource = "aosp"
           }
       }
   }
   
   dependencies { ... }
   
   // Baseline Profile Gradle plugin configuration. Everything is optional. This
   // example uses the GMD added earlier and disables connected devices.
   baselineProfile {
       // Specifies the GMDs to run the tests on. The default is none.
       managedDevices += "pixel6Api31"
       // Enables using connected devices to generate profiles. The default is
       // `true`. When using connected devices, they must be rooted or API 33 and
       // higher.
       useConnectedDevices = false
   }

   Groovy

   plugins {
       id 'com.android.test'
       id 'androidx.baselineprofile'
   }
   
   android {
       defaultConfig {
           ...
       }
   
       // Point to the app module, the module that you're generating the Baseline Profile for.
       targetProjectPath ':app'
       // Configure a GMD (optional).
       testOptions.managedDevices.devices {
           pixel6Api31(com.android.build.api.dsl.ManagedVirtualDevice) {
               device 'Pixel 6'
               apiLevel 31
               systemImageSource 'aosp'
           }
       }
   }
   
   dependencies { ... }
   
   // Baseline Profile Gradle plugin configuration. Everything is optional. This
   // example uses the GMD added earlier and disables connected devices.
   baselineProfile {
       // Specifies the GMDs to run the tests on. The default is none.
       managedDevices ['pixel6Api31']
       // Enables using connected devices to generate profiles. The default is
       // `true`. When using connected devices, they must be rooted or API 33 and
       // higher.
       useConnectedDevices false
   }

3. Crie um teste do perfil de referência no módulo de teste :baseline-profile. O exemplo a seguir é um teste que gera um perfil de referência para a inicialização do app.

       class BaselineProfileGenerator {
       @get:Rule
       val baselineProfileRule = BaselineProfileRule()
   
       @Test
       fun startup() = baselineProfileRule.collect(
           packageName = "com.example.app",
           profileBlock = {
               uiAutomator { startApp(PACKAGE_NAME) }
           }
       )
   }
   

4. Atualize o arquivo build.gradle.kts no módulo do app (por exemplo, :app).

   1. Aplique o plug-in androidx.baselineprofile.
   2. Adicione uma dependência do baselineProfile ao módulo :baseline-profile.

   Kotlin

   plugins {
       id("com.android.application")
       id("androidx.baselineprofile")
   }
   
   android {
       // There are no changes to the `android` block.
       ...
   }
   
   dependencies {
       ...
       // Add a `baselineProfile` dependency on the `:baseline-profile` module.
       baselineProfile(project(":baseline-profile"))
   }

   Groovy

   plugins {
       id 'com.android.application'
       id 'androidx.baselineprofile'
   }
   
   android {
       // No changes to the `android` block.
       ...
   }
   
   dependencies {
       ...
       // Add a `baselineProfile` dependency on the `:baseline-profile` module.
       baselineProfile ':baseline-profile'
   }

5. Gere o perfil executando as tarefas :app:generateBaselineProfile ou :app:generateVariantBaselineProfile do Gradle.

6. No final da tarefa de geração, o perfil de referência será copiado para app/src/variant/generated/baselineProfiles.

Comparar o perfil de referência

Para comparar seu perfil de referência, crie uma configuração de execução de teste instrumentado do Android com base na ação de gutter que executa as comparações definidas no arquivo StartupBenchmarks.kt. Para saber mais sobre os testes de comparação, consulte Criar uma classe Macrobenchmark e Comparar perfis de referência com a biblioteca Macrobenchmark.

Quando essa execução é feita no Android Studio, a saída do build contém detalhes das melhorias de velocidade oferecidas pelo perfil de referência:

StartupBenchmarks_startupCompilationBaselineProfiles
timeToInitialDisplayMs   min 161.8,   median 178.9,   max 194.6
StartupBenchmarks_startupCompilationNone
timeToInitialDisplayMs   min 184.7,   median 196.9,   max 202.9

Capturar todos os caminhos de código necessários

Confira as duas métricas principais para medir os tempos de inicialização do app:

• Tempo para exibição inicial (TTID): o tempo necessário para mostrar o primeiro frame da interface do aplicativo.

• Tempo para exibição total (TTFD): o TTID somado ao tempo para mostrar conteúdo que seja carregado de forma assíncrona após a exibição do frame inicial.

O TTFD é informado quando o reportFullyDrawn método do ComponentActivity é chamado. Se reportFullyDrawn nunca for chamado, o TTID será informado. Talvez seja necessário atrasar a chamada do reportFullyDrawn até que o carregamento assíncrono seja concluído. Por exemplo, se a interface contém uma lista dinâmica lenta, talvez ela seja preenchida por uma tarefa em segundo plano que será concluída depois que a lista for renderizada e, portanto, depois que a interface estiver marcada como totalmente renderizada. Nesses casos, o código executado depois que a interface atinge o estado totalmente renderizado não é incluído no perfil de referência.

Para incluir o preenchimento da lista como parte do perfil de referência, acesse o FullyDrawnReporter usando getFullyDrawnReporter e adicione um informante no código do app. Libere o informante depois que a tarefa em segundo plano terminar de preencher a lista. O FullyDrawnReporter não chama o método reportFullyDrawn até que todos os informantes sejam liberados. Ao fazer isso, o perfil de referência inclui os caminhos de código necessários para preencher a lista. Isso não muda o comportamento do app para o usuário, mas permite que o perfil de referência inclua todos os caminhos de código necessários.

Para indicar o estado totalmente renderizado, use as APIs do Compose abaixo:

• ReportDrawn indica que o elemento combinável está pronto para interação.
• ReportDrawnWhen usa um predicado, por exemplo, list.count > 0, para indicar quando o elemento combinável está pronto para interação.
• ReportDrawnAfter usa um método de suspensão que, quando concluído, indica que o elemento combinável está pronto para interação.