Configurar a geração de perfis de referência

O plug-in para Gradle facilita a geração e a manutenção de perfis de referência. Ele ajuda você a realizar as seguintes tarefas:

Esta página explica como usar o plug-in do perfil de referência para Gradle ao personalizar a geração de perfis de referência.

Requisitos do plug-in

Usar dispositivos gerenciados pelo Gradle para gerar perfis de referência

Se quiser usar um dispositivo gerenciado pelo Gradle (GMD, na sigla em inglês) para gerar seu perfil de referência, adicione um na configuração build.gradle.kts do módulo do produtor de perfil (provavelmente o módulo de teste :baselineprofile) como mostrado no exemplo a seguir:

Kotlin

android {
   testOptions.managedDevices.devices {
       create<com.android.build.api.dsl.ManagedVirtualDevice>("pixel6Api31") {
           device = "Pixel 6"
           apiLevel = 31
           systemImageSource = "aosp"
       }
   }
}

Groovy

android {
   testOptions.managedDevices.devices {
       pixel6Api31(ManagedVirtualDevice) {
           device 'Pixel 6'
           apiLevel = 31
           systemImageSource 'aosp'
       }
   }
}

Use o GMD para gerar perfis de referência adicionando-o à configuração do plug-in do perfil de referência para Gradle da seguinte maneira:

Kotlin

baselineProfile {
    managedDevices += "pixel6Api31"
}

Groovy

baselineProfile {
    managedDevices = ['pixel6Api31']
}

Ao usar um GMD para gerar perfis de referência, defina useConnectedDevices como false:

Kotlin

baselineProfile {
    ...
    useConnectedDevices = false
}

Groovy

baselineProfile {
    ...
    useConnectedDevices false
}

Gerar perfis de referência para variantes diferentes

Você pode gerar perfis de referência por variante, por variação ou como um único arquivo para usar em todas as variantes. Controle esse comportamento usando a configuração de mesclagem, conforme mostrado no exemplo a seguir.

Kotlin

baselineProfile {
    mergeIntoMain = true
}

Groovy

baselineProfile {
    mergeIntoMain true
}

Para mesclar os perfis gerados para todas as variantes em um único perfil, defina mergeIntoMain como true. Não é possível gerar perfis de referência por variante quando essa configuração é true, então há uma única tarefa do Gradle chamada generateBaselineProfile. A saída do perfil é src/main/generated/baselineProfiles.

Para desativar a mesclagem e ter um perfil por variante, defina mergeIntoMain como false. Nesse caso, existem várias tarefas do Gradle específicas de variantes. Por exemplo, quando há duas variações (como sem custo financeiro e paga) e um tipo de build de lançamento, as tarefas geradas são estas:

* `generateFreeReleaseBaselineProfile`
* `generatePaidReleaseBaselineProfile`
* `generateReleaseBaselineProfile`

Para especificar o comportamento de mesclagem por variante, use este código:

Kotlin

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

No exemplo anterior, as variantes em que a flag está definida como true são mescladas em src/main/generated/baselineProfiles, enquanto os perfis das variantes em que a flag está definida como false são mantidos na pasta src/<variant>/generated/baselineProfiles.

Por padrão, mergeIntoMain é definido como true para bibliotecas e false para apps.

Gerar perfis de referência automaticamente ao criar uma nova versão

Você pode configurar perfis de referência para serem gerados automaticamente a cada build de lançamento em vez de usar a tarefa generateBaselineProfile manualmente. Com a geração automática, o perfil mais atualizado é incluído no build de lançamento.

Para ativar a geração automática de builds de lançamento, use a flag automaticGenerationDuringBuild:

Kotlin

baselineProfile {
    automaticGenerationDuringBuild = true
}

Groovy

baselineProfile {
    automaticGenerationDuringBuild true
}

Definir a flag automaticGenerationDuringBuild como true aciona a geração de um novo perfil de referência para cada conjunto de lançamento. Isso significa que executar uma tarefa de criação de build de lançamento, como ./gradlew:app:assembleRelease, também aciona :app:generateReleaseBaselineProfile, inicia os testes de instrumentação do perfil de referência e cria o build do perfil de referência em que eles são executados. Embora a geração automática ajude os usuários a ter o melhor benefício de desempenho, ela também aumenta o tempo de build devido aos testes duplos de build e de instrumentação.

Você também pode especificar esse comportamento por variante, conforme mostrado no exemplo abaixo:

Kotlin

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

No exemplo anterior, a tarefa generateFreeReleaseBaselineProfile é executada ao iniciar assembleFreeRelease. Isso ajuda quando o usuário quer ter, por exemplo, um release para o build de distribuição que sempre gera o perfil na criação e um build releaseWithoutProfile para testes internos.

Armazenar perfis de referência em origens

É possível armazenar perfis de referência no diretório de origem usando a flag saveInSrc:

  • true: o perfil de referência é armazenado em src/<variant>/generated/baselineProfiles. Isso permite confirmar o perfil gerado mais recentemente com suas origens.
  • false: o perfil de referência é armazenado nos arquivos intermediários do diretório de build. Dessa forma, ao confirmar seu código, você não salva o perfil gerado mais recentemente.

Kotlin

baselineProfile {
    saveInSrc = true
}

Groovy

baselineProfile {
    saveInSrc true
}

Também é possível especificar esse comportamento por variante:

Kotlin

baselineProfile {
    variants {
        freeRelease {
            saveInSrc = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

Filtrar regras de perfil

O plug-in do perfil de referência para Gradle permite filtrar as regras de perfil de referência geradas. Isso será particularmente útil para bibliotecas se você quiser excluir regras de perfil para classes e métodos que fazem parte de outras dependências do app de exemplo ou da própria biblioteca. Os filtros podem incluir e excluir pacotes e classes específicos. Quando você especifica apenas exclusões, somente as regras de perfil de referência correspondentes são excluídas, e todo o restante é incluído.

A especificação de filtros pode ser qualquer um destes padrões:

  • O nome do pacote termina com caracteres curinga duplos para corresponder ao pacote especificado e a todos os subpacotes. Por exemplo, com.example.** corresponde a com.example.method e com.example.method.bar.
  • O nome do pacote termina com um caractere curinga e corresponde apenas ao pacote especificado. Por exemplo, com.example.* corresponde a com.example.method, mas não corresponde a com.example.method.bar.
  • Nomes de classe para corresponder a uma classe específica, por exemplo, com.example.MyClass.

Os exemplos abaixo mostram como incluir e excluir pacotes específicos:

Kotlin

baselineProfile {
    filter {
        include("com.somelibrary.widget.grid.**")
        exclude("com.somelibrary.widget.grid.debug.**")
        include("com.somelibrary.widget.list.**")
        exclude("com.somelibrary.widget.list.debug.**")
        include("com.somelibrary.widget.text.**")
        exclude("com.somelibrary.widget.text.debug.**")
    }
}

Groovy

baselineProfile {
    filter {
        include 'com.somelibrary.widget.grid.**'
        exclude 'com.somelibrary.widget.grid.debug.**'
        include 'com.somelibrary.widget.list.**'
        exclude 'com.somelibrary.widget.list.debug.**'
        include 'com.somelibrary.widget.text.**'
        exclude 'com.somelibrary.widget.text.debug.**'
    }
}

Personalize as regras de filtro para variantes diferentes da seguinte maneira:

Kotlin

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include("com.myapp.**") }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include("com.myapp.free.**")
            }
        }
        paid {
            filter {
                include("com.myapp.paid.**")
            }
        }
    }
}

// Build-type-specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

Groovy

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include 'com.myapp.**' }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include 'com.myapp.free.**'
            }
        }
        paid {
            filter {
                include 'com.myapp.paid.**'
            }
        }
    }
}

// Build-type specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

Você também pode filtrar regras usando o argumento filterPredicate em BaselineProfileRule.collect(). No entanto, recomendamos usar o plug-in do Gradle para fazer a filtragem, porque ele fornece uma maneira mais simples de filtrar subpacotes e um único local para configurar o módulo todo.

Outras observações

Ao criar perfis de referência, considere o seguinte:

  • Perfis de referência compilados precisam ter menos de 1,5 MB. Isso não se aplica ao formato de texto nos arquivos de origem, que geralmente são muito maiores antes da compilação. Confira o tamanho do seu perfil de referência binário no artefato de saída em assets/dexopt/baseline.prof para um APK ou em BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof para um AAB.

  • Regras abrangentes que compilam grande parte do aplicativo podem atrasar a inicialização devido ao aumento do acesso ao disco. Se você estiver começando a usar os perfis de referência, não se preocupe. No entanto, dependendo do seu app e do tamanho e do número de jornadas, adicionar várias delas pode resultar em um desempenho abaixo do ideal. Para testar o desempenho do app, teste diferentes perfis e confira se o desempenho não regressa depois das adições.

Codelabs

Analise o processo de macrobenchmark para avaliar o desempenho.
Gere um perfil de referência personalizado para um app Android e analise a eficácia dele.