Il sistema di build Gradle in Android Studio consente di includere file binari esterni o altri moduli di libreria alla build come dipendenze. Le dipendenze possono essere posizionate sulla macchina o in un repository remoto e anche tutte le dipendenze transitive dichiarate vengono incluse automaticamente. Questa pagina descrive come utilizzare le dipendenze con il tuo progetto Android, inclusi i dettagli sui comportamenti e sulle configurazioni specifiche del plug-in Android Gradle (AGP). Per una guida concettuale più approfondita alle dipendenze di Gradle, ti consigliamo di consultare 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 libreria o una dipendenza plug-in
Il modo migliore per aggiungere e gestire le dipendenze delle build è usare i cataloghi di versioni, il metodo utilizzato per impostazione predefinita dai nuovi progetti. Questa sezione tratta i tipi più comuni di configurazioni utilizzate 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 senza cataloghi di versioni e hai un progetto multimodulo, ti consigliamo di eseguire la migrazione.
Per indicazioni sull'aggiunta e sulla gestione delle dipendenze native (non comune), consulta Dipendenze native.
Nell'esempio seguente, aggiungiamo una dipendenza binaria remota (la libreria Jetpack Macrobenchmark), una dipendenza del modulo della libreria locale (myLibrary
) e una dipendenza del plug-in (il plug-in Android Gradle) al nostro progetto. Di seguito sono riportati i passaggi generali per aggiungere queste dipendenze al progetto:
Aggiungi un alias per la versione della dipendenza che vuoi nella sezione
[versions]
del file di catalogo delle versioni, denominatalibs.versions.toml
(nella directorygradle
nella visualizzazione Project o in Gradle Script 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 build. I riferimenti iniziano con il nome del catalogo, la parte
libs
dilibs.versions.toml
. Quando utilizzi un unico catalogo di versioni, ti consigliamo di mantenere il valore predefinito "libs".Aggiungi un alias per la dipendenza nelle sezioni
[libraries]
(per i programmi 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 base (BOM) pubblicata che raggruppa le famiglie di biblioteche e le relative versioni. Puoi includere una distinta base nel catalogo delle versioni e nei file di build, che poi potrà gestire automaticamente. Per i dettagli, consulta Utilizzo della distinta base.
Aggiungi un riferimento all'alias delle dipendenze allo script di build dei moduli che richiedono la dipendenza. Converti i trattini bassi e i trattini degli alias in punti quando li fai riferimento da uno script di build. Il nostro script di build a livello di modulo avrebbe il seguente aspetto:
Kotlin
plugins { alias(libs.plugins.androidApplication) } dependencies { implementation(libs.androidx.benchmark.macro) implementation(libs.my.library) }
trendy
plugins { alias 'libs.plugins.androidApplication' } dependencies { implementation libs.androidx.benchmark.macro implementation libs.my.library }
I riferimenti dei plug-in includono
plugins
dopo il nome del catalogo, mentre i riferimenti alle versioni includonoversions
dopo il nome del catalogo (i riferimenti alle versioni sono rari; consulta la sezione Dipendenze con gli stessi numeri di versione per alcuni esempi di riferimenti alle versioni. I riferimenti alla libreria non includono un qualificatorelibraries
, quindi non puoi utilizzareversions
oplugins
all'inizio dell'alias della libreria.
Configura le dipendenze
All'interno del blocco dependencies
, puoi dichiarare una dipendenza dalla libreria utilizzando una delle varie configurazioni delle dipendenze (ad esempio implementation
mostrate in precedenza). Ogni configurazione delle dipendenze fornisce a Gradle
istruzioni diverse su come usarla. La seguente tabella descrive tutte le configurazioni che puoi utilizzare per una dipendenza nel tuo progetto Android.
Configurazione | Comportamento |
---|---|
implementation |
Gradle aggiunge la dipendenza al classpath di compilazione e la pacchettizza all'output della build. Quando il modulo configura una dipendenza implementation , comunica a Gradle che non vuoi che il modulo perda la dipendenza ad altri moduli in fase di compilazione. Ciò significa che la dipendenza non viene resa disponibile per altri moduli che dipendono dal modulo attuale.
L'utilizzo di questa configurazione delle dipendenze al posto di
|
api |
Gradle aggiunge la dipendenza al classpath di compilazione e all'output della build. Quando un modulo include una dipendenza api , comunica a Gradle che il modulo vuole esportare in modo transitivo la dipendenza in altri moduli, in modo che sia disponibile sia in fase di runtime che in fase di compilazione.
Utilizza questa configurazione con cautela e solo con le dipendenze che devi esportare in modo transitivo in altri consumer upstream. Se una dipendenza |
compileOnly |
Gradle aggiunge la dipendenza solo al classpath di compilazione (ovvero non viene aggiunta all'output della build). Questo è utile durante la creazione di un modulo Android e hai bisogno della dipendenza durante la compilazione, ma è facoltativo che sia presente in fase di runtime. Ad esempio, se dipendi da una libreria che include solo annotazioni in fase di compilazione, solitamente utilizzata per generare il codice ma spesso non inclusa nell'output della build, puoi contrassegnare quella libreria come compileOnly .
Se utilizzi questa configurazione, il modulo della libreria deve includere una condizione di runtime per verificare se la dipendenza è disponibile, quindi modificarne il comportamento in modo che possa continuare a funzionare se non viene fornita. Ciò consente di ridurre le dimensioni dell'app finale, evitando l'aggiunta di dipendenze temporanee non critiche.
Nota: non puoi utilizzare la configurazione di |
runtimeOnly |
Gradle aggiunge la dipendenza solo all'output della build, da utilizzare
durante il runtime. Vale a dire che non viene aggiunto al classpath di compilazione.
Viene usato raramente su Android, ma comunemente 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 quella libreria potrebbero aggiungerla come
dipendenza implementation e includere una
dipendenza runtimeOnly per l'implementazione
del logging effettiva da utilizzare.
|
ksp |
Queste configurazioni forniscono librerie che elaborano annotazioni e altri simboli nel codice prima della compilazione. In genere convalidano il codice o generano codice aggiuntivo, riducendo il codice necessario da scrivere. Per aggiungere una dipendenza di questo tipo, devi aggiungerla al classpath del processore di annotazioni utilizzando le configurazioni Il plug-in Android Gradle presuppone che una dipendenza sia un processore di annotazione se il relativo file JAR contiene il seguente file:
Se il plug-in rileva un processore di annotazioni che si trova sul classpath di compilazione, produce un errore di build.
Quando decidi quale configurazione utilizzare, considera quanto segue:
Per maggiori informazioni sull'utilizzo dei processori di annotazioni, consulta Aggiungere processori di annotazioni. |
lintChecks |
Utilizza questa configurazione per includere una libreria contenente controlli di lint che vuoi che Gradle esegua durante la creazione del tuo progetto di app per Android. Tieni presente che gli AAR che contengono un file |
lintPublish |
Utilizza questa configurazione nei progetti della libreria Android per includere i controlli lint che vuoi compilare da Gradle in un file lint.jar e un pacchetto nel tuo AAR. In questo modo, i progetti che utilizzano il tuo
AAR applicano anche questi 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")) } trendydependencies { // 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') } |
Configura le dipendenze per una variante di build specifica
Tutte le configurazioni precedenti applicano dipendenze a tutte le varianti di build. Se invece vuoi dichiarare una dipendenza solo per uno specifico set di origine variante build o per un set di origini di test, devi utilizzare le lettere maiuscole per il nome della configurazione e il nome della variante di build o del set di origine di test.
Ad esempio, per aggiungere una dipendenza binaria remota solo alla versione di prodotto "senza costi" utilizzando la configurazione implementation
, utilizza questo:
Kotlin
dependencies { freeImplementation("com.google.firebase:firebase-ads:21.5.1") }
trendy
dependencies { freeImplementation 'com.google.firebase:firebase-ads:21.5.1' }
Tuttavia, se vuoi aggiungere una dipendenza per una variante che combina una versione di 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")) }
trendy
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 strumentati, l'aspetto è il seguente:
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") }
trendy
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' }
Tuttavia, alcune configurazioni non hanno senso in questa situazione. Ad esempio,
poiché gli altri moduli non possono dipendere da androidTest
, viene visualizzato il seguente
avviso se utilizzi la configurazione androidTestApi
:
WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with 'androidTestImplementation'.
Ordine di dipendenza
L'ordine in cui vengono elencate 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 manifest vengano uniti nella tua app dalle librerie.
Ad esempio, se il tuo progetto dichiara quanto segue:
- Dipende da
LIB_A
eLIB_B
(in questo ordine) - Inoltre,
LIB_A
dipende daLIB_C
eLIB_D
(in questo ordine) - Anche
LIB_B
dipende daLIB_C
Quindi, l'ordine delle dipendenze fisse sarà il seguente:
LIB_A
LIB_D
LIB_B
LIB_C
In questo modo sia LIB_A
che LIB_B
possano eseguire l'override di LIB_C
. Inoltre, LIB_D
ha ancora una priorità più alta di LIB_B
perché LIB_A
(che dipende da questo elemento) ha una priorità più alta di LIB_B
.
Per ulteriori informazioni su come vengono uniti i manifest di diverse origini/dipendenze di progetto, consulta Unire più file manifest.
Informazioni sulla dipendenza per Play Console
Durante la creazione della tua app, AGP include metadati che descrivono le dipendenze della libreria compilate nella tua app. Durante il caricamento dell'app, Play Console esamina questi metadati per fornire avvisi relativi a problemi noti relativi agli SDK e alle dipendenze utilizzate dall'app e, in alcuni casi, per fornire feedback utili per risolvere questi problemi.
I dati vengono compressi, criptati con una chiave di firma di Google Play e archiviati nel blocco di firma della release dell'app. Ti consigliamo di conservare questo file delle dipendenze per un'esperienza utente sicura e positiva. Per disattivare questa opzione, 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 con le dipendenze, consulta la nostra pagina di assistenza sull'utilizzo di SDK di terze parti nella tua app.
Insight sull'SDK
Android Studio mostra avvisi lint nel file di catalogo delle versioni e nella finestra di dialogo Struttura del progetto per gli SDK pubblici in Google Play SDK Index quando si applicano i seguenti problemi:
- Gli SDK sono contrassegnati come obsoleti dai rispettivi autori.
- Gli SDK violano le norme di Google Play.
Gli avvisi indicano che devi aggiornare queste dipendenze, perché l'utilizzo di versioni obsolete potrebbe impedire la pubblicazione su Google Play Console in futuro.
Aggiungi dipendenze della build senza cataloghi delle versioni
Consigliamo di utilizzare i cataloghi delle versioni per aggiungere e gestire le dipendenze, ma i progetti semplici potrebbero non aver bisogno di queste dipendenze. Ecco un esempio di file di build che non utilizza 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")) }
trendy
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 per la versione 12.3 della libreria "app-magic", all'interno del gruppo dello spazio dei nomi "com.example.android". La dichiarazione di dipendenza binaria remota è un'abbreviazione di quanto segue:
Kotlin
implementation(group = "com.example.android", name = "app-magic", version = "12.3")
trendy
implementation group: 'com.example.android', name: 'app-magic', version: '12.3'
Il file di build dichiara inoltre una dipendenza su un modulo della libreria Android denominato "mylibrary"; questo nome deve corrispondere al nome della libreria definito con include:
nel file settings.gradle.kts
. Quando crei la tua app, il sistema di compilazione compila il modulo della libreria e pacchettizza i contenuti compilati risultanti nell'app.
Il file di build dichiara anche 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 dei moduli, devi includere la dipendenza del plug-in nello script di build principale con la versione e indicare di non applicarla. L'aggiunta di apply false
comunica a Gradle di annotare la 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 }
trendy
plugins { id ‘com.android.application’ version ‘8.3.0-rc02’ apply false }
Se hai un progetto a livello di singolo modulo, puoi specificare la versione in modo esplicito nello script di build a livello di modulo e lasciare vuoto lo script di build a livello di progetto:
Kotlin
plugins { id("com.android.application") version "8.3.0" }
trendy
plugins { id 'com.android.application' version '8.3.0-rc02' }