New tests - RSA encrypt.decrypt, fibonacchi.

Also some changes regarding `checkcast` and better handling of option in the stdlib shim (unrelated to the new tests).

And a readme makeover.

Author: IntegralPilot

Readme.md

@@ -1,150 +1,181 @@
-# Rustc Codegen JVM 🚀
+# rustc_codegen_jvm 🚀
 
-[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT/Apache-2.0](https://img.shields.io/badge/license-MIT%20%7C%20Apache--2.0-blue.svg)](https://opensource.org/licenses/MIT)  
+[![CI](https://github.com/IntegralPilot/rustc_codegen_jvm/actions/workflows/ci.yml/badge.svg)](https://github.com/IntegralPilot/rustc_codegen_jvm/actions)
 
-Welcome! This project provides a custom Rust compiler backend (`rustc_codegen_jvm`) that compiles Rust code into Java Virtual Machine (JVM) bytecode. This allows Rust programs to run on the JVM. Currently, the generated bytecode supports JVM 8 and later versions.
+A **custom Rust compiler backend** that emits Java Virtual Machine bytecode.  
+Compile your Rust code into a runnable `.jar` on JVM 8+!
 
-## How It Works
+---
 
-The toolchain transforms Rust code into executable `.jar` files through several stages:
+## 📖 Table of Contents
 
-1.  **Rustc Frontend (Parsing & MIR Generation)**
-    *   Your Rust code is parsed and lowered to *Mid-level Intermediate Representation (MIR)* by the standard `rustc` frontend.
+1. [Demos](#demos)  
+2. [Features](#features)  
+3. [How It Works](#how-it-works)  
+4. [Prerequisites](#prerequisites)  
+5. [Installation & Build](#installation--build)  
+6. [Usage](#usage)  
+7. [Running Tests](#running-tests)  
+8. [Project Structure](#project-structure)  
+9. [Contributing](#contributing)  
+10. [License](#license)  
 
-2.  **MIR to OOMIR (Object-Oriented MIR)**
-    *   The MIR is lowered further into a custom intermediate representation called OOMIR. This step simplifies MIR constructs into a representation closer to object-oriented concepts, making the translation to JVM bytecode more manageable. (See `src/lower1.rs`).
+---
 
-3.  **OOMIR to JVM Classfile**
-    *   The OOMIR is then translated into standard Java `.class` files containing JVM bytecode. This is the core task of the `rustc_codegen_jvm` library in this repository (See `src/lower2.rs`). It utilizes the `ristretto_classfile` library for bytecode generation.
+## 🔥 Demos
 
-4.  **Classfile Post-Processing (Stack Map Frames)**
-    *   The generated `.class` files are processed by a dedicated tool (`asm-processor`, written in Kotlin using the ASM library). This tool calculates and inserts *Stack Map Frames*, which are required for class verification in modern JVM versions (Java 7+).
+All examples live in `tests/binary` and are compiled to JVM bytecode & run/tested on the CI on every commit. Some exicting demos made in pure-Rust include:
 
-5.  **Linking & `.jar` Generation**
-    *   Finally, the processed `.class` files for the crate and its dependencies (though dependency handling is currently basic) are linked together into a single executable `.jar` file. This step is handled by `java-linker`, a custom linker built as part of this project (See `java-linker/`). It also generates the necessary `META-INF/MANIFEST.MF` file, marking the main class if applicable.
-
-## Current Capabilities
-
-This backend currently supports a subset of Rust features:
-
-*   ✅ Compiling minimal `no_std` & `no_core` Rust programs (like an empty `main`) using the `jvm-unknown-unknown` target.
-*   ✅ Compiling simple programs using basic `core` features (like other tests) using the host target but this codegen backend to produce JVM bytecode.
-*   ✅ Basic integer arithmetic operations on all types of numbers including floats:
-    *   Addition (`+`), Subtraction (`-`), Multiplication (`*`), Division (`/`), Remainder (`%`).
-    *   Checked addition, subtraction and multiplication returning `(result, overflowed_bool)` tuples (`rustc` requests this in debug mode even for normal operations to panic on overflow).
-*   ✅ Comparisons between all number types (`==`, `!=`, `<`, `<=`, `>`, `>=`).
-*   ✅ Bitwise operations on all numbers (`&`, `|`, `^`, `<<`, `>>`).
-*   ✅ Logical operations(`&&`, `||`, `!`), support for `if` (and `else if`/`else`) and `match` statements.
-*   ✅ Unary operations (`-`, `!`).
-*   ✅ Type casting (e.g., `as` operator).
-*   ✅ Support for all Rust primitive types.
-*   ✅ Calling other functions (including recursion).
-*   ✅ Loops such as `for`, `while`, and `loop`.
-*   ✅ Variable assignment including subfield and array index assignment, including nesting.
-*   ✅ Arrays and slices, including inserting, accessing and mutating at a given index (supporting nesting).
-*   ✅ Floats (`f16`, `f32`, `f64`, `f128`) and their operations.
-*   ✅ Structs, Tuples and Enums (including traditional C-like enums but also Rust-like enums with anonymous structs and tuples in them) including nested access/setting/mutation of fields and array indices within these.
-*   ✅ Generating executable `.jar` files for binary crates.
-
-### Next Milestone:
-🚧 **Full support for the `core` crate** is the next major goal.
-
-## Prerequisites
-
-*   **Rust Nightly:** Ensure you are using the latest **nightly** Rust toolchain. You can set this up with `rustup default nightly`. Some rust components are needed but will be automatically installed by the Makefile.
-*   **Java Development Kit (JDK):** A working JDK (version 8 or later recommended) is required to run the generated `.jar` files and the `asm-processor`. Make sure `java` is in your PATH.
-*   **Gradle:** Required to build the `asm-processor` Kotlin project. Make sure `gradle` is in your PATH.
-*  **Python 3:** Required to run the integration tests and generate files from templates. Make sure `python3` is in your PATH.
-
-## Building the Toolchain
-
-1.  **Build All Components:**
-    *   You can use the provided Makefile or build script:
-      ```bash
-      # Using Make
-      make all
-      ```
-    *   This will:
-        *   Build the main `rustc_codegen_jvm` library (`target/debug/librustc_codegen_jvm.[dll/dylib/so]`).
-        *   Build the `java-linker` (`java-linker/target/debug/java-linker`).
-        *   Build the `asm-processor` (`asm-processor/build/libs/asm-processor-*.jar`).
-        *   Build the Kotlin shim of the Rust core library (`library`).
-        *   Generate the `config.toml` and `jvm-unknown-unknown.json` files from their templates.
-
-
-## Using the Toolchain (Compiling Another Rust Project)
-
-To compile *your own* Rust project using this backend:
-
-1.  **Get the Toolchain:** Clone this repository and build it as described above. Ensure you build the toolchain first, as described in the previous section, by running `make all`. You will need to re-run `make gen-files` if you change the absolute path of where this repository is stored since building.
-
-
-2.  **Configure Your Rust Project:**
-    *   In your *own* Rust project's directory, create a `.cargo/config.toml` file (if it doesn't exist).
-    * Copy the contents from the `config.toml` file generated specifically for your system, that can be found in the root of this project after running `make all`. If since running make, you've moved this repo to a different directory, you'll need to run at least `make gen-files`.
-
-3.  **Build Your Project:**
-    *   Run the standard Cargo build command, targeting the host target (using the `jvm-unknown-unknown` target is an emerging feature and means you can't even use `core`, for now, so not recommended). Cargo will read the `.cargo/config.toml` and use the specified target and flags automatically.
-    ```bash
-    cargo build
-    # Or for release builds:
-    # cargo build --release
-    ```
-
-4.  **Find & Run the Generated `.jar`:**
-    *   The compiled `.jar` file will be located in your project's `target` directory:
-        *   Debug: `target/debug/deps/[your_crate_name].jar`
-        *   Release: `target/release/deps/[your_crate_name].jar`
-    *   If your crate is a binary (`[[bin]]` or `src/main.rs`), run it using the `java` command:
-        ```bash
-        java -jar target/jvm-unknown-unknown/debug/[your_crate_name].jar
-        ```
-
-## Running This Project's Tests
-
-This project includes integration tests managed by a Python script.
-
-1.  **Ensure Toolchain is Built:** Build the project using `make all`. If you've changed the path of the repository, run `make gen-files` to regenerate the configuration files.
-2.  **Run the Tester:**
-    ```bash
-    python3 Tester.py
-    # For release mode tests:
-    # python3 Tester.py --release
-    ```
-3.  **Check Output:** Look for the final "✅ All tests passed!" message. If tests fail, the script will generate `.generated` files in the respective test directories (`tests/binary/*`) containing error details or output diffs.
-
-## Project Structure
-
-*   `src/`: Contains the source code for the `rustc_codegen_jvm` backend library.
-    *   `lib.rs`: Main backend integration point.
-    *   `lower1.rs`: MIR to OOMIR lowering pass.
-    *   `lower2.rs`: OOMIR to JVM bytecode generation pass.
-    *   `oomir.rs`: Definition of the Object-Oriented MIR (OOMIR).
-*   `java-linker/`: Source code for the custom linker that creates `.jar` filesn from the generated `.class` files.
-*   `asm-processor/`: Kotlin/Gradle project for the ASM-based bytecode post-processor that adds stack map frames to the generated `.class` files.
-*   `tests/`: Integration tests.
-    *   `binary/`: Tests for compiling executable Rust crates.
-*   `library/`: Source code for a minimal Kotlin-based implementation of the Rust core library. This serves as a temporary substitute to bootstrap the project until the backend can fully compile the Rust core library itself.
-*   `shim-metadata-gen`: A tool for generating metadata for the Kotlin core library, called at compiletime to provide nessecary info (descriptors) to the codegen backend. It's generated metadata is embedded in the generated library, so not needed at runtime.
-    *   `core.json`: Metadata for the core library, generated by this tool.
-*   `jvm-unknown-unknown.json.template`: The template for Rust target specification file (currently experimental & not recommended, use `config.toml` in your project instead).
-*  `config.toml.template`: The template for the Cargo configuration file for the toolchain.
-*   `Tester.py`: Python script for running integration tests.
-*   `GenerateFiles.py` : Python script for generating the `config.toml` file and the `jvm-unknown-unknown.json` file from their templates, making them suited to your system.
-*   `Makefile` Scripts for building the entire toolchain.
-*   `setup.sh`: Script to install Rust components.
-*   `Cargo.toml`, `Cargo.lock`: Rust package definition and dependencies for the backend.
-*   `LICENSE`, `LICENSE-Apache`: Project licenses.
-
-## Contributing
-
-Contributions are welcome! Feel free to open issues or pull requests.
-
-## License
-
-This project is dual-licensed under either of:
-
-*   MIT License ([LICENSE-MIT](LICENSE) or http://opensource.org/licenses/MIT)
-*   Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-Apache) or http://www.apache.org/licenses/LICENSE-2.0)
-
-at your option. 
+- **RSA** encryption/decryption (`rsa`) 
+- **Fibonacci** sequence generator (`fibonacci`)  
+- **Collatz conjecture** verifier (`collatz`)  
+- **Large prime** generator (`primes`)
+- Nested data structures: enums, structs, tuples, arrays, slices (`enums`, `structs`)  
+- …and more!
+
+---
+
+## ✨ Features
+
+- **Minimal `no_std` & `no_core`** programs via `jvm-unknown-unknown`  
+- 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  
+
+🚧 **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 → JVM Classfile**  
+   Translate to `.class` files using `ristretto_classfile`.  
+   _(see `src/lower2.rs`)_  
+4. **Post‑Process Stack Map Frames**  
+   Kotlin `asm-processor` (ASM library) adds verification frames.  
+5. **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)  
+- **Gradle** (`gradle` in PATH)  
+- **Python 3** (`python3` in PATH)
+
+---
+
+## 🏗 Installation & Build
+
+```bash
+# Clone & enter repo
+git clone https://github.com/your-org/rustc_codegen_jvm.git
+cd rustc_codegen_jvm
+
+# Build everything
+make all
+```
+
+This will compile:
+
+- `rustc_codegen_jvm` backend library  
+- `java-linker`  
+- `asm-processor`  
+- Kotlin shim for `core`  
+- Generate `config.toml` & `jvm-unknown-unknown.json`  
+
+If you relocate the repo, re-run:
+```bash
+make gen-files
+```
+
+---
+
+## 🚀 Usage
+
+1. **Configure your project**  
+   In *your* Rust project directory, create or update `.cargo/config.toml` with the generated template.
+
+2. **Build with Cargo**  
+   ```bash
+   cargo build           # debug
+   cargo build --release # optimized
+   ```
+
+3. **Run the `.jar`**  
+   ```bash
+   java -jar target/debug/deps/your_crate.jar
+   ```
+
+---
+
+## 🧪 Running Tests
+
+Ensure the toolchain is built:
+
+```bash
+make all
+# If you moved the repo:
+make gen-files
+```
+
+Then:
+
+```bash
+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
+├── asm-processor/         # Kotlin ASM post‑processor
+├── tests/binary/          # Integration tests
+├── library/               # Kotlin shim for Rust core library
+├── shim-metadata-gen/     # Generates core.json metadata
+├── 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>