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)

• Implementation blocks and traits (including dynamic dispatch!)

• …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
• Implementations for ADTs, including using and returning self, &self, &mut self
• Traits, including dynamic dispatch (&dyn Trait)
• Integration tests for all features, in debug and release modes

🚧 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)
• Gradle 8.5+ (gradle in PATH)
• 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 by copying the generated template (will be at the root of this repo after running make). Also, your Cargo.toml needs to contain the following (used to pass flags differentiating between debug and release builds to the linker):

   cargo-features = ["profile-rustflags"]

2. Build with Cargo

   cargo build           # debug
   cargo build --release # optimized

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