Aggiungi dipendenze build

Il sistema di compilazione Gradle in Android Studio ti consente di includere come dipendenze della compilazione eventuali file binari esterni o altri moduli di librerie. Le dipendenze possono essere situate sulla tua macchina o in un repository remoto e anche le eventuali dipendenze transitive dichiarate sono incluse automaticamente. Questa pagina descrive come utilizzare le dipendenze con il progetto Android, inclusi dettagli su comportamenti e configurazioni specifici del plug-in Android Gradle (AGP). Per una guida concettuale più approfondita alle dipendenze Gradle, consulta la guida di Gradle per la gestione delle dipendenze, ma ricorda che il progetto Android deve utilizzare solo le configurazioni delle dipendenze definite in questa pagina.

Attenzione: quando specifichi le dipendenze, non devi utilizzare numeri di versione dinamici, ad esempio 'com.android.tools.build:gradle:3.+'. L'utilizzo di questa funzionalità può causare aggiornamenti imprevisti delle versioni, difficoltà a risolvere le differenze tra le versioni e scarso rendimento.

Aggiungere una dipendenza da libreria o plug-in

Il modo migliore per aggiungere e gestire le dipendenze di compilazione è utilizzare i cataloghi delle versioni, il metodo utilizzato per impostazione predefinita dai nuovi progetti. Questa sezione illustra i tipi di configurazioni più comuni utilizzati per i progetti Android. Per altre opzioni, consulta la documentazione di Gradle. Per un esempio di app che utilizza i cataloghi di versioni, consulta Novità di Android. Se hai già configurato le dipendenze di compilazione senza cataloghi delle versioni e hai un progetto multi-modulo, 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:

Nota: è possibile dichiarare i cataloghi di versioni nel file di impostazioni, ma ti consigliamo di utilizzare un file toml separato per ricevere ulteriore assistenza con i suggerimenti di codice e l'evidenziazione di Android Studio.

1. Aggiungi un alias per la versione della dipendenza che preferisci nella sezione [versions] del file del catalogo delle versioni, chiamato libs.versions.toml (nella directory gradle 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 di libs.versions.toml. Quando utilizzi un catalogo con una sola versione, ti consigliamo di mantenere il valore predefinito di "libs".

2. 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 file 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" }
   

   Alcune librerie sono disponibili in una distinta dei materiali (BOM) pubblicata che raggruppa famiglie di librerie e le relative versioni. Puoi includere una distinta nel catalogo delle versioni e nei file di compilazione e lasciare che sia il catalogo a gestire le versioni per te. Per maggiori dettagli, consulta Utilizzare la distinta componenti.

3. Aggiungi un riferimento all'alias della dipendenza allo script di compilazione dei moduli che richiedono la dipendenza. Converti i trattini bassi e i trattini degli alias in punti quando fai riferimento a un 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)
   }

   Groovy

   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 includono plugins dopo il nome del catalogo (i riferimenti alle versioni sono rari; consulta Dipendenze con gli stessi numeri di versione per esempi di riferimenti alle versioni).versions I riferimenti alle librerie non includono un qualificatore libraries, pertanto non puoi utilizzare versions o plugins all'inizio di un alias della libreria.

Configura le dipendenze

All'interno del blocco dependencies, puoi dichiarare una dipendenza dalla libreria utilizzando una di diverse configurazioni di dipendenza (ad esempio implementation mostrato in precedenza). Ogni configurazione delle dipendenze fornisce a Gradle istruzioni diverse su come utilizzare 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. In altre parole, la dipendenza non viene messa a disposizione di altri moduli che dipendono dal modulo corrente. L'utilizzo di questa configurazione delle dipendenze anziché di api può comportare miglioramenti significativi del tempo di compilazione perché riduce il numero di moduli che il sistema di compilazione deve ricompilare. Ad esempio, se una dipendenza implementation modifica la propria API, Gradle ricompila solo quella dipendenza e i moduli che dipendono direttamente da essa. La maggior parte dei moduli di app e test dovrebbe utilizzare questa configurazione.
api	Gradle aggiunge la dipendenza al percorso di classe di compilazione e all'output della compilazione. Quando un modulo include una dipendenza api, comunica a Gradle che vuole esportare in modo transitivo la dipendenza in altri moduli, in modo che sia disponibile per questi sia al momento dell'esecuzione che in fase di compilazione. Utilizza questa configurazione con cautela e solo con le dipendenze che devi esportare in modo transitivo ad altri consumatori a monte. Se una dipendenza api modifica la propria API esterna, Gradle ricompila tutti i moduli che hanno accesso a quella dipendenza al momento della compilazione. Un numero elevato di dipendenze api può aumentare notevolmente i tempi di compilazione. A meno che tu non voglia esporre l'API di una dipendenza a un modulo separato, i moduli della libreria devono invece utilizzare le dipendenze implementation.
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 compilation, ma è facoltativo che sia presente in fase di esecuzione. 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 e poi modificare il relativo comportamento in modo che possa comunque funzionare se non è fornita. In questo modo, puoi ridurre le dimensioni dell'app finale non aggiungendo dipendenze transitorie non critiche. Nota: non puoi utilizzare la configurazione compileOnly con le dipendenze Android Archive (AAR).
runtimeOnly	Gradle aggiunge la dipendenza solo all'output della compilazione, per utilizzarla durante l'esecuzione. In altre parole, non viene aggiunto al percorso di classe di compilazione. Viene utilizzato raramente su Android, ma è molto comune nelle applicazioni di 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 kapt annotationProcessor	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 il codice che devi scrivere. Per aggiungere una dipendenza di questo tipo, devi aggiungerla al percorso di classe dell'annotatore utilizzando le configurazioni ksp, kapt o annotationProcessor. L'utilizzo di queste configurazioni migliora il rendimento della compilazione separando il percorso di compilazione dal percorso dell'annotatore. Se Gradle trova gli elaboratori di annotazioni nel percorso di compilazione, disattiva l' avoid compila, il che influisce negativamente sui tempi di compilazione (Gradle 5.0 e versioni successive ignorano gli elaboratori di annotazioni trovati nel percorso di compilazione). Il plug-in Android per Gradle presuppone che una dipendenza sia un elaboratore di annotazioni se il file JAR contiene il seguente file: META-INF/services/javax.annotation.processing.Processor Se il plug-in rileva un elaboratore di annotazioni nel percorso di compilazione, genera un errore di compilazione. ksp è un elaboratore di simboli Kotlin ed è eseguito dal compilatore Kotlin. kapt e apt sono strumenti distinti che elaborano le annotazioni prima dell'esecuzione dei compilatori Kotlin o Java. Quando decidi quale configurazione utilizzare, considera quanto segue: Se un processore è disponibile come processore di simboli Kotlin, utilizzalo come dipendenza ksp. Per informazioni dettagliate sull'utilizzo dei processori di simboli Kotlin, consulta Eseguire la migrazione da kapt a ksp. Se il gestore non è disponibile come gestore dei simboli Kotlin: Se il tuo progetto include codice sorgente Kotlin (ma può anche includere codice sorgente Java), utilizza kapt per includerlo. Se il tuo progetto utilizza solo codice sorgente Java, utilizza annotationProcessor per includerlo. Per ulteriori informazioni sull'utilizzo dei processori di annotazioni, consulta Aggiungere processori di annotazioni.
lintChecks	Utilizza questa configurazione per includere una libreria contenente i controlli lint che vuoi che Gradle esegua durante la compilazione del progetto dell'app Android. Tieni presente che gli AAR che contengono un file lint.jar eseguireanno automaticamente i controlli definiti in quel file lint.jar. Non è necessario aggiungere una dipendenza lintChecks esplicita. In questo modo puoi definire le librerie e i controlli lint associati in una singola dipendenza, assicurandoti che i controlli vengano eseguiti quando i consumatori utilizzano la tua libreria.
lintPublish	Utilizza questa configurazione nei progetti di librerie Android per includere i controlli lint che vuoi che Gradle compili in un file lint.jar e pacchettizzi nell'AAR. Di conseguenza, i progetti che utilizzano il tuo AAR applicheranno anche questi controlli di 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. 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') }

Configurare le dipendenze per una variante di compilazione specifica

Tutte le configurazioni precedenti applicano le dipendenze a tutte le varianti di build. Se invece vuoi dichiarare una dipendenza solo per un insieme di origini di variante di build specifico o per un insieme di origini di test, devi usare lettere maiuscole per il nome della configurazione e anteporvi il nome della variante di build o dell'insieme di origini di test.

Ad esempio, per aggiungere una dipendenza binaria remota solo alla versione del prodotto "senza costi" 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 dipendenze implementation per i test locali e gli strumenti di test, il codice sarà simile al 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.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, viene visualizzato il seguente avviso se utilizzi la configurazione androidTest:androidTestApi

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

Ordine di dipendenza

L'ordine in cui elenchi le dipendenze indica la priorità di ciascuna: la prima raccolta 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 e LIB_B (in questo ordine)
• e LIB_A dipende da LIB_C e LIB_D (in questo ordine)
• Inoltre, LIB_B dipende anche da LIB_C

L'ordine di dipendenza fisso sarà il seguente:

1. LIB_A
2. LIB_D
3. LIB_B
4. 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 origini/dipendenze di progetti diversi, 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 vengono compressi, criptati da una chiave di firma di Google Play e archiviati nel blocco di firma dell'app di rilascio. Ti consigliamo di conservare questo file delle dipendenze per un'esperienza utente positiva e sicura. 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 relativi 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.

Aggiungere dipendenze di compilazione senza cataloghi di versioni

Ti consigliamo di utilizzare i cataloghi delle versioni per aggiungere e gestire le dipendenze, ma i progetti semplici potrebbero non averne bisogno. 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 compilazione dichiara una dipendenza dalla versione 12.3 della libreria "app-magic", all'interno del gruppo di spazi 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")

Groovy

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

Il file di compilazione dichiara anche una dipendenza da un modulo della raccolta di Android denominato "mylibrary". Questo nome deve corrispondere al nome della raccolta definito con un include: nel 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 anche una dipendenza dal plug-in Gradle per Android (com.application.android). Se hai più moduli che utilizzano lo stesso plug-in, puoi avere una sola versione del plug-in nel percorso di classe di compilazione 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 compilazione principale è vuoto, tranne per questo blocco 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 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'
}