Em projetos com muitos módulos, pode ser difícil distribuir bibliotecas do Android para os usuários enquanto tenta manter uma estrutura de projeto clara. Em muitos casos, é preciso publicar muito mais bibliotecas do que o planejado.
O plug-in de biblioteca combinada, que vem com o Plug-in do Android para Gradle, ajuda a empacotar vários módulos de biblioteca do Android em uma única biblioteca do Android publicável. Isso permite modularizar o código-fonte e os recursos da biblioteca no build como você quiser, evitando a exposição da estrutura do projeto após a distribuição.
A distribuição como uma única biblioteca pode ter os seguintes benefícios:
- Dependências simplificadas: substitui várias dependências de biblioteca por um único AAR, simplificando a configuração do projeto e o gerenciamento de versões para os usuários.
- Tamanho reduzido da biblioteca: pode melhorar a redução de código, resultando em AARs menores.
- Segurança aprimorada: pode oferecer um controle melhor sobre os detalhes de implementação interna das bibliotecas publicadas.
Criar uma biblioteca combinada
Para criar uma biblioteca combinada, você precisa criar um novo módulo do Android, adicionar dependências e publicar a biblioteca combinada.
Pré-requisitos
Para usar o plug-in da biblioteca combinada, use o AGP 9.0 ou mais recente. As versões anteriores do plug-in da biblioteca combinada têm comportamentos e problemas diferentes, que foram corrigidos no AGP 9.0.
Adicionar um novo módulo de biblioteca unificada
Para usar o plug-in, adicione um novo módulo do Android ao seu projeto:
Neste exemplo, o módulo de biblioteca combinada será chamado de myFusedLibrary.
- Anexe
include(":myFusedLibrary")ao arquivosettings.gradle.kts. - Adicione
android-fusedlibrary = { id = "com.android.fused-library", version.ref = "agp" }na seção[plugins]do arquivogradle/libs.versions.toml. - Adicione
alias(libs.plugins.android.fusedlibrary) apply falseao bloco de plug-ins no arquivobuild.gradle.ktsde nível superior. - Para criar o módulo
myFusedLibrary, crie um novo diretório chamadomyFusedLibrary(clique com o botão direito do mouse em "My Application" > New > Directory). - Crie um arquivo
build.gradle.ktsno módulomyFusedLibrary(clique com o botão direito do mouse no módulomyFusedLibrary> New > File). - Cole o seguinte no arquivo
myFusedLibrary/build.gradle.kts:
Kotlin
plugins { alias(libs.plugins.android.fusedlibrary) `maven-publish` } androidFusedLibrary { namespace = "com.example.myFusedLibrary" minSdk = 21 } dependencies { }
Groovy
plugins { id 'com.android.fused-library' } androidFusedLibrary { namespace 'com.example.myFusedLibrary' minSdk 21 } dependencies { }
Adicionar dependências
A funcionalidade principal da biblioteca combinada é agrupar dependências. O
plug-in permite adicionar dependências de projetos locais e bibliotecas externas.
Para especificar as dependências a serem empacotadas, use a configuração include.
As dependências transitivas não são empacotadas.
Exemplo:
Kotlin
dependencies { include(project(":image-rendering")) include("mycoolfonts:font-wingdings:5.0") }
Groovy
dependencies { include project(':image-rendering') include 'mycoolfonts:font-wingdings:5.0' }
Publicar sua biblioteca combinada
É importante se familiarizar com a publicação de uma biblioteca Android antes de publicar uma biblioteca combinada. A publicação de uma biblioteca combinada é semelhante à de uma biblioteca Android, mas há algumas diferenças importantes que você precisa considerar para publicar a biblioteca combinada corretamente:
- O plug-in Maven Publish também precisa ser aplicado a qualquer módulo que tenha o plug-in Fused Library aplicado.
- A publicação precisa herdar de
fusedLibraryComponentporque isso fornece as dependências necessárias para compilar o artefato da biblioteca combinada.
Veja um exemplo de configuração de publicações:
Kotlin
plugins { alias(libs.plugins.android.fusedlibrary) `maven-publish` } androidFusedLibrary { … } dependencies { … } publishing { publications { register<MavenPublication>("release") { groupId = "my-company" artifactId = "my-fused-library" version = "1.0" from(components["fusedLibraryComponent"]) } } }
Groovy
plugins { id 'com.android.fused-library' id 'maven-publish' } androidFusedLibrary { … } dependencies { … } publishing { publications { release(MavenPublication) { groupId = "my-company" artifactId = "my-fused-library" version = "1.0" afterEvaluate { from components.fusedLibraryComponent } } }
Publicar a biblioteca combinada para teste
Teste dependendo de uma biblioteca combinada publicada de um app Android ou uma biblioteca Android. O método recomendado é publicar a biblioteca combinada e as dependências do projeto em um repositório Maven local.
Para publicar os artefatos da biblioteca combinada em um repositório local, defina uma configuração semelhante a esta:
Kotlin
plugins { alias(libs.plugins.android.fusedlibrary) `maven-publish` } repositories { maven { name = "myLocalRepo" url = uri(layout.buildDirectory.dir("myLocalRepo")) } }
Groovy
plugins { id 'com.android.fused-library' id 'maven-publish' } repositories { maven { name 'myLocalRepo' url layout.buildDirectory.dir('myLocalRepo') } }
Fazer upload da biblioteca combinada
Para distribuir sua biblioteca combinada, consulte Fazer upload da biblioteca.
Comportamento e proteções
A combinação de bibliotecas do Android tem complexidades que podem dificultar a definição de prioridades pelo plug-in. Por exemplo, duas bibliotecas com o mesmo classpath vão causar uma falha de build ao serem combinadas. A mesclagem de recursos vai considerar a ordem das dependências especificadas ao selecionar um recurso com o mesmo nome em bibliotecas diferentes.
- As bibliotecas combinadas só podem ser publicadas como um artefato de biblioteca do Android (AAR) para serem adicionadas como uma dependência.
- Não é possível fundir bibliotecas que usam vinculação de dados.
- Não é possível combinar vários tipos de build e variações de produtos em uma única biblioteca combinada. Crie bibliotecas combinadas separadas para variantes diferentes.
Para equilibrar a quantidade de configuração necessária e a facilidade de uso, o plug-in vai falhar no build em conflitos ambíguos ou usar heurísticas ao mesclar artefatos. Os detalhes de como os artefatos são combinados estão na tabela a seguir:
| Tipo | Comportamento |
|---|---|
| Classes | As bibliotecas com o mesmo caminho de classe vão causar uma falha de build ao serem combinadas. |
| Recursos para Android | A mesclagem de recursos vai considerar a ordem das dependências especificadas ao selecionar um recurso com o mesmo nome em diferentes. |
| Metadados de AAR | As versões de metadados de arquivos AAR são mescladas priorizando o valor mais alto de cada biblioteca de dependência. Há uma DSL fornecida para substituir esses valores. Kotlin androidFusedLibrary { aarMetadata { minCompileSdk = 21 minCompileSdkExtension = 1 } } |
| Recursos Java | Não é permitido ter arquivos de recursos Java em várias bibliotecas com caminhos idênticos, o que vai resultar em uma falha de build. |
Problemas conhecidos
A biblioteca combinada é um novo plug-in, e há problemas conhecidos que estão sendo resolvidos para atender a todos os casos de uso. Você pode informar bugs para qualquer problema que encontrar.
- Problema nº 454305444: bibliotecas que contêm regras do ProGuard do consumidor que não são chamadas de "proguard.txt" resultam em uma falha de build. Corrigido no AGP 9.1 e versões mais recentes.
- Problema 374982739: adição de dependências de arquivos em outros arquivos .aar
- Problema nº 231433225: não há suporte para a fusão de artefatos do RenderScript e do Prefab.
Entender as dependências de uma biblioteca combinada
A biblioteca combinada não tem fontes e usa as bibliotecas do Android
como única fonte. Por isso, é importante entender de onde vem cada elemento. Para listar
as dependências que são mescladas no artefato resultante e as
dependências necessárias para criar o artefato, execute a tarefa gradle :report na
biblioteca combinada. A tarefa gera um relatório JSON que é salvo no diretório
build/reports da biblioteca combinada.
Para mais informações sobre dependências de plug-ins internos, execute a tarefa gradle :dependencies para conferir o estado das configurações de plug-ins.