How nosba0957/shecc works
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)