Gradle Expert
Build system expertise for AmethystMultiplatform's 4-module KMP architecture. Focus: practical troubleshooting, dependency resolution, and project-specific optimizations.
Overview
The Gradle Expert skill provides comprehensive support for the AmethystMultiplatform project's build infrastructure. This skill specializes in managing Gradle build files, version catalogs, and multi-module KMP architecture while ensuring optimal build performance and dependency management.
Core Capabilities
- Build Architecture: Manages the 4-layer KMP architecture with proper dependency flow
- Version Catalog: Maintains centralized dependency configuration in libs.versions.toml
- Module Dependencies: Handles cross-platform dependencies across Android, Desktop, and iOS
- Performance Optimization: Implements build caching and parallel execution strategies
Usage
Build Commands
# Full builds
./gradlew build # All modules
./gradlew clean build # Clean build
# Desktop
./gradlew :desktopApp:run # Run desktop app
./gradlew :desktopApp:packageDmg # macOS package
# Module-specific
./gradlew :quartz:build # KMP library only
./gradlew :commons:build # Shared UI only
# Analysis
./gradlew dependencies # Dependency tree
./gradlew build --scan # Online diagnostics
Configuration Files
// In build.gradle.kts
plugins {
id("org.jetbrains.kotlin.multiplatform")
id("com.android.application")
}
kotlin {
jvm {
compilerOptions {
jvmTarget.set(JvmTarget.JVM_21)
}
}
}
Guidelines
Operational Mode
This section outlines the operational guidelines for maintaining build consistency and performance. The following patterns should be followed to ensure optimal build system behavior.
Build Architecture Mental Model
Think of this project as 4 layers:
┌─────────────┬─────────────┐
│ :amethyst │ :desktopApp │ ← Platform apps (navigation, layouts)
│ (Android) │ (JVM) │
└──────┬──────┴──────┬──────┘
│ │
└──────┬──────┘
▼
┌─────────────┐
│ :commons │ ← Shared UI (KMP with jvmAndroid)
│ (KMP UI) │
└──────┬──────┘
▼
┌─────────────┐
│ :quartz │ ← Core library (KMP: Android/JVM/iOS)
│(KMP Library)│
└─────────────┘
Key insight: Dependencies flow DOWN. Lower modules never depend on upper modules. This enables code sharing without circular dependencies.
The jvmAndroid pattern: Unique to this project. A custom source set between commonMain and {androidMain, jvmMain} for JVM-specific code shared by Android and Desktop. Not standard KMP, but critical for this architecture.
Advanced Configuration
All dependencies centralized in gradle/libs.versions.toml. Think "single source of truth."
Pattern:
[versions]
kotlin = "2.3.0"
[libraries]
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
[plugins]
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
Usage:
dependencies {
implementation(libs.okhttp) // Type-safe, IDE-autocompleted
}
Critical alignments:
- Kotlin ecosystem: All Kotlin plugins MUST share same version
- Compose ecosystem: Compose Multiplatform version → Kotlin version (check compatibility matrix)
- secp256k1 variants: All three variants (common, jni-android, jni-jvm) MUST share same version
See references/version-catalog-guide.md for comprehensive patterns.
Runtime Profile
Common Build Tasks
# Full builds
./gradlew build # All modules
./gradlew clean build # Clean build
# Desktop
./gradlew :desktopApp:run # Run desktop app
./gradlew :desktopApp:packageDmg # macOS package
# Module-specific
./gradlew :quartz:build # KMP library only
./gradlew :commons:build # Shared UI only
# Analysis
./gradlew dependencies # Dependency tree
./gradlew build --scan # Online diagnostics
See references/build-commands.md for comprehensive command reference.
Extended Capabilities
Module Structure & Dependencies
Dependency Flow
Desktop build chain:
:desktopApp → :commons (jvmMain) → :quartz (jvmMain → jvmAndroid → commonMain)
Android build chain:
:amethyst → :commons (androidMain) → :quartz (androidMain → jvmAndroid → commonMain)
Key source set pattern (quartz & commons):
commonMain # Truly cross-platform code
│
├─ jvmAndroid # JVM-specific, shared by Android + Desktop
│ ├─ androidMain
│ └─ jvmMain
│
└─ iosMain # iOS-specific (quartz only)
Dependency config types:
- Use
apiwhen types appear in module's public API or expect/actual declarations - Use
implementationfor internal implementation details - Example: quartz exposes secp256k1 (
api), but hides okhttp (implementation)
See references/dependency-graph.md for module visualization and transitive dependency flow.
Critical Dependency Patterns
1. secp256k1 (Crypto Library)
The problem: KMP library with platform-specific JNI bindings. Wrong variant = runtime crash.
Pattern:
// commonMain - API only
api(libs.secp256k1.kmp.common)
// androidMain - Android JNI
api(libs.secp256k1.kmp.jni.android)
// jvmMain - Desktop JVM JNI
implementation(libs.secp256k1.kmp.jni.jvm)
Why api in androidMain? Types leak to consumers (:amethyst).
Common error: Desktop using jni-android variant → UnsatisfiedLinkError: no secp256k1jni in java.library.path
Fix: Check source set dependencies. jvmMain must use jni-jvm, never jni-android.
2. JNA (for LibSodium Encryption)
The problem: Android needs AAR packaging, JVM needs JAR. Same library, different artifact types.
Pattern:
// androidMain
implementation("com.goterl:lazysodium-android:5.2.0@aar") // @aar explicit
implementation("net.java.dev.jna:jna:5.18.1@aar")
// jvmMain
implementation(libs.lazysodium.java) // JAR implicit
implementation(libs.jna)
Critical: Never put JNA in jvmAndroid or commonMain. Platform-specific packaging only.
3. Compose Versions
The problem: Two Compose ecosystems (Multiplatform + AndroidX) must align, or duplicate classes.
Current project config:
composeMultiplatform = "1.9.3" # Plugin + runtime
composeBom = "2025.12.01" # AndroidX Compose BOM
kotlin = "2.3.0"
Rule: Compose Multiplatform version must be compatible with Kotlin version. Check: https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-compatibility-and-versioning.html
In KMP modules (quartz, commons):
// ✅ Use Compose Multiplatform
implementation(compose.ui)
implementation(compose.material3)
// ❌ DON'T use AndroidX BOM in KMP modules
// implementation(libs.androidx.compose.bom)
In Android-only modules (amethyst):
// Can use AndroidX BOM
val composeBom = platform(libs.androidx.compose.bom)
implementation(composeBom)
4. Desktop Packaging
TargetFormat options:
// In desktopApp/build.gradle.kts
nativeDistributions {
targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
packageName = "Amethyst"
packageVersion = "1.0.0"
macOS {
bundleID = "com.vitorpamplona.amethyst.desktop"
iconFile.set(project.file("src/jvmMain/resources/icon.icns"))
}
}
Package tasks:
./gradlew :desktopApp:packageDmg # macOS
./gradlew :desktopApp:packageMsi # Windows
./gradlew :desktopApp:packageDeb # Linux
Output locations:
- macOS:
desktopApp/build/compose/binaries/main/dmg/ - Windows:
desktopApp/build/compose/binaries/main/msi/ - Linux:
desktopApp/build/compose/binaries/main/deb/
Icon requirements:
- macOS:
.icns(multi-resolution: 512, 256, 128, 32) - Windows:
.ico(256, 128, 64, 32, 16) - Linux:
.png(512x512)
Common issues:
- Main class not found → Verify
mainClass = "...MainKt"(Kotlin addsKtsuffix) - Native libs missing → Ensure secp256k1-kmp-jni-jvm in dependencies
- Icon not found → Check file exists at path, use absolute path if needed
5. Build Performance
Add to gradle.properties:
# Daemon (faster subsequent builds)
org.gradle.daemon=true
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g
# Parallel execution (multi-module speedup)
org.gradle.parallel=true
org.gradle.workers.max=8
# Caching (incremental builds)
org.gradle.caching=true
org.gradle.configuration-cache=true
# Kotlin daemon
kotlin.incremental=true
kotlin.daemon.jvmargs=-Xmx2g
Impact: Typically 30-50% faster builds after first run.
Measure impact:
./gradlew clean build --profile
# Report: build/reports/profile/profile-<timestamp>.html
When to clean build:
- After changing version catalog
- After adding/removing source sets
- When seeing unexplained errors
When NOT to clean:
- Regular development iteration
- Small code changes
- Incremental compilation works fine
Use script: scripts/analyze-build-time.sh for automated profiling.
6. Troubleshooting: Practical Patterns
Pattern 1: Version Conflict
Symptom: Duplicate class or NoSuchMethodError
Diagnosis:
./gradlew dependencyInsight --dependency <library-name>
Fix options:
- Align versions in libs.versions.toml (preferred)
- Force resolution:
configurations.all {
resolutionStrategy {
force(libs.okhttp.get().toString())
}
}
Pattern 2: Source Set Issues
Symptom: Unresolved reference to JVM library in shared code
Diagnosis: Check source set hierarchy. JVM-only libs (jackson, okhttp) can't be in commonMain.
Fix: Move to jvmAndroid or platform-specific source set.
// ❌ Wrong
commonMain {
dependencies {
implementation(libs.jackson.module.kotlin) // JVM-only!
}
}
// ✅ Correct
val jvmAndroid = create("jvmAndroid") {
dependsOn(commonMain.get())
dependencies {
api(libs.jackson.module.kotlin) // JVM code, shared by Android + Desktop
}
}
Pattern 3: Proguard Stripping Native Libs
Symptom: NoClassDefFoundError for secp256k1, JNA, or LibSodium in release builds
Fix: Update proguard rules in quartz/proguard-rules.pro:
# Native libraries
-keep class fr.acinq.secp256k1.** { *; }
-keep class com.goterl.lazysodium.** { *; }
-keep class com.sun.jna.** { *; }
# Jackson (reflection-based)
-keep class com.vitorpamplona.quartz.** { *; }
-keepattributes *Annotation*
-keepattributes Signature
Pattern 4: Compose Compiler Mismatch
Symptom: IllegalStateException: Version mismatch: runtime 1.10.0 but compiler 1.9.0
Fix: Update Compose Multiplatform version in libs.versions.toml to match Kotlin version compatibility.
Check: https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-compatibility-and-versioning.html
Pattern 5: Wrong JVM Target
Symptom: Unsupported class file major version 65
Fix: Ensure Java 21 everywhere:
# Check current Java
java -version # Should show 21
# Set JAVA_HOME
export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
# Stop Gradle daemon to pick up new Java
./gradlew --stop
Verify all build files use JVM 21:
kotlin {
jvm {
compilerOptions {
jvmTarget.set(JvmTarget.JVM_21)
}
}
}
android {
compileOptions {
sourceCompatibility = JavaVersion.VERSION_21
targetCompatibility = JavaVersion.VERSION_21
}
}
7. Comprehensive Error Guide
For detailed troubleshooting of specific errors, see references/common-errors.md. Covers:
- Compose version conflicts
- secp256k1 JNI errors
- Source set dependency issues
- Proguard/R8 problems
- Desktop packaging errors
- Kotlin compilation errors
- Dependency resolution failures
- JVM/JDK version issues
Each error includes: symptom, cause, solution, verification steps.
8. Quick Diagnostic Commands
# Check dependencies for specific module
./gradlew :quartz:dependencies
# Find specific library in dependency tree
./gradlew dependencyInsight --dependency okhttp
# Build with detailed logging
./gradlew build --info
# Generate interactive build scan (best diagnostics)
./gradlew build --scan
# Profile build performance
./gradlew clean build --profile
# Stop all Gradle daemons (fresh start)
./gradlew --stop
# Check Gradle version
./gradlew --version
9. Scripts & References
Diagnostic Scripts
scripts/analyze-build-time.sh- Profile build performance, generate optimization reportscripts/fix-dependency-conflicts.sh- Diagnose common dependency conflicts, suggest fixes
Reference Docs
references/build-commands.md- Comprehensive command reference for all tasksreferences/dependency-graph.md- Module dependencies, source set hierarchy, transitive depsreferences/version-catalog-guide.md- Version catalog patterns, usage, best practicesreferences/common-errors.md- Troubleshooting guide for frequent build issues
10. Workflow Examples
Example 1: Adding New Dependency
Task: Add kotlinx.datetime to quartz
Steps:
- Update version catalog (gradle/libs.versions.toml):
[versions]
kotlinxDatetime = "0.6.0"
[libraries]
kotlinx-datetime = { group = "org.jetbrains.kotlinx", name = "kotlinx-datetime", version.ref = "kotlinxDatetime" }
- Add to build file (quartz/build.gradle.kts):
sourceSets {
commonMain {
dependencies {
implementation(libs.kotlinx.datetime) // KMP library, goes in commonMain
}
}
}
- Sync & verify:
./gradlew :quartz:dependencies | grep datetime
Example 2: Fixing secp256k1 Error on Desktop
Error: UnsatisfiedLinkError: no secp256k1jni in java.library.path when running desktop app
Diagnosis:
./gradlew :desktopApp:dependencies --configuration runtimeClasspath | grep secp256k1
# Shows: secp256k1-kmp-jni-android ← WRONG!
Fix:
// In quartz/build.gradle.kts
jvmMain {
dependencies {
// Change from:
// implementation(libs.secp256k1.kmp.jni.android) ❌
// To:
implementation(libs.secp256k1.kmp.jni.jvm) // ✅
}
}
Verify:
./gradlew :desktopApp:dependencies --configuration runtimeClasspath | grep secp256k1
# Now shows: secp256k1-kmp-jni-jvm ✅
./gradlew :desktopApp:run # Should work
Example 3: Optimizing Build Time
Current: Clean build takes 5 minutes
Steps:
- Baseline measurement:
./gradlew clean build --profile
# Check: build/reports/profile/profile-*.html
- Add optimizations to gradle.properties:
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true
org.gradle.jvmargs=-Xmx4g
kotlin.incremental=true
- Re-measure:
./gradlew clean build --profile
Expected improvement: 30-50% faster on subsequent builds (incremental builds much faster).
11. Delegation Patterns
When to delegate to other skills:
- Source set architecture (jvmAndroid pattern, expect/actual) → Use
kotlin-multiplatformskill - Compose UI issues (composables, state management) → Use
compose-expertskill (when available) - Kotlin language issues (Flow, sealed classes, DSLs) → Use
kotlin-expertskill - Desktop-specific features (Window management, MenuBar, tray) → Use
desktop-expertskill
This skill handles: Build system, dependencies, versioning, module structure, packaging, performance.
12. Core Principles for This Build System
Centralize versions: Never hardcode versions in build.gradle.kts. Always use libs.versions.toml.
Respect source set hierarchy: Dependencies flow downward. jvmAndroid depends on commonMain, never the reverse.
Platform-specific variants matter: secp256k1, JNA must use correct variant per platform. Check when errors occur.
Clean builds are expensive: Use incremental compilation. Only clean when truly needed (source set changes, version updates).
Compose alignment is critical: Compose Multiplatform version must match Kotlin version. Check compatibility matrix.
Proguard for native libs: All JNI libraries need explicit
-keeprules in release builds.Java 21 everywhere: All modules, all targets, consistent JVM version.