# zlfn/rust-gb architecture

> Architecture diagram of the GitHub repository zlfn/rust-gb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zlfn/rust-gb
- Repository: https://github.com/zlfn/rust-gb

## Overview

##### Supporting Components
As parallel systems interfacing with the main pipeline:

a. Runtime Library Components (src/lib):
- Memory Management
- I/O Operations
- IRQ Handling
- MMIO
- Drawing Functions
- GBDK C Bindings

b. External Tools (ext/):
- GBDK Libraries
- Assembly Resources
- Files
- Binary Tools

##### Key Relationships to Highlight

Critical interactions:
- How the build-rom binary orchestrates the compilation process
- Integration points between Rust code and GBDK libraries
- Memory management flow between Rust and GameBoy hardware
- IRQ and MMIO interactions with the hardware layer

##### Additional Details

Important elements:
- Version compatibility notes
- Hardware target specifications
- Memory model constraints
- Build configuration options

##### Optimization Flow
How the code transforms through each stage:
- Rust high-level optimizations
- LLVM IR optimizations
- Z80/GameBoy-specific optimizations

- The multi-stage compilation process
- The bridge between modern Rust and retro hardware
- Safety guarantees maintained through the compilation chain
- Integration with existing GameBoy development tools

Keep the following in mind:
- Maintain clear separation between build-time and runtime components
- Both the compilation toolchain and the runtime architecture
- Where safety checks and optimizations occur
- Error handling and fallback paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Input
        RustSrc[Rust Source Code]:::rust
        Config[Project Configuration]:::config
    end

    subgraph "Compilation Pipeline"
        direction TB
        RustComp[Rust Compiler]:::rust
        LLVMIR[LLVM-IR Generation]:::llvm
        LLVMCBE[LLVM-CBE Conversion]:::llvm
        SDCC[SDCC Compilation]:::c
        GBDK[GBDK Assembly/Linking]:::gb
        ROM[Final ROM Generation]:::gb
    end

    subgraph "Runtime Library"
        direction TB
        MemMgmt["Memory Management"]:::runtime
        IOOps["I/O Operations"]:::runtime
        IRQHandle["IRQ Handling"]:::runtime
        MMIOInt["MMIO Interface"]:::runtime
        Drawing["Drawing Functions"]:::runtime
        TimeMgmt["Time Management"]:::runtime
    end

    subgraph "GBDK C Bindings"
        direction TB
        Console["Console Interface"]:::gbdk
        Font["Font Handling"]:::gbdk
        GBSpec["GameBoy Specific"]:::gbdk
        DrawInt["Drawing Integration"]:::gbdk
        RNG["Random Number Generator"]:::gbdk
        StdIO["Standard IO"]:::gbdk
    end

    subgraph "External Tools"
        direction TB
        AsmRes["Assembly Resources"]:::ext
        GBDKHead["GBDK Headers"]:::ext
        GBDKLib["GBDK Libraries"]:::ext
        BinTools["Binary Tools"]:::ext
        CRuntime["C Runtime Support"]:::ext
    end

    BuildROM["Build ROM Orchestrator"]:::core

    RustSrc --> RustComp
    Config --> RustComp
    RustComp --> LLVMIR
    LLVMIR --> LLVMCBE
    LLVMCBE --> SDCC
    SDCC --> GBDK
    GBDK --> ROM

    BuildROM --> RustComp

    MemMgmt -.-> GBDK
    IOOps -.-> GBDK
    IRQHandle -.-> GBDK
    MMIOInt -.-> GBDK
    Drawing -.-> GBDK
    TimeMgmt -.-> GBDK

    Console -.-> GBDK
    Font -.-> GBDK
    GBSpec -.-> GBDK
    DrawInt -.-> GBDK
    RNG -.-> GBDK
    StdIO -.-> GBDK

    AsmRes -.-> GBDK
    GBDKHead -.-> GBDK
    GBDKLib -.-> GBDK
    BinTools -.-> BuildROM
    CRuntime -.-> GBDK

    %% Click events for component mapping
    click BuildROM "https://github.com/zlfn/rust-gb/blob/main/src/bin/build-rom/main.rs"
    click MemMgmt "https://github.com/zlfn/rust-gb/blob/main/src/lib/memory.rs"
    click IOOps "https://github.com/zlfn/rust-gb/blob/main/src/lib/io.rs"
    click IRQHandle "https://github.com/zlfn/rust-gb/blob/main/src/lib/irq.rs"
    click MMIOInt "https://github.com/zlfn/rust-gb/blob/main/src/lib/mmio.rs"
    click Drawing "https://github.com/zlfn/rust-gb/blob/main/src/lib/drawing.rs"
    click TimeMgmt "https://github.com/zlfn/rust-gb/blob/main/src/lib/time.rs"
    click Console "https://github.com/zlfn/rust-gb/blob/main/src/lib/gbdk_c/console.rs"
    click Font "https://github.com/zlfn/rust-gb/blob/main/src/lib/gbdk_c/font.rs"
    click GBSpec "https://github.com/zlfn/rust-gb/blob/main/src/lib/gbdk_c/gb/gb.rs"
    click DrawInt "https://github.com/zlfn/rust-gb/blob/main/src/lib/gbdk_c/gb/drawing.rs"
    click RNG "https://github.com/zlfn/rust-gb/blob/main/src/lib/gbdk_c/rand.rs"
    click StdIO "https://github.com/zlfn/rust-gb/blob/main/src/lib/gbdk_c/stdio.rs"
    click AsmRes "https://github.com/zlfn/rust-gb/tree/main/ext/asm/"
    click GBDKHead "https://github.com/zlfn/rust-gb/tree/main/ext/include/gb/"
    click GBDKLib "https://github.com/zlfn/rust-gb/tree/main/ext/lib/gb/"
    click BinTools "https://github.com/zlfn/rust-gb/tree/main/ext/bin/"
    click CRuntime "https://github.com/zlfn/rust-gb/tree/main/ext/c/"

    classDef rust fill:#6b8eff,stroke:#000,stroke-width:2px
    classDef llvm fill:#3fba50,stroke:#000,stroke-width:2px
    classDef c fill:#ffdb4d,stroke:#000,stroke-width:2px
    classDef gb fill:#ff6b6b,stroke:#000,stroke-width:2px
    classDef config fill:#d3d3d3,stroke:#000,stroke-width:2px
    classDef runtime fill:#9d72ff,stroke:#000,stroke-width:2px
    classDef gbdk fill:#ff9e64,stroke:#000,stroke-width:2px
    classDef ext fill:#72d6ff,stroke:#000,stroke-width:2px
    classDef core fill:#ff64b1,stroke:#000,stroke-width:2px
```
