Aggiungi dipendenze build

Il sistema di compilazione Gradle in Android Studio ti consente di includere file binari esterni o altri moduli di libreria alla tua build come dipendenze. Le dipendenze possono trovarsi sulla tua macchina o in un repository remoto e tutte le dipendenze transitive che dichiarano vengono incluse automaticamente. In questa pagina viene descritto come utilizzare le dipendenze con il progetto Android, inclusi i dettagli su comportamenti e configurazioni specifici del plug-in Android 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.

Attenzione: quando specifichi le dipendenze, non utilizzare numeri di versione dinamici, come 'com.android.tools.build:gradle:3.+'. L'uso di questa funzionalità può causare aggiornamenti di versione imprevisti, difficoltà a risolvere le differenze di versione e prestazioni scarse.

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 utilizzato per impostazione predefinita 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 sull'aggiunta e la gestione delle dipendenze native (non comune), consulta Dipendenze native.

Nell'esempio seguente, aggiungiamo al nostro progetto una dipendenza binaria remota (la libreria Jetpack Macrobenchmark), una dipendenza dai moduli della libreria locale (myLibrary) e una dipendenza dai plug-in (il plug-in Android Gradle). Ecco i passaggi generali per aggiungere queste dipendenze al tuo progetto:

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

1. Aggiungi un alias per la versione della dipendenza che ti interessa nella sezione [versions] del file di catalogo delle versioni, denominata 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 che puoi fare riferimento negli script di build. I riferimenti iniziano con il nome del catalogo, la parte libs di libs.versions.toml. Se 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 programmi binari remoti o i moduli delle librerie locali) 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 base (BOM) pubblicata che raggruppa le 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 informazioni dettagliate, consulta la sezione Utilizzo della distinta base.

3. Aggiungi un riferimento all'alias delle dipendenze allo script di build dei moduli che richiedono la dipendenza. Converti i trattini bassi e i trattini dell'alias in punti quando vi 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)
   }
   

   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 alla versione includono versions dopo il nome del catalogo (i riferimenti alla versione sono rari; consulta Dipendenze con gli stessi numeri di versione per esempi di riferimenti alle versioni). I riferimenti alle librerie non includono un qualificatore libraries, quindi 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 delle varie configurazioni di dipendenza (come implementation mostrate prima). Ogni configurazione delle dipendenze fornisce a Gradle istruzioni diverse su come usare la dipendenza. La tabella seguente descrive tutte le configurazioni che puoi utilizzare per una dipendenza nel progetto Android.

Configurazione	Comportamento
implementation	Gradle aggiunge la dipendenza al classpath di compilazione e pacchettizza la dipendenza 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 al momento della 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 può comportare miglioramenti significativi in termini di tempo di compilazione, poiché riduce il numero di moduli che il sistema di build ha bisogno di ricompilare. Ad esempio, se una dipendenza implementation cambia la sua API, Gradle ricompila solo quella dipendenza e i moduli che dipendono direttamente da questa dipendenza. La maggior parte dei moduli di app e test dovrebbe utilizzare questa configurazione.
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. Usa questa configurazione con cautela e solo con le dipendenze necessarie per esportare transitivamente in altri consumer upstream. Se una dipendenza api cambia la sua API esterna, Gradle ricompila tutti i moduli che hanno accesso a quella dipendenza al momento della compilazione. La presenza di un numero elevato di dipendenze api può aumentare notevolmente la durata della build. A meno che tu non voglia esporre l'API di una dipendenza a un modulo separato, i moduli della libreria dovrebbero utilizzare invece le dipendenze implementation.
compileOnly	Gradle aggiunge la dipendenza solo al classpath di compilazione (ovvero, non viene aggiunta all'output della build). 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 dipendi da una libreria che include solo annotazioni in fase di compilazione, generalmente utilizzate per generare codice ma spesso non incluse nell'output della build, puoi contrassegnare la libreria 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 compileOnly con le dipendenze di Android Archive (AAR).
runtimeOnly	Gradle aggiunge la dipendenza solo all'output della build, da utilizzare durante il runtime. 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 consumer di quella libreria potrebbero aggiungerla come dipendenza implementation e includere una dipendenza runtimeOnly per l'implementazione effettiva del logging da utilizzare.
ksp kapt annotationProcessor	Queste configurazioni forniscono librerie che elaborano annotazioni e altri simboli nel codice prima che venga compilato. 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 ksp, kapt o annotationProcessor. L'utilizzo di queste configurazioni migliora le prestazioni della build separando il classpath di compilazione dal classpath del processore di annotazione. Se Gradle trova processori di annotazione sul classpath di compilazione, disattiva l' esclusione della compilazione, con un conseguente impatto negativo sul tempo di compilazione (Gradle 5.0 e versioni successive ignorano i processori di annotazione presenti nel classpath di compilazione). Il plug-in Android per Gradle presuppone che una dipendenza sia un processore di annotazione se il relativo file JAR contiene il seguente file: META-INF/services/javax.annotation.processing.Processor Se il plug-in rileva un processore di annotazione che si trova nel classpath di compilazione, genera un errore di build. ksp è un processore di simboli Kotlin ed è eseguito dal compilatore Kotlin. kapt e apt sono strumenti separati 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, usalo come dipendenza ksp. Per maggiori dettagli sull'utilizzo dei processori di simboli Kotlin, consulta la pagina Eseguire la migrazione da kapt a ksp. Se il processore non è disponibile come processore di simboli Kotlin: Se il tuo progetto include il codice sorgente Kotlin (ma può includere anche il codice sorgente Java), usa kapt per includerlo. Se il progetto utilizza solo l'origine Java, usa annotationProcessor per includerlo. 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 lint.jar eseguiranno 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 un'unica dipendenza, assicurandoti che i controlli vengano eseguiti quando i consumer utilizzano la tua libreria.
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. Di conseguenza, 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. 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")) } Alla moda 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') }

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 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 "senza costi" del prodotto utilizzando la configurazione implementation, utilizza questo comando:

Kotlin

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

Alla moda

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"))
}

Alla moda

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.5.1")
}

Alla moda

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, 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 elenchi le tue 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 vengono uniti nell'app dalle librerie.

Ad esempio, se il tuo 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)
• E LIB_B dipende anche da LIB_C

Quindi, l'ordine delle dipendenze stabile 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 eseguire l'override di LIB_C; LIB_D ha comunque una priorità più alta di LIB_B perché LIB_A (che dipende da questo valore) ha una priorità più alta di 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

Quando crei la tua app, AGP include metadati che descrivono le dipendenze della libreria compilate nella tua app. Durante il caricamento dell'app, Play Console controlla questi metadati per fornire avvisi relativi a problemi noti relativi agli SDK e alle dipendenze utilizzate 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. Puoi disattivarli includendo 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.

Approfondimenti sull'SDK

Android Studio mostra avvisi di lint nel file del catalogo delle versioni e nella finestra di dialogo della struttura del progetto per gli SDK pubblici in 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 Google Play.

Gli avvisi 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 build che non utilizza catalogi 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"))
}

Alla moda

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 binaria remota è un'abbreviazione di 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 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 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. Invece di specificare la versione in ciascuno degli script di build del modulo, dovresti includere la dipendenza del plug-in nello script di compilazione radice con la versione e indicare di non applicarla. L'aggiunta di apply false indica a Gradle di annotare la versione del plug-in, ma di non utilizzarla nella build principale. In genere lo script di compilazione 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 modulo singolo, 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"
}

Alla moda

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