3 Installation und Grundkonfiguration

3.1 Systemvoraussetzungen und Installationswege

Gradle benötigt eine Java Development Kit (JDK) Installation in Version 8 oder höher. Für aktuelle Gradle-Versionen wird JDK 11 oder 17 empfohlen, da diese Long Term Support Versionen sind. Die JDK-Version bestimmt nicht die Java-Version des zu bauenden Projekts - Gradle kann mittels Toolchains auch Projekte für andere Java-Versionen bauen. Die Verfügbarkeit von mindestens 512 MB RAM wird vorausgesetzt, für größere Projekte sind 2-4 GB empfehlenswert.

Die Installation von Gradle kann auf verschiedenen Wegen erfolgen. Der direkte Download von gradle.org ermöglicht die manuelle Installation, wird aber in der Praxis selten genutzt. Paketmanager wie SDKMAN für Unix-Systeme, Homebrew für macOS oder Chocolatey für Windows vereinfachen Installation und Versionsverwaltung. Der Befehl sdk install gradle installiert unter SDKMAN die aktuelle Version, während sdk use gradle 8.10 zwischen installierten Versionen wechselt.

Die empfohlene Methode für Projektumgebungen ist jedoch der Gradle Wrapper. Dieser macht eine lokale Gradle-Installation überflüssig und garantiert, dass alle Projektbeteiligten exakt dieselbe Gradle-Version verwenden. Der Wrapper besteht aus Shell-Skripten (gradlew für Unix, gradlew.bat für Windows) und einer Konfigurationsdatei, die die zu verwendende Gradle-Version spezifiziert.

3.2 Gradle Wrapper einrichten und verwenden

Der Gradle Wrapper wird mit dem Befehl gradle wrapper initialisiert, sofern eine lokale Gradle-Installation vorhanden ist. Dies erzeugt die Wrapper-Skripte sowie das Verzeichnis gradle/wrapper mit der Datei gradle-wrapper.properties. Diese Properties-Datei enthält die zentrale Konfiguration:

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Die distributionUrl definiert, welche Gradle-Version heruntergeladen wird. Die Verwendung der -all Distribution statt -bin inkludiert Sourcecode und Dokumentation, was beim Debugging hilfreich ist. Nach der Initialisierung verwenden alle Teammitglieder ausschließlich ./gradlew statt gradle, wodurch automatisch die korrekte Version verwendet wird.

Der Wrapper lädt beim ersten Aufruf die spezifizierte Gradle-Version herunter und cached sie im Benutzerverzeichnis unter .gradle/wrapper/dists. Nachfolgende Aufrufe verwenden die gecachte Version. Ein Gradle-Update erfolgt durch Anpassung der Version in der Properties-Datei oder durch den Befehl ./gradlew wrapper --gradle-version=8.10.1. Die Wrapper-Dateien sollten immer in die Versionskontrolle eingecheckt werden.

3.3 Grundlegende Projektstruktur

Gradle erwartet eine definierte Projektstruktur, die durch das angewendete Plugin bestimmt wird. Für Java-Projekte etabliert das Java-Plugin folgende Standardstruktur:

projekt/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle/
│   └── wrapper/
├── src/
│   ├── main/
│   │   ├── java/
│   │   └── resources/
│   └── test/
│       ├── java/
│       └── resources/
└── build/

Das src/main/java Verzeichnis enthält den Produktivcode, während src/test/java die Tests beherbergt. Ressourcen wie Properties-Dateien oder XML-Konfigurationen liegen in den entsprechenden resources Verzeichnissen. Das build Verzeichnis wird von Gradle generiert und enthält alle Build-Artefakte. Es sollte nicht in die Versionskontrolle eingecheckt werden.

Die settings.gradle.kts definiert den Projektnamen und bei Multi-Modul-Projekten die Modulstruktur. Eine minimale Settings-Datei enthält nur rootProject.name = "mein-projekt". Die build.gradle.kts konfiguriert das eigentliche Build-Verhalten, definiert Abhängigkeiten und konfiguriert Tasks.

3.4 Erste Build-Konfiguration

Eine minimale Build-Konfiguration für ein Java-Projekt sieht folgendermaßen aus:

plugins {
    java
    application
}

group = "de.company.projekt"
version = "1.0-SNAPSHOT"

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.slf4j:slf4j-api:2.0.9")
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}

application {
    mainClass.set("de.company.projekt.Main")
}

tasks.test {
    useJUnitPlatform()
}

Diese Konfiguration definiert ein Java-Anwendungsprojekt mit JDK 17, lädt Abhängigkeiten von Maven Central und konfiguriert JUnit 5 für Tests. Die implementation Configuration wird für Compile- und Runtime-Abhängigkeiten verwendet, während testImplementation nur für Tests verfügbar ist.

3.5 Gradle Properties und Umgebungskonfiguration

Gradle-Properties ermöglichen die Externalisierung von Konfigurationswerten. Die Datei gradle.properties im Projektverzeichnis definiert projektspezifische Properties, während ~/.gradle/gradle.properties benutzerspezifische Einstellungen enthält. Systemproperties und Umgebungsvariablen überschreiben diese Werte.

Wichtige Performance-Properties sollten in der projektweiten gradle.properties konfiguriert werden:

org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true

Diese Einstellungen erhöhen den verfügbaren Speicher, aktivieren parallele Task-Ausführung und schalten verschiedene Caching-Mechanismen ein. Die Configuration Cache speichert den konfigurierten Task-Graphen und beschleunigt nachfolgende Builds erheblich.

Sensible Daten wie Passwörter oder API-Keys gehören in die benutzerspezifische Properties-Datei und nicht in die Versionskontrolle. Im Build-Skript können Properties mit project.property("propertyName") oder mit Null-Safe-Access project.findProperty("propertyName") abgerufen werden.

3.6 Erste Build-Befehle und Diagnose

Nach der Grundkonfiguration stehen verschiedene Gradle-Befehle zur Verfügung. Der Befehl ./gradlew tasks listet alle verfügbaren Tasks auf. Mit ./gradlew build wird das Projekt kompiliert, getestet und paketiert. Der Befehl ./gradlew clean löscht das Build-Verzeichnis für einen sauberen Neustart.

3.6.1 Wichtige Gradle-Befehle und Parameter

3.6.1.1 Basis-Befehle

Befehl	Beschreibung	Beispiel
`tasks`	Zeigt alle verfügbaren Tasks an	`./gradlew tasks`
`tasks --all`	Zeigt alle Tasks inkl. interner Tasks	`./gradlew tasks --all`
`build`	Führt kompletten Build durch (compile, test, package)	`./gradlew build`
`clean`	Löscht das build-Verzeichnis	`./gradlew clean`
`test`	Führt nur Tests aus	`./gradlew test`
`assemble`	Erstellt Artefakte ohne Tests	`./gradlew assemble`
`check`	Führt alle Verifikations-Tasks aus	`./gradlew check`

3.6.1.2 Diagnose-Befehle

Befehl	Beschreibung	Verwendungszweck
`dependencies`	Zeigt Abhängigkeitsbaum	Versionskonflikte analysieren
`dependencies --configuration <name>`	Zeigt Abhängigkeiten einer Configuration	Spezifische Dependencies prüfen
`buildEnvironment`	Zeigt Build-Skript-Abhängigkeiten	Plugin-Versionen überprüfen
`projects`	Listet alle Projekte/Module	Multi-Modul-Struktur anzeigen
`properties`	Zeigt alle Projekt-Properties	Konfiguration verifizieren
`help --task <taskname>`	Zeigt Hilfe für spezifischen Task	Task-Optionen verstehen

3.6.1.3 Logging-Parameter

Parameter	Log-Level	Ausgabeumfang	Verwendung
`--quiet` oder `-q`	ERROR	Nur Fehler	CI/CD-Builds
`--warn` oder `-w`	WARN	Fehler und Warnungen	Produktiv-Builds
(Standard)	LIFECYCLE	Normal	Entwicklung
`--info` oder `-i`	INFO	Erweiterte Informationen	Debugging
`--debug` oder `-d`	DEBUG	Vollständige Debug-Ausgabe	Fehleranalyse
`--stacktrace`	-	Zeigt Stacktraces bei Fehlern	Exception-Debugging
`--full-stacktrace`	-	Zeigt vollständige Stacktraces	Tiefe Fehleranalyse

3.6.1.4 Performance- und Analyse-Parameter

Parameter	Beschreibung	Beispiel
`--scan`	Erstellt Build Scan auf scans.gradle.com	`./gradlew build --scan`
`--profile`	Erstellt Performance-Report in build/reports	`./gradlew build --profile`
`--parallel`	Aktiviert parallele Ausführung	`./gradlew build --parallel`
`--build-cache`	Aktiviert Build Cache	`./gradlew build --build-cache`
`--no-build-cache`	Deaktiviert Build Cache	`./gradlew clean build --no-build-cache`
`--dry-run` oder `-m`	Zeigt Tasks ohne Ausführung	`./gradlew build --dry-run`
`--continue`	Führt bei Fehlern fort	`./gradlew test --continue`

3.6.1.5 Konfigurations-Parameter

Parameter	Beschreibung	Beispiel
`-P<property>=<value>`	Setzt Projekt-Property	`./gradlew build -Pversion=1.0`
`-D<property>=<value>`	Setzt System-Property	`./gradlew test -Dtest.single=MyTest`
`--init-script <file>`	Führt Init-Skript aus	`./gradlew build --init-script init.gradle`
`--offline`	Arbeitet ohne Netzwerkzugriff	`./gradlew build --offline`
`--refresh-dependencies`	Aktualisiert alle Dependencies	`./gradlew build --refresh-dependencies`
`--rerun-tasks`	Ignoriert Up-to-date-Checks	`./gradlew test --rerun-tasks`

3.6.2 Kombinierte Verwendung

Befehle und Parameter können kombiniert werden für spezifische Anforderungen:

# Clean Build mit Info-Logging und Build Scan
./gradlew clean build --info --scan

# Nur Tests mit Debug-Output und Fortsetzung bei Fehlern
./gradlew test --debug --continue

# Dependencies für implementation Configuration anzeigen
./gradlew dependencies --configuration implementation

# Build ohne Tests mit paralleler Ausführung
./gradlew assemble --parallel --build-cache

Zur Diagnose von Build-Problemen bietet Gradle umfangreiche Hilfestellungen. Der Parameter --info oder --debug erhöht die Ausgabeverbosität. Mit ./gradlew dependencies wird der komplette Abhängigkeitsbaum visualisiert, was bei Versionskonflikten hilft. Der Befehl ./gradlew buildEnvironment zeigt die Build-Skript-Abhängigkeiten an.

Die Option --scan erstellt einen Build Scan, der detaillierte Informationen über den Build-Prozess sammelt und auf scans.gradle.com visualisiert. Dies umfasst Performance-Metriken, Task-Ausführungszeiten und Dependency-Informationen. Für kommerzielle Projekte kann Gradle Enterprise für interne Build Scans konfiguriert werden.