# yubrot/llrl architecture

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

- Interactive diagram: https://gitdiagram.com/yubrot/llrl
- Repository: https://github.com/yubrot/llrl

## Overview

Based on our analysis of the complete file tree and the README, the project is an experimental Lisp-like programming language called “llrl” that emphasizes creating a self-hosting compiler. There are two main compiler implementations provided:
- llrl0 – a Rust-based compiler that implements the language with a full compilation pipeline (parsing, semantic analysis, lowering, code generation, and driver) and supports multiple backends (LLVM, chibi, and native).
- llrl1 – a self-hosting version of the compiler written using llrl itself and ported to the LLVM-C API.
In addition, there are supporting libraries and tools:
- llvm0 and llvm1 – libraries/wrappers around LLVM functionality and tests.
- rt – the runtime effort that ties into glibc/Boehm GC and provides low-level runtime services.
- std – the standard library for llrl that provides built-in types, macros, and functionality.
- xten0, xten1, and xtencg – components for the x86_64 code generation, including a custom assembler and JIT linker used (for example) by the chibi backend.
- testcases and examples – which show various usage scenarios and serve as regression or demonstration tests.

##### Overall Structure and Components
a. Frontends and Parsing:
– Represent the S-expression lexer and parser found in both llrl0 and llrl1.
– Include AST construction, as shown by all the “ast.rs”, “parser”, “syntax”, and “sexp” modules.
b. Semantic Analysis:
c. Lowering and Transformation:
– Illustrate the “lowering” modules that transform high-level AST representations (with macros and S-expressions) into an intermediate representation (IR).
d. Code Generation and Backends:
– This is a critical piece. Separate the code generation pipeline into:
- LLVM Backend – directories under backend/llvm in both llrl0 and llrl1.
- Chibi/Natively targeted Backend – shown under backend/chibi and backend/native along with calls to the xten components.
e. Runtime and Standard Library:
– Include the “rt” module, the “std” directory (which contains standard library definitions and bootstrapping code), and mention the prerequisites (glibc, Boehm GC).
f. Supporting Libraries and Tools:
– Represent llvm0/llvm1 as shared LLVM utility libraries.
– Represent xten0, xten1, and xtencg as separate modules providing JIT/linking and assembly functionality.
– Show “testcases” and “examples” as external modules used for demonstration and verification.

##### Relationships and Flow
[Source Input] → [Lexing/Parsing] → [AST Formation] → [Semantic Analysis (imports, type inference, name resolution)] → [Lowering (IR generation and transformation)] → [Code Generation] → [Backend Processing (LLVM/chibi/native)]
– Also show a separate connection from the code generation component to “xten modules” if the chibi (x86_64-targeted) backend is used.
– Highlight that both compiler implementations (llrl0 and llrl1) share similar pipelines but differ in their implementation language and subtle processing differences.

##### Architectural Patterns and Design Principles
– Emphasize a modular layered design where each stage of the compilation process (parsing, semantic analysis, lowering, code generation) is encapsulated in its dedicated module.
– Demonstrate the separation between core language processing and the libraries/tools (i.e. standard library, runtime, assembler/JIT linker in xten).

## Diagram (Mermaid)

```mermaid
flowchart TD
    SC["Source Code (S-expression input)"]:::source

    FE["Frontend (Lexing, Parsing, AST)"]:::frontend
    SA["Semantic Analysis (Name Resolution, Type/Kind Inference, Pattern Matching)"]:::semantic
    LWR["Lowering & IR Transformation"]:::lowering
    CG["Code Generation"]:::codegen

    LLVM["LLVM Backend"]:::backend
    CHIBI["Chibi Backend"]:::backend
    NATIVE["Native Backend"]:::backend

    LUTIL["LLVM Utilities (llvm0/llvm1)"]:::util
    XTEN["x86_64 Utilities (xten0/xten1/xtencg)"]:::util

    RT["Runtime Support (rt)"]:::runtime
    STD["Standard Library (std)"]:::runtime

    TE["Testcases & Examples"]:::test

    %% Pipeline Flow
    SC --> FE
    FE --> SA
    SA --> LWR
    LWR --> CG

    %% Code Generation branches
    CG --> LLVM
    CG --> CHIBI
    CG --> NATIVE

    %% LLVM branch to utilities and runtime/standard lib
    LLVM --> LUTIL
    LUTIL --> RT
    LUTIL --> STD

    %% Chibi and Native branches converge to x86_64 utilities
    CHIBI --> XTEN
    NATIVE --> XTEN

    %% Final testing/demonstration stage
    RT --> TE

    %% Self-hosting feedback loop (llrl1)
    CG -.->|"Self-hosting"| FE

    %% Click Events for Frontend Components (llrl0 and llrl1)
    click FE "https://github.com/yubrot/llrl/blob/main/llrl0/src/lexer.rs"
    click FE "https://github.com/yubrot/llrl/blob/main/llrl0/src/parser/grammar.rs"
    click FE "https://github.com/yubrot/llrl/tree/main/llrl0/src/ast"
    click FE "https://github.com/yubrot/llrl/tree/main/llrl0/src/sexp"
    click FE "https://github.com/yubrot/llrl/blob/main/llrl1/sexp/lexer.llrl"
    click FE "https://github.com/yubrot/llrl/blob/main/llrl1/sexp/parser.llrl"

    %% Click Events for Semantic Analysis Components
    click SA "https://github.com/yubrot/llrl/blob/main/llrl0/src/module/sema/resolver.rs"
    click SA "https://github.com/yubrot/llrl/tree/main/llrl0/src/module/sema/type_inference"
    click SA "https://github.com/yubrot/llrl/blob/main/llrl0/src/module/sema/kind_inference.rs"
    click SA "https://github.com/yubrot/llrl/blob/main/llrl0/src/pattern_matching/pattern.rs"
    click SA "https://github.com/yubrot/llrl/blob/main/llrl1/module/sema/resolver.llrl"
    click SA "https://github.com/yubrot/llrl/tree/main/llrl1/module/sema/type-inference"

    %% Click Events for Lowering Components
    click LWR "https://github.com/yubrot/llrl/tree/main/llrl0/src/lowering"
    click LWR "https://github.com/yubrot/llrl/tree/main/llrl0/src/lowering/ir"
    click LWR "https://github.com/yubrot/llrl/blob/main/llrl1/lowering.llrl"
    click LWR "https://github.com/yubrot/llrl/blob/main/llrl1/lowering/branch-expander.llrl"
    click LWR "https://github.com/yubrot/llrl/blob/main/llrl1/lowering/ir.llrl"

    %% Click Events for LLVM Backend Components
    click LLVM "https://github.com/yubrot/llrl/blob/main/llrl0/src/backend/llvm/codegen.rs"
    click LLVM "https://github.com/yubrot/llrl/blob/main/llrl0/src/backend/llvm/executor.rs"
    click LLVM "https://github.com/yubrot/llrl/blob/main/llrl0/src/backend/llvm/runtime.rs"
    click LLVM "https://github.com/yubrot/llrl/blob/main/llrl1/backend/llvm/codegen.llrl"
    click LLVM "https://github.com/yubrot/llrl/blob/main/llrl1/backend/llvm/executor.llrl"
    click LLVM "https://github.com/yubrot/llrl/blob/main/llrl1/backend/llvm/runtime.llrl"

    %% Click Events for Chibi Backend Components
    click CHIBI "https://github.com/yubrot/llrl/tree/main/llrl0/src/backend/chibi"
    click CHIBI "https://github.com/yubrot/llrl/tree/main/llrl1/backend/chibi"

    %% Click Events for Native Backend Components
    click NATIVE "https://github.com/yubrot/llrl/blob/main/llrl0/src/backend/native/calling.rs"
    click NATIVE "https://github.com/yubrot/llrl/blob/main/llrl0/src/backend/native/linking.rs"
    click NATIVE "https://github.com/yubrot/llrl/blob/main/llrl1/backend/native/calling.llrl"
    click NATIVE "https://github.com/yubrot/llrl/blob/main/llrl1/backend/native/linking.llrl"

    %% Click Events for Runtime and Standard Library
    click RT "https://github.com/yubrot/llrl/blob/main/rt/llrt.rs"
    click RT "https://github.com/yubrot/llrl/blob/main/rt/rt.c"
    click RT "https://github.com/yubrot/llrl/blob/main/rt/rt.h"
    click STD "https://github.com/yubrot/llrl/tree/main/std/boot"

    %% Click Events for LLVM Utility Libraries
    click LUTIL "https://github.com/yubrot/llrl/blob/main/llvm0/src/module.rs"
    click LUTIL "https://github.com/yubrot/llrl/blob/main/llvm0/src/type_builder.rs"
    click LUTIL "https://github.com/yubrot/llrl/blob/main/llvm1/module.llrl"
    click LUTIL "https://github.com/yubrot/llrl/blob/main/llvm1/context.llrl"

    %% Click Events for x86_64 Code Generation Utilities
    click XTEN "https://github.com/yubrot/llrl/tree/main/xten0/src/asm"
    click XTEN "https://github.com/yubrot/llrl/tree/main/xten0/src/jit"
    click XTEN "https://github.com/yubrot/llrl/tree/main/xten1/asm"
    click XTEN "https://github.com/yubrot/llrl/tree/main/xten1/jit"
    click XTEN "https://github.com/yubrot/llrl/tree/main/xtencg/src/instr"
    click XTEN "https://github.com/yubrot/llrl/blob/main/xtencg/src/render.rs"

    %% Click Events for Testcases and Examples
    click TE "https://github.com/yubrot/llrl/blob/main/examples/hello-world.llrl"
    click TE "https://github.com/yubrot/llrl/blob/main/examples/fibonacci-numbers.llrl"
    click TE "https://github.com/yubrot/llrl/blob/main/testcases/000-build-ast.llrl"
    click TE "https://github.com/yubrot/llrl/blob/main/testcases/001-resolve.llrl"

    %% Style Definitions
    classDef source fill:#FFF2CC,stroke:#000,stroke-width:1px;
    classDef frontend fill:#FFCCCC,stroke:#333,stroke-width:1px;
    classDef semantic fill:#CCFFCC,stroke:#333,stroke-width:1px;
    classDef lowering fill:#CCCCFF,stroke:#333,stroke-width:1px;
    classDef codegen fill:#FFDDAA,stroke:#333,stroke-width:1px;
    classDef backend fill:#E0CCFF,stroke:#333,stroke-width:1px;
    classDef runtime fill:#CCE5FF,stroke:#333,stroke-width:1px;
    classDef util fill:#D1F7D1,stroke:#333,stroke-width:1px;
    classDef test fill:#F0F0F0,stroke:#333,stroke-width:1px

%% It is important to be as detailed as possible so that every element—from source parsing to code generation and linking—is visible; this will help in understanding and extending the compiler in the future.
```
