# felipensp/vtcc architecture

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

- Interactive diagram: https://gitdiagram.com/felipensp/vtcc
- Repository: https://github.com/felipensp/vtcc

## Overview

##### Main Components
- Frontend/CLI Module: Represented by the vtcc executable and the main entry point (hello.c is used as a sample C source file). This includes the command-line interface that accepts input files and flags (e.g., -run, -h, etc.).
- Parser and Preprocessor: Although not pinpointed with a specific “lexer” file, several files like tccpp.v indicate preprocessing and parsing responsibilities.
- Code Generation Module: Files such as tccgen.v, tccasm.v, and x86_64-gen.v focus on converting the high-level representation into architecture-specific assembly.
- Backend Linking and Executable Generation: Components like x86_64-link.v and modules within src (tcctools.v, tccrun.v) manage linking and the final executable output.
- Debugging and Symbol Information: Files including tccdbg.v, and support for DWARF (dwarf.h.v) and ELF (elf.h.v) suggest components meant for debugging and handling executable metadata.
- Libraries and Runtime Support: The lib directory contains helper modules (e.g., libtcc.v, bt-log.v, bt-exe.v) and runtime libraries (libtcc1 and its internal files) that the compiler relies on during generation and execution.
- Build Scripts: The make.vsh file serves as the build script for compiling vtcc itself, so it is part of the infrastructure rather than the runtime architecture but should be noted.

##### Relationships and Interactions
- The CLI (vtcc executable) is the entry point that receives source code (e.g., hello.c) and passes it to the parser/preprocessor.
- After parsing, the resulting internal representation is fed into the code generation modules, which then may call architecture-specific generators (x86_64-gen.v) and perform assembly-level optimizations.
- Next, the linker/assembler component assembles and links the compiled modules and integrates runtime libraries from the “lib” folder (libtcc1) to produce the final executable.
- Debug and symbol generation modules (tccdbg.v, dwarf.h.v, elf.h.v) create debuggable metadata alongside the final binary.
- Optional routes exist for dynamic linking and external dependencies via tools and flags (for example, linking with libraries like pthread as indicated in the README).

##### Architectural Patterns and Technologies
- Although vtcc is a monolithic compiler, its source structure clearly separates concerns by module (frontend, backend, code generation, etc.), echoing ideas from classical compiler design.
- The design leverages the capabilities of V language and integrates external C libraries (notice vlang.c is provided, and there are interfaces to system libraries) to implement core functionalities.
- The use of external build scripts (make.vsh) and testing (tests directory) reinforces a structured development environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI/Frontend
    subgraph "CLI/Frontend"
        CLI["CLI/Frontend (hello.c)"]:::frontend
    end

    %% Parser/Preprocessor
    subgraph "Parser/Preprocessor"
        Parser["Parser/Preprocessor (tccpp.v)"]:::parser
    end

    %% Code Generation
    subgraph "Code Generation"
        CodeGen["CodeGen (tccgen.v)"]:::codegen
        Tccasm["Assembly (tccasm.v)"]:::codegen
        ArchGen["x86_64 Gen (x86_64-gen.v)"]:::codegen
    end

    %% Linking & Executable Generation
    subgraph "Linking & Backend"
        Linker["Linker & Assembler (x86_64-link.v)"]:::linker
        Tcctools["tcctools (tcctools.v)"]:::linker
        Tccrun["tccrun (tccrun.v)"]:::linker
    end

    %% Debugging and Symbol Information
    subgraph "Debug & Metadata"
        Debugger["Debugger (tccdbg.v)"]:::debug
        DWARF["DWARF (dwarf.h.v)"]:::debug
        ELF["ELF (elf.h.v)"]:::debug
        Tccelf["Tccelf (tccelf.v)"]:::debug
    end

    %% Libraries & Runtime Support
    subgraph "Libraries & Runtime Support"
        LibTcc["Compiler Runtime (src/libtcc.v)"]:::library
        LibTcc1["LibTcc1 (libtcc1)"]:::library
        BtLog["bt-log (bt-log.v)"]:::library
        BtExe["bt-exe (bt-exe.v)"]:::library
    end

    %% Build Infrastructure
    subgraph "Build Infrastructure"
        Build["Build Script (make.vsh)"]:::build
    end

    %% Final Output
    Final["Final Executable"]:::final

    %% Connections
    CLI -->|"parse"| Parser
    Parser -->|"generateIR"| CodeGen
    CodeGen -->|"toAssembly"| Linker
    Linker -->|"produce"| Final

    %% Libraries feeding into Linking
    LibTcc -->|"runtime"| Linker
    LibTcc1 -->|"runtime"| Linker
    BtLog -->|"logging"| Linker
    BtExe -->|"execution"| Linker

    %% Debug modules attaching metadata
    Debugger -->|"debugInfo"| Final
    DWARF -->|"DWARF"| Final
    ELF -->|"ELF"| Final
    Tccelf -->|"ELFHandling"| Final

    %% Build script influences the overall process
    Build --- CLI

    %% Click Events
    click CLI "https://github.com/felipensp/vtcc/blob/main/hello.c"
    click Parser "https://github.com/felipensp/vtcc/blob/main/src/tccpp.v"
    click CodeGen "https://github.com/felipensp/vtcc/blob/main/src/tccgen.v"
    click Tccasm "https://github.com/felipensp/vtcc/blob/main/src/tccasm.v"
    click ArchGen "https://github.com/felipensp/vtcc/blob/main/src/x86_64-gen.v"
    click Linker "https://github.com/felipensp/vtcc/blob/main/src/x86_64-link.v"
    click Tcctools "https://github.com/felipensp/vtcc/blob/main/src/tcctools.v"
    click Tccrun "https://github.com/felipensp/vtcc/blob/main/src/tccrun.v"
    click Debugger "https://github.com/felipensp/vtcc/blob/main/src/tccdbg.v"
    click DWARF "https://github.com/felipensp/vtcc/blob/main/src/dwarf.h.v"
    click ELF "https://github.com/felipensp/vtcc/blob/main/src/elf.h.v"
    click Tccelf "https://github.com/felipensp/vtcc/blob/main/src/tccelf.v"
    click LibTcc "https://github.com/felipensp/vtcc/blob/main/src/libtcc.v"
    click LibTcc1 "https://github.com/felipensp/vtcc/tree/main/lib/libtcc1"
    click BtLog "https://github.com/felipensp/vtcc/blob/main/lib/bt-log.v"
    click BtExe "https://github.com/felipensp/vtcc/blob/main/lib/bt-exe.v"
    click Build "https://github.com/felipensp/vtcc/blob/main/make.vsh"

    %% Styles
    classDef frontend fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef parser fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef codegen fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef linker fill:#fff5cc,stroke:#333,stroke-width:2px;
    classDef debug fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef library fill:#cceedd,stroke:#333,stroke-width:2px;
    classDef build fill:#e6e6e6,stroke:#333,stroke-width:2px;
    classDef final fill:#e0ffe0,stroke:#333,stroke-width:2px;
```
