Dodaj zależności kompilacji

System kompilacji Gradle w Android Studio umożliwia dodawanie zewnętrznych plików binarnych lub innych modułów biblioteki do kompilacji jako zależności. Zależność może znajdować się na komputerze lub w zdalnym repozytorium. Wszystkie deklarowane przez nią zależności pośrednie są automatycznie uwzględniane. Na tej stronie opisano, jak używać zależności w projekcie na Androida, w tym szczegóły dotyczące zachowań i konfiguracji specyficznych dla wtyczki Androida do obsługi Gradle (AGP). Pełniejszy przewodnik po zależnościach Gradle znajdziesz w przewodniku Gradle dotyczącym zarządzania zależnościami. Pamiętaj jednak, że Twój projekt na Androida może korzystać tylko z konfiguracji zależności zdefiniowanych na tej stronie.

Dodawanie biblioteki lub zależności wtyczki

Najlepszym sposobem dodawania zależności kompilacji i zarządzania nimi jest korzystanie z katalogów wersji, które są domyślnie używane w przypadku nowych projektów. 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 artykule Nowości w 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 (nie są częste) 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 lokalnej biblioteki modułowej (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:

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. Szczegółowe informacje znajdziesz w dokumentacji dotyczącej specyfikacji materiałowej.

3. Dodaj odwołanie do aliasu zależności do skryptu kompilacji modułów, które wymagają tej zależności. Podczas odwoływania się do aliasu w skrypcie kompilacji należy zastąpić jego podkreślenia i kreski kropkami. 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
   }

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

Konfigurowanie zależności

W bloku dependencies możesz zadeklarować zależność od biblioteki, korzystając z jednego z kilku różnych konfiguracji zależności (np. implementation pokazanej wcześniej). Każda konfiguracja zależności dostarcza Gradle różne instrukcje dotyczące korzystania z 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.

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

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:

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

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:

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

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

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

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ść, w jakiej wymieniasz zależności, wskazuje ich priorytet: pierwsza biblioteka ma wyższy priorytet niż druga, druga wyższy niż trzecia 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).
• Funkcja LIB_B zależy też 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ściach w Konsoli Play

Podczas kompilowania aplikacji AGP zawiera metadane opisujące zależności bibliotek, które są kompilowane w aplikacji. Podczas przesyłania aplikacji Konsola Play sprawdza te metadane, aby wyświetlać alerty o znanych problemach z pakietami SDK i zależnościami, których używa aplikacja. W niektórych przypadkach może też wyświetlać informacje, które pomogą Ci rozwiązać te problemy.

Dane są kompresowane, szyfrowane za pomocą klucza podpisywania Google Play i przechowywane w bloku podpisywania aplikacji. Zalecamy zachowanie tego pliku zależności, aby zapewnić użytkownikom bezpieczne i pozytywne wrażenia. 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 stronie pomocy poświęconej korzystaniu w aplikacji z pakietów SDK innych firm.

Statystyki 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 są sygnałem, że należy zaktualizować te zależności, ponieważ korzystanie z nieaktualnych wersji może uniemożliwić opublikowanie aplikacji 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:

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

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:

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

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ą elementu include: w pliku settings.gradle.kts. Podczas kompilowania aplikacji system kompilacji kompiluje moduł biblioteki i przechowuje wynikową skompilowaną zawartość w aplikacji.

Plik build.gradle deklaruje też zależność od wtyczki Gradle dla Androida (com.application.android). Jeśli masz kilka modułów, które korzystają z tego samego wtyczka, w ścieżce klas build.gradle może być tylko jedna wersja wtyczki. Zamiast określać wersję w każdym pliku skryptu kompilacji modułu, należy uwzględnić zależność wtyczki w pliku skryptu kompilacji głównego z wersją i wskazywać, aby 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łówny jest pusty, z wyjątkiem bloku 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
}

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

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

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