nrobi144
644 lines
14 KiB
Markdown
644 lines
14 KiB
Markdown
# Common Build Errors & Solutions
|
|
|
|
## Table of Contents
|
|
- [Compose Version Conflicts](#compose-version-conflicts)
|
|
- [secp256k1 JNI Errors](#secp256k1-jni-errors)
|
|
- [Source Set Dependency Issues](#source-set-dependency-issues)
|
|
- [Proguard/R8 Issues](#proguardr8-issues)
|
|
- [Desktop Packaging Errors](#desktop-packaging-errors)
|
|
- [Kotlin Compilation Errors](#kotlin-compilation-errors)
|
|
- [Dependency Resolution Failures](#dependency-resolution-failures)
|
|
- [JVM/JDK Version Issues](#jvmjdk-version-issues)
|
|
|
|
---
|
|
|
|
## Compose Version Conflicts
|
|
|
|
### Error 1: Compose Runtime Mismatch
|
|
|
|
```
|
|
java.lang.IllegalStateException: Version mismatch: Compose runtime is 1.10.0 but compiler is 1.9.0
|
|
```
|
|
|
|
**Cause:** Compose Compiler plugin version doesn't match Compose Runtime
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In gradle/libs.versions.toml
|
|
composeMultiplatform = "1.9.3" // Must align with Kotlin version
|
|
kotlin = "2.3.0"
|
|
|
|
// Check compatibility matrix:
|
|
// https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-compatibility-and-versioning.html
|
|
```
|
|
|
|
**Verification:**
|
|
```bash
|
|
./gradlew :commons:dependencies | grep compose
|
|
```
|
|
|
|
### Error 2: AndroidX Compose BOM Conflict
|
|
|
|
```
|
|
Duplicate class androidx.compose.ui.platform.AndroidCompositionLocalMap found in modules...
|
|
```
|
|
|
|
**Cause:** Both Compose Multiplatform and AndroidX Compose BOM providing same classes
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In commons/build.gradle.kts (KMP module)
|
|
// Use Compose Multiplatform, NOT AndroidX BOM
|
|
dependencies {
|
|
implementation(compose.ui) // ✅ Compose Multiplatform
|
|
implementation(compose.material3)
|
|
|
|
// Don't use in KMP modules:
|
|
// implementation(libs.androidx.compose.bom) // ❌ Android-only
|
|
}
|
|
|
|
// In amethyst/build.gradle.kts (Android-only module)
|
|
// Can use AndroidX BOM
|
|
dependencies {
|
|
val composeBom = platform(libs.androidx.compose.bom)
|
|
implementation(composeBom)
|
|
implementation(libs.androidx.ui)
|
|
}
|
|
```
|
|
|
|
### Error 3: Material3 WindowSizeClass Not Found
|
|
|
|
```
|
|
Unresolved reference: WindowSizeClass
|
|
```
|
|
|
|
**Cause:** Using Android's WindowSizeClass in shared KMP code
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// Don't use in commonMain or jvmAndroid:
|
|
// import androidx.compose.material3.windowsizeclass.WindowSizeClass // ❌
|
|
|
|
// Use in androidMain only, or create expect/actual:
|
|
// commonMain
|
|
expect class WindowSizeClassAdapter
|
|
|
|
// androidMain
|
|
actual typealias WindowSizeClassAdapter = androidx.compose.material3.windowsizeclass.WindowSizeClass
|
|
|
|
// jvmMain (desktop)
|
|
actual class WindowSizeClassAdapter { /* Custom impl */ }
|
|
```
|
|
|
|
---
|
|
|
|
## secp256k1 JNI Errors
|
|
|
|
### Error 1: JNI Library Not Found (Desktop)
|
|
|
|
```
|
|
java.lang.UnsatisfiedLinkError: no secp256k1jni in java.library.path
|
|
```
|
|
|
|
**Cause:** Desktop using wrong secp256k1 variant (Android JNI instead of JVM JNI)
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In quartz/build.gradle.kts
|
|
sourceSets {
|
|
jvmMain {
|
|
dependencies {
|
|
// ✅ Correct - JVM variant
|
|
implementation(libs.secp256k1.kmp.jni.jvm)
|
|
|
|
// ❌ Wrong - Android variant
|
|
// implementation(libs.secp256k1.kmp.jni.android)
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Verification:**
|
|
```bash
|
|
./gradlew :quartz:dependencies --configuration jvmRuntimeClasspath | grep secp256k1
|
|
# Should show: secp256k1-kmp-jni-jvm, NOT jni-android
|
|
```
|
|
|
|
### Error 2: Version Mismatch Between Variants
|
|
|
|
```
|
|
java.lang.NoSuchMethodError: fr.acinq.secp256k1.Secp256k1.sign
|
|
```
|
|
|
|
**Cause:** Common, Android, and JVM variants have different versions
|
|
|
|
**Solution:**
|
|
```toml
|
|
# In gradle/libs.versions.toml
|
|
# All three MUST use same version
|
|
secp256k1KmpJniAndroid = "0.22.0"
|
|
|
|
[libraries]
|
|
secp256k1-kmp-common = { ..., version.ref = "secp256k1KmpJniAndroid" }
|
|
secp256k1-kmp-jni-android = { ..., version.ref = "secp256k1KmpJniAndroid" }
|
|
secp256k1-kmp-jni-jvm = { ..., version.ref = "secp256k1KmpJniAndroid" }
|
|
```
|
|
|
|
### Error 3: Android JNI Not Loaded
|
|
|
|
```
|
|
java.lang.UnsatisfiedLinkError: dalvik.system.PathClassLoader couldn't find "libsecp256k1jni.so"
|
|
```
|
|
|
|
**Cause:** Proguard stripping JNI classes
|
|
|
|
**Solution:**
|
|
```proguard
|
|
# In quartz/proguard-rules.pro
|
|
-keep class fr.acinq.secp256k1.** { *; }
|
|
```
|
|
|
|
---
|
|
|
|
## Source Set Dependency Issues
|
|
|
|
### Error 1: jvmAndroid Defined After androidMain
|
|
|
|
```
|
|
Could not get unknown property 'jvmAndroid' for source set container
|
|
```
|
|
|
|
**Cause:** Source sets must be defined in dependency order
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// ✅ Correct order
|
|
sourceSets {
|
|
commonMain { }
|
|
|
|
// Define jvmAndroid BEFORE androidMain and jvmMain
|
|
val jvmAndroid = create("jvmAndroid") {
|
|
dependsOn(commonMain.get())
|
|
}
|
|
|
|
androidMain {
|
|
dependsOn(jvmAndroid) // Now jvmAndroid exists
|
|
}
|
|
|
|
jvmMain {
|
|
dependsOn(jvmAndroid)
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error 2: Dependency in Wrong Source Set
|
|
|
|
```
|
|
Unresolved reference: ObjectMapper (Jackson)
|
|
```
|
|
|
|
**Cause:** JVM-only library in commonMain
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
sourceSets {
|
|
commonMain {
|
|
// ❌ Jackson is JVM-only, can't use here
|
|
// implementation(libs.jackson.module.kotlin)
|
|
}
|
|
|
|
val jvmAndroid = create("jvmAndroid") {
|
|
dependsOn(commonMain.get())
|
|
// ✅ Jackson in jvmAndroid (shared JVM code)
|
|
api(libs.jackson.module.kotlin)
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error 3: Platform-Specific Code in Shared Source Set
|
|
|
|
```
|
|
java.lang.NoClassDefFoundError: android.content.Context
|
|
```
|
|
|
|
**Cause:** Android-specific API in jvmAndroid or commonMain
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// Use expect/actual pattern
|
|
|
|
// commonMain
|
|
expect class PlatformContext
|
|
|
|
// androidMain
|
|
actual typealias PlatformContext = android.content.Context
|
|
|
|
// jvmMain
|
|
actual class PlatformContext {
|
|
// Custom desktop implementation
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Proguard/R8 Issues
|
|
|
|
### Error 1: Native Library Classes Stripped
|
|
|
|
```
|
|
java.lang.NoClassDefFoundError: com.goterl.lazysodium.Sodium
|
|
```
|
|
|
|
**Cause:** R8/Proguard removing JNA/LibSodium classes
|
|
|
|
**Solution:**
|
|
```proguard
|
|
# In quartz/proguard-rules.pro
|
|
-keep class com.goterl.lazysodium.** { *; }
|
|
-keep class com.sun.jna.** { *; }
|
|
-keep class fr.acinq.secp256k1.** { *; }
|
|
```
|
|
|
|
### Error 2: Reflection-Based Libraries Broken
|
|
|
|
```
|
|
com.fasterxml.jackson.databind.exc.InvalidDefinitionException: Cannot construct instance of ...
|
|
```
|
|
|
|
**Cause:** Jackson uses reflection, R8 strips class metadata
|
|
|
|
**Solution:**
|
|
```proguard
|
|
# Preserve reflection metadata
|
|
-keepattributes *Annotation*
|
|
-keepattributes Signature
|
|
-keepattributes InnerClasses
|
|
|
|
# Keep all Quartz event classes
|
|
-keep class com.vitorpamplona.quartz.** { *; }
|
|
```
|
|
|
|
### Error 3: Enum Values Missing
|
|
|
|
```
|
|
java.lang.IllegalArgumentException: No enum constant ...
|
|
```
|
|
|
|
**Cause:** R8 obfuscating enum names
|
|
|
|
**Solution:**
|
|
```proguard
|
|
# Keep all enums
|
|
-keep enum ** { *; }
|
|
-keepnames class ** { *; }
|
|
```
|
|
|
|
---
|
|
|
|
## Desktop Packaging Errors
|
|
|
|
### Error 1: Icon Not Found
|
|
|
|
```
|
|
FAILURE: Build failed with an exception.
|
|
* What went wrong: Cannot find icon file: src/jvmMain/resources/icon.icns
|
|
```
|
|
|
|
**Cause:** Icon file missing or wrong path
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In desktopApp/build.gradle.kts
|
|
nativeDistributions {
|
|
macOS {
|
|
// Ensure file exists at this path
|
|
iconFile.set(project.file("src/jvmMain/resources/icon.icns"))
|
|
}
|
|
|
|
// Check file exists:
|
|
// ls -la desktopApp/src/jvmMain/resources/
|
|
}
|
|
```
|
|
|
|
**Icon Requirements:**
|
|
- macOS: `.icns` (512x512, 256x256, 128x128, 32x32)
|
|
- Windows: `.ico` (256x256, 128x128, 64x64, 32x32, 16x16)
|
|
- Linux: `.png` (512x512 recommended)
|
|
|
|
### Error 2: Main Class Not Found
|
|
|
|
```
|
|
Error: Could not find or load main class com.vitorpamplona.amethyst.desktop.MainKt
|
|
```
|
|
|
|
**Cause:** Wrong mainClass path or Main.kt doesn't have main()
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In desktopApp/build.gradle.kts
|
|
compose.desktop {
|
|
application {
|
|
mainClass = "com.vitorpamplona.amethyst.desktop.MainKt"
|
|
// ^^^^
|
|
// Kotlin compiler adds "Kt" suffix
|
|
}
|
|
}
|
|
|
|
// In src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt
|
|
fun main() = application {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
### Error 3: Native Library Missing in Package
|
|
|
|
```
|
|
java.lang.UnsatisfiedLinkError: no secp256k1jni in java.library.path
|
|
```
|
|
|
|
**Cause:** Native libraries not bundled in distribution
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// Native libs are automatically included via dependencies
|
|
// Verify secp256k1-kmp-jni-jvm is in dependencies:
|
|
dependencies {
|
|
implementation(libs.secp256k1.kmp.jni.jvm) // ✅ Includes native libs
|
|
}
|
|
|
|
// Test packaged app:
|
|
./gradlew :desktopApp:createDistributable
|
|
# Run from: desktopApp/build/compose/binaries/main/app/
|
|
```
|
|
|
|
---
|
|
|
|
## Kotlin Compilation Errors
|
|
|
|
### Error 1: Expect/Actual Mismatch
|
|
|
|
```
|
|
'actual' declaration has no corresponding expected declaration
|
|
```
|
|
|
|
**Cause:** Signature mismatch or missing expect
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// commonMain - expect declaration
|
|
expect class CryptoProvider {
|
|
fun sign(message: ByteArray, privateKey: ByteArray): ByteArray
|
|
}
|
|
|
|
// androidMain & jvmMain - actual must match EXACTLY
|
|
actual class CryptoProvider {
|
|
actual fun sign(message: ByteArray, privateKey: ByteArray): ByteArray {
|
|
// Implementation
|
|
}
|
|
}
|
|
|
|
// Common mistakes:
|
|
// - Different parameter names ❌
|
|
// - Different return types ❌
|
|
// - Missing 'actual' modifier ❌
|
|
```
|
|
|
|
### Error 2: Target JVM Version Mismatch
|
|
|
|
```
|
|
Compilation failed: module was compiled with an incompatible version of Kotlin
|
|
```
|
|
|
|
**Cause:** Different JVM targets across modules
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// Ensure ALL modules use same JVM target
|
|
|
|
// In quartz/build.gradle.kts
|
|
kotlin {
|
|
jvm {
|
|
compilerOptions {
|
|
jvmTarget.set(JvmTarget.JVM_21) // ✅ Java 21
|
|
}
|
|
}
|
|
}
|
|
|
|
// In android {} block
|
|
compileOptions {
|
|
sourceCompatibility = JavaVersion.VERSION_21
|
|
targetCompatibility = JavaVersion.VERSION_21
|
|
}
|
|
```
|
|
|
|
### Error 3: Compose Compiler Plugin Missing
|
|
|
|
```
|
|
This declaration needs opt-in. Please use @OptIn(ComposeApi::class) or @Composable
|
|
```
|
|
|
|
**Cause:** Compose compiler plugin not applied
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In build.gradle.kts
|
|
plugins {
|
|
alias(libs.plugins.jetbrainsComposeCompiler) // ✅ Add this
|
|
alias(libs.plugins.composeMultiplatform)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dependency Resolution Failures
|
|
|
|
### Error 1: Repository Not Found
|
|
|
|
```
|
|
Could not find com.github.vitorpamplona.compose-richtext:richtext-ui:f92ef49c9d
|
|
```
|
|
|
|
**Cause:** Jitpack or custom Maven repository not configured
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In settings.gradle
|
|
dependencyResolutionManagement {
|
|
repositories {
|
|
google()
|
|
mavenCentral()
|
|
maven { url = "https://jitpack.io" } // ✅ Add Jitpack
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error 2: Gradle Version Too Old
|
|
|
|
```
|
|
Version catalogs are not supported in this version of Gradle
|
|
```
|
|
|
|
**Cause:** Gradle < 7.0
|
|
|
|
**Solution:**
|
|
```properties
|
|
# In gradle/wrapper/gradle-wrapper.properties
|
|
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
|
|
```
|
|
|
|
Then: `./gradlew wrapper --gradle-version=8.9`
|
|
|
|
### Error 3: Dependency Variant Not Found
|
|
|
|
```
|
|
No matching variant of fr.acinq.secp256k1:secp256k1-kmp-jni-android:0.22.0 was found
|
|
```
|
|
|
|
**Cause:** Wrong dependency configuration for target
|
|
|
|
**Solution:**
|
|
```kotlin
|
|
// In androidMain (Android library module)
|
|
dependencies {
|
|
// For AAR packaging
|
|
implementation("net.java.dev.jna:jna:5.18.1@aar") // ✅ Specify @aar
|
|
|
|
// secp256k1 works without @aar (auto-detects)
|
|
api(libs.secp256k1.kmp.jni.android)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## JVM/JDK Version Issues
|
|
|
|
### Error 1: Unsupported Class File Version
|
|
|
|
```
|
|
Unsupported class file major version 65
|
|
```
|
|
|
|
**Cause:** Compiled with Java 21, running with older Java
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check Java version
|
|
java -version # Should show 21
|
|
|
|
# Set JAVA_HOME if needed
|
|
export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
|
|
|
|
# Or in gradle.properties
|
|
org.gradle.java.home=/path/to/jdk-21
|
|
```
|
|
|
|
### Error 2: JVM Toolchain Not Found
|
|
|
|
```
|
|
No matching toolchain found for requested JvmVersion
|
|
```
|
|
|
|
**Cause:** Java 21 not installed or not detected
|
|
|
|
**Solution:**
|
|
```bash
|
|
# macOS (Homebrew)
|
|
brew install openjdk@21
|
|
|
|
# Ubuntu
|
|
sudo apt install openjdk-21-jdk
|
|
|
|
# Set JAVA_HOME
|
|
export JAVA_HOME=$(/usr/libexec/java_home -v 21) # macOS
|
|
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk # Linux
|
|
|
|
# Verify
|
|
./gradlew -version
|
|
```
|
|
|
|
### Error 3: Gradle Daemon Using Wrong Java
|
|
|
|
```
|
|
Daemon will be stopped at the end of the build because JVM version has changed
|
|
```
|
|
|
|
**Cause:** Daemon started with different Java version
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Stop all daemons
|
|
./gradlew --stop
|
|
|
|
# Start with correct JAVA_HOME
|
|
export JAVA_HOME=/path/to/jdk-21
|
|
./gradlew build
|
|
|
|
# Or set in gradle.properties permanently
|
|
org.gradle.java.home=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
|
|
```
|
|
|
|
---
|
|
|
|
## General Troubleshooting Steps
|
|
|
|
### Step 1: Clean Build
|
|
```bash
|
|
./gradlew clean
|
|
./gradlew --stop # Stop daemon
|
|
./gradlew build
|
|
```
|
|
|
|
### Step 2: Check Dependencies
|
|
```bash
|
|
./gradlew :moduleName:dependencies
|
|
./gradlew dependencyInsight --dependency libraryName
|
|
```
|
|
|
|
### Step 3: Enable Debug Logging
|
|
```bash
|
|
./gradlew build --info # Info logging
|
|
./gradlew build --debug # Debug logging (verbose)
|
|
./gradlew build --stacktrace
|
|
```
|
|
|
|
### Step 4: Invalidate Caches
|
|
```bash
|
|
# Clear Gradle cache
|
|
rm -rf ~/.gradle/caches/
|
|
|
|
# Clear build outputs
|
|
./gradlew clean
|
|
|
|
# Clear Gradle wrapper cache
|
|
rm -rf ~/.gradle/wrapper/
|
|
```
|
|
|
|
### Step 5: Build Scan
|
|
```bash
|
|
./gradlew build --scan
|
|
# Opens interactive diagnostics in browser
|
|
```
|
|
|
|
## Quick Reference: Error Keywords → Solution
|
|
|
|
| Error Keyword | Likely Cause | Quick Fix |
|
|
|---------------|--------------|-----------|
|
|
| `UnsatisfiedLinkError` | Wrong JNI variant | Check secp256k1/JNA variants by platform |
|
|
| `IllegalStateException` (Compose) | Version mismatch | Align Compose Multiplatform + Kotlin versions |
|
|
| `NoClassDefFoundError` | Proguard stripping | Add `-keep` rule for class |
|
|
| `Unresolved reference` | Wrong source set | Move to appropriate source set (jvmAndroid) |
|
|
| `Duplicate class` | BOM conflict | Remove AndroidX BOM from KMP modules |
|
|
| `Version mismatch` | Plugin/runtime version mismatch | Update libs.versions.toml |
|
|
| `No matching variant` | Repository or packaging issue | Add repository or @aar suffix |
|
|
| `Could not find` (dependency) | Missing repository | Add maven/jitpack to repositories |
|
|
| `Unsupported class file` | Java version mismatch | Update JAVA_HOME to Java 21 |
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
1. **Check Build Scan**: `./gradlew build --scan` for detailed diagnostics
|
|
2. **Gradle Forums**: https://discuss.gradle.org/
|
|
3. **Kotlin Slack**: #multiplatform channel
|
|
4. **Stack Overflow**: Tags `gradle`, `kotlin-multiplatform`, `compose-multiplatform`
|