diff --git a/.github/workflows/test-desktop.yml b/.github/workflows/test-desktop.yml new file mode 100644 index 0000000..9abd936 --- /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. 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: + +jobs: + test: + strategy: + fail-fast: false + matrix: + host: + - { os: macos-15, target: macosArm64 } + - { os: ubuntu-latest, target: linuxX64, also: linkDebugTestLinuxArm64 } + - { 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 ${{ matrix.host.also && format(':examples:calculator:{0}', matrix.host.also) || '' }} -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/.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 }} diff --git a/README.md b/README.md index bf00709..adf1937 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,83 +79,128 @@ 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`). - -## What crosses the bridge - -The façade's public API, parsed from its sources with Kotlin PSI: `Int`, -`Long`, `Double`, `Float`, `Boolean`, `Byte`, `Short`, `String` (length-prefixed UTF-8: NUL included), `ByteArray`, -`IntArray`, `LongArray`, `FloatArray`, `DoubleArray`, enums (verbatim, bodies included), data classes (verbatim), sealed -value hierarchies (a sealed interface or class whose nested cases are all data classes or objects: verbatim, by value, -recursive ones included), classes (proxies, released on `close()` or when collected; an `AutoCloseable`'s `close()` -closes the JVM object, then releases it), default arguments (overloads: the JVM applies the defaults), open/abstract/sealed classes and interfaces (hierarchy mirrored, objects wrapped in their most specific -exported type), nested classes (`Outer_Inner`), companion objects, extension and top-level functions, nullable types, -`List`/`Set`/`Map` (nested), lambdas as parameters (callbacks, valid during the call, exceptions rethrown as themselves) -and as return values (JVM lambdas the app calls), `suspend` functions (cancellable both ways) and `Flow` (credit-based -backpressure). - -Private and internal declarations stay the JVM's, as does a constructor that is private, internal, or takes what can't -cross; a function whose parameters or result can't cross is left out. - -JVM exceptions arrive as `JvmException` (with the JVM class name, message and stack); exceptions an app callback throws -come back out of the call as themselves. A closed proxy fails with `IllegalStateException`; `close()` releases the JVM -object once the calls using it are done (receiver *and* arguments are leased). +- **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)). -## Tests +## GraalVM native images -`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. +`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. -```bash -./gradlew :examples:calculator:iosSimulatorArm64Test +```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") +} ``` -```bash -./gradlew :examples:calculator:connectedAndroidDeviceTest -``` +- **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. + +## Kotlin/Native on the desktop + +macOS (`macosArm64`, `macosX64`), Linux (`linuxX64`, `linuxArm64`) and Windows (`mingwX64`) binaries don't link the +runtime: they load it when the app first calls a façade, from the `nja` directory next to the executable, or from +`NJA_HOME` when it is set (a library embedded in another program): + +| Runtime | `nja/` holds | The plugin puts it there | +|---|---|---| +| `GRAALVM` | `libnja.dylib`, `libnja.so` or `nja.dll` | For executables and tests of the build host's target | +| `JVM` | `classpath/` (the façades and NJA's server), `jvm.options`, optionally `runtime/` (a JDK or a `jlink`ed runtime, Java 25+; else `JAVA_HOME`'s) | For all executables and tests; `runtime/` is yours to add | + +- **Cross-compiling**: Kotlin/Native builds Linux and Windows binaries on macOS, but native-image builds for its own + host only. An executable built for another platform gets no native image (a warning says so). Build it on its own OS, + or ship the library built there in its `nja/`. +- **Linux arm64**: Kotlin/Native doesn't run on Linux arm64 hosts, so `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. +- The binaries need nothing else: on Linux, `libdl` and `libpthread`, which the client's klib adds to their link. + +## The JVM runtime + +### How it works + +| | 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 | -```bash -./gradlew :examples:calculator:jvmTest -``` +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. -## Performance +**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*: -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 GraalVM native image (`GRAALVM`) runs at HotSpot's -speed on both: on a real app's Lucene search, 8× faster than Zero on iOS, and on par with Lucene patched for ART on -Android, at about its memory. +- **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 +### jdk-mobile -The JVM's runtimes are [jdk-mobile](https://github.com/NucleusFramework/openjdk-mobile)'s releases (from +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 { @@ -167,27 +210,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). @@ -205,62 +246,76 @@ 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 GraalVM native image (`GRAALVM`, +the default) runs at HotSpot's speed on both: on a real app's Lucene search, 8× faster than Zero on iOS, and on par with +Lucene patched for ART on Android, at about its memory. ## 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/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))) 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) {