# mighty-gerbils/gerbil architecture

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

- Interactive diagram: https://gitdiagram.com/mighty-gerbils/gerbil
- Repository: https://github.com/mighty-gerbils/gerbil

## Overview

##### Project Type and Purpose
- Gerbil Scheme is a self‑hosted, ahead‑of‑time Scheme dialect and toolchain built on the Gambit runtime.
- It provides:
- An interpreter (`gxi`)
- A compiler (`gxc`)
- A macro and module system
- A large standard library (`src/std`)
- Tooling, tests, docs, and packaging support

##### High‑Level File Structure & Architectural Layers
Top‑level directories:
- `.github`, CI workflows and release pipelines
- `dist/` packaging: Docker, Guix scripts, Homebrew formula
- `doc/` documentation generator (VuePress)
- `src/` core implementation, split into:
– `src/bootstrap/gerbil/` – bootstrap compiler and expander in Scheme → C
– `src/gerbil/` – language implementation (expander, compiler, runtime in Scheme)
– `src/std/` – standard library modules (SRFIs, stdlib subsystems)
– `src/lang/` – language profiles (R7RS, SRFIs)
– `src/tools/` – command‑line utilities and project tools
– `src/gerbil/test/` – unit and integration tests
- Build support: `Makefile`, `configure`, `build.sh`, `src/build/` scripts

##### Core Components & Relationships
A. CLI Frontends
- `gxi` (interpreter) → loads `core` + `runtime` + `stdlib` & spawns REPL
- `gxc` (compiler) → invokes the expander, compiler pipeline, emits C code, invokes Gambit C compiler
B. Bootstrap Subsystem (`src/bootstrap/gerbil/`)
- Provides an initial compiler and expander to compile the full Gerbil implementation
- Inputs: Scheme sources → Outputs: compiled Scheme-to-C compiler/exander binaries
C. Expander Layer (`src/gerbil/expander`)
- Quote‑syntax macro system → syntax‑case implementation
- Module loader, symbol resolution, hygiene support
D. Compiler Layer (`src/gerbil/compiler`)
- Transforms expanded syntax tree → Gambit IR → C source
- Optimization passes (inline, call‑spec, top‑level, etc.)
E. Runtime Layer (`src/gerbil/runtime`)
- Runtime support for control flow, exceptions, threads, I/O, hashing, system calls
- Interfaces to external C libraries: zlib, libssl, SQLite
F. Standard Library (`src/std`)
- Many subsystems: IO, networking, JSON, SSL, actor frameworks, SRFIs, etc.
- Organized by functionality (net, db, fs, crypto, misc)
G. Build & Packaging
- Build scripts in `src/build/`, root `Makefile`, `configure` → orchestrate:
– Bootstrap compile
– Standard library builds
– CLI tool compilation
- `dist/` contains Dockerfile, Guix definitions, Homebrew formula

##### Architectural Patterns & Design Principles
- Layered compiler architecture (bootstrap → expander → compiler → C code → Gambit C compiler)
- Self‑hosting: initial Scheme compiler used to build full system
- Single‑instantiation module system for high‑performance AOT compilation
- Separation of concerns: interpreter vs. compiler vs. runtime vs. stdlib

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Frontends"
        gxi["Interpreter (gxi)"]:::scheme
        gxc["Compiler (gxc)"]:::scheme
    end

    subgraph "Bootstrap Subsystem"
        bootstrap["Bootstrap Compiler"]:::native
    end

    subgraph "Compiler Pipeline"
        expander["Macro Expander"]:::scheme
        compiler["Compiler (AST→IR→C)"]:::scheme
        cgen["C Source"]:::native
    end

    gambit["Gambit C Compiler"]:::native
    exe["Native Executable"]:::native
    runtime["Runtime Layer"]:::scheme
    stdlib["Standard Library"]:::scheme
    ext["External C Libraries"]:::external
    repl["REPL"]:::scheme

    subgraph "Build Orchestration"
        build["Makefile / configure / build.sh / src/build/"]:::build
    end

    subgraph "Packaging Support"
        dist["dist/ (Docker, Guix, Homebrew)"]:::build
    end

    gxc -->|"uses for bootstrap"| bootstrap
    bootstrap -->|"builds expander & compiler"| expander
    gxc -->|"runs pipeline"| expander
    expander -->|"outputs AST"| compiler
    compiler -->|"generates C code"| cgen
    cgen -->|"compiles"| gambit
    gambit -->|"produces"| exe
    exe -->|"links"| runtime
    exe -->|"links"| ext
    gxi -->|"loads"| runtime
    gxi -->|"loads"| stdlib
    gxi -->|"starts"| repl

    build --> gxc
    build --> gxi
    build --> bootstrap
    build --> expander
    build --> compiler
    build --> dist

    click gxi "https://github.com/mighty-gerbils/gerbil/blob/master/src/gerbil/gxi-main.ss"
    click gxc "https://github.com/mighty-gerbils/gerbil/blob/master/src/gerbil/gxc-main.ss"
    click bootstrap "https://github.com/mighty-gerbils/gerbil/tree/master/src/bootstrap/gerbil/"
    click expander "https://github.com/mighty-gerbils/gerbil/tree/master/src/gerbil/expander/"
    click compiler "https://github.com/mighty-gerbils/gerbil/tree/master/src/gerbil/compiler/"
    click runtime "https://github.com/mighty-gerbils/gerbil/tree/master/src/gerbil/runtime/"
    click stdlib "https://github.com/mighty-gerbils/gerbil/tree/master/src/std/"
    click build "https://github.com/mighty-gerbils/gerbil/tree/master/src/build/"
    click dist "https://github.com/mighty-gerbils/gerbil/tree/master/dist/"

    classDef scheme fill:#ccf,stroke:#000,stroke-width:1px
    classDef native fill:#cfc,stroke:#000,stroke-width:1px
    classDef external fill:#fc9,stroke:#000,stroke-width:1px
    classDef build fill:#c9f,stroke:#000,stroke-width:1px
```
