Configurer le plug-in de bibliothèque Android Gradle pour KMP

Le plug-in Gradle com.android.kotlin.multiplatform.library est l'outil officiellement compatible pour ajouter une cible Android à un module de bibliothèque Kotlin Multiplatform (KMP). Il simplifie la configuration du projet, améliore les performances de compilation et offre une meilleure intégration à Android Studio.

L'utilisation du plug-in com.android.library pour le développement KMP dépend des API du plug-in Android Gradle qui sont obsolètes et nécessitent une activation dans le plug-in Android Gradle 9.0 et versions ultérieures (quatrième trimestre 2025). Ces API devraient être supprimées dans le plug-in Android Gradle 10.0 (deuxième semestre 2026).

Pour appliquer ce plug-in, consultez la section Appliquer le plug-in Android-KMP. Si vous devez migrer à partir des anciennes API, consultez le guide de migration.

Pour obtenir de l'aide sur la migration vers AGP 9.0 ou version ultérieure, vous pouvez utiliser la compétence d'agent créée par JetBrains pour les applications KMP. Pour en savoir plus sur l'utilisation des compétences dans Android Studio, consultez Étendre le mode Agent avec des compétences. N'oubliez pas que les résultats de l'IA ne sont pas entièrement prévisibles.

Principales caractéristiques et différences

Le plug-in Android-KMP est spécialement conçu pour les projets KMP et diffère du plug-in com.android.library standard sur plusieurs points essentiels :

  • Architecture à variante unique : le plug-in utilise une seule variante, ce qui supprime la compatibilité avec les types de produits et les types de compilation, simplifie la configuration et améliore les performances de compilation.

  • Optimisé pour KMP : le plug-in est conçu pour les bibliothèques KMP, en mettant l'accent sur le code Kotlin partagé et l'interopérabilité, sans prendre en charge les builds natifs spécifiques à Android, AIDL et RenderScript.

  • Tests désactivés par défaut : les tests unitaires et les tests d'appareil (instrumentation) sont désactivés par défaut pour accélérer la compilation. Vous pouvez les activer si nécessaire.

  • Aucune extension Android de premier niveau : la configuration est gérée avec un bloc android dans le DSL KMP Gradle, ce qui permet de conserver une structure de projet KMP cohérente. Il n'y a pas de bloc d'extension android de premier niveau.

  • Activation de la compilation Java : la compilation Java est désactivée par défaut. Utilisez withJava() dans le bloc android pour l'activer. Cela améliore les temps de compilation lorsque la compilation Java n'est pas nécessaire.

Avantages du plug-in de bibliothèque Android-KMP

Le plug-in Android-KMP offre les avantages suivants pour les projets KMP :

  • Amélioration des performances et de la stabilité des builds : il est conçu pour optimiser la vitesse des builds et améliorer la stabilité des projets KMP. Son accent sur les workflows KMP contribue à un processus de compilation plus efficace et plus fiable.

  • Intégration améliorée de l'IDE : elle améliore la saisie semi-automatique du code, la navigation, le débogage et l'expérience globale des développeurs lorsqu'ils travaillent avec des bibliothèques Android KMP.

  • Configuration de projet simplifiée : le plug-in simplifie la configuration des projets KMP en supprimant les complexités spécifiques à Android, comme les variantes de compilation. Cela permet d'obtenir des fichiers de compilation plus propres et plus faciles à gérer. Auparavant, l'utilisation du plug-in com.android.library dans un projet KMP pouvait créer des noms d'ensembles de sources confus, tels que androidAndroidTest. Cette convention d'attribution de noms était moins intuitive pour les développeurs habitués aux structures de projet KMP standards.

Solutions pour les fonctionnalités non compatibles

Par rapport à l'intégration de KMP au plug-in com.android.library, certaines fonctionnalités sont manquantes dans le plug-in com.android.kotlin.multiplatform.library. Voici les solutions pour les fonctionnalités non compatibles :

  • Variantes de compilation

    Les types de compilation et les types de produits ne sont pas acceptés. En effet, le nouveau plug-in utilise une architecture à variante unique, ce qui simplifie la configuration et améliore les performances de compilation.

    Si vous avez besoin de variantes de compilation, nous vous recommandons de créer un module de bibliothèque Android autonome distinct à l'aide du plug-in com.android.library, de configurer les types de compilation et les types de produits dans ce module, puis de l'utiliser comme dépendance de projet standard à partir de l'ensemble de sources androidMain de votre bibliothèque Kotlin Multiplatform. Pour en savoir plus, consultez Créer une bibliothèque Android et Configurer des variantes de compilation.

  • Liaison de données et liaison de vue

    Il s'agit de fonctionnalités du framework d'UI spécifiques à Android, étroitement liées au système de vues Android et aux mises en page XML. Avec le nouveau plug-in de bibliothèque Android-KMP, nous vous recommandons de gérer l'UI à l'aide d'un framework multiplateforme tel que Compose Multiplatform. La liaison de données et la liaison de vue sont considérées comme des détails d'implémentation d'une application Android finale, et non comme une bibliothèque partageable.

  • Compatibilité avec les builds natifs

    Le nouveau plug-in se concentre sur la production d'un AAR standard pour la cible Android. L'intégration du code natif dans Kotlin Multiplatform est gérée directement par les propres cibles natives de KMP (comme androidNativeArm64 et androidNativeX86) et ses fonctionnalités d'interopérabilité C. Si vous devez inclure du code C/C++ natif, vous devez le définir dans un ensemble de sources commun ou natif, et configurer l'interopérabilité C dans le bloc kotlin, plutôt que d'utiliser le mécanisme externalNativeBuild spécifique à Android.

    Si vous avez besoin d'une compatibilité avec les builds natifs via externalNativeBuild, nous vous recommandons de créer un module com.android.library autonome distinct dans lequel vous pouvez intégrer du code natif, puis d'utiliser cette bibliothèque autonome à partir de l'ensemble de sources androidMain de votre projet de bibliothèque Kotlin Multiplatform. Pour en savoir plus, consultez Créer une bibliothèque Android et Ajouter du code C et C++ à votre projet.

  • Classe BuildConfig

    La fonctionnalité BuildConfig est particulièrement utile dans les environnements multivariantes. Étant donné que le nouveau plug-in de bibliothèque Kotlin Multiplatform est indépendant des variantes et n'est pas compatible avec les types de compilation et les types de produits, cette fonctionnalité n'est pas implémentée. Nous vous recommandons plutôt d'utiliser le plug-in BuildKonfig ou des solutions communautaires similaires pour générer des métadonnées pour toutes les cibles.

Prérequis

Pour utiliser le plug-in com.android.kotlin.multiplatform.library, votre projet doit être configuré avec les versions minimales suivantes ou ultérieures :

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

Appliquer le plug-in Android-KMP à un module existant

Pour appliquer le plug-in Android-KMP à un module de bibliothèque KMP existant, procédez comme suit :

  1. Déclarez les plug-ins dans le catalogue de versions. Ouvrez le fichier TOML du catalogue de versions (généralement gradle/libs.versions.toml) et ajoutez la section des définitions de plug-ins :

    # 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. Appliquez la déclaration du plug-in dans le fichier de compilation racine. Ouvrez le fichier build.gradle.kts situé dans le répertoire racine de votre projet. Ajoutez les alias de plug-in au bloc plugins à l'aide de apply false. Les alias de plug-in sont ainsi disponibles pour tous les sous-projets sans appliquer la logique du plug-in au projet racine lui-même.

    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. Appliquez le plug-in dans un fichier de compilation de module de bibliothèque KMP. Ouvrez le fichier build.gradle.kts dans votre module de bibliothèque KMP et appliquez le plug-in en haut de votre fichier dans le bloc 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. Configurer la cible KMP Android Configurez le bloc Kotlin Multiplatform (kotlin) pour définir la cible Android. Dans le bloc kotlin, spécifiez la cible Android à l'aide de 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.) ...
}

    Groovy

    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. Appliquez les modifications. Après avoir appliqué le plug-in et configuré le bloc kotlin, synchronisez votre projet Gradle pour appliquer les modifications.

Migrer depuis l'ancien plug-in

Ce guide vous aide à migrer de l'ancien plug-in com.android.library vers le plug-in com.android.kotlin.multiplatform.library.

1. Déplacer les sources

L'ancien plug-in vous permettait d'utiliser les ensembles de sources src/main, src/test et src/androidTest, en plus de src/androidMain, src/androidHostTest et src/androidDeviceTest. Le nouveau plug-in n'utilise que les répertoires sources de ce dernier. Vous devrez donc déplacer les sources de src/main vers src/androidMain, de src/test vers src/androidHostTest et de src/androidTest vers src/androidDeviceTest.

2. Configurer des répertoires de sources et de ressources personnalisés

Si vous avez des sources ou des ressources dans des répertoires non standards, vous les avez précédemment configurées à l'aide du bloc sourceSets. Avec le nouveau plug-in, utilisez l'extension androidComponents pour ajouter des répertoires sources statiques à la variante.

Notez qu'avec le nouveau plug-in, la méthode addStaticSourceDirectory ajoute le répertoire à la liste existante des répertoires sources. Avec l'ancien plug-in, la méthode setSrcDirs remplace la liste, tandis que la méthode srcDir l'ajoute.

Android-KMP

Avec le nouveau plug-in, utilisez le bloc onVariants pour interagir avec les sources de la variante.

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

Ancien plug-in

Avec le plug-in com.android.library, le bloc sourceSets était utilisé pour définir ou ajouter des répertoires sources.

// 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. Déclarer des dépendances

Une tâche courante consiste à déclarer des dépendances pour les ensembles de sources spécifiques à Android. Le nouveau plug-in nécessite que ces éléments soient explicitement placés dans le bloc sourceSets, contrairement au bloc dependencies général utilisé précédemment.

Android-KMP

Le nouveau plug-in favorise une structure plus propre en regroupant les dépendances Android dans l'ensemble de sources androidMain. En plus de l'ensemble de sources principal, il existe deux ensembles de sources de test, qui sont créés à la demande : androidDeviceTest et androidHostTest (consultez Configurer des tests d'hôte et d'appareil pour en savoir plus).

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

Les ensembles de sources ont des compilations Kotlin correspondantes nommées main, deviceTest et hostTest. Les ensembles de sources et les compilations peuvent être configurés dans le script de compilation comme suit :

// build.gradle.kts

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

Ancien plug-in

Avec l'ancien plug-in, vous pouviez déclarer des dépendances spécifiques à Android dans le bloc de dépendances de premier niveau, ce qui pouvait parfois prêter à confusion dans un module multiplate-forme.

// 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. Activer les ressources Android

La compatibilité avec les ressources Android (dossiers res) n'est pas activée par défaut avec le nouveau plug-in pour optimiser les performances de compilation. Vous devez l'activer pour l'utiliser. Cette modification permet de s'assurer que les projets ne nécessitant pas de ressources spécifiques à Android ne sont pas pénalisés par les frais de compilation associés.

Android-KMP

Vous devez activer explicitement le traitement des ressources Android. Les ressources doivent être placées dans src/androidMain/res.

// build.gradle.kts

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

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

Ancien plug-in

Le traitement des ressources était activé par défaut. Vous pouvez immédiatement ajouter un répertoire res dans src/main et commencer à ajouter des drawables XML, des valeurs, etc.

// 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. Configurer des tests d'hôte et d'appareil

Par défaut, le nouveau plug-in désactive les tests Android côté hôte (unitaires) et côté appareil (instrumentés). Vous devez explicitement accepter de créer les ensembles de sources et les configurations de test, alors que l'ancien plug-in les créait automatiquement.

Ce modèle d'activation permet de s'assurer que votre projet reste léger et n'inclut que la logique de compilation et les ensembles de sources que vous utilisez activement.

Android-KMP

Avec le nouveau plug-in, vous activez et configurez les tests dans le bloc kotlin.android. Cela rend la configuration plus explicite et évite de créer des composants de test inutilisés. L'ensemble de sources androidUnitTest devient androidHostTest (le répertoire de test passe de src/androidUnitTest à src/androidHostTest) et androidInstrumentedTest devient androidDeviceTest (le répertoire de test passe de src/androidInstrumentedTest à src/androidDeviceTest).

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

Ancien plug-in

Avec le plug-in com.android.library, les ensembles de sources androidUnitTest et androidInstrumentedTest sont créés par défaut. Vous configurez leur comportement dans le bloc android, généralement à l'aide du DSL testOptions.

// 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. Activer la compilation de la source Java

Si votre bibliothèque KMP doit compiler des sources Java pour sa cible Android, vous devez explicitement activer cette fonctionnalité avec le nouveau plug-in. Notez que cela active la compilation pour les fichiers Java situés directement dans votre projet, et non pour ses dépendances. La méthode permettant de définir la version cible de la JVM du compilateur Java et Kotlin change également.

Android-KMP

Vous devez activer la compilation Java en appelant withJava(). La cible JVM est désormais configurée directement dans le bloc kotlin { android {} } pour une configuration plus unifiée. La définition de jvmTarget ici s'applique à la compilation Kotlin et Java pour la cible Android.

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

Ancien plug-in

La compilation Java était activée par défaut. La cible JVM pour les sources Java et Kotlin a été définie dans le bloc android à l'aide de compileOptions.

// build.gradle.kts

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

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

7. Interagir avec les variantes de compilation à l'aide de androidComponents

L'extension androidComponents est toujours disponible pour interagir avec les artefacts de compilation de manière programmatique. Bien qu'une grande partie de l'API Variant reste inchangée, la nouvelle interface AndroidKotlinMultiplatformVariant est plus limitée, car le plug-in ne produit qu'une seule variante.

Par conséquent, les propriétés liées aux types de compilation et aux types de produits ne sont plus disponibles sur l'objet de variante.

Android-KMP

Le bloc onVariants n'itère désormais que sur une seule variante. Vous pouvez toujours accéder aux propriétés courantes telles que name et artifacts, mais pas à celles spécifiques au type de compilation.

// build.gradle.kts

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

Ancien plug-in

Avec plusieurs variantes, vous pouvez accéder aux propriétés spécifiques au type de compilation pour configurer les tâches.

// build.gradle.kts

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

8. Sélectionner des variantes de dépendances de bibliothèque Android

Votre bibliothèque KMP produit une seule variante pour Android. Toutefois, vous pouvez dépendre d'une bibliothèque Android standard (com.android.library) qui comporte plusieurs variantes (par exemple, des types de produit free/paid). Il est courant de devoir contrôler la façon dont votre projet sélectionne une variante de cette dépendance.

Android-KMP

Le nouveau plug-in centralise et clarifie cette logique dans le bloc kotlin.android.localDependencySelection. Il est ainsi beaucoup plus facile de savoir quelles variantes de dépendances externes seront sélectionnées pour votre bibliothèque KMP à variante unique.

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

Ancien plug-in

Vous avez configuré des stratégies de sélection des dépendances dans les blocs buildTypes and productFlavors. Pour ce faire, vous deviez souvent utiliser missingDimensionStrategy pour fournir un type par défaut pour une dimension que votre bibliothèque n'avait pas, ou matchingFallbacks dans un type spécifique pour définir un ordre de recherche.

Pour en savoir plus sur l'utilisation de l'API, consultez Résoudre les erreurs de correspondance.

9. Ajouter des dépendances d'aperçu Compose

En général, nous voulons que des bibliothèques spécifiques soient limitées à notre environnement de développement local pour éviter que des outils internes ne soient divulgués dans l'artefact publié final. Cela devient un problème avec le nouveau plug-in Android KMP, car il supprime l'architecture de type de compilation utilisée pour séparer les dépendances de développement du code de release.

Android-KMP

Pour ajouter une dépendance uniquement pour le développement et les tests locaux, ajoutez-la directement à la configuration du classpath d'exécution (dans le bloc dependencies de premier niveau) de la compilation Android principale. Cela permet de s'assurer que la dépendance est disponible au moment de l'exécution (par exemple, pour des outils tels que Compose Preview), mais qu'elle ne fait pas partie du chemin de classe de compilation ni de l'API publiée de votre bibliothèque.

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

Ancien plug-in

Les projets Kotlin multiplateforme qui utilisent le plug-in com.android.library pour la cible Android doivent utiliser la configuration debugImplementation, qui limite la dépendance au type de compilation de débogage et l'empêche d'être incluse dans la variante de release de la bibliothèque utilisée par les consommateurs.

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

10. Configurer la cible JVM pour la cible Android KMP

Le plug-in Android KMP définit la cible JVM à l'aide de android.compilerOptions.jvmTarget, qui s'applique à la fois à Java et à Kotlin, ce qui simplifie la configuration par rapport aux blocs compileOptions et kotlinOptions distincts dans les projets Android purs.

Android-KMP

Lorsque vous travaillez sur un projet Kotlin Multiplatform (KMP) incluant une cible Android, vous pouvez configurer la version cible de la JVM de plusieurs manières pour les compilateurs Kotlin et Java. Il est essentiel de comprendre la portée et la hiérarchie de ces configurations pour gérer la compatibilité du bytecode de votre projet.

Voici les trois principales façons de définir la cible JVM, classées par ordre de priorité croissant. Les valeurs de cible JVM qui ont une priorité plus élevée s'appliquent à un sous-ensemble plus petit de vos cibles configurées et remplacent les valeurs qui ont une priorité plus faible. Cela signifie que vous pouvez définir différentes versions de JVM pour différentes cibles et compilations au sein des cibles de votre projet.

Utiliser la chaîne d'outils Kotlin (priorité la plus faible)

La méthode la plus générale pour définir la cible JVM consiste à spécifier la chaîne d'outils dans le bloc kotlin de votre fichier build.gradle.kts. Cette approche définit la cible pour les tâches de compilation Kotlin et Java sur toutes les cibles basées sur la JVM de votre projet, y compris Android.

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

Cette configuration permet à kotlinc et javac de cibler la JVM 21. C'est un excellent moyen d'établir une référence cohérente pour l'ensemble de votre projet.

Utiliser les options du compilateur au niveau de la cible Android (priorité moyenne)

Vous pouvez spécifier la cible JVM spécifiquement pour la cible KMP Android dans le bloc android. Ce paramètre remplace la configuration jvmToolchain à l'échelle du projet et s'applique à toutes les compilations Android.

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

Dans ce cas, même si un jvmToolchain est défini sur une autre version, le code Kotlin et Java de la cible Android sera compilé pour cibler la JVM 11.

Utiliser les options du compilateur au niveau de la compilation (priorité la plus élevée)

Pour un contrôle plus précis, vous pouvez configurer les options du compilateur par compilation (par exemple, sur androidMain ou androidHostTest uniquement). Cela est utile si une compilation spécifique doit cibler une autre version de la JVM. Ce paramètre remplace à la fois la chaîne d'outils Kotlin et les options de niveau cible Android.

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

Cette configuration permet de s'assurer que toutes les compilations de la cible Android utilisent la JVM 11, ce qui offre un contrôle précis.

Ancien plug-in

Dans un projet KMP utilisant le plug-in de bibliothèque Android standard (com.android.library), la configuration est légèrement différente de celle du plug-in Android KMP (mais conceptuellement similaire).

Utiliser la chaîne d'outils Kotlin

La méthode kotlin.jvmToolchain() fonctionne de la même manière, en définissant sourceCompatibility et targetCompatibility pour Java, et jvmTarget pour Kotlin. Nous vous recommandons d'utiliser cette approche.

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

compileOptions et kotlinOptions

Si vous n'utilisez pas la chaîne d'outils Kotlin, vous devez configurer les cibles JVM à l'aide de blocs distincts pour Java et Kotlin.

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

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. Publier des règles de conservation pour les consommateurs

Si votre bibliothèque KMP doit fournir des règles de conservation (comme les règles ProGuard pour R8) à ses utilisateurs, vous devez explicitement activer la publication avec le nouveau plug-in. Auparavant, les règles de conservation des consommateurs étaient publiées par défaut si elles étaient spécifiées.

Android-KMP

Avec le nouveau plug-in, vous devez définir optimization.consumerKeepRules.publish = true et spécifier des fichiers de règles dans le bloc consumerKeepRules pour publier les règles de conservation des consommateurs.

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

Ancien plug-in

Avec com.android.library, tous les fichiers de règles spécifiés avec consumerProguardFiles dans android.defaultConfig sont publiés par défaut dans les artefacts de la bibliothèque.

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

12. Publier votre bibliothèque sur Maven

Si vous prévoyez de publier votre bibliothèque KMP sur Maven pour qu'elle soit utilisée par d'autres projets, le processus diffère selon que vous utilisez le nouveau plug-in Android-KMP ou l'ancien plug-in.

Android-KMP

Le plug-in com.android.kotlin.multiplatform.library s'intègre aux mécanismes de publication standards de Kotlin Multiplatform. Aucune étape spécifique à Android n'est requise au-delà du processus de publication de la bibliothèque KMP standard.

Pour publier votre bibliothèque, suivez la documentation officielle de JetBrains : Configurer la publication d'une bibliothèque multiplateforme.

Ancien plug-in

Lorsque vous utilisez com.android.library pour la cible Android dans un projet KMP, vous devez suivre le guide de publication de la bibliothèque Android standard pour préparer et publier l'artefact spécifique à Android (.aar).

Pour obtenir des instructions détaillées, consultez Préparer votre bibliothèque en vue de sa publication.

Documentation de référence de l'API du plug-in

La surface d'API du nouveau plug-in est différente de celle de com.android.library. Pour en savoir plus sur le nouveau DSL et les nouvelles interfaces, consultez la documentation de référence de l'API :

Problèmes connus liés au plug-in de bibliothèque Android-KMP

Voici les problèmes connus qui peuvent survenir lorsque vous appliquez le nouveau plug-in com.android.kotlin.multiplatform.library :