Versions de Java dans les builds Android

Que votre code source soit écrit en Java, Kotlin ou les deux, vous devez choisir une version de JDK ou de langage Java pour votre build à plusieurs endroits.

Glossaire

Java Development Kit (JDK)

Le Java Development Kit (JDK) contient les éléments suivants :

• Des outils tels qu'un compilateur, un profileur et un créateur d'archives. Ils sont utilisés en coulisses lors de votre build pour créer votre application.
• Des bibliothèques contenant des API que vous pouvez appeler à partir de votre code source Kotlin ou Java. Notez que toutes les fonctions ne sont pas disponibles sur Android.
• La machine virtuelle Java (JVM), un interprète qui exécute les applications Java. Vous utilisez la JVM pour exécuter l'IDE Android Studio et l'outil de compilation Gradle. La JVM n'est pas utilisée sur les appareils ni les émulateurs Android.

JetBrains Runtime (JBR)

Le JetBrains Runtime (JBR) est un JDK amélioré, distribué avec Android Studio. Il inclut plusieurs optimisations pour une utilisation dans Studio et les produits JetBrains associés, mais il peut également être utilisé pour exécuter d'autres applications Java.

Comment choisir un JDK pour exécuter Android Studio ?

Nous vous recommandons d'utiliser le JBR pour exécuter Android Studio. Il est déployé avec Android Studio et utilisé pour le tester. Il inclut des améliorations pour une utilisation optimale d'Android Studio. Pour vous en assurer, ne définissez pas la variable d'environnement STUDIO_JDK.

Les scripts de démarrage d'Android Studio recherchent une JVM dans l'ordre suivant :

1. Variable d'environnement STUDIO_JDK
2. Répertoire studio.jdk (dans la distribution Android Studio)
3. Répertoire jbr (JetBrains Runtime), dans la distribution Android Studio. Recommandé.
4. Variable d'environnement JDK_HOME
5. Variable d'environnement JAVA_HOME
6. Exécutable java dans la variable d'environnement PATH

Comment choisir le JDK qui exécute mes builds Gradle ?

Si vous exécutez Gradle à l'aide des boutons d'Android Studio, le JDK défini dans les paramètres d'Android Studio est utilisé pour exécuter Gradle. Si vous exécutez Gradle dans un terminal, à l'intérieur ou à l'extérieur d'Android Studio, la variable d'environnement JAVA_HOME (si elle est définie) détermine le JDK qui exécute les scripts Gradle. Si JAVA_HOME n'est pas défini, il utilise la commande java sur votre variable d'environnement PATH.

Pour obtenir des résultats plus cohérents, assurez-vous de définir votre JAVA_HOME variable d'environnement, et configuration du JDK Gradle dans Android Studio sur le même JDK.

Lors de l'exécution de votre build, Gradle crée un processus appelé daemon pour effectuer le build proprement dit. Ce processus peut être réutilisé, à condition que les builds utilisent la même version de JDK et de Gradle. La réutilisation d'un daemon réduit le temps nécessaire pour démarrer une nouvelle JVM et initialiser le système de compilation.

Si vous démarrez des builds avec différents JDK ou versions de Gradle, des daemons supplémentaires sont créés, ce qui consomme plus de processeur et de mémoire.

Configuration du JDK Gradle dans Android Studio

Pour modifier la configuration du JDK Gradle du projet existant, ouvrez les paramètres Gradle en sélectionnant File (Fichier) (ou Android Studio sous macOS) > Settings > Build, Execution, Deployment > Build Tools > Gradle (Paramètres > Compilation, exécution, déploiement > Outils de compilation > Gradle). La liste déroulante Gradle JDK contient les options suivantes que vous pouvez sélectionner :

• Macros telles que JAVA_HOME et GRADLE_LOCAL_JAVA_HOME
• Entrées de table JDK au format vendor-version, comme jbr-17, qui sont stockées dans les fichiers de configuration Android
• Téléchargement d'un JDK
• Ajout d'un JDK spécifique
• JDK détectés localement à partir du répertoire d'installation du JDK par défaut du système d'exploitation

L'option sélectionnée est stockée dans l'option gradleJvm du fichier .idea/gradle.xml du projet, et sa résolution de chemin d'accès au JDK est utilisée pour exécuter Gradle lorsqu'il est démarré via Android Studio.

Les macros permettent une sélection dynamique du chemin d'accès au JDK du projet :

• JAVA_HOME : utilise la variable d'environnement du même nom
• GRADLE_LOCAL_JAVA_HOME: utilise la propriété java.home dans le fichier .gradle/config.properties, qui est définie par défaut sur le JetBrains Runtime.

Le JDK sélectionné est utilisé pour exécuter votre build Gradle et résoudre les références d'API JDK lorsque vous modifiez vos scripts de compilation et votre code source. Notez que le compileSdk spécifié limitera davantage les symboles Java disponibles lors de la modification et de la compilation de votre code source.

Veillez à choisir une version de JDK supérieure ou égale à celle des JDK utilisés par les plug-ins que vous utilisez dans votre build Gradle. Pour déterminer la version minimale requise du JDK pour le plug-in Android Gradle (AGP), consultez le tableau de compatibilité dans les notes de version.

Par exemple, le plug-in Android Gradle version 8.x nécessite JDK 17. Si vous essayez d'exécuter un build Gradle qui l'utilise avec une version antérieure du JDK, un message semblable à celui-ci s'affiche :

An exception occurred applying plugin request [id: 'com.android.application']
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in /usr/local/buildtools/java/jdk
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

Quelles API Java puis-je utiliser dans mon code source Java ou Kotlin ?

Une application Android peut utiliser certaines des API définies dans un JDK, mais pas toutes. Le SDK Android définit les implémentations de nombreuses fonctions de bibliothèque Java dans le cadre de ses API disponibles. La propriété compileSdk spécifie la version du SDK Android à utiliser lors de la compilation de votre code source Kotlin ou Java.

android {
    ...
    compileSdk = 36
}

android {
    ...
    compileSdk 36
}

Chaque version d'Android est compatible avec une version spécifique du JDK et un sous-ensemble de ses API Java disponibles. Si vous utilisez une API Java disponible dans un compileSdk qui n'est pas disponible dans le minSdk spécifié, vous pourrez peut-être utiliser l'API dans la version antérieure d'Android via un processus appelé désucrage. Pour connaître les API compatibles, consultez la section API Java 11 et versions ultérieures disponibles via le désucrage.

Utilisez ce tableau pour déterminer la version de Java compatible avec chaque API Android et où trouver des informations sur les API Java disponibles.

Quel JDK compile mon code source Java ?

Le JDK de la chaîne d'outils Java contient le compilateur Java utilisé pour compiler tout code source Java. Ce JDK exécute également javadoc et des tests unitaires lors du build.

La chaîne d'outils est définie par défaut sur le JDK utilisé pour exécuter Gradle. Si vous utilisez la valeur par défaut et exécutez un build sur différentes machines (par exemple, votre machine locale et un serveur d'intégration continue distinct), les résultats de votre build peuvent différer si différentes versions de JDK sont utilisées.

Pour créer un build plus cohérent, vous pouvez spécifier explicitement une version de la chaîne d'outils Java. En spécifiant ceci :

• Recherche un JDK compatible sur le système exécutant le build.
  • Si aucun JDK compatible n'existe (et qu'un résolveur de chaîne d'outils est défini), en télécharge un.
• Expose les API Java de la chaîne d'outils pour les appels à partir du code source.
• Compile la source Java à l'aide de sa version de langage Java.
• Fournit des valeurs par défaut pour sourceCompatibility et targetCompatibility.

Nous vous recommandons de toujours spécifier la chaîne d'outils Java et de vous assurer que le JDK spécifié est installé ou d'ajouter un résolveur de chaîne d'outils à votre build.

Vous pouvez spécifier la chaîne d'outils, que votre code source soit écrit en Java, Kotlin ou les deux. Spécifiez la chaîne d'outils au niveau supérieur du fichier build.gradle(.kts) de votre module.

Spécifiez la version de la chaîne d'outils Java comme suit :

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

Cela fonctionne si votre source est Kotlin, Java ou un mélange des deux.

La version du JDK de la chaîne d'outils peut être la même que celle du JDK utilisé pour exécuter Gradle, mais n'oubliez pas qu'ils ont des objectifs différents.

Quelles fonctionnalités de source de langage Java puis-je utiliser dans mon code source Java ?

La propriété sourceCompatibility détermine les fonctionnalités du langage Java disponibles lors de la compilation de la source Java. Elle n'affecte pas la source Kotlin.

Spécifiez sourceCompatibility dans le fichier build.gradle(.kts) de votre module comme suit :

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

Si elle n'est pas spécifiée, cette propriété est définie par défaut sur la chaîne d'outils Java version. Si vous n'utilisez pas de chaîne d'outils Java, elle est définie par défaut sur une version choisie par le plug-in Android Gradle (par exemple, Java 8 ou version ultérieure).

Quelles fonctionnalités binaires Java puis-je utiliser lorsque je compile ma source Kotlin ou Java ?

Les propriétés targetCompatibility et jvmTarget déterminent la version du format de classe Java utilisée lors de la génération de bytecode pour la source Java et Kotlin compilée, respectivement.

Certaines fonctionnalités Kotlin existaient avant l'ajout de fonctionnalités Java équivalentes. Les premiers compilateurs Kotlin devaient créer leur propre façon de représenter ces fonctionnalités Kotlin. Certaines de ces fonctionnalités ont ensuite été ajoutées à Java. Avec les niveaux jvmTarget ultérieurs, le compilateur Kotlin peut utiliser directement la fonctionnalité Java, ce qui peut améliorer les performances.

Différentes versions d'Android sont compatibles avec différentes versions de Java. Vous pouvez profiter de fonctionnalités Java supplémentaires en augmentant targetCompatibility et jvmTarget, mais cela peut vous obliger à augmenter également votre version minimale du SDK Android pour vous assurer que la fonctionnalité est disponible.

Notez que targetCompatibility doit être supérieur ou égal à sourceCompatibility. En pratique, sourceCompatibility, targetCompatibility et jvmTarget doivent généralement utiliser la même valeur. Vous pouvez les définir comme suit :

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget '17'
    }
}

Si elles ne sont pas spécifiées, ces propriétés sont définies par défaut sur la chaîne d'outils Java version. Si vous n'utilisez pas de chaîne d'outils Java, les valeurs par défaut peuvent différer et entraîner des problèmes de build. Par conséquent, nous vous recommandons de toujours spécifier explicitement ces valeurs ou d'utiliser une chaîne d'outils Java.