FolkSong

The compiler + runtime that ties Odin's pure-Odin toolchain together into a usable whole: checking, native codegen, interpretation, module packaging, caching, overrides, and compile-time metaprogramming.

FolkSong is the conductor. It owns no frontend of its own — it orchestrates a frontend and (currently) two pluggable backends, all in the same repo:

FolkSong  (this project — BarnYard, .chkn-coop, driver, intercepts)
├── frontend/          — odin-squared: the checker (typed AST + CheckerInfo)
├── backend-llvm/      — LLVM backend (AST → native) — production path
├── backend-cranelift/ — Cranelift backend (AST → native) — fast-iter, in development
└── ../odin-vm2/       — bytecode interpreter (AST → bytecode → run) — optional sibling repo

The name

A folk song is a tune that gets passed around — everyone plays their own rendition, but it's recognizably the same song. In FolkSong, the interpreter and the native backend are two renditions of the same checked AST: same tune, different players. See the FolkSong dual- backend execution model in spec/j0_design.md.

The theme runs through the architecture:

• BarnYard — the top-level coordinator per compilation (where the session happens)
• .chkn-coop — the compiled module file (where the chickens roost)
• FolkSong — the dual-backend execution (the tune everyone plays)
• Cuttin' heads — the oracle cross-check (interp vs native, head to head, outputs must match)

What FolkSong provides

• BarnYard — per-compilation coordinator: module DAG, resolver + overrides, GOT-based linking, diagnostics, lifetimes
• .chkn-coop — immutable, self-describing, mmap-friendly fat module files: full AST + LLVM bitcode + per-ISA native + DWARF + const pool + structural import/export tables
• FolkSong dual-backend — native (LLVM backend) is THE execution path; Cranelift is the in-development fast-iteration backend; the vm2 interp is an optional dev/oracle backend rendering the same AST
• Compiler intercepts — Jai-style metaprogram message loop; the main program drives the build by draining a message stream
• Build system — recompile decisions (mtime-based in v1), distinct from the file format and the loader
• Bootstrap — host → guest environment injection (argc/argv, @(init) procs, runtime startup)

What FolkSong does NOT own

• The checker — odin-squared
• Native codegen — backend-llvm (LLVM) and backend-cranelift (Cranelift, WIP)
• The bytecode interpreter + bytecode format — odin-vm2
• Runtime conventions (foreign bridge, host intrinsics) — currently odin-vm2; may be extracted to a shared module later

Status

Design phase. See docs/PLAN.md for the phased plan and docs/STATUS.md for current progress. The architecture is specified in spec/j0_design.md.

Naming history note: the LLVM backend was originally called odin-gaud in the design docs. It was renamed to backend-llvm when backend-cranelift joined as a second backend; older docs may still reference odin-gaud and mean the same component.

Layout

FolkSong/
├── README.md
├── docs/
│   ├── PLAN.md          # phased plan (J0 ... J10)
│   └── STATUS.md        # progress dashboard, updated each session
├── spec/
│   └── j0_design.md     # the architecture spec
├── src/                 # implementation (empty — J0 not started)
└── cmd/                 # driver entry points (empty)