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 sur New, et enfin sur Module from Existing Sources....

  • Naviguez vers le projet de votre plugin.

    • Si vous utilisez Gradle, sélectionnez le fichier build.gradle, dans le dialogue suivant, cochez Use 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, assurez-vous que votre configuration Run/Debug a bien été définie, comme montré dans le README.md 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 de Project 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 groupe SpongeForge ou SpongeVanilla (en fonction de la plateforme que vous avez choisi).

  • Assurez-vous que SpongeForge_main ou SpongeVanilla_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électionnez Module Dependency.

  • Sélectionnez yourplugin_main.

  • Ne PAS cocher l’option Export du module après l’avoir ajouté à la liste.

Avertissement

À cause d’un bug dans IntelliJ (IDEA-194641), toutes les dépendances que votre plugin a (ex : le librairie standard Kotlin, ou Gson) ne seront pas ajoutées au classpath en utilisant la méthode ci-dessus. Cela résulte en un ClassNotFoundException quand votre plugin essaie d’accéder à une de ces classes, même si il a compilé correctement avec cette classe.

Ce problème affecte seulement le lancement de votre plugin à partir d’IntelliJ en tant que module. Le jar du plugin final généré se lancera normalement dans IntelliJ et un serveur de production.

Si votre plugin possède des dépendances externes, vous aurez besoin de suivre ces étapes afin de les lancer directement depuis IntelliJ :

  • Créez un nouveau module Java avec File -> New -> Module.... Nommez-le SpongeForgeContainer.

  • Ouvrez les paramètres du module pour SpongeForgeContainer comme décrit ci-dessus

  • Dans les paramètres de dépendances pour SpongeForgeContainer, ajoutez une dépendance de module sur SpongeForge_main

  • Éditez votre configuration de lancement de serveur. Changez Use classpath of module: de SpongeForge_main à SpongeForgeContainer

Vous pouvez laisser tous vos paramètres inchangés, dont la dépendance de SpongeForge_main dans le module de votre plugin. Maintenant, toutes les dépendances de votre plugin devraient être ajoutées au classpath lorsque vous démarrez le serveur.

Eclipse

  • Trouvez votre Configuration Run/Debug

    • Cliquez sur Run, suivit de Run Configurations...

    • OU, cliquez sur le menu déroulant à coté de l’icône de Run/Debug puis sur Run Configurations... ou Debug 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 aviez manuellement copié un serveur .jar dans le répertoire run et qu’il commençait 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 cliquez 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 appuyez 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.