Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiungi dipendenze build

Il sistema di compilazione Gradle in Android Studio ti consente di includere file binari o altri moduli di libreria alla tua build come dipendenze. La possono trovarsi sulla tua macchina o in un repository remoto anche le dipendenze transitive che dichiarano vengono incluse automaticamente. In questa pagina viene descritto come utilizzare le dipendenze con il progetto Android, incluse quelle relative i dettagli su comportamenti e configurazioni specifici il plug-in Android Gradle (AGP). Per una guida concettuale più completa a Gradle di dipendenze, dovresti vedere anche Guida a Gradle per la gestione delle dipendenze ma ricorda che il tuo progetto Android deve utilizzare solo configurazioni di dipendenza definite in questa pagina.

Aggiungi una dipendenza libreria o plug-in

Il modo migliore per aggiungere e gestire le dipendenze della build è usare cataloghi delle versioni, è quello usato per impostazione predefinita dai nuovi progetti. Questa sezione tratta le più comuni tipi di configurazioni utilizzate per i progetti Android; consulta le Documentazione di Gradle per altre opzioni. Per un esempio di app che utilizza cataloghi delle versioni, vedi Ora su Android. Se hai già configurato le dipendenze della build senza cataloghi delle versioni e hai un progetto multimodulo, è in corso la migrazione.

Per indicazioni sull'aggiunta e la gestione delle dipendenze native (non comune), vedi Dipendenze native.

Nel seguente esempio, aggiungiamo un programma binario remoto della dipendenza (Jetpack Macrobenchmark libreria), modulo della biblioteca locale una dipendenza (myLibrary) e un plug-in (plug-in Android Gradle) al nostro progetto. Ecco le informazioni generali passaggi per aggiungere queste dipendenze al progetto:

Aggiungi un alias per la versione della dipendenza che vuoi nel Sezione [versions] del file di catalogo delle versioni, denominata libs.versions.toml (nella directory gradle in 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 utilizzando un catalogo a versione singola, consigliamo di mantenere il valore predefinito "libs".
Aggiungi un alias per la dipendenza in [libraries] (per binari remoti o moduli di librerie locali) o [plugins] (per 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 di materiali (BOM) pubblicata che raggruppa le famiglie di librerie e le relative versioni. Puoi includere un BOM nel catalogo delle versioni e file di build e lasciare che sia lui a gestire quelle versioni. Consulta Utilizzo della distinta base per i dettagli.
Aggiungi un riferimento all'alias di dipendenza allo script di build della che richiedono la dipendenza. Converti l'alias trattini bassi e trattini ai punti quando fai riferimento a questo elemento da uno script di build. Script di build a livello di modulo avrà 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 dei plug-in includono plugins dopo il nome del catalogo e i riferimenti alla versione includono versions dopo il nome del catalogo (versione i riferimenti sono rari; consulta la sezione Dipendenze. con gli stessi numeri di versione per esempi di riferimenti di versione.) Biblioteca riferimenti non includono un qualificatore libraries, quindi non puoi utilizzare versions o plugins all'inizio di una raccolta alias.

Configura le dipendenze

All'interno del blocco dependencies, puoi dichiarare una dipendenza dalla libreria utilizzando una di diverse configurazioni di dipendenze (ad esempio implementation mostrate precedenti). Ogni configurazione delle dipendenze fornisce a Gradle istruzioni su come usare la dipendenza. Nella tabella seguente sono descritti tutti delle configurazioni che puoi usare per una dipendenza nel tuo progetto Android.

Configurazione	Comportamento
`implementation`	Gradle aggiunge la dipendenza al parametro classpath di compilazione pacchettizza la dipendenza all'output della build. Quando ogni modulo configura una dipendenza `implementation`, comunicando a Gradle che non vuoi che il modulo trasmetta la dipendenza da altri moduli al momento della compilazione. Vale a dire che la dipendenza non viene reso disponibile agli altri moduli che dipendono dal modello in maggior dettaglio più avanti in questo modulo. Usa questa configurazione delle dipendenze anziché `api` può portare a miglioramenti significativi in termini di tempo di compilazione poiché riduce il numero di moduli necessari al sistema di compilazione da ricompilare. Ad esempio, se `implementation` la dipendenza cambia la sua API, Gradle ricompila solo questa dipendenza e i moduli che dipendono direttamente da questo. La maggior parte delle app e dei test devono usare questa configurazione.
`api`	Gradle aggiunge la dipendenza alla build classpath e alla build come output. Quando un modulo include una dipendenza `api`, comunicando a Gradle che il modulo vuole esportare transitivamente la dipendenza da altri moduli, in modo che sia disponibile sia il tempo di esecuzione che il tempo di compilazione. Usa questa configurazione con cautela e solo con dipendenze che devi esportare in modo transitivo gli altri consumatori a monte. Se La dipendenza `api` cambia la sua API esterna, Gradle ricompila tutti i moduli che hanno accesso a quella dipendenza in fase di compilazione nel tempo. La presenza di un numero elevato di dipendenze `api` può aumenta significativamente i tempi di creazione. A meno che tu non voglia esporre l'API delle dipendenze in un modulo separato, i moduli della libreria dovrebbero usano le dipendenze `implementation`.
`compileOnly`	Gradle aggiunge la dipendenza solo al classpath di compilazione (ovvero, non viene aggiunto all'output della build). Ciò è utile quando stai creando un modulo Android e ti serve la dipendenza ma la sua presenza in fase di runtime è facoltativa. Per 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, potresti contrassegnare la libreria come `compileOnly`. Se utilizzi questa configurazione, il modulo Libreria deve essere includi una condizione di runtime per verificare se la dipendenza è disponibile e poi modificarne il comportamento in modo che possa se non è fornita. Ciò consente di ridurre le dimensioni all'app finale senza aggiungere dipendenze temporanee che non sono critiche. Nota: non puoi utilizzare `compileOnly` con dipendenze dell'Archivio Android (AAR).
`runtimeOnly`	Gradle aggiunge la dipendenza solo all'output della build, per uso durante il runtime. Ciò significa che non viene aggiunto al classpath di compilazione. Viene usato raramente su Android, ma è comunemente usato nei server applicazioni per fornire implementazioni di logging. Ad esempio, un libreria potrebbe utilizzare un'API di logging che non include un implementazione. Gli utenti di quella libreria potrebbero aggiungerla come la dipendenza `implementation` e includi un Dipendenza `runtimeOnly` per il logging effettivo implementazione da usare.
`ksp kapt annotationProcessor`	Queste configurazioni forniscono librerie che elaborano le annotazioni e altri simboli nel codice prima che venga compilato. In genere convalidare il codice o generare codice aggiuntivo, riducendo il codice che per scrivere. Per aggiungere questa dipendenza, devi aggiungerla al classpath del processore di annotazioni utilizzando le configurazioni `ksp`, `kapt` o `annotationProcessor`. Utilizzo migliora le prestazioni della build separando i dati di compilazione classpath dal processore di annotazione classpath. Se Gradle trova processori di annotazione sul classpath di compilazione, evitare la compilazione, con un impatto negativo sul tempo di build (Gradle 5.0 e versioni successive ignorano i processori di annotazione trovati nella compilazione classpath). Il plug-in Android per Gradle presuppone che una dipendenza sia un'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 compila classpath, produce un errore di build. `ksp` è un processore di simboli Kotlin ed è eseguito dal compilatore Kotlin. `kapt` e `apt` sono strumenti separati che le annotazioni del processo prima dell'esecuzione dei compilatori Kotlin o Java. Quando decidi quale configurazione utilizzare, considera le seguenti: Se è disponibile un processore come processore di simboli Kotlin, usa come dipendenza `ksp`. Vedi Eseguire la migrazione da Kapt a ksp. per maggiori dettagli sull'utilizzo dei processori di simboli Kotlin. Se il processore non è disponibile come processore di simboli Kotlin: Se il tuo progetto include un'origine Kotlin (ma può anche includono il codice sorgente Java), usa `kapt` per includerla. Se il progetto utilizza solo codice sorgente Java, utilizza `annotationProcessor` per includerla. Per ulteriori informazioni sull'uso dei processori di annotazione, consulta Aggiungi processori di annotazione.
`lintChecks`	Utilizza questa configurazione per includere una libreria contenente lint controlli che vuoi che vengano eseguiti da Gradle durante la creazione della tua app per Android progetto. Tieni presente che gli AAR che contengono un file `lint.jar` eseguire automaticamente i controlli definiti nel file `lint.jar`. non devi aggiungere una dipendenza `lintChecks` esplicita. In questo modo puoi definire le librerie e i controlli lint associati in un unico la dipendenza, assicurando che i controlli vengano eseguiti quando i consumatori utilizzano libreria.
`lintPublish`	Utilizza questa configurazione nei progetti della libreria Android per includere il lint controlli che vuoi che Gradle compili in un file `lint.jar` e imballare il pacco nel tuo AAR. Questo fa sì che i progetti che utilizzano il tuo AAR per applicare anche i controlli lint. Se in precedenza utilizzavi la configurazione delle dipendenze `lintChecks` per includere il lint nell'AAR pubblicato, devi eseguire la migrazione delle 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 devi dichiarare una dipendenza solo per una specifica build set di origini di varianti o per un'origine di test impostata, devi scrivere in maiuscolo la configurazione e anteponigli il nome della variante di build o il set di origini di test.

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

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 un 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 dipendenze implementation per i test locali e i test instrumentati , 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, viene visualizzato quanto segue avviso se utilizzi la configurazione androidTestApi:

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

Ordine delle dipendenze

L'ordine in cui elencare le dipendenze indica la priorità di ciascuna: la prima libreria ha una priorità più alta della seconda, la seconda è più alta principale rispetto alla terza e così via. Questo ordine è importante nel caso in cui risorse unite o gli elementi manifest vengono uniti nella 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 quell'ordine)
E LIB_B dipende anche da LIB_C

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

LIB_A
LIB_D
LIB_B
LIB_C

Ciò garantisce che sia LIB_A sia LIB_B possano eseguire l'override LIB_C; e LIB_D ha ancora una priorità più alta di LIB_B perché LIB_A (che dipende) ha una priorità maggiore di LIB_B.

Per ulteriori informazioni su come si manifesta da diversi progetti le origini/dipendenze sono unite; consulta Unire più file manifest.

Informazioni sulle dipendenze per Play Console

Quando crei la tua app, AGP include i metadati che descrivono la libreria di dipendenze compilate nella tua app. Quando carichi l'app, lo strumento La console controlla questi metadati per fornire avvisi relativi a problemi noti relativi agli SDK delle dipendenze utilizzate dalla tua app e, in alcuni casi, fornire feedback strategici risolvere questi problemi.

I dati sono compressi, criptati da una chiave di firma di Google Play e archiviati in il blocco di firma della release dell'app. Consigliamo di conservare queste dipendenze per un'esperienza utente sicura e positiva. Puoi disattivare questa opzione includendo il persone che seguo 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 utilizzando SDK di terze parti nella tua app.

Approfondimenti sull'SDK

Android Studio mostra avvisi di lint nel file di catalogo delle versioni e nella sezione Finestra di dialogo della struttura per gli SDK pubblici nel 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 è necessario aggiornare queste dipendenze, l'utilizzo di versioni obsolete potrebbe impedirti di pubblicare su Google Play di Google Cloud in futuro.

Aggiungi dipendenze build senza cataloghi delle versioni

Ti consigliamo di usare i cataloghi delle versioni per aggiungere e gestire le dipendenze, ma potrebbero non essere necessari per alcuni progetti. 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"))
}

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 dalla versione 12.3 di "app-magic" all'interno della libreria "com.example.android" gruppo dello spazio dei nomi. Il programma binario remoto la dichiarazione delle dipendenze è un modo breve per:

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 anche una dipendenza da un modulo della libreria Android denominato "mialibreria"; questo nome deve corrispondere al nome della libreria definito con include: in il 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 nel dell'app.

Il file di build dichiara anche una dipendenza dal plug-in Android Gradle (com.application.android) Se hai più moduli che utilizzano lo stesso puoi avere una sola versione del plug-in nel classpath della build in tutti i moduli. Invece di specificare la versione in ogni modulo script di build, devi includere la dipendenza del plug-in nello script di build principale alla versione e indicare di non applicarla. L'aggiunta di apply false dice Gradle per annotare la versione del plug-in, ma non per utilizzarla nella build root. 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 lo script di build a livello di modulo e lascia 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'
}