infernap12/jvm-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Ammend README.md to reflect current status

Browse Source
This commit is contained in:
james 2025-12-10 21:53:13 +10:30
parent bf259da7c9
commit bfdbbb0b8b
No known key found for this signature in database
GPG Key ID: E1FFBA228F4CAD87
1 changed files with 84 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
README.md
View File

@ -1,107 +1,122 @@
# jvm-rs # roast-vm
A Java Virtual Machine (JVM) implementation written in Rust, capable of parsing and executing Java class files and bytecode. A Java Virtual Machine (JVM) implementation written in Rust, capable of parsing and executing Java class files and bytecode.
## Overview ## Overview
jvm-rs is an educational/experimental JVM implementation that demonstrates the core components and execution model of the Java Virtual Machine. The project uses Rust's type safety and modern tooling to build a simplified but functional JVM interpreter. roast-vm is an educational/experimental JVM implementation that demonstrates the core components and execution model of the Java Virtual Machine. The project uses Rust's type safety and modern tooling to build a simplified but functional JVM interpreter.
## Features ## Features
### Currently Implemented ### Currently Implemented
- **Class File Parsing**: Full support for reading and deserializing binary Java class files (`.class`) - **Class File Parsing**: Full support for reading and deserializing binary Java class files (`.class`) with magic number `0xCAFEBABE`
- **Constant Pool Management**: Handles 20+ constant pool entry types (UTF8, Integer, Float, Long, Double, Class, String, MethodRef, FieldRef, etc.) - **Constant Pool Management**: Handles 20+ constant pool entry types (UTF8, Integer, Float, Long, Double, Class, String, MethodRef, FieldRef, InterfaceMethodRef, NameAndType, MethodHandle, MethodType, InvokeDynamic, etc.)
- **Dynamic Class Loading**: On-demand class loading with superclass and interface resolution - **Dynamic Class Loading**: On-demand class loading with superclass and interface resolution, caching via DashMap
- **Class Initialization**: Automatic `<clinit>` method execution during class initialization - **Class Initialization**: Automatic `<clinit>` method execution following JVM Spec 5.5, with recursive initialization tracking
- **Bytecode Execution**: Interpreter for JVM bytecode instructions including: - **Bytecode Execution**: Interpreter for 50+ JVM bytecode instructions including:
- Constant loading (`ldc`, `ldc2_w`) - Constants: `aconst_null`, `iconst_*`, `lconst_*`, `fconst_*`, `dconst_*`, `bipush`, `sipush`, `ldc`, `ldc_w`, `ldc2_w`
- Load/store operations (`fload`, `dload`, `fstore`, `dstore`, etc.) - Load/Store: `iload`, `lload`, `fload`, `dload`, `aload`, `istore`, `lstore`, `fstore`, `dstore`, `astore` (including `_0-3` variants)
- Type conversions (`f2d`) - Array operations: `iaload`, `laload`, `faload`, `daload`, `aaload`, `baload`, `caload`, `saload`, `iastore`, `lastore`, `fastore`, `dastore`, `aastore`, `bastore`, `castore`, `sastore`, `arraylength`
- Arithmetic operations (`dadd`) - Stack manipulation: `pop`, `pop2`, `dup`, `dup_x1`, `dup_x2`, `dup2`, `dup2_x1`, `dup2_x2`, `swap`
- Field access (`getstatic`) - Arithmetic: `iadd`, `ladd`, `fadd`, `dadd`, `isub`, `lsub`, `fsub`, `dsub`, `imul`, `lmul`, `fmul`, `dmul`, `idiv`, `ldiv`, `fdiv`, `ddiv`, `irem`, `lrem`, `frem`, `drem`, `ineg`, `lneg`, `fneg`, `dneg`
- Method invocation (`invokevirtual`, `invokestatic`) - Bitwise: `ishl`, `lshl`, `ishr`, `lshr`, `iushr`, `lushr`, `iand`, `land`, `ior`, `lor`, `ixor`, `lxor`
- Control flow (`return_void`) - Type conversions: `i2l`, `i2f`, `i2d`, `l2i`, `l2f`, `l2d`, `f2i`, `f2l`, `f2d`, `d2i`, `d2l`, `d2f`, `i2b`, `i2c`, `i2s`
- **Module System**: Support for loading classes from 7z binary image archives - Comparisons: `lcmp`, `fcmpl`, `fcmpg`, `dcmpl`, `dcmpg`
- Control flow: `ifeq`, `ifne`, `iflt`, `ifge`, `ifgt`, `ifle`, `if_icmp*`, `if_acmp*`, `goto`, `ifnull`, `ifnonnull`
- Object operations: `new`, `newarray`, `anewarray`, `multianewarray`, `checkcast`, `instanceof`
- Field access: `getstatic`, `putstatic`, `getfield`, `putfield`
- Method invocation: `invokevirtual`, `invokespecial`, `invokestatic`, `invokeinterface`
- Returns: `ireturn`, `lreturn`, `freturn`, `dreturn`, `areturn`, `return`
- **Object Model**: Full object creation, field storage, and array support (primitive and reference arrays)
- **JNI Support**: Implementation of 80+ JNI functions for native method integration
- **Native Library Loading**: Dynamic loading of native libraries (DLLs on Windows)
- **Stack Traces**: Detailed stack trace generation with line number mapping from class file attributes
- **Module System**: Support for loading classes from 7z binary image archives (JDK modules)
- **Frame-based Execution**: Proper execution context with program counter, operand stack, and local variables - **Frame-based Execution**: Proper execution context with program counter, operand stack, and local variables
### In Development ### In Development
Many bytecode instructions and JVM features are planned but not yet implemented: - Additional bytecode instructions (`tableswitch`, `lookupswitch`, `monitorenter`, `monitorexit`, etc.)
- Most bytecode operations (array operations, object creation, exception handling, etc.) - Exception handling (`athrow`, try/catch blocks)
- Complete object model and field access - Garbage collection (basic object manager exists)
- Method resolution and invoke dynamic - Reflection API
- Exception handling and throw/catch - Multi-threading support
- Type checking and validation - Method handles and `invokedynamic`
- Garbage collection
- JNI/Native interface support
## Architecture ## Architecture
### Core Components ### Core Components
- **`Vm`** (`vm.rs`): Main virtual machine controller managing threads and class loader - **`Vm`** (`vm.rs`): Main virtual machine controller managing threads, class loader, and native library loading
- **`VmThread`** (`thread.rs`): Thread of execution managing the frame stack and method invocation - **`VmThread`** (`thread.rs`): Thread of execution managing the frame stack and method invocation
- **`Frame`** (`lib.rs`): Execution context for a method with PC, operand stack, and local variables - **`Frame`** (`lib.rs`): Execution context for a method with PC, operand stack, and local variables
- **`ClassLoader`** (`class_loader.rs`): Handles dynamic class loading, linking, and initialization - **`ClassLoader`** (`class_loader.rs`): Handles dynamic class loading, linking, and initialization
- **`RuntimeClass`** (`class.rs`): Runtime representation of a loaded class - **`RuntimeClass`** (`class.rs`): Runtime representation of a loaded class with initialization state tracking
- **`ClassFile`** (`class_file/`): Binary parser for Java class files using the `deku` library - **`ClassFile`** (`class_file/`): Binary parser for Java class files using the `deku` library
- **`ConstantPool`** (`class_file/constant_pool.rs`): Constant pool resolution and management - **`ConstantPool`** (`class_file/constant_pool.rs`): Constant pool resolution and management
- **`Object`** (`object.rs`): Runtime representation of Java objects - **`ObjectManager`** (`objects/object_manager.rs`): Object allocation and garbage collection management
- **`JNI`** (`jni.rs`): Java Native Interface implementation
### Execution Flow ### Execution Flow
1. **Loading**: `ClassFile::from_bytes()` parses binary class file data 1. **Loading**: `ClassFile::from_bytes()` parses binary class file data
2. **Resolution**: `ClassLoader` converts `ClassFile` to `RuntimeClass`, resolving dependencies 2. **Resolution**: `ClassLoader` converts `ClassFile` to `RuntimeClass`, resolving dependencies
3. **Execution**: `VmThread` invokes the main method, creating a `Frame` 3. **Initialization**: Class initializers (`<clinit>`) execute per JVM Spec 5.5
4. **Interpretation**: `Frame` iterates through bytecode operations, executing each instruction 4. **Execution**: `VmThread` invokes the main method, creating a `Frame`
5. **Stack Operations**: Instructions manipulate the operand stack and local variables 5. **Interpretation**: `Frame` iterates through bytecode operations, executing each instruction
6. **Stack Operations**: Instructions manipulate the operand stack and local variables
## Usage ## Project Structure
```rust ```
use jvm_rs::{Vm, VmError}; roast-vm/
├── Cargo.toml # Workspace configuration
fn main() -> Result<(), VmError> { └── crates/
// Initialize the VM ├── core/ # Main JVM implementation (roast-vm-core)
let vm = Vm::new(); │ ├── Cargo.toml
│ └── src/
// Execute a main method │ ├── main.rs # Entry point (binary: roast)
vm.run_main("path/to/ClassFile.class")?; │ ├── lib.rs # Frame and bytecode execution
│ ├── vm.rs # Virtual Machine controller
Ok(()) │ ├── thread.rs # Thread execution management
} │ ├── class.rs # RuntimeClass definition
│ ├── class_loader.rs # ClassLoader implementation
│ ├── class_file/ # Binary class file parser
│ │ ├── class_file.rs # ClassFile parser (magic 0xCAFEBABE)
│ │ └── constant_pool.rs
│ ├── objects/ # Object model
│ │ ├── object.rs # Object representation
│ │ ├── array.rs # Array support
│ │ └── object_manager.rs
│ ├── jni.rs # JNI implementation
│ ├── instructions.rs # Bytecode opcode definitions
│ ├── attributes.rs # Class file attributes
│ ├── value.rs # Value and stack types
│ ├── error.rs # Error handling and stack traces
│ ├── native_libraries.rs # Native library management
│ └── bimage.rs # Binary image (7z) reader
│
└── roast-vm-sys/ # Native methods bridge (cdylib)
├── Cargo.toml
└── src/
├── lib.rs # Native method implementations
├── system.rs # System native calls
├── class.rs # Class native operations
└── object.rs # Object native operations
``` ```
## Dependencies ## Dependencies
- **`deku`**: Binary parsing and serialization for class files - **`deku`**: Binary parsing and serialization for class files
- **`dashmap`**: Concurrent HashMap for class and object storage
- **`jni`**: Java Native Interface bindings
- **`libloading`**: Dynamic library loading
- **`libffi`**: Foreign function interface for native calls
- **`sevenz-rust2`**: 7z archive reading for module system support
- **`log`** / **`env_logger`**: Logging infrastructure - **`log`** / **`env_logger`**: Logging infrastructure
- **`itertools`**: Iterator utilities - **`itertools`**: Iterator utilities
- **`sevenz-rust2`**: 7z archive reading for module system support - **`colored`**: Colored console output
## Project Structure
```
jvm-rs/
├── src/
│ ├── lib.rs # Frame and Value definitions
│ ├── main.rs # Entry point
│ ├── vm.rs # Virtual Machine implementation
│ ├── thread.rs # Thread execution management
│ ├── class.rs # RuntimeClass definition
│ ├── class_loader.rs # ClassLoader implementation
│ ├── class_file/
│ │ ├── class_file.rs # ClassFile parser (magic 0xCAFEBABE)
│ │ └── constant_pool.rs # Constant pool types
│ ├── attributes.rs # Bytecode operations and attributes
│ ├── macros.rs # Helper macros
│ ├── object.rs # Object representation
│ ├── bimage.rs # Binary image (7z) reader
│ └── rng.rs # RNG utilities
├── data/ # Test class files
└── lib/ # Module library (7z archives)
```
## Building ## Building
@ -121,13 +136,11 @@ RUST_LOG=debug cargo run
## Current Status ## Current Status
This project is in early development (v0.1.0). The core infrastructure for class loading and basic bytecode execution is in place, but many JVM features remain unimplemented. Contributions and experimentation are welcome! This project is in early development (v0.1.0). The core infrastructure for class loading, bytecode execution, object creation, JNI support, and stack traces is functional. Many JVM features remain in development.
## License
[Add your license here]
## References ## References
- [JVM Specification](https://docs.oracle.com/javase/specs/jvms/se21/html/index.html) - [JVM Specification](https://docs.oracle.com/javase/specs/jvms/se25/html/index.html)
- [Java Class File Format](https://docs.oracle.com/javase/specs/jvms/se21/html/jvms-4.html) - [Java Class File Format](https://docs.oracle.com/javase/specs/jvms/se25/html/jvms-4.html)