From 5b037b3940b79a848d16ae945fef693eca960b72 Mon Sep 17 00:00:00 2001 From: Ross Savage Date: Thu, 20 Jun 2024 15:05:27 +0200 Subject: [PATCH 1/4] Add Troubleshooting Android section --- src/SUMMARY.md | 1 + src/guide/android_troubleshooting.md | 76 ++++++++++++++++++++++++++++ src/guide/install.md | 2 +- 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 src/guide/android_troubleshooting.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 4302ddcd..6e0612e4 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,6 +4,7 @@ - [Getting Started](guide/getting_started.md) - [Installing the Breez SDK](guide/install.md) + - [Troubleshooting Android](guide/android_troubleshooting.md) - [Connecting to a node](guide/connecting.md) - [Getting the node state](guide/node_state.md) - [Adding logging](guide/logging.md) diff --git a/src/guide/android_troubleshooting.md b/src/guide/android_troubleshooting.md new file mode 100644 index 00000000..a6418f86 --- /dev/null +++ b/src/guide/android_troubleshooting.md @@ -0,0 +1,76 @@ +# Troubleshooting Android + +When including the Breez SDK and/or Notification Plugin into your application you might come across issues compiling because: +- it uses `kotlinx-serialization` +- it relies on JNA library + +If you do, there are several steps you can take to compile and build properly, even if they do not using the Notification Plugin feature. + +## kotlinx-serialization + +Starting with this 1.8.20 release, the Kotlin K2 compiler has a preview version of the serialization plugin. It's recommended for users to upgrade their Kotlin version to at least 1.8.20 or [set up the serialization plugin](https://github.com/Kotlin/kotlinx.serialization?tab=readme-ov-file#setup) on their projects explicitly with older versions. + +## JNA library + +JNA relies on specific class and method names to load native libraries and access native code. If these names are obfuscated or removed, it can cause runtime errors and failures in native library loading. + +To ensure proper functionality, a Proguard rules needs to be added to explicitly tell R8 compiler to keep certain parts of the JNA library. Here is an example of Proguard rules: +```pro +-dontwarn dalvik.system.VMStack +-dontwarn java.lang.** +-dontwarn javax.naming.** +-dontwarn sun.reflect.Reflection + +# JNA +-keep class com.sun.jna.** { *; } +-keep class * implements com.sun.jna.** { *; } + +# Other +-dontoptimize +``` + +These rules ensure that the JNA library's core components are not obfuscated, allowing the library to function correctly. See [Shrink, obfuscate, and optimize your app](https://developer.android.com/build/shrink-code) for more information on how and where to add Proguard rules on your app. + +## Inconsistent JVM-target compatibility + +It could be that compilation tasks for Java and Kotlin are using different JVM targets, in which case you need to set the [JVM toolchain](https://kotl.in/gradle/jvm/toolchain). In your application's `build.gradle` file in the `app` directory set the Java and Kotlin JVM targets consistently. +``` +kotlin { + jvmToolchain(17) +} + +java { + toolchain { + languageVersion.set(JavaLanguageVersion.of(17)) + } +} + +android { + compileOptions { + sourceCompatibility JavaVersion.VERSION_17 + targetCompatibility JavaVersion.VERSION_17 + } + + kotlinOptions { + jvmTarget = '17' + } +} +``` + +## Java heap space + +``` +> Could not resolve all files for configuration + > Failed to transform react-android-0.72.10-debug.aar (com.facebook.react:react-android:0.72.10) + to match attributes {artifactType=android-symbol-with-package-name, + com.android.build.api.attributes.BuildTypeAttr=debug, org.gradle.category=library, + org.gradle.dependency.bundling=external, or g.gradle.libraryelements=aar, org.gradle.status=release, + org.gradle.usage=java-api}. + > Java heap error +``` + +If you get a `Java heap space` error, try to increase the maximum memory allocation pool for the JVM in `gradle.properties`. + +``` +org.gradle.jvmargs=-Xmx3072m -XX:MaxMetaspaceSize=512m +``` \ No newline at end of file diff --git a/src/guide/install.md b/src/guide/install.md index 6160a9c1..6af7a016 100644 --- a/src/guide/install.md +++ b/src/guide/install.md @@ -56,7 +56,7 @@ dependencies { } ``` -See [the example](https://github.com/breez/breez-sdk-examples/tree/main/Android) for more details +Please check the [troubleshooting guide](/guide/android_troubleshooting.md) if you are having problems compiling your Android application. ## React Native From 1a172e866ef4af9c6b9538de2a99725d34d26e15 Mon Sep 17 00:00:00 2001 From: Ross Savage <551697+dangeross@users.noreply.github.com> Date: Thu, 20 Jun 2024 16:10:55 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Erdem Yerebasmaz --- src/guide/android_troubleshooting.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/guide/android_troubleshooting.md b/src/guide/android_troubleshooting.md index a6418f86..36468f94 100644 --- a/src/guide/android_troubleshooting.md +++ b/src/guide/android_troubleshooting.md @@ -1,10 +1,10 @@ # Troubleshooting Android -When including the Breez SDK and/or Notification Plugin into your application you might come across issues compiling because: -- it uses `kotlinx-serialization` -- it relies on JNA library +After installing Breez SDK into your application you might come across issues compiling on Android platforms because Breez SDK's Notification Plugin: +- uses `kotlinx-serialization` dependency, +- and it relies on JNA library. -If you do, there are several steps you can take to compile and build properly, even if they do not using the Notification Plugin feature. +If you do, there are several steps you can take to compile and build properly, even if your application is not using the Notification Plugin feature. ## kotlinx-serialization @@ -72,5 +72,5 @@ android { If you get a `Java heap space` error, try to increase the maximum memory allocation pool for the JVM in `gradle.properties`. ``` -org.gradle.jvmargs=-Xmx3072m -XX:MaxMetaspaceSize=512m +org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=512m ``` \ No newline at end of file From 3fdf9386425eb00ff23ce9011ab69121b0266c55 Mon Sep 17 00:00:00 2001 From: Ross Savage Date: Thu, 20 Jun 2024 16:17:09 +0200 Subject: [PATCH 3/4] Add JNI release mode warning --- src/guide/android_troubleshooting.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/guide/android_troubleshooting.md b/src/guide/android_troubleshooting.md index 36468f94..dcb7c23d 100644 --- a/src/guide/android_troubleshooting.md +++ b/src/guide/android_troubleshooting.md @@ -12,7 +12,9 @@ Starting with this 1.8.20 release, the Kotlin K2 compiler has a preview version ## JNA library -JNA relies on specific class and method names to load native libraries and access native code. If these names are obfuscated or removed, it can cause runtime errors and failures in native library loading. +JNA relies on specific class and method names to load native libraries and access native code. If these names are obfuscated or removed, it can cause runtime errors and failures in native library loading. + +The JNA library code obfuscation issue may not be apparent until compiled on "release" mode with maximum optimization and minimal footprint size that'll be used when deploying and publishing an application. To ensure proper functionality, a Proguard rules needs to be added to explicitly tell R8 compiler to keep certain parts of the JNA library. Here is an example of Proguard rules: ```pro From fe6036da98669c0d3697656a998aa2e6325c74d1 Mon Sep 17 00:00:00 2001 From: Ross Savage <551697+dangeross@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:36:37 +0200 Subject: [PATCH 4/4] Update JNA library text Co-authored-by: Erdem Yerebasmaz --- src/guide/android_troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/guide/android_troubleshooting.md b/src/guide/android_troubleshooting.md index dcb7c23d..dd807082 100644 --- a/src/guide/android_troubleshooting.md +++ b/src/guide/android_troubleshooting.md @@ -14,7 +14,7 @@ Starting with this 1.8.20 release, the Kotlin K2 compiler has a preview version JNA relies on specific class and method names to load native libraries and access native code. If these names are obfuscated or removed, it can cause runtime errors and failures in native library loading. -The JNA library code obfuscation issue may not be apparent until compiled on "release" mode with maximum optimization and minimal footprint size that'll be used when deploying and publishing an application. +The JNA library code obfuscation issue may not be apparent until your application is compiled on `release` mode with maximum optimization and minimal footprint size, that will be used when deploying and publishing an application. To ensure proper functionality, a Proguard rules needs to be added to explicitly tell R8 compiler to keep certain parts of the JNA library. Here is an example of Proguard rules: ```pro