# kaocy/nctu-compiler architecture

> Architecture diagram of the GitHub repository kaocy/nctu-compiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaocy/nctu-compiler
- Repository: https://github.com/kaocy/nctu-compiler

## Overview

##### Project type and purpose
- This is a multi‐stage compiler homework suite (projects 1–5), each building on the previous:
- project1: lexical analysis (scanner.l)
- project2: syntax analysis (parser.y + scanner.l)
- project3: adds symbol table construction
- project4: adds semantic/type checking
- project5: adds code generation targeting the JVM via Jasmin

##### File structure
- Top-level directories: project1 … project5
- Each project contains:
- Makefile (build orchestration)
- .l and .y source files (Flex & Bison)
- C source for helper modules (symbolTable, symtable, codeGenerator)
- test subdirectories with input programs
- project5 also embeds an external jasmin-2.4 toolchain (Java sources + JARs)

##### README for additional insights
- Confirms grading of each stage
- Notes project5 limitation (unused function return values)

- Scanner (Flex: scanner.l)
- Parser (Bison: parser.y + scanner interface)
- Symbol Table Manager (C modules symtable.c/h or symbolTable.c/h)
- Semantic Analyzer / Type Checker (embedded in parser actions)
- Code Generator (codeGenerator.c/h in project5)
- External Assembler (Jasmin toolchain)
- Driver / Build System (Makefile orchestrating all stages)
- Source .c/.l/.y files → Scanner → token stream
- token stream → Parser → parse tree / AST
- AST → Semantic Analyzer (walks tree, populates symbol table)
- AST + Symbol Table → Code Generator → Jasmin assembly (.j files)
- .j files → Jasmin Assembler → JVM bytecode (.class files)
- Tests feed into the driver, which invokes the pipeline
c. Architectural patterns / design principles:
- Pipeline (linear sequence of compiler phases)
- Modularity: each stage separated into its own directory and module
- Reuse: common .l/.y patterns, shared symbol table interface
d. Technologies / frameworks:
- Flex (lex) for scanner.l
- Bison (yacc) for parser.y
- C99 for parser action code, symbol table, code generator
- Jasmin (Java‐based assembler) for final bytecode emission
- GNU Make for build orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Test Layer
    subgraph "Build & Test" 
        Makefile["Makefile"]:::control
        Tests["Test Harness"]:::control
    end
    Tests --> Makefile

    %% Scanner Layer
    subgraph "Lexical Analyzer (Flex)" 
        P1Scanner["project1/scanner.l"]:::sourceModule
        P2Scanner["project2/scanner.l"]:::sourceModule
        P3Scanner["project3/scanner.l"]:::sourceModule
        P4Scanner["project4/scanner.l"]:::sourceModule
        P5Scanner["project5/scanner.l"]:::sourceModule
    end
    Makefile --> P1Scanner
    Makefile --> P2Scanner
    Makefile --> P3Scanner
    Makefile --> P4Scanner
    Makefile --> P5Scanner

    %% Token Stream Artifact
    TokenStream["Token Stream"]:::artifact
    P1Scanner --> TokenStream
    P2Scanner --> TokenStream
    P3Scanner --> TokenStream
    P4Scanner --> TokenStream
    P5Scanner --> TokenStream

    %% Parser Layer
    subgraph "Syntax Analyzer (Bison)"
        P2Parser["project2/parser.y"]:::sourceModule
        P3Parser["project3/parser.y"]:::sourceModule
        P4Parser["project4/parser.y"]:::sourceModule
        P5Parser["project5/parser.y"]:::sourceModule
    end
    TokenStream --> P2Parser
    TokenStream --> P3Parser
    TokenStream --> P4Parser
    TokenStream --> P5Parser

    AST["AST / Parse Tree"]:::artifact
    P2Parser --> AST
    P3Parser --> AST
    P4Parser --> AST
    P5Parser --> AST

    %% Symbol Table Manager
    subgraph "Symbol Table Manager"
        Sym3["project3/symbolTable.c/h"]:::analysis
        Sym4["project4/symtable.c/h"]:::analysis
        Sym5["project5/symtable.c/h"]:::analysis
    end
    AST --> Sym3
    AST --> Sym4
    AST --> Sym5

    %% Semantic Analyzer / Type Checker
    subgraph "Semantic Analyzer / Type Checker"
        DT4["project4/datatype.h"]:::analysis
        DT5["project5/datatype.h"]:::analysis
        Sem4["Embedded actions in project4/parser.y"]:::analysis
        Sem5["Embedded actions in project5/parser.y"]:::analysis
    end
    AST --> Sem4
    AST --> Sem5
    Sym4 --> Sem4
    Sym5 --> Sem5
    DT4 --> Sem4
    DT5 --> Sem5

    CheckedAST["Checked AST"]:::artifact
    Sem4 --> CheckedAST
    Sem5 --> CheckedAST

    %% Code Generator
    subgraph "Code Generator"
        CodeGen["project5/codeGenerator.c/h"]:::backend
    end
    CheckedAST --> CodeGen

    JasminJ[".j Files"]:::artifact
    CodeGen --> JasminJ

    %% External Assembler (Jasmin)
    subgraph "External Assembler (Jasmin Toolchain)"
        JasminSrc["project5/jasmin-2.4/src"]:::backend
        JasminJar["project5/jasmin-2.4/jasmin.jar"]:::backend
        JasminLib["project5/jasmin-2.4/lib"]:::backend
    end
    JasminJ --> JasminJar
    JasminJ --> JasminSrc
    JasminJ --> JasminLib

    ClassFiles[".class Files"]:::artifact
    JasminJar --> ClassFiles

    %% Click Events
    click P1Scanner "https://github.com/kaocy/nctu-compiler/blob/master/project1/scanner.l"
    click P2Scanner "https://github.com/kaocy/nctu-compiler/blob/master/project2/scanner.l"
    click P3Scanner "https://github.com/kaocy/nctu-compiler/blob/master/project3/scanner.l"
    click P4Scanner "https://github.com/kaocy/nctu-compiler/blob/master/project4/scanner.l"
    click P5Scanner "https://github.com/kaocy/nctu-compiler/blob/master/project5/scanner.l"
    click P2Parser "https://github.com/kaocy/nctu-compiler/blob/master/project2/parser.y"
    click P3Parser "https://github.com/kaocy/nctu-compiler/blob/master/project3/parser.y"
    click P4Parser "https://github.com/kaocy/nctu-compiler/blob/master/project4/parser.y"
    click P5Parser "https://github.com/kaocy/nctu-compiler/blob/master/project5/parser.y"
    click Sym3 "https://github.com/kaocy/nctu-compiler/blob/master/project3/symbolTable.c"
    click Sym3 "https://github.com/kaocy/nctu-compiler/blob/master/project3/symbolTable.h"
    click Sym4 "https://github.com/kaocy/nctu-compiler/blob/master/project4/symtable.c"
    click Sym4 "https://github.com/kaocy/nctu-compiler/blob/master/project4/symtable.h"
    click Sym5 "https://github.com/kaocy/nctu-compiler/blob/master/project5/symtable.c"
    click Sym5 "https://github.com/kaocy/nctu-compiler/blob/master/project5/symtable.h"
    click DT4 "https://github.com/kaocy/nctu-compiler/blob/master/project4/datatype.h"
    click DT5 "https://github.com/kaocy/nctu-compiler/blob/master/project5/datatype.h"
    click CodeGen "https://github.com/kaocy/nctu-compiler/blob/master/project5/codeGenerator.c"
    click CodeGen "https://github.com/kaocy/nctu-compiler/blob/master/project5/codeGenerator.h"
    click JasminSrc "https://github.com/kaocy/nctu-compiler/tree/master/project5/jasmin-2.4/src"
    click JasminJar "https://github.com/kaocy/nctu-compiler/blob/master/project5/jasmin-2.4/jasmin.jar"
    click JasminLib "https://github.com/kaocy/nctu-compiler/tree/master/project5/jasmin-2.4/lib"
    click Makefile "https://github.com/kaocy/nctu-compiler/tree/master/project5/Makefile"

    %% Styles
    classDef sourceModule fill:#ADD8E6,stroke:#000;
    classDef analysis fill:#90EE90,stroke:#000;
    classDef backend fill:#FFA500,stroke:#000;
    classDef control fill:#D3D3D3,stroke:#000;
    classDef artifact fill:#CCCCCC,stroke:#000;
```
