rjvm

rjvm is a small jvm-in-rust focused on clear structure and correct-enough behavior for trusted java 7 bytecode.

the project is intentionally minimal:

• interpreter only (no jit)
• stable handle-based java references
• compact runtime model for objects, arrays, frames, and exceptions
• tiny intrinsic surface for io and string operations used by fixtures

workspace overview

• classfile/: parses .class files (constant pool, methods, code attributes, exception tables)
• loader/: loads classes from classpath directories and jar files
• runtime/: value model, heap/object/array storage, and field keys
• interpreter/: bytecode execution, method invocation, exceptions, class init, intrinsics, and gc
• rjvm/: cli entrypoint and argument handling
• mini-rt/: tiny java runtime jar experiments and build script
• fixtures/: java programs used as integration fixtures
• tests/run_fixtures.sh: compiles fixtures and validates rjvm output

execution model

rjvm starts from a resolved main class and executes:

• public static void main(String[] args)
• or public static int main()

class loading is classpath/jar based. at startup, rjvm builds a class repository from available class files and resolves method/field references at execution time.

class initialization is tracked per class. active use sites (new, getstatic, putstatic, invokestatic) trigger <clinit> once for that class.

command line

rjvm --cp <paths> <mainclass> [args...]
rjvm --jar <app.jar> [args...]
rjvm --jar <app.jar> --main <mainclass> [args...]

notes:

• class names can be passed with dots or slashes; cli normalizes to jvm binary names.
• for --jar, main-class is read from meta-inf/manifest.mf when present.

build and test

cargo test
./tests/run_fixtures.sh

manual examples

compile and run the args fixture:

javac -source 7 -target 7 -d fixtures/entry_args/build fixtures/entry_args/src/*.java
cargo run -p rjvm -- --cp fixtures/entry_args/build Main alpha beta gamma

compile and run the json parser stress fixture:

javac -source 7 -target 7 -d fixtures/stress_json_java/build fixtures/stress_json_java/src/*.java
cargo run -p rjvm -- --cp fixtures/stress_json_java/build Main "$(cat fixtures/stress_json_java/run_args.txt)"
# or your own json
cargo run -p rjvm -- --cp fixtures/stress_json_java/build Main '{"a": {"b": [1,2, [55]]}, "c": null}"

design notes

• java references are represented as stable indices/handles, not rust references.
• gc is non-moving mark-sweep to keep handles stable.
• the fixture set is the compatibility target. this is not a full openjdk-compatible vm. i’m not that far gone :)
• code is organized so semantics are explicit over clever.

---

have fun!