Configurare il plug-in Android Gradle Library per KMP

Il plug-in Gradle com.android.kotlin.multiplatform.library è lo strumento supportato ufficialmente per aggiungere un target Android a un modulo della libreria Kotlin Multiplatform (KMP). Semplifica la configurazione del progetto, migliora le prestazioni di build e offre una migliore integrazione con Android Studio.

L'utilizzo del plug-in com.android.library per lo sviluppo di KMP dipende dalle API del plug-in Android per Gradle che sono deprecate e richiedono l'attivazione nel plug-in Android per Gradle 9.0 e versioni successive (quarto trimestre 2025). Queste API dovrebbero essere rimosse nel plug-in Android per Gradle 10.0 (seconda metà del 2026).

Per applicare questo plug-in, consulta la sezione Applica il plug-in Android-KMP. Se devi eseguire la migrazione dalle API legacy, consulta la guida alla migrazione.

Funzionalità e differenze principali

Il plug-in Android-KMP è progettato appositamente per i progetti KMP e si differenzia dal plug-in com.android.library standard per diversi aspetti chiave:

• Architettura a singola variante:il plug-in utilizza una singola variante, rimuovendo il supporto per le varianti di prodotto e i tipi di build, il che semplifica la configurazione e migliora il rendimento della build.

• Ottimizzato per KMP:il plug-in è progettato per le librerie KMP, con particolare attenzione al codice Kotlin condiviso e all'interoperabilità, omettendo il supporto per build native specifiche per Android, AIDL e RenderScript.

• Test disattivati per impostazione predefinita: sia i test delle unità sia quelli del dispositivo (strumentazione) sono disattivati per impostazione predefinita per migliorare la velocità di compilazione. Puoi attivarli se necessario.

• Nessuna estensione Android di primo livello:la configurazione viene gestita con un blocco androidLibrary all'interno di Gradle KMP DSL, mantenendo una struttura di progetto KMP coerente. Non è presente alcun blocco dell'estensione android di primo livello.

• Compilazione Java con attivazione esplicita:la compilazione Java è disattivata per impostazione predefinita. Utilizza withJava() nel blocco androidLibrary per abilitarlo. In questo modo i tempi di compilazione migliorano quando non è necessaria la compilazione Java.

Vantaggi del plug-in della libreria Android-KMP

Il plug-in Android-KMP offre i seguenti vantaggi per i progetti KMP:

• Prestazioni e stabilità di build migliorate: è progettato per velocità di build ottimizzate e stabilità migliorata all'interno dei progetti KMP. L'attenzione ai flussi di lavoro KMP contribuisce a un processo di compilazione più efficiente e affidabile.

• Integrazione IDE avanzata:offre un migliore completamento del codice, navigazione, debug ed esperienza complessiva degli sviluppatori quando si lavora con le librerie KMP Android.

• Configurazione semplificata del progetto: il plug-in semplifica la configurazione per i progetti KMP rimuovendo le complessità specifiche di Android, come le varianti di build. In questo modo, i file di build saranno più puliti e più facili da gestire. In precedenza, l'utilizzo del plug-in com.android.library nel progetto KMP poteva creare nomi di set di origine confusi, ad esempio androidAndroidTest. Questa convenzione di denominazione era meno intuitiva per gli sviluppatori che conoscono le strutture standard dei progetti KMP.

Problemi noti nel plug-in della libreria Android-KMP

Di seguito sono riportati i problemi noti che potrebbero verificarsi quando applichi il nuovo plug-in com.android.kotlin.multiplatform.library:

• L'anteprima di Compose non va a buon fine quando si utilizza il nuovo plug-in android-KMP

• NullPointerException nelle anteprime di Compose Multiplatform con il plug-in com.android.kotlin.multiplatform.library

• KMP memorizza la risoluzione delle dipendenze di compilazione comuni nella cache di configurazione che genera un errore durante la deserializzazione (solo Android)

• Supporto di sourceSetTree strumentato per la destinazione androidLibrary

Prerequisiti

Per utilizzare il plug-in com.android.kotlin.multiplatform.library, il progetto deve essere configurato con le seguenti versioni minime o successive:

• Plug-in Android per Gradle (AGP): 8.10.0
• Plug-in Kotlin Gradle (KGP): 2.0.0

Applica il plug-in Android-KMP a un modulo esistente

Per applicare il plug-in Android-KMP a un modulo di libreria KMP esistente, segui questi passaggi:

1. Dichiarare i plug-in nel catalogo delle versioni. Apri il file TOML del catalogo delle versioni (di solito gradle/libs.versions.toml) e aggiungi la sezione delle definizioni dei plug-in:

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "8.13.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. Applica la dichiarazione del plug-in nel file di build principale. Apri il file build.gradle.kts che si trova nella directory principale del progetto. Aggiungi gli alias del plug-in al blocco plugins utilizzando apply false. In questo modo, gli alias del plug-in sono disponibili per tutti i progetti secondari senza applicare la logica del plug-in al progetto principale stesso.

   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
   }

   Groovy

   // 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. Applica il plug-in in un file di build del modulo della libreria KMP. Apri il file build.gradle.kts nel modulo della libreria KMP e applica il plug-in all'inizio del file all'interno del blocco plugins:

   Kotlin

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

   Groovy

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

4. Configura la destinazione KMP di Android. Configura il blocco Kotlin Multiplatform (kotlin) per definire il target Android. All'interno del blocco kotlin, specifica la destinazione Android utilizzando androidLibrary:

   Kotlin

   kotlin {
      androidLibrary {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              sourceSetTreeName = "test"
          }
   
          compilations.configureEach {
              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.) ...
   }

   Groovy

   kotlin {
      androidLibrary {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              it.sourceSetTreeName = "test"
          }
   
          compilations.configureEach {
              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. Applica modifiche. Dopo aver applicato il plug-in e configurato il blocco kotlin, sincronizza il progetto Gradle per applicare le modifiche.

Eseguire la migrazione dal plug-in legacy

Questa guida ti aiuta a eseguire la migrazione dal plug-in com.android.library legacy al plug-in com.android.kotlin.multiplatform.library.

1. Dichiarare le dipendenze

Un'attività comune è la dichiarazione delle dipendenze per i set di origini specifici per Android. Il nuovo plug-in richiede che questi elementi vengano inseriti esplicitamente all'interno del blocco sourceSets, a differenza del blocco dependencies generale utilizzato in precedenza.

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

2. Attivare le risorse Android

Il supporto per le risorse Android (cartelle res) non è attivato per impostazione predefinita nel nuovo plug-in per ottimizzare le prestazioni di build. Per utilizzarli, devi attivare l'opzione. Questa modifica contribuisce a garantire che i progetti che non richiedono risorse specifiche per Android non siano appesantiti dal sovraccarico di build associato.

// 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

3. Configurazione dei test di host e dispositivo

Una modifica significativa nel nuovo plug-in è che i test lato host (unità) e lato dispositivo (strumentati) di Android sono disattivati per impostazione predefinita. Devi attivare esplicitamente la creazione di set e configurazioni di origini di test, mentre il vecchio plug-in li creava automaticamente.

Questo modello di attivazione contribuisce a verificare che il progetto rimanga snello e includa solo la logica di build e i set di origini che utilizzi attivamente.

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
    }
  }
}

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
  }
}

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

4. Abilita la compilazione dell'origine Java

Se la tua libreria KMP deve compilare origini Java per il target Android, devi abilitare esplicitamente questa funzionalità con il nuovo plug-in. Tieni presente che questo consente la compilazione per i file Java che si trovano direttamente all'interno del progetto, non per le sue dipendenze. Cambia anche il metodo per impostare la versione di destinazione della JVM del compilatore Java e Kotlin.

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

5. Interagire con le varianti di build utilizzando androidComponents

L'estensione androidComponents è ancora disponibile per interagire in modo programmatico con gli artefatti di build. Sebbene gran parte dell'API Variant rimanga invariata, la nuova interfaccia AndroidKotlinMultiplatformVariant è più limitata perché il plug-in produce una sola variante.

Di conseguenza, le proprietà correlate ai tipi di build e alle varianti di prodotto non sono più disponibili nell'oggetto variante.

// build.gradle.kts

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

// build.gradle.kts

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

6. Seleziona le varianti delle dipendenze della libreria Android

La libreria KMP produce una sola variante per Android. Tuttavia, potresti dipendere da una libreria Android standard (com.android.library) che ha più varianti (ad es. free/paid versioni prodotto). Controllare il modo in cui il progetto seleziona una variante da questa dipendenza è un requisito comune.

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

Riferimento API plug-in

Il nuovo plug-in ha una superficie API diversa da com.android.library. Per informazioni dettagliate sul nuovo DSL e sulle nuove interfacce, consulta i riferimenti API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant