Publicar várias bibliotecas do Android como uma com a biblioteca combinada

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.

  1. Anexe include(":myFusedLibrary") ao arquivo settings.gradle.kts.
  2. Adicione android-fusedlibrary = { id = "com.android.fused-library", version.ref = "agp" } na seção [plugins] do arquivo gradle/libs.versions.toml.
  3. Adicione alias(libs.plugins.android.fusedlibrary) apply false ao bloco de plug-ins no arquivo build.gradle.kts de nível superior.
  4. Para criar o módulo myFusedLibrary, crie um novo diretório chamado myFusedLibrary (clique com o botão direito do mouse em "My Application" > New > Directory).
  5. Crie um arquivo build.gradle.kts no módulo myFusedLibrary (clique com o botão direito do mouse no módulo myFusedLibrary > New > File).
  6. 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 fusedLibraryComponent porque 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.