Dodaj zależności kompilacji

System kompilacji Gradle w Android Studio umożliwia dołączanie zewnętrznych plików binarnych lub innych modułów biblioteki do kompilacji jako zależności. Zależność może znajdować się na Twoim komputerze lub w zdalnym repozytorium. Wszystkie deklarowane przez nią zależności uogólnione są również automatycznie uwzględniane. Na tej stronie opisano, jak używać zależności w projekcie Androida, w tym szczegóły dotyczące zachowań i konfiguracji, które są specyficzne dla wtyczki Androida do obsługi Gradle (AGP). Aby uzyskać bardziej szczegółowy przewodnik po zależnościach Gradle, zapoznaj się z przewodnikiem po Gradle dotyczącym zarządzania zależnościami. Pamiętaj, że Twój projekt na Androida musi używać tylko konfiguracji zależności zdefiniowanych na tej stronie.

Uwaga: podczas określania zależności nie należy używać dynamicznych numerów wersji, takich jak 'com.android.tools.build:gradle:3.+'. Korzystanie z tej funkcji może powodować nieoczekiwane aktualizacje wersji, utrudniać rozwiązywanie różnic między wersjami i obniżać wydajność.

Dodawanie biblioteki lub zależności wtyczki

Najlepszym sposobem na dodawanie zależności kompilacji i zarządzanie nimi jest używanie katalogów wersji, czyli metody, z której domyślnie korzystają nowe projekty. W tej sekcji omawiamy najpopularniejsze typy konfiguracji używanych w projektach na Androida. Więcej opcji znajdziesz w dokumentacji Gradle. Przykład aplikacji, która korzysta z katalogów wersji, znajdziesz w sekcji Teraz na Androidzie. Jeśli masz już skonfigurowane zależności kompilacji bez katalogów wersji i projekt wielomodułowy, zalecamy migrację.

Wskazówki dotyczące dodawania zależności natywnych i zarządzania nimi (nietypowe) znajdziesz w artykule Zależności natywne.

W tym przykładzie dodajemy do projektu zależność od zdalnej biblioteki binarnej (biblioteka Jetpack Macrobenchmark), zależność od modułu lokalnej biblioteki (myLibrary) oraz zależność od wtyczki (wtyczka Androida do obsługi Gradle). Oto ogólne czynności, które należy wykonać, aby dodać te zależności do projektu:

Uwaga: możesz zadeklarować katalogi wersji w pliku ustawień, ale zalecamy użycie osobnego pliku toml, aby uzyskać dodatkową pomoc dotyczącą sugerowanych kodów i wyróżnień w Android Studio.

1. W sekcji [versions] pliku katalogu wersji dodaj alias wybranej wersji zależności o nazwie libs.versions.toml (w katalogu gradle w widoku Projekt lub Skrypty Gradle w widoku Android):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Aliasy mogą zawierać myślniki lub podkreślenia. Te aliasy generują wartości zagnieżdżone, do których możesz się odwoływać w skryptach kompilacji. Odwołania zaczynają się od nazwy katalogu, czyli części libs w elementach libs.versions.toml. Jeśli używasz katalogu z jedną wersją, zalecamy zachowanie domyślnej wartości „libs”.

2. Dodaj alias zależności w sekcji [libraries] (w przypadku binarnych plików zdalnych lub lokalnych modułów biblioteki) lub [plugins] (w przypadku wtyczek) w pliku 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" }
   

   Niektóre biblioteki są dostępne w publikowanym zestawie materiałów (BOM), który grupuje rodziny bibliotek i ich wersje. Możesz uwzględnić plik BOM w katalogu wersji i plikach kompilacji, a następnie pozwolić mu zarządzać tymi wersjami. Więcej informacji znajdziesz w artykule Używanie specyfikacji materiałowej.

3. Dodaj odwołanie do aliasu zależności do skryptu kompilacji modułów, które wymagają tej zależności. Zamień podkreślenia i myślniki aliasu na kropki, gdy odwołasz się do niego w skrypcie kompilacji. Nasz skrypt kompilacji na poziomie modułu będzie wyglądał tak:

   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
   }

   Odniesienia do wtyczek zawierają kod plugins po nazwie katalogu, a odwołania do wersji zawierają po nazwie katalogu ciąg versions (odwołania do wersji są rzadkością – przykłady odwołań do wersji znajdziesz w sekcji Zależności z takimi samymi numerami wersji). Odwołania do biblioteki nie zawierają kwalifikatora libraries, więc nie możesz użyć właściwości versions ani plugins na początku aliasu biblioteki.

Skonfiguruj zależności

W bloku dependencies możesz zadeklarować zależność biblioteki, korzystając z jednej z kilku różnych konfiguracji zależności (np. implementation przedstawionych wcześniej). Każda konfiguracja zależności przekazuje Gradle różne instrukcje użycia tej zależności. W tabeli poniżej opisujemy poszczególne konfiguracje, których możesz używać w przypadku zależności w projekcie na Androida.

Konfiguracja	Działanie
implementation	Gradle dodaje zależność do ścieżki kompilacji i pakuje ją do danych wyjściowych kompilacji. Gdy moduł konfiguruje zależność implementation, informuje Gradle, że nie chcesz, aby moduł przekazywał tę zależność do innych modułów w czasie kompilacji. Oznacza to, że zależność ta nie jest dostępna dla innych modułów zależnych od bieżącego. Korzystanie z tej konfiguracji zależności zamiast api może znacznie skrócić czas kompilacji, ponieważ zmniejsza liczbę modułów, które system kompilacji musi ponownie skompilować. Jeśli na przykład zależność implementation zmienia swój interfejs API, Gradle ponownie skompiluje tylko tę zależność i moduły, które są od niej bezpośrednio zależne. W przypadku większości aplikacji i modułów testowych należy użyć tej konfiguracji.
api	Gradle dodaje zależność do ścieżki klasy kompilacji i danych wyjściowych kompilacji. Gdy moduł zawiera zależność api, informuje on Gradle, że chce on przenieść zależność do innych modułów, aby była ona dostępna zarówno w czasie działania, jak i podczas kompilacji. Używaj tej konfiguracji ostrożnie i tylko w przypadku zależności, które musisz eksportować do innych konsumentów na wyższym poziomie. Jeśli zależność api zmieni swój zewnętrzny interfejs API, Gradle ponownie skompiluje wszystkie moduły, które mają dostęp do tej zależności w momencie kompilacji. Duża liczba zależności api może znacznie wydłużyć czas kompilacji. Jeśli nie chcesz udostępniać interfejsu API zależności osobnemu modułowi, moduły bibliotek powinny używać zależności implementation.
compileOnly	Gradle dodaje zależność tylko do ścieżki kompilacji (czyli nie jest ona dodawana do danych wyjściowych kompilacji). Jest to przydatne, gdy tworzysz moduł Androida i potrzebujesz zależności podczas kompilacji. Możesz też umieścić go w czasie działania. Jeśli na przykład korzystasz z biblioteki, która zawiera tylko adnotacje podczas kompilacji (zwykle jest ona używana do generowania kodu, ale często nie jest uwzględniana w danych wyjściowych kompilacji), możesz oznaczyć ją jako compileOnly. Jeśli używasz tej konfiguracji, moduł biblioteki musi zawierać warunek czasu wykonywania, aby sprawdzić, czy zależność jest dostępna, a następnie łagodnie zmienić swoje działanie, aby nadal działał, jeśli zależność nie jest dostępna. Pomaga to zmniejszyć rozmiar końcowej aplikacji, ponieważ nie dodaje tymczasowych zależności, które nie są kluczowe. Uwaga: nie możesz używać konfiguracji compileOnly z zależnościami z archiwum Androida (AAR).
runtimeOnly	Gradle dodaje zależność tylko do danych wyjściowych kompilacji, która jest używana w czasie działania. Oznacza to, że nie jest ona dodawana do ścieżki kompilacji. Rzadko jest używana na Androidzie, ale powszechnie używa się w aplikacjach serwerowych do implementacji logowania. Na przykład biblioteka może używać interfejsu API do rejestrowania, który nie zawiera implementacji. Użytkownicy tej biblioteki mogą dodać ją jako zależność implementation i uwzględnić zależność runtimeOnly dla rzeczywistej implementacji logowania, której mają używać.
ksp kapt annotationProcessor	Te konfiguracje udostępniają biblioteki, które przetwarzają adnotacje i inne symbole w kodzie przed jego skompilowaniem. Zazwyczaj weryfikują kod lub generują dodatkowy kod, co zmniejsza ilość kodu, który musisz napisać. Aby dodać taką zależność, musisz ją dodać do ścieżki klas procesora adnotacji za pomocą konfiguracji ksp, kapt lub annotationProcessor. Użycie tych konfiguracji zwiększa wydajność kompilacji przez oddzielenie ścieżki klasy kompilacji od ścieżki klasy procesora adnotacji. Jeśli Gradle znajdzie procesory adnotacji w ścieżce kompilacji, dezaktywuje unikanie kompilacji, co negatywnie wpływa na czas kompilacji (Gradle w wersji 5.0 i nowszej ignoruje procesory adnotacji znalezione w ścieżce kompilacji). Wtyczka Androida do obsługi Gradle zakłada, że zależność jest procesorem adnotacji, jeśli plik JAR zawiera ten plik: META-INF/services/javax.annotation.processing.Processor Jeśli w pluginie zostanie wykryty procesor adnotacji, który znajduje się na ścieżce kompilacji, wystąpi błąd kompilacji. ksp to procesor symboli Kotlin uruchamiany przez kompilator Kotlin. kapt i apt to osobne narzędzia, które przetwarzają adnotacje przed wykonaniem kompilatorów Kotlin lub Java. Wybierając konfigurację, weź pod uwagę te kwestie: Jeśli procesor jest dostępny jako procesor symboli Kotlina, użyj go jako zależności ksp. Szczegółowe informacje o używaniu procesorów symboli Kotlina znajdziesz w artykule Migracja z kapt na ksp. Jeśli procesor nie jest dostępny jako procesor symboli Kotlin: Jeśli Twój projekt zawiera kod źródłowy Kotlin (ale może też zawierać kod źródłowy Java), użyj kapt, aby go uwzględnić. Jeśli w Twoim projekcie używane jest tylko źródło w Javie, dodaj je za pomocą annotationProcessor. Więcej informacji o używaniu procesorów adnotacji znajdziesz w artykule Dodawanie procesorów adnotacji.
lintChecks	Użyj tej konfiguracji, aby dołączyć bibliotekę zawierającą testy lintowania, które ma być wykonywane przez Gradle podczas tworzenia projektu aplikacji na Androida. Pamiętaj, że pliki AAR zawierające plik lint.jar automatycznie przeprowadzają kontrole zdefiniowane w tym pliku. Nie musisz dodawać jawnej zależności lintChecks.lint.jar Dzięki temu możesz zdefiniować biblioteki i powiązane kontrole lintowania w jednej zależności, dzięki czemu masz pewność, że testy są wykonywane, gdy konsumenci korzystają z Twojej biblioteki.
lintPublish	Użyj tej konfiguracji w projektach bibliotek na Androida, aby uwzględnić kontrole lint, które chcesz skompilować w pliku lint.jar i zapakować w pliku AAR. Dzięki temu w projektach, które wykorzystują AAR, stosowane są również testy lint. Jeśli wcześniej używałeś/używałaś konfiguracji zależności lintChecks, aby uwzględnić w opublikowanym pliku AAR sprawdzanie lint, musisz przenieść te zależności, aby zamiast tego używać konfiguracji 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') }

Konfigurowanie zależności dla konkretnego wariantu kompilacji

Wszystkie powyższe konfiguracje stosują zależności do wszystkich wariantów kompilacji. Jeśli chcesz zadeklarować zależność tylko w przypadku konkretnego zestawu źródeł wariantu kompilacji lub testów, musisz użyć nazwy konfiguracji z dużych liter i dodać do niej nazwę wariantu kompilacji lub zestawu źródeł testów.

Aby na przykład dodać zdalne binarne zależności tylko do wersji „free” produktu za pomocą konfiguracji implementation, użyj tego kodu:

Kotlin

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

Odlotowe

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

Jeśli jednak chcesz dodać zależność dla wariantu, który łączy wersję produktu i typ kompilacji, musisz zainicjować nazwę konfiguracji:

Kotlin

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

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

Odlotowe

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

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

Dodawanie zależności implementation do testów lokalnych i testów z instrumentacją:

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'
}

W tej sytuacji niektóre konfiguracje nie mają jednak sensu. Na przykład inne moduły nie mogą zależeć od androidTest, więc jeśli używasz konfiguracji androidTestApi, wyświetla się to ostrzeżenie:

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

Kolejność zależności

Kolejność wyświetlania zależności wskazuje na ich priorytet: pierwsza biblioteka ma wyższy priorytet niż druga, druga itd. Ta kolejność jest ważna w przypadku łączenia zasobów lub łączenia elementów manifestu z bibliotek do aplikacji.

Jeśli na przykład Twój projekt deklaruje:

• Zależność od LIB_A i LIB_B (w tej kolejności)
• LIB_A zależy od LIB_C i LIB_D (w tej kolejności).
• LIB_B zależy również od: LIB_C

Wtedy kolejność zależności płaskich będzie wyglądać tak:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Dzięki temu zarówno LIB_A, jak i LIB_B mogą zastąpić LIB_C, a LIB_D nadal ma wyższy priorytet niż LIB_B, ponieważ LIB_A (od którego zależy) ma wyższy priorytet niż LIB_B.

Więcej informacji o tym, jak scalać manifesty z różnych źródeł/zależności projektu, znajdziesz w artykule Scalanie wielu plików manifestu.

Informacje o zależności w Konsoli Play

Podczas tworzenia aplikacji architektura AGP zawiera metadane opisujące zależności dotyczące bibliotek. Podczas przesyłania aplikacji Konsola Play sprawdza te metadane, aby wyświetlić alerty o znanych problemach z pakietami SDK i zależnościami, z których korzysta, a w niektórych przypadkach przekazać przydatne informacje zwrotne w celu rozwiązania tych problemów.

Dane są kompresowane, szyfrowane kluczem podpisywania Google Play i przechowywane w bloku podpisywania aplikacji w wersji. Zalecamy przechowywanie tego pliku zależności ze względu na bezpieczeństwo i pozytywne wrażenia użytkowników. Możesz zrezygnować z tego sposobu, dodając ten blok kodu dependenciesInfo w pliku build.gradle.kts modułu.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Więcej informacji o naszych zasadach i potencjalnych problemach z zależnościami znajdziesz na naszej stronie pomocy dotyczącej korzystania w aplikacji z pakietów SDK innych firm.

Statystyki dotyczące pakietu SDK

W Android Studio w pliku katalogu wersji i w oknie dialogowym Struktura projektu dla publicznych pakietów SDK na platformie Google Play SDK Index wyświetlane są ostrzeżenia lint w przypadku tych problemów:

• Pakiety SDK są oznaczone przez ich autorów jako przestarzałe.
• Pakiety SDK naruszają zasady Google Play.

Ostrzeżenia sygnalizują, że trzeba zaktualizować te zależności, ponieważ używanie nieaktualnych wersji może uniemożliwić publikowanie w Konsoli Google Play w przyszłości.

Dodawanie zależności kompilacji bez katalogów wersji

Zalecamy korzystanie z katalogów wersji do dodawania zależności i zarządzania nimi, ale proste projekty mogą ich nie wymagać. Oto przykład pliku kompilacji, który nie używa katalogów wersji:

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

Ten plik kompilacji deklaruje zależność od wersji 12.3 biblioteki „app-magic” w grupie przestrzeni nazw „com.example.android”. Deklaracja zależności binarnych z dalszego serwera to skrót od:

Kotlin

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

Groovy

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

Plik kompilacji deklaruje też zależność od modułu biblioteki Androida o nazwie „mylibrary”. Nazwa ta musi być zgodna z nazwą biblioteki zdefiniowaną za pomocą include: w pliku settings.gradle.kts. Podczas tworzenia aplikacji system kompilacji kompiluje moduł biblioteki i umieszcza w aplikacji powstałą w ten sposób skompilowaną zawartość.

Plik kompilacji deklaruje również zależność od wtyczki Androida do obsługi Gradle (com.application.android). Jeśli masz kilka modułów korzystających z tej samej wtyczki, w ścieżce klasy kompilacji dla wszystkich modułów możesz mieć tylko jedną wersję wtyczki. Zamiast określać wersję w każdym ze skryptów kompilacji modułu, uwzględnij zależność wtyczki w głównym skrypcie kompilacji i wskaż wersję, by jej nie stosować. Dodanie apply false powoduje, że Gradle zapisuje wersję wtyczki, ale nie używa jej w kompilacji głównej. Zwykle skrypt kompilacji głównej jest pusty, z wyjątkiem bloku 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
}

Jeśli masz projekt z jednym modułem, możesz wyraźnie określić wersję w skrypcie kompilacji na poziomie modułu i pozostawić skrypt kompilacji na poziomie projektu pusty:

Kotlin

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

Groovy

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