How lemmih/lhc works
Project Type and Purpose
• LHC is a domain‐specific compiler toolchain: it takes Haskell 2010 source code, runs it through parsing, scope resolution, type checking, desugaring, core optimization, and IR lowering (to Bedrock), then emits LLVM IR.
• It also provides a minimal runtime system (RTS) with semispace garbage collection, exception support hooks, and optional libffi integration.
File Structure
• Top‐level “src” directory: contains the compiler driver and pipeline orchestration (Main.hs, CoreToBedrock.hs, RTS.hs).
• “bedrock” directory: Bedrock IR library (parsing, pretty‐printing, LLVM codegen, storage layouts, node sizing).
• “haskell-crux”: desugaring library for Core transformations.
• “packages/lhc-prim”: minimal base library for generated code.
• “rts”: the runtime system C code (semispace GC, stats, API).
• “libffi”: Haskell FFI bindings and examples for foreign calls.
• “tigr”: an experimental interpreter front end (separate tool).
• “examples” and “test”: user programs and test harness.
README for Additional Insights
• README shows the six‐stage pipeline with named libraries:
Parsing (haskell-src-exts) → Name resolution (haskell-scope) → Type-checking (haskell-tc) → Desugaring (haskell-crux) → Optimizing Core (LHC Core) → Bedrock IR → LLVM IR.
• It mentions “--keep-intermediate-files” to inspect each stage.
Main Components and Their Interactions
a. Compiler Front End (Haskell → Core):
• CLI/Driver (src/Main.hs, Interactive.hs)
• Parser (haskell-src-exts)
• Name Resolution (haskell-scope)
• Type Checking (haskell-tc)
• Desugaring (haskell-crux)
b. Core Optimizer and IR Lowering (Core → Bedrock):
• Core optimizer modules (src/Compiler/CoreToBedrock.hs and bedrock/src/Data/Bedrock/…)
• Simplification, inlining, register introduction, storage layout, node sizing, inline‐by‐cost.
c. Backend (Bedrock → LLVM):
• Bedrock LLVMGen (bedrock/src/Data/Bedrock/LLVMGen.hs)
• Pretty printing of .ll files
d. Runtime System and Libraries:
• RTS (rts/gc/semispace.c, api.c, stats.c)
• lhc-prim base library (packages/lhc-prim)
• libffi bindings (for foreign calls)
e. Tools/Tests/Examples:
• Example programs (examples/) compiled by CLI
• Test suite under test/ and lhc-regress
Architectural Patterns and Design Principles
• Pipeline architecture: linear stages, each with its own library.
• Clear separation of concerns: front end vs optimizer vs backend vs runtime.
• Pluggable storage strategies: semi-space, fixed, etc., via typeclasses in bedrock.
• Modular Haskell libraries for each compilation phase.
Essential Architectural Elements to Capture
• Separation between front end, optimizer, backend, and runtime.
• Intermediate IR boundaries (Haskell AST, Core, Bedrock IR, LLVM IR).
• Pluggable GC/storage modules in bedrock.
• Integration of RTS C code and lhc-prim library at link time.
• External toolchain dependencies (Stack, LLVM, cabal-install).
[Source.hs] → (Parser) → (Resolver) → (Type Checker) → (Desugarer) → (Core Optimizer) → (Bedrock IR Generator) → (LLVMGen) → [output.ll]
↳ Link with (lhc-prim) + (RTS: GC, stats, API) + (libffi)