Adicionar dependências de compilação

O sistema de build do Gradle no Android Studio permite incluir binários externos ou outros módulos de biblioteca no build como dependências. As dependências podem estar localizadas na sua máquina ou em um repositório remoto. Todas as dependências transitivas declaradas também serão automaticamente incluídas. Esta página descreve como usar dependências com um projeto do Android, incluindo detalhes sobre comportamentos e configurações específicos do Plug-in do Android para Gradle (AGP). Para orientações conceituais mais detalhadas sobre as dependências do Gradle, consulte também o Guia do Gradle para gerenciamento de dependências (link em inglês). No entanto, não esqueça que o projeto do Android precisa usar apenas as configurações de dependência definidas nesta página.

Cuidado: ao especificar as dependências, não use números de versão dinâmica, como 'com.android.tools.build:gradle:3.+'. O uso desse recurso pode causar atualizações inesperadas, dificuldade para resolver diferenças de versão e baixa performance.

Adicionar uma biblioteca ou dependência de plug-in

A melhor maneira de adicionar e gerenciar dependências de build é usar catálogos de versões, o método usado por novos projetos por padrão. Esta seção aborda os tipos mais comuns de configurações usadas para projetos Android. Consulte a documentação do Gradle para mais opções. Para conferir um exemplo de app que usa catálogos de versões, consulte Now in Android (em inglês). Se você já tem dependências de build configuradas sem catálogos de versões e um projeto com vários módulos, recomendamos migrar.

Para orientações sobre como adicionar e gerenciar dependências nativas (não comuns), consulte Dependências nativas.

No exemplo a seguir, adicionamos uma dependência binária remota (a biblioteca Macrobenchmark do Jetpack), a dependência do módulo de biblioteca local (myLibrary) e uma dependência de plug-in (o Plug-in do Android para Gradle) ao projeto. Confira as etapas gerais para adicionar essas dependências ao projeto:

Observação: é possível declarar catálogos de versões no arquivo de configurações, mas recomendamos usar um arquivo toml separado para receber mais suporte com sugestões de código e destaques do Android Studio.

1. Adicione um alias para a versão da dependência que você quer na seção [versions] do arquivo de catálogo de versões, chamado libs.versions.toml (no diretório gradle na visualização Project ou Gradle Scripts na visualização Android):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Os alias podem incluir traços ou sublinhados. Esses aliases geram valores aninhados que podem ser referenciados em scripts de build. As referências começam com o nome do catálogo, a parte libs de libs.versions.toml. Ao usar um único catálogo de versões, recomendamos manter o valor padrão de "libs".

2. Adicione um alias para a dependência nas seções [libraries] (para binários remotos ou módulos de biblioteca locais) ou [plugins] (para plug-ins) do arquivo libs.versions.toml.

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Algumas bibliotecas estão disponíveis em uma lista de materiais (BOM) publicada que agrupa famílias de bibliotecas e as versões delas. É possível incluir uma BoM no catálogo de versões e nos arquivos de build e deixar que ela gerencie essas versões para você. Consulte Como usar a Lista de materiais para mais detalhes.

3. Adicione uma referência ao alias de dependência no script de build dos módulos que exigem a dependência. Converta os sublinhados e traços do alias em pontos ao fazer referência a ele em um script de build. Nosso script de build no nível do módulo ficaria assim:

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   As referências de plug-in incluem plugins após o nome do catálogo, e as referências de versão incluem versions após o nome do catálogo. As referências de versão são incomuns. Consulte Dependências com os mesmos números de versão para conferir exemplos de referências de versão. As referências de biblioteca não incluem um qualificador libraries. Portanto, não é possível usar versions ou plugins no início de um alias de biblioteca.

Configurar dependências

Dentro do bloco dependencies, você pode declarar uma dependência de biblioteca usando uma das várias configurações de dependência diferentes (como implementation, mostrada anteriormente). Cada configuração de dependência fornece ao Gradle instruções diferentes sobre como usar a dependência. A tabela a seguir descreve cada uma das configurações que podem ser usadas para uma dependência em um projeto do Android.

Configuração	Comportamento
implementation	O Gradle adiciona a dependência ao caminho de classe de compilação e empacota a dependência no resultado do build. Quando o módulo configura uma dependência implementation, isso informa ao Gradle que você não quer que o módulo vaze a dependência para outros módulos no tempo de compilação. Ou seja, a dependência não é disponibilizada para outros módulos que dependem do módulo atual. O uso dessa configuração de dependência em vez de api pode resultar em melhorias significativas no tempo de build, porque reduz o número de módulos que o sistema de build precisa recompilar. Por exemplo, se uma dependência implementation mudar a API, o Gradle recompilará apenas essa dependência e os módulos que dependem diretamente dela. A maioria dos módulos de teste e apps precisa usar essa configuração.
api	O Gradle adiciona a dependência ao caminho de classe de compilação e ao resultado do build. Quando um módulo inclui uma dependência api, informa ao Gradle que quer exportá-la de forma transitiva para outros módulos para que ela fique disponível a eles durante a execução e a compilação. Use essa configuração com cuidado e somente com dependências que você precisa exportar de modo transitivo para outros clientes upstream. Se uma dependência api mudar a API externa, o Gradle recompilará todos os módulos que têm acesso a ela no momento da compilação. A existência de um grande número de dependências api pode aumentar consideravelmente o tempo de build. A menos que você queira expor a API de uma dependência a um módulo separado, os módulos de biblioteca precisam usar dependências implementation.
compileOnly	O Gradle adiciona a dependência somente ao caminho de classe, ou seja, a dependência não é adicionada ao resultado do build. Isso é útil quando você está criando um módulo do Android e precisa da dependência durante a compilação, mas a presença dela durante a execução é opcional. Por exemplo, se você depende de uma biblioteca que inclui apenas anotações de tempo de compilação, normalmente usadas para gerar código, mas que muitas vezes não são incluídas na saída do build, você pode marcar essa biblioteca como compileOnly. Se você usar essa configuração, o módulo de biblioteca vai ter que incluir uma condição de execução para verificar se a dependência está disponível. Se a resposta for negativa, o comportamento do módulo deverá ser modificado de forma controlada para continuar funcionando. Isso ajuda a reduzir o tamanho do app final, evitando a adição de dependências transitórias não essenciais. Observação:não é possível usar a configuração compileOnly com dependências do Arquivo do Android (AAR).
runtimeOnly	O Gradle adiciona a dependência apenas à saída de build, para uso durante o tempo de execução. Ou seja, ele não é adicionado ao caminho de classe de compilação. Ele raramente é usado no Android, mas é usado com frequência em aplicativos de servidor para fornecer implementações de geração de registros. Por exemplo, uma biblioteca pode usar uma API de registro que não inclui uma implementação. Os consumidores dessa biblioteca podem adicioná-la como uma dependência implementation e incluir uma dependência runtimeOnly para que a implementação de registro real seja usada.
ksp kapt annotationProcessor	Essas configurações fornecem bibliotecas que processam anotações e outros símbolos no código antes da compilação. Elas normalmente validam seu código ou geram código adicional, reduzindo o código que você precisa escrever. Para adicionar essa dependência, ela precisa ser adicionada ao caminho de classe do processador de anotações usando as configurações ksp, kapt ou annotationProcessor. O uso dessas configurações melhora o desempenho do build, separando o caminho de classe da compilação do caminho de classe do processador de anotações. Se o Gradle encontrar processadores de anotações no caminho de classe da compilação, ele desativará a evasão de compilação, o que afeta negativamente o tempo de build. O Gradle 5.0 e versões mais recentes ignoram os processadores de anotações encontrados no caminho de classe da compilação. O Plug-in do Android para Gradle entende que uma dependência é um processador de anotações quando o arquivo JAR contém o seguinte arquivo: META-INF/services/javax.annotation.processing.Processor Se o plug-in detecta que há um processador de anotações no caminho de classe da compilação, ele gera um erro de build. ksp é um processador de símbolos do Kotlin e é executado pelo compilador Kotlin. kapt e apt são ferramentas separadas que processam anotações antes da execução dos compiladores Kotlin ou Java. Ao decidir qual configuração usar, considere o seguinte: Se um processador estiver disponível como um processador de símbolo Kotlin, use-o como uma dependência ksp. Consulte Migrar do kapt para o ksp (link em inglês) para ver detalhes sobre o uso de processadores de símbolo Kotlin. Se o processador não estiver disponível como um processador de símbolos Kotlin: Se o projeto incluir a origem Kotlin (mas também puder incluir a origem Java), use kapt para incluí-la. Se o projeto usa apenas a origem Java, use annotationProcessor para incluí-la. Para saber mais sobre o uso de processadores de anotações, consulte Adicionar processadores de anotações.
lintChecks	Use essa configuração para incluir uma biblioteca contendo verificações de lint que você quer que o Gradle execute ao criar seu projeto de app Android. Os AARs que contêm um arquivo lint.jar executam automaticamente as verificações definidas nesse arquivo lint.jar. Não é necessário adicionar uma dependência lintChecks explícita. Isso permite definir bibliotecas e verificações de lint associadas em uma única dependência, garantindo que suas verificações sejam executadas quando os consumidores usarem a biblioteca.
lintPublish	Use essa configuração em projetos de biblioteca do Android para incluir verificações de lint que você quer que o Gradle compile em um arquivo lint.jar e empacote no seu AAR. Isso faz com que os projetos que consomem seu AAR também apliquem essas verificações de lint. Se você estava usando a configuração de dependência lintChecks anteriormente para incluir verificações de lint no AAR publicado, precisa migrar essas dependências para usar a nova configuração lintPublish descrita abaixo. Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovy dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Configurar dependências para uma variante de build específica

Todas as configurações anteriores aplicam dependências a todas as variantes de build. Se você quiser declarar uma dependência apenas para um conjunto de origem de uma variante de build específica ou para um conjunto de origem de teste, use inicial maiúscula no nome da configuração e adicione o prefixo do nome da variante de build ou do conjunto de origem de teste.

Por exemplo, para adicionar uma dependência binária remota apenas à variação de produto "free" usando a configuração implementation, use o seguinte:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

No entanto, se você quiser adicionar uma dependência para uma variante que combine uma variação de produto e um tipo de build, inicialize o nome da configuração:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Para adicionar a dependência implementation para testes locais e instrumentados, o código é semelhante a:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

No entanto, algumas configurações não fazem sentido nessa situação. Por exemplo, como outros módulos não podem depender de androidTest, você receberá o seguinte aviso se usar a configuração androidTestApi:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Ordem de dependências

A ordem em que as dependências são listadas indica a prioridade de cada uma: a primeira biblioteca tem maior prioridade que a segunda, a segunda tem maior prioridade que a terceira e assim por diante. Essa ordem é importante quando recursos são integrados ou elementos do manifesto são mesclados ao app a partir das bibliotecas.

Por exemplo, se o projeto declarar:

• A dependência de LIB_A e LIB_B (nessa ordem)
• E LIB_A depende de LIB_C e LIB_D (nessa ordem)
• E LIB_B também depende de LIB_C

A ordem de dependência combinada será a seguinte:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Isso garante que LIB_A e LIB_B possam substituir LIB_C. LIB_D mantém a prioridade maior que LIB_B porque LIB_A (que depende dele) tem prioridade maior que LIB_B.

Para saber mais sobre como manifestos de diferentes origens/dependências do projeto são integrados, consulte Integrar vários arquivos de manifesto.

Informações de dependência do Play Console

Ao criar o app, o AGP inclui metadados que descrevem as dependências de biblioteca compiladas no app. Durante o upload do app, o Play Console inspeciona esses metadados para fornecer alertas de problemas conhecidos com SDKs e dependências que o app usa e, em alguns casos, fornece feedback útil para resolver esses problemas.

Os dados são compactados, criptografados por uma chave de assinatura do Google Play e armazenados no bloco de assinatura do app de lançamento. Recomendamos manter esse arquivo de dependências para uma experiência do usuário segura e positiva. Para desativar isso, inclua o bloco dependenciesInfo no arquivo build.gradle.kts do módulo.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Para mais informações sobre nossas políticas e possíveis problemas com dependências, consulte nossa página de suporte sobre como usar SDKs de terceiros no seu app.

Insights do SDK

O Android Studio mostra avisos de lint no arquivo de catálogo de versões e na caixa de diálogo Project Structure para SDKs públicos no SDK Index do Google Play quando os seguintes problemas se aplicam:

• Os SDKs são marcados como desatualizados pelos autores.
• Os SDKs violam as políticas do Google Play.

Os avisos são indicadores de que você precisa atualizar essas dependências, porque o uso de versões desatualizadas pode impedir que você publique no Google Play Console no futuro.

Adicionar dependências de build sem catálogos de versões

Recomendamos o uso de catálogos de versões para adicionar e gerenciar dependências, mas projetos simples podem não precisar deles. Confira um exemplo de arquivo de build que não usa catálogos de versões:

Kotlin

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

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

Esse arquivo de build declara uma dependência da versão 12.3 da biblioteca "app-magic", dentro do grupo de namespace "com.example.android". A declaração de dependência binária remota é uma abreviação do seguinte:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

O arquivo de build também declara uma dependência em um módulo de biblioteca do Android chamado "mylibrary". Esse nome precisa corresponder ao nome da biblioteca definido com include: no arquivo settings.gradle.kts. Quando você cria o app, o sistema compila o módulo de biblioteca e empacota o conteúdo compilado resultante no app.

O arquivo de build também declara uma dependência no Plug-in do Android para Gradle (com.application.android). Se você tiver vários módulos que usam o mesmo plug-in, só poderá ter uma única versão do plug-in no caminho de classe do build em todos os módulos. Em vez de especificar a versão em cada um dos scripts de build do módulo, inclua a dependência do plug-in no script de build raiz com a versão e indique que ela não será aplicada. A adição de apply false informa ao Gradle a versão do plug-in, mas não o usa no build raiz. Normalmente, o script de build raiz fica vazio, exceto este bloco plugins.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Se você tiver um projeto de módulo único, poderá especificar a versão explicitamente no script de build do módulo e deixar o script de build do projeto vazio:

Kotlin

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

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}