rusty-jvm

Introduction

This project is a Java Virtual Machine (JVM) implemented in Rust, built to run Java programs independently of existing JVMs. Everything related to Java is implemented from scratch. The current version executes Java bytecode in interpreted mode, with the introduction of a Just-In-Time (JIT) compiler identified as a future milestone. The next major objectives include the integration of garbage collection and support for multithreading.

Implemented Key Features

• 100% of actual opcodes (JVMS §6)
• Lambda Expressions (JLS §15.27)
• Static initialization (JVMS §5.5, implementation details)
• Polymorphic models (JLS §8.4.8)
• Single- and multi-dimensional arrays (JLS §10)
• Exceptions (JLS §11)
• Record Classes (JVMS §8.10)
• Type casting (JLS §5.5)
• Program arguments (JLS §12.1.4)
• Assertions (JLS §14.10)
• Dynamic Language Support (partially)
• Stream API (partially)
• Reflection (some features)
• java.io (partially)
• java.nio (partially)
• java.util.zip (partially)
• java.lang.System (most features)
• JAR-files loading and execution
• Shared libraries loading and execution (partially)
• Java Native Interface Functions (partially)

See integration tests for broader examples of supported Java features.

Architecture

rusty-jvm is structured around six high-level concerns:

graph TD
    CLI["CLI / Library API"]
    VM["JVM Bootstrap"]
    CL["Class Loader"]
    HEAP["Heap"]
    INTERP["Bytecode Interpreter"]
    JNI["JNI Bridge"]

    CLI --> VM
    VM --> CL & HEAP & INTERP
    INTERP --> CL & HEAP & JNI
    JNI --> CL & HEAP

Loading

See architecture.md for detailed diagrams covering the class-loading pipeline, heap memory model, execution loop, vtable dispatch, and JNI bridge.

Design Decisions

See design-decisions.md for a detailed description of the design decisions made in this project.

Sub-crates

The project is organised as a Cargo workspace. Components with well-defined, reusable APIs are published as independent crates:

Crate	Description
jclassfile	.class file parser
jdescriptor	JVM type-descriptor and method-signature parser
jimage-rs	Reader for JDK .jimage archive files
jniname	JNI name-mangling utilities

graph TD
    JVM["rusty-jvm"]
    JCF["jclassfile\n- class-file parser"]
    JD["jdescriptor\n- type-descriptor parser"]
    JI["jimage-rs\n- jimage-archive reader"]
    JN["jniname\n- JNI name-mangling"]

    JVM --> JCF & JD & JI & JN
    JN --> JD

Loading

Roadmap

The following milestones are planned in order:

1. Garbage Collection — a tracing GC to reclaim unreachable heap objects.
2. Multithreading — java.lang.Thread, synchronized, and the Java Memory Model.
3. JIT Compilation — profile-guided native code generation for hot methods.

Java Standard Library Classes

This project relies on standard library classes from the JDK 25 (LTS). To run the Java code, you must have JDK 25 (LTS) installed on your machine and ensure the JAVA_HOME environment variable is properly set.

Getting Started

Prerequisites

Ensure the following are set up:

• A machine running Windows, MacOS, or Linux
• Rust installed
• JDK 25 (LTS) installed with the JAVA_HOME environment variable set

Example Program: Count Fruits

Create a file named FruitCount.java with the following content:

import java.util.List;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;

public class FruitCount {
    public static void main(String[] args) {
        List<String> fruits = List.of("apple", "banana", "apple", "orange", "banana", "apple");

        Map<String, Long> counts = fruits.stream()
                .collect(Collectors.groupingBy(Function.identity(), Collectors.counting()));

        System.out.println(counts);
    }
}

Steps to Run

1. Compile the program using the Java compiler:

   javac FruitCount.java

2. Run it using rusty-jvm:

   cargo run -- FruitCount

License

rusty-jvm is licensed under the MIT License.

Contributing

Contributions are welcome! See CONTRIBUTING.md for how to build the project, add integration tests, and implement new native methods.