# rui314/8cc architecture

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

- Interactive diagram: https://gitdiagram.com/rui314/8cc
- Repository: https://github.com/rui314/8cc

## Overview

##### Main Components
- Compiler Front-End:
- Preprocessor: Look at files such as cpp.c and the include/ folder (with header definitions) and keyword.inc. This module is responsible for things like macro expansion and handling include directives.
- Lexer: The file lex.c implements the tokenizer, converting source code text into tokens.
- Parser: The parse.c module processes tokens from the lexer to build abstract representations (most likely an abstract syntax tree, AST).
- Compiler Back-End:
- Code Generator: gen.c is likely responsible for generating the target code based on the parsed structure (even if not heavily optimized).
- Other Supporting Modules:
- Utility Libraries: Modules like buffer.c, dict.c, map.c, vector.c, set.c provide data structures and helper routines that underpin the compiler’s internal data management.
- Error and Debug Handling: Files such as error.c and debug.c handle error reporting and debugging support.
- File and I/O Operations: file.c and path.c are used for file management and path resolution.
- Additional Compiler Stages: Other files like encoding.c, keyword.inc, and possibly those inside test/ (which contain unit tests verifying various parts of the language semantics and compiler behavior).

##### Relationships and Interactions
- The main function calls the preprocessor module (cpp.c) to handle macro expansion and other preparatory text transformations.
- The output of the preprocessor feeds into the lexer (lex.c), which tokenizes the source input.
- Tokens are then passed on to the parser (parse.c), which builds an internal representation, typically an AST.
- Once the AST is built, the code generator (gen.c) is invoked to generate the final target code.
- Throughout this process, utility modules (buffer, map, vector, etc.) are used by several components, so they should be shown as shared libraries or supporting modules.
- Testing modules (found in the test/ directory) can be represented separately, emphasizing that they interact with each of these internal components to ensure correctness.

##### Architectural Patterns and Key Design Principles
- Modular Design: The compiler is divided into distinct modules for preprocessing, lexical analysis, parsing, and code generation, which is typical for compiler design.
- Reusability and Conciseness: Utility libraries (e.g., for dynamic arrays, maps, and sets) are reused across multiple components.
- Testing: The rigorous set of unit tests emphasizes that each major component should have clearly defined inputs and outputs.

a. A “Main Application” block (representing main.c) at the top.
- Main Application → Preprocessor Module (cpp.c, keyword.inc, include/*)
- Preprocessor → Lexer Module (lex.c)
- Lexer → Parser Module (parse.c)
- Parser → Code Generator Module (gen.c)
g. Annotations for any nontrivial build targets noted in the Makefile (like the self-compilation stages mentioned in the README such as stage1 → stage2 → stage3).

## Diagram (Mermaid)

```mermaid
flowchart TD
    MainApp["Main Application (main.c)"]:::main
    Preproc["Preprocessor (cpp.c)"]:::frontend
    Encoding["Encoding (encoding.c)"]:::frontend
    Lexer["Lexer (lex.c)"]:::frontend
    Parser["Parser (parse.c)"]:::frontend
    CodeGen["Code Generator (gen.c)"]:::backend

    MainApp -->|"init"| Preproc
    Preproc -->|"macro_expansion"| Encoding
    Encoding -->|"tokens"| Lexer
    Lexer -->|"token_stream"| Parser
    Parser -->|"AST"| CodeGen
    CodeGen -->|"self_hosted_build"| MainApp

    %% Additional Preprocessor Assets
    Preproc -.-> Keyword["keyword.inc"]:::frontend
    Preproc -.-> Include["include/"]:::frontend

    %% Utility Libraries Subgraph
    subgraph "Utility Libraries"
        Buffer["Buffer (buffer.c)"]:::utilities
        Dict["Dictionary (dict.c)"]:::utilities
        Map["Map (map.c)"]:::utilities
        Vector["Vector (vector.c)"]:::utilities
        Set["Set (set.c)"]:::utilities
    end

    %% Connect main compiler components to utilities (dotted arrows)
    Parser ---|"util"| Buffer
    Parser ---|"util"| Dict
    Parser ---|"util"| Map
    Parser ---|"util"| Vector
    Parser ---|"util"| Set

    %% Error and Debug Handling Subgraph
    subgraph "Error and Debug Handling"
        Error["Error (error.c)"]:::errordebug
        Debug["Debug (debug.c)"]:::errordebug
    end

    CodeGen ---|"error"| Error
    CodeGen ---|"debug"| Debug

    %% File and I/O Operations Subgraph
    subgraph "File and I/O Operations"
        File["File (file.c)"]:::io
        Path["Path (path.c)"]:::io
    end

    MainApp ---|"file_IO"| File
    File -->|"path_resolution"| Path

    %% Testing Modules Subgraph
    subgraph "Testing Modules"
        Testing["Testing (test/)"]:::testing
    end

    Testing ---|"validates"| Preproc
    Testing ---|"validates"| Lexer
    Testing ---|"validates"| Parser
    Testing ---|"validates"| CodeGen

    %% Click Events
    click MainApp "https://github.com/rui314/8cc/blob/master/main.c"
    click Preproc "https://github.com/rui314/8cc/blob/master/cpp.c"
    click Encoding "https://github.com/rui314/8cc/blob/master/encoding.c"
    click Lexer "https://github.com/rui314/8cc/blob/master/lex.c"
    click Parser "https://github.com/rui314/8cc/blob/master/parse.c"
    click CodeGen "https://github.com/rui314/8cc/blob/master/gen.c"
    click Keyword "https://github.com/rui314/8cc/blob/master/keyword.inc"
    click Include "https://github.com/rui314/8cc/tree/master/include/"
    click Buffer "https://github.com/rui314/8cc/blob/master/buffer.c"
    click Dict "https://github.com/rui314/8cc/blob/master/dict.c"
    click Map "https://github.com/rui314/8cc/blob/master/map.c"
    click Vector "https://github.com/rui314/8cc/blob/master/vector.c"
    click Set "https://github.com/rui314/8cc/blob/master/set.c"
    click Error "https://github.com/rui314/8cc/blob/master/error.c"
    click Debug "https://github.com/rui314/8cc/blob/master/debug.c"
    click File "https://github.com/rui314/8cc/blob/master/file.c"
    click Path "https://github.com/rui314/8cc/blob/master/path.c"
    click Testing "https://github.com/rui314/8cc/tree/master/test/"

    %% Styling definitions
    classDef main fill:#ffcccb,stroke:#333,stroke-width:2px
    classDef frontend fill:#a1d99b,stroke:#333,stroke-width:2px
    classDef backend fill:#9ecae1,stroke:#333,stroke-width:2px
    classDef utilities fill:#fdae6b,stroke:#333,stroke-width:2px
    classDef errordebug fill:#fcbba1,stroke:#333,stroke-width:2px
    classDef io fill:#c6dbef,stroke:#333,stroke-width:2px
    classDef testing fill:#dadaeb,stroke:#333,stroke-width:2px
```
