Criar uma biblioteca Android

Estruturalmente, uma biblioteca Android é igual a um módulo de app Android. Ela inclui tudo o que é necessário para criar um app, inclusive código-fonte, arquivos de recursos e um manifesto do Android.

No entanto, em vez de ser compilada em um APK para execução em um dispositivo, uma biblioteca Android é compilada em um arquivo ARchive do Android (AAR), que pode ser usado como dependência de um módulo de app Android. Ao contrário dos arquivos JAR, os arquivos AAR oferecem as funcionalidades abaixo para apps Android:

  • Os arquivos AAR podem conter recursos Android e um arquivo de manifesto, o que permite empacotar recursos compartilhados como layouts e drawables, além de classes e métodos do Kotlin ou Java.
  • Os arquivos AAR podem conter bibliotecas C/C++ para serem usadas pelo código C/C++ do módulo do app.

Um módulo de biblioteca é útil nestas situações:

  • Ao criar vários aplicativos que usam alguns componentes em comum, como atividades, serviços ou layouts de interface.
  • Ao criar um app com diversas variações de APK, como uma versão sem custos ou paga, que compartilham os principais componentes.

Nos dois casos, mova os arquivos que você quer reutilizar para um módulo de biblioteca e os adicione como dependência para cada módulo de app.

Esta página explica como criar e usar um módulo de biblioteca do Android. Para orientações sobre como publicar uma biblioteca, consulte Publicar a biblioteca

Criar um módulo de biblioteca

Para criar um novo módulo de biblioteca no projeto, faça o seguinte:

  1. Clique em File > New > New Module.
  2. Na caixa de diálogo Create New Module que aparecer, clique em Android Library e em Next.

    Há também uma opção para criar uma biblioteca Kotlin ou Java, que cria um arquivo JAR tradicional. Embora um arquivo JAR seja útil para muitos projetos, principalmente quando você quer compartilhar código com outras plataformas, ele não permite que você inclua recursos do Android ou arquivos de manifesto do Android, que são muito úteis para a reutilização de códigos em projetos Android. Este guia se concentra na criação de bibliotecas Android.

  3. Atribua um nome à biblioteca, selecione uma versão mínima do SDK para o código na biblioteca e clique em Finish.

Quando a sincronização do projeto do Gradle é concluída, o módulo de biblioteca aparece no painel Project. Se a pasta do novo módulo não aparecer, verifique se o painel está mostrando a visualização Android.

Converter um módulo de aplicativo em um módulo de biblioteca

Se você tem um módulo de app com todo o código que quer reutilizar, pode transformá-lo em um módulo de biblioteca desta forma:

  1. Abra o arquivo build.gradle de nível de módulo, se estiver usando o Groovy, ou o arquivo build.gradle.kts, se estiver usando o script Kotlin.
  2. Exclua a linha do applicationId. Apenas um módulo de app Android pode definir isso.
  3. Encontre o bloco "plugins" na parte de cima do arquivo, que tem esta aparência:

    Groovy

      plugins {
      id 'com.android.application'
  }

    Kotlin

      plugins {
      id("com.android.application")
  }

    Altere para o seguinte:

    Groovy

      plugins {
      id 'com.android.library'
  }

    Kotlin

      plugins {
      id("com.android.library")
  }
  4. Salve o arquivo e clique em File > Sync Project with Gradle Files.

A estrutura do módulo continua a mesma, mas agora funciona como uma biblioteca Android. O build cria um arquivo AAR em vez de um APK.

Para criar um arquivo AAR, selecione o módulo da biblioteca na janela Project e clique em Build > Build APK.

Adicionar dependências com a caixa de diálogo "Project Structure"

Use a caixa de diálogo Project Structure para adicionar dependências ao projeto. As seções abaixo descrevem como usar a caixa de diálogo para adicionar dependências.

Usar a biblioteca para o mesmo projeto

Para usar o código da nova biblioteca Android em outro módulo de app ou biblioteca no mesmo projeto, adicione uma dependência no projeto:

  1. Navegue até File > Project Structure > Dependencies.
  2. Selecione o módulo a que você quer adicionar a biblioteca.
  3. Na guia Declared Dependencies, clique em e selecione Module Dependency no menu.

  4. Na caixa de diálogo Add Module Dependency, selecione o módulo da sua biblioteca.

    Adicionar uma dependência de módulo na caixa de diálogo Project Structure

  5. Selecione a configuração que exige essa dependência ou escolha implementation, caso ela seja necessária para todas as configurações, e clique em OK.

O Android Studio edita o arquivo build.gradle ou build.gradle.kts do módulo para adicionar a dependência desta forma:

Groovy

  implementation project(path: ":example-library")

Kotlin

  implementation(project(":example-library"))

Usar a biblioteca em outros projetos

A maneira recomendada de compartilhar dependências (JARs e AARs) é com um repositório Maven, hospedado em um serviço como o Maven Central (link em inglês) ou com uma estrutura de diretórios no disco local. Para mais informações sobre como usar os repositórios do Maven, consulte Repositórios remotos.

Quando uma biblioteca Android é publicada em um repositório Maven, os metadados são incluídos para que as dependências da biblioteca sejam incluídas no build consumido. Isso possibilita a eliminação automática da biblioteca duplicada, se ela for usada em vários lugares.

Para usar o código da biblioteca Android em outro módulo de app de um projeto diferente, faça o seguinte:

  1. Navegue até File > Project Structure > Dependencies.
  2. Na guia Declared Dependencies, clique em e selecione Library Dependency no menu.

  3. Na caixa de diálogo Add Library Dependency, use a caixa de pesquisa para encontrar a biblioteca a ser adicionada. O formulário pesquisa os repositórios especificados no bloco dependencyResolutionManagement { repositories {...}} do arquivo settings.gradle ou settings.gradle.kts.

    Adicionar uma dependência da biblioteca na caixa de diálogo "Project Structure"

  4. Selecione a configuração que exige essa dependência ou escolha implementation, caso ela seja necessária para todas as configurações, e clique em OK.

Verifique o arquivo build.gradle ou build.gradle.kts do app para confirmar se uma declaração semelhante a esta aparece (dependendo da configuração do build que você selecionou):

Groovy

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

  implementation("com.example:examplelibrary:1.0.0")

Adicionar AAR ou JAR como uma dependência

Para usar o código de uma biblioteca Android em outro módulo de app, faça o seguinte:

  1. Navegue até File > Project Structure > Dependencies.
  2. Na guia Declared Dependencies, clique em e selecione Jar Dependency no menu.

  3. Na caixa de diálogo Add Jar/Aar Dependency, insira o caminho para o arquivo AAR ou JAR e selecione a configuração a que a dependência se aplica. Se a biblioteca estiver disponível para todas as configurações, selecione a configuração implementation.

    Adicionar dependências AAR na caixa de diálogo "Project Structure"

    Verifique o arquivo build.gradle ou build.gradle.kts do app para confirmar se uma declaração semelhante a esta aparece (dependendo da configuração do build que você selecionou):

    Groovy

      implementation files('my_path/my_lib.aar')

    Kotlin

      implementation(files("my_path/my_lib.aar"))

Para importar uma dependência no build do Gradle em execução fora do Android Studio, adicione um caminho à dependência no arquivo build.gradle ou build.gradle.kts do seu app. Exemplo:

Groovy

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

Kotlin

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

Para conferir mais informações sobre como adicionar dependências do Gradle, consulte Adicionar dependências de build.

Declarar um recurso público

Os recursos incluem todos os arquivos do diretório res/ do projeto, por exemplo, imagens. Por padrão, todos os recursos de uma biblioteca são públicos. Para tornar todos os recursos implicitamente privados, é necessário definir pelo menos um atributo específico como público.

Para declarar um recurso público, adicione uma declaração <public> ao arquivo public.xml da biblioteca. Se você não tiver adicionado recursos públicos antes, crie o arquivo public.xml no diretório res/values/ da biblioteca.

O código de exemplo abaixo cria dois recursos públicos de string com os nomes mylib_app_name e mylib_public_string:

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

Para evitar que os usuários da biblioteca acessem recursos destinados exclusivamente a uso interno, utilize esse mecanismo automático de designação de privacidade declarando um ou mais recursos públicos. Como alternativa, torne todos os recursos privados, adicionando uma tag <public /> vazia. Isso não marca nada como público e torna todos os recursos privados.

Todos os recursos que você quer que continuem visíveis para os desenvolvedores que usam sua biblioteca precisam ser públicos.

Tornar os atributos públicos de forma implícita impede que os usuários da biblioteca recebam sugestões de preenchimento de código dos recursos internos da biblioteca e permite que eles renomeiem ou removam recursos privados sem corromper os clientes da biblioteca. Os recursos privados são filtrados no preenchimento de código, e a ferramenta Lint emite um alerta quando você tenta fazer uma referência a um recurso privado.

Ao criar uma biblioteca, o Plug-in do Android para Gradle extrai as definições de recursos públicos no arquivo public.txt, que, depois disso, é empacotado dentro do arquivo AAR.

Considerações de desenvolvimento de módulos de biblioteca

Esteja ciente dos comportamentos e limitações abaixo ao desenvolver módulos de biblioteca e apps dependentes.

  • As bibliotecas são mescladas em ordem de prioridade.

    Depois de adicionar referências a módulos de biblioteca ao módulo do app Android, você pode definir a prioridade relativa. Durante o build, as bibliotecas são mescladas com o app, uma de cada vez, começando pela biblioteca de menor prioridade até a de maior prioridade.

  • Evite conflitos de mesclagem de recursos.

    As ferramentas de build mesclam recursos de um módulo de biblioteca com os de um módulo de app dependente. Se um determinado ID de recurso for definido nos dois módulos, o recurso do app vai ser usado.

    Se ocorrem conflitos entre várias bibliotecas AAR, o recurso usado será o da biblioteca listada primeiro na lista de dependências (perto da parte de cima do bloco dependencies).

    Para evitar conflitos de recursos, use classes R não transitivas. Se isso não for possível, experimente usar um prefixo ou outro esquema de nomenclatura consistente exclusivo para o módulo (ou exclusivo em todos os módulos do projeto).

  • Em builds multimódulo, as dependências JAR são tratadas como dependências transitivas.

    Quando você adiciona uma dependência JAR a um projeto de biblioteca que gera um AAR, o JAR é processado pelo módulo da biblioteca e empacotado com o AAR correspondente.

    No entanto, caso seu projeto inclua um módulo de biblioteca consumido por um módulo de app, o módulo vai tratar a dependência JAR local de biblioteca como uma dependência transitiva. Nesse caso, o JAR local é processado pelo app do módulo que o consome, não pelo módulo da biblioteca. Isso acelera builds incrementais causados por mudanças no código de uma biblioteca.

    Qualquer conflito de recursos Java causado por dependências JAR locais precisa ser resolvido no módulo do app que consome a biblioteca.

  • Um módulo de biblioteca pode depender de uma biblioteca JAR externa.

    É possível desenvolver um módulo de biblioteca que depende de uma biblioteca externa Nesse caso, o módulo dependente precisa ser criado em um destino que inclua a biblioteca externa.

    Observe que o módulo de biblioteca e o app dependente precisam declarar a biblioteca externa em um elemento <uses-library> dos arquivos de manifesto deles.

  • O atributo minSdkVersion do módulo do app precisa ser igual ou maior que a versão definida pela biblioteca.

    Uma biblioteca é compilada como parte do módulo do app dependente, portanto, as APIs usadas no módulo da biblioteca precisam ser compatíveis com a versão de plataforma que recebe suporte do módulo do app.

  • Cada módulo de biblioteca cria a própria classe R.

    Ao criar os módulos de apps dependentes, os módulos de biblioteca são compilados em um arquivo AAR, que é adicionado ao módulo do app. Portanto, cada biblioteca tem a própria classe R, nomeada de acordo com o nome do pacote da biblioteca.

    A classe R gerada no módulo principal e no módulo de biblioteca é criada em todos os pacotes necessários, incluindo o pacote do módulo principal e os pacotes das bibliotecas.

  • Um módulo de biblioteca pode incluir um arquivo de configuração do ProGuard próprio.

    Se você tiver um projeto de biblioteca usado para criar e publicar um AAR, poderá adicionar um arquivo de configuração do ProGuard à configuração de build da sua biblioteca. Se você fizer isso, o Plug-in do Android para Gradle vai aplicar as regras do ProGuard especificadas. As ferramentas de build incorporam esse arquivo no arquivo AAR gerado para o módulo de biblioteca. Ao adicionar a biblioteca a um módulo de app, o arquivo ProGuard da biblioteca é anexado ao arquivo de configuração do ProGuard (proguard.txt) do módulo do app.

    Incorporando um arquivo do ProGuard ao módulo de biblioteca, você garante que os módulos do app que dependem da biblioteca não precisam atualizar manualmente os arquivos do ProGuard para usar a biblioteca. Quando o sistema de build do Android Studio cria o app, ele usa as diretivas do módulo do app e da biblioteca. Não é necessário executar um redutor de código na biblioteca em uma etapa separada.

    Para adicionar as regras do ProGuard ao projeto da biblioteca, especifique o nome do arquivo com a propriedade consumerProguardFiles dentro do bloco defaultConfig do arquivo build.gradle ou build.gradle.kts da biblioteca.

    Por exemplo, o snippet abaixo define lib-proguard-rules.txt como o arquivo de configuração ProGuard da biblioteca:

    Groovy

    android {
    defaultConfig {
        consumerProguardFiles 'lib-proguard-rules.txt'
    }
    ...
}

    Kotlin

    android {
    defaultConfig {
        consumerProguardFiles("lib-proguard-rules.txt")
    }
    ...
}

    No entanto, se o módulo da biblioteca faz parte de um build multimódulo compilado em um APK e não gera um AAR, execute a redução de código apenas no módulo de app que consome a biblioteca. Para saber mais sobre as regras do ProGuard e o uso delas, leia Reduzir, ofuscar e otimizar o app.

  • Testar um módulo de biblioteca é muito parecido com testar um app.

    A principal diferença é que a biblioteca e as dependências dela são incluídas automaticamente como dependências do APK de teste. Isso quer dizer que o APK de teste não inclui apenas o próprio código, mas também o AAR da biblioteca e todas as dependências correspondentes. Como não há um app separado em teste, a tarefa androidTest instala (e desinstala) apenas o APK de teste.

    Ao mesclar vários arquivos de manifesto, o Gradle segue a ordem de prioridade padrão e mescla o manifesto da biblioteca com o manifesto principal do APK de teste.

Anatomia de um arquivo AAR

A extensão de um arquivo AAR é .aar, e o tipo de artefato Maven também é aar. O arquivo é um ZIP. A única entrada obrigatória é /AndroidManifest.xml.

Um arquivo AAR também pode incluir uma ou mais destas entradas opcionais: