# spydr06/bcause architecture

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

- Interactive diagram: https://gitdiagram.com/spydr06/bcause
- Repository: https://github.com/spydr06/bcause

## Overview

##### Project type and purpose
- BCause is a single-pass compiler for the historic B language, written in C99.
- Its role is to take a .b source file, parse and translate it to x86_64 machine code via GNU binutils, and link it against a minimal B standard library (libb.a).

##### File structure
Top level:
- Makefile, README.md, LICENSE → build and documentation.
- examples/ → sample B programs.
- src/
- src/compiler/ → the compiler proper, comprising:
– main.c: entry point and CLI driver
– compiler.c/h: orchestration of compilation stages
– list.c/h: internal linked‐list utility for AST or token lists
- src/libb/ → implementation of B’s standard library, built into libb.a.
- tests/ → googletest-based unit and integration tests (CMakeLists.txt plus .cpp files).

##### README for additional insights
- The README confirms the use of GNU make, binutils (as, ld), and C99.
- It describes supported language features (globals, functions, flow control, expressions).
- It shows that no extra dependencies beyond libc/binutils are used.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Input
    UserSource["User .b File"]:::external

    %% Compiler Subsystem
    subgraph "Compiler (src/compiler)" 
        direction TB
        CLI["CLI Front-end\n(main.c)"]:::compiler
        Parser["Lexical Analyzer & Parser\n(compiler.c/h)"]:::compiler
        IR["AST/IR Representation\n(list.c/h)"]:::compiler
        CodeGen["Code Generator\n(compiler.c)"]:::compiler
    end

    %% External Tools
    subgraph "External Binutils"
        direction TB
        Assembler["GNU Assembler (as)"]:::external
        Linker["GNU Linker (ld)"]:::external
    end

    %% Standard Library
    subgraph "Standard Library"
        LibB["libb.a\n(src/libb)"]:::library
    end

    %% Build System
    MakefileNode["Makefile"]:::external

    %% Testing and Examples
    subgraph "Testing & Examples"
        direction TB
        Tests["Test Harness\n(tests/)"]:::test
        Examples["Example B Programs\n(examples/)"]:::test
    end

    %% Flow
    UserSource -->|provides .b file| CLI
    CLI -->|token stream| Parser
    Parser -->|build AST/IR| IR
    IR -->|IR data| CodeGen
    CodeGen -->|.s assembly| Assembler
    Assembler -->|.o object file| Linker
    LibB -->|static lib| Linker
    Linker -->|executable| Executable["Final Executable"]:::external

    %% Tests and Examples Flow
    Examples -->|sample input| CLI
    Tests -->|invoke CLI & verify| CLI

    %% Build
    MakefileNode -->|drives build| CLI
    MakefileNode -->|invokes as/ld| Assembler
    MakefileNode -->|invokes as/ld| Linker
    MakefileNode -->|compiles libb| LibB

    %% Click Events
    click CLI "https://github.com/spydr06/bcause/blob/main/src/compiler/main.c"
    click Parser "https://github.com/spydr06/bcause/blob/main/src/compiler/compiler.c"
    click Parser "https://github.com/spydr06/bcause/blob/main/src/compiler/compiler.h"
    click IR "https://github.com/spydr06/bcause/blob/main/src/compiler/list.c"
    click IR "https://github.com/spydr06/bcause/blob/main/src/compiler/list.h"
    click CodeGen "https://github.com/spydr06/bcause/blob/main/src/compiler/compiler.c"
    click Assembler "https://github.com/spydr06/bcause/tree/main/Makefile"
    click Linker "https://github.com/spydr06/bcause/tree/main/Makefile"
    click LibB "https://github.com/spydr06/bcause/blob/main/src/libb/libb.c"
    click Tests "https://github.com/spydr06/bcause/tree/main/tests/"
    click Examples "https://github.com/spydr06/bcause/tree/main/examples/"

    %% Styles
    classDef compiler fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#bbf,stroke:#333,stroke-width:1px
    classDef library fill:#bfb,stroke:#333,stroke-width:1px
    classDef test fill:#fbf,stroke:#333,stroke-width:1px
```
