# 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)
