Il sistema di compilazione Gradle in Android Studio ti consente di includere come dipendenze moduli di librerie o binari esterni alla compilazione. Le dipendenze possono trovarsi sulla tua macchina o in un repository remoto e tutte le dipendenze transitive che dichiarano vengono incluse automaticamente. Questa pagina descrive come utilizzare le dipendenze con il progetto Android, inclusi dettagli su comportamenti e configurazioni specifici del plug-in Android per Gradle (AGP). Per una guida concettuale più approfondita alle dipendenze Gradle, consulta anche la guida di Gradle per la gestione delle dipendenze, ma ricorda che il tuo progetto Android deve utilizzare solo le configurazioni delle dipendenze definite in questa pagina.
Aggiungi una dipendenza libreria o plug-in
Il modo migliore per aggiungere e gestire le dipendenze della build è usare i cataloghi delle versioni, il metodo predefinito utilizzato dai nuovi progetti. Questa sezione illustra i tipi più comuni di configurazione utilizzati per i progetti Android. Per ulteriori opzioni, consulta la documentazione di Gradle. Per un esempio di app che utilizza cataloghi delle versioni, vedi Ora in Android. Se hai già configurato dipendenze della build senza cataloghi delle versioni e hai un progetto a più moduli, ti consigliamo di eseguire la migrazione.
Per indicazioni su come aggiungere e gestire le dipendenze native (non comuni), consulta Dipendenze native.
Nell'esempio seguente, aggiungiamo al progetto una dipendenza da codice binario remoto (la libreria Jetpack Macrobenchmark), una dipendenza dal modulo della libreria locale (myLibrary
) e una dipendenza dal plug-in (il plug-in Android Gradle). Di seguito sono riportati i passaggi generali per aggiungere queste dipendenze al progetto:
Aggiungi un alias per la versione della dipendenza che ti interessa nella sezione
[versions]
del file di catalogo delle versioni, denominatalibs.versions.toml
(nella directorygradle
nella visualizzazione Progetto o Script Gradle nella visualizzazione Android):[versions] agp = "8.3.0" androidx-macro-benchmark = "1.2.2" my-library = "1.4" [libraries] ... [plugins] ...
Gli alias possono includere trattini o trattini bassi. Questi alias generano valori nidificati a cui puoi fare riferimento negli script di compilazione. I riferimenti iniziano con il nome del catalogo, la parte
libs
dilibs.versions.toml
. Se utilizzi un catalogo con una sola versione, consigliamo di mantenere il valore predefinito di "libs".Aggiungi un alias per la dipendenza nelle sezioni
[libraries]
(per i file binari remoti o i moduli della libreria locale) o[plugins]
(per i plug-in) del filelibs.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" }
Alcune librerie sono disponibili in una distinta dei materiali (BOM) pubblicata che raggruppa famiglie di librerie e le relative versioni. Puoi includere un BOM nel catalogo delle versioni e nei file di build e lasciare che sia l'autore a gestire tali versioni. Per maggiori dettagli, consulta Utilizzare la distinta componenti.
Aggiungi un riferimento all'alias della dipendenza allo script di compilazione dei moduli che richiedono la dipendenza. Converti i trattini bassi e i trattini dell'alias in punti quando fai riferimento all'alias da uno script di compilazione. Il nostro script di compilazione a livello di modulo dovrebbe avere il seguente aspetto:
Kotlin
plugins { alias(libs.plugins.androidApplication) } dependencies { implementation(libs.androidx.benchmark.macro) implementation(libs.my.library) }
Alla moda
plugins { alias 'libs.plugins.androidApplication' } dependencies { implementation libs.androidx.benchmark.macro implementation libs.my.library }
I riferimenti ai plug-in includono
plugins
dopo il nome del catalogo e i riferimenti alle versioni includonoplugins
dopo il nome del catalogo (i riferimenti alle versioni sono infrequenti; consulta Dipendenze con gli stessi numeri di versione per esempi di riferimenti alle versioni.) I riferimenti alle librerie non includono un qualificatorelibraries
, pertanto non puoi utilizzareversions
oplugins
all'inizio di un alias della libreria.
Configura le dipendenze
All'interno del blocco dependencies
, puoi dichiarare una dipendenza dalla libreria utilizzando una
tra diverse configurazioni di dipendenza (come implementation
mostrate
in precedenza). Ogni configurazione delle dipendenze fornisce a Gradle
istruzioni diverse su come usare la dipendenza. La tabella seguente descrive ciascuna delle configurazioni che puoi utilizzare per una dipendenza nel progetto Android.
Configurazione | Comportamento |
---|---|
implementation |
Gradle aggiunge la dipendenza al percorso di classe di compilazione e la pacchettizza nell'output della build. Quando il
modulo configura una dipendenza implementation ,
comunica a Gradle che non vuoi che il modulo divulghi la
dipendenza ad altri moduli in fase di compilazione. Ciò significa che la dipendenza non viene resa disponibile per gli altri moduli che dipendono dal modulo attuale.
L'utilizzo di questa configurazione delle dipendenze al posto di |
api |
Gradle aggiunge la dipendenza al classpath della compilazione e all'output della build. Quando un modulo include una dipendenza api , comunica a Gradle che vuole esportare transitivamente
questa dipendenza in altri moduli, in modo che sia disponibile sia al runtime che alla compilazione.
Utilizza questa configurazione con cautela e solo con le dipendenze che
devi esportare in modo transitivo in altri consumatori a monte. Se una dipendenza |
compileOnly |
Gradle aggiunge la dipendenza solo al percorso di classe di compilazione
(ovvero non viene aggiunta all'output di compilazione). Questo è utile quando
crei un modulo Android e hai bisogno della dipendenza durante
la compilazione, ma è facoltativo mostrarlo in fase di runtime. Ad esempio, se hai bisogno di una libreria che includa solo annotazioni a tempo di compilazione, in genere utilizzate per generare codice, ma spesso non incluse nell'output di compilazione, puoi contrassegnarla come compileOnly .
Se utilizzi questa configurazione, il modulo della libreria deve includere una condizione di runtime per verificare se la dipendenza è disponibile, quindi modificane il comportamento in modo che possa continuare a funzionare se non viene fornita. Ciò consente di ridurre le dimensioni dell'app finale evitando di aggiungere dipendenze temporanee che non sono critiche.
Nota: non puoi utilizzare la configurazione |
runtimeOnly |
Gradle aggiunge la dipendenza solo all'output della compilazione, per utilizzarla
durante l'esecuzione. Ciò significa che non viene aggiunto al classpath di compilazione.
Viene utilizzata raramente su Android, ma viene comunemente utilizzata nelle applicazioni server per fornire implementazioni di logging. Ad esempio, una
libreria potrebbe utilizzare un'API di logging che non include un'implementazione. I consumatori di questa libreria potrebbero aggiungerla come dipendenza implementation e includere una dipendenza runtimeOnly per l'implementazione effettiva del logging.
|
ksp |
Queste configurazioni forniscono librerie che elaborano le annotazioni e altri simboli nel codice prima della compilazione. In genere convalidano il codice o generano codice aggiuntivo, riducendo la quantità di codice da scrivere. Per aggiungere questa dipendenza, devi aggiungerla al classpath del processore di annotazioni utilizzando le configurazioni Il plug-in Android per Gradle presuppone che una dipendenza sia un elaboratore di annotazioni se il file JAR contiene il seguente file:
Se il plug-in rileva un processore di annotazione che si trova nel classpath di compilazione, genera un errore di build.
Quando decidi quale configurazione utilizzare, considera quanto segue:
Per maggiori informazioni sull'utilizzo dei processori di annotazione, consulta Aggiungere processori di annotazione. |
lintChecks |
Utilizza questa configurazione per includere una libreria contenente i controlli lint che vuoi che vengano eseguiti da Gradle durante la creazione del progetto della tua app per Android. Tieni presente che i rivenditori AAR che contengono un file |
lintPublish |
Utilizza questa configurazione nei progetti della libreria Android per includere i controlli lint che vuoi che Gradle compili in un file e un pacchetto lint.jar nel tuo AAR. In questo modo, anche i progetti che utilizzano il tuo AAR applicano i controlli lint. Se in precedenza utilizzavi
la configurazione delle dipendenze lintChecks per includere i controlli lint
nell'AAR pubblicato, devi eseguire la migrazione di queste dipendenze
per utilizzare la configurazione lintPublish .
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")) } Alla modadependencies { // 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') } |
Configurare le dipendenze per una variante di compilazione specifica
Tutte le configurazioni precedenti applicano dipendenze a tutte le varianti di build. Se invece vuoi dichiarare una dipendenza solo per un set di origini specifico della variante della build o per un set di origini di test, devi scrivere il nome della configurazione in maiuscolo e anteporre il nome della variante di build o del set di origini di test.
Ad esempio, per aggiungere una dipendenza binaria remota solo alla versione del prodotto "gratuita" utilizzando la configurazione implementation
, utilizza quanto segue:
Kotlin
dependencies { freeImplementation("com.google.firebase:firebase-ads:21.5.1") }
Groovy
dependencies { freeImplementation 'com.google.firebase:firebase-ads:21.5.1' }
Tuttavia, se vuoi aggiungere una dipendenza per una variante che combina un flavor del prodotto e un tipo di build, devi inizializzare il nome della configurazione:
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") }
Per aggiungere le dipendenze implementation
per i test locali e i test instrumentati,
il codice ha il seguente aspetto:
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' }
Tuttavia, alcune configurazioni non hanno senso in questa situazione. Ad esempio,
poiché gli altri moduli non possono dipendere da androidTest
, riceverai il seguente
avviso se utilizzi la configurazione androidTestApi
:
WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with 'androidTestImplementation'.
Ordine delle dipendenze
L'ordine in cui elencare le dipendenze indica la priorità di ognuna: la prima libreria ha una priorità più alta della seconda, la seconda ha una priorità più alta della terza e così via. Questo ordine è importante nel caso in cui le risorse vengano unite o gli elementi del manifest vengano uniti all'app dalle librerie.
Ad esempio, se il progetto dichiara quanto segue:
- Dipendenza da
LIB_A
eLIB_B
(in questo ordine) - e
LIB_A
dipende daLIB_C
eLIB_D
(in questo ordine) - Inoltre,
LIB_B
dipende anche daLIB_C
L'ordine di dipendenza fisso sarà il seguente:
LIB_A
LIB_D
LIB_B
LIB_C
In questo modo, sia LIB_A
che LIB_B
possono sostituire
LIB_C
e LIB_D
ha ancora una priorità più alta rispetto
LIB_B
perché LIB_A
(che dipende da LIB_D
)
ha una priorità più alta rispetto a LIB_B
.
Per ulteriori informazioni su come vengono uniti i manifest di diverse origini/dipendenze del progetto, consulta Unire più file manifest.
Informazioni sulle dipendenze per Play Console
Durante la creazione dell'app, AGP include metadati che descrivono le dipendenze della libreria compilate nell'app. Quando carichi l'app, Play Console ispeziona questi metadati per fornire avvisi relativi a problemi noti con gli SDK e le dipendenze utilizzati dall'app e, in alcuni casi, fornire feedback utili per risolvere questi problemi.
I dati sono compressi, criptati da una chiave di firma di Google Play e archiviati nel blocco di firma della tua app di release. Ti consigliamo di conservare questo file delle dipendenze per un'esperienza utente sicura e positiva. Per disattivare questa funzionalità, includi il
seguente
blocco dependenciesInfo
nel file build.gradle.kts
del modulo.
android {
dependenciesInfo {
// Disables dependency metadata when building APKs.
includeInApk = false
// Disables dependency metadata when building Android App Bundles.
includeInBundle = false
}
}
Per ulteriori informazioni sulle nostre norme e sui potenziali problemi relativi alle dipendenze, consulta la nostra pagina di assistenza sull'utilizzo di SDK di terze parti nella tua app.
Approfondimenti sull'SDK
Android Studio mostra avvisi di lint nel file del catalogo delle versioni e nella finestra di dialogo Struttura del progetto per gli SDK pubblici nel Google Play SDK Index quando si verificano i seguenti problemi:
- Gli SDK sono contrassegnati come obsoleti dai rispettivi autori.
- Gli SDK violano le norme di Play.
Gli avvisi ti indicano che devi aggiornare queste dipendenze, perché l'utilizzo di versioni obsolete potrebbe impedirti di pubblicare in Google Play Console in futuro.
Aggiungi dipendenze build senza cataloghi delle versioni
Consigliamo di utilizzare i cataloghi delle versioni per aggiungere e gestire le dipendenze, ma potrebbero non essere necessarie per progetti semplici. Ecco un esempio di file di compilazione che non utilizza i cataloghi delle versioni:
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') }
Questo file di build dichiara una dipendenza alla versione 12.3 della libreria "app-magic", all'interno del gruppo dello spazio dei nomi "com.example.android". La dichiarazione di dipendenza dal codice binario remoto è un'abbreviazione per quanto segue:
Kotlin
implementation(group = "com.example.android", name = "app-magic", version = "12.3")
Alla moda
implementation group: 'com.example.android', name: 'app-magic', version: '12.3'
Il file di build dichiara inoltre una dipendenza da un modulo della libreria Android denominato
"mylibrary"; questo nome deve corrispondere al nome della libreria definito con un include:
nel tuo file settings.gradle.kts
. Quando compili l'app, il sistema di compilazione compila il modulo della libreria e pacchettizza i contenuti compilati risultanti nell'app.
Il file di build dichiara inoltre una dipendenza dal plug-in Android Gradle (com.application.android
). Se disponi di più moduli che utilizzano lo stesso plug-in, puoi avere una sola versione del plug-in sul classpath della build in tutti i moduli. Anziché specificare la versione in ciascuno degli script di compilazione del modulo, devi includere la dipendenza dal plug-in nello script di compilazione principale con la versione e indicare di non applicarla. L'aggiunta di apply false
indica a Gradle di prendere nota della versione del plug-in, ma di non utilizzarla nella build principale.
In genere lo script di build principale è vuoto, ad eccezione di questo blocco plugins
.
Kotlin
plugins { id("org.jetbrains.kotlin.android") version "1.9.0" apply false }
Alla moda
plugins { id ‘com.android.application’ version ‘8.3.0-rc02’ apply false }
Se hai un progetto a un modulo, puoi specificare la versione esplicitamente nello script di compilazione a livello di modulo e lasciare vuoto lo script di compilazione a livello di progetto:
Kotlin
plugins { id("com.android.application") version "8.3.0" }
Groovy
plugins { id 'com.android.application' version '8.3.0-rc02' }