# konas122/sysy-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/konas122/sysy-compiler
- Repository: https://github.com/konas122/sysy-compiler

## Overview

##### Project Type and Purpose
- This is a compiler for the SysY language.
- It implements the classic compilation pipeline: lexical analysis, parsing, semantic/type analysis, AST construction, and x86 code generation.
- It uses Flex (lexer), Bison (parser), and the GNU toolchain (assembler/linker).

##### File Structure
- **Top‑level scripts & configs**
- `makefile`, `batch_compile.sh`, `compile.sh`
- **Source directory (`src/`)**
- Lexical spec: `sysy.l`
- Grammar: `sysy.y`
- Driver: `main.cpp`
- AST & symbol tables: `tree.cpp/h`, `type.cpp/h`, `common.h`, `global.h`
- **Build artifacts**
- `build/` (placeholder)
- `out/` (generated assembly / binaries)
- **Tests**
- `test/syntax/` (syntax‑level conformance)
- `test/semantic/` (semantic checks)
- `test/asm_test/` (end‑to‑end code‑generation validation)

##### Extract Architecture Insights from README
- The compile steps map to make targets:
- `make syntaxX` → generate AST for syntax tests
- `make checkX` → semantic checks
- `make run` / scripts → generate & assemble x86 code
- Outputs: AST in `result.txt` (debug), assembly in `.asm`, object files via `as`, executables via `gcc -m32`.

##### Main Components & Interactions
a. **Frontend**
- Lexer (Flex/runs `sysy.l`)
- Parser (Bison/runs `sysy.y`)
- AST Builder (in `tree.cpp/h`)
b. **Semantic Analyzer**
- Symbol Table & Type Checker (in `type.cpp/h`, `global.h`)
c. **Code Generator**
- AST → x86 Assembly emitter (`main.cpp` orchestration + emitter code)
d. **Assembler & Linker**
- External Tools: `as`, `gcc -m32`
e. **Build & Test Harness**
- Scripts: `makefile`, `batch_compile.sh`, `compile.sh`
- Test Suites: syntax, semantic, asm_test

##### Relationships & Data Flow
- Source Code (`.c`) → [Lexer] → token stream
- Token stream → [Parser] → parse tree/AST
- AST → [Semantic Analyzer] → annotated AST or error reports
- Annotated AST → [Code Generator] → x86 `.asm` file
- `.asm` → [Assembler → Object] → [Linker → Executable]
- Tests feed source into this pipeline, validate outputs.

##### Architectural Patterns & Principles
- **Pipeline**: clear separation of compilation stages
- **Modularity**: each stage implemented in its own source files
- **Tool Integration**: Flex/Bison and GCC toolchain as external “services”
- **Test‑Driven**: separate directories for syntax, semantic, and codegen tests

##### Final Checklist
- [ ] Groupings for “Compiler Core”, “Build & Test Harness”, “Output Artifacts”
- [ ] Optional: annotate where files live (`src/`, `test/`, `out/`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Compiler Core
    subgraph "Compiler Core"
        direction TB
        Lexer["Lexer"]:::internal
        Parser["Parser"]:::internal
        ASTBuilder["AST Builder"]:::internal
        SemAnalyzer["Semantic Analyzer"]:::internal
        CodeGen["Code Generator"]:::internal
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        Flex["Flex"]:::external
        Bison["Bison"]:::external
        Assembler["Assembler (as)"]:::external
        Linker["Linker (gcc -m32)"]:::external
    end

    %% Build & Test Harness
    subgraph "Build & Test Harness"
        direction TB
        makefile["makefile"]:::script
        batch["batch_compile.sh"]:::script
        compile["compile.sh"]:::script
        subgraph "Test Suites"
            direction TB
            syntaxTests["test/syntax/"]:::tests
            semanticTests["test/semantic/"]:::tests
            asmTests["test/asm_test/"]:::tests
        end
    end

    %% Artifacts
    subgraph "Output Artifacts"
        direction TB
        Tokens["Token Stream"]:::artifact
        AST["AST"]:::artifact
        AnnotAST["Annotated AST"]:::artifact
        ASM["Assembly (.asm)"]:::artifact
        OBJ["Object File (.o)"]:::artifact
        EXE["Executable"]:::artifact
        DebugAST["Debug AST (result.txt)"]:::artifact
    end

    %% Data Flow
    src["Source Code (.c)"]:::artifact
    src -->|"source"| Flex
    Flex -->|"tokens"| Lexer
    Lexer -->|"tokens"| Parser
    Bison -->|"parse"| Parser
    Parser -->|"AST"| ASTBuilder
    ASTBuilder -->|"AST"| SemAnalyzer
    SemAnalyzer -->|"annotated AST"| CodeGen
    CodeGen -->|".asm"| ASM
    ASM -->|".asm"| Assembler
    Assembler -->|".o"| OBJ
    OBJ -->|".o"| Linker
    Linker -->|"executable"| EXE
    ASTBuilder -->|"result.txt"| DebugAST

    %% Tests triggering
    syntaxTests -->|"make syntaxX"| Parser
    semanticTests -->|"make checkX"| SemAnalyzer
    asmTests -->|"make run"| CodeGen

    %% Scripts triggering
    makefile -->|"goals"| Flex
    batch -->|"batch compile"| CodeGen
    compile -->|"compile"| CodeGen

    %% Class Definitions
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef external fill:#D5F5E3,stroke:#1D8348,color:#145A32
    classDef script fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef tests fill:#FADBD8,stroke:#C0392B,color:#641E16
    classDef artifact fill:#F2F3F4,stroke:#7B7D7D,color:#1C2833

    %% Click Events
    click Lexer "https://github.com/konas122/sysy-compiler/blob/main/src/sysy.l"
    click Parser "https://github.com/konas122/sysy-compiler/blob/main/src/sysy.y"
    click ASTBuilder "https://github.com/konas122/sysy-compiler/blob/main/src/tree.cpp"
    click ASTBuilder "https://github.com/konas122/sysy-compiler/blob/main/src/tree.h"
    click SemAnalyzer "https://github.com/konas122/sysy-compiler/blob/main/src/type.cpp"
    click SemAnalyzer "https://github.com/konas122/sysy-compiler/blob/main/src/type.h"
    click SemAnalyzer "https://github.com/konas122/sysy-compiler/blob/main/src/global.h"
    click SemAnalyzer "https://github.com/konas122/sysy-compiler/blob/main/src/common.h"
    click CodeGen "https://github.com/konas122/sysy-compiler/blob/main/src/main.cpp"
    click makefile "https://github.com/konas122/sysy-compiler/tree/main/makefile"
    click batch "https://github.com/konas122/sysy-compiler/blob/main/batch_compile.sh"
    click compile "https://github.com/konas122/sysy-compiler/blob/main/compile.sh"
    click syntaxTests "https://github.com/konas122/sysy-compiler/tree/main/test/syntax/"
    click semanticTests "https://github.com/konas122/sysy-compiler/tree/main/test/semantic/"
    click asmTests "https://github.com/konas122/sysy-compiler/tree/main/test/asm_test/"
```
