Gradle Expert

Build system expertise for AmethystMultiplatform's 10-module KMP architecture (amethyst, benchmark, quartz, geode, commons, quic, nestsClient, desktopApp, cli, quic-interop — see settings.gradle.kts). Focus: practical troubleshooting, dependency resolution, and project-specific optimizations.

Build Architecture Mental Model

The core app stack is 4 layers (the other modules hang off it: cli and geode are JVM apps over commons/quartz, nestsClient sits on quic, benchmark and quic-interop are test harnesses):

┌─────────────┬─────────────┐
│ :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.

Version Catalog Philosophy

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.

Common Build Tasks

Quick Reference

# 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.

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 api when types appear in module's public API or expect/actual declarations
• Use implementation for 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 (always re-check gradle/libs.versions.toml — these drift):

composeMultiplatform = "1.11.1"  # Plugin + runtime
composeBom = "2026.05.01"        # AndroidX Compose BOM
kotlin = "2.3.21"

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)

Desktop Packaging Basics

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 adds Kt suffix)
• Native libs missing → Ensure secp256k1-kmp-jni-jvm in dependencies
• Icon not found → Check file exists at path, use absolute path if needed

Build Performance Optimization

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.

Troubleshooting: Practical Patterns

Pattern 1: Version Conflict

Symptom: Duplicate class or NoSuchMethodError

Diagnosis:

./gradlew dependencyInsight --dependency <library-name>

Fix options:

1. Align versions in libs.versions.toml (preferred)
2. 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
    }
}

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.

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

Scripts & References

Diagnostic Scripts

• scripts/analyze-build-time.sh - Profile build performance, generate optimization report
• scripts/fix-dependency-conflicts.sh - Diagnose common dependency conflicts, suggest fixes

Reference Docs

• references/build-commands.md - Comprehensive command reference for all tasks
• references/dependency-graph.md - Module dependencies, source set hierarchy, transitive deps
• references/version-catalog-guide.md - Version catalog patterns, usage, best practices
• references/common-errors.md - Troubleshooting guide for frequent build issues

Workflow Examples

Example 1: Adding New Dependency

Task: Add kotlinx.datetime to quartz

Steps:

1. 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" }

2. Add to build file (quartz/build.gradle.kts):

sourceSets {
    commonMain {
        dependencies {
            implementation(libs.kotlinx.datetime)  // KMP library, goes in commonMain
        }
    }
}

3. 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:

1. Baseline measurement:

./gradlew clean build --profile
# Check: build/reports/profile/profile-*.html

2. 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

3. Re-measure:

./gradlew clean build --profile

Expected improvement: 30-50% faster on subsequent builds (incremental builds much faster).

Delegation Patterns

When to delegate to other skills:

• Source set architecture (jvmAndroid pattern, expect/actual) → Use kotlin-multiplatform skill
• Compose UI issues (composables, state management) → Use compose-expert skill (when available)
• Kotlin language issues (Flow, sealed classes, DSLs) → Use kotlin-expert skill
• Desktop-specific features (Window management, MenuBar, tray) → Use desktop-expert skill

This skill handles: Build system, dependencies, versioning, module structure, packaging, performance.

Core Principles for This Build System

1. Centralize versions: Never hardcode versions in build.gradle.kts. Always use libs.versions.toml.

2. Respect source set hierarchy: Dependencies flow downward. jvmAndroid depends on commonMain, never the reverse.

3. Platform-specific variants matter: secp256k1, JNA must use correct variant per platform. Check when errors occur.

4. Clean builds are expensive: Use incremental compilation. Only clean when truly needed (source set changes, version updates).

5. Compose alignment is critical: Compose Multiplatform version must match Kotlin version. Check compatibility matrix.

6. Proguard for native libs: All JNI libraries need explicit -keep rules in release builds.

7. Java 21 everywhere: All modules, all targets, consistent JVM version.