# Quick Start Guide
Get up and running with JVMRS in minutes.
## Installation
### Using Cargo
```bash
cargo add jvmrs
```
### From Source
```bash
git clone https://github.com/yingkitw/jvmrs
cd jvmrs
cargo build --release
```
### With Optional Features
```toml
[dependencies]
jvmrs = { version = "0.1", features = ["wasm", "simd"] }
```
Available features:
- `llvm` - LLVM IR generation
- `wasm` - WebAssembly backend
- `simd` - SIMD array operations
- `ffi` - C API for embedding
- `interop` - Java/Rust polyglot
- `async` - Async I/O with tokio
- `truffle` - Truffle-style language API
## Your First Program
### Create a Simple Java Program
Create `HelloWorld.java`:
```java
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello from JVMRS!");
int a = 5, b = 10;
System.out.println("5 + 10 = " + (a + b));
}
}
```
### Compile and Run
```bash
# Compile Java
javac HelloWorld.java
# Run with JVMRS
cargo run --release -- HelloWorld
```
Output:
```
Hello from JVMRS!
5 + 10 = 15
```
## Using the Interpreter
### Basic Usage
```rust
use jvmrs::Interpreter;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create interpreter
let mut interpreter = Interpreter::new();
// Run a Java class
interpreter.run_main("HelloWorld")?;
Ok(())
}
```
### Calling Java Methods
```rust
use jvmrs::{Interpreter, Value};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut interpreter = Interpreter::new();
// Call static method
let result = interpreter.invoke_method(
"java/lang/Math",
"max",
&[Value::Int(10), Value::Int(20)]
)?;
println!("Max: {}", result.as_int()); // Output: 20
Ok(())
}
```
### Working with Objects
```rust
use jvmrs::{Interpreter, Value};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut interpreter = Interpreter::new();
// Create an instance
let obj = interpreter.new_instance("java/lang/String")?;
// Get class
let class_name = interpreter.get_object_class(obj)?;
println!("Class: {}", class_name);
Ok(())
}
```
## Interactive REPL
Explore JVMRS interactively:
```bash
cargo run -- --repl
```
### REPL Session Example
```
jvmrs> load java/lang/String
Loaded class: java/lang/String
jvmrs> class java/lang/String
Class: java/lang/String
Super class: java/lang/Object
Methods:
length ()I
charAt (I)C
substring (II)Ljava/lang/String;
...
jvmrs> exec java/lang/String valueOf "123"
Result: java/lang/String@0x7f8a1c000000
jvmrs> exec java/lang/String length 0x7f8a1c000000
Result: 3
jvmrs> state
Loaded classes: 2
Memory usage: 1048576 bytes
GC runs: 0
jvmrs> exit
Goodbye!
```
## Polyglot: Java + Rust
### Registering Rust Functions
```rust
use jvmrs::{Interpreter, Value};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut interpreter = Interpreter::new();
// Register a Rust function as a native method
interpreter.register_native_method(
"com/example/Native",
"add",
"(II)I",
Box::new(|args, _memory| {
let a = args[0].as_int();
let b = args[1].as_int();
Ok(Value::Int(a + b))
})
)?;
// Call from Java
interpreter.run_main("com/example/Caller")?;
Ok(())
}
```
### Java Code
```java
package com.example;
public class Caller {
public static void main(String[] args) {
int result = add(5, 10);
System.out.println("Result: " + result); // Output: 15
}
private static native int add(int a, int b);
}
```
## Performance Optimization
### Enable JIT Compilation
JIT is enabled by default. Adjust thresholds:
```rust
use jvmrs::jit::TieredCompilationConfig;
let config = TieredCompilationConfig {
baseline_threshold: 50, // Compile after 50 invocations
optimized_threshold: 1000, // Optimize after 1000 invocations
..Default::default()
};
```
### Inline Caching
Inline caching is enabled by default. Monitor effectiveness:
```rust
let stats = interpreter.get_inline_cache_stats();
for (site, cache_stats) in stats {
println!("Hit rate: {:.2}%", cache_stats.hit_rate);
}
```
### TLAB (Thread-Local Allocation)
TLAB is enabled by default. Configure for your workload:
```rust
use jvmrs::tlab::TlabConfig;
let config = TlabConfig {
tlab_size: 128 * 1024, // 128KB per TLAB
max_tlabs: 32,
enabled: true,
};
```
## Testing
### Run Unit Tests
```bash
cargo test
```
### Run Property-Based Tests
```bash
cargo test --test property_tests
```
### Run Benchmarks
```bash
cargo bench
```
## Deployment
### WebAssembly
Compile Java to WebAssembly for browser deployment:
```bash
cargo build --features wasm
cargo run --features wasm -- --wasm-output output.wasm MyClass
```
### Embedded (no_std)
For resource-constrained environments:
```bash
cargo build --features no_std --target thumbv7em-none-eabihf
```
### AOT Compilation
Ahead-of-time compilation to native object files:
```bash
cargo run -- --aot output.o MyClass
gcc -o myapp output.o -ljvmrs
```
## Next Steps
1. **Learn More**: Read the [Architecture Documentation](ARCHITECTURE.md)
2. **Performance**: Check the [Performance Tuning Guide](docs/performance-tuning.md)
3. **Polyglot**: See the [Polyglot Programming Guide](docs/polyglot-programming.md)
4. **API Reference**: Browse the complete [API Reference](docs/api-reference.md)
5. **Examples**: Explore examples in the `examples/` directory
## Common Issues
### Class Not Found
Ensure the class is in the classpath:
```bash
cargo run -- --classpath ./classes MyClass
```
### Method Not Found
Check method signature matches exactly:
```java
// Correct signature
public static int add(int a, int b);
```
### Out of Memory
Adjust heap size:
```rust
use jvmrs::gc::GenerationalHeap;
let heap = GenerationalHeap::new(
32 * 1024 * 1024, // 32MB young generation
128 * 1024 * 1024, // 128MB old generation
);
```
### Slow Performance
1. Enable JIT (default: enabled)
2. Lower JIT threshold for warmup
3. Check inline cache hit rates
4. Monitor GC pause times
5. Profile with built-in profiler
## Getting Help
- **Documentation**: [docs/](docs/)
- **API Reference**: [docs/api-reference.md](docs/api-reference.md)
- **Issues**: [GitHub Issues](https://github.com/yingkitw/jvmrs/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yingkitw/jvmrs/discussions)
## Examples
### Calculator
```bash
cargo run Calculator
```
### ArrayList Operations
```bash
cargo run ArrayListExample
```
### Reflection
```bash
cargo run ReflectionExample
```
### Polyglot
```bash
cargo run PolyglotExample
```
## Resources
- [Architecture Documentation](ARCHITECTURE.md)
- [Performance Tuning Guide](docs/performance-tuning.md)
- [Polyglot Programming Guide](docs/polyglot-programming.md)
- [API Reference](docs/api-reference.md)
- [Competitive Differentiation](docs/competitive-differentiation.md)
- [Implementation Summary](IMPLEMENTATION_SUMMARY.md)
- [Original TODO](TODO.md)