Debugowanie wtyczek

Kiedy błędy w kodzie twojej wtyczki są trudne do zlokalizowania, a ty masz dość rekompilacji po każdej pojedynczej zmianie, a wyjścia loggerowe zawalają twój kod, debugowanie może być bardzo problematyczne. Z tego powodu ta sekcja wyjaśni ci, jak skonfigurować swoją wtyczkę, w celu wykorzystania możliwości debugowania Javy.

Przygotowywanie twojego obszaru pracy

Since we will be running both Sponge and your plugin from within your IDE, you’ll need to import either SpongeForge or SpongeVanilla, depending on which you want to use, as a project into your workspace. The instructions to do so are found on the respective project’s GitHub page. Follow those instructions carefully before proceeding here.

Now you need to make sure your plugin project is visible to the SpongeForge/SpongeVanilla project you just created. The steps necessary depend on your IDE.

IntelliJ IDEA

In IntelliJ, every project has its own workspace(s). To make your project visible to the Sponge(Vanilla) project, it needs to be a Module. Assuming you already created your project as described in Konfigurowanie IntelliJ IDEA, import it using the following steps.

  • Open the SpongeVanilla/SpongeForge project.

  • Click File, followed by New, then Module from Existing Sources....

  • Navigate to the directory of your plugin project.

    • If you’re using Gradle, select the build.gradle file, in the next dialog check Use auto-import and confirm.

    • Otherwise, just select the whole directory and click Finish.

  • Kliknij Finish.

Wskazówka

If you have not yet created your plugin, click Module... instead of Module from Existing Sources..., then create your project in the following dialogue.

Zaćmienie

Just create your project as described here: Konfigurowanie Eclipse. As long as it is in the same workspace as your SpongeVanilla/SpongeForge project, it will be visible.

Dodawanie Pluginu do ścieżki klasy Sponge

Stojący za tym pomysł polega na uruchomieniu Sponge z twojego IDE, jak zwykle. Różnica polega na tym, że dodamy Twoją wtyczkę do ścieżki klas. Odkąd Sponge domyślnie ładuje wszystkie wtyczki znajdujące się w ścieżce klas, dodanie projektu wtyczki do ścieżki klas Sponge zwalnia użytkownika z konieczności odbudowania i skopiowania pliku artefaktu do katalogu serwera po każdej zmianie.

First you need to ensure that you have your Run/Debug Configuration(s) set appropriately, as shown in the Sponge README.md

Then you’ll need to edit that Run/Debug Configuration so that it will include your project on the class path. How to do this, depends on your IDE again:

IntelliJ IDEA

  • Otwórz swoją strukturę projektu.

    • Click File, followed by Project Structure....

    • OR, click the Project Structure icon, in the upper right-hand corner of the IDE, next to the Search icon.

  • Click Modules. Expand the SpongeForge or SpongeVanilla group (depending on what you chose).

  • Make sure SpongeForge_main or SpongeVanilla_main is selected.

  • On the right column, select the Dependencies tab.

  • Click the + symbol (Add) on the bottom of the column, and select Module Dependency.

  • Select yourplugin_main.

  • NIE zaznaczaj opcji Export na module po podaniu do listy.

Ostrzeżenie

Due to a bug in IntelliJ (IDEA-194641), any dependencies that your plugin has (e.g. the Kotlin standard library, or Gson) will not be added to the classpath using the above method. This results in a ClassNotFoundException when your plugin tries to access one of these classes, even though it successfully compiled against that class.

This issue only affects running your plugin from IntelliJ as a module. Your final built plugin jar will run normally in both IntelliJ and a production server.

If your plugin has external dependencies, you’ll need to follow these steps in order to run it directly from IntelliJ:

  • Create a new Java module with File -> New -> Module.... Name it SpongeForgeContainer.

  • Open the module settings for SpongeForgeContainer as described above

  • In the dependency settings for SpongeForgeContainer, add a module dependency on SpongeForge_main

  • Edit your server run configuration. Change Use classpath of module: from SpongeForge_main to SpongeForgeContainer

You can leave all of your settings unchanged, including SpongeForge_main’s dependency on your plugin module. Now, all of your plugin’s dependencies should be added to the classpath when you run the server.

Zaćmienie

  • Znajdź swoją konfigurację uruchomienia/debugowania

    • Click Run, followed by Run Configurations...

    • OR, click the drop-down arrow beside the Run/Debug icons and then Run Configurations... or Debug Configurations..., respectively.

  • Wybierz swoją konfiguracje Uruchamiania/Debugowania dla Sponge (serwera) po lewej stronie.

  • Zmień na kartę Classpath.

  • Select User Entries, followed by the Add Projects... button.

  • Wybierz odpowiedni projekt dla twojego pluginu.

  • Kliknij przycisk OK.

  • Click the Apply button on the bottom right corner.

Uruchamianie Konfiguracji

After you’ve followed the previous steps, you should be ready to start debugging. If you start your server from your IDE, its working directory will be the run directory in your SpongeForge/SpongeVanilla project. All the files usually created by a server (worlds, configs etc.) will be stored in that run directory and persist over multiple runs of your local test server, just as if you manually copied a server .jar to the run directory and started it from there.

IntelliJ IDEA

Rather than pressing the Green right-pointing arrow to run your Run/Debug configuration, click the Green icon to the right of it, Debug.

Zaćmienie

Rather than pressing the green right-pointing arrow to run your Run/Debug configuration, click the drop-down arrow of the Debug icon (the one displaying a bug) and click your Test (Server) configuration. If it doesn’t appear in the drop-down menu, click Debug Configurations. Select Test (Server) configuration and hit the Debug button on the bottom left.

Używanie Deguggera

Now that your server (and your Plugin) are running in the Debugger, you can make use of the features it holds. The most prominently used are explained below in short, though they are not features of Sponge, but the Java Debugger your IDE makes use of.

Punkty przerwania

Punkty przerwania stanowią przydatne narzędzie do bliższego przyjrzenia się kodowi. Punkt przerwania można ustawić na początku linii kodu lub funkcji. Po osiągnięciu punktu przerwania debugger wstrzyma wykonywanie kodu, a twój IDE otworzy widok pozwalający na przeglądnięcie zawartości wszystkich zmiennych w obecnym zakresie. Wykonanie kodu nie zostanie wznowione, dopóki nie naciśniesz odpowiedniego przycisku w widoku debugowania IDE.

Punkty przerwania mogą zostać również dodane, usunięte, lub tymczasowo wyłączone w trakcie debugowania.

Wskazówka

Once a single server tick takes more than a given amount of time, the watchdog will consider the server crashed and forcefully shut it down. When working with breakpoints this might occur, so it is recommended that you edit your test environments server.properties file and set the value of max-tick-time to either a very large number (the amount of milliseconds a tick may take) or -1 (to disable the Watchdog completely).

IntelliJ IDEA

Aby dodać, lub usunąć punkt przerwania, wystarczy kliknąć lewym przyciskiem myszy w pustą przestrzeń po lewej stronie twojego edytora.

Alternatywnie, możesz umieścić kursor w linii, do której chcesz dodać lub usunąć punkt przerwania, a następnie kliknij Uruchom, a potem Przełącz punkt przerwania Lini.

Zaćmienie

W celu dodania lub usunięcia punktu przerwania, kliknij prawym przyciskiem myszy w puste miejsce po lewej stronie edytora i kliknij `` Przełącz punkt przerwania``.

Alternatively, have your cursor be in the line where you want the breakpoint added or removed and then click Run followed by Toggle Breakpoint.

Hotswapping kodu

Innym wielkim atutem debuggera jest to, że nie będziesz musiał restartować swojego serwera podczas każdej małej zmiany jakiej dokonujesz, dzięki funkcji hotswapping’u kodu. Oznacza to, że możesz prze-kompilować fragmenty kodu podczas działania w debugerze. Jakkolwiek istnieje kilka ograniczeń, najważniejsze z nich to:

  • Nie możesz tworzyć lub usuwać metod.

    • Changes to methods are limited to code within the method. You cannot modify its signature (that means its name, return type and parameter types)

  • Nie możesz usuwać klas.

    • You cannot modify a class» name, superclass or the list of interfaces it implements.

    • You can add classes. However, once it’s been built and hotswapped, the class follows the above rules.

You can test this functionality: Introduce a simple command to your plugin that just writes a word, like Sponge Then save it and start the server as described above. Run the command. It will output Sponge. Now change the command to write a different word to console, save the file. After a change, do as follows to hotswap the changes to the running program:

IntelliJ IDEA

  • Otwórz menu Run, od górnej krawędzi IDE.

  • Below the first category break, click Reload Changed Classes.

Zaćmienie

No action needed. As soon as you save the file, it will be rebuilt and automatically hotswapped with the currently running debug. Unless you changed this particular default behavior, you will not have to trigger a manual hotswap.