# romainpc/decacompiler architecture

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

- Interactive diagram: https://gitdiagram.com/romainpc/decacompiler
- Repository: https://github.com/romainpc/decacompiler

## Overview

##### Project type and purpose
- This is a **compiler** for the Deca language (“Compilateur du langage deca”), implemented in Java, built with Maven.
- It reads `.deca` source files, performs lexing, parsing, AST construction, contextual (semantic) analysis, and emits either IMA assembly (`.ass`) or Java bytecode (via Jasmin, producing `.j` files).

##### File structure
- **Build & tooling**
- `pom.xml` → Maven build, dependencies (ANTLR, Log4j, Jasmin).
- `env_settup.sh`, `wsl_config.sh` → environment scripts.
- `src/main/bin/decac` → CLI launcher shell script.
- `lib/jasmin.jar` → external library for bytecode emission.
- **Grammar & front‐end**
- `src/main/antlr4/.../DecaLexer.g4`, `DecaParser.g4` → ANTLR4 grammar.
- Generates `AbstractDecaLexer`, `AbstractDecaParser`, error listeners, exceptions in `fr.ensimag.deca.syntax`.
- **AST & tree**
- `src/main/java/fr/ensimag/deca/tree` → AST node classes (expressions, statements, declarations).
- **Contextual analysis**
- `src/main/java/fr/ensimag/deca/context` → symbol table, type definitions, contextual error checking.
- **Code generation**
- `src/main/java/fr/ensimag/deca/codegen` → register, memory, label managers, v-tables, dispatching to backends.
- `src/main/java/fr/ensimag/ima/pseudocode` → IR for IMA instructions.
- `src/main/java/fr/ensimag/ima/pseudocode/instructions` → concrete IMA ops.
- `src/main/java/fr/ensimag/ima/pseudocode/jasmin` & `instructions/jasmin` → Jasmin instruction emitter.
- **Resources & tests**
- `src/main/resources/include/Math.decah` → built-in library.
- `src/test` → lexing, syntax, context, codegen, and end-to-end scripts.

##### README for additional insights
- Confirms two backends: `.ass` (IMA) and Java bytecode (`-j` flag).
- Debug levels via `log4j.properties`.
- Test automation via Maven (`mvn test`, `mvn verify`, Jacoco).

a. **Main components**
- **CLI / Driver** (shell script + `DecacMain`)
- **Build System** (Maven)
- **Front-end**
- ANTLR Lexer → tokens
- ANTLR Parser → parse tree
- AST Builder (inferred by parser actions)
- **Semantic (Contextual) Analyzer** (symbol table, type checking)
- **Intermediate Representation** (AST + Pseudocode IR)
- **Backends**
- **IMA Assembly Generator** (`.ass`)
- **Jasmin Bytecode Generator** (`.j`) + external `jasmin.jar`
- **Output / Execution**
- IMA Simulator (external)
- JVM (executes generated `.class` via Jasmin)
b. **Relationships & data flow**
1. User invokes `decac <file>.deca`
2. CLI loads config, sets logging
3. Front-end: ANTLR Lexer → Parser → AST
4. Contextual analysis: AST + `Environment` → type-checked AST
5. Codegen dispatch: type-checked AST →
– IMA IR → `.ass` file
– Jasmin IR → `.j` file → `jasmin.jar` → `.class` bytecode
6. Output written to disk
c. **Architectural patterns**
- **Pipeline** of compiler phases (Front-end → Semantic → Backend)
- **Modular backends** (strategy pattern: pick IMA or Jasmin)
- **Separation of concerns**: grammar, AST, context, codegen, resources, CLI
d. **Key technologies**
- Java 16, Maven
- ANTLR4 (lexer/parser)
- Log4j (debug levels)
- Jasmin (Java bytecode assembler)
- Shell scripts for CLI & tests

##### Elements
- **Clear labels** on each component/module (use the actual package names).
- **Green rectangles** for compiler phases
- **Blue parallelograms** for input/output files
- **Notes or annotations** indicating configuration files (`log4j.properties`, `pom.xml`), command flags, and debug levels.

##### Details
- **essential packages** (`fr.ensimag.deca.syntax`, `.context`, `.tree`, `.codegen`, `.ima.pseudocode`).
- **two output formats** clearly.
- Don’t just group everything under “compiler”—show **each pass** separately.
- **build & launch** steps (Maven → CLI script → Java classes).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Launch
    subgraph "Build & Launch"
        style BuildSystem stroke-dasharray:5 5
        BuildSystem["Maven (pom.xml)"]:::external
        CLI["decac CLI"]:::external
        MainClass["DecacMain"]:::external
    end

    %% Front-end Phase
    subgraph "Front-end" 
        direction TB
        Lexer["ANTLR Lexer\nDecaLexer.g4"]:::phase
        Parser["ANTLR Parser\nDecaParser.g4"]:::phase
        ASTBuilder["AST Builder\nsrc/main/java/fr/ensimag/deca/tree"]:::phase
    end

    %% Semantic Phase
    subgraph "Semantic Analysis"
        direction TB
        SymbolTable["SymbolTable"]:::resource
        Context["Contextual Analyzer\nfr.ensimag.deca.context"]:::phase
    end

    %% IR Phase
    subgraph "Intermediate Representation"
        direction TB
        IMAIR["IMA Pseudocode IR\nfr.ensimag.ima.pseudocode"]:::phase
    end

    %% Backends
    subgraph "Backends"
        direction LR
        IMA["IMA Assembly Backend\nfr.ensimag.deca.codegen"]:::phase
        JasminJar["jasmin.jar"]:::external
        JasminBackend["Jasmin Backend\nfr.ensimag.ima.pseudocode.jasmin"]:::phase
    end

    %% Outputs
    subgraph "Outputs"
        direction TB
        ASS[".ass file"]:::io
        JFiles[".j file"]:::io
        ClassFiles[".class bytecode"]:::io
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        IMASim["IMA Simulator"]:::external
        JVM["JVM"]:::external
    end

    %% Resources & Tests
    subgraph "Resources & Tests"
        Builtin["Math.decah"]:::resource
        Tests["Test Harness\nsrc/test"]:::external
    end

    %% Connections
    CLI -->|"reads .deca"| Lexer
    Lexer --> Parser
    Parser --> ASTBuilder
    ASTBuilder --> Context
    Context --> SymbolTable
    Context --> IMAIR
    IMAIR --> IMA
    IMAIR --> JasminBackend
    IMA --> ASS
    JasminBackend --> JFiles
    JFiles -->|"assemble via jasmin.jar"| ClassFiles
    ASS --> IMASim
    ClassFiles --> JVM
    BuildSystem --> CLI
    BuildSystem --> MainClass
    BuildSystem -->|"config"| Builtin
    Builtin --> ASTBuilder
    Tests --> CLI

    %% Click Events
    click CLI "https://github.com/romainpc/decacompiler/tree/master/src/main/bin/decac"
    click MainClass "https://github.com/romainpc/decacompiler/blob/master/src/main/java/fr/ensimag/deca/DecacMain.java"
    click BuildSystem "https://github.com/romainpc/decacompiler/blob/master/pom.xml"
    click Builtin "https://github.com/romainpc/decacompiler/blob/master/src/main/resources/include/Math.decah"
    click Lexer "https://github.com/romainpc/decacompiler/blob/master/src/main/antlr4/fr/ensimag/deca/syntax/DecaLexer.g4"
    click Parser "https://github.com/romainpc/decacompiler/blob/master/src/main/antlr4/fr/ensimag/deca/syntax/DecaParser.g4"
    click ASTBuilder "https://github.com/romainpc/decacompiler/tree/master/src/main/java/fr/ensimag/deca/tree"
    click Context "https://github.com/romainpc/decacompiler/tree/master/src/main/java/fr/ensimag/deca/context"
    click SymbolTable "https://github.com/romainpc/decacompiler/blob/master/src/main/java/fr/ensimag/deca/tools/SymbolTable.java"
    click IMAIR "https://github.com/romainpc/decacompiler/blob/master/src/main/java/fr/ensimag/ima/pseudocode/IMAProgram.java"
    click IMA "https://github.com/romainpc/decacompiler/tree/master/src/main/java/fr/ensimag/deca/codegen"
    click JasminBackend "https://github.com/romainpc/decacompiler/tree/master/src/main/java/fr/ensimag/ima/pseudocode/jasmin"
    click JasminJar "https://github.com/romainpc/decacompiler/blob/master/lib/jasmin.jar"
    click Tests "https://github.com/romainpc/decacompiler/tree/master/src/test"

    %% Styles
    classDef phase fill:#b7e4c7,stroke:#2b7a0b
    classDef io fill:#caf0f8,stroke:#0077b6
    classDef resource fill:#ffddcc,stroke:#d35400
    classDef external stroke-dasharray:5 5,stroke:#666;font-style:italic
```
