Aggiungi dipendenze build

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:

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

  2. 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 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 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.

  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 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 includono versions 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 qualificatore libraries, quindi non puoi utilizzare versions o plugins 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 può comportare miglioramenti significativi dei tempi di compilazione perché riduce il numero di moduli di cui il sistema di compilazione ha bisogno per la ricompilazione. Ad esempio, se una dipendenza implementation cambia la sua API, Gradle ricompila solo quella dipendenza e i moduli che da questa dipendono direttamente. La maggior parte dei moduli dell'app e dei test dovrebbe utilizzare questa configurazione.

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 api cambia la sua API esterna, Gradle ricompila tutti i moduli che hanno accesso a quella dipendenza al momento della compilazione. Avere un numero elevato di dipendenze api può aumentare notevolmente i tempi di creazione. A meno che tu non voglia esporre l'API di una dipendenza a un modulo separato, i moduli delle librerie devono utilizzare le dipendenze implementation.

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 compileOnly con le dipendenze di Android Archive (AAR).

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
kapt
annotationProcessor

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 ksp, kapt o annotationProcessor. L'utilizzo di queste configurazioni migliora le prestazioni della build separando classpath di compilazione dal classpath del processore di annotazione. Se Gradle trova processori di annotazione sul classpath di compilazione, disattiva l' evitamento della compilazione, con un conseguente impatto negativo sulla durata della build (gradle 5.0 e versioni successive ignorano i processori di annotazione trovati nel classpath di compilazione).

Il plug-in Android 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 annotazioni che si trova sul classpath di compilazione, produce 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, utilizzalo come dipendenza ksp. Per maggiori dettagli sull'utilizzo dei processori di simboli Kotlin, consulta Eseguire la migrazione da kapt a ksp.
  • Se il processore non è disponibile come processore di simboli Kotlin:
    • Se il progetto include un'origine Kotlin (ma può includere anche l'origine Java), utilizza kapt per includerla.
    • Se il progetto utilizza solo l'origine Java, utilizza annotationProcessor per includerla.

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 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, garantendo che i controlli vengano eseguiti quando i consumer utilizzano la libreria.

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.

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

trendy

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 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 e LIB_B (in questo ordine)
  • Inoltre, LIB_A dipende da LIB_C e LIB_D (in questo ordine)
  • Anche LIB_B dipende da LIB_C

Quindi, l'ordine delle dipendenze fisse sarà il seguente:

  1. LIB_A
  2. LIB_D
  3. LIB_B
  4. 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'
}