# nosba0957/shecc architecture

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

- Interactive diagram: https://gitdiagram.com/nosba0957/shecc
- Repository: https://github.com/nosba0957/shecc

## Overview

##### Project type and purpose
- Project type: a self-hosting, educational C optimizing compiler written in ANSI C.
- Purpose: take a subset of C source code and generate 32-bit ARMv7-A or RISC-V (RV32IM) ELF binaries. It bootstraps itself through three stages, runs snapshot tests on IR, and provides a minimal embedded C library.

##### File structure
Top-level directories and key files:
- .ci / .github – CI scripts and workflows for formatting, testing, bootstrapping.
- mk/ – per-architecture Makefile fragments (arm.mk, riscv.mk, common.mk).
- Makefile – orchestrates configuration, build stages, tests, snapshots, cleaning.
- src/ – compiler source code:
– front-end: lexer.c, parser.c
– middle-end: ssa.c, peephole.c, reg-alloc.c
– back-ends: arm.c + arm-codegen.c, riscv.c + riscv-codegen.c
– auxiliary: globals.c, defs.h, elf.c, main.c
- lib/ – minimal C runtime (libc) implementation (c.c).
- tools/ – standalone utilities (inliner.c).
- tests/ – snapshot tests (driver.sh), C test programs (fib.c, hello.c), expected IR JSON.

##### README for additional insights
- Two-pass compilation: pass1 (syntax checking & lowering), pass2 (machine code generation).
- IR: SSA-based middle-end for optimization.
- Bootstrapping: stage0 (host compiler), stage1 & stage2 (self-compiled with QEMU).
- Options: --dump-ir, --no-libc, +m (hardware multiply), -o output.
- Tests: snapshot regression of emitted IR, unit tests via `make check`.

a. Main components
1. Front-end
– Lexer (src/lexer.c)
– Parser (src/parser.c)
2. IR Builder & Middle-end
– Lowering to basic operations (pass1 in main.c)
– SSA construction (src/ssa.c)
– Peephole optimizer (src/peephole.c)
3. Register Allocator (src/reg-alloc.c)
4. Backends
– ARM backend (src/arm.c + src/arm-codegen.c)
– RISC-V backend (src/riscv.c + src/riscv-codegen.c)
5. ELF Emitter (src/elf.c)
6. Embedded libc (lib/c.c)
7. Build subsystem
– Makefile + mk/*.mk for architecture selection
8. Test harness
– Snapshot driver (tests/driver.sh)
– QEMU invocation for bootstrapping

b. Relationships and data flow
- Source .c file → Lexer → Parser → AST / Lowered IR
- IR → SSA conversion → Optimizer (peephole) → Optimized IR
- Optimized IR → Register allocator → Target-specific codegen
- Code generator → Machine instructions → ELF sections
- Link in embedded libc → Final ELF binary
- ELF binary fed to QEMU (for stage bootstrapping) and to snapshot tests
- Makefile invokes compiler binary with flags (--dump-ir, +m, etc.)
- Tests compare dumped IR JSON against snapshots using jq and graphviz

c. Architectural patterns and design principles
- Two-phase pipeline (front-end vs. back-end)
- SSA-based middle-end for optimizations
- Target abstraction: common interface for register allocation and codegen, pluggable per-architecture
- Self-hosted bootstrapping (stage0 → stage1 → stage2)
- Snapshot-based regression for deterministic IR

d. Key technologies and libraries
- ANSI C (compiler code)
- Make + shell scripts for build/test
- QEMU user emulation (arm/riscv)
- JSON snapshots, jq, graphviz (IR dumps & tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end
    subgraph "Front-end"
        Lexer["Lexer\nsrc/lexer.c"]:::frontend
        Parser["Parser\nsrc/parser.c"]:::frontend
    end
    Lexer --> Parser

    %% Middle-end
    subgraph "Middle-end"
        Lower["Lowering (pass1)\nsrc/main.c"]:::middle
        SSA["SSA Construction\nsrc/ssa.c"]:::middle
        Peephole["Peephole Optimizer\nsrc/peephole.c"]:::middle
        RegAlloc["Register Allocator\nsrc/reg-alloc.c"]:::middle
    end
    Parser --> Lower --> SSA --> Peephole --> RegAlloc

    %% Back-end
    subgraph "Back-end"
        ARM_IF["ARM Backend Interface\nsrc/arm.c"]:::backend
        ARM_CG["ARM Code Generator\nsrc/arm-codegen.c"]:::backend
        RISC_IF["RISC-V Backend Interface\nsrc/riscv.c"]:::backend
        RISC_CG["RISC-V Code Generator\nsrc/riscv-codegen.c"]:::backend
        ELF["ELF Emitter\nsrc/elf.c"]:::backend
        LibC["Embedded libc\nlib/c.c"]:::backend
        FinalELF["Final ELF Binary"]:::data
    end
    RegAlloc --> ARM_IF --> ARM_CG --> ELF
    RegAlloc --> RISC_IF --> RISC_CG --> ELF
    ELF --> LibC --> FinalELF

    %% Bootstrapping loop
    subgraph "Bootstrapping"
        Stage0["Stage0 Compiler"]:::build
        Stage1["Stage1 Compiler"]:::build
        Stage2["Stage2 Compiler"]:::build
    end
    FinalELF --> Stage1 --> Stage2 --> Stage0

    %% Build System
    subgraph "Build System"
        Makefile["Makefile"]:::build
        ARMmk["arm.mk\nmk/arm.mk"]:::build
        RISCVmk["riscv.mk\nmk/riscv.mk"]:::build
        Commonmk["common.mk\nmk/common.mk"]:::build
    end
    Makefile --> ARMmk
    Makefile --> RISCVmk
    Makefile --> Commonmk
    Makefile --> Lexer

    %% Test Harness
    subgraph "Test Harness"
        Drv["Snapshot Driver\ntests/driver.sh"]:::test
        ChkSnap["Snapshot Verify\ntests/check-snapshots.sh"]:::test
        UpdSnap["Snapshot Update\ntests/update-snapshots.sh"]:::test
        TestProg1["fib.c\ntests/fib.c"]:::test
        TestProg2["hello.c\ntests/hello.c"]:::test
        IR_snap1["fib-arm.json\ntests/snapshots/fib-arm.json"]:::data
        IR_snap2["fib-riscv.json\ntests/snapshots/fib-riscv.json"]:::data
        IR_snap3["hello-arm.json\ntests/snapshots/hello-arm.json"]:::data
        IR_snap4["hello-riscv.json\ntests/snapshots/hello-riscv.json"]:::data
    end
    Drv --> TestProg1
    Drv --> TestProg2
    Drv --> FinalELF
    FinalELF --> ChkSnap
    FinalELF --> UpdSnap
    ChkSnap --> IR_snap1
    ChkSnap --> IR_snap2
    ChkSnap --> IR_snap3
    ChkSnap --> IR_snap4

    %% CI
    subgraph "CI"
        Fmt["check-format.sh\n.ci/check-format.sh"]:::build
        NL["check-newline.sh\n.ci/check-newline.sh"]:::build
        Workflow["main.yml\n.github/workflows/main.yml"]:::build
    end
    Fmt --> Makefile
    NL --> Makefile
    Workflow --> Makefile

    %% Click Events
    click Lexer "https://github.com/nosba0957/shecc/blob/master/src/lexer.c"
    click Parser "https://github.com/nosba0957/shecc/blob/master/src/parser.c"
    click SSA "https://github.com/nosba0957/shecc/blob/master/src/ssa.c"
    click Peephole "https://github.com/nosba0957/shecc/blob/master/src/peephole.c"
    click RegAlloc "https://github.com/nosba0957/shecc/blob/master/src/reg-alloc.c"
    click ARM_IF "https://github.com/nosba0957/shecc/blob/master/src/arm.c"
    click ARM_CG "https://github.com/nosba0957/shecc/blob/master/src/arm-codegen.c"
    click RISC_IF "https://github.com/nosba0957/shecc/blob/master/src/riscv.c"
    click RISC_CG "https://github.com/nosba0957/shecc/blob/master/src/riscv-codegen.c"
    click ELF "https://github.com/nosba0957/shecc/blob/master/src/elf.c"
    click LibC "https://github.com/nosba0957/shecc/blob/master/lib/c.c"
    click Lower "https://github.com/nosba0957/shecc/blob/master/src/main.c"
    click ARMmk "https://github.com/nosba0957/shecc/blob/master/mk/arm.mk"
    click RISCVmk "https://github.com/nosba0957/shecc/blob/master/mk/riscv.mk"
    click Commonmk "https://github.com/nosba0957/shecc/blob/master/mk/common.mk"
    click Makefile "https://github.com/nosba0957/shecc/tree/master/Makefile"
    click Fmt "https://github.com/nosba0957/shecc/blob/master/.ci/check-format.sh"
    click NL "https://github.com/nosba0957/shecc/blob/master/.ci/check-newline.sh"
    click Workflow "https://github.com/nosba0957/shecc/blob/master/.github/workflows/main.yml"
    click Drv "https://github.com/nosba0957/shecc/blob/master/tests/driver.sh"
    click ChkSnap "https://github.com/nosba0957/shecc/blob/master/tests/check-snapshots.sh"
    click UpdSnap "https://github.com/nosba0957/shecc/blob/master/tests/update-snapshots.sh"
    click TestProg1 "https://github.com/nosba0957/shecc/blob/master/tests/fib.c"
    click TestProg2 "https://github.com/nosba0957/shecc/blob/master/tests/hello.c"
    click IR_snap1 "https://github.com/nosba0957/shecc/blob/master/tests/snapshots/fib-arm.json"
    click IR_snap2 "https://github.com/nosba0957/shecc/blob/master/tests/snapshots/fib-riscv.json"
    click IR_snap3 "https://github.com/nosba0957/shecc/blob/master/tests/snapshots/hello-arm.json"
    click IR_snap4 "https://github.com/nosba0957/shecc/blob/master/tests/snapshots/hello-riscv.json"

    %% Styles
    classDef frontend fill:#D0E1F9,stroke:#0B3D91,color:#0B3D91;
    classDef middle fill:#DFF2D8,stroke:#237A00,color:#237A00;
    classDef backend fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef build fill:#E0E0E0,stroke:#7D7D7D,color:#7D7D7D;
    classDef test fill:#F3D1F4,stroke:#A200A9,color:#A200A9;
    classDef data fill:#FFF5BA,stroke:#B38F00,color:#B38F00;
```
