# multidustry/mlogjit architecture

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

- Interactive diagram: https://gitdiagram.com/multidustry/mlogjit
- Repository: https://github.com/multidustry/mlogjit

## Overview

##### Project type and purpose
- This is a compiler‐style project: a JIT (just‐in‐time) compiler called “Mlogjit” for the Mindustry Logic (MLOG) language.
- Purpose: take MLOG text, parse it, build an intermediate representation (IR), then use Cranelift to emit native machine code, and finally execute that code against a ProcessorContext.

##### File structure
Top‐level:
- Cargo.toml / Cargo.lock – Rust package and dependency manifests
- README.md – project overview
src/ directory:
- parser.rs – MLOG text → AST/IR parser
- ir.rs – definition of the intermediate representation (Instr, types)
- jit.rs – orchestration of Cranelift JITModule, function signatures, codegen entrypoint
- compiled_function.rs – wrappers around the compiled code and JITModule handles
- ctx.rs – ProcessorContext struct (register file, stack, calling conventions)
- env.rs – trait definition for ProcessorEnv, DummyProcessorEnv, I/O hooks
- oper_functions/ – implementations of individual arithmetic or math operations (add, mul, pow, etc.)
- lib.rs – public API exports (JitCompiler, parse_code, ProcessorContext)
- main.rs – optional CLI/demo entrypoint

##### README for additional insights
- It describes the pipeline: parse_code → Vec<Instr> → JitCompiler.compile → machine‐code function pointer → extern “C” invocation
- Mentions Cranelift integration, performance metrics, and planned future additions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and API
    CLI["CLI / Demo\n(main.rs)"]:::api
    API["Public API\n(lib.rs)"]:::api
    CLI -->|"uses"| API
    API -->|"parse_code() / JitCompiler"| Parser

    %% Source Code
    Source["Source Code\n(MLOG text)"]:::parsing
    Source -->|"text"| Parser

    %% Parsing & IR
    Parser["Parser Module\n(parser.rs)"]:::parsing
    IR["Intermediate Representation\n(ir.rs)"]:::parsing
    Parser -->|"Vec<Instr>"| IR

    %% Codegen & JIT
    Codegen["JIT Compiler Frontend\n(jit.rs)"]:::codegen
    Ops["Operations\n(src/oper_functions/)"]:::codegen
    IR -->|"Vec<Instr>"| Codegen
    Codegen -->|"uses operations"| Ops

    %% External Cranelift
    Cranelift["Cranelift JIT Back-end\n(external)"]:::external
    Codegen -->|"Cranelift IR"| Cranelift

    %% Compiled Function Handle
    CompFunc["CompiledFunction & JITModule\n(compiled_function.rs)"]:::codegen
    Cranelift -->|"Machine Code Buffer"| CompFunc

    %% Execution & Runtime
    ExecCtx["Execution Engine\nProcessorContext\n(ctx.rs)"]:::runtime
    Env["Environment Abstraction\n(env.rs)"]:::runtime
    CompFunc -->|"function pointer"| ExecCtx
    ExecCtx -->|"I/O / hooks"| Env
    ExecCtx -->|"executes code"| Machine

    Machine["Native Machine Code / CPU"]:::runtime

    %% Click Events
    click Parser "https://github.com/multidustry/mlogjit/blob/master/src/parser.rs"
    click IR "https://github.com/multidustry/mlogjit/blob/master/src/ir.rs"
    click Codegen "https://github.com/multidustry/mlogjit/blob/master/src/jit.rs"
    click Ops "https://github.com/multidustry/mlogjit/tree/master/src/oper_functions/"
    click CompFunc "https://github.com/multidustry/mlogjit/blob/master/src/compiled_function.rs"
    click ExecCtx "https://github.com/multidustry/mlogjit/blob/master/src/ctx.rs"
    click Env "https://github.com/multidustry/mlogjit/blob/master/src/env.rs"
    click API "https://github.com/multidustry/mlogjit/blob/master/src/lib.rs"
    click CLI "https://github.com/multidustry/mlogjit/blob/master/src/main.rs"

    %% Styles
    classDef parsing fill:#e0f7fa,stroke:#006064,color:#000;
    classDef codegen fill:#fff9c4,stroke:#f57f17,color:#000;
    classDef runtime fill:#c8e6c9,stroke:#2e7d32,color:#000;
    classDef external fill:#ffcdd2,stroke-dasharray: 5 5,stroke:#b71c1c,color:#000;
    classDef api fill:#d1c4e9,stroke:#4a148c,color:#000;
```
