Debugging d’un plugin
Quand les bugs présents dans le code de votre plugin sont durs à repérer, vous devez vous fatiguer à recompiler chaque changement effectué, ce qui rend le debugging très long et ennuyeux. C’est pourquoi nous allons parler dans cette section de la manière de configurer votre plugin afin qu’il puisse profiter des fonctions de debugging de Java.
Préparer votre workspace
Puisque nous voulons faire fonctionner Sponge et votre plugin sur votre IDE, nous aurons besoin d’importer soit SpongeForge, soit SpongeVanilla (à vous de choisir celui que vous voulez utiliser) comme un projet dans votre workspace. Les instructions à suivre sont placées dans leur pages Github respective. Suivez ces instructions avec beaucoup d’attention avant de continuer.
Maintenant, nous devons nous assurer que le projet de votre plugin est visible depuis le projet SpongeForge/SpongeVanilla que vous venez juste de créer. Les étapes suivantes dépendent de votre IDE.
IntelliJ IDEA
Dans IntelliJ, chaque projet à son propre workspace. Pour rendre votre projet Sponge(Vanilla) visible, vous devez le définir en tant que Module. En supposant que vous avez déjà créé votre projet en ayant suivi les instructions de Configurer IntelliJ IDEA, importez le en suivant les étapes suivantes.
Ouvrez le projet
SpongeVanilla
/SpongeForge
.Cliquez sur
File
, puis surNew
, et enfin surModule from Existing Sources...
.Naviguez vers le projet de votre plugin.
Si vous utilisez Gradle, sélectionnez le fichier
build.gradle
, dans le dialogue suivant, cochezUse auto-import
puis confirmez.Autrement, sélectionnez juste le fichier entier puis cliquez sur
Finish
.
Cliquez sur
Finish
.
Astuce
Si vous n’avez pas encore créé votre plugin, cliquez sur Module...
à la place de Module from Existing Sources...
, puis créez votre projet dans les fenêtres qui apparaissent.
Eclipse
Il suffit de créer votre projet comme il l’est expliqué ici: Préparation d’Eclipse. Tant qu’il est dans le même workspace que celui du projet SpongeVanilla
/SpongeForge
, il sera visible.
Ajouter le Plugin au classpath de Sponge
L’idée derrière tout ça est de lancer Sponge depuis votre IDE, comme sur un serveur normal. Cependant, il faudra ajouter votre plugin au classpath. Depuis que Sponge charge par défaut tous les plugins trouvés dans le classpath, ajouter le projet de votre plugin dans le classpath de Sponge va vous éviter de reconstruire et de copier l’artifact dans le répertoire de votre serveur après chaque modification.
Tout d’abord vous devez vous assurer que vous avez bien défini la configuration de Run/Debug convenablement, comme dans le README.md de Sponge
Puis vous devrez éditer votre configuration de Run/Debug afin qu’elle inclus votre projet dans le class path . Comment faire ça ? Eh bien ça dépend encore de votre IDE:
IntelliJ IDEA
Ouvrez la Structure du Projet.
Cliquez sur
File
, suivit deProject Structure...
.OU, cliquez sur l’icône
Project Structure
, dans le coin en haut à droite de votre IDE, près de l’icône de recherche.
Cliquez sur
Modules
. Étendez le groupeSpongeForge
ouSpongeVanilla
(en fonction de la plateforme que vous avez choisi).Assurez-vous que
SpongeForge_main
ouSpongeVanilla_main
est sélectionné.Dans la colonne de droite, sélectionnez l’onglet
Dependencies
.Cliquez sur le symbole
+
(Add
) en bas de la colonne, puis sélectionnezModule Dependency
.Sélectionnez
yourplugin_main
.Ne PAS cocher l’option
Export
du module après l’avoir ajouté à la liste.
Eclipse
Trouvez votre Configuration Run/Debug
Cliquez sur
Run
, suivit deRun Configurations...
OU, cliquez sur le menu déroulant à coté de l’icône de Run/Debug puis sur
Run Configurations...
ouDebug Configurations...
, respectivement.
Sélectionnez votre configuration Run/Debug pour Sponge (Server) sur le coté gauche.
Allez sur l’onglet
Classpath
.Sélectionnez
User Entries
, puis cliquez sur le bouton``Add Projects…``.Sélectionnez le projet approprié à votre plugin.
Cliquez sur le bouton
OK
.Cliquez sur le bouton
Apply
dans le coin en bas à droite.
Démarrer la Configuration
Après avoir suivi les étapes précédentes, vous devriez être prêt à démarrer le débogage. Si vous démarrez votre serveur depuis votre IDE, son répertoire de travail sera le répertoire run
de votre projet SpongeForge/SpongeVanilla. Tous les fichiers généralement créés par un serveur (mondes, configs etc.) seront stockés dans ce répertoire run
et persistent sur les exécutions successives de votre serveur de test local, comme si vous manuellement copier un serveur .jar dans le répertoire run
et il a commencé de là.
IntelliJ IDEA
Plutôt que d’appuyer sur la flèche verte pour démarrer la configuration de Run/Debug, cliquez sur l’icône verte à sa droite, Debug
.
Eclipse
Plutôt que de cliquer sur la flèche verte pour lancer la configuration Run/Debug, cliquez sur la flèche du menu déroulant de l’icône de Debug (celui affichant un insecte) et cliquer sur votre configuration Test (Server)
. Si elle n’apparaît pas dans le menu déroulant, cliquez sur Debug Configurations
. Sélectionnez la configuration Test (Server)
puis sur le bouton Debug
en bas à gauche.
Utiliser le Debugger
Maintenant que votre serveur (et votre plugin) fonctionnent dans le Debugger, vous pouvez utiliser toutes les fonctionnalités disponibles. Les plus utilisés sont listés ci-dessous, même si elles ne font pas partie de Sponge mais du Java Debugger que votre IDE possède.
Points d’arrêt
Les points d’arrêt sont un outil très utile pour voir le code de plus près. Un point d’arrêt peut être défini eu début d’une ligne de code ou d’une fonction. Quand vous atteignez le point d’arrêt, le debugger va stopper le code et votre IDE vous permettra d’inspecter le contenu de toutes les variables. Le code ne continuera pas tant que vous n’appuyez pas sur le bouton fonction de la vie debugging de votre IDE.
Les points d’arrêt peuvent aussi être ajoutés, retirés ou temporairement désactivés quand le debugging est en cours.
Astuce
Si un tick venait à durer plus longtemps que prévu, le watchdog (chien de garde) considéra que le serveur à crash et le forcera à se stopper. Lorsque vous travaillez avec des breakpoints (points d’arrêt) ou du code s’exécutant en pas à pas cela pourrait se produire, il est donc recommandé que vous éditiez vos fichiers d’environnements de test server.properties
et que vous définissiez la valeur de max-tick-time
à un très grand nombre (la quantité de temps qu’un tick pourrait prendre en millisecondes) ou à -1
(pour complétement désactiver le watchdog).
IntelliJ IDEA
Pour ajouter ou supprimer un breakpoint, cliquez-gauche dessus dans l’espace à gauche de l’éditeur.
Vous pouvez également avoir votre curseur sur la ligne où vous souhaitez placer ou supprimer votre point d’arrêt et cliquez sur Run
puis sur Toggle Line Breakpoint
.
Eclipse
Pour ajouter ou supprimer un breakpoint, cliquez-droit dessus dans l’espace à gauche de l’éditeur et cliquez sur Toggle Breakpoint
.
Vous pouvez également avoir votre curseur sur la ligne où vous souhaitez placer ou supprimer votre point d’arrêt et cliquez sur Run
puis sur Toggle Breakpoint
.
Code Hotswapping
L’autre avantage majeur du debugger est que vous n’avez pas à redémarrer votre serveur, même pour une infime modification, grâce au hotswapping. Cela signifie que vous pouvez juste recompilez des portions de votre code tout en utilisant votre debugger. Cependant, il y a quand même des limites, les plus importantes sont:
Vous ne pouvez pas créer ou supprimer de méthodes.
Les changements de méthodes sont limités au code contenu dans la méthode. Vous ne pouvez pas modifier sa signature (donc son nom, son type et leurs paramètres)
Vous ne pouvez pas supprimer de classes.
Vous ne pouvez pas modifier le nom d’une classe, superclasse ou la liste des interfaces qu’elle implémente.
Vous pouvez ajouter des classes. Toutefois, une fois qu’elle est construite et échangée à chaud, la classe suit les règles ci-dessous.
Vous pouvez tester cette fonctionnalité: mettez une simple commande dans votre plugin qui écris juste un mot comme Sponge
. Sauvegardez-le puis démarrez le serveur comme décrit ci-dessus. Il va afficher Sponge
. Maintenant, changez la commande pour qu’elle affiche un mot différent à la console, sauvegardez encore le fichier. Après le changement, suivez les étapes ci-dessous pour procéder au hotswap des changements du programme en cours d’exécution:
IntelliJ IDEA
Ouvrez le menu
Run
, en haut de l’IDE.En dessous de la première séparation de catégorie, cliquez sur
Reload Changed Classes
.
Eclipse
Aucune action n’est requise. Tant que vous avez sauvegardé le fichier, il sera restauré et remplacera automatiquement le debug actuel. Donc tant que vous n’avez pas modifié cette option par défaut, vous n’aurez pas à déclencher un hotswap manuellement.