How lyledean1/cyclang works
Project type and purpose
• Cyclang is a custom programming language implementation written in Rust.
• It consists of a command‑line compiler (and REPL), a PEG‑based parser, and an LLVM‑based backend that generates machine code.
• Its purpose is to read .cyc source files (or REPL input), parse them into an AST, perform semantic checks/codegen, and produce an executable.
File structure
• Top‐level crates folder holds three Rust crates:
– cyclang‑parser: grammar and parsing logic (uses Pest)
– cyclang‑backend: compiler pipeline, semantic context, code generation modules, stdlib embedding
– cyclang: the CLI driver and REPL entry point
• examples/ contains sample .cyc programs.
• book/ holds generated documentation (user guide).
• Dev environment: Docker (devcontainer), GitHub Actions, Makefile for LLVM setup.
Core architecture (compiler pipeline)
We can abstract the run of cyclang --file foo.cyc into the following stages:
1. CLI Driver (crates/cyclang/src/main.rs)
– Parses command‑line flags, selects file or REPL mode
2. Parser (crates/cyclang-parser)
– Reads source text → Pest grammar → Concrete parse tree → converts to AST
3. Semantic Context & Analysis (in cyclang-backend/src/compiler/context.rs)
– Type checking, symbol resolution, scope management
4. Intermediate Representation & CodeGen (cyclang-backend/src/compiler/codegen)
– Builds LLVM IR via llvm-sys bindings
– Embeds stdlib modules (list, string)
– Target abstraction (cyclang-backend/src/compiler/codegen/target.rs)
– Caching layer to avoid repeated builds
5. LLVM Optimization & Code Emission (via llvm-sys linking to libLLVM-19)
6. Native Binary Output or JIT Execution (for REPL)
Special guidance for a compiler‐style project
• Lay out the compiler stages in left‑to‑right (or top‑to‑bottom) sequence.
• External dependencies (Pest grammar file, LLVM library).
• How stdlib IR artifacts are loaded/generated.
• Optional REPL flow branching from the driver to a JIT execution path.
Essential details without clutter
• Major modules with their crate name (e.g., “cyclang-parser crate”).