How theunrealtarik/fcpu works
FFC is a Rust-based compiler pipeline for a .fac source language. The top-level executable is in src/main.rs, while src/lib holds the compiler subsystems. The README’s diagram matches the code layout: Source input is parsed into a program model, lowered, assembled, and emitted as final code.
The frontend boundary lives in src/lib/frontend. It is split into lexemes.rs, token.rs, ast.rs, and parser.rs, which indicates a conventional lexical-analysis → tokenization → AST construction flow. The parser produces the higher-level statement/program representation referenced in the README (Vec<StatementContext>).
The backend boundary lives in src/lib/backend. It is subdivided into ir.rs, low.rs, asm.rs, and emit.rs, which suggests a staged transformation chain from AST/program structures into an intermediate representation, then into a lower-level form, and finally into assembled output. The README explicitly names the middle stages as “Program,” “Lowerer,” and “Assembler.”
Several backend files point to compiler-internal concerns rather than code generation alone: mem.rs, symbol.rs, and tags.rs. These likely manage storage layout, symbol resolution, and metadata/tagging used across lowering and assembly. In architecture terms, these are shared support services consumed by the lowering and emission stages.
src/lib/error.rs is the shared error boundary for the whole compiler. Because every stage in a compiler can fail independently, this file likely centralizes diagnostics and propagates errors from lexing through code emission.
src/lib/mod.rs and the nested module structure show the public API surface of the library crate. The compiler core is therefore reusable as a library, with the binary wrapper in main.rs likely acting as the command-line entry point and orchestration layer.
The README image makes the data flow explicit: source text is converted into parser output, then into a program representation, then lowered and assembled into Vec<Instruction> and finally into “Code.” That means the diagram should show a clear one-way pipeline with no visible runtime server or web boundary.
The test/ directory contains focused .fac cases such as break.fac, cast.fac, cond.fac, loop.fac, math.fac, scope.fac, and unary.fac. These are feature-oriented compiler tests that exercise control flow, expressions, scoping, and type/operation handling, so they validate frontend parsing and backend lowering semantics rather than application behavior.
The scripts/signals/ folder is an auxiliary tooling boundary. Its Lua files and dl_dump.sh look like support scripts for generating or inspecting raw signal/data files, separate from the Rust compiler proper. They appear to be offline tooling rather than part of the main compilation pipeline.
Cargo.toml, Cargo.lock, and Makefile.toml indicate a standard Rust build setup with additional task automation. For architecture purposes, treat Cargo as the primary build/runtime system and the makefile as convenience tooling around compilation and testing.
Overall, the project is best diagrammed as a compiler with three major layers: frontend parsing, backend lowering/assembly, and shared compiler services (errors, symbols, memory/tags), with tests and scripts sitting beside the main pipeline as validation and tooling.
Main entry points: lib/mod.rs Library · backend/mod.rs Backend · frontend/mod.rs Frontend · low.rs Lowering
Components 17
Compiler
Rust compiler crate and its pipeline
- CLI · Command-line wrapper that orchestrates compilation
src/main.rs - Library · Public compiler library surface
src/lib/mod.rs - Frontend · Source text to structured program representation
src/lib/frontend/mod.rs - Lexemes · Breaks source into lexical units
src/lib/frontend/lexemes.rs - Tokens · Token definitions and token stream structure
src/lib/frontend/token.rs - AST · Parsed statement and program structures
src/lib/frontend/ast.rs - Parser · Builds the higher-level program context from tokens
src/lib/frontend/parser.rs - Errors · Shared compiler error boundary
src/lib/error.rs - Backend · Transforms program structures into final code
src/lib/backend/mod.rs - IR · Intermediate program representation
src/lib/backend/ir.rs - Lowering · Converts program IR into lower-level form
src/lib/backend/low.rs - Assembler · Shapes lowered data into instructions
src/lib/backend/asm.rs - Emitter · Produces final output code
src/lib/backend/emit.rs - Layout · Shared storage and layout support used by backend stages
src/lib/backend/mem.rs - Game · Additional library subsystem outside the core pipeline
src/lib/game/mod.rs
Tooling
Auxiliary scripts and build automation
- Signals · Offline scripts for dumping or inspecting signal data
scripts/signals/main.lua
Validation
Feature-oriented compiler tests
- FAC tests · Feature-focused .fac inputs for parser and codegen behavior
test/break.fac
Connections 19
- CLI → Library: uses · Binary drives the library compiler pipeline
- Library → Frontend: exposes · Public crate surface includes frontend stages
- Library → Backend: exposes · Public crate surface includes backend stages
- Library → Errors: shares · Errors are propagated across the compiler
- Library → Game: includes · Additional library module beside the compiler pipeline
- Frontend → Lexemes: scans · Frontend begins by splitting source into lexemes
- Lexemes → Tokens: forms · Lexemes are converted into tokens
- Tokens → AST: builds · Tokens feed AST and statement structures
- AST → Parser: parsed by · Parser constructs the higher-level program context
- Parser → Backend: hands off · Parsed program flows into backend processing
- Backend → IR: represents · Backend starts from program IR
- IR → Lowering: lowers · IR is lowered into a more concrete form
- Lowering → Assembler: assembles · Lowered form is assembled into instructions
- Assembler → Emitter: emits · Assembler output is turned into final code
- Layout → Lowering: supports · Storage/layout support informs lowering
- Layout → Assembler: supports · Backend assembly uses shared layout metadata
- FAC tests → Frontend: validates · Test cases exercise parsing and syntax handling
- FAC tests → Backend: validates · Test cases exercise lowering and code generation
- Signals → Backend: supports · Auxiliary scripts operate beside compiler output