Android App Build Workflow

Android App Build Workflow

Overview

sbt-multiarch-scala provides a complete Android APK build pipeline implemented entirely in sbt — no Gradle, no Android Studio project structure required. The pipeline compiles Scala 3 to JVM bytecode, converts it to DEX format via D8, packages it with aapt2, signs with apksigner, and installs via adb.

Build pipeline: androidDex -> androidPackage -> androidSign -> androidInstall

Prerequisites

JDK 17+

Android build tools (D8, aapt2, apksigner) require JDK 17 or later. JDK 22+ is recommended if also targeting desktop JVM with Panama FFM.

Android SDK

The SDK is resolved automatically. You do NOT need to install it manually.

Resolution order:

1. ANDROID_HOME environment variable
2. ANDROID_SDK_ROOT environment variable (deprecated but still recognized)
3. Auto-download to androidSdkCacheDir (defaults to <baseDirectory>/android-sdk)

When no SDK is found, AndroidPlugin downloads Android command-line tools, then runs sdkmanager to install the required platform and build-tools. Licenses are auto-accepted during download.

No Gradle

The entire pipeline is sbt-native. No build.gradle, no Android Gradle Plugin, no Gradle wrapper. All Android SDK tools (D8, aapt2, zipalign, apksigner, adb) are invoked directly from sbt tasks.

Setup

project/plugins.sbt

addSbtPlugin("com.eed3si9n"     % "sbt-projectmatrix"   % "0.11.0")
addSbtPlugin("com.kubuszok"     % "sbt-multiarch-scala" % "0.1.2")

build.sbt

lazy val androidApp = project.in(file("android"))
  .enablePlugins(AndroidPlugin)
  .settings(
    scalaVersion := "3.8.3",
    Compile / mainClass := Some("com.example.MainActivity"),
    // Optional: override SDK cache location (default: baseDirectory / "android-sdk")
    androidSdkCacheDir := (ThisBuild / baseDirectory).value / "android-sdk"
  )

AndroidManifest.xml

Place at src/main/resources/AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">
    <application
        android:label="My App"
        android:hasCode="true">
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Build Pipeline Details

Step 1: androidDex

Compiles all JVM bytecode (Scala classes + dependency JARs) to Android DEX format.

1. Triggers Compile / compile to produce .class files
2. Collects all JARs and class directories from fullClasspath
3. Creates a fat JAR of all classes (excluding android.jar, META-INF/, java/* stdlib classes, and Scribe logging JARs)
4. Runs D8 via java -cp <r8Jar> com.android.tools.r8.D8 --min-api <minApi> --lib <android.jar> --output <dexDir> <fatJar>
5. Produces classes.dex (and classes2.dex, classes3.dex, etc. for multi-dex) in target/<scalaVersion>/android/dex/

D8 is invoked from the R8 JAR (build-tools/<version>/lib/d8.jar) which ships with the Android SDK build-tools. D8 performs pure DEX conversion plus desugaring (Java 8+ lambdas, try-with-resources, etc.) but does NOT perform code shrinking or optimization.

Step 2: androidPackage

Assembles the unsigned APK:

1. Runs aapt2 to link AndroidManifest.xml with android.jar into a base APK
2. Stages app assets from resource directories into target/<scalaVersion>/android/assets/
3. Adds all DEX files from step 1 into the APK
4. Extracts native .so files from dependency JARs (provider JARs) and adds them to lib/<abi>/ in the APK
5. Runs zipalign for memory-aligned access

Step 3: androidSign

Signs the APK with a debug keystore:

1. Auto-generates a debug keystore at target/<scalaVersion>/android/debug.keystore if not present (RSA 2048, validity 10000 days)
2. Copies the aligned APK to app-debug.apk
3. Signs with apksigner using the debug keystore

Step 4: androidInstall

Installs the signed APK on a connected device or emulator via adb:

adb install -r <path-to-app-debug.apk>

Requires platform-tools to be installed in the SDK (provides adb).

Setting Keys

Key	Type	Default	Description
androidSdkCacheDir	File	baseDirectory / "android-sdk"	Where to download/cache the SDK
androidSdkRoot	Task[File]	auto-resolved	SDK root (resolved from env vars or cache dir)
androidMinSdk	Int	26	Minimum API level (Android 8.0)
androidTargetSdk	Int	35	Target API level for compilation
androidBuildToolsVersion	String	"35.0.0"	Build tools version
androidR8Rules	Option[File]	None	ProGuard/R8 rules file (exists but not yet wired)

Android SDK Defaults

Parameter	Value	Notes
minSdkVersion	26	Android 8.0 — minimum for PanamaPort
targetSdkVersion	35	Android 15 — compilation target
buildToolsVersion	35.0.0	Provides D8, aapt2, zipalign, apksigner
platformVersion	android-35	Matches targetSdkVersion

Native .so Packaging

Provider JARs containing native shared libraries for Android are automatically extracted and placed in the APK's lib/<abi>/ directory.

The plugin scans all classpath JARs for entries matching native/android-<classifier>/<name>.so and maps classifiers to Android ABI directories:

Provider classifier	APK ABI directory
android-aarch64	arm64-v8a
android-armv7	armeabi-v7a
android-x86_64	x86_64

Provider JARs with jni-provider.json or pnm-provider.json manifests containing native/android-*/*.so entries are handled automatically.

You can also place native libraries directly at src/main/resources/lib/<abi>/<name>.so for project-local native code.

PanamaPort Dependency Resolution

Android does not ship java.lang.foreign (Panama FFM). For apps that use Panama-based FFI, the PanamaPort library (com.v7878.foreign) provides a backport that works on Android API 26+.

AndroidDeps.resolvePanamaPort(cacheDir, log) handles this:

1. Downloads AAR artifacts from Maven Central (io.github.vova7878/panama/*)
2. Extracts classes.jar (and any JARs in libs/) from each AAR
3. Returns a Seq[File] of JARs added to Compile / unmanagedJars

PanamaPort dependencies (resolved automatically):

• Core, Unsafe, VarHandles, LLVM (AAR modules)
• SunCleanerStub, R8Annotations, SunUnsafeWrapper (AAR)
• DexFile, AndroidMisc (JAR)

Standard sbt/Ivy dependency resolution cannot handle AARs, so this custom resolver downloads and caches them independently.

API Level: D8 vs R8

Current state: D8 only

The build currently uses D8 (com.android.tools.r8.D8) for DEX compilation. D8 does:

• Pure DEX conversion (JVM bytecode -> Dalvik bytecode)
• Desugaring (Java 8+ lambdas, default methods, try-with-resources)

D8 does NOT do:

• Code shrinking (tree shaking)
• Optimization (method inlining, constant folding)
• API-level adaptation via ProGuard rules

Known limitation: R8 not wired

The androidR8Rules setting key exists but is not wired into the DEX command. The code always invokes com.android.tools.r8.D8, never com.android.tools.r8.R8.

This matters because PanamaPort's AAR artifacts ship proguard.txt rules that instruct R8 how to adapt API 36+ constructs for lower API levels. Without R8 + those ProGuard rules, PanamaPort may reference runtime APIs that don't exist on the target device's API level.

The PanamaPort author confirmed API 26 works IF R8 is run with the proguard.txt rules extracted from the AARs. See https://github.com/kubuszok/sge/issues/5

Future work

To fully support API 26 at runtime:

1. Extract proguard.txt from each PanamaPort AAR
2. Combine all rules into a single rules file
3. Invoke com.android.tools.r8.R8 instead of D8 with --pg-conf <rules>
4. Wire the androidR8Rules setting into the command

D8 vs R8 summary

Feature	D8	R8
DEX conversion	Yes	Yes
Desugaring	Yes	Yes
Tree shaking	No	Yes
Optimization	No	Yes
ProGuard rules	No	Yes
API adaptation	No	Yes (via rules)

Scribe Logging Exclusion

Scribe logging JARs are excluded from the fat JAR during DEX compilation. Scribe's lambda patterns cause VerifyError: wide register index out of range when D8 processes Scala 3 bytecode. The exclusion filter matches JARs with "scribe" in the filename.

Apps that need logging on Android should route their logging facade to android.util.Log via reflection or a platform-specific implementation.

Classpath Handling

The android.jar from the SDK is added to Compile / unmanagedJars as a compile-time library reference (API stubs). It is NOT included in the fat JAR for D8 — Android provides these classes at runtime.

Classes under java/* in dependency JARs are also excluded from the fat JAR, as they conflict with Android's runtime stdlib.

META-INF/ entries are stripped to avoid signature and manifest conflicts.

Build Commands

# Full pipeline: compile -> DEX -> package -> sign -> install
sbt --client 'androidInstall'

# Individual steps
sbt --client 'androidDex'       # Compile + DEX
sbt --client 'androidPackage'   # DEX + APK assembly + zipalign
sbt --client 'androidSign'      # Package + sign with debug keystore
sbt --client 'androidInstall'   # Sign + install via adb

# Each task depends on the previous, so running androidInstall
# automatically runs the entire pipeline.

Example: Full Android Project

// project/plugins.sbt
addSbtPlugin("com.eed3si9n"     % "sbt-projectmatrix"   % "0.11.0")
addSbtPlugin("com.kubuszok"     % "sbt-multiarch-scala" % "0.1.2")

// build.sbt
val scala3 = "3.8.3"

lazy val core = (projectMatrix in file("core"))
  .settings(scalaVersion := scala3)
  .jvmPlatform(scalaVersions = Seq(scala3))

lazy val android = project.in(file("android"))
  .enablePlugins(AndroidPlugin)
  .dependsOn(core.jvm(scala3))
  .settings(
    scalaVersion := scala3,
    Compile / mainClass := Some("com.example.MainActivity"),
    // Add native library providers
    libraryDependencies += "com.kubuszok" % "pnm-provider-angle" % "0.1.2",
    // Override SDK defaults if needed
    androidMinSdk := 26,
    androidTargetSdk := 35,
    androidSdkCacheDir := (ThisBuild / baseDirectory).value / "android-sdk"
  )

Troubleshooting

"AndroidManifest.xml not found"

Symptom: androidPackage fails with "AndroidManifest.xml not found at ..." Cause: The manifest must be at src/main/resources/AndroidManifest.xml Fix: Create the file at the expected location. The (Compile / resourceDirectory) setting controls the base path.

"d8 not found" / "aapt2 not found"

Symptom: Task fails looking for build-tools binaries Cause: SDK download did not install the correct build-tools version Fix: Check that build-tools/35.0.0/ exists in your SDK directory. Run sdkmanager "build-tools;35.0.0" manually, or delete the SDK cache dir and let AndroidPlugin re-download.

"adb not found"

Symptom: androidInstall fails with "adb not found at ..." Cause: platform-tools not installed in the SDK Fix: Run sdkmanager "platform-tools" in your SDK directory, or install platform-tools via Android Studio / command-line tools.

VerifyError at runtime (wide register index out of range)

Symptom: App crashes on launch with VerifyError mentioning register index Cause: D8 mishandles certain Scala 3 lambda bytecode patterns, particularly from the Scribe logging library Fix: Scribe JARs are auto-excluded from the fat JAR. If another library triggers the same issue, add its name to the exclusion filter in androidDex.

Multi-dex issues

Symptom: App crashes with ClassNotFoundException for classes that exist Cause: D8 splits classes across multiple DEX files; the class may be in classes2.dex but the runtime didn't load it Fix: All DEX files (classes.dex, classes2.dex, etc.) are automatically added to the APK. If you still hit issues, ensure minSdkVersion >= 21 (native multi-dex support). API 26 (the default) is well above this threshold.

Native .so not found at runtime

Symptom: UnsatisfiedLinkError for a native library on Android Cause: The .so file wasn't extracted from the provider JAR, or the ABI doesn't match the device architecture Fix: Verify the provider JAR contains native/android-aarch64/<name>.so (or the appropriate classifier). Check that the classifier-to-ABI mapping covers your target device. ARM64 devices use arm64-v8a, x86_64 emulators use x86_64.

PanamaPort runtime crash on API < 36

Symptom: App works on API 36+ emulator but crashes on API 26-35 device Cause: D8 does not apply PanamaPort's ProGuard rules for API adaptation Fix: This is a known limitation. The current build uses D8 (no ProGuard rule support). Workaround: test on API 36+ emulator. Proper fix requires wiring R8 with ProGuard rules extracted from PanamaPort AARs. See https://github.com/kubuszok/sge/issues/5

Slow first build

Symptom: First androidDex takes several minutes Cause: AndroidPlugin is downloading the SDK (command-line tools + platform + build-tools) Fix: This is expected on first run. Set ANDROID_HOME to a pre-installed SDK to skip the download. Subsequent builds reuse the cached SDK.

SDK download fails behind proxy/firewall

Symptom: SDK download times out or fails with connection error Cause: dl.google.com is blocked or throttled Fix: Install the Android SDK manually (via Android Studio or sdkmanager), then set ANDROID_HOME to its location. The plugin will use the existing SDK without downloading.

gitignore for Android artifacts

Add to .gitignore:

android-sdk/
target/
*.apk
*.keystore