Konfigurowanie wtyczki biblioteki Androida do obsługi Gradle na potrzeby KMP

Wtyczka com.android.kotlin.multiplatform.library do obsługi Gradle to oficjalnie obsługiwane narzędzie do dodawania celu Androida do modułu biblioteki Kotlin Multiplatform (KMP). Upraszcza konfigurację projektu, poprawia wydajność kompilacji i zapewnia lepszą integrację z Android Studio.

Używanie wtyczki com.android.library do programowania w KMP zależy od interfejsów API wtyczki Androida do obsługi Gradle, które zostały wycofane i wymagają akceptacji we wtyczce Androida do obsługi Gradle w wersji 9.0 i nowszych (IV kwartał 2025 r.). Te interfejsy API zostaną usunięte we wtyczce Androida do obsługi Gradle w wersji 10.0 (w drugiej połowie 2026 r.).

Aby zastosować tę wtyczkę, zapoznaj się z sekcją Stosowanie wtyczki Android-KMP. Jeśli chcesz przejść ze starszych interfejsów API, zapoznaj się z przewodnikiem po migracji.

Aby uzyskać pomoc dotyczącą migracji do AGP 9.0 lub nowszej wersji, możesz użyć umiejętności agenta utworzonej przez JetBrains dla aplikacji KMP. Więcej informacji o korzystaniu z umiejętności w Android Studio znajdziesz w artykule Rozszerzanie trybu agenta za pomocą umiejętności. Pamiętaj, że wyniki AI nie są całkowicie przewidywalne.

Najważniejsze funkcje i różnice

Wtyczka Android-KMP jest dostosowana specjalnie do projektów KMP i różni się od standardowej wtyczki com.android.library pod kilkoma kluczowymi względami:

• Architektura z jednym wariantem: wtyczka używa jednego wariantu, co eliminuje obsługę wariantów usługi i typów kompilacji, upraszczając konfigurację i zwiększając wydajność kompilacji.

• Optymalizacja pod kątem KMP: wtyczka jest przeznaczona do bibliotek KMP i skupia się na udostępnianym kodzie Kotlin oraz interoperacyjności, pomijając obsługę kompilacji natywnych na Androida, AIDL i RenderScript.

• Testy domyślnie wyłączone: testy jednostkowe i testy na urządzeniu (z instrumentacją) są domyślnie wyłączone, aby przyspieszyć kompilację. W razie potrzeby możesz je włączyć.

• Brak rozszerzenia Androida najwyższego poziomu: konfiguracja jest obsługiwana za pomocą bloku android w języku DSL KMP Gradle, co pozwala zachować spójną strukturę projektu KMP. Brak bloku rozszerzenia android najwyższego poziomu.

• Kompilacja Java z akceptacją: kompilacja Java jest domyślnie wyłączona. Aby go włączyć, użyj withJava() w bloku android. Skraca to czas kompilacji, gdy kompilacja Javy nie jest potrzebna.

Zalety wtyczki biblioteki Android-KMP

Wtyczka Android-KMP zapewnia te korzyści w przypadku projektów KMP:

• Lepsza wydajność i stabilność kompilacji: narzędzie zostało zaprojektowane pod kątem optymalizacji szybkości kompilacji i zwiększenia stabilności w projektach KMP. Skupienie się na przepływach pracy KMP przyczynia się do bardziej wydajnego i niezawodnego procesu kompilacji.

• Ulepszona integracja z IDE: zapewnia lepsze uzupełnianie kodu, nawigację, debugowanie i ogólne wrażenia dewelopera podczas pracy z bibliotekami KMP na Androida.

• Uproszczona konfiguracja projektu: wtyczka upraszcza konfigurację projektów KMP, usuwając złożone elementy związane z Androidem, takie jak warianty kompilacji. Dzięki temu pliki kompilacji są bardziej przejrzyste i łatwiejsze w utrzymaniu. Wcześniej użycie wtyczki com.android.library w projekcie KMP mogło powodować tworzenie mylących nazw zbiorów źródeł, takich jak androidAndroidTest. Ta konwencja nazewnictwa była mniej intuicyjna dla deweloperów znających standardowe struktury projektów KMP.

Obejścia nieobsługiwanych funkcji

W porównaniu z integracją KMP z wtyczką com.android.library wtyczka com.android.kotlin.multiplatform.library nie ma niektórych funkcji. Oto sposoby obejścia problemu z nieobsługiwanymi funkcjami:

• Warianty kompilacji

  Typy kompilacji i warianty usługi nie są obsługiwane. Wynika to z tego, że nowa wtyczka używa architektury z jednym wariantem, co upraszcza konfigurację i poprawia wydajność kompilacji.

  Jeśli potrzebujesz wariantów kompilacji, zalecamy utworzenie osobnego samodzielnego modułu biblioteki Androida za pomocą wtyczki com.android.library, skonfigurowanie typów kompilacji i wariantów usługi w tym module, a następnie użycie go jako standardowej zależności projektu ze zbioru źródeł androidMain biblioteki wieloplatformowej Kotlin. Więcej informacji znajdziesz w artykułach Tworzenie biblioteki Androida i Konfigurowanie wariantów kompilacji.

• Wiązanie danych i wiązanie widoku

  Są to funkcje platformy interfejsu na Androida, które są ściśle powiązane z systemem widoków Androida i układami XML. W przypadku nowej wtyczki biblioteki Android-KMP zalecamy obsługę interfejsu za pomocą platformy wieloplatformowej, takiej jak Compose Multiplatform. Wiązanie danych i wiązanie widoku są uważane za szczegóły implementacji ostatecznej aplikacji na Androida, a nie biblioteki, którą można udostępniać.

• Obsługa kompilacji natywnej

  Nowa wtyczka koncentruje się na tworzeniu standardowego pliku AAR dla środowiska docelowego Androida. Integracja kodu natywnego w Kotlin Multiplatform jest obsługiwana bezpośrednio przez własne cele natywne KMP (takie jak androidNativeArm64 i androidNativeX86) oraz możliwości współdziałania z C. Jeśli chcesz dołączyć natywny kod C/C++, zdefiniuj go jako część wspólnego lub natywnego zbioru źródeł i skonfiguruj współdziałanie z C w bloku kotlin, zamiast używać mechanizmu externalNativeBuild typowego dla Androida.

  Jeśli potrzebujesz obsługi kompilacji natywnej za pomocą externalNativeBuild, zalecamy utworzenie osobnego samodzielnego modułu com.android.library, w którym możesz zintegrować kod natywny, i wykorzystanie tej samodzielnej biblioteki ze zbioru źródeł androidMain projektu biblioteki Kotlin Multiplatform. Więcej informacji znajdziesz w artykułach Tworzenie biblioteki Androida i Dodawanie kodu C i C++ do projektu.

• BuildConfig klasa

  Funkcja BuildConfig jest najbardziej przydatna w środowiskach z wieloma wariantami. Nowa wtyczka biblioteki Kotlin Multiplatform nie jest zależna od wariantów i nie obsługuje typów kompilacji ani wariantów usługi, dlatego ta funkcja nie jest zaimplementowana. Zamiast tego zalecamy użycie wtyczki BuildKonfig lub podobnych rozwiązań społecznościowych do generowania metadanych dla wszystkich środowisk docelowych.

Wymagania wstępne

Aby używać wtyczki com.android.kotlin.multiplatform.library, musisz skonfigurować projekt z tymi minimalnymi wersjami lub nowszymi:

• Wtyczka Androida do obsługi Gradle (AGP): 8.10.0
• Wtyczka Kotlin Gradle (KGP): 2.0.0

Stosowanie wtyczki Android-KMP do istniejącego modułu

Aby zastosować wtyczkę Android-KMP do istniejącego modułu biblioteki KMP, wykonaj te czynności:

1. Zadeklaruj wtyczki w katalogu wersji. Otwórz plik TOML katalogu wersji (zwykle gradle/libs.versions.toml) i dodaj sekcję definicji wtyczek:

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "9.4.0"
   kotlin = "KOTLIN_VERSION"
   
   [plugins]
   kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
   android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "androidGradlePlugin" }
   

2. Zastosuj deklarację wtyczki w głównym pliku kompilacji. Otwórz plik build.gradle.kts znajdujący się w katalogu głównym projektu. Dodaj aliasy wtyczki do bloku plugins za pomocą apply false. Dzięki temu aliasy wtyczki są dostępne dla wszystkich podprojektów bez stosowania logiki wtyczki do samego projektu głównego.

   Kotlin

   // Root build.gradle.kts file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform) apply false
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library) apply false
   }

   Dynamiczny

   // Root build.gradle file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform) apply false
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library) apply false
   }

3. Zastosuj wtyczkę w pliku kompilacji modułu biblioteki KMP. Otwórz plik build.gradle.kts w module biblioteki KMP i zastosuj wtyczkę u góry pliku w bloku plugins:

   Kotlin

   // Module-specific build.gradle.kts file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

   Dynamiczny

   // Module-specific build.gradle file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

4. Skonfiguruj środowisko docelowe KMP na Androidzie. Skonfiguruj blok Kotlin Multiplatform (kotlin), aby zdefiniować środowisko docelowe Androida. W bloku kotlin określ środowisko docelowe Androida za pomocą android:

   Kotlin

   kotlin {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              sourceSetTreeName = "test"
          }
   
          compilerOptions.configure {
              jvmTarget.set(
                  org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
              )
          }
      }
   
      sourceSets {
          androidMain {
              dependencies {
                  // Add Android-specific dependencies here
              }
          }
          getByName("androidHostTest") {
              dependencies {
              }
          }
   
          getByName("androidDeviceTest") {
              dependencies {
              }
          }
      }
      // ... other targets (JVM, iOS, etc.) ...
   }

   Dynamiczny

   kotlin {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              it.sourceSetTreeName = "test"
          }
   
          compilerOptions.options.jvmTarget.set(
              org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
          )
      }
   
      sourceSets {
          androidMain {
              dependencies {
              }
          }
          androidHostTest {
              dependencies {
              }
          }
          androidDeviceTest {
              dependencies {
              }
          }
      }
      // ... other targets (JVM, iOS, etc.) ...
   }

5. Zastosuj zmiany. Po zastosowaniu wtyczki i skonfigurowaniu bloku kotlin zsynchronizuj projekt Gradle, aby zastosować zmiany.

Migracja ze starszej wtyczki

Ten przewodnik pomoże Ci przejść ze starszej wtyczki com.android.library na wtyczkę com.android.kotlin.multiplatform.library.

1. Przenoszenie źródeł

Starsza wtyczka umożliwiała korzystanie ze zbiorów źródeł src/main, src/test i src/androidTest, a także src/androidMain, src/androidHostTest i src/androidDeviceTest. Nowa wtyczka używa tylko tych drugich katalogów źródłowych, więc musisz przenieść źródła z src/main do src/androidMain, z src/test do src/androidHostTest i z src/androidTest do src/androidDeviceTest.

2. Konfigurowanie niestandardowych katalogów źródeł i zasobów

Jeśli masz źródła lub zasoby w niestandardowych katalogach, wcześniej skonfigurowano je za pomocą bloku sourceSets. W nowej wtyczce użyj rozszerzenia androidComponents, aby dodać do wariantu katalogi źródłowe statyczne.

Pamiętaj, że w przypadku nowej wtyczki metoda addStaticSourceDirectory dodaje katalog do istniejącej listy katalogów źródłowych. W przypadku starszej wtyczki metoda setSrcDirs zastępuje listę, a metoda srcDir dodaje do niej elementy.

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3. Deklarowanie zależności

Częstym zadaniem jest deklarowanie zależności dla zbiorów źródeł związanych z Androidem. Nowa wtyczka wymaga, aby były one umieszczone w bloku sourceSets, a nie w ogólnym bloku dependencies, który był używany wcześniej.

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. Włączanie zasobów Androida

Obsługa zasobów Androida (foldery res) nie jest domyślnie włączona w nowej wtyczce, aby zoptymalizować wydajność kompilacji. Aby korzystać z tej funkcji, musisz wyrazić na nią zgodę. Dzięki tej zmianie projekty, które nie wymagają zasobów związanych z Androidem, nie są obciążone dodatkowymi kosztami kompilacji.

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. Konfigurowanie testów hosta i urządzenia

Domyślnie nowa wtyczka wyłącza testy po stronie hosta (jednostkowe) i po stronie urządzenia (z instrumentacją) na Androidzie. Musisz wyraźnie wyrazić zgodę na tworzenie testowych zbiorów źródeł i konfiguracji, podczas gdy starsza wtyczka tworzyła je automatycznie.

Ten model akceptacji pomaga upewnić się, że projekt pozostaje prosty i zawiera tylko logikę kompilacji i zbiory źródeł, których aktywnie używasz.

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. Włącz kompilację źródła Java

Jeśli biblioteka KMP musi skompilować źródła Javy dla celu Androida, musisz wyraźnie włączyć tę funkcję za pomocą nowej wtyczki. Pamiętaj, że umożliwia to kompilację plików Java znajdujących się bezpośrednio w projekcie, a nie jego zależności. Zmienia się też metoda ustawiania docelowej wersji JVM kompilatora Javy i Kotlina.

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. Interakcja z wariantami kompilacji za pomocą androidComponents

Rozszerzenie androidComponents jest nadal dostępne do interakcji z artefaktami kompilacji w sposób zautomatyzowany. Chociaż interfejs API Variant pozostaje w dużej mierze taki sam, nowy interfejs AndroidKotlinMultiplatformVariant jest bardziej ograniczony, ponieważ wtyczka generuje tylko 1 wariant.

W związku z tym właściwości związane z typami kompilacji i wariantami usługi nie są już dostępne w obiekcie wariantu.

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. Wybieranie wariantów zależności biblioteki Androida

Biblioteka KMP tworzy jeden wariant na Androida. Możesz jednak korzystać ze standardowej biblioteki Androida (com.android.library), która ma wiele wariantów (np. free/paid wariantów usługi). Często trzeba kontrolować sposób, w jaki projekt wybiera wariant z tej zależności.

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

9. Dodawanie zależności podglądu Compose

Zwykle chcemy, aby określone biblioteki były ograniczone do naszego lokalnego środowiska programistycznego, aby zapobiec wyciekowi narzędzi wewnętrznych do ostatecznego opublikowanego artefaktu. W przypadku nowej wtyczki KMP do Androida stanowi to wyzwanie, ponieważ usuwa ona architekturę typu kompilacji używaną do oddzielania zależności programistycznych od kodu wersji.

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. Konfigurowanie środowiska docelowego JVM dla środowiska docelowego KMP na Androidzie

Wtyczka KMP na Androida ustawia środowisko docelowe JVM za pomocą android.compilerOptions.jvmTarget, co dotyczy zarówno Javy, jak i Kotlina, upraszczając konfigurację w porównaniu z osobnymi blokami compileOptions i kotlinOptions w projektach czysto androidowych.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. Opublikuj reguły przechowywania dla klientów

Jeśli biblioteka KMP musi dostarczać konsumentom reguły zachowywania (np. reguły ProGuard dla R8), musisz wyraźnie włączyć publikowanie za pomocą nowej wtyczki. Wcześniej reguły przechowywania konsumentów były domyślnie publikowane, jeśli zostały określone.

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. Publikowanie biblioteki w Maven

Jeśli planujesz opublikować bibliotekę KMP w Mavenie, aby mogła być używana przez inne projekty, proces będzie się różnić w zależności od tego, czy używasz nowej wtyczki Android-KMP czy starszej wtyczki.

Dokumentacja API wtyczki

Nowa wtyczka ma inny interfejs API niż com.android.library. Szczegółowe informacje o nowym języku DSL i interfejsach znajdziesz w dokumentacji API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Znane problemy z wtyczką biblioteki Android-KMP

Oto znane problemy, które mogą wystąpić po zastosowaniu nowej wtyczki com.android.kotlin.multiplatform.library:

• Błąd podglądu w Compose podczas korzystania z nowej wtyczki android-KMP

  • Poprawiono w Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 i Android Gradle Plugin 9.0.0-alpha13

• NullPointerException w podglądach Compose Multiplatform z wtyczką com.android.kotlin.multiplatform.library

  • Poprawiono w Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 i Android Gradle Plugin 9.0.0-alpha13

• KMP przechowuje rozwiązanie zależności wspólnej kompilacji w pamięci podręcznej konfiguracji, co prowadzi do błędu podczas deserializacji (tylko Android)

  • Poprawiono w Kotlin Gradle Plugin 2.3.0-Beta2

• Obsługa instrumentowanego elementu sourceSetTree dla celu androidLibrary

  • Poprawiono w Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 i Android Gradle Plugin 9.0.0-alpha13