O sistema de build do Gradle no Android Studio permite incluir ou outros módulos de biblioteca ao seu 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 seu projeto Android, incluindo: detalhes sobre comportamentos e configurações específicos o 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.
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 que os novos projetos usam por padrão. Nesta seção, abordamos os casos mais comuns tipos de configurações usadas para projetos Android; consulte o Documentação do Gradle (em inglês) para mais opções. Para conferir um exemplo de app que usa catálogos de versões, consulte Agora no Android. Se você já configurou as dependências de build sem catálogos de versões e tiver 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 um binário remoto
dependência (a biblioteca Jetpack Macrobenchmark
biblioteca), módulo de biblioteca local
uma dependência (myLibrary
) e um plug-in
(o Plug-in do Android para Gradle) ao nosso projeto. Estas são as
etapas para adicionar essas dependências ao projeto:
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, chamadalibs.versions.toml
(no diretóriogradle
no 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 aliases podem incluir traços ou sublinhados. Esses aliases geram valores aninhados que podem ser referenciados nos scripts de build. As referências começam com o nome catálogo, a parte
libs
delibs.versions.toml
. Quando usando um único catálogo de versões, recomendamos manter o valor padrão de “libs”.Adicione um alias para a dependência no
[libraries]
(para binários remotos ou módulos de biblioteca locais) ou[plugins]
(para plug-ins) do arquivolibs.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, na sigla em inglês) publicada que grupos de bibliotecas e suas versões. Você pode incluir uma BoM no seu catálogo de versões e arquivos de build, além de gerenciar essas versões para você. Consulte Como usar a Lista de materiais para mais detalhes.
Adicione uma referência ao alias de dependência para o script de compilação da módulos que exigem a dependência. Converter o alias sublinhados e traços para pontos quando você se refere a ele em um script de compilação. Nosso script de build 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-ins incluem
plugins
após o nome do catálogo. as referências de versão incluemversions
após o nome do catálogo (versão as referências são incomuns; consulte Dependências com os mesmos números de versão para conferir exemplos de referências de versão. Biblioteca referências não incluem um qualificadorlibraries
, então não é possível usarversions
ouplugins
no início de uma biblioteca alias.
Configurar dependências
No bloco dependencies
, é possível declarar uma dependência de biblioteca usando uma
de várias configurações de dependência diferentes (como implementation
mostrado
antes). 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 seu
configura uma dependência implementation , é
informando ao Gradle que você não quer que o módulo vaze a
dependência de outros módulos em tempo de compilação. Ou seja, a dependência
não é disponibilizado para outros módulos que dependem da configuração
mais tarde neste módulo.
Usar essa configuração de dependência em vez de
|
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 , ela é
informando ao Gradle que o módulo quer exportar de forma transitiva
essa dependência a outros módulos, para que fique disponível a eles em
tanto o tempo de execução quanto o de compilação.
Use essa configuração com cuidado e somente com dependências que
você precisa exportar de modo transitivo para outros consumidores upstream. Se um
A dependência |
compileOnly |
O Gradle adiciona a dependência apenas ao caminho de classe de compilação.
Ou seja, os dados não são adicionados à saída 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. Para
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 geralmente não incluídas na saída do build, é possível 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 |
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 servidores
aplicativos para fornecer implementações de geração de registros. Por exemplo,
pode usar uma API Logging que não inclui uma
implementação. Os consumidores dessa biblioteca podem adicioná-la
implementation e incluem um
Dependência runtimeOnly para a geração de registros real
implementação usar.
|
ksp |
Essas configurações fornecem bibliotecas que processam anotações e outros símbolos no código antes que ele seja compilado. Eles normalmente validar ou gerar 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 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:
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. O
Ao decidir qual configuração usar, considere as seguinte:
Para mais informações sobre o uso de processadores de anotações, consulte Adicione processadores de anotações. |
lintChecks |
Use essa configuração para incluir uma biblioteca que contenha lint verificações que você quer que o Gradle execute ao criar seu app Android. projeto. Os AARs que contêm um arquivo |
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.
Kotlindependencies { // 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")) } Groovydependencies { // 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 Em vez disso, declare uma dependência somente para um build específico de variante ou uma origem de teste definida, use letras maiúsculas no nome da configuração e adicione um prefixo com o nome da variante de build ou do conjunto de origem de teste.
Por exemplo, para adicionar uma dependência binária remota apenas aos arquivos "free" produto
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 combina um produto variação 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.5.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.5.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
eLIB_B
(nessa ordem) - E
LIB_A
depende deLIB_C
eLIB_D
(nessa ordem) - E
LIB_B
também depende deLIB_C
A ordem de dependência combinada será a seguinte:
LIB_A
LIB_D
LIB_B
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 a biblioteca. dependências que são compiladas no app. Ao fazer upload do seu app, o Play O console inspeciona esses metadados para fornecer alertas sobre problemas conhecidos com SDKs e dependências que seu aplicativo usa e, em alguns casos, fornecer feedback útil para resolver esses problemas.
Os dados são compactados, criptografados por uma chave de assinatura do Google Play e armazenados
o bloco de assinatura do app de lançamento. Recomendamos manter essas dependências
para uma experiência do usuário segura e positiva. Para desativar, inclua o
seguindo
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 no arquivo Project Caixa de diálogo "Estrutura" para SDKs públicos no O SDK Index do Google Play quando os seguintes problemas se aplicarem:
- Os SDKs são marcados como desatualizados pelos autores.
- Os SDKs violam as políticas do Google Play.
Os avisos indicam que você precisa atualizar essas dependências, porque o uso de versões desatualizadas pode impedir a publicação no Google Play 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 ou projetos podem não precisar deles. Este é um exemplo de um 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') }
Este arquivo de build declara uma dependência na versão 12.3 da versão "app-magic" dentro de "com.example.android" um grupo de namespaces. O binário remoto declaração de dependência é uma abreviação para o 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 por um include:
no
seu arquivo settings.gradle.kts
. Quando você cria seu app, o sistema de build
compila o módulo de biblioteca e empacota o conteúdo compilado resultante na
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 a mesma
só pode ter uma 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 módulo
scripts de build, inclua a dependência do plug-in no script de build raiz
com a versão e indicar para não aplicá-la. Adicionar apply false
informa
O Gradle anotará a versão do plug-in, mas não a usará 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ê tem um projeto de módulo único, pode especificar a versão explicitamente em o script de build do módulo e deixe o script de build do nível do projeto vazio:
Kotlin
plugins { id("com.android.application") version "8.3.0" }
Groovy
plugins { id 'com.android.application' version '8.3.0-rc02' }