CratonVM

A Java Virtual Machine written in Rust, with a custom x86-64 JIT and an opt-in automatic GPU fast path for a documented subset of Java kernels.

CratonVM boots against a real JDK when one is present (JAVA_HOME, CRATONVM_JAVA_HOME, or java on PATH) and runs fully standalone when it isn't — its own Rust implementations of the Java standard library mean no JDK install, no rt.jar, one self-contained binary.

Highlights

• Custom x86-64 JIT — tiered compilation (interpreter → C1 → C2), OSR, LICM, bounds-check elimination, AVX2 SIMD, precise stack maps. Experimental AArch64 backend.
• Automatic GPU fast path — supported pure static array kernels can run on NVIDIA GPUs without API changes. Eligibility is intentionally narrow and unsupported shapes fall back to CPU (see below).
• Generational GC — young/old generations, card table, selective promotion. The moving/compacting (Cheney) young gen is the default, with CRATONVM_NO_MOVING_YOUNG as the compatibility opt-out; a cycle that cannot prove complete root coverage diverts to the non-moving sweep rather than relocating (see ARCHITECTURE.md). Opt-in region-based G1 (-XX:+UseG1GC).
• Real frameworks run — Spring, Spring Boot, Tomcat, Netty, Hibernate, Hibernate Reactive, Quarkus, H2 Database boot and pass large test suites.
• Rust implementation — Rust removes many ambient memory hazards, but the VM, JIT, GC, FFI, I/O, AWT, CUDA, and JFR contain reviewed and still-being- audited unsafe regions. See SECURITY.md.
• JNI & embedding — JNI Invocation API, a stable C-ABI library (libcratonvm), and a Rust facade (cratonvm-embed).
• Observability & hardening — Java Flight Recorder, bytecode verification, opt-in I/O confinement and network egress policy (docs/SECURITY_HARDENING.md).
• Provenance instrumentation (--jdk-only) — an internal diagnostic that makes every compatibility substitution a counted, attributed event, so the gap between "runs on CratonVM" and "runs on the real class bytes" is measurable rather than assumed. Not a supported runtime mode; --real-jdk stays the default (see below).

Performance

CPU, vs HotSpot JDK 25 C2 — same flags both sides, checksum-verified against HotSpot on every run (zero mismatches):

Two rows (Matrix, Sieve) are at parity with HotSpot C2. Full methodology, per-row footnotes (HotSpot's Sieve bimodality, the Fibonacci gap), and historical context: BENCHMARK.md.

GPU offload, vs HotSpot C2 and TornadoVM 4.0.1 (RTX 2060, N = 2²⁴, warm, full H2D+kernel+D2H round-trip, checksums bit-identical to HotSpot):

Ray tracer rows are 6 interleaved rounds each (arm order alternated per round to cancel drift), full H2D+kernel+D2H, checksums bit-identical to HotSpot; the 3840×2160 row is pooled over two independent 6-round passes (12 rounds total, craton faster in all 12) run 30 minutes apart, which agreed within noise. The kernel is the reduced proxy (bench-gpu/RayTracerKernel.java), documented in gpu/raytracer-vs-tornadovm-RESOLVED-20260821.md in the internal tree, not the full apps/TornadoVM-Ray-Tracer app (whose real kernel — reflections, soft shadows, a skybox — needs dynamic-length scene loops neither engine's analyzer admits yet). The margin over TornadoVM shrinks with resolution (2.5x → 2.2x → 2.0x → 1.85x, the last at 11520×6480 / 74.6M pixels, 6/6 rounds) as CratonVM's fixed per-launch cost advantage amortises away, leaving a smaller but still consistent per-pixel-throughput edge. Every frame from 160×120 to 11520×6480 is bit-identical to HotSpot's.

Unlike TornadoVM, the supported automatic path needs no @Parallel annotations or TaskGraph API — within a deliberately narrow eligibility subset, not a general promise that arbitrary Java runs on the GPU. Full results, extra sizes, and methodology: BENCHMARK.md and docs/gpu/README.md.

What to build on

Boots, runs, and passes large real-world test suites:

• Spring / Spring Boot
• Tomcat / Netty
• Hibernate / Hibernate Reactive
• H2 DB / PostgreSQL driver
• Apache Commons Math
• Bouncy Castle Java

Java Version Support

Quick Start

Build (Rust 1.80+):

cargo build --release -p cratonvm-cli

Compile and run a class:

javac HelloWorld.java
./target/release/cratonvm -cp . HelloWorld

Run a JAR:

./target/release/cratonvm --jar app.jar

Bigger heap, G1 collector, program arguments:

./target/release/cratonvm -Xmx4g -XX:+UseG1GC -cp "classes:lib/util.jar" com.example.Main arg1 arg2

Command-Line Reference

cratonvm [OPTIONS] <CLASS_NAME> [ARGS]...
cratonvm [OPTIONS] --jar <FILE.jar> [ARGS]...

Every command above is verified against the current binary. --gpu and the other GPU options require a --features gpu-driver build — see docs/gpu/README.md.

JDK-only mode (--jdk-only)

An internal diagnostic, not a supported runtime mode — --real-jdk remains the default. It asks the VM to treat real JDK class bytes as authoritative and report every compatibility substitution it would otherwise make silently, so it is expected to fail on programs that pass under the default. A/B a program to see what it depends on:

./target/release/cratonvm -cp . MyApp                                   # default: --real-jdk
./target/release/cratonvm --jdk-only --jdk-only-report report.json -cp . MyApp

Details: docs/jdk-only-migration.md (operator guide); the rest of the JDK-only docset is indexed from docs/README.md.

Limitations

• AWT/Swing are headless (no on-screen rendering); JavaFX is out of tree.
• Reflection and JNI cover the common paths; some edge cases (C-varargs JNI forms, full foreign-thread attach) are partial.
• Cryptography is best-effort and not constant-time everywhere — see docs/CRYPTO_STATUS.md.

Documentation

• Complete manual — installation, use, compatibility, security, performance, operations, embedding, architecture, contributing, and reference
• Documentation index — map of maintained standalone and manual references
• ARCHITECTURE.md — crate layout and subsystem design
• BENCHMARK.md — benchmark methodology and full results
• Performance tuning — measurement-first tuning workflow
• Deployment and operations — packaging, sizing, security boundaries, rollout, and rollback
• Incident response — crash/hang/OOM/wrong-result diagnostic runbook
• Runtime lifecycle and runtime contracts
• docs/GC.md — collectors, barriers, heap layout
• docs/JIT_OPTIMIZATION.md — the JIT optimization journey
• docs/gpu/README.md — GPU offload reference
• docs/EMBEDDING.md — embedding CratonVM in your application
• docs/SECURITY_HARDENING.md — sandboxing and hardening
• docs/CONFIG.md — configuration reference
• docs/jdk-only-migration.md — --jdk-only operator guide; the rest of the JDK-only docset is indexed from docs/README.md

Building & Testing

cargo build --release          # full workspace
cargo test --workspace         # unit + integration tests
bash regression-suite/run.sh   # fast HotSpot-differential regression suite

Contributing

See CONTRIBUTING.md. Architectural orientation lives in ARCHITECTURE.md; required merge signals are defined by release readiness and the CI workflows.

License

Apache-2.0 — see LICENSE. CratonVM is an independent implementation and is not derived from OpenJDK sources; see THIRD-PARTY-NOTICES.md and TRADEMARKS.md.