Aggiungere dipendenze di compilazione

Il sistema di build Gradle in Android Studio ti consente di includere file binari esterni o altri moduli di libreria nella build come dipendenze. Le dipendenze possono trovarsi sulla tua macchina o in un repository remoto e vengono incluse automaticamente anche tutte le dipendenze transitive dichiarate. Questa pagina descrive come utilizzare le dipendenze con il tuo progetto Android, inclusi i dettagli su comportamenti e configurazioni specifici del plug-in Android Gradle (AGP). Per una guida concettuale più approfondita alle dipendenze di Gradle, consulta 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 della libreria o del plug-in

Il modo migliore per aggiungere e gestire le dipendenze di build è 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 delle versioni, consulta Now in Android. Se hai già configurato le dipendenze di build senza cataloghi delle versioni e hai un progetto multimodulo, ti consigliamo di eseguire la migrazione.

Per indicazioni su come aggiungere e gestire le dipendenze native (non comuni), consulta Dipendenze native.

Nell'esempio seguente, al progetto vengono aggiunte 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 per Gradle). Ecco i passaggi generali per aggiungere queste dipendenze al tuo progetto:

1. Aggiungi un alias per la versione della dipendenza che ti interessa nella sezione [versions] del file del catalogo delle versioni, denominato 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 build. I riferimenti iniziano con il nome del catalogo, la parte libs di libs.versions.toml. Quando utilizzi un catalogo delle versioni singolo, ti consigliamo di mantenere il valore predefinito "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 base (BOM) pubblicata che raggruppa le famiglie di librerie e le relative versioni. Puoi includere una BOM nel catalogo delle versioni e nei file di build e lasciare che gestisca queste versioni per te. Per i dettagli, consulta Utilizzo della distinta base.

3. Aggiungi un riferimento all'alias della dipendenza allo script di build 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 build. Lo script di build a livello di modulo sarà simile al seguente:

   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, mentre i riferimenti alle versioni includono versions 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). I riferimenti alla libreria 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 della libreria utilizzando una delle diverse configurazioni di dipendenza (ad esempio implementation mostrata 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 tuo progetto Android.

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

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 compilazione specifica

Tutte le configurazioni precedenti applicano le dipendenze a tutte le varianti di compilazione. Se invece vuoi dichiarare una dipendenza solo per un set di risorse di una variante di compilazione specifica o per un set di risorse di test, devi scrivere in maiuscolo il nome della configurazione e anteporre il nome della variante di compilazione o del set di risorse di test.

Ad esempio, per aggiungere una dipendenza binaria remota solo alla versione prodotto "senza costi" utilizzando la configurazione implementation, utilizza questo:

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

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Tuttavia, se vuoi aggiungere una dipendenza per una variante che combina una versione prodotto e un tipo di build, devi inizializzare il nome della configurazione:

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

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 di instrumentazione, il codice è il seguente:

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

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é altri moduli non possono dipendere da androidTest, se utilizzi la configurazione androidTestApi viene visualizzato il seguente avviso:

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

Ordine delle dipendenze

L'ordine in cui elenchi le dipendenze indica la priorità di ciascuna. Ad esempio, la prima libreria ha una priorità più alta della seconda e la seconda ha una priorità più alta della terza. Questo ordine è importante nel caso in cui le risorse vengano unite o gli elementi manifest vengano uniti alla tua 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 quest'ordine)
• Inoltre, LIB_B dipende da LIB_C

In questo caso, l'ordine di dipendenza lineare 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; inoltre, LIB_D ha comunque una priorità più alta di LIB_B perché LIB_A (che dipende da ) ha una priorità più alta di LIB_B.

Per saperne di più su come vengono uniti i manifest di origini o dipendenze di progetti diversi, consulta Unisci più file manifest.

Informazioni sulle dipendenze per Play Console

Durante la creazione dell'app, AGP include i metadati che descrivono le dipendenze della libreria compilate nell'app. Quando carichi l'app, Play Console esamina questi metadati per fornire avvisi relativi a problemi noti con gli SDK e le dipendenze utilizzate dall'app e, in alcuni casi, fornire feedback utili per risolvere questi problemi.

I dati vengono compressi, crittografati da una chiave di firma di Google Play e archiviati nel blocco di firma dell'app della release. Ti consigliamo di conservare questo file delle dipendenze per un'esperienza utente sicura e positiva. Puoi disattivare questa funzionalità 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 relativi alle dipendenze, consulta la nostra pagina di assistenza sull'utilizzo di SDK di terze parti nella tua app.

Insight sugli SDK

Android Studio mostra gli avvisi di lint nel file del 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 loro autori.
• Gli SDK violano le norme di Google Play.
• Gli SDK presentano vulnerabilità di sicurezza note.
• Gli SDK sono stati ritirati dai loro autori.

Gli avvisi sono indicatori che ti invitano ad aggiornare queste dipendenze, perché l'utilizzo di versioni obsolete potrebbe impedirti di pubblicare su Google Play Console in futuro.

Aggiungi dipendenze di build senza cataloghi delle 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 build che non utilizza i cataloghi delle versioni:

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

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 dalla versione 12.3 della libreria "app-magic" all'interno del gruppo di spazi dei nomi "com.example.android". La dichiarazione di dipendenza binaria remota è l'abbreviazione di quanto segue:

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

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

Il file build dichiara anche una dipendenza da un modulo della libreria Android denominato "mylibrary"; questo nome deve corrispondere al nome della libreria definito con un include: nel file settings.gradle.kts. Quando crei l'app, il sistema di build 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 per Gradle (com.application.android). Se hai più moduli che utilizzano lo stesso plug-in, puoi avere una sola versione del plug-in nel classpath di build in tutti i moduli. Anziché specificare la versione in ogni script di build del modulo, 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 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.

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

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

Se hai un progetto con un 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:

plugins {
    id("com.android.application") version "8.3.0"
}

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