DecentClang

A modular compiler pipeline written in Rust. (LLVM/Clang inspired)

---

Overview

DecentClang is a multi-crate Rust workspace implementing a full compilation pipeline:

Oat → Lexer → Parser → Typechecker → LLVMlite IR → x86 IR → Assembler → Executable

The focus of the project is:

• Phase isolation
• Deterministic artifact generation
• Clean intermediate representations
• Compiler-grade CLI ergonomics
• Toolchain architecture clarity

Originally implemented in OCaml (NUS CS4212), rewritten from scratch in Rust with stronger modularity and system-level design.

---

Features

Compiler Pipeline

• Handwritten lexer
• Recursive descent parser
• Type inference and return-path validation
• AST → LLVMlite lowering
• LLVMlite → x86 IR code generation
• Assembly emission
• Executable linking (scaffold)

CLI

• --time stage timing breakdown
• -v verbose diagnostics
• --emit-ir
• --emit-asm
• --out-dir <dir>
• --color auto|always|never
• Structured error formatting with spans

Diagnostics

Example error:

error: mismatched types
  --> examples/broken.oat:12:15
   |
12 |     return x + true;
   |               ^^^^^ expected `int`, found `bool`
note: try converting `true` to an integer

Diagnostics are deterministic and exit codes follow compiler conventions.

---

Quick Start

Build all crates:

cargo build --workspace

Build optimized driver:

cargo build -p driver --release

Run:

./target/release/dclang examples/fact.oat

---

CLI Usage

dclang examples/fact.oat
dclang --time examples/fact.oat
dclang -v --emit-ir --emit-asm --out-dir target/dclang examples/fact.oat

---

Project Structure

DecentClang/
├── lexer/         # Tokenization
├── parser/        # AST construction
├── typechecker/   # Static analysis & inference
├── frontend/      # AST → LLVMlite IR
├── llvm/          # LLVMlite IR definitions
├── backend/       # LLVMlite → x86 IR lowering
├── x86/           # x86 IR modeling
├── assembler/     # Assembly emission & layout
└── driver/        # CLI entrypoint

Each crate compiles independently and exposes a narrow API surface.

---

Design Philosophy

DecentClang emphasizes:

• Clear ownership boundaries between compilation phases
• No hidden global state
• Explicit IR modeling
• Toolchain-like CLI behavior
• Deterministic outputs suitable for automation

The project treats the compiler as developer tooling, not as a UI application.

---

Development

Run tests:

cargo test --workspace

Format:

cargo fmt

Lint:

cargo clippy --workspace -- -D warnings

---

Status

Core pipeline operational. Frontend lowering and full linking evolving. CLI stable and feature-complete for development use.

---

License

MIT