Dodawanie zależności kompilacji

System kompilacji Gradle w Android Studio umożliwia dołączanie do kompilacji zewnętrznych plików binarnych lub innych modułów bibliotek jako zależności. Zależności mogą znajdować się na Twoim komputerze lub w zdalnym repozytorium. Wszystkie zadeklarowane przez nie zależności przechodnie są również automatycznie uwzględniane. Na tej stronie opisujemy, jak używać zależności w projekcie aplikacji na Androida, w tym szczegóły dotyczące zachowań i konfiguracji, które są specyficzne dla wtyczki Androida do obsługi Gradle (AGP). Bardziej szczegółowe informacje o zależnościach Gradle znajdziesz w przewodniku po zarządzaniu zależnościami w Gradle. Pamiętaj jednak, że Twój projekt aplikacji na Androida musi używać tylko konfiguracji zależności zdefiniowanych na tej stronie.

Dodawanie zależności biblioteki lub wtyczki

Najlepszym sposobem dodawania zależności kompilacji i zarządzania nimi jest używanie katalogów wersji, czyli metody, którą domyślnie stosują nowe projekty. W tej sekcji znajdziesz najczęstsze typy konfiguracji używane w projektach aplikacji na Androida. Więcej opcji znajdziesz w dokumentacji Gradle. Przykład aplikacji, która używa katalogów wersji, znajdziesz w Now in Android. Jeśli masz już skonfigurowane zależności kompilacji bez katalogów wersji i masz projekt wielomodułowy, zalecamy migrację.

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

W poniższym przykładzie do projektu dodano zdalną zależność binarną (bibliotekę Jetpack Macrobenchmark), zależność lokalnego modułu biblioteki (myLibrary) i zależność wtyczki (wtyczka Androida do obsługi Gradle). Oto ogólne instrukcje dodawania tych zależności do projektu:

1. Dodaj alias wersji zależności, której chcesz użyć, w sekcji [versions] pliku katalogu wersji 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ć łączniki i podkreślenia. Te aliasy generują zagnieżdżone wartości, do których można się odwoływać w skryptach kompilacji. Odwołania zaczynają się od nazwy katalogu, czyli części libs w libs.versions.toml. Jeśli używasz katalogu z jedną wersją, zalecamy pozostawienie domyślnej wartości „libs”.

2. Dodaj alias zależności w sekcji [libraries] (w przypadku zdalnych plików binarnych lub lokalnych modułów biblioteki) lub [plugins] (w przypadku wtyczek) 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 opublikowanym zestawieniu komponentów (BOM), które grupuje rodziny bibliotek i ich wersje. Możesz uwzględnić BOM w katalogu wersji i plikach kompilacji, aby zarządzał tymi wersjami za Ciebie. Więcej informacji znajdziesz w artykule Korzystanie z listy materiałów.

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 ze skryptu kompilacji zamień podkreślenia i myślniki na kropki. 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)
   }

   Dynamiczny

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   Odwołania do wtyczek zawierają plugins po nazwie katalogu, a odwołania do wersji zawierają versions po nazwie katalogu (odwołania do wersji są rzadkie; przykłady odwołań do wersji 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żywać versions ani plugins na początku aliasu biblioteki.

Konfigurowanie zależności

W bloku dependencies możesz zadeklarować zależność biblioteki, używając jednej 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 zależności. W tabeli poniżej opisujemy każdą konfigurację, której możesz użyć w przypadku zależności w projekcie aplikacji 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 dla konkretnego zbioru źródeł wariantu kompilacji lub testowego zbioru źródeł, musisz zapisać nazwę konfiguracji wielkimi literami i poprzedzić ją nazwą wariantu kompilacji lub testowego zbioru źródeł.

Aby na przykład dodać zdalną zależność binarną tylko do „bezpłatnego” wariantu usługi 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 wariant usługi 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")
}

Aby dodać zależności implementation do testów lokalnych i testów z instrumentacją, użyj tego kodu:

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

Jednak niektóre konfiguracje nie mają sensu w tej sytuacji. Na przykład inne moduły nie mogą zależeć od androidTest, więc jeśli użyjesz konfiguracji androidTestApi, zobaczysz 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, określa priorytet każdej z nich. Na przykład pierwsza biblioteka ma wyższy priorytet niż druga, a druga ma wyższy priorytet niż trzecia. Ta kolejność jest ważna, gdy zasoby są scalane lub elementy pliku manifestu są scalane z bibliotek w aplikacji.

Jeśli na przykład w projekcie zadeklarujesz:

• 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 też od LIB_C

W takim przypadku kolejność zależności będzie następująca:

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 (który od niego zależy) ma wyższy priorytet niż LIB_B.

Więcej informacji o łączeniu plików manifestu z różnych źródeł lub zależności projektu znajdziesz w artykule o łączeniu wielu plików manifestu.

Informacje o zależnościach w Konsoli Play

Podczas tworzenia aplikacji AGP uwzględnia 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 używanymi przez aplikację, a w niektórych przypadkach przekazywać przydatne informacje, które pomogą rozwiązać te problemy.

Dane są kompresowane, szyfrowane za pomocą klucza podpisywania Google Play i przechowywane w bloku podpisywania aplikacji w wersji produkcyjnej. Zalecamy zachowanie tego pliku zależności, aby zapewnić użytkownikom bezpieczeństwo i pozytywne wrażenia. Możesz zrezygnować, dodając ten blok 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 dotyczącej korzystania z pakietów SDK innych firm w aplikacji.

Statystyki dotyczące pakietów SDK

Android Studio wyświetla ostrzeżenia lintera w pliku katalogu wersji i w oknie Struktura projektu w przypadku publicznych pakietów SDK wymienionych na platformie Google Play SDK Index, gdy występują te problemy:

• Pakiety SDK są oznaczone przez autorów jako nieaktualne.
• Pakiety SDK naruszają zasady Google Play.
• Pakiety SDK mają znane luki w zabezpieczeniach.
• Pakiety SDK zostały wycofane przez ich autorów.

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

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

Zalecamy używanie katalogów wersji do dodawania zależności i zarządzania nimi, ale w przypadku prostych projektów może to nie być konieczne. 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 od zdalnego pliku binarnego jest skrótem 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”. Ta nazwa musi być zgodna z nazwą biblioteki zdefiniowaną za pomocą include: w pliku settings.gradle.kts. Podczas tworzenia aplikacji system kompilacji kompiluje moduł biblioteki i pakuje skompilowaną zawartość w aplikacji.

Plik kompilacji deklaruje też zależność od wtyczki Androida do obsługi Gradle (com.application.android). Jeśli masz kilka modułów, które używają tej samej wtyczki, we wszystkich modułach możesz mieć tylko jedną wersję wtyczki w ścieżce kompilacji. Zamiast określać wersję w każdym skrypcie kompilacji modułu, należy uwzględnić zależność wtyczki w głównym skrypcie kompilacji z wersją i wskazać, aby jej nie stosować. Dodanie apply false informuje Gradle, aby zanotował wersję wtyczki, ale nie używał jej w głównej kompilacji. Zwykle główny skrypt kompilacji jest pusty, z wyjątkiem tego 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 z jednym modułem, możesz określić wersję bezpośrednio w skrypcie kompilacji na poziomie modułu i pozostawić skrypt kompilacji na poziomie projektu pusty:

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

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