JVMRS

A Java Virtual Machine implementation in Rust, featuring Cranelift JIT, AOT to native object files, generational GC, and multiple compilation backends.

Why JVMRS?

Compared to HotSpot, OpenJ9, and GraalVM, jvmrs differentiates with Rust-native design and unique capabilities:

Use jvmrs when you need: embeddable JVM, Java→WASM, Rust/Java interop, AOT to .o files, or a Rust-based JVM for research and tooling.

Installation

Add to your Cargo.toml:

[dependencies]
jvmrs = "0.1"

For optional features (LLVM IR, WebAssembly, etc.):

[dependencies]
jvmrs = { version = "0.1", features = ["wasm"] }

Quick Start

# Clone and run
git clone https://github.com/yingkitw/jvmrs
cd jvmrs

# Run example classes (examples/ contains precompiled .class files)
cargo run Minimal
cargo run TestGetStatic
cargo run TestLdc

# Or compile your own Java and run
javac -d examples examples/HelloWorld.java
cargo run HelloWorld

Usage

Run a class

# Run main class (resolves via classpath)
cargo run HelloWorld
cargo run Calculator
cargo run SimpleMath

CLI options

Environment variables

Examples

# Run with default JIT
cargo run Calculator

# Run without JIT
cargo run -- --no-jit Calculator

# AOT compile to object file
cargo run -- --aot output.o HelloWorld

# Emit LLVM IR (requires: cargo build --features llvm)
cargo run --features llvm -- --llvm Calculator > calc.ll

# Custom JIT threshold
cargo run -- --jit-threshold 50 SimpleMath

Examples

Example Java programs in examples/:

HelloWorld.java

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
        int a = 5, b = 10, c = a + b;
        System.out.println("5 + 10 = " + c);
    }
}

Calculator.java

public class Calculator {
    public static int add(int a, int b) { return a + b; }
    public static int subtract(int a, int b) { return a - b; }
    public static int multiply(int a, int b) { return a * b; }
    public static float divide(float a, float b) { return a / b; }
    
    public static void main(String[] args) {
        int x = 20, y = 8;
        System.out.println("x + y = " + add(x, y));
        System.out.println("x - y = " + subtract(x, y));
        System.out.println("x * y = " + multiply(x, y));
        System.out.println("x / y = " + divide(x, y));
    }
}

SimpleMath.java

public class SimpleMath {
    public static int add(int a, int b) { return a + b; }
    public static void main(String[] args) {
        int z = add(5, 10);
        System.out.println("5 + 10 = " + z);
    }
}

Running the examples

# Precompiled examples (Minimal, TestGetStatic, TestLdc)
cargo run Minimal
cargo run TestGetStatic
cargo run TestLdc

# Or compile and run your own
javac -d examples examples/HelloWorld.java examples/Calculator.java examples/SimpleMath.java
cargo run HelloWorld    # Hello, World! / 5 + 10 = 15
cargo run Calculator   # Arithmetic demo
cargo run SimpleMath   # 5 + 10 = 15

Rust calling Java (polyglot)

cargo run --example rust_calling_java

Interactive REPL

# Start interactive REPL (requires repl feature)
cargo run -- --repl

# Example REPL commands:
jvmrs> load java/lang/String
jvmrs> class java/lang/String
jvmrs> exec java/lang/String valueOf 42
jvmrs> help
jvmrs> exit

REPL Commands

Features

Core

• Class file parser, constant pool, stack-based interpreter
• Generational GC with parallel sweep
• Arrays, strings, inheritance, interfaces
• Inline Caching – Optimized virtual method dispatch (3-5x faster)
• Thread-Local Allocation (TLAB) – Fast, lock-free object allocation (2-3x faster)
• Compressed Oops – 16-bit encoded references for memory-constrained environments (50% per-slot savings)
• Reflection – Interpreter::new_instance, get_field_value, set_field_value, invoke_method, get_object_class
• Serialization – Binary format for HeapObject and Value (JVRS format)
• Property-Based Tests – 30+ comprehensive property tests for correctness

Compilation

• Cranelift JIT – bytecode-to-native for hot methods
• Tiered compilation – interpreter → baseline → optimized
• AOT – compile to .o via cranelift-object
• LLVM IR (--features llvm) – export to LLVM
• WebAssembly (--features wasm) – emit WASM

Optional (feature-gated)

• ffi – C API for embedding
• interop – Java/Rust polyglot
• async – tokio async I/O
• simd – SIMD array ops
• truffle – GraalVM-style language API

Building

cargo build
cargo build --features llvm    # LLVM IR export
cargo build --features wasm    # WebAssembly backend

Testing

cargo test                        # 68+ unit tests
cargo test --doc                  # Doctests (extensions example)
cargo test --test property_tests    # Property-based tests (requires proptest feature)
cargo bench                       # Run comprehensive benchmark suite
cargo bench --bench instruction_benchmarks  # Specific benchmarks

Test Coverage

• Unit Tests: 68+ tests covering all core modules
• Property-Based Tests: 30+ tests verifying invariants across 20+ properties
• Benchmarks: Comprehensive suite covering 14 benchmark categories
• Integration Tests: End-to-end testing with example classes

Test Features

• Arithmetic operations (commutative, associative, identity)
• Bitwise operations (De Morgan's laws, idempotence)
• Array operations (length preservation, write/read)
• Stack operations (push/pop reversibility)
• String operations (concatenation associativity)
• GC correctness (live object preservation)
• Method invocation consistency
• Object identity and null handling

Documentation

• API Documentation
• ARCHITECTURE.md – Design and components
• IMPLEMENTATION_SUMMARY.md – Performance enhancements and features
• docs/api-reference.md – Complete API reference with examples
• docs/performance-tuning.md – Performance optimization guide
• docs/polyglot-programming.md – Java/Rust interop guide
• docs/competitive-differentiation.md – How JVMRS differs from other JVMs
• spec.md – Technical specification
• TODO.md – Roadmap

License

Licensed under either of MIT or Apache-2.0 at your option.