Gradle-Plugin: Was sich im Projekt ändert

1. build.gradle.kts als Anweisung für Gradle

Wenn ein Einsteiger zum ersten Mal build.gradle.kts öffnet, wirkt es oft wie ein uralter Zauberspruch: Ändere einen Buchstaben – und das Projekt verwandelt sich in einen Kürbis. Das ist ein normales Gefühl. Aber um die Angst loszuwerden, reicht eine einfache Erkenntnis: build.gradle.kts ist eine Anweisung für Gradle, wie dein Projekt leben soll. Nicht für Java-Code, nicht für die IDE, sondern genau für das Build-System.

Das Wichtigste dabei: Gradle weiß "von Haus aus" nicht, dass du ein Java-Anwendungsprojekt bauen willst, dass Quellcode in src/main/java liegt, wo Tests sind, wie man kompiliert, ein Jar baut und das Projekt startet. Es versteht das nicht, weil „die IDE es entschieden hat", sondern weil du Plugins einbindest – spezielle Module, die das Verhalten von Gradle erweitern.

Kurz gesagt: Gradle ist der „Motor", Plugins sind die „Aufsätze". Der Motor kann sich drehen, aber bohren, schleifen oder schneiden tut er je nach Aufsatz. Und ja, einer der häufigsten Fehler bei Einsteigern ist die Verwechslung von „Werkzeugaufsatz" und „Baumaterial". In Gradle ist das genau die Verwechslung von Plugin und Dependency.

2. Plugin vs. Dependency: unterschiedliche Rollen

Ohne diese Klarheit wirst du immer wieder auf dieselbe Rechen treten. Plugin und Dependency werden in derselben Datei (build.gradle.kts) eingebunden, sehen ähnlich aus, sind aber für verschiedene Dinge zuständig. Wenn man sie verwechselt, kann man stundenlang ein Problem beheben, das im Grunde nur eine Frage ist: „Schreibe ich überhaupt in den richtigen Block?"

Ein Plugin ändert das Build-Verhalten: welche Gradle-Aufgaben (tasks) existieren, wie die Kompilierung abläuft, woher Quellcode kommt, wie ein Artefakt verpackt wird, ob das Projekt als Anwendung gestartet werden kann. Eine Abhängigkeit (dependency) ist eine Bibliothek, die dein Java-Code verwendet: z. B. Jackson für JSON oder SLF4J für Logging.

Um den Unterschied zu spüren, hilft diese Tabelle:

plugins { ... }

dependencies { ... }

java

implementation("tools.jackson.core:jackson-databind:3.0.4")

Und das ist das praktische Kriterium, das man wie ein Mantra wiederholen sollte: Ein Plugin ändert, wie das Projekt lebt, eine Dependency ändert, was der Code kann. Wenn du denkst „Ich will eine Bibliothek einbinden, um JSON zu schreiben" und landest in plugins {} – du bist fast sicher auf dem falschen Weg.

3. Plugins und der Block plugins {}

Wenn man build.gradle.kts ruhig liest – nicht als „magisches Laken" –, ist es ziemlich logisch: Zuerst legst du fest, was das Projekt ist (über Plugins), dann woher externe Bibliotheken kommen, dann was genau eingebunden werden soll. Heute interessiert uns der erste Teil – Plugins.

In Kotlin DSL werden Plugins im Block plugins {} eingebunden. Wichtig dabei: Einige Plugins sind eingebaut (Core Plugins), sie kommen zusammen mit Gradle. Sie können kurz und ohne Versionsangabe geschrieben werden. Genau so machen wir es im ReadLater Starter, damit der Build maximal verständlich bleibt.

Ein minimales Beispiel sieht so aus:

plugins {
    java // Core-Plugin: aktiviert das Java-Projektmodell (Kompilierung, Tests, Jar)
}

Diese Zeile bedeutet: „Gradle, behandle dieses Projekt als Java-Projekt und aktiviere das Java-Build-Modell." Gradle hat intern viel Mechanik, aber was uns praktisch wichtig ist: Nach der Einbindung von java versteht es Quellcode, Kompilierung, Tests, Jar und die Standardprojektstruktur.

Und jetzt zum Vergleich – ein Ausschnitt, der ähnlich aussieht, aber bereits zu Abhängigkeiten gehört. Heute analysieren wir ihn nicht; er ist nur da, damit du den anderen Block siehst:

dependencies {
    // Das ist eine Bibliothek für deinen Java-Code, kein "Gradle-Erweiterungsmodul"
    implementation("tools.jackson.core:jackson-databind:3.0.4")
}

Wenn du dir merkst, dass Plugins immer in plugins {} und Bibliotheken immer in dependencies {} gehören, sparst du dir jede Menge Nerven. Ungefähr so, als würdest du aufhören, Zucker in die Suppe zu schütten. Manche streiten darüber… aber das lassen wir.

4. Plugin java: Was es dem Projekt gibt

Die Einbindung von java wird oft so verstanden: „Na ja, irgendwie muss ich Gradle doch sagen, dass ich in Java schreibe." Das stimmt, klingt aber zu abstrakt. Tatsächlich ändert das java-Plugin das Projekt ganz konkret: Gradle beginnt, es als Java-Projekt mit eigenen Konventionen und Aufgaben zu sehen. Schauen wir, was das genau bedeutet, warum Gradle nicht alles „erraten" muss und warum die IDE nicht die Hauptwahrheitsquelle sein soll.

Das java-Plugin gibt Gradle das Java-Projektmodell: Es enthält Konventionen (conventions) und Aufgaben (tasks). Konventionen bedeuten: „Wir haben vereinbart, dass Quellcode hier liegt, Ressourcen dort, Tests da drüben." Aufgaben bedeuten: „Wir können kompilieren, Tests ausführen und ein Jar bauen." Das ist keine Philosophie – genau dieses Modell läuft hinter Befehlen wie ./gradlew build.

In der Praxis macht das java-Plugin mindestens zwei wichtige Dinge:

1) Es verknüpft Gradle mit der Standard-Verzeichnisstruktur. Es erwartet, dass der Hauptquellcode in src/main/java liegt, Ressourcen in src/main/resources, Tests in src/test/java.

2) Es fügt Aufgaben für Kompilierung und Artefaktbau hinzu. Man muss die ganze Liste jetzt nicht auswendig kennen – uns interessiert das Prinzip: Du bekommst einen klaren Weg „Quellcode → Kompilierung → Ergebnis".

Man kann sich das als einfaches Schema vorstellen:

flowchart TD
    A["src/main/java"] --> B["compileJava"]
    C["src/main/resources"] --> D["processResources"]
    B --> E["classes"]
    D --> E["classes"]
    E --> F["jar"]

Du musst die Aufgabennamen nicht jetzt auswendig kennen. Wichtig ist das Gefühl: Ohne java muss Gradle nicht verstehen, was „Java-Quellcode", „Ressourcen" und „Jar" sind. Dieses Wissen bekommt es über das Plugin.

Die minimale Konfiguration, mit der ReadLater Starter ein Java-Projekt bleibt, sieht so aus:

plugins {
    java // Sagt Gradle: "Das ist ein Java-Projekt"
}

Und ja, das ist einer der Fälle, wo eine Zeile in build.gradle.kts das Projektverhalten stärker verändert als zehn Zeilen Java-Code. Ein bisschen frustrierend, aber so funktioniert die Welt der Build-Tools nun mal.

5. Plugin application und Aufgabe run

Fast alle mögen ./gradlew run, weil es so aussieht: „Ich drücke einen Knopf – und es startet." Aber es ist wichtig zu verstehen, woher diese Magie kommt. Der Befehl run ist keine „eingebaute Gradle-Funktion". Es ist eine Aufgabe (task), die erscheint, weil das application-Plugin eingebunden ist.

Das application-Plugin wird gebraucht, wenn man eine ausführbare Anwendung baut – nicht nur „eine Bibliothek mit Klassen". Es sagt Gradle: „Das Projekt hat einen Einstiegspunkt main, ich will das bequem ausführen können." Außerdem bereitet es noch einige Dinge für das Anwendungsleben vor, aber in unserem Kurs ist der Fokus einfach: Starten über Gradle.

Minimale Plugin-Konfiguration für eine ausführbare Java-Anwendung in unserem Projekt:

plugins {
    java        // Basis: Java-Projektmodell (Kompilierung, Tests, Jar)
    application // Gibt die Aufgabe `run` und Anwendungseinstellungen
}

Hier stellt sich die berechtigte Frage: „Warum nicht nur application?" Im echten Leben ziehen manche Plugins andere nach, aber im Lernprojekt behalten wir Explizitheit: java ist für das Java-Modell, application für das Anwendungsstartmodell zuständig. So ist es für Einsteiger leichter, den Faden nicht zu verlieren.

Damit das application-Plugin weiß, was genau zu starten ist, gibt man ihm normalerweise mainClass an. In Kotlin DSL sieht das so aus (Beispiel für ReadLater Starter):

plugins {
    java        // Nötig, damit Gradle Java-Quellcode bauen kann
    application // Nötig, damit die Aufgabe `run` erscheint
}

application {
    // Vollständiger Name der Klasse mit `public static void main(String[] args)`
    mainClass.set("com.example.readlater.ReadLaterApplication")
}

Und ein Beispiel des Einstiegspunkts selbst, um die Gradle-Konfiguration mit der echten Java-Klasse zu verknüpfen:

package com.example.readlater;

public class ReadLaterApplication {
    public static void main(String[] args) {
        // Einstiegspunkt der Anwendung: hier "landet" der Start über `./gradlew run`
        System.out.println("ReadLater Starter is running");
    }
}

Der Sinn dieser Verknüpfung ist simpel: Gradle startet dein main() nicht per Magie, sondern weil du application eingebunden und angegeben hast, wo deine main class liegt.

6. Plugins und Gradle-Aufgaben: die Schlüsselverbindung

Der Satz „Ein Plugin fügt Tasks hinzu" klingt langweilig genau bis zum ersten Aufeinandertreffen mit der Frage: „Warum funktioniert der Befehl run nicht?" oder „Warum baut Gradle kein Jar?" Dann stellt sich schnell heraus, dass Gradle kein großes monolithisches Skript ist, sondern ein System, dessen Verhalten sich aus eingebundenen Teilen zusammensetzt.

Wenn du ./gradlew run schreibst, sucht Gradle nach einer Aufgabe namens run. Wenn sie existiert – wird sie ausgeführt. Wenn nicht – sagt Gradle ehrlich: „Diese Aufgabe gibt es nicht." Das ist kein „Java-Fehler", kein „IDE-Absturz" und auch kein „Gradle-Absturz". Es bedeutet einfach, dass in deinem Build-Modell der Baustein fehlt, der diese Aufgabe bringen sollte.

Ein sehr anschauliches und ehrlich gesagt nützliches Gedankenexperiment: Entferne application aus plugins und versuche dann ./gradlew run. Gradle antwortet mit einem Fehler: „Task 'run' not found." Ungefähr so, als würdest du die Räder vom Fahrrad entfernen und dich wundern, dass es kein Transportmittel mehr ist, sondern ein Kunstobjekt.

Hier entsteht das richtige „erwachsene" Gradle-Modell:

flowchart TD
    A["build.gradle.kts"] --> B["plugins"]
    B --> C["Gradle fügt Aufgaben hinzu"]
    C --> D["Du rufst Aufgaben über ./gradlew ... auf"]
    D --> E["Projekt wird kompiliert / gestartet / gebaut"]

Ein Plugin ist keine Bibliothek für deinen Code. Es ist ein Modul, das Gradle neue Möglichkeiten und Regeln gibt. Wenn man das jetzt versteht, wird es danach viel leichter sein, fremde build.gradle.kts-Dateien zu lesen – ohne sich wie ein Archäologe zu fühlen, der versehentlich einen „Ritualkreis" ausgegraben hat.

7. Plugins für ReadLater Starter: das Minimum

Es verlockt sehr, „für alle Fälle" alles mögliche einzubinden. Einsteiger machen das: „Was, wenn es gebraucht wird? Was, wenn das so richtig ist?" Am Ende wird build.gradle.kts zur Vitrine unbekannter Technologien, und das Projekt beginnt sein eigenes Leben zu führen. In einem Lernprojekt ist das besonders schädlich: Du verlierst die Ursache-Wirkungs-Zusammenhänge.

Auf der aktuellen Kursebene brauchen wir einen minimalen und erklärbaren Satz: das Plugin java, damit Gradle das Java-Projekt versteht, und das Plugin application, damit wir ReadLater Starter mit einem Befehl starten können. Das war's. Keine Plugins „zur Schönheit", „zur zukünftigen Verpackung", „für Tests, die wir noch nicht schreiben", und schon gar kein „fast-Spring, aber kein Spring".

Empfohlenes Gerüst für build.gradle.kts (nur über Plugins und Start) kann so aussehen:

plugins {
    java        // Basis-Java-Modell (Struktur src/*, Kompilierung, Jar)
    application // Aufgabe `run` und Anwendungsstarteinstellungen
}

application {
    // Klasse, die bei `./gradlew run` gestartet wird
    mainClass.set("com.example.readlater.ReadLaterApplication")
}

Bemerke, wie angenehm das ist: Du kannst diese Datei laut in 15 Sekunden erklären. Das ist ein guter Test für „Ich habe keinen Zauberspruch kopiert, ich verstehe, was ich tue".

Merke dir die Kernaussage: Plugins sind für den Build. Halten wir den Fokus genau darauf: Damit Gradle kann, was wir wollen, binden wir das nötige Plugin ein, und Bibliotheken binden wir separat ein.

8. Typische Fehler beim Umgang mit Gradle-Plugins

Fehler Nr. 1: Plugin und Dependency verwechseln, weil „beides in build.gradle.kts eingebunden wird".
Das ist der klassische Anfängerfehler. Meistens so: Der Lernende will Jackson hinzufügen und sucht eine Stelle in plugins {}. Ergebnis – unverständliche Fehler und das Gefühl, dass Gradle „unverständlich schimpft". Heilmittel: das einfache Prinzip – ein Plugin ändert den Build des Projekts, eine Dependency fügt dem Java-Code eine Bibliothek hinzu. Und sie haben verschiedene Blöcke in der Build-Datei.

Fehler Nr. 2: application einbinden und mainClass vergessen – dann wundern, dass „run nicht weiß, was zu starten ist".
Das application-Plugin ist kein Hellseher. Wenn das Projekt mehrere Klassen mit main() hat (was manchmal sogar versehentlich passiert), muss Gradle nicht raten. Daher am besten sofort die explizite Einstellung mainClass.set(...) angeben. Ein Fehler in der mainClass-Zeile kommt auch oft vor: falsches Package, falscher Name, Klasse noch nicht erstellt – und der Start ist kaputt.

Fehler Nr. 3: Plugins „auf Vorrat" hinzufügen, weil es so sicherer wirkt.
In den ersten Kurstagen sollte der Build kurz und erklärbar bleiben. Jedes überflüssige Plugin bringt neue Aufgaben, neue Regeln und neue Überraschungen. Überraschungen kommen meistens nicht als Geschenk, sondern als: „Warum dauert mein Build jetzt 5 Minuten?" oder „Warum ist das Jar plötzlich anders?" Besser Plugins nur hinzufügen, wenn man erklären kann, welches konkrete Problem sie lösen.

Fehler Nr. 4: Gradle als „IDE-Funktion" wahrnehmen, nicht als eigenständiges Tool.
Manchmal denkt ein Lernender: „Ich starte doch aus IntelliJ, also ist alles in Ordnung." Dann öffnet er das Projekt auf einem anderen Rechner, und dort startet nichts. Plugins sind genau dafür da, dass das Projektverhalten im Repository festgelegt wird – nicht in den lokalen IDE-Einstellungen. In unserem Kurs ist das grundsätzlich: Wir gewöhnen uns an den wichtigen Gedanken – das Projekt lebt außerhalb der IDE.

Fehler Nr. 5: Wegen des Wortes Plugin in Panik geraten, als ob es „etwas Kompliziertes und Enterprise-mäßiges" wäre.
Das Wort „Plugin" klingt beeindruckend, aber auf unserem Level ist es sehr bodenständig: java sagt „Das ist ein Java-Projekt", application sagt „Das ist eine ausführbare Anwendung". Man muss sich kein „Plugin schreiben", „Custom Tasks" oder „Build Engineering" vorstellen – das ist eine andere Ebene und ein anderes Thema. Jetzt brauchen wir Klarheit: Welche zwei Zeilen machen das Projekt verständlich und startbar.

1

Aufgabe

Java Server, Level 3, Lektion 0

Gesperrt

Minimales ausführbares Projekt mit Plugins

Minimales ausführbares Projekt mit Plugins

Öffnen