# RoastVM

A Java Virtual Machine (JVM) implementation written in Rust.

## Overview

RoastVM is an educational/experimental JVM implementation that executes Java bytecode. It supports class file parsing,
bytecode interpretation, JNI native methods, and includes a boot image system for loading the Java standard library.

## Features

- **Class File Parsing** - Full `.class` file support using deku for binary parsing
- **Bytecode Interpreter** - 200+ JVM instructions implemented
- **Object Model** - Objects, arrays, monitors, and string interning
- **JNI Support** - 250+ JNI functions for native method integration
- **Boot Image** - Load JDK classes from 7z module archives
- **Native FFI** - Dynamic library loading via libffi

## Project Structure

```
roast-vm/
├── crates/
│   ├── core/                    # Main VM implementation
│   │   └── src/
│   │       ├── main.rs          # Entry point
│   │       ├── vm.rs            # VM controller
│   │       ├── thread.rs        # Thread execution
│   │       ├── class_loader.rs  # Class loading
│   │       ├── bimage.rs        # Boot image reader
│   │       ├── frame/           # Stack frames & interpreter
│   │       ├── class_file/      # Class file parser
│   │       ├── objects/         # Object/array model
│   │       └── native/          # JNI infrastructure
│   │
│   └── roast-vm-sys/            # Native methods (cdylib)
│       └── src/                 # JNI implementations
│
├── lib/                         # Boot image location
├── data/                        # Default classpath
└── docs/                        # Detailed documentation
```

## Documentation

Detailed implementation docs are in the `docs/` folder:

- [Class File Parsing](docs/class-file-parsing.md) - Binary format, constant pool, attributes
- [Frame & Interpreter](docs/frame-interpreter.md) - Stack frames, opcode dispatch
- [Object Management](docs/object-management.md) - Objects, arrays, monitors
- [JNI](docs/jni.md) - JNIEnv structure, native invocation
- [Native/FFI](docs/native-ffi.md) - Library loading, libffi integration
- [roast-vm-sys](docs/roast-vm-sys.md) - Native method implementations
- [Class Loading](docs/class-loading.md) - Boot image, classpath, RuntimeClass

## Building

```bash
cargo build
cargo build --release
cargo test
```

## Running

```bash
# Run with default classpath (./data)
cargo run

# Run with custom classpath
cargo run -- /path/to/classes

# With debug logging
RUST_LOG=debug cargo run
```

## Dependencies

| Crate                                                 | Purpose                   |
|-------------------------------------------------------|---------------------------|
| [deku](https://crates.io/crates/deku)                 | Binary class file parsing |
| [dashmap](https://crates.io/crates/dashmap)           | Concurrent maps           |
| [jni](https://crates.io/crates/jni)                   | JNI type definitions      |
| [libloading](https://crates.io/crates/libloading)     | Dynamic library loading   |
| [libffi](https://crates.io/crates/libffi)             | Native function calls     |
| [sevenz-rust2](https://crates.io/crates/sevenz-rust2) | Boot image archives       |
| [parking_lot](https://crates.io/crates/parking_lot)   | Synchronization           |

## Status

Early development (v0.2.0). Core class loading, bytecode execution, and JNI are functional. Exception handling and GC
are in progress.

**Vendor**: infernap12

## References

- [JVM Specification](https://docs.oracle.com/javase/specs/jvms/se25/html/index.html)
- [JNI Specification](https://docs.oracle.com/en/java/javase/25/docs/specs/jni/index.html)