# integralpilot/rustc_codegen_jvm architecture

> Architecture diagram of the GitHub repository integralpilot/rustc_codegen_jvm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/integralpilot/rustc_codegen_jvm
- Repository: https://github.com/integralpilot/rustc_codegen_jvm

## Overview

#### Purpose and entry points
`rustc_codegen_jvm` is a Rust compiler backend that emits JVM Java 8+ class files from Rust crates, then packages runnable/self-contained JARs. The backend is loaded by rustc through the root crate (`Cargo.toml`, `src/lib.rs`). User-facing orchestration is the Cargo subcommand in `cargo-jvm/src/main.rs`; JAR assembly is a separate CLI in `java-linker/src/main.rs`.

#### Compilation boundary: rustc MIR to OOMIR
Rustc owns parsing, type checking, borrow checking, drop elaboration, and MIR production. The backend receives MIR and lowers it into Object-Oriented MIR (OOMIR), a JVM-oriented intermediate representation. Core definitions and interpretation support are in `src/oomir.rs` and `src/oomir/interpret.rs`; the backend integration and instrumentation are in `src/lib.rs` and `src/instrumentation.rs`.

#### Stage 1: MIR lowering
`lower1` translates Rust constructs into Java-compatible classes, interfaces, methods, fields, and control flow while preserving Rust semantics. It contains the critical representation decisions for types, operands/places, statics, closures, trait objects, naming, and checked operations:
`src/lower1.rs`, `src/lower1/types.rs`, `src/lower1/control_flow.rs`.
This is the principal semantic boundary where Rust ABI/data-model features become OOMIR/JVM constructs.

#### Stage 2: OOMIR optimization
The first optimization layer transforms OOMIR before bytecode emission, including dataflow, copy propagation, reachability, and reorganization:
`src/optimise1.rs`, `src/optimise1/dataflow.rs`, `src/optimise1/copyprop.rs`.
Its output remains JVM-independent enough to be reasoned about as OOMIR, but is tailored to make bytecode generation tractable and efficient.

#### Stage 3: JVM bytecode generation
`lower2` turns optimized OOMIR into class-file structures and serialized `.class` artifacts. It manages constant pools, JVM instruction generation, translation, large-method handling, second-pass optimization, and verifier-required stack-map frames:
`src/lower2.rs`, `src/lower2/jvm_gen.rs`, `src/lower2/stackmaps.rs`.
This is the hard JVM verification boundary: generated code must satisfy JVM operand-stack, control-flow, and class-file constraints.

#### Packaging and developer workflow
`cargo-jvm` wraps Cargo using the pinned nightly and JVM target, supports build/run/test/package workflows, invokes Java tooling, and locates generated artifacts. Relevant implementation paths are `cargo-jvm/src/main.rs`, `cargo-jvm/src/lib.rs`, and `cargo-jvm/build.rs`. `java-linker` packages generated classes with runtime classes and manifest metadata into JARs (`java-linker/src/main.rs`). Material external requirements are rustup/pinned nightly, Cargo/rustc internals, Python 3 for repository automation, Git, and a JDK with `java`, `javac`, and `jar`.

#### Runtime and standard-library adaptation
Generated code depends on a Java runtime library implementing Rust-specific behavior: pointer virtualization, numeric types, intrinsics, deterministic drop dispatch, panic/unwind support, threading, files, and networking. Key boundary paths are `runtime/src/Pointer.java`, `runtime/src/RuntimeSupport.java`, and `runtime/src/PanicSupport.java`. The virtual-MMU pointer layer permits raw pointers, transmute, unions, and atomic operations without violating GC or bytecode verification.

Rust `std` support is supplied by patches plus JVM platform overlays rather than a native OS layer: `std/patches/0001-jvm-bootstrap.patch`, `std/overlay/std/src/sys/fs/jvm.rs`, and `std/overlay/std/src/sys/net/connection/jvm.rs`. These bridge Rust APIs to the Java runtime/NIO and JVM services.

#### Execution model and interop
The output runs inside a JVM, with HotSpot JIT responsible for much runtime optimization. Rust structs map to Java classes, traits to interfaces, enums to base/subclass families, closures/function types to single-method interfaces, and trait-object dispatch to interface references. Java-facing integration examples establish the intended direct interop boundary: `tests/integration/lambda_callbacks/Main.java`, `tests/integration/trait_implementors/Main.java`, and `tests/integration/cdylib/Main.java`.

Main entry points: [`runtime/src/RuntimeSupport.java`](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/runtime/src/RuntimeSupport.java) (Java runtime support), [`java-linker/src/main.rs`](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/java-linker/src/main.rs) (java-linker), [`src/lower2.rs`](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower2.rs) (OOMIR → class files), [`src/lower1.rs`](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower1.rs) (MIR → OOMIR lowering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Developer workflow"]
  node_cargo_jvm["cargo-jvm<br/>Cargo subcommand<br/>[main.rs]"]
  node_rust_toolchain{{"Pinned rustc toolchain<br/>external compiler"}}
  node_java_linker["java-linker<br/>JAR assembler<br/>[main.rs]"]
end

subgraph group_compiler["Compiler backend"]
  node_backend["rustc codegen backend<br/>rustc backend<br/>[lib.rs]"]
  node_mir["Rust MIR<br/>compiler IR"]
  node_lower1["MIR → OOMIR lowering<br/>semantic lowering<br/>[lower1.rs]"]
  node_oomir["OOMIR<br/>intermediate representation<br/>[oomir.rs]"]
  node_optimise1["OOMIR optimization<br/>IR optimizer<br/>[optimise1.rs]"]
  node_lower2["OOMIR → class files<br/>bytecode generation<br/>[lower2.rs]"]
  node_stackmaps["Verifier stack maps<br/>class-file validation<br/>[stackmaps.rs]"]
  node_classes["Generated .class files<br/>build artifact"]
end

subgraph group_runtime["JVM runtime and std"]
  node_jvm_runtime["Java runtime support<br/>runtime library"]
  node_pointer_layer["Virtual-MMU pointers<br/>memory runtime<br/>[Pointer.java]"]
  node_std_overlay["Rust std JVM overlay<br/>standard-library adaptation<br/>[jvm.rs]"]
end

subgraph group_execution["JVM execution"]
  node_jar["Runnable JAR<br/>packaged artifact"]
  node_jvm{{"JVM / HotSpot<br/>execution runtime"}}
  node_java_interop["Java callers<br/>interop boundary<br/>[Main.java]"]
end

node_cargo_jvm -->|"invokes"| node_rust_toolchain
node_rust_toolchain -->|"produces"| node_mir
node_rust_toolchain -->|"loads"| node_backend
node_mir -->|"lowers"| node_lower1
node_backend -->|"orchestrates"| node_lower1
node_lower1 -->|"emits"| node_oomir
node_oomir -->|"optimizes"| node_optimise1
node_optimise1 -->|"optimized OOMIR"| node_lower2
node_lower2 -->|"computes"| node_stackmaps
node_stackmaps -->|"verifies emission"| node_classes
node_lower2 -->|"serializes"| node_classes
node_cargo_jvm -->|"packages through"| node_java_linker
node_classes -->|"packages"| node_java_linker
node_jvm_runtime -->|"bundles"| node_java_linker
node_pointer_layer -->|"provides memory model"| node_jvm_runtime
node_std_overlay -->|"uses Java services"| node_jvm_runtime
node_java_linker -->|"assembles"| node_jar
node_jar -->|"runs on"| node_jvm
node_jvm_runtime -->|"executes within"| node_jvm
node_java_interop -.->|"uses generated API"| node_jar

click node_cargo_jvm "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/cargo-jvm/src/main.rs"
click node_backend "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lib.rs"
click node_lower1 "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower1.rs"
click node_oomir "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/oomir.rs"
click node_optimise1 "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/optimise1.rs"
click node_lower2 "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower2.rs"
click node_stackmaps "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower2/stackmaps.rs"
click node_java_linker "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/java-linker/src/main.rs"
click node_jvm_runtime "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/runtime/src/RuntimeSupport.java"
click node_pointer_layer "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/runtime/src/Pointer.java"
click node_std_overlay "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/std/overlay/std/src/sys/fs/jvm.rs"
click node_java_interop "https://github.com/integralpilot/rustc_codegen_jvm/blob/main/tests/integration/lambda_callbacks/Main.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cargo_jvm,node_rust_toolchain,node_java_linker toneBlue
class node_backend,node_mir,node_lower1,node_oomir,node_optimise1,node_lower2,node_stackmaps,node_classes toneAmber
class node_jvm_runtime,node_pointer_layer,node_std_overlay toneMint
class node_jar,node_jvm,node_java_interop toneRose
```

## Components

### Developer workflow

- [cargo-jvm](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/cargo-jvm/src/main.rs): Cargo subcommand · Builds, runs, tests, and packages JVM-targeted Rust crates. · `cargo-jvm/src/main.rs`
- **Pinned rustc toolchain**: external compiler · Provides Rust analysis and MIR through rustc internals.
- [java-linker](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/java-linker/src/main.rs): JAR assembler · Combines generated classes, runtime classes, and manifest metadata. · `java-linker/src/main.rs`

### Compiler backend

- [rustc codegen backend](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lib.rs): rustc backend · Loaded by rustc to compile crate MIR into JVM artifacts. · `src/lib.rs`
- **Rust MIR**: compiler IR · Typed and elaborated control-flow input owned by rustc.
- [MIR → OOMIR lowering](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower1.rs): semantic lowering · Maps Rust data-model and ABI semantics to JVM-oriented constructs. · `src/lower1.rs`
- [OOMIR](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/oomir.rs): intermediate representation · Object-oriented MIR with interpretation support. · `src/oomir.rs`
- [OOMIR optimization](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/optimise1.rs): IR optimizer · Performs dataflow, copy propagation, reachability, and reorganization. · `src/optimise1.rs`
- [OOMIR → class files](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower2.rs): bytecode generation · Builds constant pools, JVM instructions, and serialized class artifacts. · `src/lower2.rs`
- [Verifier stack maps](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/src/lower2/stackmaps.rs): class-file validation · Emits verifier-required operand-stack frames. · `src/lower2/stackmaps.rs`
- **Generated .class files**: build artifact

### JVM runtime and std

- [Java runtime support](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/runtime/src/RuntimeSupport.java): runtime library · Implements pointer virtualization, intrinsics, drops, panics, and platform services. · `runtime/src/RuntimeSupport.java`
- [Virtual-MMU pointers](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/runtime/src/Pointer.java): memory runtime · Supports raw-pointer features while preserving GC and bytecode safety. · `runtime/src/Pointer.java`
- [Rust std JVM overlay](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/std/overlay/std/src/sys/fs/jvm.rs): standard-library adaptation · Bridges Rust filesystem and networking APIs to Java and NIO. · `std/overlay/std/src/sys/fs/jvm.rs`

### JVM execution

- **Runnable JAR**: packaged artifact · Self-contained application package.
- **JVM / HotSpot**: execution runtime · Verifies classes and JIT-optimizes execution.
- [Java callers](https://github.com/integralpilot/rustc_codegen_jvm/blob/main/tests/integration/lambda_callbacks/Main.java): interop boundary · Java code can directly use generated classes, interfaces, and callbacks. · `tests/integration/lambda_callbacks/Main.java`

## Connections

- cargo-jvm → Pinned rustc toolchain: invokes
- Pinned rustc toolchain → Rust MIR: produces
- Pinned rustc toolchain → rustc codegen backend: loads
- Rust MIR → MIR → OOMIR lowering: lowers
- rustc codegen backend → MIR → OOMIR lowering: orchestrates
- MIR → OOMIR lowering → OOMIR: emits
- OOMIR → OOMIR optimization: optimizes
- OOMIR optimization → OOMIR → class files: optimized OOMIR
- OOMIR → class files → Verifier stack maps: computes
- Verifier stack maps → Generated .class files: verifies emission
- OOMIR → class files → Generated .class files: serializes
- cargo-jvm → java-linker: packages through
- Generated .class files → java-linker: packages
- Java runtime support → java-linker: bundles
- Virtual-MMU pointers → Java runtime support: provides memory model
- Rust std JVM overlay → Java runtime support: uses Java services
- java-linker → Runnable JAR: assembles
- Runnable JAR → JVM / HotSpot: runs on
- Java runtime support → JVM / HotSpot: executes within
- Java callers → Runnable JAR: uses generated API