From 518b2fb2238883ebbf9b909b5517be065ed6e719 Mon Sep 17 00:00:00 2001 From: Elie Gambache Date: Mon, 16 Nov 2026 22:22:25 +0200 Subject: [PATCH 1/3] Kotlin/Native on macOS, Linux and Windows; GraalVM by default The native transport (JNI or a native image's entry points) is shared by every Kotlin/Native target. On the desktop the runtime is loaded from nja/ next to the executable (or NJA_HOME): the facades' native image, a shared library built by the host's native-image, or a JDK's libjvm. GRAALVM is the default runtime everywhere (Android keeps the JVM on non-Linux hosts unless set). Buffers are freed by the side that allocated them (Windows' C runtimes differ); GraalLink drops StackValue (virtual threads); IosLink becomes JniLink. README rewritten. --- .github/workflows/test-desktop.yml | 41 ++ README.md | 341 +++++++++------- examples/calculator/build.gradle.kts | 8 +- .../client/TortureSupport.android.kt | 2 + .../calculator/client/NjaTortureTest.kt | 6 +- .../calculator/client/TortureSupport.kt | 3 + .../calculator/client/TortureSupport.jvm.kt | 2 + .../client/TortureSupport.native.kt} | 14 +- .../nucleusframework/nja/plugin/NjaPlugin.kt | 183 ++++++++- .../nja/plugin/tasks/GitHubReleases.kt | 53 +++ .../nja/plugin/tasks/NjaGraalvmTask.kt | 59 ++- .../nja/plugin/tasks/NjaJdkMobileTask.kt | 43 +- .../nja/plugin/tasks/NjaNativeLibraryTask.kt | 67 ++++ .../android-native/src/nja_android_graal.c | 9 +- runtime/client/build.gradle.kts | 11 +- .../client/src/nativeInterop/cinterop/jni.def | 368 ++++++++++++++++-- .../nucleusframework/nja/Platform.native.kt} | 167 ++++++-- .../nja/server/GraalLink.java | 44 ++- .../nja/server/{IosLink.java => JniLink.java} | 10 +- 19 files changed, 1122 insertions(+), 309 deletions(-) create mode 100644 .github/workflows/test-desktop.yml rename examples/calculator/src/{iosTest/kotlin/com/example/calculator/client/TortureSupport.ios.kt => nativeTest/kotlin/com/example/calculator/client/TortureSupport.native.kt} (86%) create mode 100644 plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/GitHubReleases.kt create mode 100644 plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaNativeLibraryTask.kt rename runtime/client/src/{iosMain/kotlin/dev/nucleusframework/nja/Platform.ios.kt => nativeMain/kotlin/dev/nucleusframework/nja/Platform.native.kt} (58%) rename runtime/server/src/main/java/dev/nucleusframework/nja/server/{IosLink.java => JniLink.java} (52%) diff --git a/.github/workflows/test-desktop.yml b/.github/workflows/test-desktop.yml new file mode 100644 index 0000000..91f865c --- /dev/null +++ b/.github/workflows/test-desktop.yml @@ -0,0 +1,41 @@ +name: Kotlin/Native desktop + +# The example's suites in Kotlin/Native executables on macOS, Linux and Windows, each on its own host (a native image +# builds on its own platform): with the façades in a GraalVM native image (the default) and in a JDK's JVM +on: + pull_request: + workflow_dispatch: + +jobs: + test: + strategy: + fail-fast: false + matrix: + host: + - { os: macos-15, target: macosArm64 } + - { os: ubuntu-latest, target: linuxX64 } + - { os: ubuntu-24.04-arm, target: linuxArm64 } + - { os: windows-latest, target: mingwX64 } + runtime: [GRAALVM, JVM] + runs-on: ${{ matrix.host.os }} + timeout-minutes: 90 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: 25 + - uses: gradle/actions/setup-gradle@v4 + # native-image's C toolchain on Windows: Visual Studio's + - uses: ilammy/msvc-dev-cmd@v1 + if: runner.os == 'Windows' + - name: Tests + shell: bash + env: + GITHUB_TOKEN: ${{ github.token }} + run: ./gradlew :examples:calculator:${{ matrix.host.target }}Test -Pnja.runtime=${{ matrix.runtime }} --stacktrace + - uses: actions/upload-artifact@v4 + if: always() + with: + name: desktop-${{ matrix.host.target }}-${{ matrix.runtime }} + path: examples/calculator/build/reports/tests/** diff --git a/README.md b/README.md index 593a77f..f42dc2f 100644 --- a/README.md +++ b/README.md @@ -4,65 +4,63 @@ > **Highly experimental.** This project is a proof of concept: its APIs, its Gradle plugins and the runtimes it relies > on can change at any time, and it may not be maintained. Don't depend on it for production apps. -Use **Java libraries from Kotlin Multiplatform iOS and Android apps, on a real JVM** — [jdk-mobile](https://github.com/NucleusFramework/openjdk-mobile)'s -OpenJDK 27 — running **in the app's own process**. +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](https://github.com/NucleusFramework/openjdk-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) { → JVM: a dispatcher, compiled with → class Search : AutoCloseable { - fun query(q: String): the façade (no reflection) fun query(q: String): List +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 List App: proxies + a binary codec, suspend fun index(...) suspend fun index(...) one transport per platform fun watch(): Flow fun watch(): Flow } -} // backed by the JVM, in-process +} // 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 iOS and Android code calls as if it were local. +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. -## How it works +## Platforms and runtimes -| | iOS | Android | JVM (desktop) | +| Platform | `GRAALVM` (default) | `JVM` | `ART` | |---|---|---|---| -| JVM | Zero (jdk-mobile's interpreter: iOS forbids JIT) | HotSpot server VM (C2 JIT) | The app's own | -| Where | Linked into the app (`libjvm.a`, static) | `libnja.so`: HotSpot + the JDK's natives + the bridge, loaded by ART | The façades on the app's class path | -| 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) | A plain call into the dispatcher, on the calling thread | -| 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 | A plain call back, on the same thread | -| Fallback process | none | none | none | +| 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 | -**A JVM target** (`jvm()`, a desktop app) sees the same proxies as the mobile ones, 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). +Choose per platform with `runtime` (all), `iosRuntime`, `androidRuntime`, `desktopRuntime` +(`import dev.nucleusframework.nja.plugin.NjaRuntimeType`): -**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`, loaded `RTLD_LOCAL` by - `System.loadLibrary`: its `JNI_CreateJavaVM` never meets ART's. A small JDK patch - ([`jdk-mobile/inprocess.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's `libopenjdk` lives). -- **Signals**: ART's `libsigchain` intercepts `sigaction`: HotSpot's `SIGSEGV` handler (implicit null checks, safepoint - polls, stack banging) is chained behind ART's fault manager, which forwards the faults outside ART's code. `-Xrs` - leaves `SIGQUIT` and 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 — the semantics of a JNI call on one thread. A round trip costs ~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`). +```kotlin +nucleusJvm { + runtime = NjaRuntimeType.GRAALVM // the default + androidRuntime = NjaRuntimeType.JVM // e.g. HotSpot's JIT on Android +} +``` -**iOS** links jdk-mobile's static libraries into the app and starts the VM in-process; `java.home` is `/lib`, the -class path `/nja/classpath`. +- **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 `androidRuntime` is set. Set `androidRuntime = NjaRuntimeType.GRAALVM` to get an error rather than + that fallback. +- **`ART`** is 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 own `minSdk`. + The other platforms then run `GRAALVM`. ## Quick start ```kotlin // settings.gradle.kts: includeBuild the plugin (not published yet) -// search-facade/build.gradle.kts — the façade, on the JVM +// search-facade/build.gradle.kts: the façade, on the JVM plugins { kotlin("jvm") id("dev.nucleusframework.nja.facade") @@ -71,7 +69,7 @@ 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 +// shared/build.gradle.kts: the KMP module using it plugins { kotlin("multiplatform") id("com.android.kotlin.multiplatform.library") @@ -81,81 +79,125 @@ kotlin { android { namespace = "com.example.shared"; compileSdk = 35; minSdk = 29 } iosArm64() iosSimulatorArm64() + macosArm64() + linuxX64() + mingwX64() } nucleusJvm { facade(project(":search-facade")) - jvmOptions.addAll("-Xmx512m") - // The JVM's runtimes: jdk-mobile's latest release, downloaded (see "jdk-mobile" below) + jvmOptions.addAll("-Xmx512m") // a native image keeps -Xmx (its maximum heap) and -D } ``` ```kotlin -// commonMain — the façade's API, on both platforms +// commonMain: the façade's API, on every platform Search("/path/to/index").use { search -> - val hits = search.query("kotlin") // a call into the JVM + val hits = search.query("kotlin") // a call into the runtime search.watch().take(10).collect { ... } // a JVM Flow, with backpressure } ``` -On iOS, test executables and executables get the runtime next to them automatically; an app copies -`build/nja/ios//` into its bundle (Run Script phase) and links with the options the plugin applies to the -Kotlin binaries (`-force_load` of jdk-mobile's static libraries, `-export_dynamic`). +- **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//` (java.home, class path) into its bundle (Run Script + phase). +- **Android**: the plugin adds `libnja.so` and 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](#kotlinnative-on-the-desktop)). -## What crosses the bridge +## GraalVM native images -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). +`njaNativeImage` (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. -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. +```kotlin +nucleusJvm { + graalvmMobileRelease = "graalvm-mobile-25.4.4.1.1b1.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") +} +``` -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). +- **Mobile**: GraalVM CE ships no static libraries for iOS or Android. + [graalvm-mobile](https://github.com/NucleusFramework/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.so` link. +- **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///reachability-metadata.json`), as GraalVM's own + [reachability metadata](https://www.graalvm.org/latest/reference-manual/native-image/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 `-Xmx` in `jvmOptions` becomes the image's maximum heap (`-R:MaxHeapSize`), and its `-D` system + properties are kept. `nativeImageOptions` go 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-static` with binfmt). + The kit's Linux libraries are built against glibc: its `libglibc_compat.a` adapts them to bionic, including the + resolver's `struct addrinfo` (in kits released after `b1.2`: with earlier ones, `InetAddress` lookups crash). +- **Virtual threads**: `StackValue` throws on a virtual thread. In code virtual threads may run, pass native memory + through `UnmanagedMemory` or pinned arrays. -## Tests +## Kotlin/Native on the desktop -`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, on iOS, on Android and on the JVM, from -`commonTest`, plus 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. +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): -```bash -./gradlew :examples:calculator:iosSimulatorArm64Test -``` +| 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 `jlink`ed runtime, Java 25+; else `JAVA_HOME`'s) | For all executables and tests; `runtime/` is yours to add | -```bash -./gradlew :examples:calculator:connectedAndroidDeviceTest -``` +- **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/`. +- **The JVM's tests** run on Gradle's Java 25 toolchain (their `JAVA_HOME`). +- **Shipping**: copy `nja/` next to the app's executable, or set `NJA_HOME`. A shared library or framework the app + links finds `nja/` next to the executable that loaded it. +- The binaries need nothing else: on Linux, `libdl` and `libpthread`, which the client's klib adds to their link. -```bash -./gradlew :examples:calculator:jvmTest -``` +## The JVM runtime -## Performance +### How it works -See [BENCHMARKS.md](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. +| | 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 | -## jdk-mobile +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*: -The JVM's runtimes are [jdk-mobile](https://github.com/NucleusFramework/openjdk-mobile)'s releases (from +- **Symbols**: HotSpot and the JDK's natives are linked into one shared library, `-Bsymbolic`, loaded `RTLD_LOCAL` by + `System.loadLibrary`: its `JNI_CreateJavaVM` never meets ART's. A small JDK patch + ([`jdk-mobile/inprocess.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's `libopenjdk` lives). +- **Signals**: ART's `libsigchain` intercepts `sigaction`. HotSpot's `SIGSEGV` handler (implicit null checks, safepoint + polls, stack banging) is chained behind ART's fault manager, which forwards the faults outside ART's code. `-Xrs` + leaves `SIGQUIT` and 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 `/lib` and the class path is +`/nja/classpath`. + +### jdk-mobile + +The mobile JVMs are [jdk-mobile](https://github.com/NucleusFramework/openjdk-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`; the tasks reading them depend on it (`njaJdkMobile`). +extracts them into `build/nja/jdkMobile`. ```kotlin nucleusJvm { @@ -165,27 +207,25 @@ nucleusJvm { } ``` -With `latest`, a new jdk-mobile release reaches the next build: pin `jdkMobileRelease` 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. - -### How jdk-mobile is built +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](https://github.com/NucleusFramework/openjdk-mobile) is a recipe, not a fork of the -JDK: it builds a stable OpenJDK (the 27 line, from [openjdk/jdk27u](https://github.com/openjdk/jdk27u)'s GA releases) +JDK. It builds a stable OpenJDK (the 27 line, from [openjdk/jdk27u](https://github.com/openjdk/jdk27u)'s GA releases) with two patches on top: - `openjdk-mobile.patch`: [openjdk/mobile](https://github.com/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 +- `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 (loaded `RTLD_LOCAL` by 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, the -server VM (C2 JIT) for Android — 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 +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-b.` (`jdk-mobile-27b35.3`: JDK 27, its GA build 35, the recipe's third release on it). @@ -203,62 +243,75 @@ git clone --depth 1 --branch jdk-27-ga https://github.com/openjdk/jdk27u.git jdk openjdk-mobile/build.sh android-aarch64 jdk # or android-x64, ios-simulator, ios-device ``` -The result (`dist/jdk-mobile-.tar.gz`) has the release's layout; extract it into `/` for +The result (`dist/jdk-mobile-.tar.gz`) has the release's layout: extract it into `/` for `nucleusJvm.jdkMobile`. [`jdk-mobile/inprocess.patch`](jdk-mobile/inprocess.patch) is a copy of the recipe's. -## Runtimes +## What crosses the bridge -What runs the façades is chosen per platform: `runtime` (both), `iosRuntime`, `androidRuntime` -(`import dev.nucleusframework.nja.plugin.NjaRuntimeType`). +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). -| `NjaRuntimeType` | iOS | Android | The plugin downloads | -|---|---|---|---| -| `JVM` (default) | Zero, linked into the app | HotSpot in the app's process (Android 10+) | jdk-mobile's runtimes | -| `GRAALVM` | the façades' native image | the façades' native image (Android 10+, built on Linux) | graalvm-mobile's kit, GraalVM CE | -| `ART` | – (iOS keeps `JVM`) | the façades dexed with the app, on ART itself | nothing | +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). -`ART` is for Java libraries ART runs as they are, whose module targets iOS through NJA: the façades and NJA's server -become the app's own dependencies, called in process like on a JVM target; no runtime in the app, and the app's own -`minSdk`. +**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). -## GraalVM native images +## Tests -Instead of jdk-mobile's JVM, the façades can run compiled ahead of time into a GraalVM native image, linked into the -app: no interpreter on iOS (Zero runs searches 100× slower than an image), no JIT nor class metadata on Android. +`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. -```kotlin -nucleusJvm { - runtime = NjaRuntimeType.GRAALVM // iOS and Android; default: NjaRuntimeType.JVM - androidRuntime = NjaRuntimeType.JVM // or per platform (iosRuntime, androidRuntime) - graalvmMobileRelease = "graalvm-mobile-25.4.4.1.1b1.1" // default: latest - nativeImageOptions.add("-H:+ReportExceptionStackTraces") -} +```bash +./gradlew :examples:calculator:iosSimulatorArm64Test ``` -(`import dev.nucleusframework.nja.plugin.NjaRuntimeType` in the build script.) The plugin downloads, into Gradle's -cache, [graalvm-mobile](https://github.com/NucleusFramework/graalvm-mobile)'s kit for each target (GraalVM CE's static -libraries for iOS and Android, rebuilt by its CI for each GraalVM CE release) and the GraalVM CE release it is for, for -the build host; `njaNativeImage` compiles the façades with it into an object, which the iOS binaries and -Android's `libnja.so` link. The app's code doesn't change: the client finds the image's entry points at run time. - -- **Reachability metadata**: libraries reaching classes by reflection or resources bring their native-image metadata - in their jars (`META-INF/native-image///reachability-metadata.json`), as GraalVM's own - [reachability metadata](https://www.graalvm.org/latest/reference-manual/native-image/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**: `jvmOptions`' `-Xmx` becomes the image's maximum heap (`-R:MaxHeapSize`), its `-D` system properties - are kept; `nativeImageOptions` go 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); on macOS, keep `androidRuntime = NjaRuntimeType.JVM` for local builds. native-image runs - small C programs for the target: on a Linux host of another architecture (arm64 images on x64), through qemu-user - (`qemu-user-static` with binfmt). GraalVM has no FFM - API (`java.lang.foreign`) for Android: the libraries must do without it. +```bash +./gradlew :examples:calculator:connectedAndroidDeviceTest +``` + +```bash +./gradlew :examples:calculator:macosArm64Test # or linuxX64Test, linuxArm64Test, mingwX64Test, on that OS +``` + +```bash +./gradlew :examples:calculator:jvmTest +``` + +`-Pnja.runtime=JVM` runs the same suites on the JVM runtime. + +## Performance + +See [BENCHMARKS.md](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 native image runs the same +libraries without an interpreter. ## Layout -- `plugin-build/` — the Gradle plugins (`dev.nucleusframework.nja.facade`, `dev.nucleusframework.nja`): PSI analysis, - member table, server and client generators, Android linking/packaging, iOS linking/bundling. -- `runtime/server` — runs in the mobile JVM: dispatch, handles, async (suspend/Flow), the Android and iOS links. -- `runtime/client` — KMP: codec, call scopes and leases, proxies' base, async, the Android and iOS transports. -- `runtime/android-native` — the ART ↔ HotSpot bridge (C). -- `examples/` — `calculator` (the test suites), `torture-facade`, `benchmark*`. +- `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*`. diff --git a/examples/calculator/build.gradle.kts b/examples/calculator/build.gradle.kts index d25658e..0de1d4f 100644 --- a/examples/calculator/build.gradle.kts +++ b/examples/calculator/build.gradle.kts @@ -16,6 +16,12 @@ kotlin { } iosSimulatorArm64() iosArm64() + // Kotlin/Native on the desktop: the same suites, the runtime next to the test executable + macosArm64() + macosX64() + linuxX64() + linuxArm64() + mingwX64() // The desktop: the façades in this JVM, the same suites jvm() @@ -43,7 +49,7 @@ nucleusJvm { // A second façade in the same JVM: NJA's own stress tests facade(project(":examples:torture-facade")) jvmOptions.addAll("-Xss2m", "-Xmx512m") - // The same suites on a GraalVM native image: -Pnja.runtime=GRAALVM + // The same suites on a JVM (jdk-mobile's on iOS and Android, a JDK's on the desktop): -Pnja.runtime=JVM providers.gradleProperty("nja.runtime").orNull?.let { runtime.set(dev.nucleusframework.nja.plugin.NjaRuntimeType.valueOf(it)) } // -Pnja.androidAbis=arm64-v8a,x86_64 providers.gradleProperty("nja.androidAbis").orNull?.let { androidAbis.set(it.split(',').toSet()) } diff --git a/examples/calculator/src/androidDeviceTest/kotlin/com/example/calculator/client/TortureSupport.android.kt b/examples/calculator/src/androidDeviceTest/kotlin/com/example/calculator/client/TortureSupport.android.kt index 7bd5550..1ae536e 100644 --- a/examples/calculator/src/androidDeviceTest/kotlin/com/example/calculator/client/TortureSupport.android.kt +++ b/examples/calculator/src/androidDeviceTest/kotlin/com/example/calculator/client/TortureSupport.android.kt @@ -46,3 +46,5 @@ internal actual fun appFaultStorm(count: Int): Int { } return caught + (if (missing == null) 0 else 0) } + +internal actual val isDesktopNative: Boolean = false diff --git a/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/NjaTortureTest.kt b/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/NjaTortureTest.kt index 550225b..4f51f6b 100644 --- a/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/NjaTortureTest.kt +++ b/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/NjaTortureTest.kt @@ -29,7 +29,7 @@ import kotlin.time.TimeSource class NjaTortureTest { private val jvm = JvmTorture() - private val isAndroid = jvm.vm().name.contains("Server") + private val isAndroid = !isDesktopNative && jvm.vm().name.contains("Server") @Test fun `the JVM is the expected one`() { @@ -42,6 +42,10 @@ class NjaTortureTest { } else if (vm.name.contains("Substrate")) { // A GraalVM native image (GraalVM CE 25) assertTrue(vm.version.startsWith("25"), "$vm") + } else if (isDesktopNative) { + // A JDK's HotSpot (the façades' Java 25 or later) + assertTrue(vm.version.substringBefore('.').toInt() >= 25, "$vm") + assertTrue(vm.name.contains("Server"), "$vm") } else if (!vm.name.contains("Dalvik")) { // jdk-mobile's JVM (on ART, the façades run as they are) assertTrue(vm.version.startsWith("27"), "$vm") diff --git a/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/TortureSupport.kt b/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/TortureSupport.kt index cba10ba..ff72297 100644 --- a/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/TortureSupport.kt +++ b/examples/calculator/src/commonTest/kotlin/com/example/calculator/client/TortureSupport.kt @@ -36,6 +36,9 @@ internal expect fun platformGetenv(name: String): String? /** On a JVM target, the version of the JVM the tests (and so the façades) run in; on the mobile ones, null (jdk-mobile). */ internal expect fun hostJvmVersion(): String? +/** Kotlin/Native on macOS, Linux or Windows: the JVM runtime is a JDK's HotSpot. */ +internal expect val isDesktopNative: Boolean + object System { private val origin = TimeSource.Monotonic.markNow() diff --git a/examples/calculator/src/jvmTest/kotlin/com/example/calculator/client/TortureSupport.jvm.kt b/examples/calculator/src/jvmTest/kotlin/com/example/calculator/client/TortureSupport.jvm.kt index bcbdb0b..be8e895 100644 --- a/examples/calculator/src/jvmTest/kotlin/com/example/calculator/client/TortureSupport.jvm.kt +++ b/examples/calculator/src/jvmTest/kotlin/com/example/calculator/client/TortureSupport.jvm.kt @@ -46,3 +46,5 @@ internal actual fun appFaultStorm(count: Int): Int { } return caught + (if (missing == null) 0 else 0) } + +internal actual val isDesktopNative: Boolean = false diff --git a/examples/calculator/src/iosTest/kotlin/com/example/calculator/client/TortureSupport.ios.kt b/examples/calculator/src/nativeTest/kotlin/com/example/calculator/client/TortureSupport.native.kt similarity index 86% rename from examples/calculator/src/iosTest/kotlin/com/example/calculator/client/TortureSupport.ios.kt rename to examples/calculator/src/nativeTest/kotlin/com/example/calculator/client/TortureSupport.native.kt index 7d208e2..0def7e1 100644 --- a/examples/calculator/src/iosTest/kotlin/com/example/calculator/client/TortureSupport.ios.kt +++ b/examples/calculator/src/nativeTest/kotlin/com/example/calculator/client/TortureSupport.native.kt @@ -7,6 +7,7 @@ import kotlinx.cinterop.ExperimentalForeignApi import kotlinx.cinterop.StableRef import kotlinx.cinterop.alloc import kotlinx.cinterop.asStableRef +import kotlinx.cinterop.convert import kotlinx.cinterop.memScoped import kotlinx.cinterop.nativeHeap import kotlinx.cinterop.ptr @@ -25,6 +26,8 @@ import platform.posix.sched_yield import platform.posix.timespec import kotlin.concurrent.atomics.AtomicBoolean import kotlin.experimental.ExperimentalNativeApi +import kotlin.native.OsFamily +import kotlin.native.Platform import kotlin.native.runtime.GC import kotlin.native.runtime.NativeRuntimeApi @@ -43,7 +46,7 @@ private class Runner(val body: () -> Unit) { } } -/** A pthread with a JVM-like 8 MB stack (iOS' default for secondary threads is 512 KB). */ +/** A pthread with a JVM-like 8 MB stack (iOS' and macOS' default for secondary threads is 512 KB). */ actual class Thread actual constructor(body: () -> Unit) { private val runner = Runner(body) private val handle = nativeHeap.alloc() @@ -56,7 +59,7 @@ actual class Thread actual constructor(body: () -> Unit) { memScoped { val attr = alloc() pthread_attr_init(attr.ptr) - pthread_attr_setstacksize(attr.ptr, 8uL * 1024uL * 1024uL) + pthread_attr_setstacksize(attr.ptr, (8 * 1024 * 1024).convert()) val ref = StableRef.create(runner) val entry = staticCFunction { arg: COpaquePointer? -> val r = arg!!.asStableRef() @@ -90,8 +93,8 @@ actual class Thread actual constructor(body: () -> Unit) { actual fun sleep(millis: Long, nanos: Int) { memScoped { val ts = alloc() - ts.tv_sec = millis / 1000 - ts.tv_nsec = (millis % 1000) * 1_000_000 + nanos + ts.tv_sec = (millis / 1000).convert() + ts.tv_nsec = ((millis % 1000) * 1_000_000 + nanos).convert() nanosleep(ts.ptr, null) } } @@ -113,6 +116,9 @@ internal actual fun platformGetenv(name: String): String? = getenv(name)?.toKStr internal actual fun hostJvmVersion(): String? = null +internal actual val isDesktopNative: Boolean = + Platform.osFamily == OsFamily.MACOSX || Platform.osFamily == OsFamily.LINUX || Platform.osFamily == OsFamily.WINDOWS + internal actual fun appFaultStorm(count: Int): Int { var caught = 0 val holder: Any? = if (count < 0) "never" else null diff --git a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/NjaPlugin.kt b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/NjaPlugin.kt index ae3ea21..d4f2334 100644 --- a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/NjaPlugin.kt +++ b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/NjaPlugin.kt @@ -8,6 +8,7 @@ import dev.nucleusframework.nja.plugin.tasks.NjaAndroidRuntimeTask import dev.nucleusframework.nja.plugin.tasks.NjaGraalvmTask import dev.nucleusframework.nja.plugin.tasks.NjaJdkMobileTask import dev.nucleusframework.nja.plugin.tasks.NjaNativeImageTask +import dev.nucleusframework.nja.plugin.tasks.NjaNativeLibraryTask import dev.nucleusframework.nja.plugin.tasks.PACKAGES_FILE import org.gradle.api.Plugin import org.gradle.api.Project @@ -22,30 +23,40 @@ import org.gradle.api.provider.ListProperty import org.gradle.api.provider.Property import org.gradle.api.provider.SetProperty import org.gradle.api.tasks.Copy +import org.gradle.api.tasks.Sync import org.gradle.api.tasks.TaskProvider +import org.gradle.jvm.toolchain.JavaLanguageVersion +import org.gradle.jvm.toolchain.JavaToolchainService import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType import org.jetbrains.kotlin.gradle.plugin.mpp.Executable import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget import org.jetbrains.kotlin.gradle.plugin.mpp.TestExecutable +import org.jetbrains.kotlin.gradle.targets.native.tasks.KotlinNativeTest import org.jetbrains.kotlin.gradle.targets.jvm.KotlinJvmTarget +import org.jetbrains.kotlin.konan.target.Architecture import org.jetbrains.kotlin.konan.target.Family import org.jetbrains.kotlin.konan.target.KonanTarget import java.io.File import java.util.Properties -/** What runs the façades on a mobile platform. */ +/** What runs the façades on a platform of the app (a JVM target runs them in its own JVM, whatever this says). */ enum class NjaRuntimeType { - /** jdk-mobile's OpenJDK: HotSpot in the app's process on Android, Zero (an interpreter) on iOS. */ - JVM, - /** - * The façades compiled ahead of time into a GraalVM native image (GraalVM CE, with graalvm-mobile's libraries), - * linked into the app. Much faster than Zero on iOS, lighter than HotSpot on Android; no FFM API on Android, and an - * Android image builds on Linux only. Libraries bring their reachability metadata (`META-INF/native-image`). + * The façades compiled ahead of time into a GraalVM native image (GraalVM CE), the default: on iOS and Android + * linked into the app (with graalvm-mobile's libraries), on macOS, Linux and Windows a shared library next to the + * executable. Much faster than Zero on iOS, lighter than HotSpot on Android, no JVM to ship on the desktop. An image + * builds on its own platform's host (Android's on Linux); no FFM API on Android. Libraries bring their reachability + * metadata (`META-INF/native-image`). */ GRAALVM, + /** + * A JVM in the app's process: jdk-mobile's OpenJDK on mobile (HotSpot on Android, Zero, an interpreter, on iOS), a + * JDK's HotSpot on macOS, Linux and Windows (the app's `nja/runtime`, or `JAVA_HOME`'s). + */ + JVM, + /** * Android only: the façades on ART itself, dexed with the app, for libraries ART runs as they are (whose module * targets iOS through NJA): no runtime in the app, nothing below Android 10 required. @@ -55,17 +66,29 @@ enum class NjaRuntimeType { abstract class NjaExtension(private val project: Project) { /** - * What runs the façades on iOS and Android, unless [iosRuntime] or [androidRuntime] say otherwise. JVM by default; - * ART applies to Android only (iOS then runs the JVM). + * What runs the façades on every platform, unless [iosRuntime], [androidRuntime] or [desktopRuntime] say + * otherwise: GRAALVM by default. ART applies to Android only (the others then run GRAALVM). */ abstract val runtime: Property /** What runs the façades on iOS ([runtime] by default). */ abstract val iosRuntime: Property - /** What runs the façades on Android ([runtime] by default). */ + /** + * What runs the façades on Android: [runtime] by default, except on a build host other than Linux, which can't + * build an Android native image: the JVM there, unless set. + */ abstract val androidRuntime: Property + /** What runs the façades in a Kotlin/Native macOS, Linux or Windows binary ([runtime] by default). */ + abstract val desktopRuntime: Property + + /** + * The GraalVM CE release (graalvm/graalvm-ce-builds' tag, e.g. `graal-25.5.5.0.3`) building the desktop's native images: + * `latest` by default. The mobile ones use the release their graalvm-mobile kit is for. + */ + abstract val graalvmRelease: Property + /** * The graalvm-mobile release a native image's libraries come from: `latest` (the default) or a tag * (`graalvm-mobile-25.4.4.1.1b1.1`), downloaded from [graalvmMobileRepository]'s releases. native-image is the @@ -108,9 +131,10 @@ abstract class NjaExtension(private val project: Project) { } /** - * Applied to a Kotlin Multiplatform module (Android, iOS, the JVM): its common code gets the façades' proxies, and its - * binaries the JVM: on Android HotSpot, in the app's process next to ART; on iOS Zero, linked into the app; on a JVM - * target the app's own JVM, the façades on its class path. + * Applied to a Kotlin Multiplatform module (Android, iOS, macOS, Linux, Windows, the JVM): its common code gets the + * façades' proxies, and its binaries the runtime running them (see [NjaRuntimeType]): a GraalVM native image by default, + * linked into the app on mobile, next to the executable on the desktop; or a JVM in the app's process. On a JVM target + * the app's own JVM, the façades on its class path. */ class NjaPlugin : Plugin { override fun apply(project: Project) { @@ -119,10 +143,16 @@ class NjaPlugin : Plugin { extension.jvmOptions.convention(emptyList()) extension.jdkMobileRelease.convention(NjaJdkMobileTask.LATEST) extension.jdkMobileRepository.convention("NucleusFramework/openjdk-mobile") - extension.runtime.convention(NjaRuntimeType.JVM) - // ART is Android's: iOS keeps the JVM then - extension.iosRuntime.convention(extension.runtime.map { if (it == NjaRuntimeType.ART) NjaRuntimeType.JVM else it }) - extension.androidRuntime.convention(extension.runtime) + extension.runtime.convention(NjaRuntimeType.GRAALVM) + // ART is Android's: the others run a native image then + val notArt = extension.runtime.map { if (it == NjaRuntimeType.ART) NjaRuntimeType.GRAALVM else it } + extension.iosRuntime.convention(notArt) + extension.desktopRuntime.convention(notArt) + // An Android native image builds on Linux only: elsewhere, Android runs the JVM unless told otherwise + extension.androidRuntime.convention( + extension.runtime.map { if (it == NjaRuntimeType.GRAALVM && !isLinuxHost()) NjaRuntimeType.JVM else it }, + ) + extension.graalvmRelease.convention(NjaJdkMobileTask.LATEST) extension.graalvmMobileRelease.convention(NjaJdkMobileTask.LATEST) extension.graalvmMobileRepository.convention("NucleusFramework/graalvm-mobile") extension.nativeImageOptions.convention(emptyList()) @@ -166,8 +196,13 @@ class NjaPlugin : Plugin { val kotlin = project.extensions.getByType(KotlinMultiplatformExtension::class.java) kotlin.sourceSets.getByName("commonMain").kotlin.srcDir(clientSources.map { it.incoming.files }) project.dependencies.add("commonMainApi", "dev.nucleusframework.nja:nja-client:$NJA_VERSION") + val nativeLibrary = lazy { registerNativeLibrary(project, extension, nativeImageClassPath) } kotlin.targets.withType(KotlinNativeTarget::class.java).configureEach { - if (konanTarget.family == Family.IOS) configureIos(project, extension, classPath.get(), this, jdkMobileTasks, nativeImages) + when (konanTarget.family) { + Family.IOS -> configureIos(project, extension, classPath.get(), this, jdkMobileTasks, nativeImages) + Family.OSX, Family.LINUX, Family.MINGW -> configureDesktop(project, extension, classPath.get(), this, nativeLibrary) + else -> Unit + } } kotlin.targets.withType(KotlinJvmTarget::class.java).configureEach { configureJvm(project, this, facades, clientSources.get()) } } @@ -212,6 +247,28 @@ class NjaPlugin : Plugin { } } + /** The desktop's native image: GraalVM CE for the host ([NjaExtension.graalvmRelease]), native-image's shared library. */ + private fun registerNativeLibrary( + project: Project, + extension: NjaExtension, + classPath: org.gradle.api.provider.Provider, + ): TaskProvider { + val graalvm = project.tasks.register("njaGraalvmHost", NjaGraalvmTask::class.java) { + description = "Downloads GraalVM CE for this host, for the desktop's native image." + release.set(extension.graalvmRelease) + cacheDir.set(project.gradle.gradleUserHomeDir.resolve("caches/nja/graalvm")) + offline.set(project.gradle.startParameter.isOffline) + homeFile.set(project.layout.buildDirectory.file("nja/graalvm/host.home")) + } + return project.tasks.register("njaNativeLibrary", NjaNativeLibraryTask::class.java) { + description = "Compiles the façades into a GraalVM native image for this host, a shared library." + graalvmHome.set(graalvm.flatMap { it.homeFile }) + this.classPath.from(classPath) + options.set(extension.jvmOptions.zip(extension.nativeImageOptions) { jvm, own -> nativeImageOptions(jvm) + own }) + libraryFile.set(project.layout.buildDirectory.file("nja/nativeLibrary/${NjaNativeLibraryTask.libraryName()}")) + } + } + // The JVM's options a native image has: its maximum heap and system properties private fun nativeImageOptions(jvmOptions: List): List = jvmOptions.mapNotNull { when { @@ -424,9 +481,99 @@ class NjaPlugin : Plugin { } } + /** + * A Kotlin/Native macOS, Linux or Windows target: its executables find the runtime in `nja/` next to them (or in + * `NJA_HOME`), loaded at run time, so they link (and cross-compile) without it. A native image builds on its own + * platform's host only: built elsewhere, the executables get no runtime (a warning says so). + */ + private fun configureDesktop( + project: Project, + extension: NjaExtension, + classPath: Configuration, + target: KotlinNativeTarget, + nativeLibrary: Lazy>, + ) { + val name = target.name.replaceFirstChar { it.uppercaseChar() } + val graal = extension.desktopRuntime.map { + check(it != NjaRuntimeType.ART) { "NJA: ART is Android's: desktopRuntime is GRAALVM or JVM" } + it == NjaRuntimeType.GRAALVM + } + val hostTarget = isHostTarget(target.konanTarget) + val targetName = target.name + val bundle = project.tasks.register("njaDesktopBundle$name", Sync::class.java) { + description = "Lays out what ${target.name}'s executables load: the native image, or the JVM's class path and options." + into(project.layout.buildDirectory.dir("nja/desktop/${target.name}")) + dependsOn(graal.map { if (it && hostTarget) listOf(nativeLibrary.value) else emptyList() }) + from(graal.map { if (it && hostTarget) listOf(nativeLibrary.value.flatMap { task -> task.libraryFile }) else emptyList() }) { + into("nja") + } + from(graal.map { if (it) emptyList() else listOf(classPath) }) { into("nja/classpath") } + val options = extension.jvmOptions + inputs.property("jvmOptions", options) + inputs.property("graal", graal) + doLast { + if (graal.get()) { + if (!hostTarget) { + logger.warn( + "nja: $targetName's native image builds on its own platform only (not ${NjaGraalvmTask.hostPlatform()}): " + + "its executables have no runtime", + ) + } + } else { + destinationDir.resolve("nja").mkdirs() + destinationDir.resolve("nja/jvm.options").writeText(options.get().joinToString("\n")) + } + } + } + // The JVM on this host: a JDK 25 (Gradle's toolchain) runs the tests + val testJavaHome = project.provider { + project.extensions.findByType(JavaToolchainService::class.java) + ?.launcherFor { languageVersion.set(JavaLanguageVersion.of(JAVA_VERSION)) }?.get()?.metadata?.installationPath?.asFile?.path + } + target.binaries.configureEach { + val binary = this + if (binary !is Executable && binary !is TestExecutable) return@configureEach + val install = project.tasks.register("njaInstall${binary.name.replaceFirstChar { it.uppercaseChar() }}$name", Copy::class.java) { + from(bundle) + into(binary.outputDirectory) + // The previous runtime goes: a native image and a class path don't mix + val runtimeDir = binary.outputDirectory.resolve("nja") + doFirst { runtimeDir.deleteRecursively() } + } + binary.linkTaskProvider.configure { finalizedBy(install) } + if (binary is TestExecutable) { + project.tasks.withType(KotlinNativeTest::class.java).matching { it.name == "${target.name}Test" }.configureEach { + dependsOn(install) + if (!graal.get()) testJavaHome.get()?.let { environment("JAVA_HOME", it) } + } + } + } + } + + private fun isHostTarget(target: KonanTarget): Boolean { + val os = System.getProperty("os.name").lowercase() + val family = when { + os.startsWith("mac") -> Family.OSX + os.startsWith("linux") -> Family.LINUX + os.startsWith("windows") -> Family.MINGW + else -> return false + } + val architecture = when (System.getProperty("os.arch")) { + "aarch64", "arm64" -> Architecture.ARM64 + "x86_64", "amd64" -> Architecture.X64 + else -> return false + } + return target.family == family && target.architecture == architecture + } + + private fun isLinuxHost() = System.getProperty("os.name").lowercase().startsWith("linux") + companion object { const val FACADES = "njaFacades" + /** The façades' Java version: the desktop JVM's tests run on a JDK of it. */ + private const val JAVA_VERSION = 25 + /** jdk-mobile's targets, as its releases name their runtimes. */ val JDK_MOBILE_TARGETS = listOf("android-aarch64", "android-x64", "ios-simulator-aarch64", "ios-device-aarch64") diff --git a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/GitHubReleases.kt b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/GitHubReleases.kt new file mode 100644 index 0000000..1983613 --- /dev/null +++ b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/GitHubReleases.kt @@ -0,0 +1,53 @@ +package dev.nucleusframework.nja.plugin.tasks + +import org.gradle.api.GradleException +import org.gradle.api.logging.Logger +import java.io.File +import java.net.HttpURLConnection +import java.net.URI +import java.util.Properties + +/** + * A GitHub repository's releases: `latest` resolved through the release page's redirect (no API, no rate limit) and + * kept a day in [cacheDir]; offline or the network down, the last one resolved. + */ +internal object GitHubReleases { + private const val DAY_MILLIS = 24L * 60 * 60 * 1000 + + fun resolve(repo: String, release: String, cacheDir: File, offline: Boolean, logger: Logger): String { + if (release != NjaJdkMobileTask.LATEST) return release + val cache = File(cacheDir, "latest-${repo.replace('/', '_')}.properties") + val known = Properties().apply { if (cache.isFile) cache.reader().use { load(it) } } + val knownTag = known.getProperty("tag") + val fresh = System.currentTimeMillis() - (known.getProperty("at")?.toLongOrNull() ?: 0L) < DAY_MILLIS + if (knownTag != null && (fresh || offline)) return knownTag + if (offline) throw GradleException("NJA: offline, and $repo's latest release was never resolved") + val tag = try { + latestTag(repo) + } catch (e: Exception) { + knownTag?.also { logger.warn("nja: can't resolve $repo's latest release (${e.message}), using $it") } ?: throw e + } + cache.parentFile.mkdirs() + Properties().apply { + setProperty("tag", tag) + setProperty("at", System.currentTimeMillis().toString()) + cache.writer().use { store(it, null) } + } + return tag + } + + // github.com//releases/latest redirects to .../releases/tag/ + private fun latestTag(repo: String): String { + val connection = URI("https://github.com/$repo/releases/latest").toURL().openConnection() as HttpURLConnection + connection.instanceFollowRedirects = false + connection.requestMethod = "HEAD" + try { + val location = connection.getHeaderField("Location") + ?: throw GradleException("NJA: no latest release of $repo (HTTP ${connection.responseCode})") + return location.substringAfterLast("/releases/tag/").takeIf { it != location && it.isNotEmpty() } + ?: throw GradleException("NJA: unexpected latest release of $repo: $location") + } finally { + connection.disconnect() + } + } +} diff --git a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaGraalvmTask.kt b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaGraalvmTask.kt index 7832337..ecf4c42 100644 --- a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaGraalvmTask.kt +++ b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaGraalvmTask.kt @@ -3,9 +3,12 @@ package dev.nucleusframework.nja.plugin.tasks import org.gradle.api.DefaultTask import org.gradle.api.GradleException import org.gradle.api.file.DirectoryProperty +import org.gradle.api.file.RegularFileProperty import org.gradle.api.provider.Property +import org.gradle.api.tasks.Input import org.gradle.api.tasks.InputDirectory import org.gradle.api.tasks.Internal +import org.gradle.api.tasks.Optional import org.gradle.api.tasks.OutputFile import org.gradle.api.tasks.PathSensitive import org.gradle.api.tasks.PathSensitivity @@ -17,49 +20,63 @@ import java.net.URI import java.util.Properties /** - * GraalVM CE for the build host, the release a graalvm-mobile kit ([kit]) is for (its `graalvm.tag`): downloaded from - * graalvm/graalvm-ce-builds' release into Gradle's cache ([cacheDir]) and extracted there once. Writes its home's path - * to [homeFile]. + * GraalVM CE for the build host: the release a graalvm-mobile kit ([kit]) is for (its `graalvm.tag`), or, without a kit + * (the desktop), [release] (`latest` by default). Downloaded from graalvm/graalvm-ce-builds' release into Gradle's + * cache ([cacheDir]) and extracted there once. Writes its home's path to [homeFile]. */ @DisableCachingByDefault(because = "Downloads into Gradle's cache") abstract class NjaGraalvmTask : DefaultTask() { - @get:InputDirectory @get:PathSensitive(PathSensitivity.RELATIVE) abstract val kit: DirectoryProperty + @get:InputDirectory @get:Optional @get:PathSensitive(PathSensitivity.RELATIVE) abstract val kit: DirectoryProperty + @get:Input @get:Optional abstract val release: Property @get:Internal abstract val cacheDir: DirectoryProperty @get:Internal abstract val offline: Property - @get:OutputFile abstract val homeFile: org.gradle.api.file.RegularFileProperty + @get:OutputFile abstract val homeFile: RegularFileProperty + + init { + // latest may have moved: checked every build (cheaply: the resolution is cached, GraalVM CE too) + outputs.upToDateWhen { !release.isPresent || release.get() != NjaJdkMobileTask.LATEST } + } @TaskAction fun stage() { - val properties = Properties().apply { File(kit.get().asFile, KIT_PROPERTIES).reader().use { load(it) } } - val tag = properties.getProperty("graalvm.tag")?.takeIf { it.isNotEmpty() } - ?: throw GradleException("NJA: the graalvm-mobile kit doesn't name its GraalVM release (graalvm.tag)") + val tag = if (kit.isPresent) { + val properties = Properties().apply { File(kit.get().asFile, KIT_PROPERTIES).reader().use { load(it) } } + properties.getProperty("graalvm.tag")?.takeIf { it.isNotEmpty() } + ?: throw GradleException("NJA: the graalvm-mobile kit doesn't name its GraalVM release (graalvm.tag)") + } else { + GitHubReleases.resolve(UPSTREAM, release.getOrElse(NjaJdkMobileTask.LATEST), cacheDir.get().asFile, offline.get(), logger) + } val dir = File(cacheDir.get().asFile, "$tag-${hostPlatform()}") - val home = File(dir, "home") - if (!File(home, "bin/native-image").isFile) { + val home = homeIn(dir) + if (home == null || !File(home, nativeImageExecutable()).isFile) { if (offline.get()) throw GradleException("NJA: offline, and GraalVM CE $tag isn't in Gradle's cache") download(tag, dir) } - homeFile.get().asFile.writeText(home.canonicalPath) + homeFile.get().asFile.writeText(homeIn(dir)!!.canonicalPath) } + // Its home, once extracted: named in home.path (no symbolic links on Windows), or by the link `home` of earlier versions + private fun homeIn(dir: File): File? = + File(dir, "home.path").takeIf { it.isFile }?.let { File(it.readText().trim()) } ?: File(dir, "home").takeIf { it.isDirectory } + private fun download(tag: String, dir: File) { - val suffix = "_${hostPlatform()}_bin.tar.gz" + val suffix = "_${hostPlatform()}_bin.${if (isWindows()) "zip" else "tar.gz"}" val api = "https://api.github.com/repos/$UPSTREAM/releases/tags/$tag" val json = open(api).inputStream.use { it.readBytes().decodeToString() } val url = Regex("\"browser_download_url\"\\s*:\\s*\"([^\"]+${Regex.escape(suffix)})\"").find(json)?.groupValues?.get(1) ?: throw GradleException("NJA: no GraalVM CE for ${hostPlatform()} in $UPSTREAM's release $tag") dir.deleteRecursively() val extracted = File(dir, "extracted").apply { mkdirs() } - val archive = File(dir, "graalvm.tar.gz") + val archive = File(dir, "graalvm${suffix.substringAfter("_bin")}") logger.lifecycle("nja: downloading GraalVM CE $tag for ${hostPlatform()}") open(url).inputStream.use { input -> archive.outputStream().use { input.copyTo(it) } } - // tar keeps the archive's symbolic links and permissions - val tar = ProcessBuilder("tar", "-xzf", archive.path, "-C", extracted.path).inheritIO().start() + // tar keeps the archive's symbolic links and permissions; Windows' own (bsdtar) reads zip archives too + val tar = ProcessBuilder("tar", "-xf", archive.path, "-C", extracted.path).inheritIO().start() if (tar.waitFor() != 0) throw GradleException("NJA: can't extract $archive") archive.delete() - val release = extracted.walkTopDown().maxDepth(4).firstOrNull { it.name == "release" && File(it.parentFile, "bin").isDirectory } + val release = extracted.walkTopDown().maxDepth(5).firstOrNull { it.name == "release" && File(it.parentFile, "bin").isDirectory } ?: throw GradleException("NJA: no GraalVM home in $url") - java.nio.file.Files.createSymbolicLink(File(dir, "home").toPath(), release.parentFile.toPath()) + File(dir, "home.path").writeText(release.parentFile.canonicalPath) } // The GitHub API, with a token when there is one (its rate limit is the token's then) @@ -76,6 +93,11 @@ abstract class NjaGraalvmTask : DefaultTask() { const val UPSTREAM = "graalvm/graalvm-ce-builds" const val KIT_PROPERTIES = "graalvm-mobile.properties" + fun isWindows() = System.getProperty("os.name").lowercase().startsWith("windows") + + /** native-image, relative to GraalVM's home. */ + fun nativeImageExecutable() = if (isWindows()) "bin/native-image.cmd" else "bin/native-image" + /** The build host, as GraalVM CE names its archives. */ fun hostPlatform(): String { val os = System.getProperty("os.name").lowercase() @@ -87,7 +109,8 @@ abstract class NjaGraalvmTask : DefaultTask() { return when { os.startsWith("mac") -> "macos-$arch" os.startsWith("linux") -> "linux-$arch" - else -> throw GradleException("NJA: GraalVM's mobile targets build on macOS or Linux, not ${System.getProperty("os.name")}") + os.startsWith("windows") -> "windows-$arch" + else -> throw GradleException("NJA: GraalVM CE has no build for ${System.getProperty("os.name")}") } } } diff --git a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaJdkMobileTask.kt b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaJdkMobileTask.kt index db1d35b..d449dab 100644 --- a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaJdkMobileTask.kt +++ b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaJdkMobileTask.kt @@ -12,10 +12,8 @@ import org.gradle.api.tasks.OutputDirectory import org.gradle.api.tasks.TaskAction import org.gradle.work.DisableCachingByDefault import java.io.File -import java.net.HttpURLConnection import java.net.URI import java.security.MessageDigest -import java.util.Properties import javax.inject.Inject /** @@ -50,7 +48,7 @@ abstract class NjaJdkMobileTask : DefaultTask() { @TaskAction fun stage() { val repo = repository.get() - val tag = resolve(repo, release.get()) + val tag = GitHubReleases.resolve(repo, release.get(), cacheDir.get().asFile, offline.get(), logger) val asset = assetName(product.get(), tag, target.get()) val out = outputDir.get().asFile val marker = File(out, ".nja-release") @@ -73,44 +71,6 @@ abstract class NjaJdkMobileTask : DefaultTask() { File(out, "bin").listFiles()?.forEach { it.setExecutable(true) } } - private fun resolve(repo: String, release: String): String { - if (release != LATEST) return release - val cache = File(cacheDir.get().asFile, "latest-${repo.replace('/', '_')}.properties") - val known = Properties().apply { if (cache.isFile) cache.reader().use { load(it) } } - val knownTag = known.getProperty("tag") - val fresh = System.currentTimeMillis() - (known.getProperty("at")?.toLongOrNull() ?: 0L) < DAY_MILLIS - if (knownTag != null && (fresh || offline.get())) return knownTag - if (offline.get()) throw GradleException("NJA: offline, and $repo's latest release was never resolved") - val tag = try { - latestTag(repo) - } catch (e: Exception) { - // The network down: the last one resolved, if any - knownTag?.also { logger.warn("nja: can't resolve $repo's latest release (${e.message}), using $it") } ?: throw e - } - cache.parentFile.mkdirs() - Properties().apply { - setProperty("tag", tag) - setProperty("at", System.currentTimeMillis().toString()) - cache.writer().use { store(it, null) } - } - return tag - } - - // github.com//releases/latest redirects to .../releases/tag/ - private fun latestTag(repo: String): String { - val connection = URI("https://github.com/$repo/releases/latest").toURL().openConnection() as HttpURLConnection - connection.instanceFollowRedirects = false - connection.requestMethod = "HEAD" - try { - val location = connection.getHeaderField("Location") - ?: throw GradleException("NJA: no latest release of $repo (HTTP ${connection.responseCode})") - return location.substringAfterLast("/releases/tag/").takeIf { it != location && it.isNotEmpty() } - ?: throw GradleException("NJA: unexpected latest release of $repo: $location") - } finally { - connection.disconnect() - } - } - // In Gradle's cache, by release: checked against the .sha256 published with it private fun download(repo: String, tag: String, asset: String): File { val dir = File(cacheDir.get().asFile, "$repo/$tag").apply { mkdirs() } @@ -153,7 +113,6 @@ abstract class NjaJdkMobileTask : DefaultTask() { const val LATEST = "latest" const val JDK_MOBILE = "jdk-mobile" const val GRAALVM_MOBILE = "graalvm-mobile" - private const val DAY_MILLIS = 24L * 60 * 60 * 1000 /** -b. -> ---b..tar.gz */ fun assetName(product: String, tag: String, target: String): String { diff --git a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaNativeLibraryTask.kt b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaNativeLibraryTask.kt new file mode 100644 index 0000000..087e921 --- /dev/null +++ b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/tasks/NjaNativeLibraryTask.kt @@ -0,0 +1,67 @@ +package dev.nucleusframework.nja.plugin.tasks + +import org.gradle.api.DefaultTask +import org.gradle.api.GradleException +import org.gradle.api.file.ConfigurableFileCollection +import org.gradle.api.file.RegularFileProperty +import org.gradle.api.provider.ListProperty +import org.gradle.api.tasks.CacheableTask +import org.gradle.api.tasks.Classpath +import org.gradle.api.tasks.Input +import org.gradle.api.tasks.InputFile +import org.gradle.api.tasks.OutputFile +import org.gradle.api.tasks.PathSensitive +import org.gradle.api.tasks.PathSensitivity +import org.gradle.api.tasks.TaskAction +import java.io.File + +/** + * The façades ([classPath], with NJA's server) compiled into a GraalVM native image for the build host, as a shared + * library ([libraryFile]: `libnja.dylib`, `libnja.so`, `nja.dll`) exporting NJA's entry points, which a Kotlin/Native + * desktop binary loads at run time. native-image is [graalvmHome]'s (a file holding its path); on Windows it needs + * Visual Studio's C toolchain. Libraries bring their reachability metadata in their jars (`META-INF/native-image`); + * [options] are native-image's own. + */ +@CacheableTask +abstract class NjaNativeLibraryTask : DefaultTask() { + @get:InputFile @get:PathSensitive(PathSensitivity.NONE) abstract val graalvmHome: RegularFileProperty + @get:Classpath abstract val classPath: ConfigurableFileCollection + @get:Input abstract val options: ListProperty + @get:OutputFile abstract val libraryFile: RegularFileProperty + + @TaskAction + fun build() { + val home = File(graalvmHome.get().asFile.readText().trim()) + val library = libraryFile.get().asFile + val work = File(temporaryDir, "native-image").apply { deleteRecursively(); mkdirs() } + val command = mutableListOf( + File(home, NjaGraalvmTask.nativeImageExecutable()).path, + "-cp", classPath.files.joinToString(File.pathSeparator), + "--shared", "-H:TempDirectory=${File(work, "tmp").path}", + "-o", File(work, library.nameWithoutExtension).path, + ) + command += options.get() + val process = ProcessBuilder(command).directory(work).redirectErrorStream(true).start() + val output = process.inputStream.bufferedReader().readText() + if (process.waitFor() != 0) { + logger.error(output) + throw GradleException("NJA: native-image failed for ${NjaGraalvmTask.hostPlatform()}") + } + logger.info(output) + val built = File(work, library.name).takeIf { it.isFile } + ?: throw GradleException("NJA: native-image wrote no ${library.name}") + built.copyTo(library, overwrite = true) + } + + companion object { + /** The library's file name on the build host. */ + fun libraryName(): String { + val os = System.getProperty("os.name").lowercase() + return when { + os.startsWith("mac") -> "libnja.dylib" + os.startsWith("windows") -> "nja.dll" + else -> "libnja.so" + } + } + } +} diff --git a/runtime/android-native/src/nja_android_graal.c b/runtime/android-native/src/nja_android_graal.c index 0ee0247..da86f68 100644 --- a/runtime/android-native/src/nja_android_graal.c +++ b/runtime/android-native/src/nja_android_graal.c @@ -23,7 +23,7 @@ extern int graal_attach_thread(graal_isolate_t* isolate, graal_isolatethread_t** extern graal_isolatethread_t* graal_get_current_thread(graal_isolate_t* isolate); extern int graal_detach_thread(graal_isolatethread_t* thread); extern void* nja_graal_dispatch(graal_isolatethread_t* thread, const void* message, int length, int* reply_length); -extern void nja_graal_set_upcall(graal_isolatethread_t* thread, void* upcall); +extern void nja_graal_set_upcall(graal_isolatethread_t* thread, void* upcall, void* release); static JavaVM* art_vm; static jclass jvm_class; // AndroidJvm @@ -70,6 +70,11 @@ static void* upcall(const void* request, int length, int* answer_length) { return buffer; } +// Frees an answer of upcall (the image and this library share bionic's malloc: its replies are freed with free too) +static void release(void* buffer) { + free(buffer); +} + // AndroidJvm.start: creates the isolate (once); its arguments are the JVM's, unused. Null, or the error. static jstring JNICALL art_start(JNIEnv* env, jclass cls, jstring java_home, jstring class_path, jstring link_class, jobjectArray options) { @@ -85,7 +90,7 @@ static jstring JNICALL art_start(JNIEnv* env, jclass cls, jstring java_home, jst return (*env)->NewStringUTF(env, error); } pthread_setspecific(thread_key, thread); - nja_graal_set_upcall(thread, (void*)upcall); + nja_graal_set_upcall(thread, (void*)upcall, (void*)release); } pthread_mutex_unlock(&start_lock); return NULL; diff --git a/runtime/client/build.gradle.kts b/runtime/client/build.gradle.kts index e384d70..2245233 100644 --- a/runtime/client/build.gradle.kts +++ b/runtime/client/build.gradle.kts @@ -23,7 +23,14 @@ kotlin { jvm() jvmToolchain(25) - listOf(iosArm64(), iosSimulatorArm64()).forEach { target -> + // Kotlin/Native: iOS (the runtime linked into the app), macOS, Linux and Windows (the runtime loaded next to the + // executable): one JNI and native image transport for all (nativeMain) + listOf( + iosArm64(), iosSimulatorArm64(), + macosArm64(), macosX64(), + linuxX64(), linuxArm64(), + mingwX64(), + ).forEach { target -> target.compilations.getByName("main").cinterops.create("jni") { definitionFile.set(project.file("src/nativeInterop/cinterop/jni.def")) includeDirs(project.file("src/nativeInterop/cinterop/include")) @@ -51,7 +58,7 @@ mavenPublishing { coordinates("dev.nucleusframework.nja", project.name, project.version.toString()) pom { name.set("Nucleus JVM Access client") - description.set("The part of Nucleus JVM Access running in the app (Android, iOS, the JVM): starts the JVM and calls the façades") + description.set("The part of Nucleus JVM Access running in the app (Android, iOS, macOS, Linux, Windows, the JVM): starts the runtime and calls the façades") url.set("https://github.com/NucleusFramework/NucleusJvmAccess") licenses { license { diff --git a/runtime/client/src/nativeInterop/cinterop/jni.def b/runtime/client/src/nativeInterop/cinterop/jni.def index 3cab82a..7419a8a 100644 --- a/runtime/client/src/nativeInterop/cinterop/jni.def +++ b/runtime/client/src/nativeInterop/cinterop/jni.def @@ -1,20 +1,321 @@ -# JNI (the JVM's invocation API and JNIEnv), from jdk-mobile's headers, and a GraalVM native image's entry points. The -# runtime (jdk-mobile's JVM or the façades' native image) is linked into the app's binary by the NJA Gradle plugin; its -# entry points are looked up at run time, so that the binary links with either. +# JNI (the JVM's invocation API and JNIEnv), from jdk-mobile's headers, and a GraalVM native image's entry points. +# On iOS the runtime (jdk-mobile's JVM or the façades' native image) is linked into the app's binary by the NJA Gradle +# plugin; on macOS, Linux and Windows it is a shared library loaded at run time (the façades' native image, or a JDK's +# libjvm). Either way its entry points are looked up at run time, so that the binary links with any of them. package = dev.nucleusframework.nja.jni headers = jni.h headerFilter = jni.h jni_md.h noStringConversion = NewStringUTF GetStringUTFChars +# glibc declares RTLD_DEFAULT with _GNU_SOURCE +compilerOpts.linux = -D_GNU_SOURCE +linkerOpts.linux = -ldl -lpthread --- +#include +#include +#include + +#ifdef _WIN32 +#include +#else +#include #include +#include +#include +#include +#include +#endif +#ifdef __APPLE__ +#include +#endif + +/* + * The file system, with UTF-8 paths (on Windows, converted to its wide ones): where the runtime is, next to the + * executable. Strings returned are malloc'ed (the caller frees them). + */ +#ifdef _WIN32 +static wchar_t* nja_wide(const char* path) { + int length = MultiByteToWideChar(CP_UTF8, 0, path, -1, NULL, 0); + if (length <= 0) return NULL; + wchar_t* wide = (wchar_t*)malloc(length * sizeof(wchar_t)); + if (wide) MultiByteToWideChar(CP_UTF8, 0, path, -1, wide, length); + return wide; +} + +static char* nja_utf8(const wchar_t* wide) { + int length = WideCharToMultiByte(CP_UTF8, 0, wide, -1, NULL, 0, NULL, NULL); + if (length <= 0) return NULL; + char* utf8 = (char*)malloc(length); + if (utf8) WideCharToMultiByte(CP_UTF8, 0, wide, -1, utf8, length, NULL, NULL); + return utf8; +} +#endif + +/* The running executable's path, or NULL */ +static char* nja_executable_path(void) { +#if defined(_WIN32) + wchar_t path[32768]; + DWORD length = GetModuleFileNameW(NULL, path, 32768); + if (length == 0 || length >= 32768) return NULL; + return nja_utf8(path); +#elif defined(__APPLE__) + uint32_t size = 0; + _NSGetExecutablePath(NULL, &size); + char* path = (char*)malloc(size); + if (!path || _NSGetExecutablePath(path, &size) != 0) { free(path); return NULL; } + char* real = realpath(path, NULL); + free(path); + return real; +#else + return realpath("/proc/self/exe", NULL); +#endif +} + +/* 1: a file, 2: a directory, 0: nothing there */ +static int nja_file_kind(const char* path) { +#ifdef _WIN32 + wchar_t* wide = nja_wide(path); + if (!wide) return 0; + DWORD attributes = GetFileAttributesW(wide); + free(wide); + if (attributes == INVALID_FILE_ATTRIBUTES) return 0; + return (attributes & FILE_ATTRIBUTE_DIRECTORY) ? 2 : 1; +#else + struct stat status; + if (stat(path, &status) != 0) return 0; + return S_ISDIR(status.st_mode) ? 2 : 1; +#endif +} + +/* A directory's entries' names, each followed by a newline; NULL if it can't be read */ +static char* nja_list_directory(const char* path) { + size_t capacity = 1024, length = 0; + char* names = (char*)malloc(capacity); + if (!names) return NULL; +#ifdef _WIN32 + size_t path_length = strlen(path); + char* pattern = (char*)malloc(path_length + 3); + if (!pattern) { free(names); return NULL; } + memcpy(pattern, path, path_length); + memcpy(pattern + path_length, "\\*", 3); + wchar_t* wide = nja_wide(pattern); + free(pattern); + WIN32_FIND_DATAW entry; + HANDLE find = wide ? FindFirstFileW(wide, &entry) : INVALID_HANDLE_VALUE; + free(wide); + if (find == INVALID_HANDLE_VALUE) { free(names); return NULL; } + do { + char* name = nja_utf8(entry.cFileName); + if (!name) continue; +#else + DIR* directory = opendir(path); + if (!directory) { free(names); return NULL; } + struct dirent* entry; + while ((entry = readdir(directory)) != NULL) { + const char* name = entry->d_name; +#endif + size_t name_length = strlen(name); + if (length + name_length + 2 > capacity) { + while (length + name_length + 2 > capacity) capacity *= 2; + char* grown = (char*)realloc(names, capacity); + if (!grown) { free(names); names = NULL; } + names = grown; + } + if (names) { + memcpy(names + length, name, name_length); + length += name_length; + names[length++] = '\n'; + } +#ifdef _WIN32 + free(name); + if (!names) break; + } while (FindNextFileW(find, &entry)); + FindClose(find); +#else + if (!names) break; + } + closedir(directory); +#endif + if (names) names[length] = 0; + return names; +} + +/* A file's content as a C string, or NULL */ +static char* nja_read_file(const char* path) { +#ifdef _WIN32 + wchar_t* wide = nja_wide(path); + FILE* file = wide ? _wfopen(wide, L"rb") : NULL; + free(wide); +#else + FILE* file = fopen(path, "rb"); +#endif + if (!file) return NULL; + size_t capacity = 4096, length = 0, read; + char* content = (char*)malloc(capacity); + while (content && (read = fread(content + length, 1, capacity - length - 1, file)) > 0) { + length += read; + if (capacity - length <= 1) { + char* grown = (char*)realloc(content, capacity *= 2); + if (!grown) { free(content); content = NULL; } + content = grown; + } + } + fclose(file); + if (content) content[length] = 0; + return content; +} + +/* An environment variable (UTF-8), or NULL */ +static char* nja_getenv(const char* name) { +#ifdef _WIN32 + wchar_t* wide_name = nja_wide(name); + if (!wide_name) return NULL; + wchar_t value[32768]; + DWORD length = GetEnvironmentVariableW(wide_name, value, 32768); + free(wide_name); + if (length == 0 || length >= 32768) return NULL; + return nja_utf8(value); +#else + const char* value = getenv(name); + return value ? strdup(value) : NULL; +#endif +} + +/* The shared library holding the runtime, once loaded (NULL: the runtime is linked into the binary, as on iOS) */ +static void* nja_runtime; + +/* Loads the runtime's shared library; [dependencies]: a directory its own dependencies are in, or NULL. NULL on + * success, else the reason (static) */ +static const char* nja_load_runtime(const char* path, const char* dependencies) { +#ifdef _WIN32 + if (dependencies) { + wchar_t* directory = nja_wide(dependencies); + if (directory) AddDllDirectory(directory); + free(directory); + } + wchar_t* wide = nja_wide(path); + HMODULE module = wide ? LoadLibraryExW(wide, NULL, LOAD_LIBRARY_SEARCH_DEFAULT_DIRS | LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR) : NULL; + free(wide); + if (!module) { + static char reason[64]; + snprintf(reason, sizeof reason, "LoadLibrary failed, error %lu", GetLastError()); + return reason; + } + nja_runtime = module; + return NULL; +#else + (void)dependencies; + void* handle = dlopen(path, RTLD_NOW | RTLD_LOCAL); + if (!handle) return dlerror(); + nja_runtime = handle; + return NULL; +#endif +} + +/* A symbol of the runtime: in its shared library once loaded, else in the process (linked in) */ +static void* nja_symbol(const char* name) { +#ifdef _WIN32 + HMODULE module = nja_runtime ? (HMODULE)nja_runtime : GetModuleHandleW(NULL); + return (void*)GetProcAddress(module, name); +#else + return dlsym(nja_runtime ? nja_runtime : RTLD_DEFAULT, name); +#endif +} /* - * A thread attached to the JVM detaches when it ends. Not from a pthread key destructor: Darwin frees the threads' - * thread_local storage before those run, HotSpot's current thread with it. _tlv_atexit (what C++ thread_local - * destructors use) runs while it is still there. No Kotlin runs at that point: plain C. + * Runs [function] when the calling thread exits, while its thread-local storage is still there: the runtime's current + * thread lives in it. Darwin: _tlv_atexit (what C++ thread_local destructors use; Darwin frees the thread_local + * storage before pthread key destructors run). Linux: glibc's __cxa_thread_atexit_impl, the same. Windows: a fiber + * local storage callback, skipped once the process exits (the runtime goes with it). No Kotlin runs at that point. */ +#if defined(__APPLE__) extern void _tlv_atexit(void (*function)(void*), void* argument); +static void nja_at_thread_exit(void (*function)(void*), void* argument) { _tlv_atexit(function, argument); } +#elif defined(_WIN32) +typedef struct nja_exit_hook { void (*function)(void*); void* argument; struct nja_exit_hook* next; } nja_exit_hook; +static DWORD nja_exit_slot = FLS_OUT_OF_INDEXES; +static volatile LONG nja_process_exiting; + +static void nja_mark_exiting(void) { nja_process_exiting = 1; } + +static void WINAPI nja_run_exit_hooks(void* hooks) { + for (nja_exit_hook* hook = (nja_exit_hook*)hooks; hook;) { + nja_exit_hook* next = hook->next; + if (!nja_process_exiting) hook->function(hook->argument); + free(hook); + hook = next; + } +} + +static INIT_ONCE nja_exit_once = INIT_ONCE_STATIC_INIT; + +static BOOL CALLBACK nja_init_exit_slot(PINIT_ONCE once, void* parameter, void** context) { + (void)once; (void)parameter; (void)context; + nja_exit_slot = FlsAlloc(nja_run_exit_hooks); + atexit(nja_mark_exiting); + return TRUE; +} + +static void nja_at_thread_exit(void (*function)(void*), void* argument) { + InitOnceExecuteOnce(&nja_exit_once, nja_init_exit_slot, NULL, NULL); + if (nja_exit_slot == FLS_OUT_OF_INDEXES) return; + nja_exit_hook* hook = (nja_exit_hook*)malloc(sizeof(nja_exit_hook)); + if (!hook) return; + hook->function = function; + hook->argument = argument; + hook->next = (nja_exit_hook*)FlsGetValue(nja_exit_slot); + FlsSetValue(nja_exit_slot, hook); +} +#else +extern int __cxa_thread_atexit_impl(void (*function)(void*), void* argument, void* dso); +extern void* __dso_handle; +static void nja_at_thread_exit(void (*function)(void*), void* argument) { + __cxa_thread_atexit_impl(function, argument, &__dso_handle); +} +#endif + +/* A recursive lock (the runtime's few shared structures) */ +static void* nja_lock_new(void) { +#ifdef _WIN32 + CRITICAL_SECTION* lock = (CRITICAL_SECTION*)malloc(sizeof(CRITICAL_SECTION)); + if (lock) InitializeCriticalSection(lock); +#else + pthread_mutex_t* lock = (pthread_mutex_t*)malloc(sizeof(pthread_mutex_t)); + if (lock) { + pthread_mutexattr_t attributes; + pthread_mutexattr_init(&attributes); + pthread_mutexattr_settype(&attributes, PTHREAD_MUTEX_RECURSIVE); + pthread_mutex_init(lock, &attributes); + pthread_mutexattr_destroy(&attributes); + } +#endif + return lock; +} + +static void nja_lock_lock(void* lock) { +#ifdef _WIN32 + EnterCriticalSection((CRITICAL_SECTION*)lock); +#else + pthread_mutex_lock((pthread_mutex_t*)lock); +#endif +} + +static void nja_lock_unlock(void* lock) { +#ifdef _WIN32 + LeaveCriticalSection((CRITICAL_SECTION*)lock); +#else + pthread_mutex_unlock((pthread_mutex_t*)lock); +#endif +} + +static void nja_lock_free(void* lock) { +#ifdef _WIN32 + DeleteCriticalSection((CRITICAL_SECTION*)lock); +#else + pthread_mutex_destroy((pthread_mutex_t*)lock); +#endif + free(lock); +} static void nja_detach(void* vm) { JavaVM* jvm = (JavaVM*)vm; @@ -27,65 +328,80 @@ static JNIEnv* nja_attach_current_thread(JavaVM* vm, const char* name) { if ((*vm)->GetEnv(vm, (void**)&env, JNI_VERSION_21) == JNI_OK) return env; JavaVMAttachArgs args = {JNI_VERSION_21, (char*)name, NULL}; if ((*vm)->AttachCurrentThreadAsDaemon(vm, (void**)&env, &args) != JNI_OK) return NULL; - _tlv_atexit(nja_detach, vm); + nja_at_thread_exit(nja_detach, vm); return env; } -typedef jint (*nja_create_vm_fn)(JavaVM**, void**, void*); +typedef jint (JNICALL *nja_create_vm_fn)(JavaVM**, void**, void*); -/* JNI_CreateJavaVM, when the JVM is linked in; JNI_ERR otherwise */ +/* JNI_CreateJavaVM, when the JVM is linked in or loaded; JNI_ERR otherwise */ static jint nja_create_java_vm(JavaVM** vm, void** env, void* args) { - nja_create_vm_fn create = (nja_create_vm_fn)dlsym(RTLD_DEFAULT, "JNI_CreateJavaVM"); + nja_create_vm_fn create = (nja_create_vm_fn)nja_symbol("JNI_CreateJavaVM"); return create ? create(vm, env, args) : JNI_ERR; } -/* A GraalVM native image (graal_isolate.h's API and NJA's entry points), when one is linked in */ +/* A GraalVM native image (graal_isolate.h's API and NJA's entry points), when one is linked in or loaded */ typedef int (*nja_graal_create_isolate_fn)(void*, void**, void**); typedef int (*nja_graal_attach_thread_fn)(void*, void**); typedef void* (*nja_graal_get_current_thread_fn)(void*); typedef int (*nja_graal_detach_thread_fn)(void*); typedef void* (*nja_graal_dispatch_fn)(void*, const void*, int, int*); -typedef void (*nja_graal_set_upcall_fn)(void*, void*); +typedef void (*nja_graal_free_fn)(void*, void*); +typedef void (*nja_graal_set_upcall_fn)(void*, void*, void*); static void* nja_graal_isolate; static nja_graal_dispatch_fn nja_graal_dispatch_entry; +static nja_graal_free_fn nja_graal_free_entry; +static nja_graal_get_current_thread_fn nja_graal_current_entry; +static nja_graal_attach_thread_fn nja_graal_attach_entry; +static nja_graal_detach_thread_fn nja_graal_detach_entry; static int nja_graal_available(void) { - return dlsym(RTLD_DEFAULT, "nja_graal_dispatch") != NULL; + return nja_symbol("nja_graal_dispatch") != NULL; } static void nja_graal_detach(void* thread) { - nja_graal_detach_thread_fn detach = (nja_graal_detach_thread_fn)dlsym(RTLD_DEFAULT, "graal_detach_thread"); - if (detach) detach(thread); + if (nja_graal_detach_entry) nja_graal_detach_entry(thread); } /* The calling thread's isolate thread, attaching it (detached when it exits) on its first call; NULL on failure */ static void* nja_graal_thread(void) { - nja_graal_get_current_thread_fn current = (nja_graal_get_current_thread_fn)dlsym(RTLD_DEFAULT, "graal_get_current_thread"); - void* thread = current(nja_graal_isolate); + void* thread = nja_graal_current_entry(nja_graal_isolate); if (thread) return thread; - nja_graal_attach_thread_fn attach = (nja_graal_attach_thread_fn)dlsym(RTLD_DEFAULT, "graal_attach_thread"); - if (attach(nja_graal_isolate, &thread) != 0) return NULL; - _tlv_atexit(nja_graal_detach, thread); + if (nja_graal_attach_entry(nja_graal_isolate, &thread) != 0) return NULL; + nja_at_thread_exit(nja_graal_detach, thread); return thread; } +/* The app's buffers (its callbacks' answers) are freed by its own C library: on Windows, the image has another */ +static void nja_graal_release(void* buffer) { free(buffer); } + /* Creates the isolate (the calling thread attached to it) and gives it the app's callback entry; 0 on success */ static int nja_graal_start(void* upcall) { - nja_graal_create_isolate_fn create = (nja_graal_create_isolate_fn)dlsym(RTLD_DEFAULT, "graal_create_isolate"); - nja_graal_set_upcall_fn set_upcall = (nja_graal_set_upcall_fn)dlsym(RTLD_DEFAULT, "nja_graal_set_upcall"); - nja_graal_dispatch_entry = (nja_graal_dispatch_fn)dlsym(RTLD_DEFAULT, "nja_graal_dispatch"); - if (!create || !set_upcall || !nja_graal_dispatch_entry) return -1; + nja_graal_create_isolate_fn create = (nja_graal_create_isolate_fn)nja_symbol("graal_create_isolate"); + nja_graal_set_upcall_fn set_upcall = (nja_graal_set_upcall_fn)nja_symbol("nja_graal_set_upcall"); + nja_graal_dispatch_entry = (nja_graal_dispatch_fn)nja_symbol("nja_graal_dispatch"); + nja_graal_free_entry = (nja_graal_free_fn)nja_symbol("nja_graal_free"); + nja_graal_current_entry = (nja_graal_get_current_thread_fn)nja_symbol("graal_get_current_thread"); + nja_graal_attach_entry = (nja_graal_attach_thread_fn)nja_symbol("graal_attach_thread"); + nja_graal_detach_entry = (nja_graal_detach_thread_fn)nja_symbol("graal_detach_thread"); + if (!create || !set_upcall || !nja_graal_dispatch_entry || !nja_graal_free_entry || !nja_graal_current_entry || !nja_graal_attach_entry) return -1; void* thread = NULL; int result = create(NULL, &nja_graal_isolate, &thread); if (result != 0) return result; - set_upcall(thread, upcall); + set_upcall(thread, upcall, (void*)nja_graal_release); return 0; } -/* Serves a call on the calling thread: the reply (to free), its length in reply_length; NULL if it can't attach */ +/* Serves a call on the calling thread: the reply (to free with nja_graal_free_reply), its length in reply_length; + * NULL if it can't attach */ static void* nja_graal_call(const void* message, int length, int* reply_length) { void* thread = nja_graal_thread(); if (!thread) return NULL; return nja_graal_dispatch_entry(thread, message, length, reply_length); } + +/* Frees a reply of the image, with the image's own C library */ +static void nja_graal_free_reply(void* reply) { + nja_graal_free_entry(nja_graal_current_entry(nja_graal_isolate), reply); +} diff --git a/runtime/client/src/iosMain/kotlin/dev/nucleusframework/nja/Platform.ios.kt b/runtime/client/src/nativeMain/kotlin/dev/nucleusframework/nja/Platform.native.kt similarity index 58% rename from runtime/client/src/iosMain/kotlin/dev/nucleusframework/nja/Platform.ios.kt rename to runtime/client/src/nativeMain/kotlin/dev/nucleusframework/nja/Platform.native.kt index 8ef3863..f50dac4 100644 --- a/runtime/client/src/iosMain/kotlin/dev/nucleusframework/nja/Platform.ios.kt +++ b/runtime/client/src/nativeMain/kotlin/dev/nucleusframework/nja/Platform.native.kt @@ -15,15 +15,28 @@ import dev.nucleusframework.nja.jni.jmethodID import dev.nucleusframework.nja.jni.jvalue import dev.nucleusframework.nja.jni.nja_attach_current_thread import dev.nucleusframework.nja.jni.nja_create_java_vm +import dev.nucleusframework.nja.jni.nja_executable_path +import dev.nucleusframework.nja.jni.nja_file_kind +import dev.nucleusframework.nja.jni.nja_getenv import dev.nucleusframework.nja.jni.nja_graal_available import dev.nucleusframework.nja.jni.nja_graal_call +import dev.nucleusframework.nja.jni.nja_graal_free_reply import dev.nucleusframework.nja.jni.nja_graal_start +import dev.nucleusframework.nja.jni.nja_list_directory +import dev.nucleusframework.nja.jni.nja_load_runtime +import dev.nucleusframework.nja.jni.nja_lock_free +import dev.nucleusframework.nja.jni.nja_lock_lock +import dev.nucleusframework.nja.jni.nja_lock_new +import dev.nucleusframework.nja.jni.nja_lock_unlock +import dev.nucleusframework.nja.jni.nja_read_file +import dev.nucleusframework.nja.jni.nja_symbol +import kotlinx.cinterop.ByteVar +import kotlinx.cinterop.COpaquePointer import kotlinx.cinterop.COpaquePointerVar import kotlinx.cinterop.CPointer -import kotlinx.cinterop.ByteVar +import kotlinx.cinterop.CPointerVar import kotlinx.cinterop.ExperimentalForeignApi import kotlinx.cinterop.IntVar -import kotlinx.cinterop.readBytes import kotlinx.cinterop.addressOf import kotlinx.cinterop.alloc import kotlinx.cinterop.allocArray @@ -33,16 +46,12 @@ import kotlinx.cinterop.invoke import kotlinx.cinterop.memScoped import kotlinx.cinterop.pointed import kotlinx.cinterop.ptr +import kotlinx.cinterop.readBytes import kotlinx.cinterop.reinterpret import kotlinx.cinterop.staticCFunction +import kotlinx.cinterop.toKString import kotlinx.cinterop.usePinned import kotlinx.cinterop.value -import platform.Foundation.NSBundle -import platform.Foundation.NSFileManager -import platform.Foundation.NSRecursiveLock -import platform.Foundation.NSString -import platform.Foundation.NSUTF8StringEncoding -import platform.Foundation.stringWithContentsOfFile import platform.posix.free import platform.posix.malloc import platform.posix.memcpy @@ -51,12 +60,17 @@ import kotlin.native.concurrent.ObsoleteWorkersApi import kotlin.native.concurrent.ThreadLocal import kotlin.native.concurrent.TransferMode import kotlin.native.concurrent.Worker +import kotlin.native.ref.Cleaner import kotlin.native.ref.createCleaner internal actual class NjaLock actual constructor() { - private val lock = NSRecursiveLock() - actual fun lock() = lock.lock() - actual fun unlock() = lock.unlock() + private val lock: COpaquePointer = nja_lock_new() ?: throw OutOfMemoryError() + + @Suppress("unused") + private val cleaner: Cleaner = createCleaner(lock) { nja_lock_free(it) } + + actual fun lock() = nja_lock_lock(lock) + actual fun unlock() = nja_lock_unlock(lock) } @ThreadLocal @@ -75,13 +89,102 @@ internal actual fun startDaemon(name: String, body: () -> Unit) { internal actual fun createCleaner(ref: JvmRef): Any = createCleaner(ref) { it.close() } -internal actual fun startTransport(): Transport = if (nja_graal_available() != 0) IosGraal.apply { start() } else IosJvm.apply { start() } +/** + * The runtime: linked into the binary (iOS), or a shared library loaded from the runtime's directory (macOS, Linux, + * Windows): the façades' native image if it is there, else a JDK's JVM. + */ +internal actual fun startTransport(): Transport { + if (nja_graal_available() != 0) return NativeGraal.apply { start() } + if (nja_symbol("JNI_CreateJavaVM") == null) { + val image = "${RuntimeFiles.directory}/${RuntimeFiles.imageLibrary}" + if (RuntimeFiles.isFile(image)) { + RuntimeFiles.load(image, null) + return NativeGraal.apply { start() } + } + val javaHome = RuntimeFiles.javaHome() + RuntimeFiles.load("$javaHome/${RuntimeFiles.jvmLibrary}", if (RuntimeFiles.isWindows) "$javaHome/bin" else null) + } + return NativeJvm.apply { start() } +} + +/** + * Where the runtime is: `NJA_HOME`, or the `nja` directory next to the executable (an iOS app's bundle: the + * executable is at its root). There, the façades' native image (`libnja.dylib`, `libnja.so`, `nja.dll`), or the JVM's + * class path (`classpath/`), options (`jvm.options`) and, optionally, java.home (`runtime/`, else `JAVA_HOME`'s). + */ +private object RuntimeFiles { + val isWindows = Platform.osFamily == OsFamily.WINDOWS + + val directory: String by lazy { + getenv("NJA_HOME") ?: run { + val executable = nja_executable_path()?.let { path -> path.toKString().also { free(path) } } + ?: error("NJA: can't find the executable's path") + "${executable.substring(0, executable.lastIndexOfAny(charArrayOf('/', '\\')))}/nja" + } + } + + val imageLibrary = when (Platform.osFamily) { + OsFamily.MACOSX -> "libnja.dylib" + OsFamily.WINDOWS -> "nja.dll" + else -> "libnja.so" + } + + val jvmLibrary = when (Platform.osFamily) { + OsFamily.MACOSX -> "lib/server/libjvm.dylib" + OsFamily.WINDOWS -> "bin/server/jvm.dll" + else -> "lib/server/libjvm.so" + } + + val classPathSeparator = if (isWindows) ";" else ":" + + fun javaHome(): String { + val bundled = "$directory/runtime" + if (nja_file_kind(bundled) == 2) return bundled + return getenv("JAVA_HOME") ?: error( + "NJA: no runtime in $directory: neither the façades' native image ($imageLibrary) nor a JVM (runtime/, or JAVA_HOME)", + ) + } + + fun isFile(path: String) = nja_file_kind(path) == 1 + + fun load(path: String, dependencies: String?) { + val failure = nja_load_runtime(path, dependencies) + check(failure == null) { "NJA: can't load $path: ${failure?.toKString()}" } + } + + fun list(path: String): List { + val names = nja_list_directory(path) ?: return emptyList() + try { + return names.toKString().lines().filter { it.isNotEmpty() } + } finally { + free(names) + } + } + + fun read(path: String): String? { + val content = nja_read_file(path) ?: return null + try { + return content.toKString() + } finally { + free(content) + } + } + + private fun getenv(name: String): String? { + val value = nja_getenv(name) ?: return null + try { + return value.toKString().takeIf { it.isNotEmpty() } + } finally { + free(value) + } + } +} /** - * The façades compiled into a GraalVM native image, linked into the app: the app's threads call its entry points, - * attached to its isolate on their first call, and it calls the app back on the same thread. + * The façades compiled into a GraalVM native image, linked into the app or loaded: the app's threads call its entry + * points, attached to its isolate on their first call, and it calls the app back on the same thread. */ -private object IosGraal : Transport { +private object NativeGraal : Transport { fun start() { val result = nja_graal_start(staticCFunction(::graalUpcall)) check(result == 0) { "NJA: the native image's isolate failed to start: $result" } @@ -94,7 +197,7 @@ private object IosGraal : Transport { try { reply.reinterpret().readBytes(replyLength.value) } finally { - free(reply) + nja_graal_free_reply(reply) } } } @@ -109,24 +212,22 @@ private fun graalUpcall(request: CPointer?, length: Int, answerLength: } /** - * The JVM (jdk-mobile's Zero, linked into the app) in the app's process: the app's threads call it through JNI, - * attached on their first call. Its java.home is `/lib` (the VM sets it itself), the façades' class path - * `/nja/classpath`. + * The JVM in the app's process: jdk-mobile's Zero linked into an iOS app, or a JDK's libjvm loaded on the desktop. The + * app's threads call it through JNI, attached on their first call. Its java.home is the VM's own (an iOS app's + * `/lib`, the JDK's), the façades' class path the runtime directory's `classpath/`. */ -private object IosJvm : Transport { - private const val LINK_CLASS = "dev/nucleusframework/nja/server/IosLink" +private object NativeJvm : Transport { + private const val LINK_CLASS = "dev/nucleusframework/nja/server/JniLink" private var vm: CPointer? = null private var linkClass: jclass? = null private var dispatch: jmethodID? = null fun start() { - val bundle = NSBundle.mainBundle.bundlePath - val classPathDir = "$bundle/nja/classpath" - @Suppress("UNCHECKED_CAST") - val jars = (NSFileManager.defaultManager.contentsOfDirectoryAtPath(classPathDir, null) as? List).orEmpty() - .filter { it.endsWith(".jar") }.sorted().joinToString(":") { "$classPathDir/$it" } - val options = listOf("-Djava.class.path=$jars") + readOptions("$bundle/nja/jvm.options") + val classPathDir = "${RuntimeFiles.directory}/classpath" + val jars = RuntimeFiles.list(classPathDir).filter { it.endsWith(".jar") }.sorted() + .joinToString(RuntimeFiles.classPathSeparator) { "$classPathDir/$it" } + val options = listOf("-Djava.class.path=$jars") + readOptions("${RuntimeFiles.directory}/jvm.options") memScoped { val vmOptions = allocArray(options.size) options.forEachIndexed { i, option -> vmOptions[i].optionString = option.cstr.ptr } @@ -135,7 +236,7 @@ private object IosJvm : Transport { args.nOptions = options.size args.options = vmOptions args.ignoreUnrecognized = 0u - val vmOut = alloc>() + val vmOut = alloc>() val envOut = alloc() val result = nja_create_java_vm(vmOut.ptr, envOut.ptr, args.ptr) check(result == JNI_OK) { "NJA: JNI_CreateJavaVM failed: $result" } @@ -152,15 +253,13 @@ private object IosJvm : Transport { methods[0].fnPtr = staticCFunction(::upcall) check(fns.RegisterNatives!!(env, linkClass, methods, 1) == JNI_OK) { "NJA: can't register the upcall" } dispatch = fns.GetStaticMethodID!!(env, linkClass, "dispatch".cstr.ptr, "([B)[B".cstr.ptr) - checkException(env, "NJA: IosLink.dispatch is missing") + checkException(env, "NJA: JniLink.dispatch is missing") fns.DeleteLocalRef!!(env, local) } } - private fun readOptions(path: String): List { - val text = NSString.stringWithContentsOfFile(path, NSUTF8StringEncoding, null) ?: return emptyList() - return text.lines().map { it.trim() }.filter { it.isNotEmpty() && !it.startsWith("#") } - } + private fun readOptions(path: String): List = + RuntimeFiles.read(path).orEmpty().lines().map { it.trim() }.filter { it.isNotEmpty() && !it.startsWith("#") } /** This thread's JNIEnv, attaching it (as a daemon, detached when it ends) on its first call. */ fun env(): CPointer { @@ -209,7 +308,7 @@ private fun toByteArray(env: CPointer, array: jbyteArray?): ByteArray return bytes } -/** IosLink.upcall: the JVM calls one of the app's callbacks, on the thread of the call that passed it. */ +/** JniLink.upcall: the JVM calls one of the app's callbacks, on the thread of the call that passed it. */ private fun upcall(env: CPointer?, @Suppress("UNUSED_PARAMETER") cls: jclass?, request: jbyteArray?): jbyteArray? { val e = env!! val fns = e.pointed.value!!.pointed diff --git a/runtime/server/src/main/java/dev/nucleusframework/nja/server/GraalLink.java b/runtime/server/src/main/java/dev/nucleusframework/nja/server/GraalLink.java index 8c6fcfb..b6e7d58 100644 --- a/runtime/server/src/main/java/dev/nucleusframework/nja/server/GraalLink.java +++ b/runtime/server/src/main/java/dev/nucleusframework/nja/server/GraalLink.java @@ -1,7 +1,6 @@ package dev.nucleusframework.nja.server; import org.graalvm.nativeimage.IsolateThread; -import org.graalvm.nativeimage.StackValue; import org.graalvm.nativeimage.UnmanagedMemory; import org.graalvm.nativeimage.c.function.CEntryPoint; import org.graalvm.nativeimage.c.function.CFunctionPointer; @@ -13,7 +12,10 @@ /** * A GraalVM native image (the façades compiled ahead of time, linked into the app): the app calls its entry points on * its own threads, attached to the image's isolate, and the image calls the app back through a function pointer, on - * the same thread. Messages are buffers of the C heap: each side frees the ones it receives. + * the same thread. Messages are buffers of the C heap, freed by the side that allocated them (on Windows the image's C + * library isn't the app's): the app frees the image's replies through {@code nja_graal_free}, the image the app's + * answers through the function it was given. No StackValue: it throws on a virtual thread, which a façade may invoke a + * callback from. */ public final class GraalLink { private GraalLink() {} @@ -24,13 +26,27 @@ interface Upcall extends CFunctionPointer { CCharPointer invoke(CCharPointer request, int length, CIntPointer answerLength); } + /** Frees a buffer of the app (an answer). */ + interface Release extends CFunctionPointer { + @InvokeCFunctionPointer + void invoke(CCharPointer buffer); + } + private static Upcall upcall; + private static Release release; private static final Link LINK = GraalLink::exchange; @CEntryPoint(name = "nja_graal_set_upcall") - static void setUpcall(IsolateThread thread, Upcall function) { + static void setUpcall(IsolateThread thread, Upcall function, Release releaseFunction) { upcall = function; + release = releaseFunction; + } + + /** Frees a reply of the image. */ + @CEntryPoint(name = "nja_graal_free") + static void free(IsolateThread thread, CCharPointer reply) { + UnmanagedMemory.free(reply); } /** Serves a call of the app: its reply, malloc'ed, its length written to [replyLength]. */ @@ -43,17 +59,21 @@ static CCharPointer dispatch(IsolateThread thread, CCharPointer message, int len private static byte[] exchange(byte[] request) { CCharPointer buffer = toBuffer(request); - CIntPointer answerLength = StackValue.get(CIntPointer.class); - CCharPointer answer; - try { - answer = upcall.invoke(buffer, request.length, answerLength); - } finally { - UnmanagedMemory.free(buffer); - } + CIntPointer answerLength = UnmanagedMemory.malloc(Integer.BYTES); try { - return toBytes(answer, answerLength.read()); + CCharPointer answer; + try { + answer = upcall.invoke(buffer, request.length, answerLength); + } finally { + UnmanagedMemory.free(buffer); + } + try { + return toBytes(answer, answerLength.read()); + } finally { + release.invoke(answer); + } } finally { - UnmanagedMemory.free(answer); + UnmanagedMemory.free(answerLength); } } diff --git a/runtime/server/src/main/java/dev/nucleusframework/nja/server/IosLink.java b/runtime/server/src/main/java/dev/nucleusframework/nja/server/JniLink.java similarity index 52% rename from runtime/server/src/main/java/dev/nucleusframework/nja/server/IosLink.java rename to runtime/server/src/main/java/dev/nucleusframework/nja/server/JniLink.java index 8211df5..dc3efe3 100644 --- a/runtime/server/src/main/java/dev/nucleusframework/nja/server/IosLink.java +++ b/runtime/server/src/main/java/dev/nucleusframework/nja/server/JniLink.java @@ -1,13 +1,13 @@ package dev.nucleusframework.nja.server; /** - * iOS: the JVM runs in the app's process and its threads (Kotlin/Native ones, attached to it), so calls and callbacks - * are plain JNI calls on the calling thread. + * Kotlin/Native (iOS, macOS, Linux, Windows): the JVM runs in the app's process and its threads (Kotlin/Native ones, + * attached to it), so calls and callbacks are plain JNI calls on the calling thread. */ -public final class IosLink { - private IosLink() {} +public final class JniLink { + private JniLink() {} - private static final Link LINK = IosLink::upcall; + private static final Link LINK = JniLink::upcall; /** Serves a call of the app. */ static byte[] dispatch(byte[] message) { From 2a058b5440b50ec1e0ed89173e37daf72d229d30 Mon Sep 17 00:00:00 2001 From: Elie Gambache Date: Mon, 16 Nov 2026 22:27:12 +0200 Subject: [PATCH 2/3] CI: qemu-user on Ubuntu 26.04 (no qemu-user-static there) --- .github/workflows/test-graalvm-android.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test-graalvm-android.yml b/.github/workflows/test-graalvm-android.yml index 6b10836..a8c53d1 100644 --- a/.github/workflows/test-graalvm-android.yml +++ b/.github/workflows/test-graalvm-android.yml @@ -22,7 +22,9 @@ jobs: (yes || true) | "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "ndk;27.2.12479018" > /dev/null || true echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/27.2.12479018" >> "$GITHUB_ENV" # native-image's C queries for arm64 run on this x64 runner through qemu-user - sudo apt-get update -q && sudo apt-get install -yq qemu-user-static binfmt-support + # (qemu-user-static until Ubuntu 25.10; qemu-user-binfmt from 26.04, whose qemu-user is static) + sudo apt-get update -q + sudo apt-get install -yq qemu-user-static binfmt-support || sudo apt-get install -yq qemu-user-binfmt - name: Test APKs env: GITHUB_TOKEN: ${{ github.token }} From 107af2d2dcbba68c25c7763ff908aac3b9bcf058 Mon Sep 17 00:00:00 2001 From: Elie Gambache Date: Mon, 16 Nov 2026 22:39:59 +0200 Subject: [PATCH 3/3] Windows checkouts' CRLF sources parsed; linuxArm64 linked on x64 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Kotlin PSI wants \n: a façade checked out on Windows (\r\n) lost members in the generated client. Kotlin/Native doesn't run on Linux arm64 hosts: CI links linuxArm64's tests on Linux x64, and the README says how its image ships. --- .github/workflows/test-desktop.yml | 8 ++++---- README.md | 3 +++ .../nja/plugin/analysis/PsiSourceParser.kt | 3 ++- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.github/workflows/test-desktop.yml b/.github/workflows/test-desktop.yml index 91f865c..9abd936 100644 --- a/.github/workflows/test-desktop.yml +++ b/.github/workflows/test-desktop.yml @@ -1,7 +1,8 @@ name: Kotlin/Native desktop # The example's suites in Kotlin/Native executables on macOS, Linux and Windows, each on its own host (a native image -# builds on its own platform): with the façades in a GraalVM native image (the default) and in a JDK's JVM +# builds on its own platform): with the façades in a GraalVM native image (the default) and in a JDK's JVM. Kotlin/Native +# doesn't run on Linux arm64 hosts: linuxArm64's test executable is linked on Linux x64, not run on: pull_request: workflow_dispatch: @@ -13,8 +14,7 @@ jobs: matrix: host: - { os: macos-15, target: macosArm64 } - - { os: ubuntu-latest, target: linuxX64 } - - { os: ubuntu-24.04-arm, target: linuxArm64 } + - { os: ubuntu-latest, target: linuxX64, also: linkDebugTestLinuxArm64 } - { os: windows-latest, target: mingwX64 } runtime: [GRAALVM, JVM] runs-on: ${{ matrix.host.os }} @@ -33,7 +33,7 @@ jobs: shell: bash env: GITHUB_TOKEN: ${{ github.token }} - run: ./gradlew :examples:calculator:${{ matrix.host.target }}Test -Pnja.runtime=${{ matrix.runtime }} --stacktrace + run: ./gradlew :examples:calculator:${{ matrix.host.target }}Test ${{ matrix.host.also && format(':examples:calculator:{0}', matrix.host.also) || '' }} -Pnja.runtime=${{ matrix.runtime }} --stacktrace - uses: actions/upload-artifact@v4 if: always() with: diff --git a/README.md b/README.md index 7fb6bcf..adf1937 100644 --- a/README.md +++ b/README.md @@ -154,6 +154,9 @@ runtime: they load it when the app first calls a façade, from the `nja` directo - **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 `linuxArm64` binaries are always cross-compiled. + With `GRAALVM`, build the native image on a Linux arm64 machine (`native-image --shared` of the façades' class path, + as `njaNativeLibrary` does) and ship it in `nja/`; the `JVM` runtime 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 set `NJA_HOME`. A shared library or framework the app links finds `nja/` next to the executable that loaded it. diff --git a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/analysis/PsiSourceParser.kt b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/analysis/PsiSourceParser.kt index 533ac52..0e1170f 100644 --- a/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/analysis/PsiSourceParser.kt +++ b/plugin-build/plugin/src/main/kotlin/dev/nucleusframework/nja/plugin/analysis/PsiSourceParser.kt @@ -71,7 +71,8 @@ class PsiSourceParser { // Phase 1: prescan type declarations (reused as long as the content is unchanged) val entries = sources.distinctBy { it.file.absoluteFile }.map { source -> val key = source.file.absolutePath - val text = source.file.readText() + // PSI wants \n: a Windows checkout's sources have \r\n + val text = source.file.readText().replace("\r\n", "\n") val hash = sha256(text.toByteArray()) val cached = previous[key]?.takeIf { it.contentHash == hash && it.isCommon == source.isCommon } Entry(source, key, text, hash, cached, cached?.prescan ?: prescan(psi.parse(source.file, text)))