# buildit-lang/buildit architecture

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

- Interactive diagram: https://gitdiagram.com/buildit-lang/buildit
- Repository: https://github.com/buildit-lang/buildit

## Overview

##### Project type and purpose
- BuildIt is a C++ library/framework (not a standalone application) for multi‑stage code generation and rapid DSL development.
- It exposes a header‑only API (in include/) and a compiled implementation (in src/) that works with any standard C++ compiler.

##### Top‑level architectural components
a. BuildIt Core Library
- API Layer (include/)
– builder/ : public types and functions for dyn_var, static_var, builder_context, annotations, generics
– blocks/  : definitions of AST nodes (block, stmt, expr, var), matchers, visitors, replacers
– util/    : auxiliary components (printer, tracer, var_finder)
- Implementation Layer (src/)
– src/builder/ : actual implementations of builder methods, context support, generics
– src/blocks/  : implementations of block visitors, code generator, loop finders, extract_cuda, var_namer, etc.
– src/util/    : tracer and var_finder implementations

b. External Dependencies
– deps/d2x : optional debugging library that plugs into BuildIt core via util/tracer
– Standard C++ toolchain (g++, GNU make)

c. Build System
– Makefiles and build rules (make/, make/buildit_rules.mk, make/deps.mk, etc.)
– CI workflows under .github/workflows and Travis config

d. Sample DSLs and Tests
– samples/ : dozens of example .cpp files written with dyn_var/static_var APIs
– samples/outputs/ : expected generated code outputs and var name mappings to validate correctness

##### Relationships and Data Flow
- A user’s .cpp that includes <builder/dyn_var.h> invokes the Builder API
→ Builder constructs a lightweight AST of “blocks” and “stmts”
→ AST passes through block visitors & matchers that perform rewrites (loop_finder, if_switcher, rce, etc.)
→ c_code_generator (in blocks/) emits final target code (C++ loops, CUDA pragmas, etc.)
→ util/printer formats generated code; util/tracer can instrument runtime for debugging (via d2x)
- BuilderContext orchestrates multi‑stage code specialization using static_var, dyn_var and generics

##### Architectural Patterns and Principles
- Visitor Pattern: src/blocks/block_visitor operates over AST node types
- Builder Pattern: builder::Builder constructs AST incrementally, supports annotations
- Multi‑stage Programming: separation of “definition stage” (dyn_var expressions) vs. “codegen stage” (static code)
- Modular Design: well‑defined modules (builder, blocks, util) each with clear responsibilities
- Extensibility Points: custom matchers/replacers can be plugged into the blocks pipeline

##### Detail Checklist
- AST (blocks) as a first‑class component with edges to visitors and the code generator

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entry
    A["User DSL Code\n(samples/*.cpp)"] 

    %% Public API Layer
    subgraph "Public API" 
        direction TB
        API1["Builder Module\n(include/builder)"] 
        API2["Blocks Module\n(include/blocks)"]
        API3["Utilities Module\n(include/util)"]
    end

    %% Core Implementation Layer
    subgraph "Core Implementation"
        direction TB
        IMP1["Builder Impl\n(src/builder)"]
        IMP2["Blocks Impl\n(src/blocks)"]
        IMP3["Utilities Impl\n(src/util)"]
    end

    %% AST and Pipeline
    subgraph "Codegen Pipeline"
        direction TB
        AST["AST\n(blocks)"]
        VIS["Visitors & Transformers\n(src/blocks)"]
        CG["Code Generator\n(src/blocks)"]
        PR["Printer\n(src/util)"]
        TR["Tracer\n(src/util)"]
        OUT["Generated Code\n(samples/outputs/sample*)"]
    end

    %% External Dependencies
    subgraph "External Dependencies"
        D2X["d2x Debugger\n(deps/d2x)"]
    end

    %% Build System
    subgraph "Build System"
        direction TB
        MF["Makefile"]
        MR1["buildit_rules.mk\n(make/buildit_rules.mk)"]
        MR2["deps.mk\n(make/deps.mk)"]
        MR3["tests.mk\n(make/tests.mk)"]
    end

    %% CI Workflows
    subgraph "CI Workflows"
        direction TB
        GH["GitHub Actions\n(.github/workflows/ci-all-samples.yml)"]
        TRV["Travis CI\n(.travis.yml)"]
    end

    %% Samples Outputs
    SO1["Sample Outputs\n(samples/outputs/sample*)"]
    SO2["Var Name Mappings\n(samples/outputs.var_names/sample*)"]

    %% Relationships
    A -->|"includes dyn_var API"| API1
    API1 -->|"depends on"| IMP1
    API2 -->|"defines AST"| AST
    API3 -->|"auxiliary funcs"| PR
    AST -->|"visit()"| VIS
    VIS -->|"generate()"| CG
    CG -->|"format()"| PR
    PR -->|"instrument()"| TR
    TR -->|"plugins via"| D2X
    CG -->|"emit code"| OUT
    MF -->|"builds"| IMP1
    MF -->|"builds"| IMP2
    MF -->|"builds"| IMP3
    MF -->|"compiles to lib"| OUT
    MR1 --> MF
    MR2 --> MF
    MR3 --> MF
    GH -->|"runs tests on"| SO1
    GH -->|"validates against"| SO2
    TRV -->|"runs tests on"| SO1
    TRV -->|"validates against"| SO2

    %% Click Events
    click API1 "https://github.com/buildit-lang/buildit/tree/master/include/builder"
    click API2 "https://github.com/buildit-lang/buildit/tree/master/include/blocks"
    click API3 "https://github.com/buildit-lang/buildit/tree/master/include/util"
    click IMP1 "https://github.com/buildit-lang/buildit/tree/master/src/builder"
    click IMP2 "https://github.com/buildit-lang/buildit/tree/master/src/blocks"
    click IMP3 "https://github.com/buildit-lang/buildit/tree/master/src/util"
    click D2X "https://github.com/buildit-lang/buildit/tree/master/deps/d2x"
    click MF "https://github.com/buildit-lang/buildit/tree/master/Makefile"
    click MR1 "https://github.com/buildit-lang/buildit/blob/master/make/buildit_rules.mk"
    click MR2 "https://github.com/buildit-lang/buildit/blob/master/make/deps.mk"
    click MR3 "https://github.com/buildit-lang/buildit/blob/master/make/tests.mk"
    click GH "https://github.com/buildit-lang/buildit/blob/master/.github/workflows/ci-all-samples.yml"
    click TRV "https://github.com/buildit-lang/buildit/blob/master/.travis.yml"
    click A "https://github.com/buildit-lang/buildit/blob/master/samples/*.cpp"
    click OUT "https://github.com/buildit-lang/buildit/tree/master/samples/outputs/sample*"
    click SO2 "https://github.com/buildit-lang/buildit/tree/master/samples/outputs.var_names/sample*"

    %% Styles
    classDef publicAPI fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef coreImpl fill:#90EE90,stroke:#333,stroke-width:1px
    classDef utilities fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px

    class API1,API2,API3 publicAPI
    class IMP1,IMP2,IMP3 coreImpl
    class PR,TR utilities
    class D2X external
    class MF,MR1,MR2,MR3 external
    class GH,TRV external
    class A,OUT,SO1,SO2 external
```
