Note
Pre-1.0: the APIs and the Gradle plugins' DSL can still change between minor versions.
Use Java libraries from Kotlin Multiplatform apps (iOS, Android, macOS, Linux, Windows) in the app's own process. By default the libraries are compiled ahead of time into a GraalVM native image. A real JVM can run them instead: jdk-mobile's OpenJDK on mobile, a JDK's HotSpot on the desktop.
Façade (Kotlin/JVM, Java 25) The plugin generates The app (commonMain) sees
─────────────────────────── ──────────────────── ─────────────────────────
class Search(dir: String) { → Runtime: a dispatcher, compiled → class Search : AutoCloseable {
fun query(q: String): with the façade (no reflection) fun query(q: String): List<Hit>
List<Hit> App: proxies + a binary codec, suspend fun index(...)
suspend fun index(...) one transport per platform fun watch(): Flow<Event>
fun watch(): Flow<Event> }
} // in-process, no server
You write a façade: a plain Kotlin/JVM module using any Java library (Lucene 10, Jackson, …). Its public API
(classes, interfaces, data classes, enums, collections, lambdas, suspend, Flow) becomes a Kotlin Multiplatform API
your common code calls as if it were local. The app's code is the same whatever runs the façades.
| Platform | GRAALVM (default) |
JVM |
ART |
|---|---|---|---|
| iOS (arm64, simulator arm64) | The façades' native image, linked into the app | jdk-mobile's Zero (an interpreter: iOS forbids JIT), linked into the app | – |
| Android (arm64, x86_64), 10+ | The façades' native image in libnja.so, loaded by ART |
jdk-mobile's HotSpot (C2 JIT) in libnja.so, next to ART |
The façades dexed with the app, on ART itself |
| macOS, Linux, Windows (Kotlin/Native) | The façades' native image, a shared library next to the executable | A JDK's HotSpot, loaded from the app's nja/runtime or JAVA_HOME |
– |
JVM target (jvm()) |
The façades on the app's own class path | same | same |
Choose per platform with runtime (all), iosRuntime, androidRuntime, desktopRuntime
(import dev.nucleusframework.nja.plugin.NjaRuntimeType):
nucleusJvm {
runtime = NjaRuntimeType.GRAALVM // the default
androidRuntime = NjaRuntimeType.JVM // e.g. HotSpot's JIT on Android
}- Why GraalVM by default: no interpreter on iOS (Zero runs Lucene searches about 100× slower than an image), no JIT warmup and no class metadata on Android, no JVM to ship on the desktop, and a fast start everywhere.
- What it costs: an image builds on its own platform's host (iOS and macOS images on macOS, Android and Linux ones
on Linux, Windows ones on Windows), libraries reaching classes by reflection need their reachability metadata, and
Android has no FFM API (
java.lang.foreign). - Android on a non-Linux host: an Android native image builds on Linux only, so on macOS (a local build) Android
runs the JVM unless
androidRuntimeis set. SetandroidRuntime = NjaRuntimeType.GRAALVMto get an error rather than that fallback. ARTis for Java libraries ART runs as they are, in a module that also targets iOS through NJA. The façades and NJA's server become the app's own dependencies, called in-process as on a JVM target, with the app's ownminSdk. The other platforms then runGRAALVM.
// settings.gradle.kts: includeBuild the plugin (not published yet)
// search-facade/build.gradle.kts: the façade, on the JVM
plugins {
kotlin("jvm")
id("dev.nucleusframework.nja.facade")
}
kotlin { jvmToolchain(25) }
njaFacade { libName = "search" }
dependencies { implementation("org.apache.lucene:lucene-core:10.5.2") }
// shared/build.gradle.kts: the KMP module using it
plugins {
kotlin("multiplatform")
id("com.android.kotlin.multiplatform.library")
id("dev.nucleusframework.nja")
}
kotlin {
android { namespace = "com.example.shared"; compileSdk = 35; minSdk = 29 }
iosArm64()
iosSimulatorArm64()
macosArm64()
linuxX64()
mingwX64()
}
nucleusJvm {
facade(project(":search-facade"))
jvmOptions.addAll("-Xmx512m") // a native image keeps -Xmx (its maximum heap) and -D
}// commonMain: the façade's API, on every platform
Search("/path/to/index").use { search ->
val hits = search.query("kotlin") // a call into the runtime
search.watch().take(10).collect { ... } // a JVM Flow, with backpressure
}- iOS: binaries link the runtime. An app built with Xcode links with the options the plugin applies to the Kotlin
binaries. With the JVM, it also copies
build/nja/ios/<target>/(java.home, class path) into its bundle (Run Script phase). - Android: the plugin adds
libnja.soand the runtime's assets to the app's variants. - Desktop: executables and test executables get the runtime in
nja/next to them (see Kotlin/Native on the desktop).
njaNativeImage<Target> (mobile) and njaNativeLibrary (desktop) compile the façades, with NJA's server, into a native
image with GraalVM CE's native-image. The app's code doesn't change: the client finds the image's entry points at run
time.
nucleusJvm {
graalvmMobileRelease = "graalvm-mobile-25.5.5.0.3b1.2" // mobile: graalvm-mobile's kit (default: latest)
graalvmRelease = "graal-25.5.5.0.3" // desktop: GraalVM CE's release (default: latest)
nativeImageOptions.add("-H:+ReportExceptionStackTraces")
}- Mobile: GraalVM CE ships no static libraries for iOS or Android.
graalvm-mobile's kits rebuild them for each GraalVM CE release
and name the release they are for. The plugin downloads the kit for each target and that GraalVM CE for the build host
into Gradle's cache. native-image cross-compiles a relocatable object, which the iOS binaries and Android's
libnja.solink. - Desktop: native-image builds a shared library for its own host (
libnja.dylib,libnja.so,nja.dll). On Windows it needs Visual Studio's C toolchain (the "x64 Native Tools" environment, or an installation native-image finds). - Reachability metadata: libraries reaching classes by reflection or resources bring their native-image metadata in
their jars (
META-INF/native-image/<group>/<artifact>/reachability-metadata.json), as GraalVM's own reachability metadata requires. Trace it with the native-image agent on a JVM (-agentlib:native-image-agent=config-output-dir=...). NJA's dispatchers need none. - Options: the
-XmxinjvmOptionsbecomes the image's maximum heap (-R:MaxHeapSize), and its-Dsystem properties are kept.nativeImageOptionsgo to native-image as they are. - Android: arm64 and x86_64 (the emulators). native-image compiles its host's Java classes, so an Android image
builds on Linux only (a CI runner, a Linux container). native-image also runs small C programs for the target: on a
Linux host of another architecture (arm64 images on x64), they run through qemu-user (
qemu-user-staticwith binfmt). The kit's Linux libraries are built against glibc: itslibglibc_compat.aadapts them to bionic, including the resolver'sstruct addrinfo(fromgraalvm-mobile-25.5.5.0.3b1.2: with earlier kits,InetAddresslookups crash). - Virtual threads:
StackValuethrows on a virtual thread. In code virtual threads may run, pass native memory throughUnmanagedMemoryor pinned arrays.
macOS (macosArm64, macosX64), Linux (linuxX64, linuxArm64) and Windows (mingwX64) binaries don't link the
runtime: they load it when the app first calls a façade, from the nja directory next to the executable, or from
NJA_HOME when it is set (a library embedded in another program):
| Runtime | nja/ holds |
The plugin puts it there |
|---|---|---|
GRAALVM |
libnja.dylib, libnja.so or nja.dll |
For executables and tests of the build host's target |
JVM |
classpath/ (the façades and NJA's server), jvm.options, optionally runtime/ (a JDK or a jlinked runtime, Java 25+; else JAVA_HOME's) |
For all executables and tests; runtime/ is yours to add |
- Cross-compiling: Kotlin/Native builds Linux and Windows binaries on macOS, but native-image builds for its own
host only. An executable built for another platform gets no native image (a warning says so). Build it on its own OS,
or ship the library built there in its
nja/. - Linux arm64: Kotlin/Native doesn't run on Linux arm64 hosts, so
linuxArm64binaries are always cross-compiled. WithGRAALVM, build the native image on a Linux arm64 machine (native-image --sharedof the façades' class path, asnjaNativeLibrarydoes) and ship it innja/; theJVMruntime needs nothing built there. - The JVM's tests run on Gradle's Java 25 toolchain (their
JAVA_HOME). - Shipping: copy
nja/next to the app's executable, or setNJA_HOME. A shared library or framework the app links findsnja/next to the executable that loaded it. - The binaries need nothing else: on Linux,
libdlandlibpthread, which the client's klib adds to their link.
| iOS | Android | Desktop (Kotlin/Native) | |
|---|---|---|---|
| JVM | jdk-mobile's Zero (iOS forbids JIT) | jdk-mobile's HotSpot server VM (C2 JIT) | A JDK's HotSpot |
| Where | Linked into the app (libjvm.a, static) |
libnja.so: HotSpot + the JDK's natives + the bridge, loaded by ART |
libjvm loaded at run time |
| Calls | JNI from the calling Kotlin/Native thread (attached on first use, detached when it ends) | Handed from the ART thread to a HotSpot thread paired with it (futex channel, spin-then-sleep) | As on iOS |
| Callbacks (JVM → app) | JNI upcall on the same thread | The answer of the channel, served on the ART thread; nested calls recurse on the same pair | As on iOS |
A native image works like the iOS column on every platform: the app's threads attach to the image's isolate and call its entry points, and the image calls the app back on the same thread.
One process on Android. ART and HotSpot can't share a thread (both keep their state in TLS and guard zones on the stack), but they can share a process:
- Symbols: HotSpot and the JDK's natives are linked into one shared library,
-Bsymbolic, loadedRTLD_LOCALbySystem.loadLibrary: itsJNI_CreateJavaVMnever meets ART's. A small JDK patch (jdk-mobile/inprocess.patch, on top of jdk-mobile's) makes HotSpot look its natives up in that library rather than in the process' main handle (app_process, where ART'slibopenjdklives). - Signals: ART's
libsigchaininterceptssigaction. HotSpot'sSIGSEGVhandler (implicit null checks, safepoint polls, stack banging) is chained behind ART's fault manager, which forwards the faults outside ART's code.-XrsleavesSIGQUITand the other signals to ART. - Threads: each ART thread calling the JVM gets a HotSpot thread of its own (created by the bridge, 8 MB stack). Messages strictly alternate on their channel, so a callback and the calls it makes are served recursively by the same pair, with the semantics of a JNI call on one thread. A round trip costs about 0.4 µs.
The VM's runtime (java.home, ~50 MB, per ABI) and the façades' class path ship in the APK's assets and are extracted
once per version; the VM's output goes to logcat (NJA-JVM). On iOS, java.home is <app>/lib and the class path is
<app>/nja/classpath.
The mobile JVMs are jdk-mobile's releases (from
jdk-mobile-27b35.3, whose Android runtimes include the static libraries built with inprocess.patch). The plugin
downloads those the module needs (the Android ABIs it ships, its iOS targets), checks them against the .sha256
published with them, keeps them in Gradle's cache (~/.gradle/caches/nja/jdk-mobile: a clean downloads nothing) and
extracts them into build/nja/jdkMobile.
nucleusJvm {
jdkMobileRelease = "jdk-mobile-27b35.3" // default: latest (resolved once a day; offline, the last one)
jdkMobileRepository = "NucleusFramework/openjdk-mobile" // the default
jdkMobile = layout.projectDirectory.dir("my-jdk") // instead: runtimes of one's own, used as they are
}With latest, a new release reaches the next build: pin jdkMobileRelease (and graalvmMobileRelease,
graalvmRelease) for builds that must not move. Runtimes of one's own are one directory per target (android-aarch64,
android-x64, ios-simulator-aarch64, ios-device-aarch64), each with static/, include/ and lib/ (java.home);
scripts/stage-jdk-mobile.sh lays out a local OpenJDK build that way.
NucleusFramework/openjdk-mobile is a recipe, not a fork of the JDK. It builds a stable OpenJDK (the 27 line, from openjdk/jdk27u's GA releases) with two patches on top:
openjdk-mobile.patch: openjdk/mobile's iOS and Android ports, carried over to the stable line, with the fixes they need there (Zero's W^X handling on iOS, bionic and an NDK build from a macOS host on Android);inprocess.patch: what NJA needs to run HotSpot inside an app's process on Android. The VM looks its natives up in the shared library holding it (loadedRTLD_LOCALby ART) rather than in the process' own handle.
Its build.sh builds one target from an OpenJDK checkout: Zero (the interpreter) as static libraries for iOS, and the
server VM (C2 JIT) for Android, both as static libraries (which NJA links into libnja.so) and as a launcher for apps
that run Java in a process of its own. Its CI follows the JDK's line: every day, and on each change to the recipe, it
builds the latest GA for the four targets, smoke-tests the Android runtime on an emulator and publishes a release named
jdk-mobile-<version>b<build>.<revision> (jdk-mobile-27b35.3: JDK 27, its GA build 35, the recipe's third release
on it).
To build a runtime yourself (autoconf, a boot JDK 26 or 27; Xcode for iOS, the Android NDK for Android):
git clone https://github.com/NucleusFramework/openjdk-mobile.gitgit clone --depth 1 --branch jdk-27-ga https://github.com/openjdk/jdk27u.git jdkopenjdk-mobile/build.sh android-aarch64 jdk # or android-x64, ios-simulator, ios-deviceThe result (dist/jdk-mobile-<target>.tar.gz) has the release's layout: extract it into <stage>/<target> for
nucleusJvm.jdkMobile. jdk-mobile/inprocess.patch is a copy of the recipe's.
The façade's public API, parsed from its sources with Kotlin PSI: Int,
Long, Double, Float, Boolean, Byte, Short, String (length-prefixed UTF-8: NUL included), ByteArray,
IntArray, LongArray, FloatArray, DoubleArray, enums (verbatim, bodies included), data classes (verbatim), sealed
value hierarchies (a sealed interface or class whose nested cases are all data classes or objects: verbatim, by value,
recursive ones included), classes (proxies, released on close() or when collected; an AutoCloseable's close()
closes the JVM object, then releases it), default arguments (overloads: the JVM applies the defaults), open/abstract/sealed classes and interfaces (hierarchy mirrored, objects wrapped in their most specific
exported type), nested classes (Outer_Inner), companion objects, extension and top-level functions, nullable types,
List/Set/Map (nested), lambdas as parameters (callbacks, valid during the call, exceptions rethrown as themselves)
and as return values (JVM lambdas the app calls), suspend functions (cancellable both ways) and Flow (credit-based
backpressure).
Private and internal declarations stay the JVM's, as does a constructor that is private, internal, or takes what can't cross; a function whose parameters or result can't cross is left out.
JVM exceptions arrive as JvmException (with the JVM class name, message and stack); exceptions an app callback throws
come back out of the call as themselves. A closed proxy fails with IllegalStateException; close() releases the JVM
object once the calls using it are done (receiver and arguments are leased).
A JVM target (jvm(), a desktop app on the JVM) sees the same proxies, with the façades in its own JVM: the plugin
puts them on the target's runtime class path, and the messages are still encoded (the app's code is the same
everywhere). Both the façades and their proxies being on that class path, the proxies need a package of their own: set
njaFacade { clientPackage = "…" } (the plugin checks it before the JVM target compiles).
examples/calculator runs a suite of 2,008 tests (types, arrays, sealed values, callbacks, suspend, flows, inheritance,
load, concurrency, monkey and torture tests) against a calculator façade, from commonTest, on every platform. It also
runs NJA's own torture suite (NjaTortureTest): JVM null checks and stack overflows on 16 threads while the app faults
and collects, JIT deoptimization storms, 300-level JVM ↔ app nesting, callbacks invoked from the wrong JVM thread,
thread churn (1,000 threads, no JVM thread leak), 24–48 MB payloads, 100k handles released by close and by collection,
cancellation storms, 200k-element flows, a 20 s chaos soak on 24 threads.
./gradlew :examples:calculator:iosSimulatorArm64Test./gradlew :examples:calculator:connectedAndroidDeviceTest./gradlew :examples:calculator:macosArm64Test # or linuxX64Test, linuxArm64Test, mingwX64Test, on that OS./gradlew :examples:calculator:jvmTest-Pnja.runtime=JVM runs the same suites on the JVM runtime.
See BENCHMARKS.md. In short, on Android NJA's HotSpot runs Jackson and Commons Math 1.8–7.8× faster
than ART, and Lucene 10 (Java 21, out of ART's reach) at desktop speed; an empty call costs 0.33 µs. On iOS, Zero (an
interpreter) suits occasional calls, not CPU-bound work (an empty call costs 2.4 µs). A GraalVM native image (GRAALVM,
the default) runs at HotSpot's speed on both: on a real app's Lucene search, 8× faster than Zero on iOS, and on par with
Lucene patched for ART on Android, at about its memory.
plugin-build/: the Gradle plugins (dev.nucleusframework.nja.facade,dev.nucleusframework.nja): PSI analysis, member table, server and client generators, native images, Android linking/packaging, iOS linking/bundling, the desktop's runtime directory.runtime/server: runs in the JVM or the native image: dispatch, handles, async (suspend/Flow), the platforms' links.runtime/client: KMP: codec, call scopes and leases, proxies' base, async, the transports (Android, Kotlin/Native, the JVM).runtime/android-native: the ART ↔ HotSpot bridge and the ART ↔ native image bridge (C).examples/:calculator(the test suites),torture-facade,benchmark*.