# unight0/stacklisp architecture

> Architecture diagram of the GitHub repository unight0/stacklisp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unight0/stacklisp
- Repository: https://github.com/unight0/stacklisp

## Overview

#### Purpose and Entry Points
Stacklisp is a small Lisp-to-stack-machine toolchain. It translates Lisp source into bytecode, persists that bytecode, and executes or disassembles it on a C-based VM.

Primary command-line entry points:
- `t1.py`: compiler/translator invoked as `./t1 <source>`
- `vm.c`: VM executable supporting `read <bytecode>` and `run <bytecode>`
- `Makefile`: likely builds the native VM and supporting C objects

#### Lisp Front End
The Python front end converts source text into an internal AST before code generation:
- `lexer.py`: tokenizes Lisp syntax
- `parser.py`: parses tokens into syntax trees
- `asttypes.py`: AST node/type definitions
- `t1.py`: orchestrates source loading, parsing, code generation, display, and output writing

Example source programs are root-level `.lisp` files such as `simple.lisp`, `arith.lisp`, `bool.lisp`, and `example.lisp`.

#### Compiler Semantics and Built-ins
Compilation behavior is centered on recognized Lisp forms, commands, and runtime-visible functions:
- `cmds.py`: command/form definitions or translation dispatch
- `binput.py`: bytecode input/output representation or serialization support
- `codegen.py`: lowers parsed Lisp structures into stack-machine bytecode
- `defs.h`: shared opcode/instruction definitions for the native runtime

This is the principal language/runtime boundary: Python must emit bytecode compatible with the C VM’s opcode and value conventions.

#### Bytecode Artifact Boundary
The compiler writes a binary artifact, conventionally `out.bin`, which is later consumed independently by the VM:
- `t1.py`
- `binput.py`
- `out.bin`

The artifact boundary permits translation and execution to run as separate processes. The VM can also read and print bytecode without executing it.

#### Stack-Machine Runtime
The execution engine is implemented in C and operates over an explicit stack abstraction:
- `vm.c`: bytecode loading, instruction dispatch, read/disassembly mode, and run mode
- `stack.c`
- `stack.h`

`vm.c` is the runtime control loop: it reads serialized instructions, manipulates VM state through the stack, and invokes operation implementations.

#### Native Runtime Operations and Shared State
Runtime instruction behavior and system-facing functions are separated from the VM loop:
- `sysfuncs.c`
- `sysfuncs.h`
- `utils.c`
- `utils.h`
- `globals.h`
- `globals_extern.h`

These files define the native support layer for stack operations, built-in/system functions, utilities, and shared global state. They form the key infrastructure boundary beneath bytecode dispatch.

#### End-to-End Flow
1. A Lisp file is passed to `t1.py`.
2. `lexer.py` and `parser.py` construct AST values from source.
3. `codegen.py`, guided by `cmds.py`, emits VM-compatible bytecode.
4. The compiler displays and writes the bytecode artifact.
5. `vm.c` loads the artifact either to print decoded instructions (`read`) or execute them (`run`).
6. The VM dispatches operations against `stack.c` and native runtime services in `sysfuncs.c`.

Main entry points: [`vm.c`](https://github.com/unight0/stacklisp/blob/master/vm.c) (VM control loop), [`codegen.py`](https://github.com/unight0/stacklisp/blob/master/codegen.py) (Code generator), [`sysfuncs.c`](https://github.com/unight0/stacklisp/blob/master/sysfuncs.c) (Native operations), [`parser.py`](https://github.com/unight0/stacklisp/blob/master/parser.py) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Python compiler"]
  node_compiler_cli["Compiler CLI<br/>translator entry point<br/>[t1.py]"]
  node_lexer["Lexer<br/>tokenizer<br/>[lexer.py]"]
  node_parser["Parser<br/>[parser.py]"]
  node_ast_types["AST types<br/>syntax model<br/>[asttypes.py]"]
  node_codegen["Code generator<br/>bytecode lowering<br/>[codegen.py]"]
  node_commands["Forms and commands<br/>translation dispatch<br/>[cmds.py]"]
  node_bytecode_io["Bytecode I/O<br/>serialization<br/>[binput.py]"]
end

subgraph group_artifact["Bytecode boundary"]
  node_out_bin["out.bin<br/>bytecode artifact<br/>[out.bin]"]
end

subgraph group_runtime["Native VM"]
  node_makefile["Native build<br/>build entry point"]
  node_vm["VM control loop<br/>C VM entry point<br/>[vm.c]"]
  node_opcode_defs["Opcode definitions<br/>instruction contract<br/>[defs.h]"]
  node_stack["Stack abstraction<br/>VM state<br/>[stack.c]"]
  node_stack_api["Stack interface<br/>C header<br/>[stack.h]"]
  node_native_ops["Native operations<br/>runtime services<br/>[sysfuncs.c]"]
  node_native_ops_api["Runtime service API<br/>C header<br/>[sysfuncs.h]"]
  node_runtime_support["Runtime support<br/>utilities and shared state<br/>[utils.c]"]
end

node_lisp_source["Lisp source<br/>program input"]

node_lisp_source -->|"compile"| node_compiler_cli
node_compiler_cli -->|"tokenizes"| node_lexer
node_lexer -->|"tokens"| node_parser
node_parser -->|"creates"| node_ast_types
node_parser -->|"AST"| node_codegen
node_codegen -->|"recognized forms"| node_commands
node_codegen -->|"emits"| node_bytecode_io
node_bytecode_io -->|"writes"| node_out_bin
node_opcode_defs -.->|"bytecode contract"| node_codegen
node_makefile -->|"builds"| node_vm
node_out_bin -->|"read or run"| node_vm
node_opcode_defs -->|"instruction definitions"| node_vm
node_vm -->|"manipulates state"| node_stack
node_stack_api -.->|"declares"| node_stack
node_vm -->|"dispatches operations"| node_native_ops
node_native_ops_api -.->|"declares"| node_native_ops
node_native_ops -->|"uses"| node_stack
node_native_ops -->|"uses"| node_runtime_support

click node_compiler_cli "https://github.com/unight0/stacklisp/blob/master/t1.py"
click node_lexer "https://github.com/unight0/stacklisp/blob/master/lexer.py"
click node_parser "https://github.com/unight0/stacklisp/blob/master/parser.py"
click node_ast_types "https://github.com/unight0/stacklisp/blob/master/asttypes.py"
click node_codegen "https://github.com/unight0/stacklisp/blob/master/codegen.py"
click node_commands "https://github.com/unight0/stacklisp/blob/master/cmds.py"
click node_bytecode_io "https://github.com/unight0/stacklisp/blob/master/binput.py"
click node_out_bin "https://github.com/unight0/stacklisp/blob/master/out.bin"
click node_makefile "https://github.com/unight0/stacklisp/blob/master/Makefile"
click node_vm "https://github.com/unight0/stacklisp/blob/master/vm.c"
click node_opcode_defs "https://github.com/unight0/stacklisp/blob/master/defs.h"
click node_stack "https://github.com/unight0/stacklisp/blob/master/stack.c"
click node_stack_api "https://github.com/unight0/stacklisp/blob/master/stack.h"
click node_native_ops "https://github.com/unight0/stacklisp/blob/master/sysfuncs.c"
click node_native_ops_api "https://github.com/unight0/stacklisp/blob/master/sysfuncs.h"
click node_runtime_support "https://github.com/unight0/stacklisp/blob/master/utils.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_compiler_cli,node_lexer,node_parser,node_ast_types,node_codegen,node_commands,node_bytecode_io toneBlue
class node_out_bin toneAmber
class node_makefile,node_vm,node_opcode_defs,node_stack,node_stack_api,node_native_ops,node_native_ops_api,node_runtime_support toneMint
class node_lisp_source toneNeutral
```

## Components

### Python compiler

- [Compiler CLI](https://github.com/unight0/stacklisp/blob/master/t1.py): translator entry point · Loads source and coordinates compilation and output. · `t1.py`
- [Lexer](https://github.com/unight0/stacklisp/blob/master/lexer.py): tokenizer · `lexer.py`
- [Parser](https://github.com/unight0/stacklisp/blob/master/parser.py): AST parser · `parser.py`
- [AST types](https://github.com/unight0/stacklisp/blob/master/asttypes.py): syntax model · `asttypes.py`
- [Code generator](https://github.com/unight0/stacklisp/blob/master/codegen.py): bytecode lowering · `codegen.py`
- [Forms and commands](https://github.com/unight0/stacklisp/blob/master/cmds.py): translation dispatch · `cmds.py`
- [Bytecode I/O](https://github.com/unight0/stacklisp/blob/master/binput.py): serialization · `binput.py`

### Bytecode boundary

- [out.bin](https://github.com/unight0/stacklisp/blob/master/out.bin): bytecode artifact · Persisted compiler output consumed in a separate VM process. · `out.bin`

### Native VM

- [Native build](https://github.com/unight0/stacklisp/blob/master/Makefile): build entry point · `Makefile`
- [VM control loop](https://github.com/unight0/stacklisp/blob/master/vm.c): C VM entry point · Loads bytecode, disassembles it, or dispatches it for execution. · `vm.c`
- [Opcode definitions](https://github.com/unight0/stacklisp/blob/master/defs.h): instruction contract · Shared bytecode opcode and value conventions. · `defs.h`
- [Stack abstraction](https://github.com/unight0/stacklisp/blob/master/stack.c): VM state · `stack.c`
- [Stack interface](https://github.com/unight0/stacklisp/blob/master/stack.h): C header · `stack.h`
- [Native operations](https://github.com/unight0/stacklisp/blob/master/sysfuncs.c): runtime services · Built-ins and system-facing instruction behavior. · `sysfuncs.c`
- [Runtime service API](https://github.com/unight0/stacklisp/blob/master/sysfuncs.h): C header · `sysfuncs.h`
- [Runtime support](https://github.com/unight0/stacklisp/blob/master/utils.c): utilities and shared state · Utilities plus global-state declarations used beneath dispatch. · `utils.c`

### Other components

- **Lisp source**: program input · Root-level example or user .lisp program.

## Connections

- Lisp source → Compiler CLI: compile
- Compiler CLI → Lexer: tokenizes
- Lexer → Parser: tokens
- Parser → AST types: creates
- Parser → Code generator: AST
- Code generator → Forms and commands: recognized forms
- Code generator → Bytecode I/O: emits
- Bytecode I/O → out.bin: writes
- Opcode definitions → Code generator: bytecode contract
- Native build → VM control loop: builds
- out.bin → VM control loop: read or run
- Opcode definitions → VM control loop: instruction definitions
- VM control loop → Stack abstraction: manipulates state
- Stack interface → Stack abstraction: declares
- VM control loop → Native operations: dispatches operations
- Runtime service API → Native operations: declares
- Native operations → Stack abstraction: uses
- Native operations → Runtime support: uses