bollwerk/.github/skills/android-build/SKILL.md

name	description
android-build	Android-App bauen (assembleDebug/Release), Gradle-Kommandos, häufige Build-Fehler beheben. Verwende diesen Skill für alles rund um Kompilierung, Gradle, Dependency-Management und Build-Konfiguration. Trigger-Phrasen: 'build', 'bauen', 'kompilieren', 'assembleDebug', 'Gradle', 'dependency', 'APK'.

Skill: Android Build

Baut die Bollwerk-Android-App mit Gradle. Handhabt bekannte Fallstricke auf diesem Windows-Setup.

---

Voraussetzungen

Komponente	Pfad / Wert
Android SDK	C:\Users\JensR\AppData\Local\Android\Sdk
ANDROID_HOME	User-Umgebungsvariable (persistent gesetzt)
local.properties	sdk.dir=C\\:\\\\Users\\\\JensR\\\\AppData\\\\Local\\\\Android\\\\Sdk
Java	OpenJDK 21 (im PATH)
Gradle	8.11.1 (via Wrapper)
Kotlin	2.1.10
AGP	8.7.3

---

Build-Kommandos

Verwende immer das android-dev.ps1-Skript statt roher Gradle-Aufrufe:

# Debug-Build (Standard)
& ".github/skills/android-build/android-dev.ps1" -Action build

# Clean + Build (bei File-Locks oder korruptem Cache)
& ".github/skills/android-build/android-dev.ps1" -Action clean-build

# Nur clean
& ".github/skills/android-build/android-dev.ps1" -Action clean

# Hot Reload: Build + Install + Relaunch auf laufendem Emulator (ohne Neustart)
& ".github/skills/android-build/android-dev.ps1" -Action hot-reload

Screenshot

Screenshots sind ein eigenständiges Skript (nicht Teil von android-dev.ps1):

# Screenshot mit PNG-Validierung
& ".github/skills/android-build/screenshot.ps1"

# Screenshot + sichtbare UI-Texte extrahieren
& ".github/skills/android-build/screenshot.ps1" -UiDump

Wichtig: Niemals adb exec-out screencap -p > file.png in PowerShell verwenden – PowerShell konvertiert Binärdaten in UTF-16 und zerstört den PNG-Header.

Direkter Gradle-Aufruf (Fallback)

Falls das Skript nicht verfügbar ist, gibt es zwei verlässliche Varianten:

Variante A – via execution_subagent (empfohlen)

cd x:\bollwerk ; .\gradlew assembleDebug test

• .\gradlew (ohne .bat) funktioniert hier einwandfrei
• Kein | Out-String nötig – execution_subagent wertet den Output korrekt aus
• Tasks können kombiniert werden: assembleDebug test, assembleDebug assembleRelease etc.
• execution_subagent meldet BUILD SUCCESSFUL zuverlässig, auch wenn Gradle Warnungen auf stderr ausgibt

Variante B – via run_in_terminal (PowerShell direkt)

$env:ANDROID_HOME = "C:\Users\JensR\AppData\Local\Android\Sdk"
cd "x:\bollwerk"
.\gradlew.bat assembleDebug 2>&1 | Out-String

Wichtig: Hier muss .\gradlew.bat (mit .bat) und | Out-String verwendet werden – ohne .bat kann PowerShell die Ausgabe falsch interpretieren; ohne | Out-String werden stderr-Warnungen als Fehler gewertet und Exit-Code 1 zurückgegeben, obwohl Gradle BUILD SUCCESSFUL meldet.

---

Bekannte Probleme

1. Build-Dateien gesperrt (AccessDeniedException)

Dateien im build/-Verzeichnis können durch andere Prozesse gesperrt sein.

Lösung:

Remove-Item "app\build" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "build" -Recurse -Force -ErrorAction SilentlyContinue
# Dann erneut bauen

Das android-dev.ps1-Skript macht dies automatisch bei -Action clean-build.

2. PowerShell zeigt Exit-Code 1 trotz BUILD SUCCESSFUL

Gradle gibt Deprecation-Warnungen auf stderr aus. PowerShell wertet das als Fehler.

Lösung: Prüfe den Gradle-Output auf BUILD SUCCESSFUL, nicht den Exit-Code.

3. Batchvorgang abbrechen (J/N)?

Tritt auf, wenn gradlew.bat ein Ctrl+C-Signal empfängt (z.B. durch Terminal-Timeout).

Lösung: Verwende | Out-String und ausreichend Timeout (600s+). Das android-dev.ps1-Skript umgeht dieses Problem.

4. android.useAndroidX fehlt

gradle.properties muss enthalten:
android.useAndroidX=true

---

APK-Ausgabe

Variante	Pfad
Debug	app/build/outputs/apk/debug/app-debug.apk
Release	app/build/outputs/apk/release/app-release.apk

---

Terminal-Aufruf-Konventionen

# Immer so aufrufen:
run_in_terminal mode=sync timeout=600000

Gradle-Builds dauern beim ersten Mal 2–5 Minuten (Daemon-Start + Download). Folge-Builds: 10–30 Sekunden.