GLaDOS

GLaDOS is a tiny Lisp environment written in Haskell: a front-end that parses and compiles Lisp programs and a bytecode virtual machine that runs them. The project started as a student exercise and grew into a complete toolchain capable of handling real-world Lisp snippets.

What you get

• A readable compiler pipeline (parser → macros → desugaring → SSA-like lowering → bytecode)
• A stack-based VM with tail-call optimisation, closures, and a small standard library
• Ready-to-run examples plus a Jenkins-backed functional regression suite
• Haskell sources that can be hacked on with stack or the provided Makefile

Quick tour

# Build the executable (uses stack under the hood)
make

# Run a Lisp file
./glados examples/factorial_test.lisp

# Peek at the generated bytecode
./glados --disasm examples/factorial_test.lisp

# Dump raw bytecode instructions
./glados --bytecode examples/factorial_test.lisp

# Run the Haskell unit tests locally
stack test

The resulting binary reads a .lisp file, compiles it to bytecode, loads the builtins from src/Builtins.hs, and executes the program on the VM. Functional tests now run automatically in Jenkins after every push.

Learn the project

• docs/README.md — map of the documentation set
• docs/ARCHITECTURE.md — how the compiler and VM are structured
• docs/LANGUAGE_GUIDE.md — how to write programs for our Lisp dialect
• docs/INSTRUCTIONS.md — bytecode and runtime reference
• docs/DEVELOPMENT.md — build, test, and debugging workflows

Repository layout

.
├── app/                 Main CLI wiring
├── docs/                Project documentation
├── examples/            Sample Lisp programs
├── scripts/             Helper scripts used by tooling
├── src/                 Compiler, runtime, and builtins
├── test/                Haskell unit tests
└── Makefile             Shortcuts around stack

Key sources worth opening:

• src/Compiler.hs — orchestration of all compilation passes
• src/CodeGen.hs — lowers ANF into bytecode instructions
• src/VM.hs — the execution loop and call-stack management
• src/Builtins.hs — implementation of primitives like +, format, read-line

Current status

• Tail-call optimisation is enabled by default (cfgTCO = True)
• Jenkins runs the full functional regression suite on every branch; check the latest build before merging
• Known limitations and TODOs are tracked in CHANGELOG.md

License

This repository is released under the MIT licence (see LICENSE).