diff --git a/.github/workflows/release-shimmercapture.yml b/.github/workflows/release-shimmercapture.yml index 44e98f5..5617ab8 100644 --- a/.github/workflows/release-shimmercapture.yml +++ b/.github/workflows/release-shimmercapture.yml @@ -18,11 +18,14 @@ # build reads the version; fails if it is already tagged, if versionCode did not go up since the # last ShimmerCapture release, or if the app is not set to PUBLIC; lists the PRs since # that release in the run summary, to write whats_new from; builds the signed release -# APK. Read-only (no keystore without it): it also runs, unsigned, on PRs. +# APK, shrunk and obfuscated by R8, and keeps R8's mapping.txt as its own artifact. +# Read-only (no keystore without it): it also runs, unsigned, on PRs. # release tags ShimmerCapture_v on the commit it built and creates the GitHub # pre-release with the APK and notes since the previous ShimmerCapture release. # Pre-release, so the Android API release stays "Latest", as before. -# play google_play only: uploads the same APK to Play's Production track as a draft. +# play google_play only: uploads the same APK to Play's Production track as a draft, with +# mapping.txt so Play's crash reports show the real class and method names. The +# mapping is never attached to the public GitHub release. # # If a later job fails, "Re-run failed jobs" re-runs just that job. # @@ -327,6 +330,14 @@ jobs: path: release-assets/ if-no-files-found: error + # R8's map from obfuscated names back to the code, for Play's crash reports. Its own artifact, + # so the release job, which publishes everything in shimmercapture-apk, never makes it public. + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: shimmercapture-mapping + path: ShimmerAndroidInstrumentDriver/shimmerServiceExample/build/outputs/mapping/release/mapping.txt + if-no-files-found: error + release: needs: build if: github.event_name == 'workflow_dispatch' && !inputs.dry_run @@ -383,6 +394,11 @@ jobs: name: shimmercapture-apk path: release-assets + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: shimmercapture-mapping + path: release-mapping + - name: Write the release notes working-directory: . env: @@ -408,6 +424,7 @@ jobs: serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }} packageName: com.shimmersensing.shimmerconnect releaseFiles: release-assets/${{ needs.build.outputs.apk }} + mappingFile: release-mapping/mapping.txt releaseName: ${{ needs.build.outputs.version }} track: production status: draft diff --git a/AGENTS.md b/AGENTS.md index 4627fec..4194f62 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,6 +138,10 @@ Android API workflow; it dry-runs on any PR that changes it. `release-shimmercap same for the ShimmerCapture app (`shimmerServiceExample`): a signed APK, a GitHub pre-release and a draft Google Play release. Its version comes from that module's `build.gradle`, so each release starts with an uprev PR; `shimmerServiceExample/RELEASING.md` is the step-by-step guide. +ShimmerCapture's release build runs R8 (DEV-1426): all `com.shimmerresearch` code is kept as it +is, because it relies on serialization and reflection, and only the third-party libraries are +shrunk and obfuscated. Anything new found by name needs a rule in its `proguard-rules.pro`, and the +debug build, which R8 never touches, does not show what it breaks. ## Modules diff --git a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md index 8de2a88..cec5347 100644 --- a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md +++ b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md @@ -43,7 +43,8 @@ release anything else. Then, as before the workflow existed: 1. Sync Gradle in Android Studio, **Clean Project**, run the app on a device and check that it - connects, configures, streams and plots. + connects, configures, streams and plots. That is the debug build, which R8 does not touch: + the release build must be checked too, from a dry run (step 2, and *R8* below). 2. Commit (`ShimmerCapture 1.3.4 (versionCode 35)`), push, and open a PR into `master`. 3. Wait for CI ("Build and test") to pass, get it reviewed, and merge. @@ -73,7 +74,9 @@ A dry run does everything up to the signed APK and stops. Open the run to check: it. Do not choose any option on *Protected with Play* → *Manage Play app signing* as part of a release: enrolling cannot be undone. - The APK itself is on the run page under **Artifacts** (`shimmercapture-apk`), to install on a test - device. + device. It is the release build, shrunk and obfuscated by R8 exactly as it will ship, so this is + the APK to test on hardware before a release (see *R8* below). Uninstall the Play version first: + a debug or Play install of the app is signed differently and blocks installing it over the top. A dry run can be started from any branch, so it is also the way to try an uprev before merging it. @@ -149,6 +152,36 @@ Not uploading through the workflow? Download the APK from the GitHub release, an - Move the ticket on in Jira. - If the release changes what the app does, update this module's [README](README.md). +## R8: shrinking and obfuscation + +The release build runs R8 (`minifyEnabled true`), which Google Play expects: without it Play Console +flags *DEX code optimisation is below our threshold*. R8 removes code it thinks is unused and renames +the rest. The rules in [`proguard-rules.pro`](proguard-rules.pro) say what it must leave alone, each +with its reason: + +- **All Shimmer code** (`com.shimmerresearch.**`: the driver, this library, the app and the + biophysical processing jar) is kept as it is, because it uses Java serialization and reflection + that R8 cannot see. Only the third-party libraries are shrunk and obfuscated; they are about 80% + of the app's classes, well past Play's 25%. +- **androidplot** and **AndroidBluetoothLibrary**, which work by reflection. +- **Two AppCompat names** `MainActivity` reaches by name to align the toolbar. +- `-dontwarn` for classes the driver refers to but the app never had (protobuf, Netty, JNA, + desktop UI): R8 only reports them. + +What R8 breaks, it breaks **at runtime, not at build time**: a class or field found by name is +missing, and the app crashes (`ClassNotFoundException`, `NoSuchFieldException`) or, worse, quietly +behaves differently. The debug build is never shrunk, so it cannot show this. Before each release, +install the dry run's APK and check on hardware what the app does: connect, configure, stream and +plot, SD logging, CSV, and the Verisense functions, on a Shimmer3, a Shimmer3R and a Verisense over +Bluetooth Classic and BLE. + +When something new is reached by reflection or serialization, add a `-keep` rule for it with a +comment saying why. When a crash report from Play shows obfuscated names, it was uploaded without a +mapping: the play job uploads R8's `mapping.txt` with each release (it is kept as the +`shimmercapture-mapping` artifact, never on the public GitHub release). For a release built by hand, +upload `shimmerServiceExample/build/outputs/mapping/release/mapping.txt` in Play Console → *App +bundle explorer* → the version → *Downloads* → *ReTrace mapping file*. + ## When a run fails **Re-run failed jobs** on the run page re-runs only what failed, so a GitHub release that was @@ -163,6 +196,8 @@ already created is not created twice. | `No SHIMMERCAPTURE_KEYSTORE_BASE64 secret` | The signing secrets are missing. See *Secrets* below | | `The APK is not signed with the ShimmerCapture release key` | The keystore secret holds a different key from the one Play knows. Nothing was published. Replace `SHIMMERCAPTURE_KEYSTORE_BASE64` (and its passwords and alias) with the original keystore, see *Secrets* below | | `The APK does not carry versionName …` | The build didn't pick up `build.gradle`'s values. Check for a version override in Gradle files | +| `Missing classes detected while running R8` | A dependency now refers to a class the app doesn't have. If the code that refers to it can't run in ShimmerCapture, add a `-dontwarn` for it to `proguard-rules.pro`, with the reason, as for protobuf and Netty. If it can run, the class is needed: add the dependency | +| The released app crashes, or misbehaves, where the debug build doesn't | R8 removed or renamed something found by name. Find it from the crash report (Play maps the names back) and add a `-keep` rule | | **play**: `No GOOGLE_PLAY_SERVICE_ACCOUNT_JSON secret` | The Play secret is missing. The GitHub release is done; upload by hand (step 4), or add the secret and re-run the job | | **play**: `The caller does not have permission` | The service account lacks access to ShimmerCapture in Play Console, or was just added: new permissions can take a day. Re-run the play job later | | **play**: `APK specifies a version code that has already been used` | That `versionCode` reached Play before, e.g. by hand. Uprev again | @@ -202,4 +237,4 @@ Get-Content -Raw | gh secret set GOOGLE_PLAY_SERVICE_ACCOUNT_JSON --r If the workflow is unavailable, Android Studio still does the same job: **Build** → **Generate Signed App Bundle / APK** → **APK** → module `shimmerServiceExample`, the upload keystore, build variant **release**. The APK lands in `shimmerServiceExample/release/`. Do the uprev (step 1) first -all the same, then upload as in step 4. +all the same, then upload as in step 4, with R8's `mapping.txt` (see *R8* above). diff --git a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle index ddf660a..b7f0077 100644 --- a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle +++ b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/build.gradle @@ -8,8 +8,8 @@ android { applicationId "com.shimmersensing.shimmerconnect" minSdkVersion 21 targetSdkVersion 36 - versionCode 37 - versionName "1.3.4" + versionCode 38 + versionName "1.3.5" multiDexEnabled true testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" @@ -17,8 +17,10 @@ android { } buildTypes { release { - minifyEnabled false - proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' + // R8 shrinks, optimises and obfuscates the release build. Google Play flags apps + // without it (DEV-1426). What must not be touched is kept in proguard-rules.pro. + minifyEnabled true + proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } } configurations.all { diff --git a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/proguard-rules.pro b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/proguard-rules.pro index c336f13..4ea1029 100644 --- a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/proguard-rules.pro +++ b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/proguard-rules.pro @@ -1,25 +1,76 @@ -# Add project specific ProGuard rules here. -# By default, the flags in this file are appended to flags specified -# in C:\Users\Jos\AppData\Local\Android\Sdk/tools/proguard/proguard-android.txt -# You can edit the include path and order by changing the proguardFiles -# directive in build.gradle. +# R8 rules for ShimmerCapture's release build (DEV-1426). # -# For more details, see -# http://developer.android.com/guide/developing/tools/proguard.html +# Google Play flags apps whose code R8 does not optimise or obfuscate. R8 shrinks, +# optimises and obfuscates everything except what is kept here: the third-party +# libraries (AndroidX, Material, Guava, FastBle, ...) are most of the app, and +# they need no rules of their own. +# +# What is kept, and why. Each is code R8 cannot see being used, so it would +# remove or rename it and break the app only at runtime, not at build time. + +# Shimmer code: the driver (shimmerdriver, shimmerbluetoothmanager), this repo's +# library, the app, and the closed-source ShimmerBiophysicalProcessingLibrary jar. +# - Java serialization: device objects are cloned through ObjectOutputStream +# (e.g. configuring a device works on a clone), and many classes have private +# readObject/writeObject, which only serialization calls. +# - Reflection: ExGConfigBytesDetails.getExGConfigOptionFields() and +# UartPacketDetails.getUartPropertyParsed() collect static fields by +# reflection, so R8 would drop those fields as unused. +# Keeping it whole means that is safe without auditing each class. Optimising it +# is left for later, with a test on hardware for each change. +-keep class com.shimmerresearch.** { *; } +-keep interface com.shimmerresearch.** { *; } + +# androidplot: its Configurator sets plot properties from XML by reflecting on +# getter and setter names. +-keep class com.androidplot.** { *; } + +# AndroidBluetoothLibrary: built around reflection. +-keep class it.gerdavax.** { *; } -# Add any project specific keep options here: +# MainActivity aligns the toolbar by reaching into AppCompat by name: it reads +# Toolbar's private mTitleTextView by reflection, and finds the overflow menu by +# its class's simple name, "ActionMenuView". R8 would rename both, and the code +# fails silently (the title and the menu icon just lose their alignment). +-keepclassmembers class androidx.appcompat.widget.Toolbar { + android.widget.TextView mTitleTextView; +} +-keepnames class androidx.appcompat.widget.ActionMenuView -# If your project uses WebView with JS, uncomment the following -# and specify the fully qualified class name to the JavaScript interface -# class: -#-keepclassmembers class fqcn.of.javascript.interface.for.webview { -# public *; -#} +# Serialization of the non-Shimmer classes a device object holds, e.g. Guava +# collections: keep what Java serialization uses but R8 cannot see. +-keepclassmembers class * implements java.io.Serializable { + static final long serialVersionUID; + private static final java.io.ObjectStreamField[] serialPersistentFields; + !static !transient ; + private void writeObject(java.io.ObjectOutputStream); + private void readObject(java.io.ObjectInputStream); + java.lang.Object writeReplace(); + java.lang.Object readResolve(); +} -# Uncomment this to preserve the line number information for -# debugging stack traces. -#-keepattributes SourceFile,LineNumberTable +# Classes the driver refers to that are not in the app, and were not before R8 +# either: R8 only reports the references. They are reached only by driver code +# ShimmerCapture does not run (gRPC, Shimmer4, desktop UI), which is kept as-is +# above, so the app fails no differently than it did. +# - excluded on purpose in the root build.gradle (exclude group: ...) +-dontwarn com.google.protobuf.** +-dontwarn io.netty.** +-dontwarn com.sun.jna.** +# - desktop-only (the driver also runs on PCs) +-dontwarn java.awt.** +-dontwarn javax.swing.** +# - optional dependencies of gRPC, Netty and Guava +-dontwarn org.eclipse.jetty.alpn.** +-dontwarn org.eclipse.jetty.npn.** +-dontwarn org.apache.log4j.** +-dontwarn org.apache.logging.log4j.** +-dontwarn org.slf4j.impl.** +-dontwarn org.jetbrains.annotations.** +-dontwarn reactor.blockhound.** +-dontwarn sun.misc.** -# If you keep the line number information, uncomment this to -# hide the original source file name. -#-renamesourcefileattribute SourceFile +# Line numbers in Play's crash reports. Play maps the rest back with the +# mapping.txt the release workflow uploads. +-keepattributes SourceFile,LineNumberTable +-renamesourcefileattribute SourceFile diff --git a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/src/main/java/com/shimmerresearch/shimmercapture/MainActivity.java b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/src/main/java/com/shimmerresearch/shimmercapture/MainActivity.java index 0ba4d5a..1c68950 100644 --- a/ShimmerAndroidInstrumentDriver/shimmerServiceExample/src/main/java/com/shimmerresearch/shimmercapture/MainActivity.java +++ b/ShimmerAndroidInstrumentDriver/shimmerServiceExample/src/main/java/com/shimmerresearch/shimmercapture/MainActivity.java @@ -8,10 +8,13 @@ import android.app.ProgressDialog; import android.content.DialogInterface; import android.content.pm.PackageManager; +import android.graphics.Color; import android.net.Uri; import android.os.Looper; import android.os.Message; +import androidx.activity.EdgeToEdge; +import androidx.activity.SystemBarStyle; import androidx.annotation.NonNull; import androidx.appcompat.widget.Toolbar; import androidx.core.app.ActivityCompat; @@ -19,7 +22,6 @@ import androidx.core.graphics.Insets; import androidx.core.graphics.drawable.DrawableCompat; import androidx.core.view.ViewCompat; -import androidx.core.view.WindowCompat; import androidx.core.view.WindowInsetsCompat; import androidx.fragment.app.FragmentManager; @@ -194,7 +196,10 @@ public void requestPermissions(){ startServiceandBTManager(); } - WindowCompat.setDecorFitsSystemWindows(getWindow(), false); + // Edge to edge, as Android 15+ enforces for apps targeting it, the way Google Play + // recommends (DEV-1426). Status bar icons stay light: the toolbar behind them is dark in + // both light and dark mode. The insets listeners below keep content clear of the bars. + EdgeToEdge.enable(this, SystemBarStyle.dark(Color.TRANSPARENT)); setContentView(R.layout.activity_main); Toolbar toolbar = findViewById(R.id.toolbar);