IntelliJ - Proste zarządzanie bibliotekami oraz systemem kontroli wersji.

Witajcie! 

Jak wskazuje tytuł w tym poradniku przybliżę Wam czym jest Git i Maven w IntelliJ, a także pokażę jego praktyczne zastosowania. Z tym, że nie będę tłumaczyć jak napisać sam plugin, zajmę się jedynie samą kompilacją i zarządzaniem bibliotekami. Jeżeli chcecie dowiedzieć się jak zacząć i poznać podstawowe pojęcia możecie zaglądnąć do świetnie napisanego poradnika Ixidi'ego pod tym linkiem: klik!

Wstęp
Dobrze, więc zacznijmy od początku, jeżeli chodzi o samego Gita i Mavena to są to jedne z najczęściej używanych narzędzi nie tylko przez pasjonatów, ale także w środowisku komercyjnym. Są one darmowe i w pełni funkcjonalne. Jednym z dużych minusów jest to, że z początku sama ich obsługa może wydawać się skomplikowana, ale wcale taka nie jest.

Zatem - czym jest Git? To system kontroli wersji, jest open source i dzięki niemu możecie zapisywać swoją pracę do repozytorium, aby później mieć dostęp do każdej wersji danego projektu poprzez zamieszczanie commitów. Możecie także dzielić swój projekt na różne gałęzie - na przykład rozwijać jedną gałęź dla wersji 1.8 - 1.12 i drugą dla 1.13 - 1.16. Jest to bardzo dobre rozwiązanie dla osób, które chciałby tworzyć projekty wspólnie z kimś innym. Poza tym możecie także sklonować publiczne gotowe repozytoria i kontynuować pracę nad czymś co ktoś już zaczął bądź skończył. Oczywiście mówię tu tylko o przykładach w codziennym użytku dla mniejszych developerów, zastosowań jest o wiele więcej. Więcej można dowiedzieć się tutaj: https://pl.wikipedia.org/wiki/Git_(oprogramowanie)

Idąc dalej - czym jest Maven? To narzędzie, które pozwala na kompilację Waszych pluginów wraz z bibliotekami, których nawet nie musicie pobierać (a raczej nie bezpośrednio) na Wasz komputer. Wystarczy odpowiedni plik - pom.xml uzupełnić o konkretne repozytoria i biblioteki, wraz z ich wersjami (patrz Git), a Maven automatycznie doda je podczas budowania Waszego projektu. Sam maven ma kilka opcji, czyli tzw. celów, które pełnią różne funkcje, nas będą interesowały dwa cele - package i shade (ten drugi będzie dostępny tylko po dodaniu wtyczki do Mavena w pliku pom, ale i tak będzie używać pierwszego jako swojej "bazy"). Co robi package i shade? Pierwszy cel kompiluje nasz kod i wrzuca go do jara, a drugi dodaje także do niego wybrane biblioteki (w przypadku kiedy dana libka nie jest osobnym, działającym pluginem, który należy wrzucić na serwer).

1. Tworzenie własnego repozytorium dla naszych pluginów
A więc zaczynamy! Na początku mamy dwie opcje - jedna, o której już wspominałem, czyli zaimportowanie projektu, który stworzył ktoś inny i druga - stworzenie nowego. 

Najpierw zajmiemy się tą drugą. Aby stworzyć nowy projekt będziemy potrzebowali serwera Git, tzn. miejsca, w którym przechowywany będzie nasz program. Najpopularniejszymi, darmowymi serwisami oferującymi takie usługi są https://github.com/ https://bitbucket.org/ https://gitlab.com z czego ja polecam ten pierwszy. Zakładamy konto na wybranym serwisie, a następnie szukamy opcji utworzenia nowego repozytorium. Po utworzeniu repozytorium otrzymamy link, który sobie zapisujemy, będzie on służył do zarządzania naszym repozytorium. 
Następnie przechodzimy do IntelliJ, klikamy kolejno w File -> Project from Version Control, w nowym oknie dialogowym wklejamy URL do naszego repozytorium i na koniec klikamy Clone. Z lewej strony klikamy prawym na nasz projekt, New -> Module i w następnym oknie dialogowym zaznaczamy Maven (wybierzcie też wersję SDK, zapewne będzie to 1.8, ale to zależy od preferencji). Następnie nazywamy nasz moduł i dodajemy go do projektu. Cały projekt jest zbiorem modułów, z czego moduł będzie pluginem, więc w jednym projekcie możemy mieć wiele pluginów. Możliwe, że w międzyczasie będziecie musieli się zalogować, robicie to po prostu poprzez podanie Waszego loginu i hasła do Gita, bądź generujecie sobie token.

Po tych krokach czas na zaimportowanie spigota. Repozytorium możecie znaleźć po wpisaniu "spigot maven" w google, podaje je też niżej:

<repositories>
    <repository>
        <id>spigot-repo</id>
        <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
    </repository>
</repositories>

Poniższy kod xml należy skopiować i wkleić do pliku pom.xml, znajdującego się wewnątrz modułu, który uprzednio stworzyliście, pod znacznikiem zamykającym version, dzięki temu możemy zaimportować do naszego modułu kilka wersji spigota. Aby to zrobić pod repozytoriami wklejamy poniższy kod:

<dependencies>
    <dependency>
           <groupId>org.spigotmc</groupId>
           <artifactId>spigot-api</artifactId>
           <version>1.16.3-R0.1-SNAPSHOT</version>
           <scope>provided</scope>
    </dependency>
</dependencies>

Jak możecie zauważyć zależność zawiera pole version, które odpowiada za wersję spigota. Listę wszystkich wersji możecie znaleźć po przejściu w URL podany w repozytorium. Wasz cały plik xml powinien wyglądać tak:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>BasicPlugin</artifactId>
    <version>1.0-SNAPSHOT</version>

    <repositories>
        <repository>
            <id>spigot-repo</id>
            <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>1.16.3-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

</project>

Czekamy chwilę, aż nasze IDE pobierze odpowiednie pliki z serwera git i rozwijając kolejne gałęzie modułu szukamy folderu main / java i w tamtym miejscu tworzymy standardową strukturę plików (czyli między innymi package z Waszą domeną). Plik plugin.yml umieszczamy w stworzonym wcześniej przez Mavena folderze resources, który też znajduje się w folderze main. Maven automatycznie doda go do naszego pliku .jar. Ważne jesto to, że nie podajecie ścieżki main/java w polu main pliku plugin.yml tylko bezpośrednio package.

Teraz, aby wyeksportować nasz kod do pliku .jar po prawej stronie szukamy zakładki Maven, rozwijamy opcje naszego modułu, przechodzimy w Lifecycle i wybieramy cel package. 

Jeżeli pojawia Wam się błąd 

Cytat

[ERROR] Source option 5 is no longer supported. Use 6 or later.
[ERROR] Target option 1.5 is no longer supported. Use 1.6 or later.

To prawdopodobnie używacie wersji JDK 9 lub nowszej, i macie dwie opcje.
1) Użyć wersji JDK 8
2) Poinstruować mavena, żeby skompilował plugin do wersji 11 (tylko w przypadku jeżeli na maszynie, dla której piszecie dany plugin obsługuje wersję 11!)

Żeby poinstruować Mavena, że chcecie kompilować plugin w innej wersji JDK niż domyślnie do pliku pom.xml dodajecie za znacznikiem version poniższy kod:

  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>

W ten sposób mamy działający plugin!  Po zakończeniu pracy możecie zcommitować zmiany do Waszego repozytorium poprzez menu VCS ze wstążki. 

2. Importowanie gotowych repozytoriów

Okej, jeżeli chcecie użyć kogoś kodu, jako swojej podstawy to możecie zaimportować projekt wprost z serwera Git, aby to zrobić na stronie, na której zamieszczony jest projekt szukacie opcji clone, jak ją znajdziecie to kopiujecie link, i przechodzicie do IntelliJ. Tam Klikacie na File -> New ->Project from Version Control -> i w polu URL wklejacie link. Dzięki temu macie od razu działający projekt, który możecie dowolnie przerabiać. Pod tym linkiem https://github.com/skymakerx/poradnik macie repozytorium, które utworzyłem na potrzeby tego poradnika zawierając bibliotekę, proces opisany w punkcie 3. Sam plugin nie robi wiele. Po wejściu tworzy NPC z Waszą nazwą w miejscu, w którym się pojawiliście. Jest to jedynie przykład. Ważnym jest, że nie będziecie mogli commitować tutaj zmian, do tego będziecie musieli utworzyć swoje repozytorium i to do niego wrzucać odpowiednie zmiany.

3. Dodawanie bibliotek do naszego pluginu

Żeby dodać sobie do pluginu jakąś bibliotekę, powiedzmy NPCLib (strona projektu: https://github.com/MinecraftLibraries/NPCLib/) dodajemy do repozytoriów wartości, które autor zalecił w pliku README, czyli repozytorium:

    <repository>
        <id>ossrh</id>
        <url>https://oss.sonatype.org/content/groups/public/</url>
    </repository>

i zależność

    <dependency>
        <groupId>net.jitse</groupId>
        <artifactId>npclib-api</artifactId>
        <version>2.9-SNAPSHOT</version>
        <scope>compile</scope>
    </dependency>

cały plik powinien wyglądać tak:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>BasicPlugin</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>

    <repositories>
        <repository>
            <id>spigot-repo</id>
            <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
        </repository>
        <repository>
            <id>ossrh</id>
            <url>https://oss.sonatype.org/content/groups/public/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>1.16.3-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>net.jitse</groupId>
            <artifactId>npclib-plugin</artifactId>
            <version>2.9-SNAPSHOT</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

</project>

I teraz standardowo podążając za poradnikiem możemy używać wszelkich dobrodziejstw danego API. Według autora mamy trzy opcje, żeby użyć jego API, chociaż nas interesować będą dwie. Wrzucić jego plugin jako działający plugin do spigota i dodać jego plugin jako zależność w plugin.yml w naszym pluginie lub zshade'ować jego plugin razem z naszym pluginem do jednego pliku .jar i my chcielibyśmy użyć właśnie drugiej opcji. Tak jak wcześniej wspomniałem, będziemy potrzebować do tego wtyczki do Mavena, którą zamieścimy klasycznie w pliku pom.xml naszego projektu:

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <relocations>
                        <relocation>
                            <pattern>net.jitse.npclib</pattern>
                            <shadedPattern>org.example.basicplugin.libs</shadedPattern>
                        </relocation>
                    </relocations>
                </configuration>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

Zwróćcie uwagę na znacznik shadedPattern! Tam podajecie sobie lokalizację, do której chcielibyście wrzucić API, nie ma ona dużego znaczenia, ale jeżeli lubicie porządek to warto wrzucać libki do osobnego pakietu (nie musi on być utworzony w projekcie). Wsio! 

Jeżeli macie jakieś pytania, bądź problemy, możecie napisać poniżej - chętnie odpowiem  

@LeviBoyPL całkiem dobrze rozpisane, ale nie uważasz że warto byłoby od razu uczyć ludzi Gradle'a zamiast Mavena? Nowsza technologia i prostsza, znacznie bardziej zwięzła składnia.

5 godzin temu, Libter napisał:

Nowsza technologia i prostsza, znacznie bardziej zwięzła składnia.

W pełni się z Tobą zgadzam, wybór Mavena nad Gradlem wynikał głównie z tego, że osobiście więcej widziałem repozytoriów git, w których podają gotowe rozwiązania kopiuj - wklej właśnie dla Mavena. Ludzie chętniej przeczytają artykuł, o terminie, o który gdzieś już kiedyś się natknęli, niż o coś nowego. Przy Gradlu też trzeba by troszkę namieszać strukturą. No i też łatwo jest omyłkowo podczas instalacji IntelliJ wyłączyć sobie wtyczkę Gradle'a i nie wiedzieć o jego istnieniu, a Mavena nie da się w ten sposób wyłączyć, widać go zawsze przy tworzeniu nowego projektu.