How mighty-gerbils/gerbil works
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