Gradle Wrapper, Toolchain et Boot plugin

1. La compilation comme partie de l'application

Si vous venez du monde des programmes en console, la compilation peut sembler être « juste appuyer sur Run ». Mais dès que le projet a au moins un collègue (ou un deuxième ordinateur), le classique commence : « chez moi ça marche, chez toi non, on se connecte, montre-moi l'écran ». Spring Boot en tant que plateforme aime la prévisibilité, et cela exige aussi une compilation prévisible.

Le squelette du projet est déjà là, mais sans règles de build claires, il reste juste un ensemble de fichiers. Après la génération, la question principale devient très pratique : comment faire en sorte que ce squelette s'assemble et se lance de la même façon sur n'importe quelle machine.

Imaginez que catalog-service est un plat. Le code ce sont les ingrédients, le conteneur Spring c'est la cuisine, et la compilation c'est la recette avec la température, le temps et les proportions exactes. Si la recette est « approximative », sur une plaque ça donnera quelque chose de correct, sur une autre — du charbon. C'est pourquoi dès le départ on fixe trois choses : quelle version de Gradle utiliser, quelle version de Java utiliser et quelles tâches Boot sont disponibles dans le projet.

Pour ne pas mélanger les termes, gardez en tête ce tableau simple — il économise beaucoup de nerfs :

bootJar

Ces trois points convergent ensuite au même endroit — dans build.gradle.kts. C'est pourquoi il est utile de comprendre d'abord leurs rôles séparément, puis de lire le fichier de build dans son ensemble. C'est précisément pour ça qu'il est important maintenant de ne pas juste appuyer sur Run, mais de comprendre sur quoi ce lancement repose.

2. Gradle Wrapper : « le Gradle qui vient avec le projet »

Dans un monde idéal, tout le monde a le même Gradle, la même Java et la même chance. Dans le monde réel, chaque développeur a son « zoo » sur le portable : certains ont Gradle 8, d'autres 9.4, d'autres encore ne l'ont jamais installé parce que « IntelliJ fait tout tout seul ». Le Gradle Wrapper est un moyen de rendre le projet indépendant de ces aléas.

Le Wrapper n'est pas un programme séparé « à la place de Gradle ». C'est un ensemble de fichiers dans votre projet qui garantit : quand vous lancez la compilation, vous lancez la version correcte de Gradle, celle choisie par le projet lui-même. Et oui, c'est l'une des raisons pour lesquelles dans les projets Boot on écrit dans le README les commandes avec ./gradlew, et non juste gradle.

Quand vous générez un projet dans Initializr, il ajoute le Wrapper automatiquement — et c'est parfait, parce que manuellement un débutant oubliera presque toujours quelque chose, puis dira : « mon Gradle est cassé », alors qu'en réalité il… n'était pas là.

La mini-carte des fichiers du Wrapper ressemble à ceci :

catalog-service/
├── gradlew
├── gradlew.bat
└── gradle/
    └── wrapper/
        ├── gradle-wrapper.properties
        └── gradle-wrapper.jar

Il est important de comprendre le rôle de chaque fichier sans mysticisme. gradlew — script pour Linux/macOS, gradlew.bat — pour Windows. Leur tâche est simple : lire les paramètres depuis gradle-wrapper.properties, télécharger la version de Gradle requise si elle n'est pas encore dans le cache, et lancer la compilation. gradle-wrapper.jar — le petit « moteur » du Wrapper, qui sait télécharger et démarrer la bonne version de Gradle.

Si vous pensez « et si je supprime gradle-wrapper.jar, c'est un binaire, c'est bizarre de le stocker dans git ? » — vous pouvez, mais alors vous retournez à l'âge de pierre : chacun lancera la compilation comme il peut. On ne fait pas ça. On veut que catalog-service soit portable.

Comment le Wrapper choisit Gradle

Le fichier le plus intéressant ici est gradle/wrapper/gradle-wrapper.properties. Il est petit, mais c'est lui qui détermine quelle version de Gradle votre projet considère comme « correcte ».

Exemple typique :

# D'où le Wrapper télécharge la distribution Gradle
distributionUrl=https\://services.gradle.org/distributions/gradle-9.4-bin.zip

Notez cette idée simple : la version de Gradle n'est pas « ce que vous avez installé », c'est « ce qui est écrit dans le projet ». Au premier lancement, le Wrapper télécharge la version de Gradle indiquée et la met dans le cache utilisateur, généralement quelque part dans le répertoire personnel, dans ~/.gradle/.... C'est pourquoi le premier lancement peut être un peu plus long : c'est normal, vous n'avez pas cassé internet.

Il est utile de savoir où vit le cache pour ne pas paniquer quand Gradle « télécharge quelque chose depuis longtemps ». En simplifiant, ça ressemble à ceci :

flowchart TD
    A[Vous lancez ./gradlew] --> B[Le Wrapper lit gradle-wrapper.properties]
    B --> C{La version de Gradle est-elle déjà dans le cache ?}
    C -- Oui --> D[Lancement de Gradle]
    C -- Non --> E[Téléchargement de gradle-9.4-bin.zip]
    E --> F[Extraction dans ~/.gradle/wrapper/dists]
    F --> D[Lancement de Gradle]

C'est ça la « reproductibilité » : le même projet tire toujours la même version de Gradle, et le build se comporte de manière prévisible.

Lancement correct du Wrapper depuis la racine

Le Wrapper se lance avec des commandes qui se ressemblent sur toutes les machines, mais avec une légère différence selon l'OS. Règle importante — les lancer depuis la racine du projet, là où se trouve gradlew. Sinon Gradle peut ne pas trouver votre build.gradle.kts, settings.gradle.kts et se comportera comme si vous « étiez venu à la mauvaise fête ».

Mini-jeu de commandes à retenir dès maintenant :

# Linux/macOS
./gradlew --version

# Windows (cmd)
gradlew.bat --version

# Windows (PowerShell)
.\gradlew --version

Notez : ./gradlew n'est pas un « point et slash magiques ». C'est littéralement « lance le fichier gradlew depuis le dossier courant ». Si vous écrivez juste gradle, vous lancerez le Gradle installé globalement, si vous en avez un, et toute l'idée du Wrapper sera détruite en un appui sur Entrée. Donc oui, ./gradlew est notre petit rituel quotidien qui évite de gros problèmes quotidiens.

3. Java Toolchain : fixer la version de Java

Deuxième douleur classique du débutant : « J'ai installé Java, mais le projet ne se compile toujours pas » ou « j'ai Java 25, mais Gradle dit qu'il en faut 21 ». Il est important de comprendre ici : en réalité vous pouvez avoir plusieurs Java en même temps, et ce n'est pas une erreur, c'est un état normal du développement. Le problème commence quand le projet ne dit pas explicitement quelle Java il attend.

Java Toolchain est un mécanisme Gradle qui permet de dire explicitement dans build.gradle.kts : « compile le projet avec cette version de Java ». Alors la compilation ne dépend plus de quelle Java se trouvait « accidentellement en premier dans le PATH » ou quelle Java l'IDE a prise « par défaut ».

Il est important de rester cohérent ici : le projet ne doit pas avoir soudainement une deuxième « vraie » version de Java. Si Java 25 a été choisie dans Initializr, on fixe la même version dans le toolchain. Alors le projet n'aura pas de Java « formelle » dans le formulaire et de Java « réelle » dans le build.

Configuration minimale du toolchain dans build.gradle.kts

Le toolchain se configure dans build.gradle.kts dans le bloc java. C'est calme et ne demande pas de magie :

java {
    toolchain {
        // On fixe explicitement la version du JDK pour la compilation (compilation et tâches Gradle)
        languageVersion = JavaLanguageVersion.of(25)
    }
}

Ce que ça signifie concrètement : « Gradle, quand tu compileras et lanceras des tâches, utilise JDK 25 comme cible. » Vous pouvez avoir JDK 17, 21 et 25 sur la machine, mais le build essaiera d'utiliser exactement celui que vous avez indiqué.

Il ne faut pas confondre cela avec la Java sur laquelle Gradle lui-même tourne. Gradle s'exécute aussi dans une JVM. Si vous avez une Java vraiment inadaptée pour lancer Gradle, vous pouvez obtenir une erreur avant même que le toolchain commence à fonctionner. C'est rare, mais si ça arrive — pas de panique : ce n'est pas « Spring est cassé », c'est juste « Gradle n'a pas pu démarrer sur cette JVM ».

Vérification de l'application du toolchain

Les débutants configurent souvent le toolchain puis ne savent pas : « Ça a marché ou j'ai juste joliment écrit un bout de texte dans build.gradle.kts ? » Bonne nouvelle : une vérification existe, et elle ne requiert pas de philosophie.

Premièrement, on peut regarder quelle Java voit Gradle et sur quelle Java il a démarré :

./gradlew --version

Deuxièmement, Gradle a un rapport sur les toolchains, souvent disponible comme tâche javaToolchains. C'est un moyen pratique de voir quels JDK ont été trouvés et lequel sera choisi :

./gradlew -q javaToolchains

Si la tâche n'est pas disponible, ce n'est pas une catastrophe : ./gradlew --version et la vérification des paramètres de l'IDE suffisent. Mais quand javaToolchains est disponible, c'est comme une « radiographie » de la partie Java de votre build.

Il est utile de garder une idée simple en tête : le toolchain concerne la compilation, pas ce que vous voyez accidentellement dans le terminal après java -version. Le terminal montre « la Java par défaut de l'utilisateur », et le Gradle toolchain montre « la Java choisie par le projet ».

4. Le plugin org.springframework.boot : son rôle dans le build

Si le Wrapper et le toolchain s'occupent de la reproductibilité du build, le Boot plugin s'occupe de le rendre orienté Spring Boot. On peut assembler un projet Java sans le Boot plugin. On peut même faire une application web sans lui, si on veut vraiment souffrir. Mais ici on apprend à ne pas souffrir et à construire le bon baseline.

Le Boot plugin n'est pas « juste une dépendance de plus ». C'est une extension de Gradle qui ajoute des tâches pratiques et des conventions spécifiquement pour les applications Boot : lancement via bootRun, assemblage du jar exécutable via bootJar, empaquetage correct, valeurs par défaut sensées uniquement pour Boot. C'est comme dire à Gradle : « Ce n'est pas juste un programme Java. C'est une application Spring Boot, sois gentil de la traiter en conséquence. »

Connecter le Boot plugin et fixer la version de Boot

Les plugins se connectent dans le bloc plugins dans build.gradle.kts. Au minimum ça ressemble à ceci :

plugins {
    // Tâches et conventions de base pour un projet Java (compileJava, test, etc.)
    java

    // Spring Boot apporte les tâches bootRun/bootJar et les paramètres de build Boot
    id("org.springframework.boot") version "4.0.3"
}

La logique est simple : java dit à Gradle « c'est un projet Java, active la compilation, les tests et les tâches standard », et org.springframework.boot ajoute par-dessus la spécificité Boot. La version du plugin correspond généralement à la version de Spring Boot que vous avez choisie dans Initializr.

Et une idée pratique importante : ne « bidouillez pas la version de Boot au feeling ». Si vous changez soudainement 4.0.3 en quelque chose comme 4.0.99-rc1 parce que « je veux la dernière », vous allez avoir une aventure. Et les aventures dans ce cours doivent prendre la forme de la compréhension, pas de bugs.

Ce qu'ajoute le Boot plugin

On a souvent l'impression qu'un plugin c'est quelque chose d'abstrait. Précisons donc concrètement : le Boot plugin ajoute des tâches Gradle dont vous vous servirez vraiment.

Comment voir qu'une tâche existe sans la lancer ? Par exemple comme ça :

./gradlew help --task bootRun

Si Gradle vous a décrit la tâche bootRun, le Boot plugin est connecté et fonctionne. C'est une vérification très calme et « sans stress » : vous n'assemblez rien, vous ne lancez rien, vous demandez juste à Gradle : « on a ce bouton-là ? »

5. Schéma général du baseline de build

Au début, il est facile de percevoir gradlew, le toolchain et le Boot plugin comme trois incantations disparates. Mais c'est au fond une seule histoire : rendre le build prévisible. Il est utile de voir toute la chaîne d'un coup, sinon vous corrigerez les erreurs à l'aveugle en disant le fameux : « je n'ai rien changé, ça s'est fait tout seul ».

Essayons de rassembler tout ça dans un schéma, comme dans les documents d'ingénierie :

flowchart TD
    Dev[Développeur] -->|lance| W["./gradlew"]
    W --> G[Gradle 9.4 depuis le Wrapper]
    G --> P[Plugins : java + org.springframework.boot]
    P --> T[Tâches : compileJava / test / bootRun / bootJar]
    T --> A[Lancement ou assemblage de catalog-service]

Tout est honnête et sans mysticisme. Vous lancez ./gradlew — c'est l'entrée dans le build. Le Wrapper fournit la version de Gradle. Gradle lit build.gradle.kts, connecte les plugins. Les plugins ajoutent des tâches. Les tâches soit lancent l'application (bootRun), soit assemblent l'artefact (bootJar). Et seulement après ça apparaît quelque chose qu'on peut appeler « une application qui fonctionne ».

Si vous mémorisez cette chaîne, la moitié des problèmes précoces disparaissent d'eux-mêmes : vous comprenez à quelle étape « ça a cassé » et vous arrêtez de tout réparer en même temps.

Mini-vérification du baseline dans catalog-service

On a très envie d'appuyer tout de suite sur Run et de voir « Started CatalogServiceApplication… ». C'est normal, on est tous comme ça. Mais un bon démarrage en ingénierie — c'est d'abord s'assurer que les outils sont en place, puis lancer. On va faire ici une petite vérification : elle prend quelques minutes et économise des heures.

La première commande vérifie que le Wrapper fonctionne et que Gradle se lance « par le projet » :

./gradlew --version

La deuxième commande est utile précisément pour le sujet de la leçon d'aujourd'hui : vous verrez quels Java toolchains sont disponibles, ou au moins vous vous assurerez que Gradle voit bien votre Java :

./gradlew -q javaToolchains

La troisième commande vérifie le Boot plugin « sans risque » : on ne démarre pas de serveur et on ne télécharge rien de plus que nécessaire — on regarde juste que la tâche existe :

./gradlew help --task bootRun

Si les trois commandes ont fonctionné sans erreurs, vous êtes dans une très bonne position. Vous avez un build reproductible, une cible Java fixée et des tâches orientées Boot. C'est ça l'hygiène de base du build d'un projet.

6. Erreurs classiques

Presque tous les problèmes avec le Wrapper, le toolchain et les plugins ne viennent pas du fait que vous « n'avez pas compris quelque chose », mais parce que nous avons tous des habitudes d'autres mondes du développement. Certains ont l'habitude que « l'IDE assemble toute seule », d'autres que java -version dit la vérité, d'autres que « les fichiers superflus peuvent être supprimés ». Voyons les pièges les plus fréquents pour que vous les reconnaissiez du premier coup.

Erreur n°1 : lancer gradle à la place de ./gradlew.
Si vous lancez le gradle global, vous sortez du monde de la reproductibilité. Vous pouvez avoir une autre version de Gradle et obtenir des erreurs bizarres : de l'incompatibilité de plugins jusqu'à « pourquoi je n'ai pas bootRun ». Le remède est très simple : dans les projets du cours, on commence toujours les commandes par ./gradlew (ou .\gradlew dans PowerShell).

Erreur n°2 : lancer le Wrapper depuis un autre dossier que la racine du projet.
Quand vous lancez les commandes depuis un autre dossier, Gradle peut ne pas trouver build.gradle.kts et settings.gradle.kts ou trouver « le mauvais projet ». Les symptômes peuvent être amusants : de « Task not found » jusqu'à l'impression que Gradle « ne voit pas les dépendances ». Habitude simple : d'abord cd catalog-service, ensuite ./gradlew ....

Erreur n°3 : supprimer les fichiers du Wrapper parce que « c'est des déchets » ou « les binaires dans git c'est mal ».
gradlew, gradlew.bat, gradle-wrapper.jar, gradle-wrapper.properties — ce ne sont pas des déchets, ce sont des parties du projet. Les supprimer transforme le build en loterie. Dans un projet pédagogique, on veut que n'importe qui puisse cloner le dépôt et l'assembler sans installer « le bon Gradle » manuellement.

Erreur n°4 : confondre « la Java dans le terminal » et « la Java qu'utilise le build ».
La commande java -version montre la Java qui est en premier dans le PATH de votre terminal courant. Mais le Gradle toolchain peut choisir une autre Java. Ce n'est pas un bug ni un complot — c'est justement un mécanisme de contrôle. Si vous voyez une divergence, ne vous inquiétez pas : vérifiez ./gradlew --version et si disponible, javaToolchains.

Erreur n°5 : ne pas fixer le Java Toolchain et espérer de la chance de l'IDE.
Aujourd'hui ça s'est compilé, demain vous avez mis à jour l'IDE, après-demain un collègue a un JDK différent — et tout part en vrille. Le toolchain n'est pas nécessaire parce que vous « ne vous faites pas confiance », mais parce que le projet doit avoir un contrat clair sur Java. Pour un projet Boot, c'est l'hygiène de base, comme se laver les mains avant de cuisiner.

1

Mission

Spring Boot, niveau 3, leçon 1

Bloqué

Wrapper, plugin Boot et Java Toolchain dans un même projet

Wrapper, plugin Boot et Java Toolchain dans un même projet

Ouvrir

1

Mission

Spring Boot, niveau 3, leçon 1

Bloqué

Script de rapport sur l'environnement de construction

Script de rapport sur l'environnement de construction

Ouvrir