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:

• Criar perfis de referência para o app.
• Criar perfis de referência para a biblioteca.
• Personalizar a geração de perfis de referência.

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

• AGP 8.0 ou versões mais recentes
• Dependência da versão mais recente do plug-in para Gradle.

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:

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

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:

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

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

baselineProfile {
    ...
    useConnectedDevices = false
}

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.

baselineProfile {
    mergeIntoMain = true
}

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:

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

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:

baselineProfile {
    automaticGenerationDuringBuild = true
}

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:

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

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.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

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

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

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:

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.**")
    }
}

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:

// 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.**")
            }
        }
    }
}

// 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.

Personalizar os tipos de build de comparativo de mercado e perfil de referência

O plug-in do perfil de referência para Gradle cria outros tipos de build para gerar os perfis e executar comparações. Esses tipos de build são prefixados com benchmark e nonMinified. Por exemplo, para o tipo de build release, o plug-in cria os tipos de build benchmarkRelease e nonMinifiedRelease. Esses tipos de build são configurados automaticamente para o caso de uso específico e geralmente não precisam de personalização. Mas há alguns casos em que ainda pode ser útil aplicar algumas opções personalizadas, por exemplo, aplicar uma configuração de assinatura diferente.

Você pode personalizar os tipos de build gerados automaticamente usando um subconjunto de propriedades de tipo de build. As propriedades não utilizáveis são substituídas. O exemplo abaixo mostra como personalizar os outros tipos de build e quais propriedades são substituídas:

android {
    buildTypes {
        release {
            ...
        }
        benchmarkRelease {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default
            // it's the same as for the `release` build type).
            signingConfig = signingConfigs.getByName("benchmarkRelease")
        }
        nonMinifiedRelease {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.getByName("nonMinifiedRelease")

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't
            // customize the following properties, which are always overridden to
            // avoid breaking Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false
        }
    }
}

android {
    buildTypes {
        release {
            ...
        }
        benchmarkRelease {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default it's the
            // same as for the `release` build type.)
            signingConfig = signingConfigs.benchmarkRelease
        }
        nonMinifiedRelease {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.nonMinifiedRelease

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't use
            // the following properties, which are always overridden to avoid breaking
            // Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false       
        }
    }
}

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