lightbulb_outline Please take our October 2018 developer survey. Start survey

Criar uma biblioteca Android

Estruturalmente, uma biblioteca Android é igual a um módulo de aplicativo Android. Ela pode conter tudo o que é necessário para criar um aplicativo, inclusive código-fonte, arquivos de recursos e um manifesto do Android. No entanto, em vez de compilada em um APK para execução em um dispositivo, a biblioteca Android é compilada em um arquivo Android Archive (AAR) que pode ser usado como dependência de um módulo de aplicativo Android. Diferentemente dos arquivos JAR, 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 Java.

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

  • Ao compilar vários aplicativos que usam alguns componentes em comum, como atividades, serviços ou layouts de IU.
  • Ao compilar um aplicativo que existe em várias variações de APK, como uma versão gratuita e paga, e os mesmos componentes essenciais são necessários nas duas versões.

Nos dois casos, basta mover os arquivos a reutilizar para um módulo de biblioteca e adicioná-la como dependência para cada módulo de aplicativo. Esta página ensina a proceder nas duas situações.

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 janela exibida Create New Module, clique em Android Library e em Next.

    Existe também uma opção para criar uma biblioteca Java, que cria um arquivo JAR tradicional. Embora um arquivo JAR seja útil para muitos projetos, principalmente quando é necessário compartilhar código com outras plataformas, esse tipo de arquivo não permite a inclusão de recursos Android nem arquivos de manifesto, o que é muito útil para reutilização de código em projetos Android. Portanto, este guia se concentra na criação de bibliotecas Android.

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

Após a conclusão da sincronização do projeto Gradle, o módulo de biblioteca será exibido no painel Project à esquerda. Se a pasta do novo módulo não for exibida, verifique se a visualização do Android está sendo exibida.

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

Se você tiver um módulo de aplicativo com todo o código que quer reutilizar, poderá transformá-lo em um módulo de biblioteca da seguinte forma:

  1. Abra o arquivo build.gradle do módulo de aplicativo existente. Na parte superior, você verá o seguinte:
    apply plugin: 'com.android.application'
    
  2. Altere a atribuição de plug-in da seguinte forma:

    apply plugin: 'com.android.library'
    
  3. Clique em Sync Project with Gradle Files.

Pronto. A estrutura inteira do módulo se mantém, mas ele passa a operar como uma biblioteca Android e a compilação criará um arquivo AAR em vez de APK.

Adicionar uma biblioteca como dependência

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

  1. Adicione a biblioteca ao projeto usando um dos seguintes métodos (se você criou o módulo de biblioteca no mesmo projeto, a biblioteca já está no projeto e você pode ignorar esta etapa):
    • Adicione o arquivo AAR (ou JAR) compilado:
      1. Clique em File > New Module.
      2. Clique em Import .JAR/.AAR Package e em Next.
      3. Insira a localização do arquivo AAR ou JAR e clique em Finish.
    • Importe o módulo de biblioteca para o projeto:
      1. Clique em File > New > Import Module.
      2. Insira a localização do diretório do módulo de biblioteca e clique em Finish.

      O módulo de biblioteca é copiado para o projeto, portanto você pode até editar o código da biblioteca. Se você quiser manter uma única versão do código da biblioteca, provavelmente não é isso que você quer. Em vez disso, importe o arquivo AAR compilado como descrito acima.

  2. Verifique se a biblioteca é a primeira do arquivo settings.gradle, como mostrado abaixo para uma biblioteca denominada "my-library-module":
    include ':app', ':my-library-module'
    
  3. Abra o arquivo build.gradle do módulo de aplicativo e adicione uma nova linha ao bloco dependencies, como mostrado no snippet abaixo:
    dependencies {
        compile project(":my-library-module")
    }
    
  4. Clique em Sync Project with Gradle Files.

No exemplo acima, o módulo de biblioteca Android denominado my-library- module torna-se uma dependência de compilação para o módulo em que reside o arquivo build.gradle.

Todo o código e todos os recursos da biblioteca Android passam a estar disponíveis para o módulo de aplicativo e o arquivo AAR da biblioteca é empacotado com o APK durante a compilação.

No entanto, se você quiser compartilhar separadamente o arquivo AAR, poderá encontrá-lo em project-name/module-name/build/outputs/aar/ e gerá-lo novamente clicando em Build > Make Project.

Escolher os recursos que serão públicos

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. Os recursos incluem todos os arquivos no diretório res/ do projeto, como imagens. Para evitar que os usuários da biblioteca acessem recursos destinados exclusivamente para uso interno, use esse mecanismo automático de designação de privacidade declarando um ou mais recursos públicos.

Para declarar um recurso público, adicione uma declaração ao arquivo public.xml da biblioteca. Se você ainda não adicionou recursos públicos antes, é necessário criar o arquivo public.xml no diretório res/values/ da biblioteca.

O código de amostra a seguir 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>

Todos os recursos que devem ficar visíveis para os desenvolvedores que usam a biblioteca devem ser tornados públicos. Por exemplo: embora a maioria dos recursos na biblioteca appcompat v7 sejam privados, os atributos que controlam o widget Toolbar são públicos para manter a compatibilidade com o material design.

Além de evitar que os usuários da biblioteca vejam sugestões de conclusão de código dos recursos internos da biblioteca, os atributos tornados implicitamente privados também permitem renomear ou remover recursos privados sem afetar os clientes da biblioteca. Os recursos privados são filtrados da conclusão de código e do editor de temas, e o Lint emite um aviso quando você tenta fazer uma referência a um recurso privado.

Considerações de desenvolvimento

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

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

  • Conflitos de mesclagem de recursos

    As ferramentas de compilação mesclam recursos de um módulo de biblioteca com os de um módulo de aplicativo dependente. Se um determinado ID de recurso for definido nos dois módulos, será usado o recurso do aplicativo.

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

    Para evitar conflitos de recursos para IDs de recursos comuns, considere usar um prefixo ou outro esquema de nomenclatura consistente exclusivo para o módulo (ou exclusivo em todos os módulos do projeto).

  • Um módulo de biblioteca pode incluir uma biblioteca JAR

    Você pode desenvolver um módulo de biblioteca que inclui uma biblioteca JAR. No entanto, é preciso editar manualmente o caminho de compilação do módulo de aplicativo dependente e adicionar um caminho para o arquivo JAR.

  • 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 (por exemplo, a biblioteca externa Maps). Nesse caso, o aplicativo dependente deve ser compilado em um destino que inclua a biblioteca externa (por exemplo, o complemento Google APIs). Observe também que o módulo de biblioteca e o aplicativo dependente devem declarar a biblioteca externa em um elemento <uses- library> de seus arquivos de manifesto.

  • Módulos de biblioteca não podem incluir ativos brutos

    As ferramentas não permitem o uso de arquivos de ativos brutos (salvos no diretório assets/) em um módulo de biblioteca. Todos os recursos de ativos usados no aplicativo devem ser armazenados no diretório assets/ do próprio módulo de aplicativo.

  • O atributo minSdkVersion do módulo de aplicativo deve ser igual ou maior que a versão definida pela biblioteca

    Uma biblioteca é compilada como parte do módulo de aplicativo dependente, portanto as APIs usadas no módulo de biblioteca devem ser compatíveis com a versão de plataforma compatível com o módulo de aplicativo.

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

    Ao compilar os módulos de aplicativos dependentes, os módulos de biblioteca são compilados em um arquivo AAR, que é adicionado ao módulo de aplicativo. Portanto, cada biblioteca tem sua própria classe R, nomeada de acordo com o nome do pacote da biblioteca. A classe R gerada do módulo principal e o módulo de biblioteca são criados em todos os pacotes necessários, incluindo o pacote do módulo principal e os pacotes das bibliotecas.

  • Os módulos de biblioteca podem incluir seu próprio arquivo de configuração do ProGuard

    Você pode ativar a redução de código na biblioteca adicionando um arquivo de configuração do ProGuard à biblioteca, com suas diretivas do ProGuard. As ferramentas de compilação incorporam esse arquivo no arquivo AAR gerado para o módulo de biblioteca. Ao adicionar a biblioteca a um módulo de aplicativo, o arquivo ProGuard da biblioteca é anexado ao arquivo de configuração do ProGuard (proguard.txt) do módulo de aplicativo.

    A incorporação de um arquivo ProGuard no módulo de biblioteca garante que os módulos de aplicativos que dependem da biblioteca não precisem atualizar manualmente seus arquivos ProGuard para usar a biblioteca. Quando o ProGuard é executado no módulo de aplicativo Android, ele usa as diretivas do módulo de aplicativo e da biblioteca, portanto não execute o ProGuard apenas na biblioteca.

    Para especificar o nome do arquivo de configuração da biblioteca, adicione-o ao método consumerProguardFiles, dentro do bloco defaultConfig do arquivo build.gradle da biblioteca. Por exemplo, o snippet a seguir define lib-proguard-rules.txt como o arquivo de configuração do ProGuard da biblioteca:

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

    Por padrão, o módulo de aplicativo usa a compilação de lançamento da biblioteca, mesmo quando usa o tipo de compilação de depuração do módulo de aplicativo. Para usar um tipo de compilação diferente da biblioteca, é necessário adicionar dependências ao bloco dependencies do arquivo build.gradle do aplicativo e definir publishNonDefault como true no arquivo build.gradle da biblioteca. Por exemplo: o snippet de código a seguir no arquivo build.gradle do aplicativo faz com que este use o tipo de compilação de depuração da biblioteca quando o módulo de aplicativo é compilado no modo de depuração, e use o tipo de compilação de lançamento da biblioteca quando o módulo de aplicativo é compilado no modo de lançamento:

    dependencies {
        debugCompile project(path: ':library', configuration: 'debug')
        releaseCompile project(path: ':library', configuration: 'release')
    }
    

    Também é preciso adicionar a linha a seguir dentro do bloco android do arquivo build.gradle da biblioteca para expor as configurações da biblioteca que não são de lançamento para os projetos que as usam:

    android {
        ...
        publishNonDefault true
    }
    

    No entanto, observe que a definição de publishNonDefault pode aumentar os tempos de compilação.

    Para garantir que as regras do ProGuard da biblioteca não apliquem efeitos colaterais de redução aos módulos de aplicativos, inclua apenas as regras que desativam os recursos do ProGuard que não funcionam com a biblioteca. As regras que tentam ajudar desenvolvedores podem conflitar com o código existente em um módulo de aplicativo ou suas outras bibliotecas e, portanto, não devem ser incluídas. Por exemplo, o arquivo ProGuard da biblioteca pode especificar qual código precisa ser mantido durante a minificação de um módulo de aplicativo.

    Observação: a cadeia de ferramentas Jack é compatível com apenas algumas opções de redução e ofuscação do ProGuard.

Anatomia de um arquivo AAR

A extensão de arquivo de um arquivo AAR é .aar, e o tipo de artefato Maven também deve ser aar. O arquivo em si é um arquivo zip contendo estas entradas obrigatórias:

  • /AndroidManifest.xml
  • /classes.jar
  • /res/
  • /R.txt

Além disso, um arquivo AAR pode incluir uma ou mais destas entradas opcionais:

  • /assets/
  • /libs/name.jar
  • /jni/abi_name/name.so (onde abi_name é uma das ABIs compatíveis com o Android)
  • /proguard.txt
  • /lint.jar