EPIC++ Compiler

A complete compiler for the EPIC++ programming language that generates LLVM IR. Built with Python, ANTLR4, and llvmlite.

Features

EPIC++ is a statically-typed, compiled language with:

Types

• Integers: i64, i32, char (8-bit)
• Floating point: f64, f32
• Boolean: bool
• Pointers: *T for any type T
• Arrays: pointer-based with [] indexing
• Strings: null-terminated *char
• Structs: user-defined composite types
• None: void-like type for functions

Language Features

• Functions with parameters and return values
• Variables with block scoping
• Control flow: if/else, while, for loops
• break and continue statements
• Type casting with @ operator
• Pointer operations: new, delete, * (dereference), & (address-of)
• Struct member access: . and ->
• Comparison and logical operators

Example

struct Person {
    name: *char;
    age: i64;
}

func greet(p: *Person): none {
    write("Hello, ", p->name, "! You are ", p->age, " years old.\n");
}

func main(): i64 {
    var p: *Person = new Person;
    p->name = "Alice";
    p->age = 30;
    
    greet(p);
    
    delete p;
    return 0;
}

Installation

Requirements

• Python 3.8+
• UNIX-like OS (Linux, macOS, WSL)

Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/epicpp-compiler.git
cd epicpp-compiler

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install antlr4-python3-runtime antlr4-tools llvmlite==0.43.0

# Build the grammar
antlr4 EpicPP.g4 -Dlanguage=Python3 -visitor

Usage

Compile and Run

python3 runner.py path/to/program.epp

This will:

1. Compile the .epp source to LLVM IR
2. Generate .ll (human-readable IR), .bc (binary IR), and .opt.bc (optimized IR)
3. Execute the program using JIT compilation

Run Tests

# Run all tests
python3 test.py

# Run specific subtask tests (1-9)
python3 test.py 6

Project Structure

├── codegen.py      # Main compiler - AST to LLVM IR translation
├── EpicPP.g4       # ANTLR4 grammar definition
├── runner.py       # Compiler driver and JIT executor
├── runtime.py      # System function injection (I/O, memory)
├── parseutil.py    # Parsing utilities
├── test.py         # Test runner
└── tests/          # Test cases organized by subtask
    ├── 1/          # Basic types and expressions
    ├── 2/          # Variables and scoping
    ├── 3/          # Functions
    ├── 4/          # Booleans
    ├── 5/          # Control flow
    ├── 6/          # Floating point
    ├── 7/          # Pointers
    ├── 8/          # Arrays and strings
    └── 9/          # Structs

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  .epp file  │ ──▶ │   ANTLR4    │ ──▶ │  codegen.py │ ──▶ │  LLVM IR    │
│  (source)   │     │   Parser    │     │  (visitor)  │     │  (.ll/.bc)  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                   │
                                                                   ▼
                                                            ┌─────────────┐
                                                            │     JIT     │
                                                            │  Execution  │
                                                            └─────────────┘

Implementation Highlights

• Two-pass compilation: First declare all structs/functions, then define them (handles forward references)
• Lvalue/Rvalue distinction: Proper handling of assignable vs read-only expressions
• Scope management: Stack-based symbol tables for variable scoping
• LLVM IR generation: Uses llvmlite for type-safe IR construction
• Memory management: Manual allocation via calloc/free wrappers

License

MIT License - feel free to use this project for learning and reference.

Acknowledgments

This compiler was built as part of a programming languages course. The grammar (EpicPP.g4) and test cases were provided as part of the assignment.