PyCOOLC

An AOT compiler for COOL (Classroom Object Oriented Language), targeting the MIPS 32-bit Architecture and written entirely in Python 3.

COOL is a small statically-typed object-oriented language that is type-safe and garbage collected. It has mainly 3 primitive data types: Integers, Strings and Booleans (true, false). It supports conditional and iterative control flow in addition to pattern matching. Everything in COOL is an expression! Many example COOL programs can be found under the /examples directory.

A BNF-based specification of COOL's Context-Free Grammar can be found at /docs/Grammar.md.

Contents

• Language Features
• Project overview
  • Architecture
  • How it works
• Development status
• How to install
  • Requirements
  • Installing SPIM
  • Installing from source
• How to use
  • Standalone
  • Python modules
  • Makefile commands
• How to test
• References
• License

Language features

• Primitive Data Types:
  • Integers
  • Strings
  • Booleans (true, false)
• Object Oriented:
  • Class Declaration
  • Object Instantiation
  • Inheritance
  • Class Attributes
  • Class Methods
• Strong Static Typing
• Pattern Matching
• Control Flow:
  • Switch Case
  • If/Then/Else
  • While Loops
• Automatic Memory Management:
  • Garbage Collection (planned)

Project overview

Architecture

PyCOOLC follows classical compiler architecture with Frontend and Backend components:

flowchart LR
    subgraph Frontend
        A[Source .cl] --> B[Lexer]
        B --> |tokens| C[Parser]
        C --> |AST| D[Semantic Analysis]
    end
    
    subgraph Backend
        D --> |typed AST| E[IR Builder]
        E --> |TAC| F[Optimizer]
        F --> |optimized TAC| G[Code Generator]
    end
    
    G --> H[MIPS .s]

| Stage | Module | Description | |-------|--------|-------------| | Lexer | lexer.py | Regex-based tokenizer | | Parser | parser.py | LALR(1) parser, builds AST | | Semantic Analysis | semanalyser.py | Type checking, scope analysis, inheritance | | IR Builder | ir/ | Three-Address Code, Control Flow Graph, SSA | | Optimizer | optimization/ | Constant propagation, liveness, dead code elimination | | Code Generator | codegen.py | MIPS 32-bit with dispatch tables and runtime |

How it works

COOL Program:

class Main inherits IO {
   main(): Object { out_string("Hello!\n") };
};

1. Lexer → CLASS, TYPE(Main), INHERITS, TYPE(IO), {, ...
2. Parser → AST with Program → Class → ClassMethod
3. Semantic Analysis → Type-checks out_string call, resolves IO inheritance
4. Code Generation → MIPS assembly with dispatch to IO.out_string

Development status

Each Compiler stage and Runtime feature is designed as a separate component that can be used standalone or as a Python module, the following is the development status of each one:

| Compiler Stage | Python Module | Status | |:-------------------|:--------------------------------------------|:----------------------------| | Lexical Analysis | lexer.py | :white_check_mark: done | | Parsing | parser.py | :white_check_mark: done | | Semantic Analysis | semanalyser.py | :white_check_mark: done | | Optimization | optimization/ | :white_check_mark: done | | Code Generation | codegen.py | :white_check_mark: done | | Garbage Collection | - | :construction: planned |

How to install

Requirements

• Python >= 3.12
• SPIM - MIPS 32-bit Assembly Simulator (see: Installing SPIM).
• All Python packages listed in: requirements.txt.

Installing SPIM

SPIM is a self-contained simulator that runs MIPS32 programs. You'll need it to execute the compiled assembly output.

Download: Get the latest version from SourceForge.

macOS:

# Download and install QtSpim
curl -LO https://sourceforge.net/projects/spimsimulator/files/QtSpim_9.1.24_mac.mpkg.zip
unzip QtSpim_9.1.24_mac.mpkg.zip
open QtSpim_9.1.24_mac.mpkg

# Or use the command-line spim (if installed via homebrew or from source)
brew install spim  # if available

Linux (Debian/Ubuntu):

# Download the .deb package
wget https://sourceforge.net/projects/spimsimulator/files/qtspim_9.1.24_linux64.deb
sudo dpkg -i qtspim_9.1.24_linux64.deb

Windows:

Download QtSpim_9.1.24_Windows.msi from SourceForge and run the installer.

Installing from source

# Clone the repository
git clone https://github.com/aalhour/pycoolc.git
cd pycoolc

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

# Install dependencies and the package
pip install -e .

Or use the Makefile:

make venv
source .venv/bin/activate

How to use

Standalone

Help and usage information:

pycoolc --help

Compile a COOL program:

pycoolc hello_world.cl

Compile multiple files together (classes can reference each other):

pycoolc atoi.cl atoi_test.cl -o atoi_test.s

Specify a custom name for the compiled output program:

pycoolc hello_world.cl --outfile helloWorldAsm.s

Run the compiled program (MIPS machine code) with the SPIM simulator:

spim -file helloWorldAsm.s

Or with QtSpim (GUI):

qtspim helloWorldAsm.s

Skip code generation (type-check only):

pycoolc hello_world.cl --no-codegen

View intermediate representations:

pycoolc hello_world.cl --tokens     # Show lexer output
pycoolc hello_world.cl --ast        # Show parsed AST
pycoolc hello_world.cl --semantics  # Show typed AST

Python modules

from pycoolc.lexer import make_lexer
from pycoolc.parser import make_parser
from pycoolc.semanalyser import make_semantic_analyser
from pycoolc.codegen import make_code_generator

# Lexical analysis
lexer = make_lexer()
lexer.input(a_cool_program_source_code_str)
for token in lexer:
    print(token)

# Parsing
parser = make_parser()
ast = parser.parse(a_cool_program_source_code_str)
print(ast)

# Semantic analysis
analyzer = make_semantic_analyser()
typed_ast = analyzer.transform(ast)

# Code generation
codegen = make_code_generator(analyzer)
mips_code = codegen.generate(typed_ast)
print(mips_code)

Makefile commands

make help              # Show all available targets
make venv              # Create virtual environment
make install           # Install package in development mode
make unit-tests        # Run unit tests
make integration-test  # Run integration tests with SPIM
make test              # Run all tests
make clean             # Clean build artifacts

How to test

PyCOOLC has comprehensive test coverage across all compiler phases:

# Run all unit tests
make unit-tests

# Run integration tests (requires SPIM)
make integration-test

# Run everything
make test

References

• Engineering a Compiler, Cooper and Torczon - Amazon
• Modern Compiler Implementation in ML, Appel - www, Amazon
• Stanford's Compiler Theory Course - www12, www16, YouTube

License

This project is licensed under the MIT License.

All copyrights of the files and documents under the /docs directory belong to their original owners.