rustc_codegen_jvm 🚀

A custom Rust compiler backend that emits Java Virtual Machine bytecode.
Compile your Rust code into a runnable .jar on JVM 8+!

---

📖 Table of Contents

1. Demos
2. Features
3. How It Works
4. Prerequisites
5. Installation & Build
6. Usage
7. Running Tests
8. Project Structure
9. Contributing
10. License

---

🔥 Demos

All examples live in tests/binary and are compiled to JVM bytecode & run/tested on the CI on every commit. Some exciting demos made in pure-Rust include:

• RSA encryption/decryption
• Binary search algorithm
• Fibonacci sequence generator
• Collatz conjecture verifier
• Large prime generator
• Use of nested data structures: enums, structs, tuples, arrays, slices (enums, structs - both tests use arrays and tuples)
• …and more!

---

✨ Features

• Minimal no_std & no_core programs via jvm-unknown-unknown
• Optimisations including constant folding and propogation, dead code elimination, and more to generate efficient JVM bytecode
• Basic core support on host target for JVM output
• Arithmetic (integers + floats, incl. checked ops)
• Comparisons, bitwise & logical ops
• Control flow: if/else, match, for, while, loop
• Type casting (as), primitive types
• Function calls (recursion supported)
• Arrays & slices with nested indexing
• Structs, tuples, enums (both C‑like and Rust‑style)
• Executable .jar generation for binary crates
• Mutable borrowing, references, and dereferencing
• Integration tests for all features

🚧 Next Milestone: Full support for the Rust core crate.

---

⚙️ How It Works

1. Rustc Frontend → MIR
   Standard rustc parses your code into Mid‑level IR (MIR).
2. MIR → OOMIR
   Custom “Object‑Oriented MIR” simplifies MIR into OOP‑style constructs.
   (see src/lower1.rs)
3. OOMIR optimiser Optimises OOMIR using constant folding, dead code elimination, and more.
   (see src/optimise1.rs)
   • Constant Folding: Evaluates constant expressions at compile time.
   • Constant Propagation: Replaces variables with their constant values.
   • Dead Code Elimination: Removes unused code paths.
   • Algebraic Simplification: Simplifies expressions using algebraic identities.
4. OOMIR → JVM Classfile
   Translate to .class files using ristretto_classfile.
   (see src/lower2.rs)
5. R8 pass
   r8 adds stack map frames (neeeded to run on JVM 8+) and applies some further optimisations.
6. Link & Package
   java-linker bundles .class files into a runnable .jar with META-INF/MANIFEST.MF.

---

🛠 Prerequisites

• Rust Nightly (rustup default nightly)
• JDK 8+ (java in PATH, and the JAVA_HOME environment variable set)
• Python 3 (python3 in PATH)

---

🏗 Installation & Build

# Clone & enter repo
git clone https://github.com/IntegralPilot/rustc_codegen_jvm.git
cd rustc_codegen_jvm

# Build everything
make all

This will compile:

• rustc_codegen_jvm backend library
• java-linker
• Kotlin shim for core (once core support is reached, this will no longer be needed)
• Generate config.toml & jvm-unknown-unknown.json

If you relocate the repo, re-run:

make gen-files

---

🚀 Usage

1. Configure your project
   In your Rust project directory, create or update .cargo/config.toml with the generated template (will be at the root of this repo after running make).

2. Build with Cargo

   cargo build           # debug
   cargo build --release # optimized - functionality available slightly impaired 

3. Run the .jar

   java -jar target/debug/deps/your_crate*.jar

---

🧪 Running Tests

Ensure the toolchain is built:

make all
# If you moved the repo:
make gen-files

Then:

python3 Tester.py
# or with --release for release‑mode tests

Look for ✅ All tests passed! or inspect .generated files on failure.

---

📂 Project Structure

.
├── src/                   # rustc_codegen_jvm backend
│   ├── lib.rs
│   ├── lower1.rs          # MIR → OOMIR
│   ├── lower2.rs          # OOMIR → JVM bytecode
│   └── oomir.rs           # OOMIR definitions
├── java-linker/           # Bundles .class files into .jar
├── tests/binary/          # Integration tests
├── library/               # Kotlin shim for Rust core library
├── shim-metadata-gen/     # Generates core.json metadata
├── proguard/              # .pro rules used for r8
├── Makefile               # build & gen-files
├── config.toml.template
├── jvm-unknown-unknown.json.template
├── Tester.py              # test runner
├── GenerateFiles.py       # regenerates config & target spec
└── LICENSE, LICENSE-Apache

---

🤝 Contributing

Contributions, issues & PRs welcome! :)

---

📄 License

Dual‑licensed under MIT OR Apache 2.0 at your option:
https://opensource.org/licenses/MIT
https://www.apache.org/licenses/LICENSE-2.0